Re: [Libcdio-devel] Hindsight is 2020 - Let's sort multiextents at last

[Thomas Schmitt]

Hi,

there is one wrong statement in the NEWS.md chapter 3.0.0:
Multi-extent is not about a non-straight sequence of blocks, but about
multiple directory records representing pieces of the same data file.

I began with small changes to make this better understandable for
programmers who have no ISO 9660 background knowledge. The result is
now quite different from yours:

- Corrected explanation of multi-extent.
- Mentioned the extra constraint that extents have to form a neat byte
  sequence.
- Described what happens to old programs when they encounter multi-extent
  files.
- Changed the hint about "loop controlling variables" to "byte counting
  variables", because that's the wider condition for getting a 32-bit
  problem.
- Corrected some broad finger typos.

Please especially check my english language.

--------------------------------------------------------------------
My proposal:

version 3.0.0
=============

This version adds multi-extent support for ISO-9660. A single extent can store 
only up to 4 GiB - 1 byte. Larger data files are expressed in ISO 9660 
according to Level Of Interchange 3 as a group of files with identical names, 
each being one extent of the whole file.

libcdio now detects this situation and represents multiple extents as one file,
provided that the blocks of the extents alltogether form a gapless and properly 
ordered sequence of file content bytes.
When libiso9600 detects a gap or other jumps in the byte sequence, a warning
message is generated and no `iso9660_stat_t` object is created for the 
multi-extent file. I.e. the file will not appear in `readdir()`-ish results and 
individual inquiries will yield `NULL` rather than an `iso9660_stat_t` object.
Up to now, there are no ISO 9660 production programs known which would create 
extent sequences not digestible by libcdio.

Programs written for previous versions of _libcdio_ will still work for 
single-extent files. But they will see only the size of the first extent of a 
multi-extent file. In order to be prepared for correctly handling both, 
single-extent and multi-extent files, applications need to be adapted:

* switch from using `iso9660_stat_t.size` to the new attribute 
`iso9660_stat_t.total_size`. The reason is that old attribute `.size` can hold 
only 32 bit.
* make sure that byte counting variables can cope with integer numbers up to 43 
bit (32 bit block address + 11 bit byte address in block). In C-like languages 
this may mean switching from `int` to `long int`.

--------------------------------------------------------------------
As git diff:

diff --git a/NEWS.md b/NEWS.md
index 4c6a69b..94ad017 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,19 +1,18 @@
 version 3.0.0
 =============

-This version adds multi-extent support for ISO-9660. Previously the blocks maki
ng up an ISO-9660 file had to come strictly sequentially.
+This version adds multi-extent support for ISO-9660. A single extent can store
only up to 4 GiB - 1 byte. Larger data files are expressed in ISO 9660 according
 to Level Of Interchange 3 as a group of files with identical names, each being
one extent of the whole file.

-In this version, when libiso9600 detects that this is not the case, a warning m
essage is generated and a `iso9660_stat_t` object is not created.
+libcdio now detects this situation and represents multiple extents as one file,
+provided that the blocks of the extents alltogether form a gapless and properly
 ordered sequence of file content bytes.
+When libiso9600 detects a gap or other jumps in the byte sequence, a warning
+message is generated and no `iso9660_stat_t` object is created for the multi-ex
tent file. I.e. the file will not appear in `readdir()`-ish results and individu
al inquiries will yield `NULL` rather than an `iso9660_stat_t` object.
+Up to now, there are no ISO 9660 production programs known which would create 
extent sequences not digestible by libcdio.

-the file will not appear in `readdir()`-ish results and individual inquiries 
will yield `NULL` rather than an `iso9660_stat_t` object.
+Programs written for previous versions of _libcdio_ will still work for 
single-extent files. But they will see only the size of the first extent of a 
multi-extent file. In order to be prepared for correctly handling both, 
single-extent and multi-extent files, applications need to be adapted:

-Programs written for previous versions of _libcdio_ will still work for 
single-extent files. However in order to handle large multi-extent files, 
applications
-need to be adapted:
-
-* switch from using `iso9660_stat_t.size` to the new attrtibute 
`iso9660_stat_t.total_size`
-* make sure that loop controlling variables can cope with integer numbers up 
to 43 bit numbers. In C-like lanaguage this may mean switching from `int` to 
`long int`
-
-Notes: 43 bits is the sum of a 32-bit block address plus an 11-bit byte 
address in a block); `mkisofs` and `libisofs` currently only produce the files 
with sequential blocks.
+* switch from using `iso9660_stat_t.size` to the new attribute 
`iso9660_stat_t.total_size`. The reason is that old attribute `.size` can hold 
only 32 bit.
+* make sure that byte counting variables can cope with integer numbers up to 
43 bit (32 bit block address + 11 bit byte address in block). In C-like 
languages this may mean switching from `int` to `long int`.

-------------------------------------------------------------------------

Have a nice day :)

Thomas