libburnia/libisofs
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Write multisession/growing/modification info to the Tutorial.

Browse Source
This commit is contained in:
Vreixo Formoso
2008-02-02 17:08:15 +01:00
parent 7e0482a461
commit bf5bf7af98
2 changed files with 170 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
COPYRIGHT
View File

@@ -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
View File

@@ -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
-------------------------------------------------------------------------------