|
|
|
@ -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 |
|
|
|
------------------------------------------------------------------------------- |
|
|
|
|
|
|
|
|
|
|
|
|
Vreixo Formoso
14 years ago