path: root/FAQ-cd.txt

Q: What is this tool aimed at anyway?
A: It is designed to handle ISO images you make from CDs.


Q: What is an ISO image anyway?
A: You can create an ISO with free tools like cdrdao in raw mode, or others,
   like cdrwin, CloneCD, etc...


Q: Are all the ISO formats handled?
A: No. Only raw-2532 images files. Always the file format outputted by CloneCD
   and cdrwin, and the format outputted by cdrdao with the --read-raw option.


Q: Is Nero's file format supported?
A: No.


Q: Why? Nero's a spreaded software!
A: It's a commercial tool. Since I don't use any commercial tool, and that no
   GPL software generates Nero ISO, it won't be supported.


Q: What is this tool/library able to?
A: First, you can read/write sectors from/to an iso file. You can also read
   informations about an iso file. You can extract/insert files from/to
   an iso file. Depending upon the mode you'll be using, it will compute
   the right CRC/ECC code for the given sector. The whole in the following
   (eventually mixed) modes: MODE_1, MODE_2, MODE_2_FORM_1, MODE_2_FORM_2.
   Additionnaly, it is able to produce patches (.ppf files) instead modifying
   the iso file, saving you time when you use the right softwares.
   Actually, it is quite "oriented" on the MODE_2* formats, since it's
   the PSX's formats. And now, it is able to interpret LUA scripts.


Q: I've heard CDmage or ECCRegen can also correct the sectors for me.
A: Maybe. Since they only run on Win32 platforms, I've never tried them.


Q: So, what is the goal of this software?
A: To modify (patch) ISO images. Nothing else. And of course I want it free,
   opensource, and working on my prefered operating system, Linux. I can
   actually compile it for windows, using the mingw32 system (the same you
   can find in DevC++)


Q: Where does the source code for the CRC/ECC comes from?
A: Originally, it has been taken from cdrdao. Yazoo has given some
   modifications to it. Then I've cleaned it up and made some minor
   modifications on my self. The source code was called 'yazedc'.


Q: Do you have the right to do so?
A: The software is GPL'ed. I've got the right to give modified versions
   of it, as long as I don't claim the modificated thing it the original,
   and as long as I mention the original authors in it.


Q: What a strange name, 'yazedc' ?
A: I've got my own ideas about the name's origin... The easy solution:
   "YAZoo EDC", where EDC is the field name of one of the things it will
   recompute. But there is a more... complicated solution I won't give.


Q: So, I can modify your code too, create a new tool, and diffuse it?
A: Yes, as long as you give me back your changes if I ask them, that the
   new software is also GPL'ed, and that you mantion me as the original
   writer of the software, you can. Read the GPL carefully, it's very
   interesting and instructing.


Q: With which information What is exactly the format of a CD-Rom?
A: Firstly, when you have a raw sector, you have to understand its primary form.
   Secondly, the whole CD has an internal format, called the iso9660. The format
   of the iso9660 is easy to find on the internet. Here is one first easy link:
       http://www.ccs.neu.edu/home/bchafy/cdb/info/iso9660.txt
   Then you have two more difficult documents:
       http://www.ecma.ch/ecma1/stand/ecma-119.htm
   and
       http://www.ecma.ch/ecma1/stand/ecma-130.htm
   
   All those links were taken from the page
       http://www.ccs.neu.edu/home/bchafy/cdb/info/info.html

   The sector format is a bit complicated to find on the internet. Here is what
   I've found.
   
   First you have to know that there is many formats that describe the sector's
   organisation. Those are called "Books". There is the Red Book, the Yellow
   Book, the Blue Book, the Green Book, the Orange Book, and the White Book.

   The Red Book is for Audio CD. The Yellow for common CD-Roms. The Blue book
   for Philips's VideoCD. The Green Book for CD-i and CD-XA. The Orange Book
   for CD-R cds. And the White Book seems to be a replacement of the Green one.
   
   This is quite unclear and you have to actually buy the books since they
   aren't in public domain.
   
   So the informations I'll give comes from various source of various free
   softwares. Should I mention two: cdrdao http://cdrdao.sourceforge.net
   and ECCRegen http://web.tiscali.it/eccregen as the most useful sources.

   Here is the general form of a CD-Rom sector:
   
 <--------------------------- sector: 2352 bytes ------------------------------>
 <- Header: 16 bytes -><---------------- Datas: 2336 bytes -------------------->

   Let's move to the header description:
   
 <--------------------------- header: 16 bytes ------------------------------>
 <-- sync bytes: 12 bytes --><-- localisation: 3 bytes --><-- mode: 1 byte -->

   The sync bytes are easy: it is always 00 FF FF FF FF FF FF FF FF FF FF 00
   They are supposed to help the CD reader to synchronize enough to be able to
   read the sector correctly.

   The localisation is the sector "position" described in time. For example,
   the sector 200000 of a CD is at the "time" 44:28:50. The first is the number
   of minutes, the second is the number of seconds, in the range 0-59 and the
   last is the frame number, in the range 0-74. It means there is 75 frames
   into a second for a CD player. Please note that the CD "begins" at 00:02:00.
   
   Ok now that we know all this, you can feel the way the localisation is
   stored. But it is not that easy...
   
 <-------------------- localisation: 3 bytes -------------------->
 <-- minute: 1 byte --><-- second: 1 byte --><-- frame: 1 byte -->

   That's seems to be all right *BUT* the fact is that the bytes are stored
   in packed BCD format. You may know what the BCD format is if you are "old"
   enough for that. I won't enter into the details so if you want a more
   description of the BCD format, look into the net. You only have to know that:

typedef unsigned char uchar;
uchar from_BCD(uchar x) {return ((x & 15) + ((x & 240) >> 4) * 10));}
uchar to_BCD(uchar x) {return ((x / 10) << 4) | (x % 10));}
int is_valid_BCD(uchar x) {return (((x & 15) < 10) && ((x >> 4) < 10));}

   Last hint: when you look at a BCD packed number, you have to read it in
   hexadecimal, and then you will see a "decimal" number. So when you count
   in BCD, you'll have this: 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
   0x08, 0x09, 0x10, 0x11, 0x12, etc... You see? You've got a "gap": no 0x0a,
   0x0b, 0x0c, etc... So the BCD is only a trick for an easy reading of hexa
   dumps of various informations.

   All right. This was for the localisation part. The last part is the mode
   byte. It is really simple actually. It is 0 for an empty sector, 1 for a
   sector in MODE1, and 2 for a sector in MODE2. Easy as hell.
   
   Ok here we are: we know the basic form of a CD's sector, and even know the
   MODE of the sector. Now the datas depends upon the sector mode. Here you have
   the various kinds:
   
 <-------------- MODE 1 FORM 1 Sector datas: 2336 bytes ---------------------->
 <- datas: 2048 bytes -><- EDC: 4 bytes -><- 0s: 8 bytes -><- ECC: 276 bytes ->
 
 <---------- MODE 1 FORM 2 and also MODE 2 Sector datas: 2336 bytes ---------->
 <----------------------------- datas: 2336 bytes ---------------------------->

 <-------------- MODE 2 FORM 1 Sector datas: 2336 bytes ---------------------->
 <- SH: 8 bytes -><- datas: 2048 bytes -><- EDC: 4 bytes -><- ECC: 276 bytes ->

 <-------------- MODE 2 FORM 2 Sector datas: 2336 bytes ---------------------->
 <- SH: 8 bytes -><---------- datas: 2324 bytes ----------><- spare: 4 bytes ->

   Well, I *really* don't know how to distinguish the different "FORMS" from
   each others for the MODE 1. Have to look further for this.
   
   The ECC and EDC are controls blocks. The yazedc code can compute them, so
   don't worry about them.
   
   The 'SH' (SubHeader) field is the most "complicated" one. Those eight little
   bits are the only one I'm really not sure of. All of that because you have to
   buy the Books to find the information. This SubHeader is only found into
   MODE_2_FORM_1 and MODE_2_FORM_2 sectors.
   
   Here you have the informations I've been able to gather:
   
   -) The SubHeader has 8 bytes, but it's twice the same 4 bytes.
   -) The 4 bytes are described using the following fields:
     o) 1st byte: File Number (FN)
     o) 2nd byte: Channel Number (CN)
     o) 3rd byte: Sub Mode (SM)
     o) 4st byte: Coding Info (CI)
   -) The SubHeaders seems to be very important when dealing with STR files,
      since it's the only way to distinguish a video sector from an audio
      sector. But it seems that it doesn't matter when dealing with normal
      files. It might be obvious since the iso9660 format doesn't care about
      those bits. But better try to patch them if necessary...
   -) The Sub Mode byte is a bit field which seems to be described like this:
       0: End of Record (EOR)
       1: Video
       2: Audio
       3: Data
       4: Trigger
       5: Form 2
       6: Real Time (RT)
       7: End of File (EOF)

   Of course, the PSX has the CDs in MODE 2... So the common files are
   stored in MODE 2 FORM 1, the STR/XA files are stored in "MODE 2" but
   actually they are in MODE 2 FORM 1 and 2. The MOVCONV tool will in fact
   produce files that does contain the subheaders.
   
   Those subheaders are very likely to vary, and seems to be very important for
   stream processing. Please note that "str" video sectors are considered as
   data sectors, and not as video sectors.
   
   The CN byte indicates the channel number of the current sector. The XA
   format may contain interlaced channels. So for example, if you have a
   file that does contain 8 channels, you will have first the first sector
   of the channel 0, then the first sector of the channel 1, etc...
   
   This is also a bit more difficult when you know that video is also
   interlaced and considered as a channel itself. The common interlacement
   is 7 video sectors for 1 audio sector, but this may vary. And all the
   channels may be completely independants. For example, you may have a
   sound-free video that does contain an audio channel, this audio channel
   may be used for another part in the game.
   
   This is to optimize the reading process. Since the cd reader is a 2x cd
   reader, it *HAS* to read data in full 300KBps. So, if you have a sound
   free video, the reading process will be faster than the decoding process,
   and everything should crash. This is about the same for the audio sectors.
   The 'leap' sector function of MOVCONV does add blank sectors in order to
   pad the channels that may have stopped before the others. 
   
   One "speed" of the CD reader corresponds to four time the playback speed
   of a stereo audio channel at 37800Hz. So at full speed you can have eight
   stereo audio channels at 37800Hz. Or you can have 32 mono audio channels
   at 18900Hz.
   
   Common video str files needs 7/8 of the full speed of the CD reader.
   "Common" means 320x224 videos at 15fps. So you can have a full movie
   in 320x224x15fps with a stereo sound track at 37800hz. So, now, you
   may understand why the common interlacement may vary.
   
   The CI byte does contains some flags about the current sector, but I'm
   yet unable to give a full description of them. I've only got this: for
   XA audio sectors, the bit 0 is set when you have stereo sound, and the bit
   2 is set when you have "half frequency", ie 18900Hz instead of 37800Hz.
   
   The Video frames are in plain Form 1, and the Audio frames are in plain
   Form 2. But it _seems_ the Video frames are not checked against ECC/EDC,
   and filled with zeros instead.
   
   The last but not the least: the MODE 2 FORM 1 and MODE 2 FORM 2 are also
   called XA-Mode1 and XA-Mode2 or simplier: XA-1 and XA-2.

   I hope this will help you as it helped me writing this software.


Q: What's with all this LUA stuff?
A: LUA is a scripting language. There, in cd-tool, it enables you to create
   custom patches, or evoluted "mini softwares". If you want to use it, you
   first have to learn how LUA works and how you can program it. Look at the
   official web site for more informations about this language: www.lua.org
   Please, do not bug me about LUA syntax. The huge load of documentation
   about this language should be really enough.


Q: What's your LUA API?
A: First of all, my LUA distribution is the 5.0, slightly modified. The basic
   LUA compiler is not able to understand hex or octal numbers. I made a patch
   of my own to add this support. You'll find this patch at the very end of
   this document.
   
   Now, for the API itself. As basic layer, there are some functions that you
   will surely need. Those are "andB", "orB", "xorB", "notB", "shr" and "shl".
   The and, or, xor and not are there because there is no binary equivalent of
   those functions into native LUA. The two others, shr and shl, are
   respectively "shift right" and "shift left". All the functions work
   internally using 32 bits unsigned integers.
   
   There is a little 'debug' function that can help: "hex". Its syntax is:
   
       hex(number[, format])
   
   Where "format" is a string, which is "%02x" by default. This function
   simply returns the formatted string from the C call printf(format, number)
   So, you can actually mess up with the format, and display something else
   than plain hexa. And even cause the C host to crash, if you put an
   incorrect format string.
   
   
   You also have a "print" function, which takes a string as arguement. Its
   display form is platform independant (a newline is automatically added)
   but for this actual version of CD-Tool, will only be displayed on verbose
   mode (option -v in the command line)
   
   
   Ho, I almost forgot. CD-Tool opens the following LUA libraries before
   running any script:
   
       base, math, string, table
   
   Please read the LUA manual about those libraries. (Note that the "print"
   function of the base library is not here, and is replaced with mine)
   
   Let's talk about objects now. My API supports two kind of objects. Objects
   created from within LUA, and objects exported from the C++. Usually, the
   objects created by LUA will be destroyable. It means they have a garbage
   collector metamethod, and also a ":destroy()" method, to forcabily destroy
   the object. The objects exported by the C++ code will be NOT destroyable,
   and any try to call the :destroy() method will just fail.
   
   Now, about files. My API supports three "kind" of files. Input files,
   Output files, and Buffers. Each of them have exactly the same API. The
   Buffer one has one more feature that I will discuss below. But first,
   here are the constructors.
   
       Input(filename)
       Output(filename)
       Buffer([seekable])
   
   The variable 'filename' is a string, and 'seekable', a boolean. All those
   three functions will return what I call a "handle". Several functions of
   the API will take those handles as arguments. The variable seekable is
   false by default. A non-seekable buffer is a fifo. You won't be able to
   seek through it. But it will take less memory than a seekable one.
   Output will always create an empty file, erasing any existing one.
   
   Now, what you can do with handles. Well, here you have all the "methods"
   you can call on these handles:
   
       :read()
   
   With no arguments, this method will read a string from the file, up to the
   end of the line (or the file) and will eventually remove the end of line
   marker (LF or CRLF, autodetected)
   
       :read(size)
   
   Will read "size" bytes from the handle, will put them in an array, and
   return this array. Beware: usually, LUA coders consider arrays starting
   from 1. Mine start from 0. This function will return how much bytes were
   actually read from the handle. Beware: if it hits the end of the file, it
   will return 0, and will automatically close the handle.
   
       :readU8()  :readU16()   :readU32()
   
   Will read a 8, 16 or 32 bits unsigned number, and return it.
   Always Little Endian.
   
       :write(string)
   
   Will write the string to the handle. Will return nothing.
   
       :write(size, array)
   
   Will write the "size" bytes to the handle, taken inside of "array".
   Remember: 0-started arrays huh? Will return the number of bytes
   actually written on the file. Should not be useful, except for detecting
   a "disk full" error.
   
       :writeU8(byte)  :writeU16(word)  :writeU32(dword)
   
   Will write a 8, 16 or 32 bits unsigned number.
   Always Little Endian.
   
       :copyfrom(handle[, size])
   
   Will read up to 'size' bytes from the given handle, and put them inside
   of the calling handle. If not present, size will be "-1", which means
   "up to the end". The 'source' handle will then be closed (since it hit
   the end of file)
   
       :copyto(handle[, size])
   
   This is just the countrary of the function above. And to conciliate minds,
   I also have the following global function:
   
       copyhandle(source, destination[, size])
   
   which has still the same meanings than above.
   
   Now for some booleans methods:
   
       :isclosed()  :canread()  :canwrite()  :canseek()
   
   Should be self explanatory.
   
       :tell()
   
   Will return the actual file position pointer, or if the handle is non
   seekable, will just return a counter of the number of bytes read so far.
   
       :getname()
   
   Will return a string containing the name of the handle. May be the filename,
   if the called object is an Input or Output handle. Otherwise, will just be
   the string "Fifo" or "Buffer", depending on the seekability of the Buffer.
   
       :getsize()
   
   Will return the handle size in bytes. If it's a Fifo, it will return the
   number of remaining bytes.
   
       :close()
   
   Will close the file, and flush the remaining datas in caches.
   
       :flush()
   
   Will only flush any datas remaining in caches.
   
       :seek(pos[, wheel])
   
   Will seek the file pointer at position "pos". The wheel argument is here to
   tell from which point of view "pos" should be seen. By default, wheel is
   SEEK_SET, which tells that "pos" is referring from the start of the file.
   But you can also have SEEK_CUR, which says that "pos" is referring from the
   actual file pointer. And SEEK_END, which will then make "pos" to be seen
   as a relative position from the end of the file. Thus, having a negative
   value for "pos" is completely legal. It will return the actual file pointer.
   
      :setz([level])
   
   Will enable the zlib against the handle, at the specified level, from 0 (no
   compression) to 9 (max compression). The argument 'level' is 9 by default.
   Having a level for an Input handle has no meaning. Having :setz() against
   a Buffer will simply fail. When a handle is :setz(), any further read or
   write will be transparantly made through the zlib. Thus, if you open an
   Output file, and immediately specify a :setz() on it, it will produce a
   .gz file, that you can decompress using a lot of well known decompressor
   softwares.
   
   
   Now for special features about seekable buffers. First, since they have two
   file pointers, the common ":tell()" and ":seek()" will work for the reading
   pointer. So I had to add the methods ":wtell()" and ":wseek()" that will
   work with the writing pointer.
   
   Moreover, you can access a seekable buffer as an array, starting from 0.
   
   That's all for basic files. Let's move out to CD specific objects. Here are
   the base "types" we will work with:
   
     cdutils, direntry, cdfile, cddate, PVD, DirTree, and isobuider.
   
   Let's discuss them now. A "cdutils" is usually created from "cd-tool", and
   passed to the LUA script as the "cdutil" variable. This object holds the
   power to read, and eventually write to the iso file, or CD device the user
   specified as argument. Of course, if the user specified a device, you will
   not be able to write to it. The LUA code can not create a cdutils object.
   Coming with the cdutils object are some global variables. These are:
   
       MODE0 = 0, MODE1 = 1, MODE2 = 2,
       MODE2_FORM1 = 3, MODE2_FORM2 = 4,
       MODE_RAW = 5, GUESS = 6
   
   They should be used each time a "mode" is needed as a sector mode argument.
   Many methods of cdutils will ask an optionnal "mode" argument, and will
   default to "GUESS" if not specified.
   
   You can also access these three helpers arrays:
   
       sec_sizes, an array of sector sizes, depending on the mode
       sec_offsts, an array of the actual start point of the sector inside
          the raw sector, and
       sec_modes, an array of strings that describe the sector modes.
   
   The least but not the last, it comes with these functions:

       swapword(number)  swap endianness of given 16 bits number
       swapdword(number) swap endianness of given 32 bits number

       from_bcd(number)     convert byte from BCD notation
       to_bcd(number)       convert byte to BCD notation
       is_valid_bcd(number) returns a boolean
   
       from_msf(msf[, start)
       from_msf(m, s, f[, start])
           converts a MSF sector address into a plain sector number.
           By default, "start" is 150 (a CD usually starts at 0:02:00,
           which is 150 sectors)
   
   The methods of the cdutils object are:
   
       :sectorseek(sector)
   
   Will seek the current reading pointer to the specified sector number. Many
   methods of cdutils will ask an optionnal "sector" argument, and will use
   the current reading pointer if not specified.

       :guessmode([sector])
   
   Will return the guessed mode for the specified sector.
   
       :readsector([sector[, mode]])
   
   Will return an array containing the user datas for the specified sector.
   It means that, if "mode" is different of MODE_RAW, that only the user part
   of the sector will be returned.
   
       :readdatas(size[, sector[, mode]])
   
   Will return an array containing the user datas for the sectors starting at
   "sector", by only reading the user datas specified by the "mode".
   
       :readfile(handle, size[, sector[, mode]])
   
   Will basically do the same, but will write down the datas to the specified
   handle. Will return nothing.
   
       :writesector(array[, sector[, mode]])
   
   Will write the array inside the specified sector, using the specified mode.
   That is, it will only write inside the user datas of the specified sector.
   
       :writedatas(array, size[, sector[, mode]])
   
   Will write "size" bytes from the array inside the sectors starting at
   'sector', writing only inside the user datas parts.
   
       :writefile(handle[, size[, sector[, mode]])
   
   Will basically do the same, but will read from the specified handle, up
   to its end if size equals -1 (default)
   
   Now, the following methods will return a "direntry" object. I will discuss
   them shortly after.
   
       :findpath(path)  :findparent(path)  :finddirectory(dir, path)
   
   For the three functions, the "path" is a string. For the definition of a
   path, it can be a directory name, or a filename. It is absolute if it
   starts with a "/". Each subdirectory is separated by a "/". Beware: usual
   iso9660 filenames ends with the string ";1"
   
   So, ":findpath" and ":findparent" will look for the directory entry of the
   exact path, or the parent containing the path specified in argument. They
   will return a "direntry", which is a kind of "dump" of the iso structure
   that corresponds to this entry in the file table. The last function,
   ":finddirectory()", will look inside of the directory specified as argument
   for the relative (unique) filename (that can be either a file, or another
   directory). Beware: if the specified direntry points to a file, and not
   a directory, it will fail.
   
   So, what's a "direntry" object ? It's a destroyable read-only object
   returned by these three functions, which contains the infos from the
   directory entry corresponding to a specific path (a file or a directory)
   
   You can read a direntry object as an array, which has the following
   entries:
   
        R           number - entry size
	NExt        number - "Number of Extensions"
	Sector      number - entry sector on CD
	Size        number - entry size on CD
	Year        number - date & time
	Month       number - date & time
	Day         number - date & time
	Hour        number - date & time
	Minute      number - date & time
	Second      number - date & time
	Offset      number - date & time
	Flags       number - entry flags (see an iso9660 doc)
	HandleUnit  number - should be 0
	HandleGap   number - should be 0
	VolSeq      number - should be 0
	N           number - name size 
	id          string - name
	
   Moreover, it has the following boolean methods that can query a direntry:
   
       :ishidden()  :isdir()
           Will query the Flag entry. There are other entries, but I don't
           think they are useful.
           
       :hasxa()
           Will compute if a Sony's XA special entry exists.
       
       :isxadir()  :isxaaudio()  :isxastr()  :isxaxa()  :isxaform1()
           If the direntry has an xa entry, this will query it.


    Now for a quite interesting object. It's the "cdfile" object. It is a
    derivate of the "handle" generic object, and thus, will have exactly the
    same behavior as an "Input" object. The big thing is that this file comes
    from inside the iso file directly, with intelligent sector reading (read:
    it will extract correctly STR files)
    
    So, if you remember all the methods of a handle object, I only have to
    tell you how to construct a cdfile object. There are two constructors.
    
        cdfile(cdutils, direntry[, mode])
        cdfile(cdutils, sector[, size[, mode]])
    
    The first one is evident. It will simply clone the given direntry object
    into a readable handle.
    
    The second one is a little bit tricker. You specify a sector number, and
    a filesize. But by default, size is -1, which means "autodetect". Yeah, I
    know this may sound strange, but, on mode 2 CDs, there are sector flags
    that helps delimiting files entries. And since the "tricks" used in games
    like Xenogears or Chrono Cross are only directory hiding, those flags were
    constructed, and are still here. So, the autodetection will try to find
    the correct file size using these flags. Beware, it may fail, and it will
    not work at all on mode 1 CDs.
    
    
    Okay, I discussed a lot about iso readings, and small patching. Now for
    the real thing: iso reconstruction.
    
    First, I have to introduce three structures used actively by the functions.
    The first is the "cddate" structure. It holds any data necessary to set up
    a date for various places in the iso structure. You can read/write the
    fields of a cddate. All of them are numbers, and should be
    self-explanatory:
    
        year, month, day, hour, minute, second, hundredths, offset
    
    The function "cddate" will return an empty destroyable cddate.
    
    The second structure I have to introduce is the "PVD" structure, which
    stands for "Primary Volume Descriptor". It is the basic datas that every
    CD has. As the cddate structure, you can access the PVD structure as an
    array, which fields are:
    
        sysid      string - system ID
        volid      string - volume ID
        volsetid   string - volume set ID
        pubid      string - publisher ID
        prepid     string - data preparer ID
        appid      string - application ID
        copyright  string - copyright file
        abstract   string - abstract file
        biblio     string - bibliography file
        volcreat   date   - volume creation date
        modif      date   - volume modification date
        volexp     date   - volume expiration date
        voleff     data   - effective volume date
    
    The last field, "appdata", is hidden. It is a 512 bytes array which
    contains "application datas", usually zeroes. You can access these bytes
    directly by using number as indices of a PVD structure. Starting from 0.
    SONY usually puts datas in there, so...
    
    In order to create a PVD structure, you have several ways. You can create
    an empty PDV using the "PVD" function. But there is also three functions
    that will clone an existing PVD. Those are:
    
        createpvd(cdutils)  createpvd_handle(handle)  createpvd_array(array)
    
    The cdutils one will automatically look for the sector 16 of the input iso
    in order to clone it. The two others will just wait 2048 bytes of data
    that contain the user data of a PVD sector.
    

    The last useful structure is the "DirTree" structure. It is used for
    building the iso directory structure. When finalizing the iso file, these
    structures will be dumped as "direntries". So they mostly have the same
    fields and meanings.
    
    LUA code should not construct DirTrees directly. It is possible though,
    through the "DirTree" function. Here's the syntax:
    
        DirTree(father[, isdir])
    
    The "father" argument should be the other DirTree which is the parent of
    the newer one, or "nil" to create a root directory (*really* not
    recommanded imho. I really do not see why you would do that. Apart of
    creating a fake rootsystem, which is doable, but not tested though, and
    was not designed for it (yet)), The "isdir" argument is a boolean, which
    defaults to true. You *have* to set it to false in order to create a plain
    file.
    
    Next, the fields of this objects are:
    
        isdir     boolean - read only attribute
        sector    number  - entry sector index
        size      number  - entry size
        hidden    boolean - sets the hidden entry flag
        hardhide  boolean - a trick. see below.
        name      string  - entry name.
        creation  date    - entry creation date
        have_xa   boolean - has a sony's xa entry
        xa_dir    boolean - flag "is directory"
        xa_audio  boolean - flag "is audio track"
        xa_str    boolean - flag "is str video file"
        xa_xa     boolean - flag "is xa audio file"
        xa_form1  boolean - flag "is in mode 2 form 1"
        mode      number  - direntry sector mode
            beware: this "mode" entry is to tell how to store the direntry,
            not the file pointing to it.

        father, child, brother are read only entries. They are non destroyable
        DirTrees and are used to browse the actual directory tree.
    
    The "hardhide" attribute is to tell the system to "not dump" the entry
    when finalizing the CD. Useful for "hidden" filesystems, like Xenogears.
    
    And finally, the methods for this object:
    
        :fromdir(direntry)
    
    This will copy the directory entry into the called DirTree, except the
    sector and size attributes.
    
        :setbasicsxa()
    
    Will set the basic XA attribute. dir:setbasicsxa() is equivalent to the
    following piece of code:
    
        dir.have_xa = true
        dir.xa_form1 = true
        dir.xa_xa = false
        dir.xa_str = false
        dir.xa_audio = false
        dir.xa_dir = dir.isdir
    
    
    Pfiew, only one object remaining. Here it is. Its name is "isobuilder".
    It will control and administrate the creation process of an iso file
    by using all of the above structures and functions.
    
    You can create one from LUA, but CD-Tool might just give one to your
    script, with the global name "iso". The constructor has the following
    syntax:
    
        isobuilder(handle[, mode])
    
    This will return an isobuilder object, that will write everything out to
    the specified file, and will create a 2352-raw iso using the given sector
    mode (mode 2 form 1 by default). Actually, it would be nonsense to put
    something else than "MODE1" or "MODE2_FORM1" as 'mode' here.
    
    I have to explain a bit how this isobuilder object works. You will be able
    to "append" datas, and retains the sector numbers where the datas were
    storen inside the DirTree structures. So, when you're done with putting
    your files, the isobuilder object will create all the necessary structures
    all around the CD, where it spared some space.
    
    This object has the following methods:
    
        :foreword(cdutils)
        :foreword_handle(handle[, mode])
        :foreword_array(array[, mode])
    
    That will create what I call the "forewords" of the CD, ie the 16 first
    sectors. The "cdutils" version will automatically takes the 16 sectors
    from the input iso. The two others will read the 16 sectors from the
    datas you give it, using the specified mode, which defaults to 2352 bytes
    per sector, that is, exactly 37632 bytes.
    
    Next to it, you have the method
    
        :setbasics(pvd[, rootsize[, ptsize[, nvd[, rootsect]]]])
    
    that will create the first structures, and return the root DirTree of your
    new iso. By default, rootsize = 1, ptsize = 1, nvd = 1, and rootsect = -1.
    
    Please retain the "rootsize" in memory a little bit, we will discuss it
    right after. "ptsize" is the size of the path table, in sectors. Note that
    there is 3 copies of the path table. So, in reality, this number will be
    multiplicated by 4. NVD is the number of volume descriptors. We currently
    set the "Primary" volume descriptor, and the end marker, at respectively
    sector 16 and 17. So, if you want more volume descriptors, you should set
    this variable to another value, and then start to write your custom volume
    descriptors at sector 17. Do not forget the end marker, it will always be
    put at the sector 17, even if you have several volume descriptors. And
    finally, the rootsect is the sector of the rootdirectory, if you want to
    place it at a certain sector, and thus, reserving some sectors between
    the path table and the rootsector. Note that the default value, -1, just
    tell to compute it.
    
        :createdir(dirtree, name[, size[, direntry[, mode]]])
    
    This will create a subdirectory in the specified dirtree object. Size is
    defaulted to 1, direntry to nil, and mode to -1. When creating a directory
    the isobuilder will hold one or more sectors for it in the iso file. You
    can't really tell by advance how much sectors you need however. But since
    you are creating patches, you should know how much you actually need. So,
    you have to tell how much sectors you reserve for the directory. This is
    also true for the root, and thus, the "rootsize" in the :setbasics()
    method tells the size of the root directory, in sectors. The direntry
    object, when it exists, will help to clone the entry. If "name" is empty,
    it will also get cloned. If "size" is 0, it will also get cloned. And
    finally, if "mode" is different from -1, the directory will be stored
    using this mode. Otherwise, the mode is the default iso mode specified
    in the isobuilder object creation.
    
        :createfile(dirtree, name, file[, direntry[, mode]])
    
    This is the companion of the previous method. It will create a file in the
    iso, with basically the same behavior. It reads the file from a handle, up
    to the end, and append it to the current iso. The argument direntry, if
    not nil, will be used to clone the attributes. Even the name if the given
    one is "". The file will be immediately stored on disk. The filename will
    be automatically be followed by ";1" when dumping, so you don't have to
    put it anywhere.
    
        :close([cuefile[, mode]])
    
    Will finalize the isofile, by dumping all the necessary structures. The
    argument 'cuefile' is eventually a handle pointing to an output file where
    the ".cue" file used for cdrwin will be put, but this feature is not yet
    enabled. And mode is there to override the default iso mode, as usual.
    
    SO, you should only need that. But I also added some methods that you may
    want/need/etc...
    
        :getdispsect()
    
    This will basically return the iso file size in sectors.
    
        :putfile(file[, mode[, sector]])
    
    This will write a bare file onto the iso. By default, mode is -1 and means
    "take the default iso mode", and sector is -1, and means "use the value
    returned by :getdispsect()". The function will return the sector number
    the file was put on.
    
        :putdatas(array, size[, mode[, sector]])
    
    Basically the same as above, but with an array of bytes rather than a
    handle. Beware, still starting at 0.
    
        :createsector(array[, mode[, sector]])
    
    Will write down a sector, by returning the address it was wrote. Array
    begining at 0, mode = -1: default mode, sector = -1: use :getdispsect().
    One interesting info to know about this function, is that, when using
    mode 2 form X sectors, it will set basic subheaders, especially the flags
    "End of Record" and "End of File". So, when all the other functions will
    set them, for :createsector, you manually have to specify them using the
    following methods:
    
        :setEOF()
        :clearEOF()
    
    Finally, I wrote one "helper" method, though you can't write it yet using
    this API:
    
        :copydir(dirtree, cdutils, direntry[, mode])
    
    This will copy one directory from a cdutils object, inside of the
    isobuilder object. The argument 'dirtree' is the destination directory,
    'cdutils' is the source thing, 'direntry' the directory entry from cdutils
    to be copied, and mode is here to override the default mode. It will work
    recursively. If mode is MODE2_FORM1, and if it encounters a special XA
    file stored in plain mode 2, it will compute the necessary datas in order
    to correctly copy it. The function doesn't return anything.
    
    Okay, I presented everything. Now for a quick and simple example of use.
    This LUA script, when used with the cd-tool's luapatch command, will act
    exactly like the cd-tool's copy command:

        dir = cdutil:findpath "/"
        rsize = dir.Size

        iso:foreword(cdutil)
        pvd = createpvd(cdutil)
        root = iso:setbasics(pvd, rsize / 2048)
        iso:copydir(root, cdutil, cdutil:findpath "/")

        buf = Buffer()
        buf:write "Touched!\n"
        iso:createfile(root, buf, "TOUCHED.TXT"):setbasicsxa()

        iso:close()
    
    Pwieew, all done. Good luck ! ;-)
    

Q: What patch did you applied to the LUA compiler?
A: Only one of my own, to add support for hex and octal numbers. Here it is:
diff -u -r1.1 llex.c
--- src/llex.c  6 Nov 2003 11:56:07 -0000
+++ src/llex.c  19 Nov 2003 23:03:35 -0000
@@ -172,15 +172,34 @@

 /* LUA_NUMBER */
 static void read_numeral (LexState *LS, int comma, SemInfo *seminfo) {
+  int oct = 0, hex = 0;
   size_t l = 0;
   checkbuffer(LS, l);
   if (comma) save(LS, '.', l);
-  while (isdigit(LS->current)) {
+  else if (LS->current == '0') {
+    oct = 1;
+    checkbuffer(LS, 1);
+    save_and_next(LS, l);
+    if (LS->current == 'x') {
+      oct = 0;
+      hex = 1;
+      checkbuffer(LS, 1);
+      save_and_next(LS, l);
+    }
+  }
+  while (isdigit(LS->current) || (hex && isxdigit(LS->current))) {
     checkbuffer(LS, l);
     save_and_next(LS, l);
   }
+  checkbuffer(LS, 1);
   if (LS->current == '.') {
     save_and_next(LS, l);
+    if (hex || oct) {
+      save(LS, '\0', l);
+      luaX_lexerror(LS,
+                   "error in number, mixing decimal point with octal or hexadecimal",
+                   TK_NUMBER);
+    }
     if (LS->current == '.') {
       save_and_next(LS, l);
       save(LS, '\0', l);
@@ -195,6 +214,12 @@
   }
   if (LS->current == 'e' || LS->current == 'E') {
     save_and_next(LS, l);  /* read `E' */
+    if (hex || oct) {
+      save(LS, '\0', l);
+      luaX_lexerror(LS,
+                   "error in number, mixing exponential with octal or hexadecimal",
+                   TK_NUMBER);
+    }
     if (LS->current == '+' || LS->current == '-')
       save_and_next(LS, l);  /* optional exponent sign */
     while (isdigit(LS->current)) {
diff -u -r1.1 lobject.c
--- src/lobject.c       6 Nov 2003 11:56:07 -0000
+++ src/lobject.c       19 Nov 2003 23:03:35 -0000
@@ -20,13 +20,6 @@
 #include "lstring.h"
 #include "lvm.h"

-
-/* function to convert a string to a lua_Number */
-#ifndef lua_str2number
-#define lua_str2number(s,p)     strtod((s), (p))
-#endif
-
-
 const TObject luaO_nilobject = {LUA_TNIL, {NULL}};


@@ -91,7 +84,17 @@

 int luaO_str2d (const char *s, lua_Number *result) {
   char *endptr;
-  lua_Number res = lua_str2number(s, &endptr);
+  size_t l = strlen(s);
+  lua_Number res;
+  if ((l > 0) && (s[0] == '0')) {
+    if ((l > 2) && (s[1] == 'x')) {
+      res = strtol(s + 2, &endptr, 16);
+    } else {
+      res = strtol(s + 1, &endptr, 8);
+    }
+  } else {
+    res = strtod(s, &endptr);
+  }
   if (endptr == s) return 0;  /* no conversion */
   while (isspace((unsigned char)(*endptr))) endptr++;
   if (*endptr != '\0') return 0;  /* invalid trailing characters? */