From bf5bf7af98bef6f75ee6705514b5f31f81cbad02 Mon Sep 17 00:00:00 2001 From: Vreixo Formoso Date: Sat, 2 Feb 2008 17:08:15 +0100 Subject: [PATCH] Write multisession/growing/modification info to the Tutorial. --- COPYRIGHT | 2 +- doc/Tutorial | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 170 insertions(+), 2 deletions(-) diff --git a/COPYRIGHT b/COPYRIGHT index 3fd993e..8d562a3 100644 --- a/COPYRIGHT +++ b/COPYRIGHT @@ -1,7 +1,7 @@ Vreixo Formoso , Mario Danic , Thomas Schmitt -Copyright (C) 2007 Vreixo Formoso, Mario Danic, Thomas Schmitt +Copyright (C) 2007-2008 Vreixo Formoso, Mario Danic, Thomas Schmitt This program is free software; you can redistribute it and/or modify diff --git a/doc/Tutorial b/doc/Tutorial index bfb0627..fc2f891 100755 --- a/doc/Tutorial +++ b/doc/Tutorial @@ -20,7 +20,10 @@ Contents: 2.1 Image tree manipulation 2.2 Set the write options 2.3 Obtaining a burn_source -3. Image growing and multisession +3. Image growing and modification + 3.1 Growing vs Modification + 3.2 Image import + 3.3 Generating a new image 4. Bootable images 5. Advanced features @@ -337,3 +340,168 @@ You can get the state of the buffer in any moment, with the function: You can also cancel the writer thread at any time, with the cancel() function of the burn_source. + +------------------------------------------------------------------------------- +3. Image growing and modification +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- +3.1 Growing vs Modification + +Libisofs is not restricted only to create new images. It can also be used to +modify existing images. It supports two kind of image modifications, that we +have called image growing and image modification: + +Image modification consists in generating a new image, based on the contents +of an existing image. In this mode, libisofs takes an image, the users modifies +its contents (adding new files, removing files, changing their names...), and +finally libisofs generates a completely new image. + +On the other side, image growing is similar, with the difference that the new +image is dependent on the other, i.e., it refers to files of the other image. +Thus, it can't be mounted without the old image. The purpose of this kind of +images is to increment or add files to a multisession disc. The new image only +contains the new files. Old files are just references to the old image blocks. + +The advantage of the growing approach is that the generated image is smaller, +as only the new files are written. This mode is suitable when you just want to +add some files to a very big image, or when dealing with write-once media, such +as CD-R. Both the time and space needed for the modification is much less than +with normal image modify. + +The main problem of growing is that the new image needs to be recorded together +with the old image, in order to be mountable. The total size of the image +(old + new) is bigger (even much bigger) than a completely new image. So, if +you plan to distribute an image on Internet, or burn it to a disc, generate a +completely new image is usually a better alternative. + +To be able to mount a grown image, the OS needs to now you have appended new +data to the original image. In multisession media (such as CD-R), the new data +is appended as a new session, so the OS can identify this and mount the image +propertly. However, when dealing with non-multisession media (such as DVD+RW) +or plain .iso files, the new data is just appended at the end of the old image, +and the OS has no way to know that the appended data is in fact a "new +session". The method introduced by Andy Polyakov in growisofs can be used in +those cases. It consists in overwrite the volume descriptors of the old image +with a new ones that refer to the newly appended contents. + +------------------------------------------------------------------------------- +3.2 Image import + +The first thing you need to do in order to modify or grow an image is to import +it, with the function: + + iso_image_import() + +It takes several arguments. + +First, the image context, an IsoImage previously obtained with iso_image_new(). +In most cases you will want to use an empty image. However, if you have already +added files to the image, they will be removed and replaced with the contents +of the image being imported. + +The second parameter is an IsoDataSource instance. It abstracts the original +image, and it is used by libisofs to access its contents. You are free to +implement your own data source to access image contents. However, libisofs has +a simple implementation suitable for reading images on the local filesystem, +that can be used for import both .iso files and inserted media, via the block +device and POSIX functions. You can get it with + + iso_data_source_new_from_file() + +The third parameter of iso_image_import() is a pointer to an IsoReadOpts +struct. It holds the options for image reading. You get it with: + + iso_read_opts_new() + +and after calling iso_image_import() you should free it with + + iso_read_opts_free() + +Some options are related to select what extensions to read. Default options +are suitable for most users. + + iso_read_opts_set_no_rockridge() + iso_read_opts_set_no_joliet() + iso_read_opts_set_no_iso1999() + iso_read_opts_set_preferjoliet() + +If RockRidge extensions are not present, many files attributes can't be +obtained. In those cases libisofs uses default values. You have options to +configure what default values to use. + + iso_read_opts_set_default_uid() + iso_read_opts_set_default_gid() + iso_read_opts_set_default_permissions() + +If the original image has been created in another system with a different +charset, you may want to use: + + iso_read_opts_set_input_charset() + +to specify the encoding of the file names on image. + +Finally, to import multisession images, you should tell libisofs that it must +read the last session. For that, you must set the block where the last session +starts: + + iso_read_opts_set_start_block() + +The last parameter for iso_image_import(), optional, is a pointer that will +be filled with a library-allocated IsoReadImageFeatures, that lets you access +some information about the image: size, extensions used,... + +[TODO: explain that iso_image_import uses dir rec options] + +------------------------------------------------------------------------------- +3.3 Generating a new image + +After importing the image, the old image tree gets loaded. You are free to +make any changes to it: add new files, remove files, change names or +attributes... Refer to "2.1 Image tree manipulation" for details. + +When it is ready, you can now create the new image. The process is the same as +explained in "2.2 Set the write options" and "2.3 Obtaining a burn_source". +However, there are some write options that should be taken into account. + +First of all, you must select whether you want to grow or modify the image +(read "3.1 Growing vs Modification" for details). You must call + + iso_write_opts_set_appendable() + +An appendable image leads to image growing, and a non-appendable image leads +to a completelly new image (modification). An appendable image will be appended +after the old image (in a new session, for example). Thus, in those cases, the +first block of the image is not 0. You should set the correct lba of the first +block with: + + iso_write_opts_set_ms_block() + +That is usually the "Next Writable Address" on a multisession media, and a +value slightly greater than the old image size on .iso files or DVD+RW media. +You can obtain the old image size with the iso_read_image_features_get_size() +function. + +In this last case (i.e., on a non multisession media), you will need to +overwrite the volume descriptors of the old image with the new ones. To do +this you need: + +- Allocate a buffer of at least 64 KiBs. +- Initialize it with the first 64 KiBs of the original image. +- Pass the buffer to libisofs with the iso_write_opts_set_overwrite_buf() + option. +- After appending the new image, you have to overwrite the first 64 KiBs of + the original image with the new content of the buffer. + + +------------------------------------------------------------------------------- +4. Bootable images +------------------------------------------------------------------------------- + + + +------------------------------------------------------------------------------- +5. Advanced features +------------------------------------------------------------------------------- + +