Write multisession/growing/modification info to the Tutorial.
This commit is contained in:
Vreixo Formoso
parent
7e0482a461
commit
bf5bf7af98
@ -1,7 +1,7 @@
|
||||
Vreixo Formoso <metalpain2002@yahoo.es>,
|
||||
Mario Danic <mario.danic@gmail.com>,
|
||||
Thomas Schmitt <scdbackup@gmx.net>
|
||||
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
|
||||
|
||||
170
doc/Tutorial
170
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
|
||||
-------------------------------------------------------------------------------
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user