"Fossies" - the Fresh Open Source Software Archive

Member "libisofs-1.5.4/libisofs/libisofs.h" (7 Feb 2021, 336981 Bytes) of package /linux/misc/libisofs-1.5.4.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "libisofs.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.5.2_vs_1.5.4.

    1 
    2 #ifndef LIBISO_LIBISOFS_H_
    3 #define LIBISO_LIBISOFS_H_
    4 
    5 /*
    6  * Copyright (c) 2007-2008 Vreixo Formoso, Mario Danic
    7  * Copyright (c) 2009-2021 Thomas Schmitt
    8  *
    9  * This file is part of the libisofs project; you can redistribute it and/or
   10  * modify it under the terms of the GNU General Public License version 2 
   11  * or later as published by the Free Software Foundation. 
   12  * See COPYING file for details.
   13  */
   14 
   15 /* Important: If you add a public API function then add its name to file
   16                  libisofs/libisofs.ver 
   17 */
   18 
   19 #ifdef __cplusplus
   20 extern "C" {
   21 #endif
   22 
   23 /* 
   24  *
   25  * Applications must use 64 bit off_t.
   26  * E.g. on 32-bit GNU/Linux by defining
   27  *   #define _LARGEFILE_SOURCE
   28  *   #define _FILE_OFFSET_BITS 64
   29  * The minimum requirement is to interface with the library by 64 bit signed
   30  * integers where libisofs.h or libisoburn.h prescribe off_t.
   31  * Failure to do so may result in surprising malfunction or memory faults.
   32  * 
   33  * Application files which include libisofs/libisofs.h must provide
   34  * definitions for uint32_t and uint8_t.
   35  * This can be achieved either:
   36  * - by using autotools which will define HAVE_STDINT_H or HAVE_INTTYPES_H
   37  *   according to its ./configure tests,
   38  * - or by defining the macros HAVE_STDINT_H or HAVE_INTTYPES_H according
   39  *   to the local situation,
   40  * - or by appropriately defining uint32_t and uint8_t by other means,
   41  *   e.g. by including inttypes.h before including libisofs.h
   42  */
   43 #ifdef HAVE_STDINT_H
   44 #include <stdint.h>
   45 #else
   46 #ifdef HAVE_INTTYPES_H
   47 #include <inttypes.h>
   48 #endif
   49 #endif
   50 
   51 
   52 /*
   53  * Normally this API is operated via public functions and opaque object
   54  * handles. But it also exposes several C structures which may be used to
   55  * provide custom functionality for the objects of the API. The same
   56  * structures are used for internal objects of libisofs, too.
   57  * You are not supposed to manipulate the entrails of such objects if they
   58  * are not your own custom extensions.
   59  *
   60  * See for an example IsoStream = struct iso_stream below.
   61  */
   62 
   63 
   64 #include <sys/stat.h>
   65 
   66 #include <stdlib.h>
   67 
   68 /* Because AIX defines "open" as "open64".
   69    There are struct members named "open" in libisofs.h which get affected.
   70    So all includers of libisofs.h must get included fcntl.h to see the same.
   71 */
   72 #include <fcntl.h>
   73 
   74 
   75 /**
   76  * The following two functions and three macros are utilities to help ensuring
   77  * version match of application, compile time header, and runtime library.
   78  */
   79 /**
   80  * These three release version numbers tell the revision of this header file
   81  * and of the API it describes. They are memorized by applications at
   82  * compile time.
   83  * They must show the same values as these symbols in ./configure.ac
   84  *     LIBISOFS_MAJOR_VERSION=...
   85  *     LIBISOFS_MINOR_VERSION=...
   86  *     LIBISOFS_MICRO_VERSION=...
   87  * Note to anybody who does own work inside libisofs:
   88  * Any change of configure.ac or libisofs.h has to keep up this equality !
   89  *
   90  * Before usage of these macros on your code, please read the usage discussion
   91  * below.
   92  *
   93  * @since 0.6.2
   94  */
   95 #define iso_lib_header_version_major  1
   96 #define iso_lib_header_version_minor  5
   97 #define iso_lib_header_version_micro  4
   98 
   99 /**
  100  * Get version of the libisofs library at runtime.
  101  * NOTE: This function may be called before iso_init().
  102  *
  103  * @since 0.6.2
  104  */
  105 void iso_lib_version(int *major, int *minor, int *micro);
  106 
  107 /**
  108  * Check at runtime if the library is ABI compatible with the given version.
  109  * NOTE: This function may be called before iso_init().
  110  *
  111  * @return
  112  *      1 lib is compatible, 0 is not.
  113  *
  114  * @since 0.6.2
  115  */
  116 int iso_lib_is_compatible(int major, int minor, int micro);
  117 
  118 /**
  119  * Usage discussion:
  120  *
  121  * Some developers of the libburnia project have differing opinions how to
  122  * ensure the compatibility of libraries and applications.
  123  *
  124  * It is about whether to use at compile time and at runtime the version
  125  * numbers provided here. Thomas Schmitt advises to use them. Vreixo Formoso
  126  * advises to use other means.
  127  *
  128  * At compile time:
  129  *
  130  * Vreixo Formoso advises to leave proper version matching to properly
  131  * programmed checks in the the application's build system, which will
  132  * eventually refuse compilation.
  133  *
  134  * Thomas Schmitt advises to use the macros defined here for comparison with
  135  * the application's requirements of library revisions and to eventually
  136  * break compilation.
  137  *
  138  * Both advises are combinable. I.e. be master of your build system and have
  139  * #if checks in the source code of your application, nevertheless.
  140  *
  141  * At runtime (via iso_lib_is_compatible()):
  142  *
  143  * Vreixo Formoso advises to compare the application's requirements of
  144  * library revisions with the runtime library. This is to allow runtime
  145  * libraries which are young enough for the application but too old for
  146  * the lib*.h files seen at compile time.
  147  *
  148  * Thomas Schmitt advises to compare the header revisions defined here with
  149  * the runtime library. This is to enforce a strictly monotonous chain of
  150  * revisions from app to header to library, at the cost of excluding some older
  151  * libraries.
  152  *
  153  * These two advises are mutually exclusive.
  154  */
  155 
  156 struct burn_source;
  157 
  158 /**
  159  * Context for image creation. It holds the files that will be added to image,
  160  * and several options to control libisofs behavior.
  161  *
  162  * @since 0.6.2
  163  */
  164 typedef struct Iso_Image IsoImage;
  165 
  166 /*
  167  * A node in the iso tree, i.e. a file that will be written to image.
  168  *
  169  * It can represent any kind of files. When needed, you can get the type with
  170  * iso_node_get_type() and cast it to the appropriate subtype. Useful macros
  171  * are provided, see below.
  172  *
  173  * @since 0.6.2
  174  */
  175 typedef struct Iso_Node IsoNode;
  176 
  177 /**
  178  * A directory in the iso tree. It is an special type of IsoNode and can be
  179  * casted to it in any case.
  180  *
  181  * @since 0.6.2
  182  */
  183 typedef struct Iso_Dir IsoDir;
  184 
  185 /**
  186  * A symbolic link in the iso tree. It is an special type of IsoNode and can be
  187  * casted to it in any case.
  188  *
  189  * @since 0.6.2
  190  */
  191 typedef struct Iso_Symlink IsoSymlink;
  192 
  193 /**
  194  * A regular file in the iso tree. It is an special type of IsoNode and can be
  195  * casted to it in any case.
  196  *
  197  * @since 0.6.2
  198  */
  199 typedef struct Iso_File IsoFile;
  200 
  201 /**
  202  * An special file in the iso tree. This is used to represent any POSIX file
  203  * other that regular files, directories or symlinks, i.e.: socket, block and
  204  * character devices, and fifos.
  205  * It is an special type of IsoNode and can be casted to it in any case.
  206  *
  207  * @since 0.6.2
  208  */
  209 typedef struct Iso_Special IsoSpecial;
  210 
  211 /**
  212  * The type of an IsoNode.
  213  *
  214  * When an user gets an IsoNode from an image, (s)he can use
  215  * iso_node_get_type() to get the current type of the node, and then
  216  * cast to the appropriate subtype. For example:
  217  *
  218  * ...
  219  * IsoNode *node;
  220  * res = iso_dir_iter_next(iter, &node);
  221  * if (res == 1 && iso_node_get_type(node) == LIBISO_DIR) {
  222  *      IsoDir *dir = (IsoDir *)node;
  223  *      ...
  224  * }
  225  *
  226  * @since 0.6.2
  227  */
  228 enum IsoNodeType {
  229     LIBISO_DIR,
  230     LIBISO_FILE,
  231     LIBISO_SYMLINK,
  232     LIBISO_SPECIAL,
  233     LIBISO_BOOT
  234 };
  235 
  236 /* macros to check node type */
  237 #define ISO_NODE_IS_DIR(n) (iso_node_get_type(n) == LIBISO_DIR)
  238 #define ISO_NODE_IS_FILE(n) (iso_node_get_type(n) == LIBISO_FILE)
  239 #define ISO_NODE_IS_SYMLINK(n) (iso_node_get_type(n) == LIBISO_SYMLINK)
  240 #define ISO_NODE_IS_SPECIAL(n) (iso_node_get_type(n) == LIBISO_SPECIAL)
  241 #define ISO_NODE_IS_BOOTCAT(n) (iso_node_get_type(n) == LIBISO_BOOT)
  242 
  243 /* macros for safe downcasting */
  244 #define ISO_DIR(n) ((IsoDir*)(ISO_NODE_IS_DIR(n) ? n : NULL))
  245 #define ISO_FILE(n) ((IsoFile*)(ISO_NODE_IS_FILE(n) ? n : NULL))
  246 #define ISO_SYMLINK(n) ((IsoSymlink*)(ISO_NODE_IS_SYMLINK(n) ? n : NULL))
  247 #define ISO_SPECIAL(n) ((IsoSpecial*)(ISO_NODE_IS_SPECIAL(n) ? n : NULL))
  248 
  249 #define ISO_NODE(n) ((IsoNode*)n)
  250 
  251 /**
  252  * File section in an old image.
  253  *
  254  * @since 0.6.8
  255  */
  256 struct iso_file_section
  257 {
  258     uint32_t block;
  259     uint32_t size;
  260 };
  261 
  262 /* If you get here because of a compilation error like
  263 
  264        /usr/include/libisofs/libisofs.h:166: error:
  265        expected specifier-qualifier-list before 'uint32_t'
  266 
  267    then see the paragraph above about the definition of uint32_t.
  268 */
  269 
  270 
  271 /**
  272  * Context for iterate on directory children.
  273  * @see iso_dir_get_children()
  274  *
  275  * @since 0.6.2
  276  */
  277 typedef struct Iso_Dir_Iter IsoDirIter;
  278 
  279 /**
  280  * It represents an El-Torito boot image.
  281  *
  282  * @since 0.6.2
  283  */
  284 typedef struct el_torito_boot_image ElToritoBootImage;
  285 
  286 /**
  287  * An special type of IsoNode that acts as a placeholder for an El-Torito
  288  * boot catalog. Once written, it will appear as a regular file.
  289  *
  290  * @since 0.6.2
  291  */
  292 typedef struct Iso_Boot IsoBoot;
  293 
  294 /**
  295  * Flag used to hide a file in the RR/ISO or Joliet tree.
  296  *
  297  * @see iso_node_set_hidden
  298  * @since 0.6.2
  299  */
  300 enum IsoHideNodeFlag {
  301     /** Hide the node in the ECMA-119 / RR tree */
  302     LIBISO_HIDE_ON_RR = 1 << 0,
  303     /** Hide the node in the Joliet tree, if Joliet extension are enabled */
  304     LIBISO_HIDE_ON_JOLIET = 1 << 1,
  305     /** Hide the node in the ISO-9660:1999 tree, if that format is enabled */
  306     LIBISO_HIDE_ON_1999 = 1 << 2,
  307 
  308     /** Hide the node in the HFS+ tree, if that format is enabled.
  309         @since 1.2.4
  310     */
  311     LIBISO_HIDE_ON_HFSPLUS = 1 << 4,
  312 
  313     /** Hide the node in the FAT tree, if that format is enabled.
  314         @since 1.2.4
  315     */
  316     LIBISO_HIDE_ON_FAT = 1 << 5,
  317 
  318     /** With IsoNode and IsoBoot: Write data content even if the node is
  319      *                            not visible in any tree.
  320      *  With directory nodes    : Write data content of IsoNode and IsoBoot
  321      *                            in the directory's tree unless they are
  322      *                            explicitly marked LIBISO_HIDE_ON_RR
  323      *                            without LIBISO_HIDE_BUT_WRITE.
  324      *  @since 0.6.34
  325      */
  326     LIBISO_HIDE_BUT_WRITE = 1 << 3
  327 };
  328 
  329 /**
  330  * El-Torito bootable image type.
  331  *
  332  * @since 0.6.2
  333  */
  334 enum eltorito_boot_media_type {
  335     ELTORITO_FLOPPY_EMUL,
  336     ELTORITO_HARD_DISC_EMUL,
  337     ELTORITO_NO_EMUL
  338 };
  339 
  340 /**
  341  * Replace mode used when adding a node to a directory.
  342  * This controls how libisofs will act when you tried to add to a dir a file
  343  * with the same name that an existing file.
  344  *
  345  * @since 0.6.2
  346  */
  347 enum iso_replace_mode {
  348     /**
  349      * Never replace an existing node, and instead fail with
  350      * ISO_NODE_NAME_NOT_UNIQUE.
  351      */
  352     ISO_REPLACE_NEVER,
  353     /**
  354      * Always replace the old node with the new.
  355      */
  356     ISO_REPLACE_ALWAYS,
  357     /**
  358      * Replace with the new node if it is the same file type
  359      */
  360     ISO_REPLACE_IF_SAME_TYPE,
  361     /**
  362      * Replace with the new node if it is the same file type and its ctime
  363      * is newer than the old one.
  364      */
  365     ISO_REPLACE_IF_SAME_TYPE_AND_NEWER,
  366     /**
  367      * Replace with the new node if its ctime is newer than the old one.
  368      */
  369     ISO_REPLACE_IF_NEWER
  370     /*
  371      * TODO #00006 define more values
  372      *  -if both are dirs, add contents (and what to do with conflicts?)
  373      */
  374 };
  375 
  376 /**
  377  * Options for image written.
  378  * @see iso_write_opts_new()
  379  * @since 0.6.2
  380  */
  381 typedef struct iso_write_opts IsoWriteOpts;
  382 
  383 /**
  384  * Options for image reading or import.
  385  * @see iso_read_opts_new()
  386  * @since 0.6.2
  387  */
  388 typedef struct iso_read_opts IsoReadOpts;
  389 
  390 /**
  391  * Source for image reading.
  392  *
  393  * @see struct iso_data_source
  394  * @since 0.6.2
  395  */
  396 typedef struct iso_data_source IsoDataSource;
  397 
  398 /**
  399  * Data source used by libisofs for reading an existing image.
  400  *
  401  * It offers homogeneous read access to arbitrary blocks to different sources
  402  * for images, such as .iso files, CD/DVD drives, etc...
  403  *
  404  * To create a multisession image, libisofs needs a IsoDataSource, that the
  405  * user must provide. The function iso_data_source_new_from_file() constructs
  406  * an IsoDataSource that uses POSIX I/O functions to access data. You can use
  407  * it with regular .iso images, and also with block devices that represent a
  408  * drive.
  409  *
  410  * @since 0.6.2
  411  */
  412 struct iso_data_source
  413 {
  414 
  415     /* reserved for future usage, set to 0 */
  416     int version;
  417 
  418     /**
  419      * Reference count for the data source. Should be 1 when a new source
  420      * is created. Don't access it directly, but with iso_data_source_ref()
  421      * and iso_data_source_unref() functions.
  422      */
  423     unsigned int refcount;
  424 
  425     /**
  426      * Opens the given source. You must open() the source before any attempt
  427      * to read data from it. The open is the right place for grabbing the
  428      * underlying resources.
  429      *
  430      * @return
  431      *      1 if success, < 0 on error (has to be a valid libisofs error code)
  432      */
  433     int (*open)(IsoDataSource *src);
  434 
  435     /**
  436      * Close a given source, freeing all system resources previously grabbed in
  437      * open().
  438      *
  439      * @return
  440      *      1 if success, < 0 on error (has to be a valid libisofs error code)
  441      */
  442     int (*close)(IsoDataSource *src);
  443 
  444     /**
  445      * Read an arbitrary block (2048 bytes) of data from the source.
  446      *
  447      * @param lba
  448      *     Block to be read.
  449      * @param buffer
  450      *     Buffer where the data will be written. It should have at least
  451      *     2048 bytes.
  452      * @return
  453      *      1 if success,
  454      *    < 0 if error. This function has to emit a valid libisofs error code.
  455      *        Predefined (but not mandatory) for this purpose are:
  456      *          ISO_DATA_SOURCE_SORRY ,   ISO_DATA_SOURCE_MISHAP,
  457      *          ISO_DATA_SOURCE_FAILURE , ISO_DATA_SOURCE_FATAL
  458      */
  459     int (*read_block)(IsoDataSource *src, uint32_t lba, uint8_t *buffer);
  460 
  461     /**
  462      * Clean up the source specific data. Never call this directly, it is
  463      * automatically called by iso_data_source_unref() when refcount reach
  464      * 0.
  465      */
  466     void (*free_data)(IsoDataSource *src);
  467 
  468     /** Source specific data */
  469     void *data;
  470 };
  471 
  472 /**
  473  * Return information for image. This is optionally allocated by libisofs,
  474  * as a way to inform user about the features of an existing image, such as
  475  * extensions present, size, ...
  476  *
  477  * @see iso_image_import()
  478  * @since 0.6.2
  479  */
  480 typedef struct iso_read_image_features IsoReadImageFeatures;
  481 
  482 /**
  483  * POSIX abstraction for source files.
  484  *
  485  * @see struct iso_file_source
  486  * @since 0.6.2
  487  */
  488 typedef struct iso_file_source IsoFileSource;
  489 
  490 /**
  491  * Abstract for source filesystems.
  492  *
  493  * @see struct iso_filesystem
  494  * @since 0.6.2
  495  */
  496 typedef struct iso_filesystem IsoFilesystem;
  497 
  498 /**
  499  * Interface that defines the operations (methods) available for an
  500  * IsoFileSource.
  501  *
  502  * @see struct IsoFileSource_Iface
  503  * @since 0.6.2
  504  */
  505 typedef struct IsoFileSource_Iface IsoFileSourceIface;
  506 
  507 /**
  508  * IsoFilesystem implementation to deal with ISO images, and to offer a way to
  509  * access specific information of the image, such as several volume attributes,
  510  * extensions being used, El-Torito artifacts...
  511  *
  512  * @since 0.6.2
  513  */
  514 typedef IsoFilesystem IsoImageFilesystem;
  515 
  516 /**
  517  * See IsoFilesystem->get_id() for info about this.
  518  * @since 0.6.2
  519  */
  520 extern unsigned int iso_fs_global_id;
  521 
  522 /**
  523  * An IsoFilesystem is a handler for a source of files, or a "filesystem".
  524  * That is defined as a set of files that are organized in a hierarchical
  525  * structure.
  526  *
  527  * A filesystem allows libisofs to access files from several sources in
  528  * an homogeneous way, thus abstracting the underlying operations needed to
  529  * access and read file contents. Note that this doesn't need to be tied
  530  * to the disc filesystem used in the partition being accessed. For example,
  531  * we have an IsoFilesystem implementation to access any mounted filesystem,
  532  * using standard POSIX functions. It is also legal, of course, to implement
  533  * an IsoFilesystem to deal with a specific filesystem over raw partitions.
  534  * That is what we do, for example, to access an ISO Image.
  535  *
  536  * Each file inside an IsoFilesystem is represented as an IsoFileSource object,
  537  * that defines POSIX-like interface for accessing files.
  538  *
  539  * @since 0.6.2
  540  */
  541 struct iso_filesystem
  542 {
  543     /**
  544      * Type of filesystem.
  545      * "file" -> local filesystem
  546      * "iso " -> iso image filesystem
  547      */
  548     char type[4];
  549 
  550     /* reserved for future usage, set to 0 */
  551     int version;
  552 
  553     /**
  554      * Get the root of a filesystem.
  555      *
  556      * @return
  557      *    1 on success, < 0 on error (has to be a valid libisofs error code)
  558      */
  559     int (*get_root)(IsoFilesystem *fs, IsoFileSource **root);
  560 
  561     /**
  562      * Retrieve a file from its absolute path inside the filesystem.
  563      * @param file
  564      *     Returns a pointer to a IsoFileSource object representing the
  565      *     file. It has to be disposed by iso_file_source_unref() when
  566      *     no longer needed.
  567      * @return
  568      *     1 success, < 0 error (has to be a valid libisofs error code)
  569      *      Error codes:
  570      *         ISO_FILE_ACCESS_DENIED
  571      *         ISO_FILE_BAD_PATH
  572      *         ISO_FILE_DOESNT_EXIST
  573      *         ISO_OUT_OF_MEM
  574      *         ISO_FILE_ERROR
  575      *         ISO_NULL_POINTER
  576      */
  577     int (*get_by_path)(IsoFilesystem *fs, const char *path,
  578                        IsoFileSource **file);
  579 
  580     /**
  581      * Get filesystem identifier.
  582      *
  583      * If the filesystem is able to generate correct values of the st_dev
  584      * and st_ino fields for the struct stat of each file, this should
  585      * return an unique number, greater than 0.
  586      *
  587      * To get a identifier for your filesystem implementation you should
  588      * use iso_fs_global_id, incrementing it by one each time.
  589      *
  590      * Otherwise, if you can't ensure values in the struct stat are valid,
  591      * this should return 0.
  592      */
  593     unsigned int (*get_id)(IsoFilesystem *fs);
  594 
  595     /**
  596      * Opens the filesystem for several read operations. Calling this function
  597      * is not needed at all, each time that the underlying system resource
  598      * needs to be accessed, it is opened property.
  599      * However, if you plan to execute several operations on the filesystem,
  600      * it is a good idea to open it previously, to prevent several open/close
  601      * operations to occur.
  602      *
  603      * @return 1 on success, < 0 on error (has to be a valid libisofs error code)
  604      */
  605     int (*open)(IsoFilesystem *fs);
  606 
  607     /**
  608      * Close the filesystem, thus freeing all system resources. You should
  609      * call this function if you have previously open() it.
  610      * Note that you can open()/close() a filesystem several times.
  611      *
  612      * @return 1 on success, < 0 on error (has to be a valid libisofs error code)
  613      */
  614     int (*close)(IsoFilesystem *fs);
  615 
  616     /**
  617      * Free implementation specific data. Should never be called by user.
  618      * Use iso_filesystem_unref() instead.
  619      */
  620     void (*free)(IsoFilesystem *fs);
  621 
  622     /* internal usage, do never access them directly */
  623     unsigned int refcount;
  624     void *data;
  625 };
  626 
  627 /**
  628  * Interface definition for an IsoFileSource. Defines the POSIX-like function
  629  * to access files and abstract underlying source.
  630  *
  631  * @since 0.6.2
  632  */
  633 struct IsoFileSource_Iface
  634 {
  635     /**
  636      * Tells the version of the interface:
  637      * Version 0 provides functions up to (*lseek)().
  638      * @since 0.6.2
  639      * Version 1 additionally provides function *(get_aa_string)().
  640      * @since 0.6.14
  641      * Version 2 additionally provides function *(clone_src)().
  642      * @since 1.0.2
  643      */
  644     int version;
  645 
  646     /**
  647      * Get the absolute path in the filesystem this file source belongs to.
  648      *
  649      * @return
  650      *     the path of the FileSource inside the filesystem, it should be
  651      *     freed when no more needed.
  652      */
  653     char* (*get_path)(IsoFileSource *src);
  654 
  655     /**
  656      * Get the name of the file, with the dir component of the path.
  657      *
  658      * @return
  659      *     the name of the file, it should be freed when no more needed.
  660      */
  661     char* (*get_name)(IsoFileSource *src);
  662 
  663     /**
  664      * Get information about the file. It is equivalent to lstat(2).
  665      *
  666      * @return
  667      *    1 success, < 0 error (has to be a valid libisofs error code)
  668      *      Error codes:
  669      *         ISO_FILE_ACCESS_DENIED
  670      *         ISO_FILE_BAD_PATH
  671      *         ISO_FILE_DOESNT_EXIST
  672      *         ISO_OUT_OF_MEM
  673      *         ISO_FILE_ERROR
  674      *         ISO_NULL_POINTER
  675      */
  676     int (*lstat)(IsoFileSource *src, struct stat *info);
  677 
  678     /**
  679      * Get information about the file. If the file is a symlink, the info
  680      * returned refers to the destination. It is equivalent to stat(2).
  681      *
  682      * @return
  683      *    1 success, < 0 error
  684      *      Error codes:
  685      *         ISO_FILE_ACCESS_DENIED
  686      *         ISO_FILE_BAD_PATH
  687      *         ISO_FILE_DOESNT_EXIST
  688      *         ISO_OUT_OF_MEM
  689      *         ISO_FILE_ERROR
  690      *         ISO_NULL_POINTER
  691      */
  692     int (*stat)(IsoFileSource *src, struct stat *info);
  693 
  694     /**
  695      * Check if the process has access to read file contents. Note that this
  696      * is not necessarily related with (l)stat functions. For example, in a
  697      * filesystem implementation to deal with an ISO image, if the user has
  698      * read access to the image it will be able to read all files inside it,
  699      * despite of the particular permission of each file in the RR tree, that
  700      * are what the above functions return.
  701      *
  702      * @return
  703      *     1 if process has read access, < 0 on error (has to be a valid
  704      *     libisofs error code)
  705      *      Error codes:
  706      *         ISO_FILE_ACCESS_DENIED
  707      *         ISO_FILE_BAD_PATH
  708      *         ISO_FILE_DOESNT_EXIST
  709      *         ISO_OUT_OF_MEM
  710      *         ISO_FILE_ERROR
  711      *         ISO_NULL_POINTER
  712      */
  713     int (*access)(IsoFileSource *src);
  714 
  715     /**
  716      * Opens the source.
  717      * @return 1 on success, < 0 on error (has to be a valid libisofs error code)
  718      *      Error codes:
  719      *         ISO_FILE_ALREADY_OPENED
  720      *         ISO_FILE_ACCESS_DENIED
  721      *         ISO_FILE_BAD_PATH
  722      *         ISO_FILE_DOESNT_EXIST
  723      *         ISO_OUT_OF_MEM
  724      *         ISO_FILE_ERROR
  725      *         ISO_NULL_POINTER
  726      */
  727     int (*open)(IsoFileSource *src);
  728 
  729     /**
  730      * Close a previously opened file
  731      * @return 1 on success, < 0 on error
  732      *      Error codes:
  733      *         ISO_FILE_ERROR
  734      *         ISO_NULL_POINTER
  735      *         ISO_FILE_NOT_OPENED
  736      */
  737     int (*close)(IsoFileSource *src);
  738 
  739     /**
  740      * Attempts to read up to count bytes from the given source into
  741      * the buffer starting at buf.
  742      *
  743      * The file src must be open() before calling this, and close() when no
  744      * more needed. Not valid for dirs. On symlinks it reads the destination
  745      * file.
  746      *
  747      * @return
  748      *     number of bytes read, 0 if EOF, < 0 on error (has to be a valid
  749      *     libisofs error code)
  750      *      Error codes:
  751      *         ISO_FILE_ERROR
  752      *         ISO_NULL_POINTER
  753      *         ISO_FILE_NOT_OPENED
  754      *         ISO_WRONG_ARG_VALUE -> if count == 0
  755      *         ISO_FILE_IS_DIR
  756      *         ISO_OUT_OF_MEM
  757      *         ISO_INTERRUPTED
  758      */
  759     int (*read)(IsoFileSource *src, void *buf, size_t count);
  760 
  761     /**
  762      * Read a directory.
  763      *
  764      * Each call to this function will return a new children, until we reach
  765      * the end of file (i.e, no more children), in that case it returns 0.
  766      *
  767      * The dir must be open() before calling this, and close() when no more
  768      * needed. Only valid for dirs.
  769      *
  770      * Note that "." and ".." children MUST NOT BE returned.
  771      *
  772      * @param child
  773      *     pointer to be filled with the given child. Undefined on error or OEF
  774      * @return
  775      *     1 on success, 0 if EOF (no more children), < 0 on error (has to be
  776      *     a valid libisofs error code)
  777      *      Error codes:
  778      *         ISO_FILE_ERROR
  779      *         ISO_NULL_POINTER
  780      *         ISO_FILE_NOT_OPENED
  781      *         ISO_FILE_IS_NOT_DIR
  782      *         ISO_OUT_OF_MEM
  783      */
  784     int (*readdir)(IsoFileSource *src, IsoFileSource **child);
  785 
  786     /**
  787      * Read the destination of a symlink. You don't need to open the file
  788      * to call this.
  789      *
  790      * @param buf
  791      *     allocated buffer of at least bufsiz bytes.
  792      *     The dest. will be copied there, and it will be NULL-terminated
  793      * @param bufsiz
  794      *     characters to be copied. Destination link will be truncated if
  795      *     it is larger than given size. This include the 0x0 character.
  796      * @return
  797      *     1 on success, < 0 on error (has to be a valid libisofs error code)
  798      *      Error codes:
  799      *         ISO_FILE_ERROR
  800      *         ISO_NULL_POINTER
  801      *         ISO_WRONG_ARG_VALUE -> if bufsiz <= 0
  802      *         ISO_FILE_IS_NOT_SYMLINK
  803      *         ISO_OUT_OF_MEM
  804      *         ISO_FILE_BAD_PATH
  805      *         ISO_FILE_DOESNT_EXIST
  806      *
  807      */
  808     int (*readlink)(IsoFileSource *src, char *buf, size_t bufsiz);
  809 
  810     /**
  811      * Get the filesystem for this source. No extra ref is added, so you
  812      * must not unref the IsoFilesystem.
  813      *
  814      * @return
  815      *     The filesystem, NULL on error
  816      */
  817     IsoFilesystem* (*get_filesystem)(IsoFileSource *src);
  818 
  819     /**
  820      * Free implementation specific data. Should never be called by user.
  821      * Use iso_file_source_unref() instead.
  822      */
  823     void (*free)(IsoFileSource *src);
  824 
  825     /**
  826      * Repositions the offset of the IsoFileSource (must be opened) to the
  827      * given offset according to the value of flag.
  828      *
  829      * @param offset
  830      *      in bytes
  831      * @param flag
  832      *      0 The offset is set to offset bytes (SEEK_SET)
  833      *      1 The offset is set to its current location plus offset bytes
  834      *        (SEEK_CUR)
  835      *      2 The offset is set to the size of the file plus offset bytes
  836      *        (SEEK_END).
  837      * @return
  838      *      Absolute offset position of the file, or < 0 on error. Cast the
  839      *      returning value to int to get a valid libisofs error.
  840      *
  841      * @since 0.6.4
  842      */
  843     off_t (*lseek)(IsoFileSource *src, off_t offset, int flag);
  844 
  845     /* Add-ons of .version 1 begin here */
  846 
  847     /**
  848      * Valid only if .version is > 0. See above.
  849      * Get the AAIP string with encoded ACL and xattr.
  850      * (Not to be confused with ECMA-119 Extended Attributes).
  851      *
  852      * bit1 and bit2 of flag should be implemented so that freshly fetched
  853      * info does not include the undesired ACL or xattr. Nevertheless if the
  854      * aa_string is cached, then it is permissible that ACL and xattr are still
  855      * delivered.
  856      *
  857      * @param flag       Bitfield for control purposes
  858      *                   bit0= Transfer ownership of AAIP string data.
  859      *                         src will free the eventual cached data and might
  860      *                         not be able to produce it again.
  861      *                   bit1= No need to get ACL (no guarantee of exclusion)
  862      *                   bit2= No need to get xattr (no guarantee of exclusion)
  863      * @param aa_string  Returns a pointer to the AAIP string data. If no AAIP
  864      *                   string is available, *aa_string becomes NULL.
  865      *                   (See doc/susp_aaip_*_*.txt for the meaning of AAIP and
  866      *                    libisofs/aaip_0_2.h for encoding and decoding.)
  867      *                   The caller is responsible for finally calling free()
  868      *                   on non-NULL results.
  869      * @return           1 means success (*aa_string == NULL is possible)
  870      *                   2 means success, but it is possible that attributes
  871      *                     exist in non-user namespaces which could not be
  872      *                     explored due to lack of permission.
  873      *                     @since 1.5.0
  874      *                  <0 means failure and must b a valid libisofs error code
  875      *                     (e.g. ISO_FILE_ERROR if no better one can be found).
  876      * @since 0.6.14
  877      */
  878     int (*get_aa_string)(IsoFileSource *src,
  879                                      unsigned char **aa_string, int flag);
  880 
  881     /**
  882      * Produce a copy of a source. It must be possible to operate both source
  883      * objects concurrently.
  884      * 
  885      * @param old_src
  886      *     The existing source object to be copied
  887      * @param new_stream
  888      *     Will return a pointer to the copy
  889      * @param flag
  890      *     Bitfield for control purposes. Submit 0 for now.
  891      *     The function shall return ISO_STREAM_NO_CLONE on unknown flag bits.
  892      *
  893      * @since 1.0.2
  894      * Present if .version is 2 or higher.
  895      */
  896     int (*clone_src)(IsoFileSource *old_src, IsoFileSource **new_src, 
  897                      int flag);
  898 
  899     /*
  900      * TODO #00004 Add a get_mime_type() function.
  901      * This can be useful for GUI apps, to choose the icon of the file
  902      */
  903 };
  904 
  905 #ifndef __cplusplus
  906 #ifndef Libisofs_h_as_cpluspluS
  907 
  908 /**
  909  * An IsoFile Source is a POSIX abstraction of a file.
  910  *
  911  * @since 0.6.2
  912  */
  913 struct iso_file_source
  914 {
  915     const IsoFileSourceIface *class;
  916     int refcount;
  917     void *data;
  918 };
  919 
  920 #endif /* ! Libisofs_h_as_cpluspluS */
  921 #endif /* ! __cplusplus */
  922 
  923 
  924 /* A class of IsoStream is implemented by a class description
  925  *    IsoStreamIface = struct IsoStream_Iface
  926  * and a structure of data storage for each instance of IsoStream.
  927  * This structure shall be known to the functions of the IsoStreamIface.
  928  * To create a custom IsoStream class:
  929  * - Define the structure of the custom instance data.
  930  * - Implement the methods which are described by the definition of
  931  *   struct IsoStream_Iface (see below),
  932  * - Create a static instance of IsoStreamIface which lists the methods as
  933  *   C function pointers. (Example in libisofs/stream.c : fsrc_stream_class)
  934  * To create an instance of that class:
  935  * - Allocate sizeof(IsoStream) bytes of memory and initialize it as
  936  *   struct iso_stream :
  937  *   - Point to the custom IsoStreamIface by member .class .
  938  *   - Set member .refcount to 1.
  939  *   - Let member .data point to the custom instance data.
  940  *
  941  * Regrettably the choice of the structure member name "class" makes it
  942  * impossible to implement this generic interface in C++ language directly.
  943  * If C++ is absolutely necessary then you will have to make own copies
  944  * of the public API structures. Use other names but take care to maintain
  945  * the same memory layout.
  946  */
  947 
  948 /**
  949  * Representation of file contents. It is an stream of bytes, functionally
  950  * like a pipe.
  951  *
  952  * @since 0.6.4
  953  */
  954 typedef struct iso_stream IsoStream;
  955 
  956 /**
  957  * Interface that defines the operations (methods) available for an
  958  * IsoStream.
  959  *
  960  * @see struct IsoStream_Iface
  961  * @since 0.6.4
  962  */
  963 typedef struct IsoStream_Iface IsoStreamIface;
  964 
  965 /**
  966  * Serial number to be used when you can't get a valid id for a Stream by other
  967  * means. If you use this, both fs_id and dev_id should be set to 0.
  968  * This must be incremented each time you get a reference to it.
  969  *
  970  * @see IsoStreamIface->get_id()
  971  * @since 0.6.4
  972  */
  973 extern ino_t serial_id;
  974 
  975 /**
  976  * Interface definition for IsoStream methods. It is public to allow
  977  * implementation of own stream types.
  978  * The methods defined here typically make use of stream.data which points
  979  * to the individual state data of stream instances.
  980  * 
  981  * @since 0.6.4
  982  */
  983 
  984 struct IsoStream_Iface
  985 {
  986     /*
  987      * Current version of the interface.
  988      * Version 0 (since 0.6.4)
  989      *    deprecated but still valid.
  990      * Version 1 (since 0.6.8) 
  991      *    update_size() added.
  992      * Version 2 (since 0.6.18)
  993      *    get_input_stream() added.
  994      *    A filter stream must have version 2 at least.
  995      * Version 3 (since 0.6.20)
  996      *    cmp_ino() added.
  997      *    A filter stream should have version 3 at least.
  998      * Version 4 (since 1.0.2)
  999      *    clone_stream() added.
 1000      */
 1001     int version;
 1002 
 1003     /**
 1004      * Type of Stream.
 1005      * "fsrc" -> Read from file source
 1006      * "cout" -> Cut out interval from disk file
 1007      * "mem " -> Read from memory
 1008      * "boot" -> Boot catalog
 1009      * "extf" -> External filter program
 1010      * "ziso" -> zisofs compression
 1011      * "osiz" -> zisofs uncompression
 1012      * "gzip" -> gzip compression
 1013      * "pizg" -> gzip uncompression (gunzip)
 1014      * "user" -> User supplied stream
 1015      */
 1016     char type[4];
 1017 
 1018     /**
 1019      * Opens the stream.
 1020      *
 1021      * @return
 1022      *     1 on success, 2 file greater than expected, 3 file smaller than
 1023      *     expected, < 0 on error (has to be a valid libisofs error code)
 1024      */
 1025     int (*open)(IsoStream *stream);
 1026 
 1027     /**
 1028      * Close the Stream.
 1029      * @return
 1030      *     1 on success, < 0 on error (has to be a valid libisofs error code)
 1031      */
 1032     int (*close)(IsoStream *stream);
 1033 
 1034     /**
 1035      * Get the size (in bytes) of the stream. This function should always
 1036      * return the same size, even if the underlying source size changes,
 1037      * unless you call update_size() method.
 1038      */
 1039     off_t (*get_size)(IsoStream *stream);
 1040 
 1041     /**
 1042      * Attempt to read up to count bytes from the given stream into
 1043      * the buffer starting at buf. The implementation has to make sure that
 1044      * either the full desired count of bytes is delivered or that the
 1045      * next call to this function will return EOF or error.
 1046      * I.e. only the last read block may be shorter than parameter count.
 1047      *
 1048      * The stream must be open() before calling this, and close() when no
 1049      * more needed.
 1050      *
 1051      * @return
 1052      *     number of bytes read, 0 if EOF, < 0 on error (has to be a valid
 1053      *     libisofs error code)
 1054      */
 1055     int (*read)(IsoStream *stream, void *buf, size_t count);
 1056 
 1057     /**
 1058      * Tell whether this IsoStream can be read several times, with the same
 1059      * results. For example, a regular file is repeatable, you can read it
 1060      * as many times as you want. However, a pipe is not.
 1061      *
 1062      * @return
 1063      *     1 if stream is repeatable, 0 if not,
 1064      *     < 0 on error (has to be a valid libisofs error code)
 1065      */
 1066     int (*is_repeatable)(IsoStream *stream);
 1067 
 1068     /**
 1069      * Get an unique identifier for the IsoStream.
 1070      */
 1071     void (*get_id)(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id,
 1072                   ino_t *ino_id);
 1073 
 1074     /**
 1075      * Free implementation specific data. Should never be called by user.
 1076      * Use iso_stream_unref() instead.
 1077      */
 1078     void (*free)(IsoStream *stream);
 1079 
 1080     /**
 1081      * Update the size of the IsoStream with the current size of the underlying
 1082      * source, if the source is prone to size changes. After calling this,
 1083      * get_size() shall eventually return the new size.
 1084      * This will never be called after iso_image_create_burn_source() was
 1085      * called and before the image was completely written.
 1086      * (The API call to update the size of all files in the image is
 1087      *  iso_image_update_sizes()).
 1088      *
 1089      * @return
 1090      *     1 if ok, < 0 on error (has to be a valid libisofs error code)
 1091      *
 1092      * @since 0.6.8
 1093      * Present if .version is 1 or higher.
 1094      */
 1095     int (*update_size)(IsoStream *stream);
 1096 
 1097     /**
 1098      * Retrieve the eventual input stream of a filter stream.
 1099      *
 1100      * @param stream
 1101      *     The eventual filter stream to be inquired.
 1102      * @param flag
 1103      *     Bitfield for control purposes. 0 means normal behavior.
 1104      * @return
 1105      *     The input stream, if one exists. Elsewise NULL.
 1106      *     No extra reference to the stream shall be taken by this call.
 1107      *
 1108      * @since 0.6.18
 1109      * Present if .version is 2 or higher.
 1110      */
 1111     IsoStream *(*get_input_stream)(IsoStream *stream, int flag);
 1112 
 1113     /**
 1114      * Compare two streams whether they are based on the same input and will
 1115      * produce the same output. If in any doubt, then this comparison should
 1116      * indicate no match. A match might allow hardlinking of IsoFile objects.
 1117      *
 1118      * A pointer value of NULL is permissible. In this case, function
 1119      * iso_stream_cmp_ino() will decide on its own.
 1120      *
 1121      * If not NULL, this function .cmp_ino() will be called by
 1122      * iso_stream_cmp_ino() if both compared streams point to it, and if not
 1123      * flag bit0 of iso_stream_cmp_ino() prevents it.
 1124      * So a .cmp_ino() function must be able to compare any pair of streams
 1125      * which name it as their .cmp_ino(). A fallback to iso_stream_cmp_ino(,,1)
 1126      * would endanger transitivity of iso_stream_cmp_ino(,,0).
 1127      *
 1128      * With filter streams, the decision whether the underlying chains of
 1129      * streams match, should be delegated to
 1130      *    iso_stream_cmp_ino(iso_stream_get_input_stream(s1, 0),
 1131      *                       iso_stream_get_input_stream(s2, 0), 0);
 1132      *
 1133      * The stream.cmp_ino() function has to establish an equivalence and order
 1134      * relation: 
 1135      *   cmp_ino(A,A) == 0
 1136      *   cmp_ino(A,B) == -cmp_ino(B,A) 
 1137      *   if cmp_ino(A,B) == 0 && cmp_ino(B,C) == 0 then cmp_ino(A,C) == 0
 1138      * Most tricky is the demand for transitivity:
 1139      *   if cmp_ino(A,B) < 0 && cmp_ino(B,C) < 0 then cmp_ino(A,C) < 0
 1140      *
 1141      * @param s1
 1142      *     The first stream to compare. Expect foreign stream types.
 1143      * @param s2
 1144      *     The second stream to compare. Expect foreign stream types.
 1145      * @return
 1146      *     -1 if s1 is smaller s2 , 0 if s1 matches s2 , 1 if s1 is larger s2
 1147      *
 1148      * @since 0.6.20
 1149      * Present if .version is 3 or higher.
 1150      */
 1151     int (*cmp_ino)(IsoStream *s1, IsoStream *s2);
 1152 
 1153     /**
 1154      * Produce a copy of a stream. It must be possible to operate both stream
 1155      * objects concurrently.
 1156      * 
 1157      * @param old_stream
 1158      *     The existing stream object to be copied
 1159      * @param new_stream
 1160      *     Will return a pointer to the copy
 1161      * @param flag
 1162      *     Bitfield for control purposes. 0 means normal behavior.
 1163      *     The function shall return ISO_STREAM_NO_CLONE on unknown flag bits.
 1164      * @return
 1165      *     1 in case of success, or an error code < 0
 1166      *
 1167      * @since 1.0.2
 1168      * Present if .version is 4 or higher.
 1169      */
 1170     int (*clone_stream)(IsoStream *old_stream, IsoStream **new_stream,
 1171                         int flag);
 1172 
 1173 };
 1174 
 1175 #ifndef __cplusplus
 1176 #ifndef Libisofs_h_as_cpluspluS
 1177 
 1178 /**
 1179  * Representation of file contents as a stream of bytes.
 1180  *
 1181  * @since 0.6.4
 1182  */
 1183 struct iso_stream
 1184 {
 1185     IsoStreamIface *class;
 1186     int refcount;
 1187     void *data;
 1188 };
 1189 
 1190 #endif /* ! Libisofs_h_as_cpluspluS */
 1191 #endif /* ! __cplusplus */
 1192 
 1193 
 1194 /**
 1195  * Initialize libisofs. Before any usage of the library you must either call
 1196  * this function or iso_init_with_flag().
 1197  * Only exception from this rule: iso_lib_version(), iso_lib_is_compatible().
 1198  * @return 1 on success, < 0 on error
 1199  *
 1200  * @since 0.6.2
 1201  */
 1202 int iso_init();
 1203 
 1204 /**
 1205  * Initialize libisofs. Before any usage of the library you must either call
 1206  * this function or iso_init() which is equivalent to iso_init_with_flag(0).
 1207  * Only exception from this rule: iso_lib_version(), iso_lib_is_compatible().
 1208  * @param flag
 1209  *      Bitfield for control purposes
 1210  *      bit0= do not set up locale by LC_* environment variables
 1211  * @return 1 on success, < 0 on error
 1212  *
 1213  * @since 0.6.18
 1214  */
 1215 int iso_init_with_flag(int flag);
 1216 
 1217 /**
 1218  * Finalize libisofs.
 1219  *
 1220  * @since 0.6.2
 1221  */
 1222 void iso_finish();
 1223 
 1224 /**
 1225  * Override the reply of libc function nl_langinfo(CODESET) which may or may
 1226  * not give the name of the character set which is in effect for your
 1227  * environment. So this call can compensate for inconsistent terminal setups.
 1228  * Another use case is to choose UTF-8 as intermediate character set for a
 1229  * conversion from an exotic input character set to an exotic output set.
 1230  *
 1231  * @param name
 1232  *     Name of the character set to be assumed as "local" one.
 1233  * @param flag
 1234  *     Unused yet. Submit 0.
 1235  * @return
 1236  *     1 indicates success, <=0 failure
 1237  *
 1238  * @since 0.6.12
 1239  */
 1240 int iso_set_local_charset(char *name, int flag);
 1241 
 1242 /**
 1243  * Obtain the local charset as currently assumed by libisofs.
 1244  * The result points to internal memory. It is volatile and must not be
 1245  * altered.
 1246  *
 1247  * @param flag
 1248  *     Unused yet. Submit 0.
 1249  *
 1250  * @since 0.6.12
 1251  */
 1252 char *iso_get_local_charset(int flag);
 1253 
 1254 /**
 1255  * Inquire and maybe define the time which is considered to be "now" and
 1256  * used for timestamps of freshly created ISO nodes and as default of
 1257  * image timestamps.
 1258  * If ever, this should normally be enabled and defined before iso_image_new().
 1259  * If it is disabled, time(NULL) is considered to be "now".
 1260  *
 1261  * @param now
 1262  *      Returns the "now" value and maybe submits it as definition.
 1263  * @param flag
 1264  *      Bitfield for control purposes
 1265  *      bit0= *now contains the time to be set as nowtime override.
 1266               Enable the override if not bit1 is set, too.
 1267  *      bit1= Disable the nowtime override
 1268  * @return 1= *now is not overridden , 2= *now is overridden
 1269  *
 1270  * @since 1.5.2
 1271  */
 1272 int iso_nowtime(time_t *now, int flag);
 1273 
 1274 
 1275 /**
 1276  * Create a new image, empty.
 1277  *
 1278  * The image will be owned by you and should be unref() when no more needed.
 1279  *
 1280  * @param name
 1281  *     Name of the image. This will be used as volset_id and volume_id.
 1282  * @param image
 1283  *     Location where the image pointer will be stored.
 1284  * @return
 1285  *     1 success, < 0 error
 1286  *
 1287  * @since 0.6.2
 1288  */
 1289 int iso_image_new(const char *name, IsoImage **image);
 1290 
 1291 
 1292 /**
 1293  * Control whether ACL and xattr will be imported from external filesystems
 1294  * (typically the local POSIX filesystem) when new nodes get inserted. If
 1295  * enabled by iso_write_opts_set_aaip() they will later be written into the
 1296  * image as AAIP extension fields.
 1297  *
 1298  * A change of this setting does neither affect existing IsoNode objects
 1299  * nor the way how ACL and xattr are handled when loading an ISO image.
 1300  * The latter is controlled by iso_read_opts_set_no_aaip().
 1301  *
 1302  * @param image
 1303  *     The image of which the behavior is to be controlled
 1304  * @param what
 1305  *     A bit field which sets the behavior:
 1306  *     bit0= ignore ACLs if the external file object bears some
 1307  *     bit1= ignore xattr if the external file object bears some
 1308  *     bit3= if not bit1: import all xattr namespaces, not only "user."
 1309  *           @since 1.5.0
 1310  *     all other bits are reserved
 1311  *
 1312  * @since 0.6.14
 1313  */
 1314 void iso_image_set_ignore_aclea(IsoImage *image, int what);
 1315 
 1316 
 1317 /**
 1318  * Obtain the current setting of iso_image_set_ignore_aclea().
 1319  *
 1320  * @param image
 1321  *     The image to be inquired
 1322  * @return
 1323  *    The currently set value.
 1324  * 
 1325  * @since 1.5.0
 1326  */
 1327 int iso_image_get_ignore_aclea(IsoImage *image);
 1328 
 1329 
 1330 /**
 1331  * Creates an IsoWriteOpts for writing an image. You should set the options
 1332  * desired with the correspondent setters.
 1333  *
 1334  * Options by default are determined by the selected profile. Fifo size is set
 1335  * by default to 2 MB.
 1336  *
 1337  * @param opts
 1338  *     Pointer to the location where the newly created IsoWriteOpts will be
 1339  *     stored. You should free it with iso_write_opts_free() when no more
 1340  *     needed.
 1341  * @param profile
 1342  *     Default profile for image creation. For now the following values are
 1343  *     defined:
 1344  *     ---> 0 [BASIC]
 1345  *        No extensions are enabled, and ISO level is set to 1. Only suitable
 1346  *        for usage for very old and limited systems (like MS-DOS), or by a
 1347  *        start point from which to set your custom options.
 1348  *     ---> 1 [BACKUP]
 1349  *        POSIX compatibility for backup. Simple settings, ISO level is set to
 1350  *        3 and RR extensions are enabled. Useful for backup purposes.
 1351  *        Note that ACL and xattr are not enabled by default.
 1352  *        If you enable them, expect them not to show up in the mounted image.
 1353  *        They will have to be retrieved by libisofs applications like xorriso.
 1354  *     ---> 2 [DISTRIBUTION]
 1355  *        Setting for information distribution. Both RR and Joliet are enabled
 1356  *        to maximize compatibility with most systems. Permissions are set to
 1357  *        default values, and timestamps to the time of recording.
 1358  * @return
 1359  *      1 success, < 0 error
 1360  *
 1361  * @since 0.6.2
 1362  */
 1363 int iso_write_opts_new(IsoWriteOpts **opts, int profile);
 1364 
 1365 /**
 1366  * Free an IsoWriteOpts previously allocated with iso_write_opts_new().
 1367  *
 1368  * @since 0.6.2
 1369  */
 1370 void iso_write_opts_free(IsoWriteOpts *opts);
 1371 
 1372 /**
 1373  * Announce that only the image size is desired, that the struct burn_source
 1374  * which is set to consume the image output stream will stay inactive,
 1375  * and that the write thread will be cancelled anyway by the .cancel() method
 1376  * of the struct burn_source.
 1377  * This avoids to create a write thread which would begin production of the
 1378  * image stream and would generate a MISHAP event when burn_source.cancel()
 1379  * gets into effect.
 1380  * 
 1381  * @param opts
 1382  *      The option set to be manipulated.
 1383  * @param will_cancel
 1384  *      0= normal image generation
 1385  *      1= prepare for being canceled before image stream output is completed
 1386  * @return
 1387  *      1 success, < 0 error
 1388  *
 1389  * @since 0.6.40
 1390  */
 1391 int iso_write_opts_set_will_cancel(IsoWriteOpts *opts, int will_cancel);
 1392 
 1393 /**
 1394  * Set the ISO-9960 level to write at.
 1395  *
 1396  * @param opts
 1397  *      The option set to be manipulated.
 1398  * @param level
 1399  *      -> 1 for higher compatibility with old systems. With this level
 1400  *      filenames are restricted to 8.3 characters.
 1401  *      -> 2 to allow up to 31 filename characters.
 1402  *      -> 3 to allow files greater than 4GB
 1403  * @return
 1404  *      1 success, < 0 error
 1405  *
 1406  * @since 0.6.2
 1407  */
 1408 int iso_write_opts_set_iso_level(IsoWriteOpts *opts, int level);
 1409 
 1410 /**
 1411  * Whether to use or not Rock Ridge extensions.
 1412  *
 1413  * This are standard extensions to ECMA-119, intended to add POSIX filesystem
 1414  * features to ECMA-119 images. Thus, usage of this flag is highly recommended
 1415  * for images used on GNU/Linux systems. With the usage of RR extension, the
 1416  * resulting image will have long filenames (up to 255 characters), deeper
 1417  * directory structure, POSIX permissions and owner info on files and
 1418  * directories, support for symbolic links or special files... All that
 1419  * attributes can be modified/set with the appropriate function.
 1420  *
 1421  * @param opts
 1422  *      The option set to be manipulated.
 1423  * @param enable
 1424  *      1 to enable RR extension, 0 to not add them
 1425  * @return
 1426  *      1 success, < 0 error
 1427  *
 1428  * @since 0.6.2
 1429  */
 1430 int iso_write_opts_set_rockridge(IsoWriteOpts *opts, int enable);
 1431 
 1432 /**
 1433  * Whether to add the non-standard Joliet extension to the image.
 1434  *
 1435  * This extensions are heavily used in Microsoft Windows systems, so if you
 1436  * plan to use your disc on such a system you should add this extension.
 1437  * Usage of Joliet supplies longer filesystem length (up to 64 unicode
 1438  * characters), and deeper directory structure.
 1439  *
 1440  * @param opts
 1441  *      The option set to be manipulated.
 1442  * @param enable
 1443  *      1 to enable Joliet extension, 0 to not add them
 1444  * @return
 1445  *      1 success, < 0 error
 1446  *
 1447  * @since 0.6.2
 1448  */
 1449 int iso_write_opts_set_joliet(IsoWriteOpts *opts, int enable);
 1450 
 1451 /**
 1452  * Whether to add a HFS+ filesystem to the image which points to the same
 1453  * file content as the other directory trees.
 1454  * It will get marked by an Apple Partition Map in the System Area of the ISO
 1455  * image. This may collide with data submitted by
 1456  *   iso_write_opts_set_system_area()
 1457  * and with settings made by 
 1458  *   el_torito_set_isolinux_options()
 1459  * The first 8 bytes of the System Area get overwritten by
 1460  *   {0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff}
 1461  * which can be executed as x86 machine code without negative effects.
 1462  * So if an MBR gets combined with this feature, then its first 8 bytes
 1463  * should contain no essential commands.
 1464  * The next blocks of 2 KiB in the System Area will be occupied by APM entries.
 1465  * The first one covers the part of the ISO image before the HFS+ filesystem
 1466  * metadata. The second one marks the range from HFS+ metadata to the end
 1467  * of file content data. If more ISO image data follow, then a third partition
 1468  * entry gets produced. Other features of libisofs might cause the need for
 1469  * more APM entries.
 1470  *
 1471  * @param opts
 1472  *      The option set to be manipulated.
 1473  * @param enable
 1474  *      1 to enable HFS+ extension, 0 to not add HFS+ metadata and APM
 1475  * @return
 1476  *      1 success, < 0 error
 1477  *
 1478  * @since 1.2.4
 1479  */
 1480 int iso_write_opts_set_hfsplus(IsoWriteOpts *opts, int enable);
 1481 
 1482 /**
 1483  * >>> Production of FAT32 is not implemented yet.
 1484  * >>> This call exists only as preparation for implementation.
 1485  *
 1486  * Whether to add a FAT32 filesystem to the image which points to the same
 1487  * file content as the other directory trees.
 1488  *
 1489  * >>> FAT32 is planned to get implemented in co-existence with HFS+
 1490  * >>> Describe impact on MBR
 1491  *
 1492  * @param opts
 1493  *      The option set to be manipulated.
 1494  * @param enable
 1495  *      1 to enable FAT32 extension, 0 to not add FAT metadata
 1496  * @return
 1497  *      1 success, < 0 error
 1498  *
 1499  * @since 1.2.4
 1500  */
 1501 int iso_write_opts_set_fat(IsoWriteOpts *opts, int enable);
 1502 
 1503 /**
 1504  * Supply a serial number for the HFS+ extension of the emerging image.
 1505  *
 1506  * @param opts
 1507  *      The option set to be manipulated.
 1508  * @param serial_number
 1509  *      8 bytes which should be unique to the image.
 1510  *      If all bytes are 0, then the serial number will be generated as
 1511  *      random number by libisofs. This is the default setting.
 1512  * @return
 1513  *      1 success, < 0 error
 1514  *
 1515  * @since 1.2.4
 1516  */
 1517 int iso_write_opts_set_hfsp_serial_number(IsoWriteOpts *opts,
 1518                                           uint8_t serial_number[8]);
 1519 
 1520 /**
 1521  * Set the block size for Apple Partition Map and for HFS+.
 1522  *
 1523  * @param opts
 1524  *      The option set to be manipulated.
 1525  * @param hfsp_block_size
 1526  *      The allocation block size to be used by the HFS+ filesystem.
 1527  *      0, 512, or 2048
 1528  * @param apm_block_size
 1529  *      The block size to be used for and within the Apple Partition Map.
 1530  *      0, 512, or 2048.
 1531  *      Size 512 is not compatible with options which produce GPT.
 1532  * @return
 1533  *      1 success, < 0 error
 1534  *
 1535  * @since 1.2.4
 1536  */
 1537 int iso_write_opts_set_hfsp_block_size(IsoWriteOpts *opts,
 1538                                      int hfsp_block_size, int apm_block_size);
 1539 
 1540 
 1541 /**
 1542  * Whether to use newer ISO-9660:1999 version.
 1543  *
 1544  * This is the second version of ISO-9660. It allows longer filenames and has
 1545  * less restrictions than old ISO-9660. However, nobody is using it so there
 1546  * are no much reasons to enable this.
 1547  *
 1548  * @since 0.6.2
 1549  */
 1550 int iso_write_opts_set_iso1999(IsoWriteOpts *opts, int enable);
 1551 
 1552 /**
 1553  * Control generation of non-unique inode numbers for the emerging image.
 1554  * Inode numbers get written as "file serial number" with PX entries as of
 1555  * RRIP-1.12. They may mark families of hardlinks.
 1556  * RRIP-1.10 prescribes a PX entry without file serial number.If not overridden
 1557  * by iso_write_opts_set_rrip_1_10_px_ino() there will be no file serial number
 1558  * written into RRIP-1.10 images.
 1559  *
 1560  * Inode number generation does not affect IsoNode objects which imported their
 1561  * inode numbers from the old ISO image (see iso_read_opts_set_new_inos())
 1562  * and which have not been altered since import. It rather applies to IsoNode
 1563  * objects which were newly added to the image, or to IsoNode which brought no
 1564  * inode number from the old image, or to IsoNode where certain properties 
 1565  * have been altered since image import.
 1566  *
 1567  * If two IsoNode are found with same imported inode number but differing
 1568  * properties, then one of them will get assigned a new unique inode number.
 1569  * I.e. the hardlink relation between both IsoNode objects ends.
 1570  *
 1571  * @param opts
 1572  *      The option set to be manipulated.
 1573  * @param enable 
 1574  *      1 = Collect IsoNode objects which have identical data sources and
 1575  *          properties.
 1576  *      0 = Generate unique inode numbers for all IsoNode objects which do not
 1577  *          have a valid inode number from an imported ISO image.
 1578  *      All other values are reserved.
 1579  *
 1580  * @since 0.6.20
 1581  */
 1582 int iso_write_opts_set_hardlinks(IsoWriteOpts *opts, int enable);
 1583 
 1584 /**
 1585  * Control writing of AAIP information for ACL and xattr.
 1586  * For importing ACL and xattr when inserting nodes from external filesystems
 1587  * (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea().
 1588  * For loading of this information from images see iso_read_opts_set_no_aaip().
 1589  *
 1590  * @param opts
 1591  *      The option set to be manipulated.
 1592  * @param enable
 1593  *      1 = write AAIP information from nodes into the image
 1594  *      0 = do not write AAIP information into the image
 1595  *      All other values are reserved.
 1596  *
 1597  * @since 0.6.14
 1598  */
 1599 int iso_write_opts_set_aaip(IsoWriteOpts *opts, int enable);
 1600 
 1601 /**
 1602  * Use this only if you need to reproduce a suboptimal behavior of older
 1603  * versions of libisofs. They used address 0 for links and device files,
 1604  * and the address of the Volume Descriptor Set Terminator for empty data
 1605  * files.
 1606  * New versions let symbolic links, device files, and empty data files point
 1607  * to a dedicated block of zero-bytes after the end of the directory trees.
 1608  * (Single-pass reader libarchive needs to see all directory info before
 1609  *  processing any data files.)
 1610  *
 1611  * @param opts
 1612  *      The option set to be manipulated.
 1613  * @param enable
 1614  *      1 = use the suboptimal block addresses in the range of 0 to 115.
 1615  *      0 = use the address of a block after the directory tree. (Default)
 1616  *
 1617  * @since 1.0.2
 1618  */
 1619 int iso_write_opts_set_old_empty(IsoWriteOpts *opts, int enable);
 1620 
 1621 /**
 1622  * Caution: This option breaks any assumptions about names that
 1623  *          are supported by ECMA-119 specifications. 
 1624  * Try to omit any translation which would make a file name compliant to the
 1625  * ECMA-119 rules. This includes and exceeds omit_version_numbers,
 1626  * max_37_char_filenames, no_force_dots bit0, allow_full_ascii. Further it
 1627  * prevents the conversion from local character set to ASCII.
 1628  * The maximum name length is given by this call. If a filename exceeds
 1629  * this length or cannot be recorded untranslated for other reasons, then
 1630  * image production is aborted with ISO_NAME_NEEDS_TRANSL.
 1631  * Currently the length limit is 96 characters, because an ECMA-119 directory
 1632  * record may at most have 254 bytes and up to 158 other bytes must fit into
 1633  * the record. Probably 96 more bytes can be made free for the name in future.
 1634  * @param opts
 1635  *      The option set to be manipulated.
 1636  * @param len
 1637  *      0 = disable this feature and perform name translation according to
 1638  *          other settings.
 1639  *     >0 = Omit any translation. Eventually abort image production
 1640  *          if a name is longer than the given value.
 1641  *     -1 = Like >0. Allow maximum possible length (currently 96)
 1642  * @return >=0 success, <0 failure
 1643  *         In case of >=0 the return value tells the effectively set len.
 1644  *         E.g. 96 after using len == -1.
 1645  * @since 1.0.0
 1646  */
 1647 int iso_write_opts_set_untranslated_name_len(IsoWriteOpts *opts, int len);
 1648 
 1649 /**
 1650  * Convert directory names for ECMA-119 similar to other file names, but do
 1651  * not force a dot or add a version number.
 1652  * This violates ECMA-119 by allowing one "." and especially ISO level 1 
 1653  * by allowing DOS style 8.3 names rather than only 8 characters.
 1654  * (mkisofs and its clones seem to do this violation.)
 1655  * @param opts
 1656  *      The option set to be manipulated.
 1657  * @param allow
 1658  *      1= allow dots , 0= disallow dots and convert them
 1659  * @return
 1660  *      1 success, < 0 error
 1661  * @since 1.0.0
 1662  */
 1663 int iso_write_opts_set_allow_dir_id_ext(IsoWriteOpts *opts, int allow);
 1664 
 1665 /**
 1666  * Omit the version number (";1") at the end of the ISO-9660 identifiers.
 1667  * This breaks ECMA-119 specification, but version numbers are usually not
 1668  * used, so it should work on most systems. Use with caution.
 1669  * @param opts
 1670  *      The option set to be manipulated.
 1671  * @param omit
 1672  *      bit0= omit version number with ECMA-119 and Joliet
 1673  *      bit1= omit version number with Joliet alone (@since 0.6.30)
 1674  * @since 0.6.2
 1675  */
 1676 int iso_write_opts_set_omit_version_numbers(IsoWriteOpts *opts, int omit);
 1677 
 1678 /**
 1679  * Allow ISO-9660 directory hierarchy to be deeper than 8 levels.
 1680  * This breaks ECMA-119 specification. Use with caution.
 1681  *
 1682  * @since 0.6.2
 1683  */
 1684 int iso_write_opts_set_allow_deep_paths(IsoWriteOpts *opts, int allow);
 1685 
 1686 /**
 1687  * This call describes the directory where to store Rock Ridge relocated
 1688  * directories.
 1689  * If not iso_write_opts_set_allow_deep_paths(,1) is in effect, then it may
 1690  * become necessary to relocate directories so that no ECMA-119 file path
 1691  * has more than 8 components. These directories are grafted into either
 1692  * the root directory of the ISO image or into a dedicated relocation
 1693  * directory.
 1694  * For Rock Ridge, the relocated directories are linked forth and back to
 1695  * placeholders at their original positions in path level 8. Directories
 1696  * marked by Rock Ridge entry RE are to be considered artefacts of relocation
 1697  * and shall not be read into a Rock Ridge tree. Instead they are to be read
 1698  * via their placeholders and their links.
 1699  * For plain ECMA-119, the relocation directory and the relocated directories
 1700  * are just normal directories which contain normal files and directories.
 1701  * @param opts
 1702  *      The option set to be manipulated.
 1703  * @param name
 1704  *      The name of the relocation directory in the root directory. Do not
 1705  *      prepend "/". An empty name or NULL will direct relocated directories
 1706  *      into the root directory. This is the default.
 1707  *      If the given name does not exist in the root directory when
 1708  *      iso_image_create_burn_source() is called, and if there are directories
 1709  *      at path level 8, then directory /name will be created automatically.
 1710  *      The name given by this call will be compared with iso_node_get_name()
 1711  *      of the directories in the root directory, not with the final ECMA-119
 1712  *      names of those directories.
 1713  * @param flags
 1714  *      Bitfield for control purposes.
 1715  *      bit0= Mark the relocation directory by a Rock Ridge RE entry, if it
 1716  *            gets created during iso_image_create_burn_source(). This will
 1717  *            make it invisible for most Rock Ridge readers.
 1718  *      bit1= not settable via API (used internally)
 1719  * @return
 1720  *      1 success, < 0 error
 1721  * @since 1.2.2
 1722 */
 1723 int iso_write_opts_set_rr_reloc(IsoWriteOpts *opts, char *name, int flags);
 1724 
 1725 /**
 1726  * Allow path in the ISO-9660 tree to have more than 255 characters.
 1727  * This breaks ECMA-119 specification. Use with caution.
 1728  *
 1729  * @since 0.6.2
 1730  */
 1731 int iso_write_opts_set_allow_longer_paths(IsoWriteOpts *opts, int allow);
 1732 
 1733 /**
 1734  * Allow a single file or directory identifier to have up to 37 characters.
 1735  * This is larger than the 31 characters allowed by ISO level 2, and the
 1736  * extra space is taken from the version number, so this also forces
 1737  * omit_version_numbers.
 1738  * This breaks ECMA-119 specification and could lead to buffer overflow
 1739  * problems on old systems. Use with caution.
 1740  *
 1741  * @since 0.6.2
 1742  */
 1743 int iso_write_opts_set_max_37_char_filenames(IsoWriteOpts *opts, int allow);
 1744 
 1745 /**
 1746  * ISO-9660 forces filenames to have a ".", that separates file name from
 1747  * extension. libisofs adds it if original filename doesn't has one. Set
 1748  * this to 1 to prevent this behavior.
 1749  * This breaks ECMA-119 specification. Use with caution.
 1750  *
 1751  * @param opts
 1752  *      The option set to be manipulated.
 1753  * @param no
 1754  *      bit0= no forced dot with ECMA-119
 1755  *      bit1= no forced dot with Joliet (@since 0.6.30)
 1756  *
 1757  * @since 0.6.2
 1758  */
 1759 int iso_write_opts_set_no_force_dots(IsoWriteOpts *opts, int no);
 1760 
 1761 /**
 1762  * Allow lowercase characters in ISO-9660 filenames. By default, only
 1763  * uppercase characters, numbers and a few other characters are allowed.
 1764  * This breaks ECMA-119 specification. Use with caution.
 1765  * If lowercase is not allowed then those letters get mapped to uppercase
 1766  * letters.
 1767  *
 1768  * @since 0.6.2
 1769  */
 1770 int iso_write_opts_set_allow_lowercase(IsoWriteOpts *opts, int allow);
 1771 
 1772 /**
 1773  * Allow all 8-bit characters to appear on an ISO-9660 filename. Note
 1774  * that "/" and 0x0 characters are never allowed, even in RR names.
 1775  * This breaks ECMA-119 specification. Use with caution.
 1776  *
 1777  * @since 0.6.2
 1778  */
 1779 int iso_write_opts_set_allow_full_ascii(IsoWriteOpts *opts, int allow);
 1780 
 1781 /**
 1782  * If not iso_write_opts_set_allow_full_ascii() is set to 1:
 1783  * Allow all 7-bit characters that would be allowed by allow_full_ascii, but
 1784  * map lowercase to uppercase if iso_write_opts_set_allow_lowercase()
 1785  * is not set to 1.
 1786  * @param opts    
 1787  *      The option set to be manipulated.
 1788  * @param allow
 1789  *      If not zero, then allow what is described above.
 1790  *
 1791  * @since 1.2.2
 1792  */
 1793 int iso_write_opts_set_allow_7bit_ascii(IsoWriteOpts *opts, int allow);
 1794 
 1795 /**
 1796  * Allow all characters to be part of Volume and Volset identifiers on
 1797  * the Primary Volume Descriptor. This breaks ISO-9660 constraints, but
 1798  * should work on modern systems.
 1799  *
 1800  * @since 0.6.2
 1801  */
 1802 int iso_write_opts_set_relaxed_vol_atts(IsoWriteOpts *opts, int allow);
 1803 
 1804 /**
 1805  * Allow paths in the Joliet tree to have more than 240 characters.
 1806  * This breaks Joliet specification. Use with caution.
 1807  *
 1808  * @since 0.6.2
 1809  */
 1810 int iso_write_opts_set_joliet_longer_paths(IsoWriteOpts *opts, int allow);
 1811 
 1812 /**
 1813  * Allow leaf names in the Joliet tree to have up to 103 characters.
 1814  * Normal limit is 64. 
 1815  * This breaks Joliet specification. Use with caution.
 1816  *
 1817  * @since 1.0.6
 1818  */
 1819 int iso_write_opts_set_joliet_long_names(IsoWriteOpts *opts, int allow);
 1820 
 1821 /**
 1822  * Use character set UTF-16BE with Joliet, which is a superset of the
 1823  * actually prescribed character set UCS-2.
 1824  * This breaks Joliet specification with exotic characters which would
 1825  * elsewise be mapped to underscore '_'. Use with caution.
 1826  *
 1827  * @since 1.3.6
 1828  */
 1829 int iso_write_opts_set_joliet_utf16(IsoWriteOpts *opts, int allow);
 1830 
 1831 /**
 1832  * Write Rock Ridge info as of specification RRIP-1.10 rather than RRIP-1.12:
 1833  * signature "RRIP_1991A" rather than "IEEE_1282", field PX without file
 1834  * serial number.
 1835  *
 1836  * @since 0.6.12
 1837  */
 1838 int iso_write_opts_set_rrip_version_1_10(IsoWriteOpts *opts, int oldvers);
 1839 
 1840 /**
 1841  * Write field PX with file serial number (i.e. inode number) even if
 1842  * iso_write_opts_set_rrip_version_1_10(,1) is in effect.
 1843  * This clearly violates the RRIP-1.10 specs. But it is done by mkisofs since
 1844  * a while and no widespread protest is visible in the web.
 1845  * If this option is not enabled, then iso_write_opts_set_hardlinks() will
 1846  * only have an effect with iso_write_opts_set_rrip_version_1_10(,0).
 1847  * 
 1848  * @since 0.6.20
 1849  */
 1850 int iso_write_opts_set_rrip_1_10_px_ino(IsoWriteOpts *opts, int enable);
 1851 
 1852 /**
 1853  * Write AAIP as extension according to SUSP 1.10 rather than SUSP 1.12.
 1854  * I.e. without announcing it by an ER field and thus without the need
 1855  * to precede the RRIP fields and the AAIP field by ES fields.
 1856  * This saves 5 to 10 bytes per file and might avoid problems with readers
 1857  * which dislike ER fields other than the ones for RRIP.
 1858  * On the other hand, SUSP 1.12 frowns on such unannounced extensions 
 1859  * and prescribes ER and ES. It does this since the year 1994.
 1860  *
 1861  * In effect only if above iso_write_opts_set_aaip() enables writing of AAIP.
 1862  *
 1863  * @since 0.6.14
 1864  */
 1865 int iso_write_opts_set_aaip_susp_1_10(IsoWriteOpts *opts, int oldvers);
 1866 
 1867 /**
 1868  * Store as ECMA-119 Directory Record timestamp the mtime of the source node
 1869  * rather than the image creation time.
 1870  * If storing of mtime is enabled, then the settings of
 1871  * iso_write_opts_set_replace_timestamps() apply. (replace==1 will revoke,
 1872  * replace==2 will override mtime by iso_write_opts_set_default_timestamp().
 1873  *
 1874  * Since version 1.2.0 this may apply also to Joliet and ISO 9660:1999. To
 1875  * reduce the probability of unwanted behavior changes between pre-1.2.0 and
 1876  * post-1.2.0, the bits for Joliet and ISO 9660:1999 also enable ECMA-119.
 1877  * The hopefully unlikely bit14 may then be used to disable mtime for ECMA-119.
 1878  *
 1879  * To enable mtime for all three directory trees, submit 7.
 1880  * To disable this feature completely, submit 0.
 1881  *
 1882  * @param opts    
 1883  *      The option set to be manipulated.
 1884  * @param allow
 1885  *      If this parameter is negative, then mtime is enabled only for ECMA-119.
 1886  *      With positive numbers, the parameter is interpreted as bit field :
 1887  *          bit0= enable mtime for ECMA-119 
 1888  *          bit1= enable mtime for Joliet and ECMA-119
 1889  *          bit2= enable mtime for ISO 9660:1999 and ECMA-119
 1890  *          bit14= disable mtime for ECMA-119 although some of the other bits
 1891  *                 would enable it
 1892  *          @since 1.2.0
 1893  *      Before version 1.2.0 this applied only to ECMA-119 :
 1894  *          0 stored image creation time in ECMA-119 tree.
 1895  *          Any other value caused storing of mtime.
 1896  *          Joliet and ISO 9660:1999 always stored the image creation time.
 1897  * @since 0.6.12
 1898  */
 1899 int iso_write_opts_set_dir_rec_mtime(IsoWriteOpts *opts, int allow);
 1900 
 1901 /**
 1902  * Whether to sort files based on their weight.
 1903  *
 1904  * @see iso_node_set_sort_weight
 1905  * @since 0.6.2
 1906  */
 1907 int iso_write_opts_set_sort_files(IsoWriteOpts *opts, int sort);
 1908 
 1909 /**
 1910  * Whether to compute and record MD5 checksums for the whole session and/or
 1911  * for each single IsoFile object. The checksums represent the data as they
 1912  * were written into the image output stream, not necessarily as they were
 1913  * on hard disk at any point of time.
 1914  * See also calls iso_image_get_session_md5() and iso_file_get_md5().
 1915  * @param opts
 1916  *      The option set to be manipulated.
 1917  * @param session
 1918  *      If bit0 set: Compute session checksum
 1919  * @param files
 1920  *      If bit0 set: Compute a checksum for each single IsoFile object which
 1921  *                   gets its data content written into the session. Copy
 1922  *                   checksums from files which keep their data in older
 1923  *                   sessions.
 1924  *      If bit1 set: Check content stability (only with bit0). I.e.  before
 1925  *                   writing the file content into to image stream, read it
 1926  *                   once and compute a MD5. Do a second reading for writing
 1927  *                   into the image stream. Afterwards compare both MD5 and
 1928  *                   issue a MISHAP event ISO_MD5_STREAM_CHANGE if they do not
 1929  *                   match.
 1930  *                   Such a mismatch indicates content changes between the
 1931  *                   time point when the first MD5 reading started and the
 1932  *                   time point when the last block was read for writing.
 1933  *                   So there is high risk that the image stream was fed from
 1934  *                   changing and possibly inconsistent file content.
 1935  *                   
 1936  * @since 0.6.22
 1937  */
 1938 int iso_write_opts_set_record_md5(IsoWriteOpts *opts, int session, int files);
 1939 
 1940 /**
 1941  * Set the parameters "name" and "timestamp" for a scdbackup checksum tag.
 1942  * It will be appended to the libisofs session tag if the image starts at
 1943  * LBA 0 (see iso_write_opts_set_ms_block()). The scdbackup tag can be used
 1944  * to verify the image by command scdbackup_verify device -auto_end.
 1945  * See scdbackup/README appendix VERIFY for its inner details.
 1946  *
 1947  * @param opts
 1948  *      The option set to be manipulated.
 1949  * @param name
 1950  *      A word of up to 80 characters. Typically volno_totalno telling
 1951  *      that this is volume volno of a total of totalno volumes.
 1952  * @param timestamp
 1953  *      A string of 13 characters YYMMDD.hhmmss (e.g. A90831.190324).
 1954  *      A9 = 2009, B0 = 2010, B1 = 2011, ... C0 = 2020, ...
 1955  * @param tag_written
 1956  *      Either NULL or the address of an array with at least 512 characters.
 1957  *      In the latter case the eventually produced scdbackup tag will be
 1958  *      copied to this array when the image gets written. This call sets
 1959  *      scdbackup_tag_written[0] = 0 to mark its preliminary invalidity.
 1960  * @return
 1961  *      1 indicates success, <0 is error
 1962  *
 1963  * @since 0.6.24
 1964  */
 1965 int iso_write_opts_set_scdbackup_tag(IsoWriteOpts *opts,
 1966                                      char *name, char *timestamp,
 1967                                      char *tag_written);
 1968 
 1969 /**
 1970  * Whether to set default values for files and directory permissions, gid and
 1971  * uid. All these take one of three values: 0, 1 or 2.
 1972  *
 1973  * If 0, the corresponding attribute will be kept as set in the IsoNode.
 1974  * Unless you have changed it, it corresponds to the value on disc, so it
 1975  * is suitable for backup purposes. If set to 1, the corresponding attrib.
 1976  * will be changed by a default suitable value. Finally, if you set it to
 1977  * 2, the attrib. will be changed with the value specified by the functioins
 1978  * below. Note that for mode attributes, only the permissions are set, the
 1979  * file type remains unchanged.
 1980  *
 1981  * @see iso_write_opts_set_default_dir_mode
 1982  * @see iso_write_opts_set_default_file_mode
 1983  * @see iso_write_opts_set_default_uid
 1984  * @see iso_write_opts_set_default_gid
 1985  * @since 0.6.2
 1986  */
 1987 int iso_write_opts_set_replace_mode(IsoWriteOpts *opts, int dir_mode,
 1988                                     int file_mode, int uid, int gid);
 1989 
 1990 /**
 1991  * Set the mode to use on dirs when you set the replace_mode of dirs to 2.
 1992  *
 1993  * @see iso_write_opts_set_replace_mode
 1994  * @since 0.6.2
 1995  */
 1996 int iso_write_opts_set_default_dir_mode(IsoWriteOpts *opts, mode_t dir_mode);
 1997 
 1998 /**
 1999  * Set the mode to use on files when you set the replace_mode of files to 2.
 2000  *
 2001  * @see iso_write_opts_set_replace_mode
 2002  * @since 0.6.2
 2003  */
 2004 int iso_write_opts_set_default_file_mode(IsoWriteOpts *opts, mode_t file_mode);
 2005 
 2006 /**
 2007  * Set the uid to use when you set the replace_uid to 2.
 2008  *
 2009  * @see iso_write_opts_set_replace_mode
 2010  * @since 0.6.2
 2011  */
 2012 int iso_write_opts_set_default_uid(IsoWriteOpts *opts, uid_t uid);
 2013 
 2014 /**
 2015  * Set the gid to use when you set the replace_gid to 2.
 2016  *
 2017  * @see iso_write_opts_set_replace_mode
 2018  * @since 0.6.2
 2019  */
 2020 int iso_write_opts_set_default_gid(IsoWriteOpts *opts, gid_t gid);
 2021 
 2022 /**
 2023  * 0 to use IsoNode timestamps, 1 to use recording time, 2 to use
 2024  * values from timestamp field. This applies to the timestamps of Rock Ridge
 2025  * and if the use of mtime is enabled by iso_write_opts_set_dir_rec_mtime().
 2026  * In the latter case, value 1 will revoke the recording of mtime, value
 2027  * 2 will override mtime by iso_write_opts_set_default_timestamp().
 2028  *
 2029  * @see iso_write_opts_set_default_timestamp
 2030  * @since 0.6.2
 2031  */
 2032 int iso_write_opts_set_replace_timestamps(IsoWriteOpts *opts, int replace);
 2033 
 2034 /**
 2035  * Set the timestamp to use when you set the replace_timestamps to 2.
 2036  *
 2037  * @see iso_write_opts_set_replace_timestamps
 2038  * @since 0.6.2
 2039  */
 2040 int iso_write_opts_set_default_timestamp(IsoWriteOpts *opts, time_t timestamp);
 2041 
 2042 /**
 2043  * Whether to always record timestamps in GMT.
 2044  *
 2045  * By default, libisofs stores local time information on image. You can set
 2046  * this to always store timestamps converted to GMT. This prevents any
 2047  * discrimination of the timezone of the image preparer by the image reader.
 2048  *
 2049  * It is useful if you want to hide your timezone, or you live in a timezone
 2050  * that can't be represented in ECMA-119. These are timezones with an offset
 2051  * from GMT greater than +13 hours, lower than -12 hours, or not a multiple
 2052  * of 15 minutes.
 2053  * Negative timezones (west of GMT) can trigger bugs in some operating systems
 2054  * which typically appear in mounted ISO images as if the timezone shift from
 2055  * GMT was applied twice (e.g. in New York 22:36 becomes 17:36).
 2056  *
 2057  * @since 0.6.2
 2058  */
 2059 int iso_write_opts_set_always_gmt(IsoWriteOpts *opts, int gmt);
 2060 
 2061 /**
 2062  * Set the charset to use for the RR names of the files that will be created
 2063  * on the image.
 2064  * NULL to use default charset, that is the locale charset.
 2065  * You can obtain the list of charsets supported on your system executing
 2066  * "iconv -l" in a shell.
 2067  *
 2068  * @since 0.6.2
 2069  */
 2070 int iso_write_opts_set_output_charset(IsoWriteOpts *opts, const char *charset);
 2071 
 2072 /**
 2073  * Set the type of image creation in case there was already an existing
 2074  * image imported. Libisofs supports two types of creation:
 2075  * stand-alone and appended.
 2076  *
 2077  * A stand-alone image is an image that does not need the old image any more
 2078  * for being mounted by the operating system or imported by libisofs. It may
 2079  * be written beginning with byte 0 of optical media or disk file objects. 
 2080  * There will be no distinction between files from the old image and those
 2081  * which have been added by the new image generation.
 2082  *
 2083  * On the other side, an appended image is not self contained. It may refer
 2084  * to files that stay stored in the imported existing image.
 2085  * This usage model is inspired by CD multi-session. It demands that the
 2086  * appended image is finally written to the same media or disk file
 2087  * as the imported image at an address behind the end of that imported image.
 2088  * The exact address may depend on media peculiarities and thus has to be
 2089  * announced by the application via iso_write_opts_set_ms_block().
 2090  * The real address where the data will be written is under control of the
 2091  * consumer of the struct burn_source which takes the output of libisofs
 2092  * image generation. It may be the one announced to libisofs or an intermediate
 2093  * one. Nevertheless, the image will be readable only at the announced address.
 2094  *
 2095  * If you have not imported a previous image by iso_image_import(), then the
 2096  * image will always be a stand-alone image, as there is no previous data to
 2097  * refer to. 
 2098  *
 2099  * @param opts
 2100  *      The option set to be manipulated.
 2101  * @param append
 2102  *      1 to create an appended image, 0 for an stand-alone one.
 2103  *
 2104  * @since 0.6.2
 2105  */
 2106 int iso_write_opts_set_appendable(IsoWriteOpts *opts, int append);
 2107 
 2108 /**
 2109  * Set the start block of the image. It is supposed to be the lba where the
 2110  * first block of the image will be written on disc. All references inside the
 2111  * ISO image will take this into account, thus providing a mountable image.
 2112  *
 2113  * For appendable images, that are written to a new session, you should
 2114  * pass here the lba of the next writable address on disc.
 2115  *
 2116  * In stand alone images this is usually 0. However, you may want to
 2117  * provide a different ms_block if you don't plan to burn the image in the
 2118  * first session on disc, such as in some CD-Extra disc whether the data
 2119  * image is written in a new session after some audio tracks.
 2120  *
 2121  * @since 0.6.2
 2122  */
 2123 int iso_write_opts_set_ms_block(IsoWriteOpts *opts, uint32_t ms_block);
 2124 
 2125 /**
 2126  * Sets the buffer where to store the descriptors which shall be written
 2127  * at the beginning of an overwritable media to point to the newly written
 2128  * image.
 2129  * This is needed if the write start address of the image is not 0.
 2130  * In this case the first 64 KiB of the media have to be overwritten
 2131  * by the buffer content after the session was written and the buffer
 2132  * was updated by libisofs. Otherwise the new session would not be
 2133  * found by operating system function mount() or by libisoburn.
 2134  * (One could still mount that session if its start address is known.)
 2135  *
 2136  * If you do not need this information, for example because you are creating a
 2137  * new image for LBA 0 or because you will create an image for a true
 2138  * multisession media, just do not use this call or set buffer to NULL.
 2139  *
 2140  * Use cases:
 2141  *
 2142  * - Together with iso_write_opts_set_appendable(opts, 1) the buffer serves
 2143  *   for the growing of an image as done in growisofs by Andy Polyakov.
 2144  *   This allows appending of a new session to non-multisession media, such
 2145  *   as DVD+RW. The new session will refer to the data of previous sessions
 2146  *   on the same media.
 2147  *   libisoburn emulates multisession appendability on overwritable media
 2148  *   and disk files by performing this use case.
 2149  *
 2150  * - Together with iso_write_opts_set_appendable(opts, 0) the buffer allows
 2151  *   to write the first session on overwritable media to start addresses
 2152  *   other than 0.
 2153  *   This address must not be smaller than 32 blocks plus the eventual
 2154  *   partition offset as defined by iso_write_opts_set_part_offset().
 2155  *   libisoburn in most cases writes the first session on overwritable media
 2156  *   and disk files to LBA (32 + partition_offset) in order to preserve its
 2157  *   descriptors from the subsequent overwriting by the descriptor buffer of
 2158  *   later sessions.
 2159  *
 2160  * @param opts
 2161  *      The option set to be manipulated.
 2162  * @param overwrite
 2163  *      When not NULL, it should point to at least 64KiB of memory, where
 2164  *      libisofs will install the contents that shall be written at the
 2165  *      beginning of overwritable media.
 2166  *      You should initialize the buffer either with 0s, or with the contents
 2167  *      of the first 32 blocks of the image you are growing. In most cases,
 2168  *      0 is good enough.
 2169  *      IMPORTANT: If you use iso_write_opts_set_part_offset() then the
 2170  *                 overwrite buffer must be larger by the offset defined there.
 2171  *
 2172  * @since 0.6.2
 2173  */
 2174 int iso_write_opts_set_overwrite_buf(IsoWriteOpts *opts, uint8_t *overwrite);
 2175 
 2176 /**
 2177  * Set the size, in number of blocks, of the ring buffer used between the
 2178  * writer thread and the burn_source. You have to provide at least a 32
 2179  * blocks buffer. Default value is set to 2MB, if that is ok for you, you
 2180  * don't need to call this function.
 2181  *
 2182  * @since 0.6.2
 2183  */
 2184 int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size);
 2185 
 2186 /*
 2187  * Attach 32 kB of binary data which shall get written to the first 32 kB 
 2188  * of the ISO image, the ECMA-119 System Area. This space is intended for
 2189  * system dependent boot software, e.g. a Master Boot Record which allows to
 2190  * boot from USB sticks or hard disks. ECMA-119 makes no own assumptions or
 2191  * prescriptions about the byte content.
 2192  *
 2193  * If system area data are given or options bit0 is set, then bit1 of
 2194  * el_torito_set_isolinux_options() is automatically disabled.
 2195  *
 2196  * @param opts
 2197  *      The option set to be manipulated.
 2198  * @param data
 2199  *        Either NULL or 32 kB of data. Do not submit less bytes !
 2200  * @param options
 2201  *        Can cause manipulations of submitted data before they get written:
 2202  *        bit0= Only with System area type 0 = MBR
 2203  *              Apply a --protective-msdos-label as of grub-mkisofs.
 2204  *              This means to patch bytes 446 to 512 of the system area so
 2205  *              that one partition is defined which begins at the second
 2206  *              512-byte block of the image and ends where the image ends.
 2207  *              This works with and without system_area_data.
 2208  *              Modern GRUB2 system areas get also treated by bit14. See below.
 2209  *        bit1= Only with System area type 0 = MBR
 2210  *              Apply isohybrid MBR patching to the system area.
 2211  *              This works only with system area data from SYSLINUX plus an
 2212  *              ISOLINUX boot image as first submitted boot image 
 2213  *              (see iso_image_set_boot_image()) and only if not bit0 is set.
 2214  *        bit2-7= System area type
 2215  *              0= with bit0 or bit1: MBR
 2216  *                 else: type depends on bits bit10-13: System area sub type
 2217  *              1= MIPS Big Endian Volume Header
 2218  *                 @since 0.6.38
 2219  *                 Submit up to 15 MIPS Big Endian boot files by
 2220  *                 iso_image_add_mips_boot_file().
 2221  *                 This will overwrite the first 512 bytes of the submitted
 2222  *                 data.
 2223  *              2= DEC Boot Block for MIPS Little Endian
 2224  *                 @since 0.6.38
 2225  *                 The first boot file submitted by
 2226  *                 iso_image_add_mips_boot_file() will be activated.
 2227  *                 This will overwrite the first 512 bytes of the submitted
 2228  *                 data.
 2229  *              3= SUN Disk Label for SUN SPARC
 2230  *                 @since 0.6.40
 2231  *                 Submit up to 7 SPARC boot images by
 2232  *                 iso_write_opts_set_partition_img() for partition numbers 2
 2233  *                 to 8.
 2234  *                 This will overwrite the first 512 bytes of the submitted
 2235  *                 data.
 2236  *              4= HP-PA PALO boot sector version 4 for HP PA-RISC
 2237  *                 @since 1.3.8
 2238  *                 Suitable for older PALO of e.g. Debian 4 and 5. 
 2239  *                 Submit all five parameters of iso_image_set_hppa_palo():
 2240  *                   cmdline, bootloader, kernel_32, kernel_64, ramdisk
 2241  *              5= HP-PA PALO boot sector version 5 for HP PA-RISC
 2242  *                 @since 1.3.8
 2243  *                 Suitable for newer PALO, where PALOHDRVERSION in
 2244  *                 lib/common.h is defined as 5.
 2245  *                 Submit all five parameters of iso_image_set_hppa_palo():
 2246  *                   cmdline, bootloader, kernel_32, kernel_64, ramdisk
 2247  *              6= DEC Alpha SRM boot sector
 2248  *                 @since 1.4.0
 2249  *                 Submit bootloader path in ISO by iso_image_set_alpha_boot().
 2250  *        bit8-9= Only with System area type 0 = MBR
 2251  *              @since 1.0.4
 2252  *              Cylinder alignment mode eventually pads the image to make it
 2253  *              end at a cylinder boundary.
 2254  *                0 = auto (align if bit1)
 2255  *                1 = always align to cylinder boundary
 2256  *                2 = never align to cylinder boundary
 2257  *                3 = always align, additionally pad up and align partitions
 2258  *                    which were appended by iso_write_opts_set_partition_img()
 2259  *                    @since 1.2.6
 2260  *        bit10-13= System area sub type
 2261  *              @since 1.2.4
 2262  *              With type 0:
 2263  *                if options bit0 ... MBR with partition start at block 1
 2264  *                if options bit1 ... ISOLINUX isohybrid MBR
 2265  *                else:
 2266  *                0 = no particular sub type, use unaltered
 2267  *                1 = CHRP: A single MBR partition of type 0x96 covers the
 2268  *                          ISO image. Not compatible with any other feature
 2269  *                          which needs to have own MBR partition entries.
 2270  *                2 = generic MBR @since 1.3.8
 2271  *        bit14= Only with System area type 0 = MBR
 2272  *              GRUB2 boot provisions:
 2273  *              @since 1.3.0
 2274  *              Patch system area at byte 0x1b0 to 0x1b7 with
 2275  *              (512-block address + 4)  of the first boot image file.
 2276  *              Little-endian 8-byte.
 2277  *              Is normally combined with options bit0.
 2278  *              Will not be in effect if options bit1 is set.
 2279  *        bit15= Only with System area type MBR but not with CHRP
 2280  *              Enforce MBR "bootable/active" flag. In worst case by dummy
 2281  *              partition of type 0x00 which occupies block 0.
 2282  *              @since 1.4.4
 2283  * @param flag
 2284  *        bit0 = invalidate any attached system area data. Same as data == NULL
 2285  *               (This re-activates eventually loaded image System Area data.
 2286  *                To erase those, submit 32 kB of zeros without flag bit0.)
 2287  *        bit1 = keep data unaltered
 2288  *        bit2 = keep options unaltered
 2289  * @return
 2290  *      ISO_SUCCESS or error
 2291  * @since 0.6.30
 2292  */
 2293 int iso_write_opts_set_system_area(IsoWriteOpts *opts, char data[32768],
 2294                                    int options, int flag);
 2295 
 2296 /**
 2297  * Set a name for the system area. This setting is ignored unless system area
 2298  * type 3 "SUN Disk Label" is in effect by iso_write_opts_set_system_area().
 2299  * In this case it will replace the default text at the start of the image:
 2300  *   "CD-ROM Disc with Sun sparc boot created by libisofs"
 2301  *
 2302  * @param opts
 2303  *      The option set to be manipulated.
 2304  * @param label
 2305  *      A text of up to 128 characters.
 2306  * @return
 2307  *      ISO_SUCCESS or error
 2308  * @since 0.6.40
 2309 */
 2310 int iso_write_opts_set_disc_label(IsoWriteOpts *opts, char *label);
 2311 
 2312 /**
 2313  * Explicitly set the four timestamps of the emerging Primary Volume
 2314  * Descriptor and in the volume descriptors of Joliet and ISO 9660:1999,
 2315  * if those are to be generated.
 2316  * Default with all parameters is 0.
 2317  *
 2318  * ECMA-119 defines them as:
 2319  * @param opts
 2320  *        The option set to be manipulated.
 2321  * @param vol_creation_time
 2322  *        When "the information in the volume was created."
 2323  *        A value of 0 means that the timepoint of write start is to be used.
 2324  * @param vol_modification_time
 2325  *        When "the information in the volume was last modified."
 2326  *        A value of 0 means that the timepoint of write start is to be used.
 2327  * @param vol_expiration_time
 2328  *        When "the information in the volume may be regarded as obsolete."
 2329  *        A value of 0 means that the information never shall expire.
 2330  * @param vol_effective_time
 2331  *        When "the information in the volume may be used."
 2332  *        A value of 0 means that not such retention is intended.
 2333  * @param vol_uuid
 2334  *        If this text is not empty, then it overrides vol_creation_time and
 2335  *        vol_modification_time by copying the first 16 decimal digits from
 2336  *        uuid, eventually padding up with decimal '1', and writing a NUL-byte
 2337  *        as timezone.
 2338  *        Other than with vol_*_time the resulting string in the ISO image
 2339  *        is fully predictable and free of timezone pitfalls.
 2340  *        It should express a reasonable time in form  YYYYMMDDhhmmsscc.
 2341  *        The timezone will always be recorded as GMT.
 2342  *        E.g.:  "2010040711405800" = 7 Apr 2010 11:40:58 (+0 centiseconds)
 2343  * @return
 2344  *        ISO_SUCCESS or error
 2345  *
 2346  * @since 0.6.30
 2347  */
 2348 int iso_write_opts_set_pvd_times(IsoWriteOpts *opts,
 2349                         time_t vol_creation_time, time_t vol_modification_time,
 2350                         time_t vol_expiration_time, time_t vol_effective_time,
 2351                         char *vol_uuid);
 2352 
 2353 
 2354 /*
 2355  * Control production of a second set of volume descriptors (superblock)
 2356  * and directory trees, together with a partition table in the MBR where the
 2357  * first partition has non-zero start address and the others are zeroed.
 2358  * The first partition stretches to the end of the whole ISO image.
 2359  * The additional volume descriptor set and trees will allow to mount the
 2360  * ISO image at the start of the first partition, while it is still possible
 2361  * to mount it via the normal first volume descriptor set and tree at the
 2362  * start of the image or storage device.
 2363  * This makes few sense on optical media. But on USB sticks it creates a
 2364  * conventional partition table which makes it mountable on e.g. Linux via
 2365  * /dev/sdb and /dev/sdb1 alike.
 2366  * IMPORTANT: When submitting memory by iso_write_opts_set_overwrite_buf()
 2367  *            then its size must be at least 64 KiB + partition offset. 
 2368  *
 2369  * @param opts
 2370  *        The option set to be manipulated.
 2371  * @param block_offset_2k
 2372  *        The offset of the partition start relative to device start.
 2373  *        This is counted in 2 kB blocks. The partition table will show the
 2374  *        according number of 512 byte sectors.
 2375  *        Default is 0 which causes no special partition table preparations.
 2376  *        If it is not 0 then it must not be smaller than 16.
 2377  * @param secs_512_per_head
 2378  *        Number of 512 byte sectors per head. 1 to 63. 0=automatic.
 2379  * @param heads_per_cyl
 2380  *        Number of heads per cylinder. 1 to 255. 0=automatic.
 2381  * @return
 2382  *        ISO_SUCCESS or error
 2383  *
 2384  * @since 0.6.36
 2385  */
 2386 int iso_write_opts_set_part_offset(IsoWriteOpts *opts,
 2387                                    uint32_t block_offset_2k,
 2388                                    int secs_512_per_head, int heads_per_cyl);
 2389 
 2390 
 2391 /** The minimum version of libjte to be used with this version of libisofs
 2392     at compile time. The use of libjte is optional and depends on configure
 2393     tests. It can be prevented by ./configure option --disable-libjte .
 2394     @since 0.6.38
 2395 */
 2396 #define iso_libjte_req_major 2
 2397 #define iso_libjte_req_minor 0
 2398 #define iso_libjte_req_micro 0
 2399 
 2400 /** 
 2401  * Associate a libjte environment object to the upcoming write run.
 2402  * libjte implements Jigdo Template Extraction as of Steve McIntyre and
 2403  * Richard Atterer.
 2404  * The call will fail if no libjte support was enabled at compile time.
 2405  * @param opts
 2406  *        The option set to be manipulated.
 2407  * @param libjte_handle
 2408  *        Pointer to a struct libjte_env e.g. created by libjte_new().
 2409  *        It must stay existent from the start of image generation by
 2410  *        iso_image_create_burn_source() until the write thread has ended.
 2411  *        This can be inquired by iso_image_generator_is_running().
 2412  *        In order to keep the libisofs API identical with and without
 2413  *        libjte support the parameter type is (void *).
 2414  * @return
 2415  *        ISO_SUCCESS or error
 2416  *
 2417  * @since 0.6.38
 2418 */
 2419 int iso_write_opts_attach_jte(IsoWriteOpts *opts, void *libjte_handle);
 2420 
 2421 /**
 2422  * Remove eventual association to a libjte environment handle.
 2423  * The call will fail if no libjte support was enabled at compile time.
 2424  * @param opts
 2425  *        The option set to be manipulated.
 2426  * @param libjte_handle
 2427  *        If not submitted as NULL, this will return the previously set
 2428  *        libjte handle. 
 2429  * @return
 2430  *        ISO_SUCCESS or error
 2431  *
 2432  * @since 0.6.38
 2433 */
 2434 int iso_write_opts_detach_jte(IsoWriteOpts *opts, void **libjte_handle);
 2435 
 2436 
 2437 /**
 2438  * Cause a number of blocks with zero bytes to be written after the payload
 2439  * data, but before the eventual checksum data. Unlike libburn tail padding,
 2440  * these blocks are counted as part of the image and covered by eventual
 2441  * image checksums.
 2442  * A reason for such padding can be the wish to prevent the Linux read-ahead
 2443  * bug by sacrificial data which still belong to image and Jigdo template.
 2444  * Normally such padding would be the job of the burn program which should know
 2445  * that it is needed with CD write type TAO if Linux read(2) shall be able
 2446  * to read all payload blocks.
 2447  * 150 blocks = 300 kB is the traditional sacrifice to the Linux kernel.
 2448  * @param opts
 2449  *        The option set to be manipulated.
 2450  * @param num_blocks
 2451  *        Number of extra 2 kB blocks to be written.
 2452  * @return
 2453  *        ISO_SUCCESS or error
 2454  *
 2455  * @since 0.6.38
 2456  */
 2457 int iso_write_opts_set_tail_blocks(IsoWriteOpts *opts, uint32_t num_blocks);
 2458 
 2459 
 2460 /**
 2461  * The libisofs interval reader is used internally and offered by libisofs API:
 2462  * @since 1.4.0
 2463  * The functions iso_write_opts_set_prep_img(), iso_write_opts_set_efi_bootp(),
 2464  * and iso_write_opts_set_partition_img() accept with their flag bit0 an
 2465  * interval reader description string instead of a disk path.
 2466  * The API calls are iso_interval_reader_new(), iso_interval_reader_read(),
 2467  * and iso_interval_reader_destroy().
 2468  * The data may be cut out and optionally partly zeroized.
 2469  *
 2470  * An interval reader description string has the form:
 2471  *   $flags:$interval:$zeroizers:$source
 2472  * The component $flags modifies the further interpretation:
 2473  *  "local_fs" ....... demands to read from a file depicted by the path in
 2474  *                     $source.
 2475  *  "imported_iso" ... demands to read from the IsoDataSource object that was
 2476  *                     used with iso_image_import() when
 2477  *                     iso_read_opts_keep_import_src() was enabled.
 2478  *                     The text in $source is ignored.
 2479  *                     The application has to ensure that reading from the
 2480  *                     import source does not disturb production of the new
 2481  *                     ISO session. Especially this would be the case if the
 2482  *                     import source is the same libburn drive with a
 2483  *                     sequential optical medium to which the new session shall
 2484  *                     get burned.
 2485  * The component $interval consists of two byte address numbers separated
 2486  * by a "-" character. E.g. "0-429" means to read bytes 0 to 429.
 2487  * The component $zeroizers consists of zero or more comma separated strings.
 2488  * They define which part of the read data to zeroize. Byte number 0 means
 2489  * the byte read from the $interval start address.
 2490  * Each string may be either
 2491  *  "zero_mbrpt" ..... demands to zeroize bytes 446 to 509 of the read data if
 2492  *                     bytes 510 and 511 bear the MBR signature 0x55 0xaa.
 2493  *  "zero_gpt" ....... demands to check for a GPT header in bytes 512 to 1023,
 2494  *                     to zeroize it and its partition table blocks.
 2495  *  "zero_apm" ....... demands to check for an APM block 0 and to zeroize
 2496  *                     its partition table blocks. But not the block 0 itself,
 2497  *                     because it could be actually MBR x86 machine code.
 2498  *  $zero_start"-"$zero_end ... demands to zeroize the read-in bytes beginning
 2499  *                     with number $zero_start and ending after $zero_end. 
 2500  * The component $source is the file path with "local_fs", and ignored with
 2501  * "imported_iso".
 2502  * Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning
 2503  * multiplication by {1024, 1024k, 1024m, 1024g, 2048, 512}. A scaled value
 2504  * as end number depicts the last byte of the scaled range.
 2505  * E.g. "0d-0d" is "0-511".
 2506  * Examples:
 2507  *    "local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso"
 2508  *    "imported_iso:45056d-47103d::"
 2509  */
 2510 struct iso_interval_reader;
 2511 
 2512 /**
 2513  * Create an interval reader object.
 2514  *
 2515  * @param img
 2516  *        The IsoImage object which can provide the "imported_iso" data source.
 2517  * @param path
 2518  *        The interval reader description string. See above.
 2519  * @param ivr
 2520  *        Returns in case of success a pointer to the created object.
 2521  *        Dispose it by iso_interval_reader_destroy() when no longer needed.
 2522  * @param byte_count
 2523  *        Returns in case of success the number of bytes in the interval.
 2524  * @param flag
 2525  *        bit0= tolerate (src == NULL) with "imported_iso".
 2526  *              (Will immediately cause eof of interval input.)
 2527  * @return
 2528  *        ISO_SUCCESS or error (which is < 0)
 2529  *
 2530  * @since 1.4.0
 2531  */
 2532 int iso_interval_reader_new(IsoImage *img, char *path,
 2533                             struct iso_interval_reader **ivr,
 2534                             off_t *byte_count, int flag);
 2535 
 2536 /**
 2537  * Dispose an interval reader object.
 2538  *
 2539  * @param ivr
 2540  *        The reader object to be disposed. *ivr will be set to NULL.
 2541  * @param flag
 2542  *        Unused yet. Submit 0.
 2543  * @return
 2544  *        ISO_SUCCESS or error (which is < 0)
 2545  * 
 2546  * @since 1.4.0
 2547  */ 
 2548 int iso_interval_reader_destroy(struct iso_interval_reader **ivr, int flag);
 2549 
 2550 /**
 2551  * Read the next block of 2048 bytes from an interval reader object.
 2552  * If end-of-input happens, the interval will get filled up with 0 bytes.
 2553  *
 2554  * @param ivr
 2555  *        The object to read from.
 2556  * @param buf
 2557  *        Pointer to memory for filling in at least 2048 bytes.
 2558  * @param buf_fill
 2559  *        Will in case of success return the number of valid bytes.
 2560  *        If this is smaller than 2048, then end-of-interval has occurred.
 2561  * @param flag
 2562  *        Unused yet. Submit 0.
 2563  * @return
 2564  *        ISO_SUCCESS if data were read, 0 if not, < 0 if error
 2565  *
 2566  * @since 1.4.0
 2567  */
 2568 int iso_interval_reader_read(struct iso_interval_reader *ivr, uint8_t *buf,
 2569                              int *buf_fill, int flag);
 2570 
 2571 
 2572 /**
 2573  * Copy a data file from the local filesystem into the emerging ISO image.
 2574  * Mark it by an MBR partition entry as PreP partition and also cause
 2575  * protective MBR partition entries before and after this partition.
 2576  * Vladimir Serbinenko stated aboy PreP = PowerPC Reference Platform :
 2577  *   "PreP [...] refers mainly to IBM hardware. PreP boot is a partition
 2578  *    containing only raw ELF and having type 0x41."
 2579  *
 2580  * This feature is only combinable with system area type 0
 2581  * and currently not combinable with ISOLINUX isohybrid production.
 2582  * It overrides --protective-msdos-label. See iso_write_opts_set_system_area().
 2583  * Only partition 4 stays available for iso_write_opts_set_partition_img().
 2584  * It is compatible with HFS+/FAT production by storing the PreP partition
 2585  * before the start of the HFS+/FAT partition.
 2586  *
 2587  * @param opts
 2588  *        The option set to be manipulated.
 2589  * @param image_path
 2590  *        File address in the local file system or instructions for interval
 2591  *        reader. See flag bit0.
 2592  *        NULL revokes production of the PreP partition.
 2593  * @param flag
 2594  *        bit0= The path contains instructions for the interval reader.
 2595  *              See above.
 2596  *              @since 1.4.0
 2597  *        All other bits are reserved for future usage. Set them to 0.
 2598  * @return
 2599  *        ISO_SUCCESS or error
 2600  *
 2601  * @since 1.2.4
 2602  */
 2603 int iso_write_opts_set_prep_img(IsoWriteOpts *opts, char *image_path,
 2604                                 int flag);
 2605 
 2606 /**
 2607  * Copy a data file from the local filesystem into the emerging ISO image.
 2608  * Mark it by an GPT partition entry as EFI System partition, and also cause
 2609  * protective GPT partition entries before and after the partition.
 2610  * GPT = Globally Unique Identifier Partition Table
 2611  *
 2612  * This feature may collide with data submitted by
 2613  *   iso_write_opts_set_system_area()
 2614  * and with settings made by
 2615  *   el_torito_set_isolinux_options()
 2616  * It is compatible with HFS+/FAT production by storing the EFI partition
 2617  * before the start of the HFS+/FAT partition.
 2618  * The GPT overwrites byte 0x0200 to 0x03ff of the system area and all
 2619  * further bytes above 0x0800 which are not used by an Apple Partition Map.
 2620  *
 2621  * @param opts
 2622  *        The option set to be manipulated.
 2623  * @param image_path
 2624  *        File address in the local file system or instructions for interval
 2625  *        reader. See flag bit0.
 2626  *        NULL revokes production of the EFI boot partition.
 2627  * @param flag
 2628  *        bit0= The path contains instructions for the interval reader
 2629  *              See above.
 2630  *              @since 1.4.0
 2631  *        All other bits are reserved for future usage. Set them to 0.
 2632  * @return
 2633  *        ISO_SUCCESS or error
 2634  *
 2635  * @since 1.2.4
 2636  */
 2637 int iso_write_opts_set_efi_bootp(IsoWriteOpts *opts, char *image_path, 
 2638                                  int flag);
 2639 
 2640 /**
 2641  * Control whether the emerging GPT gets a pseudo-randomly generated disk GUID
 2642  * or whether it gets a user supplied GUID.
 2643  * The partition GUIDs will be generated in a reproducible way by exoring the
 2644  * little-endian 32 bit partition number with the disk GUID beginning at byte
 2645  * offset 9.
 2646  *
 2647  * @param opts
 2648  *        The option set to be manipulated.
 2649  * @param guid
 2650  *        16 bytes of user supplied GUID. Readily byte-swapped from the text
 2651  *        form as prescribed by UEFI specs:
 2652  *          4 byte, 2 byte, 2 byte as little-endian. 
 2653  *          2 byte, 6 byte as big-endian.
 2654  *        The upper 4 bit of guid[7] should bear the value 4 to express the
 2655  *        RFC 4122 version 4. Bit 7 of byte[8] should  be set to 1 and bit 6
 2656  *        be set to 0, in order to express the RFC 4122 variant of UUID,
 2657  *        where version 4 means "pseudo-random uuid".
 2658  * @param mode
 2659  *        0 = ignore parameter guid and produce the GPT disk GUID by a
 2660  *            pseudo-random algorithm. This is the default setting.
 2661  *        1 = use parameter guid as GPT disk GUID
 2662  *        2 = ignore parameter guid and derive the GPT disk GUID from
 2663  *            parameter vol_uuid of iso_write_opts_set_pvd_times().
 2664  *            The 16 bytes of vol_uuid get copied and bytes 7, 8 get their
 2665  *            upper bits changed to comply to RFC 4122 and UEFI.
 2666  *            Error ISO_GPT_NO_VOL_UUID will occur if image production begins
 2667  *            before vol_uuid was set.
 2668  *
 2669  * @return
 2670  *        ISO_SUCCESS or ISO_BAD_GPT_GUID_MODE
 2671  *
 2672  * @since 1.4.6
 2673  */
 2674 int iso_write_opts_set_gpt_guid(IsoWriteOpts *opts, uint8_t guid[16],
 2675                                 int mode);
 2676 
 2677 /**
 2678  * Generate a pseudo-random GUID suitable for iso_write_opts_set_gpt_guid().
 2679  *
 2680  * @param guid
 2681  *        Will be filled by 16 bytes of generated GUID.
 2682  *
 2683  * @since 1.4.6
 2684  */
 2685 void iso_generate_gpt_guid(uint8_t guid[16]);
 2686 
 2687 /**
 2688  * Cause an arbitrary data file to be appended to the ISO image and to be
 2689  * described by a partition table entry in an MBR or SUN Disk Label at the
 2690  * start of the ISO image.
 2691  * The partition entry will bear the size of the image file rounded up to
 2692  * the next multiple of 2048 bytes.
 2693  * MBR or SUN Disk Label are selected by iso_write_opts_set_system_area()
 2694  * system area type: 0 selects MBR partition table. 3 selects a SUN partition
 2695  * table with 320 kB start alignment.
 2696  *
 2697  * @param opts
 2698  *        The option set to be manipulated.
 2699  * @param partition_number
 2700  *        Depicts the partition table entry which shall describe the
 2701  *        appended image.
 2702  *        Range with MBR: 1 to 4. 1 will cause the whole ISO image to be
 2703  *                        unclaimable space before partition 1.
 2704  *        Range with SUN Disk Label: 2 to 8.
 2705  * @param partition_type
 2706  *        The MBR partition type. E.g. FAT12 = 0x01 , FAT16 = 0x06, 
 2707  *        Linux Native Partition = 0x83. See fdisk command L.
 2708  *        This parameter is ignored with SUN Disk Label.
 2709  * @param image_path
 2710  *        File address in the local file system or instructions for interval
 2711  *        reader. See flag bit0.
 2712  *        With SUN Disk Label: an empty name causes the partition to become
 2713  *        a copy of the next lower partition.
 2714  * @param flag
 2715  *        bit0= The path contains instructions for the interval reader
 2716  *              See above.
 2717  *              @since 1.4.0
 2718  *        All other bits are reserved for future usage. Set them to 0.
 2719  * @return
 2720  *        ISO_SUCCESS or error
 2721  *
 2722  * @since 0.6.38
 2723  */
 2724 int iso_write_opts_set_partition_img(IsoWriteOpts *opts, int partition_number,
 2725                            uint8_t partition_type, char *image_path, int flag);
 2726 
 2727 /**
 2728  * Control whether partitions created by iso_write_opts_set_partition_img()
 2729  * are to be represented in MBR or as GPT partitions.
 2730  * 
 2731  * @param opts
 2732  *        The option set to be manipulated.
 2733  * @param gpt
 2734  *        0= represent as MBR partition; as GPT only if other GPT partitions
 2735  *           are present
 2736  *        1= represent as GPT partition and cause protective MBR with a single
 2737  *           partition which covers the whole output data.
 2738  *           This may fail if other settings demand MBR partitions.
 2739  * @return
 2740  *        ISO_SUCCESS or error
 2741  *
 2742  * @since 1.4.0
 2743  */
 2744 int iso_write_opts_set_appended_as_gpt(IsoWriteOpts *opts, int gpt);
 2745 
 2746 /**
 2747  * Set the GPT Type GUID for a partition defined by
 2748  * iso_write_opts_set_partition_img().
 2749  *
 2750  * @param opts
 2751  *        The option set to be manipulated.
 2752  * @param partition_number
 2753  *        Depicts the partition table entry which shall get the Type GUID.
 2754  * @param guid
 2755  *        16 bytes of user supplied GUID. Readily byte-swapped from the text
 2756  *        form as prescribed by UEFI specs:
 2757  *          4 byte, 2 byte, 2 byte as little-endian.
 2758  *          2 byte, 6 byte as big-endian.
 2759  * @param valid
 2760  *        Set to 1 to make this Type GUID valid.
 2761  *        Set to 0 in order to invalidate a previously made setting. In this
 2762  *        case MBR type 0xEF will become the EFI Type GUID. All others will
 2763  *        become the Basic Data Partition Type GUID.
 2764  * @return
 2765  *        ISO_SUCCESS or error
 2766  *
 2767  * @since 1.5.2
 2768  */
 2769 int iso_write_opts_set_part_type_guid(IsoWriteOpts *opts, int partition_number,
 2770                                       uint8_t guid[16], int valid);
 2771 
 2772 /**
 2773  * Control whether partitions created by iso_write_opts_set_partition_img()
 2774  * are to be represented in Apple Partition Map.
 2775  * 
 2776  * @param opts
 2777  *        The option set to be manipulated.
 2778  * @param apm
 2779  *        0= do not represent appended partitions in APM
 2780  *        1= represent in APM, even if not
 2781  *           iso_write_opts_set_part_like_isohybrid() enables it and no
 2782  *           other APM partitions emerge.
 2783  * @return
 2784  *        ISO_SUCCESS or error
 2785  *
 2786  * @since 1.4.4
 2787  */
 2788 int iso_write_opts_set_appended_as_apm(IsoWriteOpts *opts, int apm);
 2789 
 2790 /**
 2791  * Control whether bits 2 to 8 of el_torito_set_isolinux_options()
 2792  * shall apply even if not isohybrid MBR patching is enabled (bit1 of
 2793  * parameter options of iso_write_opts_set_system_area()):
 2794  * - Mentioning of El Torito boot images in GPT.
 2795  * - Mentioning of El Torito boot images in APM.
 2796  *
 2797  * In this case some other behavior from isohybrid processing will apply too:
 2798  * - No MBR partition of type 0xee emerges, even if GPT gets produced.
 2799  * - Gaps between GPT and APM partitions will not be filled by more partitions.
 2800  *
 2801  * An extra feature towards isohybrid is enabled:
 2802  * - Appended partitions get mentioned in APM if other APM partitions emerge.
 2803  *
 2804  * @param opts
 2805  *        The option set to be manipulated.
 2806  * @param alike
 2807  *        0= Apply the described behavior only with ISOLINUX isohybrid.
 2808  *           Do not mention appended partitions in APM unless
 2809  *           iso_write_opts_set_appended_as_apm() is enabled.
 2810  *        1= Apply the described behavior even without ISOLINUX isohybrid.
 2811  *        
 2812  * @return
 2813  *        ISO_SUCCESS or error
 2814  *
 2815  * @since 1.4.4
 2816  */
 2817 int iso_write_opts_set_part_like_isohybrid(IsoWriteOpts *opts, int alike);
 2818 
 2819 /**
 2820  * Set the partition type of the MBR partition which represents the ISO
 2821  * filesystem or at least protects it.
 2822  * This is without effect if no such partition emerges by other settings or
 2823  * if the partition type is prescribed mandatorily like 0xee for GPT protective
 2824  * MBR or 0x96 for CHRP.
 2825  * @param opts
 2826  *        The option set to be manipulated.
 2827  * @param part_type
 2828  *        0x00 to 0xff as desired partition type.
 2829  *        Any other value (e.g. -1) enables the default types of the various
 2830  *        occasions.
 2831  * @return
 2832  *        ISO_SUCCESS or error
 2833  * @since 1.4.8
 2834  */
 2835 int iso_write_opts_set_iso_mbr_part_type(IsoWriteOpts *opts, int part_type);
 2836 
 2837 /**
 2838  * Set the GPT Type GUID for the partition which represents the ISO 9660
 2839  * filesystem, if such a partition emerges in GPT.
 2840  * @param opts
 2841  *        The option set to be manipulated.
 2842  * @param guid
 2843  *        16 bytes of user supplied GUID. Readily byte-swapped from the text
 2844  *        form as prescribed by UEFI specs:
 2845  *          4 byte, 2 byte, 2 byte as little-endian.
 2846  *          2 byte, 6 byte as big-endian.
 2847  * @param valid
 2848  *        Set to 1 to make this Type GUID valid.
 2849  *        Set to 0 in order to invalidate a previously made setting. In this
 2850  *        case the setting of iso_write_opts_set_iso_mbr_part_type() or its
 2851  *        default will get into effect.
 2852  * @return
 2853  *        ISO_SUCCESS or error
 2854  *
 2855  * @since 1.5.2
 2856  */
 2857 int iso_write_opts_set_iso_type_guid(IsoWriteOpts *opts, uint8_t guid[16],
 2858                                      int valid);
 2859 
 2860 /**
 2861  * Inquire the start address of the file data blocks after having used
 2862  * IsoWriteOpts with iso_image_create_burn_source().
 2863  * @param opts
 2864  *        The option set that was used when starting image creation
 2865  * @param data_start
 2866  *        Returns the logical block address if it is already valid
 2867  * @param flag
 2868  *        Reserved for future usage, set to 0.
 2869  * @return
 2870  *        1 indicates valid data_start, <0 indicates invalid data_start
 2871  *
 2872  * @since 0.6.16
 2873  */
 2874 int iso_write_opts_get_data_start(IsoWriteOpts *opts, uint32_t *data_start,
 2875                                   int flag);
 2876 
 2877 /**
 2878  * Update the sizes of all files added to image.
 2879  *
 2880  * This may be called just before iso_image_create_burn_source() to force
 2881  * libisofs to check the file sizes again (they're already checked when added
 2882  * to IsoImage). It is useful if you have changed some files after adding then
 2883  * to the image.
 2884  *
 2885  * @return
 2886  *    1 on success, < 0 on error
 2887  * @since 0.6.8
 2888  */
 2889 int iso_image_update_sizes(IsoImage *image);
 2890 
 2891 /**
 2892  * Create a burn_source and a thread which immediately begins to generate
 2893  * the image. That burn_source can be used with libburn as a data source
 2894  * for a track. A copy of its public declaration in libburn.h can be found
 2895  * further below in this text.
 2896  *
 2897  * If image generation shall be aborted by the application program, then
 2898  * the .cancel() method of the burn_source must be called to end the
 2899  * generation thread:  burn_src->cancel(burn_src);
 2900  *
 2901  * @param image
 2902  *     The image to write.
 2903  * @param opts
 2904  *     The options for image generation. All needed data will be copied, so
 2905  *     you can free the given struct once this function returns.
 2906  * @param burn_src
 2907  *     Location where the pointer to the burn_source will be stored
 2908  * @return
 2909  *     1 on success, < 0 on error
 2910  *
 2911  * @since 0.6.2
 2912  */
 2913 int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts,
 2914                                  struct burn_source **burn_src);
 2915 
 2916 /**
 2917  * Inquire whether the image generator thread is still at work. As soon as the
 2918  * reply is 0, the caller of iso_image_create_burn_source() may assume that
 2919  * the image generation has ended.
 2920  * Nevertheless there may still be readily formatted output data pending in
 2921  * the burn_source or its consumers. So the final delivery of the image has
 2922  * also to be checked at the data consumer side,e.g. by burn_drive_get_status()
 2923  * in case of libburn as consumer.
 2924  * @param image
 2925  *     The image to inquire.
 2926  * @return
 2927  *     1 generating of image stream is still in progress
 2928  *     0 generating of image stream has ended meanwhile
 2929  *
 2930  * @since 0.6.38
 2931  */
 2932 int iso_image_generator_is_running(IsoImage *image);
 2933 
 2934 /**
 2935  * Creates an IsoReadOpts for reading an existent image. You should set the
 2936  * options desired with the correspondent setters. Note that you may want to
 2937  * set the start block value.
 2938  *
 2939  * Options by default are determined by the selected profile.
 2940  *
 2941  * @param opts
 2942  *     Pointer to the location where the newly created IsoReadOpts will be
 2943  *     stored. You should free it with iso_read_opts_free() when no more
 2944  *     needed.
 2945  * @param profile
 2946  *     Default profile for image reading. For now the following values are
 2947  *     defined:
 2948  *     ---> 0 [STANDARD]
 2949  *         Suitable for most situations. Most extension are read. When both
 2950  *         Joliet and RR extension are present, RR is used.
 2951  *         AAIP for ACL and xattr is not enabled by default.
 2952  * @return
 2953  *      1 success, < 0 error
 2954  *
 2955  * @since 0.6.2
 2956  */
 2957 int iso_read_opts_new(IsoReadOpts **opts, int profile);
 2958 
 2959 /**
 2960  * Free an IsoReadOpts previously allocated with iso_read_opts_new().
 2961  *
 2962  * @since 0.6.2
 2963  */
 2964 void iso_read_opts_free(IsoReadOpts *opts);
 2965 
 2966 /**
 2967  * Set the block where the image begins. It is usually 0, but may be different
 2968  * on a multisession disc.
 2969  *
 2970  * @since 0.6.2
 2971  */
 2972 int iso_read_opts_set_start_block(IsoReadOpts *opts, uint32_t block);
 2973 
 2974 /**
 2975  * Do not read Rock Ridge extensions.
 2976  * In most cases you don't want to use this. It could be useful if RR info
 2977  * is damaged, or if you want to use the Joliet tree.
 2978  *
 2979  * @since 0.6.2
 2980  */
 2981 int iso_read_opts_set_no_rockridge(IsoReadOpts *opts, int norr);
 2982 
 2983 /**
 2984  * Do not read Joliet extensions.
 2985  *
 2986  * @since 0.6.2
 2987  */
 2988 int iso_read_opts_set_no_joliet(IsoReadOpts *opts, int nojoliet);
 2989 
 2990 /**
 2991  * Do not read ISO 9660:1999 enhanced tree
 2992  *
 2993  * @since 0.6.2
 2994  */
 2995 int iso_read_opts_set_no_iso1999(IsoReadOpts *opts, int noiso1999);
 2996 
 2997 /**
 2998  * Control reading of AAIP information about ACL and xattr when loading
 2999  * existing images.
 3000  * For importing ACL and xattr when inserting nodes from external filesystems
 3001  * (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea().
 3002  * For eventual writing of this information see iso_write_opts_set_aaip().
 3003  *
 3004  * @param opts
 3005  *       The option set to be manipulated
 3006  * @param noaaip
 3007  *       1 = Do not read AAIP information
 3008  *       0 = Read AAIP information if available
 3009  *       All other values are reserved.
 3010  * @since 0.6.14
 3011  */
 3012 int iso_read_opts_set_no_aaip(IsoReadOpts *opts, int noaaip);
 3013 
 3014 /**
 3015  * Control reading of an array of MD5 checksums which is eventually stored
 3016  * at the end of a session. See also iso_write_opts_set_record_md5().
 3017  * Important: Loading of the MD5 array will only work if AAIP is enabled
 3018  *            because its position and layout is recorded in xattr "isofs.ca".
 3019  *
 3020  * @param opts
 3021  *       The option set to be manipulated
 3022  * @param no_md5
 3023  *       0 = Read MD5 array if available, refuse on non-matching MD5 tags
 3024  *       1 = Do not read MD5 checksum array
 3025  *       2 = Read MD5 array, but do not check MD5 tags
 3026  *           @since 1.0.4
 3027  *       All other values are reserved.
 3028  *
 3029  * @since 0.6.22
 3030  */
 3031 int iso_read_opts_set_no_md5(IsoReadOpts *opts, int no_md5);
 3032 
 3033 
 3034 /**
 3035  * Control discarding of eventual inode numbers from existing images.
 3036  * Such numbers may come from RRIP 1.12 entries PX. If not discarded they
 3037  * get written unchanged when the file object gets written into an ISO image. 
 3038  * If this inode number is missing with a file in the imported image,
 3039  * or if it has been discarded during image reading, then a unique inode number
 3040  * will be generated at some time before the file gets written into an ISO
 3041  * image.
 3042  * Two image nodes which have the same inode number represent two hardlinks
 3043  * of the same file object. So discarding the numbers splits hardlinks.
 3044  *
 3045  * @param opts
 3046  *       The option set to be manipulated
 3047  * @param new_inos
 3048  *     1 = Discard imported inode numbers and finally hand out a unique new
 3049  *         one to each single file before it gets written into an ISO image.
 3050  *     0 = Keep eventual inode numbers from PX entries.
 3051  *         All other values are reserved.
 3052  * @since 0.6.20
 3053  */
 3054 int iso_read_opts_set_new_inos(IsoReadOpts *opts, int new_inos);
 3055 
 3056 /**
 3057  * Whether to prefer Joliet over RR. libisofs usually prefers RR over
 3058  * Joliet, as it give us much more info about files. So, if both extensions
 3059  * are present, RR is used. You can set this if you prefer Joliet, but
 3060  * note that this is not very recommended. This doesn't mean than RR
 3061  * extensions are not read: if no Joliet is present, libisofs will read
 3062  * RR tree.
 3063  *
 3064  * @since 0.6.2
 3065  */
 3066 int iso_read_opts_set_preferjoliet(IsoReadOpts *opts, int preferjoliet);
 3067 
 3068 /**
 3069  * How to convert file names if neither Rock Ridge nor Joliet names
 3070  * are present and acceptable.
 3071  *
 3072  * @param opts
 3073  *      The option set to be manipulated
 3074  * @param ecma119_map
 3075  *      The conversion mode to apply:
 3076  *       0 = unmapped:  Take name as recorded in ECMA-119 directory record
 3077  *                      (not suitable for writing it to a new ISO filesystem)
 3078  *       1 = stripped:  Like unmapped, but strip off trailing ";1" or ".;1"
 3079  *       2 = uppercase: Like stripped, but map {a-z} to {A-Z}
 3080  *       3 = lowercase: Like stripped, but map {A-Z} to {a-z}
 3081  * @return
 3082  *       ISO_SUCCESS if ecma119_map was accepted
 3083  *       0           if the value was out of range
 3084  *       < 0         if other error
 3085  *
 3086  * @since 1.4.2
 3087  */
 3088 int iso_read_opts_set_ecma119_map(IsoReadOpts *opts, int ecma119_map);
 3089 
 3090 /**
 3091  * How to convert Joliet file names.
 3092  *
 3093  * @param opts
 3094  *      The option set to be manipulated
 3095  * @param ecma119_map
 3096  *      The conversion mode to apply:
 3097  *       0 = unmapped:  Take name as recorded in Joliet directory record
 3098  *                      (not suitable for writing it to a new ISO filesystem)
 3099  *       1 = stripped:  Strip off trailing ";1" or ".;1"
 3100  * @return
 3101  *       ISO_SUCCESS if joliet_map was accepted
 3102  *       0           if the value was out of range
 3103  *       < 0         if other error
 3104  *
 3105  * @since 1.5.4
 3106  */
 3107 int iso_read_opts_set_joliet_map(IsoReadOpts *opts, int joliet_map);
 3108 
 3109 /**
 3110  * Set default uid for files when RR extensions are not present.
 3111  *
 3112  * @since 0.6.2
 3113  */
 3114 int iso_read_opts_set_default_uid(IsoReadOpts *opts, uid_t uid);
 3115 
 3116 /**
 3117  * Set default gid for files when RR extensions are not present.
 3118  *
 3119  * @since 0.6.2
 3120  */
 3121 int iso_read_opts_set_default_gid(IsoReadOpts *opts, gid_t gid);
 3122 
 3123 /**
 3124  * Set default permissions for files when RR extensions are not present.
 3125  *
 3126  * @param opts
 3127  *       The option set to be manipulated
 3128  * @param file_perm
 3129  *      Permissions for files.
 3130  * @param dir_perm
 3131  *      Permissions for directories.
 3132  *
 3133  * @since 0.6.2
 3134  */
 3135 int iso_read_opts_set_default_permissions(IsoReadOpts *opts, mode_t file_perm,
 3136                                           mode_t dir_perm);
 3137 
 3138 /**
 3139  * Set the input charset of the file names on the image. NULL to use locale
 3140  * charset. You have to specify a charset if the image filenames are encoded
 3141  * in a charset different that the local one. This could happen, for example,
 3142  * if the image was created on a system with different charset.
 3143  *
 3144  * @param opts
 3145  *       The option set to be manipulated
 3146  * @param charset
 3147  *      The charset to use as input charset.  You can obtain the list of
 3148  *      charsets supported on your system executing "iconv -l" in a shell.
 3149  *
 3150  * @since 0.6.2
 3151  */
 3152 int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset);
 3153 
 3154 /**
 3155  * Enable or disable methods to automatically choose an input charset.
 3156  * This eventually overrides the name set via iso_read_opts_set_input_charset()
 3157  *
 3158  * @param opts
 3159  *       The option set to be manipulated
 3160  * @param mode
 3161  *       Bitfield for control purposes:
 3162  *       bit0= Allow to use the input character set name which is eventually
 3163  *             stored in attribute "isofs.cs" of the root directory.
 3164  *             Applications may attach this xattr by iso_node_set_attrs() to
 3165  *             the root node, call iso_write_opts_set_output_charset() with the
 3166  *             same name and enable iso_write_opts_set_aaip() when writing
 3167  *             an image.
 3168  *       Submit any other bits with value 0.
 3169  *
 3170  * @since 0.6.18
 3171  *
 3172  */
 3173 int iso_read_opts_auto_input_charset(IsoReadOpts *opts, int mode);
 3174 
 3175 /**
 3176  * Enable or disable loading of the first 32768 bytes of the session.
 3177  *
 3178  * @param opts
 3179  *       The option set to be manipulated
 3180  * @param mode
 3181  *       Bitfield for control purposes:
 3182  *       bit0= Load System Area data and attach them to the image so that they
 3183  *             get written by the next session, if not overridden by
 3184  *             iso_write_opts_set_system_area().
 3185  *       Submit any other bits with value 0.
 3186  *
 3187  * @since 0.6.30
 3188  *
 3189  */
 3190 int iso_read_opts_load_system_area(IsoReadOpts *opts, int mode);
 3191 
 3192 /**
 3193  * Control whether to keep a reference to the IsoDataSource object which
 3194  * allows access to the blocks of the imported ISO 9660 filesystem.
 3195  * This is needed if the interval reader shall read from "imported_iso".
 3196  *
 3197  * @param opts
 3198  *       The option set to be manipulated
 3199  * @param mode
 3200  *       Bitfield for control purposes:
 3201  *       bit0= Keep a reference to the IsoDataSource until the IsoImage object
 3202  *             gets disposed by its final iso_image_unref().
 3203  *       Submit any other bits with value 0.
 3204  *
 3205  * @since 1.4.0
 3206  *
 3207  */
 3208 int iso_read_opts_keep_import_src(IsoReadOpts *opts, int mode);
 3209 
 3210 /**
 3211  * Import a previous session or image, for growing or modify.
 3212  *
 3213  * @param image
 3214  *     The image context to which old image will be imported. Note that all
 3215  *     files added to image, and image attributes, will be replaced with the
 3216  *     contents of the old image.
 3217  *     TODO #00025 support for merging old image files
 3218  * @param src
 3219  *     Data Source from which old image will be read. A extra reference is
 3220  *     added, so you still need to iso_data_source_unref() yours.
 3221  * @param opts
 3222  *     Options for image import. All needed data will be copied, so you
 3223  *     can free the given struct once this function returns.
 3224  * @param features
 3225  *     If not NULL, a new IsoReadImageFeatures will be allocated and filled
 3226  *     with the features of the old image. It should be freed with
 3227  *     iso_read_image_features_destroy() when no more needed. You can pass
 3228  *     NULL if you're not interested on them.
 3229  * @return
 3230  *     1 on success, < 0 on error
 3231  *
 3232  * @since 0.6.2
 3233  */
 3234 int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts,
 3235                      IsoReadImageFeatures **features);
 3236 
 3237 /**
 3238  * Destroy an IsoReadImageFeatures object obtained with iso_image_import.
 3239  *
 3240  * @since 0.6.2
 3241  */
 3242 void iso_read_image_features_destroy(IsoReadImageFeatures *f);
 3243 
 3244 /**
 3245  * Get the size (in 2048 byte block) of the image, as reported in the PVM.
 3246  *
 3247  * @since 0.6.2
 3248  */
 3249 uint32_t iso_read_image_features_get_size(IsoReadImageFeatures *f);
 3250 
 3251 /**
 3252  * Whether RockRidge extensions are present in the image imported.
 3253  *
 3254  * @since 0.6.2
 3255  */
 3256 int iso_read_image_features_has_rockridge(IsoReadImageFeatures *f);
 3257 
 3258 /**
 3259  * Whether Joliet extensions are present in the image imported.
 3260  *
 3261  * @since 0.6.2
 3262  */
 3263 int iso_read_image_features_has_joliet(IsoReadImageFeatures *f);
 3264 
 3265 /**
 3266  * Whether the image is recorded according to ISO 9660:1999, i.e. it has
 3267  * a version 2 Enhanced Volume Descriptor.
 3268  *
 3269  * @since 0.6.2
 3270  */
 3271 int iso_read_image_features_has_iso1999(IsoReadImageFeatures *f);
 3272 
 3273 /**
 3274  * Whether El-Torito boot record is present present in the image imported.
 3275  *
 3276  * @since 0.6.2
 3277  */
 3278 int iso_read_image_features_has_eltorito(IsoReadImageFeatures *f);
 3279 
 3280 /**
 3281  * Tells what directory tree was loaded:
 3282  *     0= ISO 9660 , 1 = Joliet , 2 = ISO 9660:1999
 3283  *
 3284  * @since 1.5.4
 3285  */
 3286 int iso_read_image_features_tree_loaded(IsoReadImageFeatures *f);
 3287 
 3288 /**
 3289  * Tells whether Rock Ridge information was used while loading the tree:
 3290  *   1= yes, 0= no
 3291  *
 3292  * @since 1.5.4
 3293  */
 3294 int iso_read_image_features_rr_loaded(IsoReadImageFeatures *f);
 3295 
 3296 /**
 3297  * Increments the reference counting of the given image.
 3298  *
 3299  * @since 0.6.2
 3300  */
 3301 void iso_image_ref(IsoImage *image);
 3302 
 3303 /**
 3304  * Decrements the reference counting of the given image.
 3305  * If it reaches 0, the image is free, together with its tree nodes (whether
 3306  * their refcount reach 0 too, of course).
 3307  *
 3308  * @since 0.6.2
 3309  */
 3310 void iso_image_unref(IsoImage *image);
 3311 
 3312 /**
 3313  * Attach user defined data to the image. Use this if your application needs
 3314  * to store addition info together with the IsoImage. If the image already
 3315  * has data attached, the old data will be freed.
 3316  *
 3317  * @param image
 3318  *      The image to which data shall be attached.
 3319  * @param data
 3320  *      Pointer to application defined data that will be attached to the
 3321  *      image. You can pass NULL to remove any already attached data.
 3322  * @param give_up
 3323  *      Function that will be called when the image does not need the data
 3324  *      any more. It receives the data pointer as an argumente, and eventually
 3325  *      causes data to be freed. It can be NULL if you don't need it.
 3326  * @return
 3327  *      1 on success, < 0 on error
 3328  *
 3329  * @since 0.6.2
 3330  */
 3331 int iso_image_attach_data(IsoImage *image, void *data, void (*give_up)(void*));
 3332 
 3333 /**
 3334  * The the data previously attached with iso_image_attach_data()
 3335  *
 3336  * @since 0.6.2
 3337  */
 3338 void *iso_image_get_attached_data(IsoImage *image);
 3339 
 3340 /**
 3341  * Set the name truncation mode and the maximum name length for nodes from
 3342  * image importing, creation of new IsoNode objects, and name changing image
 3343  * manipulations.
 3344  *
 3345  * Truncated names are supposed to be nearly unique because they end by the MD5
 3346  * of the first 4095 characters of the untruncated name. One should treat them
 3347  * as if they were the untruncated original names.
 3348  *
 3349  * For proper processing of truncated names it is necessary to use
 3350  *   iso_image_set_node_name()   instead of  iso_node_set_name()
 3351  *   iso_image_add_new_dir()                 iso_tree_add_new_dir()
 3352  *   iso_image_add_new_file()                iso_tree_add_new_file()
 3353  *   iso_image_add_new_special()             iso_tree_add_new_special()
 3354  *   iso_image_add_new_symlink()             iso_tree_add_new_symlink()
 3355  *   iso_image_tree_clone()                  iso_tree_clone()
 3356  *   iso_image_dir_get_node()                iso_dir_get_node()
 3357  *   iso_image_path_to_node()                iso_tree_path_to_node()
 3358  * 
 3359  * Beware of ambiguities if both, the full name and the truncated name,
 3360  * exist in the same directory. Best is to only set truncation parameters
 3361  * once with an ISO filesystem and to never change them later.
 3362  * 
 3363  * If writing of AAIP is enabled, then the mode and length are recorded in
 3364  * xattr "isofs.nt" of the root node.
 3365  * If reading of AAIP is enabled and "isofs.nt" is found, then it gets into
 3366  * effect if both, the truncate mode value from "isofs.nt" and the current
 3367  * truncate mode of the IsoImage are 1, and the length is between 64 and 255.
 3368  * 
 3369  * @param img
 3370  *      The image which shall be manipulated.
 3371  * @param mode
 3372  *      0= Do not truncate but throw error ISO_RR_NAME_TOO_LONG if a file name
 3373  *         is longer than parameter length.
 3374  *      1= Truncate to length and overwrite the last 33 bytes of that length
 3375  *         by a colon ':' and the hex representation of the MD5 of the first
 3376  *         4095 bytes of the whole oversized name.
 3377  *         Potential incomplete UTF-8 characters will get their leading bytes
 3378  *         replaced by '_'.
 3379  *         Mode 1 is the default.
 3380  * @param length
 3381  *      Maximum byte count of a file name. Permissible values are 64 to 255.
 3382  *      Default is 255.
 3383  * @return
 3384  *      ISO_SUCCESS or ISO_WRONG_ARG_VALUE
 3385  *
 3386  * @since 1.4.2
 3387  */
 3388 int iso_image_set_truncate_mode(IsoImage *img, int mode, int length);
 3389 
 3390 /**
 3391  * Inquire the current setting of iso_image_set_truncate_mode().
 3392  *
 3393  * @param img
 3394  *      The image which shall be inquired.
 3395  * @param mode
 3396  *      Returns the mode value.
 3397  * @param length
 3398  *      Returns the length value.
 3399  * @return
 3400  *      ISO_SUCCESS or <0 = error
 3401  *
 3402  * @since 1.4.2
 3403  */
 3404 int iso_image_get_truncate_mode(IsoImage *img, int *mode, int *length);
 3405 
 3406 /**
 3407  * Immediately apply the given truncate mode and length to the given string.
 3408  * 
 3409  * @param mode
 3410  *      See iso_image_set_truncate_mode()
 3411  * @param length
 3412  *      See iso_image_set_truncate_mode()
 3413  * @param name
 3414  *      The string to be inspected and truncated if mode says so.
 3415  * @param flag
 3416  *      Bitfield for control purposes. Unused yet. Submit 0.
 3417  * @return
 3418  *      ISO_SUCCESS, ISO_WRONG_ARG_VALUE, ISO_RR_NAME_TOO_LONG
 3419  *
 3420  * @since 1.4.2
 3421  */
 3422 int iso_truncate_leaf_name(int mode, int length, char *name, int flag);
 3423 
 3424 /**
 3425  * Get the root directory of the image.
 3426  * No extra ref is added to it, so you must not unref it. Use iso_node_ref()
 3427  * if you want to get your own reference.
 3428  *
 3429  * @since 0.6.2
 3430  */
 3431 IsoDir *iso_image_get_root(const IsoImage *image);
 3432 
 3433 /**
 3434  * Fill in the volset identifier for a image.
 3435  *
 3436  * @since 0.6.2
 3437  */
 3438 void iso_image_set_volset_id(IsoImage *image, const char *volset_id);
 3439 
 3440 /**
 3441  * Get the volset identifier.
 3442  * The returned string is owned by the image and must not be freed nor
 3443  * changed.
 3444  *
 3445  * @since 0.6.2
 3446  */
 3447 const char *iso_image_get_volset_id(const IsoImage *image);
 3448 
 3449 /**
 3450  * Fill in the volume identifier for a image.
 3451  *
 3452  * @since 0.6.2
 3453  */
 3454 void iso_image_set_volume_id(IsoImage *image, const char *volume_id);
 3455 
 3456 /**
 3457  * Get the volume identifier.
 3458  * The returned string is owned by the image and must not be freed nor
 3459  * changed.
 3460  *
 3461  * @since 0.6.2
 3462  */
 3463 const char *iso_image_get_volume_id(const IsoImage *image);
 3464 
 3465 /**
 3466  * Fill in the publisher for a image.
 3467  *
 3468  * @since 0.6.2
 3469  */
 3470 void iso_image_set_publisher_id(IsoImage *image, const char *publisher_id);
 3471 
 3472 /**
 3473  * Get the publisher of a image.
 3474  * The returned string is owned by the image and must not be freed nor
 3475  * changed.
 3476  *
 3477  * @since 0.6.2
 3478  */
 3479 const char *iso_image_get_publisher_id(const IsoImage *image);
 3480 
 3481 /**
 3482  * Fill in the data preparer for a image.
 3483  *
 3484  * @since 0.6.2
 3485  */
 3486 void iso_image_set_data_preparer_id(IsoImage *image,
 3487                                     const char *data_preparer_id);
 3488 
 3489 /**
 3490  * Get the data preparer of a image.
 3491  * The returned string is owned by the image and must not be freed nor
 3492  * changed.
 3493  *
 3494  * @since 0.6.2
 3495  */
 3496 const char *iso_image_get_data_preparer_id(const IsoImage *image);
 3497 
 3498 /**
 3499  * Fill in the system id for a image. Up to 32 characters.
 3500  *
 3501  * @since 0.6.2
 3502  */
 3503 void iso_image_set_system_id(IsoImage *image, const char *system_id);
 3504 
 3505 /**
 3506  * Get the system id of a image.
 3507  * The returned string is owned by the image and must not be freed nor
 3508  * changed.
 3509  *
 3510  * @since 0.6.2
 3511  */
 3512 const char *iso_image_get_system_id(const IsoImage *image);
 3513 
 3514 /**
 3515  * Fill in the application id for a image. Up to 128 chars.
 3516  *
 3517  * @since 0.6.2
 3518  */
 3519 void iso_image_set_application_id(IsoImage *image, const char *application_id);
 3520 
 3521 /**
 3522  * Get the application id of a image.
 3523  * The returned string is owned by the image and must not be freed nor
 3524  * changed.
 3525  *
 3526  * @since 0.6.2
 3527  */
 3528 const char *iso_image_get_application_id(const IsoImage *image);
 3529 
 3530 /**
 3531  * Fill copyright information for the image. Usually this refers
 3532  * to a file on disc. Up to 37 characters.
 3533  *
 3534  * @since 0.6.2
 3535  */
 3536 void iso_image_set_copyright_file_id(IsoImage *image,
 3537                                      const char *copyright_file_id);
 3538 
 3539 /**
 3540  * Get the copyright information of a image.
 3541  * The returned string is owned by the image and must not be freed nor
 3542  * changed.
 3543  *
 3544  * @since 0.6.2
 3545  */
 3546 const char *iso_image_get_copyright_file_id(const IsoImage *image);
 3547 
 3548 /**
 3549  * Fill abstract information for the image. Usually this refers
 3550  * to a file on disc. Up to 37 characters.
 3551  *
 3552  * @since 0.6.2
 3553  */
 3554 void iso_image_set_abstract_file_id(IsoImage *image,
 3555                                     const char *abstract_file_id);
 3556 
 3557 /**
 3558  * Get the abstract information of a image.
 3559  * The returned string is owned by the image and must not be freed nor
 3560  * changed.
 3561  *
 3562  * @since 0.6.2
 3563  */
 3564 const char *iso_image_get_abstract_file_id(const IsoImage *image);
 3565 
 3566 /**
 3567  * Fill biblio information for the image. Usually this refers
 3568  * to a file on disc. Up to 37 characters.
 3569  *
 3570  * @since 0.6.2
 3571  */
 3572 void iso_image_set_biblio_file_id(IsoImage *image, const char *biblio_file_id);
 3573 
 3574 /**
 3575  * Get the biblio information of a image.
 3576  * The returned string is owned by the image and must not be freed or changed.
 3577  *
 3578  * @since 0.6.2
 3579  */
 3580 const char *iso_image_get_biblio_file_id(const IsoImage *image);
 3581 
 3582 /**
 3583  * Fill Application Use field of the Primary Volume Descriptor.
 3584  * ECMA-119 8.4.32 Application Use (BP 884 to 1395)
 3585  * "This field shall be reserved for application use. Its content
 3586  *  is not specified by this Standard."
 3587  *
 3588  * @param image
 3589  *      The image to manipulate.
 3590  * @param app_use_data
 3591  *      Up to 512 bytes of data.
 3592  * @param count
 3593  *      The number of bytes in app_use_data. If the number is smaller than 512,
 3594  *      then the remaining bytes will be set to 0.
 3595  * @since 1.3.2
 3596  */
 3597 void iso_image_set_app_use(IsoImage *image, const char *app_use_data,
 3598                            int count);
 3599 
 3600 /**
 3601  * Get the current setting for the Application Use field of the Primary Volume
 3602  * Descriptor.
 3603  * The returned char array of 512 bytes is owned by the image and must not
 3604  * be freed or changed.
 3605  *
 3606  * @param image 
 3607  *      The image to inquire
 3608  * @since 1.3.2
 3609  */
 3610 const char *iso_image_get_app_use(IsoImage *image);
 3611 
 3612 /**
 3613  * Get the four timestamps from the Primary Volume Descriptor of the imported
 3614  * ISO image. The timestamps are strings which are either empty or consist
 3615  * of 16 digits of the form YYYYMMDDhhmmsscc, plus a signed byte in the range
 3616  * of -48 to +52, which gives the timezone offset in steps of 15 minutes.
 3617  * None of the returned string pointers shall be used for altering or freeing
 3618  * data. They are just for reading. 
 3619  *
 3620  * @param image
 3621  *        The image to be inquired.
 3622  * @param creation_time
 3623  *        Returns a pointer to the Volume Creation time:
 3624  *        When "the information in the volume was created."
 3625  * @param modification_time
 3626  *        Returns a pointer to Volume Modification time:
 3627  *        When "the information in the volume was last modified."
 3628  * @param expiration_time
 3629  *        Returns a pointer to Volume Expiration time:
 3630  *        When "the information in the volume may be regarded as obsolete."
 3631  * @param effective_time
 3632  *        Returns a pointer to Volume Expiration time:
 3633  *        When "the information in the volume may be used."
 3634  * @return
 3635  *        ISO_SUCCESS or error
 3636  *
 3637  * @since 1.2.8
 3638  */
 3639 int iso_image_get_pvd_times(IsoImage *image,
 3640                             char **creation_time, char **modification_time,
 3641                             char **expiration_time, char **effective_time);
 3642 
 3643 /**
 3644  * Create a new set of El-Torito bootable images by adding a boot catalog
 3645  * and the default boot image.
 3646  * Further boot images may then be added by iso_image_add_boot_image().
 3647  *
 3648  * @param image
 3649  *      The image to make bootable. If it was already bootable this function
 3650  *      returns an error and the image remains unmodified.
 3651  * @param image_path
 3652  *      The absolute path of a IsoFile to be used as default boot image or
 3653  *      --interval:appended_partition_$number[_start_$start_size_$size]:...
 3654  *      if type is ELTORITO_NO_EMUL. $number gives the partition number.
 3655  *      If _start_$start_size_$size is present, then it overrides the 2 KiB
 3656  *      start block of the partition and the partition size counted in
 3657  *      blocks of 512 bytes.
 3658  * @param type
 3659  *      The boot media type. This can be one of 3 types:
 3660  *             - ELTORITO_FLOPPY_EMUL.
 3661  *               Floppy emulation: Boot image file must be exactly
 3662  *               1200 KiB, 1440 KiB or 2880 KiB.
 3663  *             - ELTORITO_HARD_DISC_EMUL.
 3664  *               Hard disc emulation: The image must begin with a master
 3665  *               boot record with a single image.
 3666  *             - ELTORITO_NO_EMUL.
 3667  *               No emulation. You should specify load segment and load size
 3668  *               of image.
 3669  * @param catalog_path
 3670  *      The absolute path in the image tree where the catalog will be stored.
 3671  *      The directory component of this path must be a directory existent on
 3672  *      the image tree, and the filename component must be unique among all
 3673  *      children of that directory on image. Otherwise a correspodent error
 3674  *      code will be returned. This function will add an IsoBoot node that acts
 3675  *      as a placeholder for the real catalog, that will be generated at image
 3676  *      creation time.
 3677  * @param boot
 3678  *      Location where a pointer to the added boot image will be stored. That
 3679  *      object is owned by the IsoImage and must not be freed by the user,
 3680  *      nor dereferenced once the last reference to the IsoImage was disposed
 3681  *      via iso_image_unref(). A NULL value is allowed if you don't need a
 3682  *      reference to the boot image.
 3683  * @return
 3684  *      1 on success, < 0 on error
 3685  *
 3686  * @since 0.6.2
 3687  */
 3688 int iso_image_set_boot_image(IsoImage *image, const char *image_path,
 3689                              enum eltorito_boot_media_type type,
 3690                              const char *catalog_path,
 3691                              ElToritoBootImage **boot);
 3692 
 3693 /**
 3694  * Add a further boot image to the set of El-Torito bootable images.
 3695  * This set has already to be created by iso_image_set_boot_image().
 3696  * Up to 31 further boot images may be added.
 3697  *
 3698  * @param image
 3699  *      The image to which the boot image shall be added.
 3700  *      returns an error and the image remains unmodified.
 3701  * @param image_path
 3702  *      The absolute path of a IsoFile to be used as boot image or
 3703  *      --interval:appended_partition_$number[_start_$start_size_$size]:...
 3704  *      if type is ELTORITO_NO_EMUL. See iso_image_set_boot_image.
 3705  * @param type
 3706  *      The boot media type. See iso_image_set_boot_image.
 3707  * @param flag
 3708  *      Bitfield for control purposes. Unused yet. Submit 0.
 3709  * @param boot
 3710  *      Location where a pointer to the added boot image will be stored.
 3711  *      See iso_image_set_boot_image
 3712  * @return
 3713  *      1 on success, < 0 on error
 3714  *                    ISO_BOOT_NO_CATALOG means iso_image_set_boot_image()
 3715  *                    was not called first.
 3716  *
 3717  * @since 0.6.32
 3718  */
 3719 int iso_image_add_boot_image(IsoImage *image, const char *image_path,
 3720                              enum eltorito_boot_media_type type, int flag,
 3721                              ElToritoBootImage **boot);
 3722 
 3723 /**
 3724  * Get the El-Torito boot catalog and the default boot image of an ISO image.
 3725  *
 3726  * This can be useful, for example, to check if a volume read from a previous
 3727  * session or an existing image is bootable. It can also be useful to get
 3728  * the image and catalog tree nodes. An application would want those, for
 3729  * example, to prevent the user removing it.
 3730  *
 3731  * Both nodes are owned by libisofs and must not be freed. You can get your
 3732  * own ref with iso_node_ref(). You can also check if the node is already
 3733  * on the tree by getting its parent (note that when reading El-Torito info
 3734  * from a previous image, the nodes might not be on the tree even if you haven't
 3735  * removed them). Remember that you'll need to get a new ref
 3736  * (with iso_node_ref()) before inserting them again to the tree, and probably
 3737  * you will also need to set the name or permissions.
 3738  *
 3739  * @param image
 3740  *      The image from which to get the boot image.
 3741  * @param boot
 3742  *      If not NULL, it will be filled with a pointer to the boot image, if
 3743  *      any. That object is owned by the IsoImage and must not be freed by
 3744  *      the user, nor dereferenced once the last reference to the IsoImage was
 3745  *      disposed via iso_image_unref().
 3746  * @param imgnode
 3747  *      When not NULL, it will be filled with the image tree node. No extra ref
 3748  *      is added, you can use iso_node_ref() to get one if you need it.
 3749  *      The returned value is NULL if the boot image source is no IsoFile.
 3750  * @param catnode
 3751  *      When not NULL, it will be filled with the catnode tree node. No extra
 3752  *      ref is added, you can use iso_node_ref() to get one if you need it.
 3753  * @return
 3754  *      1 on success, 0 is the image is not bootable (i.e., it has no El-Torito
 3755  *      image), < 0 error.
 3756  *
 3757  * @since 0.6.2
 3758  */
 3759 int iso_image_get_boot_image(IsoImage *image, ElToritoBootImage **boot,
 3760                              IsoFile **imgnode, IsoBoot **catnode);
 3761 
 3762 /**
 3763  * Get detailed information about the boot catalog that was loaded from
 3764  * an ISO image.
 3765  * The boot catalog links the El Torito boot record at LBA 17 with the 
 3766  * boot images which are IsoFile objects in the image. The boot catalog
 3767  * itself is not a regular file and thus will not deliver an IsoStream.
 3768  * Its content is usually quite short and can be obtained by this call.
 3769  *
 3770  * @param image
 3771  *      The image to inquire.
 3772  * @param catnode
 3773  *      Will return the boot catalog tree node. No extra ref is taken.
 3774  * @param lba
 3775  *      Will return the block address of the boot catalog in the image.
 3776  * @param content
 3777  *      Will return either NULL or an allocated memory buffer with the
 3778  *      content bytes of the boot catalog.
 3779  *      Dispose it by free() when no longer needed.
 3780  * @param size
 3781  *      Will return the number of bytes in content.
 3782  * @return
 3783  *      1 if reply is valid, 0 if not boot catalog was loaded, < 0 on error.
 3784  *
 3785  * @since 1.1.2
 3786  */
 3787 int iso_image_get_bootcat(IsoImage *image, IsoBoot **catnode, uint32_t *lba,
 3788                           char **content, off_t *size);
 3789 
 3790 
 3791 /**
 3792  * Get all El-Torito boot images of an ISO image.
 3793  *
 3794  * The first of these boot images is the same as returned by
 3795  * iso_image_get_boot_image(). The others are alternative boot images. 
 3796  *
 3797  * @param image
 3798  *      The image from which to get the boot images.
 3799  * @param num_boots
 3800  *      The number of available array elements in boots and bootnodes.
 3801  * @param boots
 3802  *      Returns NULL or an allocated array of pointers to boot images.
 3803  *      Apply system call free(boots) to dispose it.
 3804  * @param bootnodes
 3805  *      Returns NULL or an allocated array of pointers to the IsoFile nodes
 3806  *      which bear the content of the boot images in boots.
 3807  *      An array entry is NULL if the boot image source is no IsoFile.
 3808 
 3809 >>> Need getter for partition index
 3810 
 3811  * @param flag
 3812  *      Bitfield for control purposes. Unused yet. Submit 0.
 3813  * @return
 3814  *      1 on success, 0 no El-Torito catalog and boot image attached,
 3815  *      < 0 error.
 3816  *
 3817  * @since 0.6.32
 3818  */
 3819 int iso_image_get_all_boot_imgs(IsoImage *image, int *num_boots,
 3820                    ElToritoBootImage ***boots, IsoFile ***bootnodes, int flag);
 3821 
 3822 
 3823 /**
 3824  * Removes all El-Torito boot images from the ISO image.
 3825  *
 3826  * The IsoBoot node that acts as placeholder for the catalog is also removed
 3827  * for the image tree, if there.
 3828  * If the image is not bootable (don't have el-torito boot image) this function
 3829  * just returns.
 3830  *
 3831  * @since 0.6.2
 3832  */
 3833 void iso_image_remove_boot_image(IsoImage *image);
 3834 
 3835 /**
 3836  * Sets the sort weight of the boot catalog that is attached to an IsoImage.
 3837  * 
 3838  * For the meaning of sort weights see iso_node_set_sort_weight().
 3839  * That function cannot be applied to the emerging boot catalog because
 3840  * it is not represented by an IsoFile.
 3841  *
 3842  * @param image
 3843  *      The image to manipulate.
 3844  * @param sort_weight
 3845  *      The larger this value, the lower will be the block address of the
 3846  *      boot catalog record.
 3847  * @return
 3848  *      0= no boot catalog attached , 1= ok , <0 = error
 3849  *
 3850  * @since 0.6.32
 3851  */
 3852 int iso_image_set_boot_catalog_weight(IsoImage *image, int sort_weight);
 3853 
 3854 /**
 3855  * Hides the boot catalog file from directory trees.
 3856  * 
 3857  * For the meaning of hiding files see iso_node_set_hidden().
 3858  *
 3859  * 
 3860  * @param image
 3861  *      The image to manipulate.
 3862  * @param hide_attrs
 3863  *      Or-combination of values from enum IsoHideNodeFlag to set the trees
 3864  *      in which the record.
 3865  * @return
 3866  *      0= no boot catalog attached , 1= ok , <0 = error
 3867  *
 3868  * @since 0.6.34
 3869  */
 3870 int iso_image_set_boot_catalog_hidden(IsoImage *image, int hide_attrs);
 3871 
 3872 
 3873 /**
 3874  * Get the boot media type as of parameter "type" of iso_image_set_boot_image()
 3875  * or iso_image_add_boot_image().
 3876  *
 3877  * @param bootimg
 3878  *      The image to inquire
 3879  * @param media_type
 3880  *      Returns the media type
 3881  * @return
 3882  *      1 = ok , < 0 = error
 3883  *
 3884  * @since 0.6.32
 3885  */
 3886 int el_torito_get_boot_media_type(ElToritoBootImage *bootimg, 
 3887                                   enum eltorito_boot_media_type *media_type);
 3888 
 3889 /**
 3890  * Sets the platform ID of the boot image.
 3891  * 
 3892  * The Platform ID gets written into the boot catalog at byte 1 of the
 3893  * Validation Entry, or at byte 1 of a Section Header Entry.
 3894  * If Platform ID and ID String of two consecutive bootimages are the same
 3895  *
 3896  * @param bootimg
 3897  *      The image to manipulate.
 3898  * @param id
 3899  *      A Platform ID as of
 3900  *      El Torito 1.0  : 0x00= 80x86,  0x01= PowerPC,  0x02= Mac
 3901  *      Others         : 0xef= EFI
 3902  * @return
 3903  *      1 ok , <=0 error
 3904  *
 3905  * @since 0.6.32
 3906  */
 3907 int el_torito_set_boot_platform_id(ElToritoBootImage *bootimg, uint8_t id);
 3908 
 3909 /**
 3910  * Get the platform ID value. See el_torito_set_boot_platform_id().
 3911  *
 3912  * @param bootimg
 3913  *      The image to inquire
 3914  * @return
 3915  *      0 - 255 : The platform ID 
 3916  *      < 0     : error
 3917  *
 3918  * @since 0.6.32
 3919  */
 3920 int el_torito_get_boot_platform_id(ElToritoBootImage *bootimg);
 3921 
 3922 /**
 3923  * Sets the load segment for the initial boot image. This is only for
 3924  * no emulation boot images, and is a NOP for other image types.
 3925  *
 3926  * @param bootimg
 3927  *      The image to to manipulate
 3928  * @param segment
 3929  *      Load segment address.
 3930  *      The data type of this parameter is not fully suitable. You may submit
 3931  *      negative numbers in the range ((short) 0x8000) to ((short) 0xffff)
 3932  *      in order to express the non-negative numbers 0x8000 to 0xffff.
 3933  *
 3934  * @since 0.6.2
 3935  */
 3936 void el_torito_set_load_seg(ElToritoBootImage *bootimg, short segment);
 3937 
 3938 /**
 3939  * Get the load segment value. See el_torito_set_load_seg().
 3940  *
 3941  * @param bootimg
 3942  *      The image to inquire
 3943  * @return
 3944  *      0 - 65535 : The load segment value 
 3945  *      < 0       : error
 3946  *
 3947  * @since 0.6.32
 3948  */
 3949 int el_torito_get_load_seg(ElToritoBootImage *bootimg);
 3950 
 3951 /**
 3952  * Sets the number of sectors (512b) to be load at load segment during
 3953  * the initial boot procedure. This is only for
 3954  * no emulation boot images, and is a NOP for other image types.
 3955  *
 3956  * @param bootimg
 3957  *      The image to to manipulate
 3958  * @param sectors
 3959  *      Number of 512-byte blocks to be loaded by the BIOS.
 3960  *      The data type of this parameter is not fully suitable. You may submit
 3961  *      negative numbers in the range ((short) 0x8000) to ((short) 0xffff)
 3962  *      in order to express the non-negative numbers 0x8000 to 0xffff.
 3963  *
 3964  * @since 0.6.2
 3965  */
 3966 void el_torito_set_load_size(ElToritoBootImage *bootimg, short sectors);
 3967 
 3968 /**
 3969  * Get the load size. See el_torito_set_load_size().
 3970  *
 3971  * @param bootimg
 3972  *      The image to inquire
 3973  * @return
 3974  *      0 - 65535 : The load size value
 3975  *      < 0       : error
 3976  *
 3977  * @since 0.6.32
 3978  */
 3979 int el_torito_get_load_size(ElToritoBootImage *bootimg);
 3980 
 3981 /**
 3982  * State that the load size shall be the size of the boot image automatically.
 3983  * This overrides el_torito_set_load_size().
 3984  * @param bootimg
 3985  *      The image to to manipulate
 3986  * @param mode
 3987  *      0= use value of el_torito_set_load_size()
 3988  *      1= determine value from boot image
 3989  */
 3990 void el_torito_set_full_load(ElToritoBootImage *bootimg, int mode);
 3991 
 3992 /**
 3993  * Inquire the setting of el_torito_set_full_load().
 3994  * @param bootimg
 3995  *      The image to inquire
 3996  * @return
 3997  *      The mode set with el_torito_set_full_load().
 3998  */
 3999 int el_torito_get_full_load(ElToritoBootImage *bootimg);
 4000 
 4001 /**
 4002  * Marks the specified boot image as not bootable
 4003  *
 4004  * @since 0.6.2
 4005  */
 4006 void el_torito_set_no_bootable(ElToritoBootImage *bootimg);
 4007 
 4008 /**
 4009  * Get the bootability flag. See el_torito_set_no_bootable().
 4010  *
 4011  * @param bootimg
 4012  *      The image to inquire
 4013  * @return
 4014  *      0 = not bootable, 1 = bootable , <0 = error
 4015  *
 4016  * @since 0.6.32
 4017  */
 4018 int el_torito_get_bootable(ElToritoBootImage *bootimg);
 4019 
 4020 /**
 4021  * Set the id_string of the Validation Entry or Sector Header Entry which
 4022  * will govern the boot image Section Entry in the El Torito Catalog.
 4023  *
 4024  * @param bootimg
 4025  *      The image to manipulate.
 4026  * @param id_string
 4027  *      The first boot image puts 24 bytes of ID string into the Validation
 4028  *      Entry, where they shall "identify the manufacturer/developer of
 4029  *      the CD-ROM".
 4030  *      Further boot images put 28 bytes into their Section Header.
 4031  *      El Torito 1.0 states that "If the BIOS understands the ID string, it
 4032  *      may choose to boot the system using one of these entries in place
 4033  *      of the INITIAL/DEFAULT entry." (The INITIAL/DEFAULT entry points to the
 4034  *      first boot image.)
 4035  * @return
 4036  *      1 = ok , <0 = error
 4037  *
 4038  * @since 0.6.32
 4039  */
 4040 int el_torito_set_id_string(ElToritoBootImage *bootimg, uint8_t id_string[28]);
 4041 
 4042 /** 
 4043  * Get the id_string as of el_torito_set_id_string().
 4044  *
 4045  * @param bootimg
 4046  *      The image to inquire
 4047  * @param id_string
 4048  *      Returns 28 bytes of id string
 4049  * @return
 4050  *      1 = ok , <0 = error
 4051  *
 4052  * @since 0.6.32
 4053  */
 4054 int el_torito_get_id_string(ElToritoBootImage *bootimg, uint8_t id_string[28]);
 4055 
 4056 /**
 4057  * Set the Selection Criteria of a boot image.
 4058  *
 4059  * @param bootimg
 4060  *      The image to manipulate.
 4061  * @param crit
 4062  *      The first boot image has no selection criteria. They will be ignored.
 4063  *      Further boot images put 1 byte of Selection Criteria Type and 19
 4064  *      bytes of data into their Section Entry.
 4065  *      El Torito 1.0 states that "The format of the selection criteria is
 4066  *      a function of the BIOS vendor. In the case of a foreign language
 4067  *      BIOS three bytes would be used to identify the language".
 4068  *      Type byte == 0 means "no criteria",
 4069  *      type byte == 1 means "Language and Version Information (IBM)".
 4070  * @return
 4071  *      1 = ok , <0 = error
 4072  *
 4073  * @since 0.6.32
 4074  */
 4075 int el_torito_set_selection_crit(ElToritoBootImage *bootimg, uint8_t crit[20]);
 4076 
 4077 /** 
 4078  * Get the Selection Criteria bytes as of el_torito_set_selection_crit().
 4079  *
 4080  * @param bootimg
 4081  *      The image to inquire
 4082  * @param crit
 4083  *      Returns 20 bytes of type and data
 4084  * @return
 4085  *      1 = ok , <0 = error
 4086  *
 4087  * @since 0.6.32
 4088  */
 4089 int el_torito_get_selection_crit(ElToritoBootImage *bootimg, uint8_t crit[20]);
 4090 
 4091 
 4092 /**
 4093  * Makes a guess whether the boot image was patched by a boot information
 4094  * table. It is advisable to patch such boot images if their content gets
 4095  * copied to a new location. See el_torito_set_isolinux_options().
 4096  * Note: The reply can be positive only if the boot image was imported
 4097  *       from an existing ISO image.
 4098  *
 4099  * @param bootimg
 4100  *      The image to inquire
 4101  * @param flag
 4102  *       Bitfield for control purposes:
 4103  *       bit0 - bit3= mode
 4104  *       0 = inquire for classic boot info table as described in man mkisofs
 4105  *           @since 0.6.32
 4106  *       1 = inquire for GRUB2 boot info as of bit9 of options of
 4107  *           el_torito_set_isolinux_options()
 4108  *           @since 1.3.0
 4109  * @return
 4110  *      1 = seems to contain the inquired boot info, 0 = quite surely not
 4111  * @since 0.6.32
 4112  */
 4113 int el_torito_seems_boot_info_table(ElToritoBootImage *bootimg, int flag);
 4114 
 4115 /**
 4116  * Specifies options for ISOLINUX or GRUB boot images. This should only be used
 4117  * if the type of boot image is known.
 4118  *
 4119  * @param bootimg
 4120  *      The image to set options on 
 4121  * @param options
 4122  *        bitmask style flag. The following values are defined:
 4123  *
 4124  *        bit0= Patch the boot info table of the boot image.
 4125  *              This does the same as mkisofs option -boot-info-table.
 4126  *              Needed for ISOLINUX or GRUB boot images with platform ID 0.
 4127  *              The table is located at byte 8 of the boot image file.
 4128  *              Its size is 56 bytes. 
 4129  *              The original boot image file on disk will not be modified.
 4130  *
 4131  *              One may use el_torito_seems_boot_info_table() for a
 4132  *              qualified guess whether a boot info table is present in
 4133  *              the boot image. If the result is 1 then it should get bit0
 4134  *              set if its content gets copied to a new LBA.
 4135  *
 4136  *        bit1= Generate a ISOLINUX isohybrid image with MBR.
 4137  *              ----------------------------------------------------------
 4138  *              @deprecated since 31 Mar 2010:
 4139  *              The author of syslinux, H. Peter Anvin requested that this
 4140  *              feature shall not be used any more. He intends to cease
 4141  *              support for the MBR template that is included in libisofs.
 4142  *              ----------------------------------------------------------
 4143  *              A hybrid image is a boot image that boots from either
 4144  *              CD/DVD media or from disk-like media, e.g. USB stick.
 4145  *              For that you need isolinux.bin from SYSLINUX 3.72 or later.
 4146  *              IMPORTANT: The application has to take care that the image
 4147  *                         on media gets padded up to the next full MB.
 4148  *                         Under seiveral circumstances it might get aligned
 4149  *                         automatically. But there is no warranty.
 4150  *        bit2-7= Mentioning in isohybrid GPT
 4151  *                0= Do not mention in GPT
 4152  *                1= Mention as Basic Data partition.
 4153  *                   This cannot be combined with GPT partitions as of
 4154  *                   iso_write_opts_set_efi_bootp()
 4155  *                   @since 1.2.4
 4156  *                2= Mention as HFS+ partition.
 4157  *                   This cannot be combined with HFS+ production by
 4158  *                   iso_write_opts_set_hfsplus().
 4159  *                   @since 1.2.4
 4160  *                Primary GPT and backup GPT get written if at least one 
 4161  *                ElToritoBootImage shall be mentioned.
 4162  *                The first three mentioned GPT partitions get mirrored in the
 4163  *                the partition table of the isohybrid MBR. They get type 0xfe.
 4164  *                The MBR partition entry for PC-BIOS gets type 0x00 rather
 4165  *                than 0x17.
 4166  *                Often it is one of the further MBR partitions which actually
 4167  *                gets used by EFI.
 4168  *                @since 1.2.4
 4169  *        bit8= Mention in isohybrid Apple partition map
 4170  *              APM get written if at least one ElToritoBootImage shall be
 4171  *              mentioned. The ISOLINUX MBR must look suitable or else an error
 4172  *              event will happen at image generation time.
 4173  *              @since 1.2.4
 4174  *        bit9= GRUB2 boot info
 4175  *              Patch the boot image file at byte 1012 with the 512-block
 4176  *              address + 2. Two little endian 32-bit words. Low word first.
 4177  *              This is combinable with bit0.
 4178  *              @since 1.3.0
 4179  * @param flag
 4180  *        Reserved for future usage, set to 0.
 4181  * @return
 4182  *      1 success, < 0 on error
 4183  * @since 0.6.12
 4184  */
 4185 int el_torito_set_isolinux_options(ElToritoBootImage *bootimg,
 4186                                    int options, int flag);
 4187 
 4188 /** 
 4189  * Get the options as of el_torito_set_isolinux_options().
 4190  *
 4191  * @param bootimg
 4192  *      The image to inquire
 4193  * @param flag
 4194  *        Reserved for future usage, set to 0.
 4195  * @return
 4196  *      >= 0 returned option bits , <0 = error
 4197  *
 4198  * @since 0.6.32
 4199  */
 4200 int el_torito_get_isolinux_options(ElToritoBootImage *bootimg, int flag);
 4201 
 4202 /** Deprecated:
 4203  * Specifies that this image needs to be patched. This involves the writing
 4204  * of a 16 bytes boot information table at offset 8 of the boot image file.
 4205  * The original boot image file won't be modified.
 4206  * This is needed for isolinux boot images.
 4207  *
 4208  * @since 0.6.2
 4209  * @deprecated Use el_torito_set_isolinux_options() instead
 4210  */
 4211 void el_torito_patch_isolinux_image(ElToritoBootImage *bootimg);
 4212 
 4213 /**
 4214  * Obtain a copy of the eventually loaded first 32768 bytes of the imported
 4215  * session, the System Area.
 4216  * It will be written to the start of the next session unless it gets
 4217  * overwritten by iso_write_opts_set_system_area().
 4218  *
 4219  * @param img
 4220  *        The image to be inquired.
 4221  * @param data
 4222  *        A byte array of at least 32768 bytes to take the loaded bytes.
 4223  * @param options
 4224  *        The option bits which will be applied if not overridden by
 4225  *        iso_write_opts_set_system_area(). See there.
 4226  * @param flag
 4227  *        Bitfield for control purposes, unused yet, submit 0
 4228  * @return
 4229  *        1 on success, 0 if no System Area was loaded, < 0 error.
 4230  * @since 0.6.30
 4231  */
 4232 int iso_image_get_system_area(IsoImage *img, char data[32768],
 4233                               int *options, int flag);
 4234 
 4235 /**
 4236  * The maximum length of a single line in the output of function
 4237  * iso_image_report_system_area() and iso_image_report_el_torito().
 4238  * This number includes the trailing 0.
 4239  * @since 1.3.8
 4240  */
 4241 #define ISO_MAX_SYSAREA_LINE_LENGTH 4096
 4242 
 4243 /**
 4244  * Texts which describe the output format of iso_image_report_system_area().
 4245  * They are publicly defined here only as part of the API description.
 4246  * Do not use these macros in your application but rather call
 4247  * iso_image_report_system_area() with flag bit0.
 4248  */
 4249 #define ISO_SYSAREA_REPORT_DOC \
 4250 \
 4251 "Report format for recognized System Area data.", \
 4252 "", \
 4253 "No text will be reported if no System Area was loaded or if it was", \
 4254 "entirely filled with 0-bytes.", \
 4255 "Else there will be at least these three lines:", \
 4256 "  System area options: hex", \
 4257 "       see libisofs.h, parameter of iso_write_opts_set_system_area().", \
 4258 "  System area summary: word ... word", \
 4259 "       human readable interpretation of system area options and other info", \
 4260 "       The words are from the set:", \
 4261 "        { MBR, CHRP, PReP, GPT, APM, MIPS-Big-Endian, MIPS-Little-Endian,", \
 4262 "          SUN-SPARC-Disk-Label, HP-PA-PALO, DEC-Alpha, ", \
 4263 "          protective-msdos-label, isohybrid, grub2-mbr,", \
 4264 "          cyl-align-{auto,on,off,all}, not-recognized, }", \
 4265 "        The acronyms indicate boot data for particular hardware/firmware.", \
 4266 "        protective-msdos-label is an MBR conformant to specs of GPT.", \
 4267 "        isohybrid is an MBR implementing ISOLINUX isohybrid functionality.", \
 4268 "        grub2-mbr is an MBR with GRUB2 64 bit address patching.", \
 4269 "        cyl-align-on indicates that the ISO image MBR partition ends at a", \
 4270 "        cylinder boundary. cyl-align-all means that more MBR partitions", \
 4271 "        exist and all end at a cylinder boundary.", \
 4272 "        not-recognized tells about unrecognized non-zero system area data.", \
 4273 "  ISO image size/512 : decimal", \
 4274 "       size of ISO image in block units of 512 bytes.", \
 4275 ""
 4276 #define ISO_SYSAREA_REPORT_DOC_MBR \
 4277 \
 4278 "If an MBR is detected, with at least one partition entry of non-zero size,", \
 4279 "then there may be:", \
 4280 "  Partition offset   : decimal", \
 4281 "       if not 0 then a second ISO 9660 superblock was found to which", \
 4282 "       MBR partition 1 or GPT partition 1 is pointing.", \
 4283 "  MBR heads per cyl  : decimal", \
 4284 "       conversion factor between MBR C/H/S address and LBA. 0=inconsistent.", \
 4285 "  MBR secs per head  : decimal", \
 4286 "       conversion factor between MBR C/H/S address and LBA. 0=inconsistent.", \
 4287 "  MBR partition table:   N Status  Type        Start        Blocks", \
 4288 "       headline for MBR partition table.", \
 4289 "  MBR partition      :   X    hex   hex      decimal       decimal", \
 4290 "       gives partition number, status byte, type byte, start block,", \
 4291 "       and number of blocks. 512 bytes per block.", \
 4292 "  MBR partition path :   X  path", \
 4293 "       the path of a file in the ISO image which begins at the partition", \
 4294 "       start block of partition X.", \
 4295 "  PReP boot partition: decimal decimal", \
 4296 "       gives start block and size of a PReP boot partition in ISO 9660", \
 4297 "       block units of 2048 bytes.", \
 4298 ""
 4299 #define ISO_SYSAREA_REPORT_DOC_GPT1 \
 4300 \
 4301 "GUID Partition Table can coexist with MBR:", \
 4302 "  GPT                :   N  Info", \
 4303 "       headline for GPT partition table. The fields are too wide for a", \
 4304 "       neat table. So they are listed with a partition number and a text.", \
 4305 "  GPT CRC should be  :      <hex>  to match first 92 GPT header block bytes", \
 4306 "  GPT CRC found      :      <hex>  matches all 512 bytes of GPT header block", \
 4307 "       libisofs-1.2.4 to 1.2.8 had a bug with the GPT header CRC. So", \
 4308 "       libisofs is willing to recognize GPT with the buggy CRC. These", \
 4309 "       two lines inform that most partition editors will not accept it.", \
 4310 "  GPT array CRC wrong:      should be <hex>, found <hex>", \
 4311 "       GPT entry arrays are accepted even if their CRC does not match.", \
 4312 "       In this case, both CRCs are reported by this line.", \
 4313 "  GPT backup problems:      text", \
 4314 "       reports about inconsistencies between main GPT and backup GPT.", \
 4315 "       The statements are comma separated:", \
 4316 "          Implausible header LBA <decimal>", \
 4317 "          Cannot read header block at 2k LBA <decimal>", \
 4318 "          Not a GPT 1.0 header of 92 bytes for 128 bytes per entry", \
 4319 "          Head CRC <hex> wrong. Should be <hex>", \
 4320 "          Head CRC <hex> wrong. Should be <hex>. Matches all 512 block bytes", \
 4321 "          Disk GUID differs (<hex_digits>)", \
 4322 "          Cannot read array block at 2k LBA <decimal>", \
 4323 "          Array CRC <hex> wrong. Should be <hex>", \
 4324 "          Entries differ for partitions <decimal> [... <decimal>]", \
 4325 "  GPT disk GUID      :      hex_digits", \
 4326 "       32 hex digits giving the byte string of the disk's GUID", \
 4327 "  GPT entry array    :      decimal  decimal  word", \
 4328 "       start block of partition entry array and number of entries. 512 bytes", \
 4329 "       per block. The word may be \"separated\" if partitions are disjoint,", \
 4330 "       \"overlapping\" if they are not. In future there may be \"nested\"", \
 4331 "       as special case where all overlapping partitions are superset and", \
 4332 "       subset, and \"covering\" as special case of disjoint partitions", \
 4333 "       covering the whole GPT block range for partitions.", \
 4334 "  GPT lba range      :      decimal  decimal  decimal", \
 4335 "       addresses of first payload block, last payload block, and of the", \
 4336 "       GPT backup header block. 512 bytes per block." \
 4337 
 4338 #define ISO_SYSAREA_REPORT_DOC_GPT2 \
 4339 \
 4340 "  GPT partition name :   X  hex_digits", \
 4341 "       up to 144 hex digits giving the UTF-16LE name byte string of", \
 4342 "       partition X. Trailing 16 bit 0-characters are omitted.", \
 4343 "  GPT partname local :   X  text", \
 4344 "       the name of partition X converted to the local character set.", \
 4345 "       This line may be missing if the name cannot be converted, or is", \
 4346 "       empty.", \
 4347 "  GPT partition GUID :   X   hex_digits", \
 4348 "       32 hex digits giving the byte string of the GUID of partition X.", \
 4349 "  GPT type GUID      :   X   hex_digits", \
 4350 "       32 hex digits giving the byte string of the type GUID of partition X.", \
 4351 "  GPT partition flags:   X   hex", \
 4352 "       64 flag bits of partition X in hex representation.", \
 4353 "       Known bit meanings are:", \
 4354 "         bit0 = \"System Partition\" Do not alter.", \
 4355 "         bit2 = Legacy BIOS bootable (MBR partition type 0x80)", \
 4356 "         bit60= read-only", \
 4357 "  GPT start and size :   X  decimal  decimal", \
 4358 "       start block and number of blocks of partition X. 512 bytes per block.", \
 4359 "  GPT partition path :   X  path", \
 4360 "       the path of a file in the ISO image which begins at the partition", \
 4361 "       start block of partition X.", \
 4362 ""
 4363 #define ISO_SYSAREA_REPORT_DOC_APM \
 4364 \
 4365 "Apple partition map can coexist with MBR and GPT:", \
 4366 "  APM                :   N  Info", \
 4367 "       headline for human readers.", \
 4368 "  APM block size     :      decimal", \
 4369 "       block size of Apple Partition Map. 512 or 2048. This applies to", \
 4370 "       start address and size of all partitions in the APM.", \
 4371 "  APM gap fillers    :      decimal", \
 4372 "       tells the number of partitions with name \"Gap[0-9[0-9]]\" and type", \
 4373 "       \"ISO9660_data\".", \
 4374 "  APM partition name :   X   text", \
 4375 "       the name of partition X. Up to 32 characters.", \
 4376 "  APM partition type :   X   text", \
 4377 "       the type string of partition X. Up to 32 characters.", \
 4378 "  APM start and size :   X   decimal  decimal", \
 4379 "       start block and number of blocks of partition X.", \
 4380 "  APM partition path :   X   path", \
 4381 "       the path of a file in the ISO image which begins at the partition", \
 4382 "       start block of partition X.", \
 4383 ""
 4384 #define ISO_SYSAREA_REPORT_DOC_MIPS \
 4385 \
 4386 "If a MIPS Big Endian Volume Header is detected, there may be:", \
 4387 "  MIPS-BE volume dir :   N      Name       Block       Bytes", \
 4388 "       headline for human readers.", \
 4389 "  MIPS-BE boot entry :   X  upto8chr     decimal     decimal", \
 4390 "       tells name, 512-byte block address, and byte count of boot entry X.", \
 4391 "  MIPS-BE boot path  :   X  path", \
 4392 "       tells the path to the boot image file in the ISO image which belongs", \
 4393 "       to the block address given by boot entry X.", \
 4394 "", \
 4395 "If a DEC Boot Block for MIPS Little Endian is detected, there may be:", \
 4396 "  MIPS-LE boot map   :   LoadAddr    ExecAddr SegmentSize SegmentStart", \
 4397 "       headline for human readers.", \
 4398 "  MIPS-LE boot params:    decimal     decimal     decimal     decimal", \
 4399 "       tells four numbers which are originally derived from the ELF header", \
 4400 "       of the boot file. The first two are counted in bytes, the other two", \
 4401 "       are counted in blocks of 512 bytes.", \
 4402 "  MIPS-LE boot path  : path", \
 4403 "       tells the path to the boot file in the ISO image which belongs to the", \
 4404 "       address given by SegmentStart.", \
 4405 "  MIPS-LE elf offset : decimal", \
 4406 "       tells the relative 512-byte block offset inside the boot file:", \
 4407 "         SegmentStart - FileStartBlock", \
 4408 ""
 4409 #define ISO_SYSAREA_REPORT_DOC_SUN \
 4410 \
 4411 "If a SUN SPARC Disk Label is present:", \
 4412 "  SUN SPARC disklabel: text", \
 4413 "       tells the disk label text.", \
 4414 "  SUN SPARC secs/head: decimal", \
 4415 "       tells the number of sectors per head.", \
 4416 "  SUN SPARC heads/cyl: decimal", \
 4417 "       tells the number of heads per cylinder.", \
 4418 "  SUN SPARC partmap  :   N   IdTag   Perms    StartCyl   NumBlock", \
 4419 "       headline for human readers.", \
 4420 "  SUN SPARC partition:   X   hex     hex       decimal    decimal", \
 4421 "       gives partition number, type word, permission word, start cylinder,", \
 4422 "       and number of of blocks. 512 bytes per block. Type word may be: ", \
 4423 "       0=unused, 2=root partition with boot, 4=user partition.", \
 4424 "       Permission word is 0x10 = read-only.", \
 4425 "  SPARC GRUB2 core   : decimal  decimal", \
 4426 "       tells byte address and byte count of the GRUB2 SPARC core file.", \
 4427 "  SPARC GRUB2 path   : path", \
 4428 "       tells the path to the data file in the ISO image which belongs to the", \
 4429 "       address given by core.", \
 4430 ""
 4431 #define ISO_SYSAREA_REPORT_DOC_HPPA \
 4432 \
 4433 "If a HP-PA PALO boot sector version 4 or 5 is present:", \
 4434 "  PALO header version: decimal", \
 4435 "       tells the PALO header version: 4 or 5.", \
 4436 "  HP-PA cmdline      : text", \
 4437 "       tells the command line for the kernels.", \
 4438 "  HP-PA boot files   :   ByteAddr    ByteSize  Path", \
 4439 "       headline for human readers.", \
 4440 "  HP-PA 32-bit kernel: decimal  decimal  path", \
 4441 "       tells start byte, byte count, and file path of the 32-bit kernel.", \
 4442 "  HP-PA 64-bit kernel: decimal  decimal  path", \
 4443 "       tells the same for the 64-bit kernel.", \
 4444 "  HP-PA ramdisk      : decimal  decimal  path", \
 4445 "       tells the same for the ramdisk file.", \
 4446 "  HP-PA bootloader   : decimal  decimal  path", \
 4447 "       tells the same for the bootloader file.", \
 4448 ""
 4449 #define ISO_SYSAREA_REPORT_DOC_ALPHA \
 4450 "If a DEC Alpha SRM boot sector is present:", \
 4451 "  DEC Alpha ldr size : decimal", \
 4452 "       tells the number of 512-byte blocks in DEC Alpha Secondary Bootstrap", \
 4453 "       Loader file.", \
 4454 "  DEC Alpha ldr adr  : decimal", \
 4455 "       tells the start of the loader file in units of 512-byte blocks.", \
 4456 "  DEC Alpha ldr path : path", \
 4457 "       tells the path of a file in the ISO image which starts at the loader", \
 4458 "       start address."
 4459 
 4460 /**
 4461  * Obtain an array of texts describing the detected properties of the
 4462  * eventually loaded System Area.
 4463  * The array will be NULL if no System Area was loaded. It will be non-NULL
 4464  * with zero line count if the System Area was loaded and contains only
 4465  * 0-bytes. 
 4466  * Else it will consist of lines as described in ISO_SYSAREA_REPORT_DOC above.
 4467  *
 4468  * File paths and other long texts are reported as "(too long to show here)"
 4469  * if their length plus preceding text plus trailing 0-byte exceeds the
 4470  * line length limit of ISO_MAX_SYSAREA_LINE_LENGTH bytes.
 4471  * Texts which may contain whitespace or unprintable characters will start
 4472  * at fixed positions and extend to the end of the line.
 4473  * Note that newline characters may well appearing in the middle of a "line".
 4474  *
 4475  * @param image
 4476  *        The image to be inquired.
 4477  * @param reply
 4478  *        Will return an array of pointers to the result text lines or NULL.
 4479  *        Dispose a non-NULL reply by a call to iso_image_report_system_area()
 4480  *        with flag bit15, when no longer needed.
 4481  *        Be prepared for a long text with up to ISO_MAX_SYSAREA_LINE_LENGTH
 4482  *        characters per line.
 4483  * @param line_count
 4484  *        Will return the number of valid pointers in reply.
 4485  * @param flag
 4486  *        Bitfield for control purposes
 4487  *          bit0= do not report system area but rather reply a copy of
 4488  *                above text line arrays ISO_SYSAREA_REPORT_DOC*.
 4489  *                With this bit it is permissible to submit image as NULL.
 4490  *         bit15= dispose result from previous call.
 4491  * @return
 4492  *        1 on success, 0 if no System Area was loaded, < 0 error.
 4493  * @since 1.3.8
 4494  */
 4495 int iso_image_report_system_area(IsoImage *image,
 4496                                  char ***reply, int *line_count, int flag);
 4497 
 4498 /**
 4499  * Text which describes the output format of iso_image_report_el_torito().
 4500  * It is publicly defined here only as part of the API description.
 4501  * Do not use it as macro in your application but rather call
 4502  * iso_image_report_el_torito() with flag bit0.
 4503  */
 4504 #define ISO_ELTORITO_REPORT_DOC \
 4505 "Report format for recognized El Torito boot information.", \
 4506 "", \
 4507 "No text will be reported if no El Torito information was found.", \
 4508 "Else there will be at least these three lines", \
 4509 "  El Torito catalog  : decimal  decimal", \
 4510 "       tells the block address and number of 2048-blocks of the boot catalog.", \
 4511 "  El Torito images   :   N  Pltf  B   Emul  Ld_seg  Hdpt  Ldsiz         LBA", \
 4512 "       is the headline of the boot image list.", \
 4513 "  El Torito boot img :   X  word  char  word  hex  hex  decimal  decimal", \
 4514 "       tells about boot image number X:", \
 4515 "       - Platform Id: \"BIOS\", \"PPC\", \"Mac\", \"UEFI\" or a hex number.", \
 4516 "       - Bootability: either \"y\" or \"n\".", \
 4517 "       - Emulation: \"none\", \"fd1.2\", \"fd1.4\", \"fd2.8\", \"hd\"", \
 4518 "                    for no emulation, three floppy MB sizes, hard disk.", \
 4519 "       - Load Segment: start offset in boot image. 0x0000 means 0x07c0.", \
 4520 "       - Hard disk emulation partition type: MBR partition type code.", \
 4521 "       - Load size: number of 512-blocks to load with emulation mode \"none\".", \
 4522 "       - LBA: start block number in ISO filesystem (2048-block).", \
 4523 "", \
 4524 "The following lines appear conditionally:", \
 4525 "  El Torito cat path : iso_rr_path", \
 4526 "       tells the path to the data file in the ISO image which belongs to", \
 4527 "       the block address where the boot catalog starts.", \
 4528 "       (This line is not reported if no path points to that block.)", \
 4529 "  El Torito img path :   X  iso_rr_path", \
 4530 "       tells the path to the data file in the ISO image which belongs to", \
 4531 "       the block address given by LBA of boot image X.", \
 4532 "       (This line is not reported if no path points to that block.)", \
 4533 "  El Torito img opts :   X  word ... word", \
 4534 "       tells the presence of extra features:", \
 4535 "         \"boot-info-table\"    image got boot info table patching.", \
 4536 "         \"isohybrid-suitable\" image is suitable for ISOLINUX isohybrid MBR.", \
 4537 "         \"grub2-boot-info\"    image got GRUB2 boot info patching.", \
 4538 "       (This line is not reported if no such options were detected.)", \
 4539 "  El Torito id string:   X  hex_digits", \
 4540 "       tells the id string of the catalog section which hosts boot image X.", \
 4541 "       (This line is not reported if the id string is all zero.)", \
 4542 "  El Torito sel crit :   X  hex_digits", \
 4543 "       tells the selection criterion of boot image X.", \
 4544 "       (This line is not reported if the criterion is all zero.)", \
 4545 "  El Torito img blks :   X  decimal", \
 4546 "       gives an upper limit of the number of 2048-blocks in the boot image", \
 4547 "       if it is not accessible via a path in the ISO directory tree.", \
 4548 "       The boot image is supposed to end before the start block of any", \
 4549 "       other entity of the ISO filesystem.", \
 4550 "       (This line is not reported if no limiting entity is found.)", \
 4551 "  El Torito hdsiz/512:   X  decimal", \
 4552 "       gives with a boot image of emulation type \"hd\" the lowest block", \
 4553 "       number which is above any partition end in the boot image's MBR", \
 4554 "       partition table. This can be considered the claimed size of the", \
 4555 "       emulated hard disk given in blocks of 512 bytes.", \
 4556 "       (This line is not reported if no partition is found in the image.)", \
 4557 ""
 4558 
 4559 /**
 4560  * Obtain an array of texts describing the detected properties of the
 4561  * eventually loaded El Torito boot information.
 4562  * The array will be NULL if no El Torito info was loaded.
 4563  * Else it will consist of lines as described in ISO_ELTORITO_REPORT_DOC above.
 4564  *
 4565  * The lines have the same length restrictions and whitespace rules as the ones
 4566  * returned by iso_image_report_system_area().
 4567  * 
 4568  * @param image
 4569  *        The image to be inquired.
 4570  * @param reply
 4571  *        Will return an array of pointers to the result text lines or NULL.
 4572  *        Dispose a non-NULL reply by a call to iso_image_report_el_torito()
 4573  *        with flag bit15, when no longer needed.
 4574  *        Be prepared for a long text with up to ISO_MAX_SYSAREA_LINE_LENGTH
 4575  *        characters per line.
 4576  * @param line_count
 4577  *        Will return the number of valid pointers in reply.
 4578  * @param flag
 4579  *        Bitfield for control purposes
 4580  *          bit0= do not report system area but rather reply a copy of
 4581  *                above text line array ISO_ELTORITO_REPORT_DOC.
 4582  *                With this bit it is permissible to submit image as NULL.
 4583  *         bit15= dispose result from previous call.
 4584  * @return
 4585  *        1 on success, 0 if no El Torito information was loaded, < 0 error.
 4586  * @since 1.3.8
 4587  */
 4588 int iso_image_report_el_torito(IsoImage *image,
 4589                                char ***reply, int *line_count, int flag);
 4590 
 4591 
 4592 /**
 4593  * Compute a CRC number as expected in the GPT main and backup header blocks.
 4594  *
 4595  * The CRC at byte offset 88 is supposed to cover the array of partition
 4596  * entries.
 4597  * The CRC at byte offset 16 is supposed to cover the readily produced
 4598  * first 92 bytes of the header block while its bytes 16 to 19 are still
 4599  * set to 0.
 4600  * Block size is 512 bytes. Numbers are stored little-endian.
 4601  * See doc/boot_sectors.txt for the byte layout of GPT.
 4602  *
 4603  * This might be helpful for applications which want to manipulate GPT
 4604  * directly. The function is in libisofs/system_area.c and self-contained.
 4605  * So if you want to copy+paste it under the license of that file: Be invited.
 4606  * Be warned that this implementation works bit-wise and thus is much slower
 4607  * than table-driven ones. For less than 32 KiB, it fully suffices, though.
 4608  *
 4609  * @param data
 4610  *        The memory buffer with the data to sum up.
 4611  * @param count
 4612  *        Number of bytes in data.
 4613  * @param flag
 4614  *        Bitfield for control purposes. Submit 0.
 4615  * @return
 4616  *        The CRC of data. 
 4617  * @since 1.3.8
 4618  */
 4619 uint32_t iso_crc32_gpt(unsigned char *data, int count, int flag);
 4620 
 4621 /**
 4622  * Add a MIPS boot file path to the image.
 4623  * Up to 15 such files can be written into a MIPS Big Endian Volume Header
 4624  * if this is enabled by value 1 in iso_write_opts_set_system_area() option
 4625  * bits 2 to 7. 
 4626  * A single file can be written into a DEC Boot Block if this is enabled by
 4627  * value 2 in iso_write_opts_set_system_area() option bits 2 to 7. So only
 4628  * the first added file gets into effect with this system area type.
 4629  * The data files which shall serve as MIPS boot files have to be brought into
 4630  * the image by the normal means.
 4631  * @param image
 4632  *        The image to be manipulated.
 4633  * @param path
 4634  *        Absolute path of the boot file in the ISO 9660 Rock Ridge tree.
 4635  * @param flag
 4636  *        Bitfield for control purposes, unused yet, submit 0
 4637  * @return
 4638  *        1 on success, < 0 error
 4639  * @since 0.6.38
 4640  */
 4641 int iso_image_add_mips_boot_file(IsoImage *image, char *path, int flag);
 4642 
 4643 /**
 4644  * Obtain the number of added MIPS Big Endian boot files and pointers to
 4645  * their paths in the ISO 9660 Rock Ridge tree.
 4646  * @param image
 4647  *        The image to be inquired.
 4648  * @param paths
 4649  *        An array of pointers to be set to the registered boot file paths.
 4650  *        This are just pointers to data inside IsoImage. Do not free() them.
 4651  *        Eventually make own copies of the data before manipulating the image.
 4652  * @param flag
 4653  *        Bitfield for control purposes, unused yet, submit 0
 4654  * @return
 4655  *        >= 0 is the number of valid path pointers , <0 means error
 4656  * @since 0.6.38
 4657  */
 4658 int iso_image_get_mips_boot_files(IsoImage *image, char *paths[15], int flag);
 4659 
 4660 /**
 4661  * Clear the list of MIPS Big Endian boot file paths.
 4662  * @param image
 4663  *        The image to be manipulated.
 4664  * @param flag
 4665  *        Bitfield for control purposes, unused yet, submit 0
 4666  * @return
 4667  *        1 is success , <0 means error
 4668  * @since 0.6.38
 4669  */
 4670 int iso_image_give_up_mips_boot(IsoImage *image, int flag);
 4671 
 4672 /**
 4673  * Designate a data file in the ISO image of which the position and size
 4674  * shall be written after the SUN Disk Label. The position is written as
 4675  * 64-bit big-endian number to byte position 0x228. The size is written
 4676  * as 32-bit big-endian to 0x230.
 4677  * This setting has an effect only if system area type is set to 3
 4678  * with iso_write_opts_set_system_area(). 
 4679  *
 4680  * @param img
 4681  *        The image to be manipulated.
 4682  * @param sparc_core
 4683  *        The IsoFile which shall be mentioned after the SUN Disk label.
 4684  *        NULL is a permissible value. It disables this feature.
 4685  * @param flag
 4686  *        Bitfield for control purposes, unused yet, submit 0
 4687  * @return
 4688  *        1 is success , <0 means error
 4689  * @since 1.3.0
 4690  */
 4691 int iso_image_set_sparc_core(IsoImage *img, IsoFile *sparc_core, int flag);
 4692 
 4693 /**
 4694  * Obtain the current setting of iso_image_set_sparc_core().
 4695  *
 4696  * @param img
 4697  *        The image to be inquired.
 4698  * @param sparc_core
 4699  *        Will return a pointer to the IsoFile (or NULL, which is not an error)
 4700  * @param flag
 4701  *        Bitfield for control purposes, unused yet, submit 0
 4702  * @return
 4703  *        1 is success , <0 means error
 4704  * @since 1.3.0
 4705  */
 4706 int iso_image_get_sparc_core(IsoImage *img, IsoFile **sparc_core, int flag);
 4707 
 4708 /**
 4709  * Define a command line and submit the paths of four mandatory files for
 4710  * production of a HP-PA PALO boot sector for PA-RISC machines.
 4711  * The paths must lead to already existing data files in the ISO image
 4712  * which stay with these paths until image production.
 4713  *
 4714  * @param img
 4715  *        The image to be manipulated.
 4716  * @param cmdline
 4717  *        Up to 127 characters of command line.
 4718  * @param bootloader
 4719  *        Absolute path of a data file in the ISO image.
 4720  * @param kernel_32
 4721  *        Absolute path of a data file in the ISO image which serves as
 4722  *        32 bit kernel.
 4723  * @param kernel_64
 4724  *        Absolute path of a data file in the ISO image which serves as
 4725  *        64 bit kernel.
 4726  * @param ramdisk
 4727  *        Absolute path of a data file in the ISO image.
 4728  * @param flag
 4729  *        Bitfield for control purposes
 4730  *         bit0= Let NULL parameters free the corresponding image properties.
 4731  *               Else only the non-NULL parameters of this call have an effect
 4732  * @return
 4733  *        1 is success , <0 means error
 4734  * @since 1.3.8
 4735  */
 4736 int iso_image_set_hppa_palo(IsoImage *img, char *cmdline, char *bootloader,
 4737                             char *kernel_32, char *kernel_64, char *ramdisk,
 4738                             int flag);
 4739 
 4740 /**
 4741  * Inquire the current settings of iso_image_set_hppa_palo().
 4742  * Do not free() the returned pointers.
 4743  *
 4744  * @param img
 4745  *        The image to be inquired.
 4746  * @param cmdline
 4747  *        Will return the command line.
 4748  * @param bootloader
 4749  *        Will return the absolute path of the bootloader file.
 4750  * @param kernel_32
 4751  *        Will return the absolute path of the 32 bit kernel file.
 4752  * @param kernel_64
 4753  *        Will return the absolute path of the 64 bit kernel file.
 4754  * @param ramdisk
 4755  *        Will return the absolute path of the RAM disk file.
 4756  * @return
 4757  *        1 is success , <0 means error
 4758  * @since 1.3.8
 4759  */
 4760 int iso_image_get_hppa_palo(IsoImage *img, char **cmdline, char **bootloader,
 4761                             char **kernel_32, char **kernel_64, char **ramdisk);
 4762 
 4763 
 4764 /**
 4765  * Submit the path of the DEC Alpha Secondary Bootstrap Loader file.
 4766  * The path must lead to an already existing data file in the ISO image
 4767  * which stays with this path until image production.
 4768  * This setting has an effect only if system area type is set to 6
 4769  * with iso_write_opts_set_system_area().
 4770  *
 4771  * @param img
 4772  *        The image to be manipulated.
 4773  * @param boot_loader_path
 4774  *        Absolute path of a data file in the ISO image.
 4775  *        Submit NULL to free this image property.
 4776  * @param flag
 4777  *        Bitfield for control purposes. Unused yet. Submit 0.
 4778  * @return
 4779  *        1 is success , <0 means error
 4780  * @since 1.4.0
 4781  */
 4782 int iso_image_set_alpha_boot(IsoImage *img, char *boot_loader_path, int flag);
 4783 
 4784 /**
 4785  * Inquire the path submitted by iso_image_set_alpha_boot()
 4786  * Do not free() the returned pointer.
 4787  *
 4788  * @param img
 4789  *        The image to be inquired.
 4790  * @param boot_loader_path
 4791  *        Will return the path. NULL if none is currently submitted.
 4792  * @return
 4793  *        1 is success , <0 means error
 4794  * @since 1.4.0
 4795  */
 4796 int iso_image_get_alpha_boot(IsoImage *img, char **boot_loader_path);
 4797 
 4798 
 4799 /**
 4800  * Increments the reference counting of the given node.
 4801  *
 4802  * @since 0.6.2
 4803  */
 4804 void iso_node_ref(IsoNode *node);
 4805 
 4806 /**
 4807  * Decrements the reference counting of the given node.
 4808  * If it reach 0, the node is free, and, if the node is a directory,
 4809  * its children will be unref() too.
 4810  *
 4811  * @since 0.6.2
 4812  */
 4813 void iso_node_unref(IsoNode *node);
 4814 
 4815 /**
 4816  * Get the type of an IsoNode.
 4817  *
 4818  * @since 0.6.2
 4819  */
 4820 enum IsoNodeType iso_node_get_type(IsoNode *node);
 4821 
 4822 /**
 4823  * Class of functions to handle particular extended information. A function
 4824  * instance acts as an identifier for the type of the information. Structs
 4825  * with same information type must use a pointer to the same function.
 4826  *
 4827  * @param data
 4828  *     Attached data
 4829  * @param flag
 4830  *     What to do with the data. At this time the following values are
 4831  *     defined:
 4832  *      -> 1 the data must be freed
 4833  * @return
 4834  *     1 in any case.
 4835  *
 4836  * @since 0.6.4
 4837  */
 4838 typedef int (*iso_node_xinfo_func)(void *data, int flag);
 4839 
 4840 /**
 4841  * Add extended information to the given node. Extended info allows
 4842  * applications (and libisofs itself) to add more information to an IsoNode.
 4843  * You can use this facilities to associate temporary information with a given
 4844  * node. This information is not written into the ISO 9660 image on media
 4845  * and thus does not persist longer than the node memory object.
 4846  *
 4847  * Each node keeps a list of added extended info, meaning you can add several
 4848  * extended info data to each node. Each extended info you add is identified
 4849  * by the proc parameter, a pointer to a function that knows how to manage
 4850  * the external info data. Thus, in order to add several types of extended
 4851  * info, you need to define a "proc" function for each type.
 4852  *
 4853  * @param node
 4854  *      The node where to add the extended info
 4855  * @param proc
 4856  *      A function pointer used to identify the type of the data, and that
 4857  *      knows how to manage it
 4858  * @param data
 4859  *      Extended info to add.
 4860  * @return
 4861  *      1 if success, 0 if the given node already has extended info of the
 4862  *      type defined by the "proc" function, < 0 on error
 4863  *
 4864  * @since 0.6.4
 4865  */
 4866 int iso_node_add_xinfo(IsoNode *node, iso_node_xinfo_func proc, void *data);
 4867 
 4868 /**
 4869  * Remove the given extended info (defined by the proc function) from the
 4870  * given node.
 4871  *
 4872  * @return
 4873  *      1 on success, 0 if node does not have extended info of the requested
 4874  *      type, < 0 on error
 4875  *
 4876  * @since 0.6.4
 4877  */
 4878 int iso_node_remove_xinfo(IsoNode *node, iso_node_xinfo_func proc);
 4879 
 4880 /**
 4881  * Remove all extended information  from the given node.
 4882  *
 4883  * @param node
 4884  *      The node where to remove all extended info
 4885  * @param flag
 4886  *      Bitfield for control purposes, unused yet, submit 0
 4887  * @return
 4888  *      1 on success, < 0 on error
 4889  *      
 4890  * @since 1.0.2
 4891  */
 4892 int iso_node_remove_all_xinfo(IsoNode *node, int flag);
 4893 
 4894 /**
 4895  * Get the given extended info (defined by the proc function) from the
 4896  * given node.
 4897  *
 4898  * @param node
 4899  *      The node to inquire
 4900  * @param proc
 4901  *      The function pointer which serves as key
 4902  * @param data
 4903  *      Will after successful call point to the xinfo data corresponding
 4904  *      to the given proc. This is a pointer, not a feeable data copy.
 4905  * @return
 4906  *      1 on success, 0 if node does not have extended info of the requested
 4907  *      type, < 0 on error
 4908  *
 4909  * @since 0.6.4
 4910  */
 4911 int iso_node_get_xinfo(IsoNode *node, iso_node_xinfo_func proc, void **data);
 4912 
 4913 
 4914 /**
 4915  * Get the next pair of function pointer and data of an iteration of the
 4916  * list of extended information. Like:
 4917  *     iso_node_xinfo_func proc;
 4918  *     void *handle = NULL, *data; 
 4919  *     while (iso_node_get_next_xinfo(node, &handle, &proc, &data) == 1) {
 4920  *         ... make use of proc and data ...
 4921  *     }
 4922  * The iteration allocates no memory. So you may end it without any disposal
 4923  * action.
 4924  * IMPORTANT: Do not continue iterations after manipulating the extended
 4925  *            information of a node. Memory corruption hazard !
 4926  * @param node
 4927  *      The node to inquire
 4928  * @param  handle
 4929  *      The opaque iteration handle. Initialize iteration by submitting
 4930  *      a pointer to a void pointer with value NULL.
 4931  *      Do not alter its content until iteration has ended.
 4932  * @param proc
 4933  *      The function pointer which serves as key
 4934  * @param data
 4935  *      Will be filled with the extended info corresponding to the given proc
 4936  *      function
 4937  * @return
 4938  *      1 on success
 4939  *      0 if iteration has ended (proc and data are invalid then)
 4940  *      < 0 on error
 4941  *
 4942  * @since 1.0.2
 4943  */
 4944 int iso_node_get_next_xinfo(IsoNode *node, void **handle,
 4945                             iso_node_xinfo_func *proc, void **data);
 4946 
 4947 
 4948 /**
 4949  * Class of functions to clone extended information. A function instance gets
 4950  * associated to a particular iso_node_xinfo_func instance by function
 4951  * iso_node_xinfo_make_clonable(). This is a precondition to have IsoNode
 4952  * objects clonable which carry data for a particular iso_node_xinfo_func.
 4953  *
 4954  * @param old_data
 4955  *     Data item to be cloned
 4956  * @param new_data
 4957  *     Shall return the cloned data item
 4958  * @param flag
 4959  *     Unused yet, submit 0
 4960  *     The function shall return ISO_XINFO_NO_CLONE on unknown flag bits.
 4961  * @return
 4962  *     > 0 number of allocated bytes
 4963  *       0 no size info is available
 4964  *     < 0 error
 4965  * 
 4966  * @since 1.0.2
 4967  */
 4968 typedef int (*iso_node_xinfo_cloner)(void *old_data, void **new_data,int flag);
 4969 
 4970 /**
 4971  * Associate a iso_node_xinfo_cloner to a particular class of extended
 4972  * information in order to make it clonable.
 4973  *
 4974  * @param proc
 4975  *     The key and disposal function which identifies the particular
 4976  *     extended information class.
 4977  * @param cloner
 4978  *     The cloner function which shall be associated with proc.
 4979  * @param flag
 4980  *     Unused yet, submit 0
 4981  * @return
 4982  *     1 success, < 0 error
 4983  * 
 4984  * @since 1.0.2
 4985  */
 4986 int iso_node_xinfo_make_clonable(iso_node_xinfo_func proc,
 4987                                  iso_node_xinfo_cloner cloner, int flag);
 4988 
 4989 /**
 4990  * Inquire the registered cloner function for a particular class of
 4991  * extended information.
 4992  *
 4993  * @param proc
 4994  *     The key and disposal function which identifies the particular
 4995  *     extended information class.
 4996  * @param cloner
 4997  *     Will return the cloner function which is associated with proc, or NULL.
 4998  * @param flag
 4999  *     Unused yet, submit 0
 5000  * @return
 5001  *     1 success, 0 no cloner registered for proc, < 0 error
 5002  * 
 5003  * @since 1.0.2
 5004  */
 5005 int iso_node_xinfo_get_cloner(iso_node_xinfo_func proc,
 5006                               iso_node_xinfo_cloner *cloner, int flag);
 5007 
 5008 /**
 5009  * Set the name of a node. Note that if the node is already added to a dir
 5010  * this can fail if dir already contains a node with the new name.
 5011  * The IsoImage context defines a maximum permissible name length and a mode
 5012  * how to react on oversized names. See iso_image_set_truncate_mode().
 5013  *
 5014  * @param image
 5015  *      The image object to which the node belongs or shall belong in future.
 5016  * @param node
 5017  *      The node of which you want to change the name. One cannot change the
 5018  *      name of the root directory.
 5019  * @param name
 5020  *      The new name for the node. It may not be empty. If it is oversized
 5021  *      then it will be handled according to iso_image_set_truncate_mode().
 5022  * @param flag
 5023  *      bit0= issue warning in case of truncation
 5024  * @return
 5025  *      1 on success, < 0 on error
 5026  *
 5027  * @since 1.4.2
 5028  */
 5029 int iso_image_set_node_name(IsoImage *image, IsoNode *node, const char *name,
 5030                             int flag);
 5031 
 5032 /**
 5033  *                            *** Deprecated ***
 5034  *                   use iso_image_set_node_name() instead
 5035  *
 5036  * Set the name of a node without taking into respect name truncation mode of
 5037  * an IsoImage.
 5038  *
 5039  * @param node
 5040  *      The node whose name you want to change. Note that you can't change
 5041  *      the name of the root.
 5042  * @param name
 5043  *      The name for the node. If you supply an empty string or a
 5044  *      name greater than 255 characters this returns with failure, and
 5045  *      node name is not modified.
 5046  * @return
 5047  *      1 on success, < 0 on error
 5048  *
 5049  * @since 0.6.2
 5050  */
 5051 int iso_node_set_name(IsoNode *node, const char *name);
 5052 
 5053 
 5054 /**
 5055  * Get the name of a node.
 5056  * The returned string belongs to the node and must not be modified nor
 5057  * freed. Use strdup if you really need your own copy.
 5058  *
 5059  * Up to version 1.4.2 inquiry of the root directory name returned NULL,
 5060  * which is a bug in the light of above description.
 5061  * Since 1.4.2 the return value is an empty string.
 5062  *
 5063  * @since 0.6.2
 5064  */
 5065 const char *iso_node_get_name(const IsoNode *node);
 5066 
 5067 /**
 5068  * Set the permissions for the node. This attribute is only useful when
 5069  * Rock Ridge extensions are enabled.
 5070  *
 5071  * @param node
 5072  *      The node to change
 5073  * @param mode
 5074  *     bitmask with the permissions of the node, as specified in 'man 2 stat'.
 5075  *     The file type bitfields will be ignored, only file permissions will be
 5076  *     modified.
 5077  *
 5078  * @since 0.6.2
 5079  */
 5080 void iso_node_set_permissions(IsoNode *node, mode_t mode);
 5081 
 5082 /**
 5083  * Get the permissions for the node
 5084  *
 5085  * @since 0.6.2
 5086  */
 5087 mode_t iso_node_get_permissions(const IsoNode *node);
 5088 
 5089 /**
 5090  * Get the mode of the node, both permissions and file type, as specified in
 5091  * 'man 2 stat'.
 5092  *
 5093  * @since 0.6.2
 5094  */
 5095 mode_t iso_node_get_mode(const IsoNode *node);
 5096 
 5097 /**
 5098  * Set the user id for the node. This attribute is only useful when
 5099  * Rock Ridge extensions are enabled.
 5100  *
 5101  * @since 0.6.2
 5102  */
 5103 void iso_node_set_uid(IsoNode *node, uid_t uid);
 5104 
 5105 /**
 5106  * Get the user id of the node.
 5107  *
 5108  * @since 0.6.2
 5109  */
 5110 uid_t iso_node_get_uid(const IsoNode *node);
 5111 
 5112 /**
 5113  * Set the group id for the node. This attribute is only useful when
 5114  * Rock Ridge extensions are enabled.
 5115  *
 5116  * @since 0.6.2
 5117  */
 5118 void iso_node_set_gid(IsoNode *node, gid_t gid);
 5119 
 5120 /**
 5121  * Get the group id of the node.
 5122  *
 5123  * @since 0.6.2
 5124  */
 5125 gid_t iso_node_get_gid(const IsoNode *node);
 5126 
 5127 /**
 5128  * Set the time of last modification of the file
 5129  *
 5130  * @since 0.6.2
 5131  */
 5132 void iso_node_set_mtime(IsoNode *node, time_t time);
 5133 
 5134 /**
 5135  * Get the time of last modification of the file
 5136  *
 5137  * @since 0.6.2
 5138  */
 5139 time_t iso_node_get_mtime(const IsoNode *node);
 5140 
 5141 /**
 5142  * Set the time of last access to the file
 5143  *
 5144  * @since 0.6.2
 5145  */
 5146 void iso_node_set_atime(IsoNode *node, time_t time);
 5147 
 5148 /**
 5149  * Get the time of last access to the file
 5150  *
 5151  * @since 0.6.2
 5152  */
 5153 time_t iso_node_get_atime(const IsoNode *node);
 5154 
 5155 /**
 5156  * Set the time of last status change of the file
 5157  *
 5158  * @since 0.6.2
 5159  */
 5160 void iso_node_set_ctime(IsoNode *node, time_t time);
 5161 
 5162 /**
 5163  * Get the time of last status change of the file
 5164  *
 5165  * @since 0.6.2
 5166  */
 5167 time_t iso_node_get_ctime(const IsoNode *node);
 5168 
 5169 /**
 5170  * Set whether the node will be hidden in the directory trees of RR/ISO 9660,
 5171  * or of Joliet (if enabled at all), or of ISO-9660:1999 (if enabled at all).
 5172  *
 5173  * A hidden file does not show up by name in the affected directory tree.
 5174  * For example, if a file is hidden only in Joliet, it will normally
 5175  * not be visible on Windows systems, while being shown on GNU/Linux.
 5176  *
 5177  * If a file is not shown in any of the enabled trees, then its content will
 5178  * not be written to the image, unless LIBISO_HIDE_BUT_WRITE is given (which
 5179  * is available only since release 0.6.34).
 5180  *
 5181  * @param node
 5182  *      The node that is to be hidden.
 5183  * @param hide_attrs
 5184  *      Or-combination of values from enum IsoHideNodeFlag to set the trees
 5185  *      in which the node's name shall be hidden.
 5186  *
 5187  * @since 0.6.2
 5188  */
 5189 void iso_node_set_hidden(IsoNode *node, int hide_attrs);
 5190 
 5191 /**
 5192  * Get the hide_attrs as eventually set by iso_node_set_hidden().
 5193  *
 5194  * @param node
 5195  *      The node to inquire.
 5196  * @return
 5197  *      Or-combination of values from enum IsoHideNodeFlag which are
 5198  *      currently set for the node.
 5199  *
 5200  * @since 0.6.34
 5201  */
 5202 int iso_node_get_hidden(IsoNode *node);
 5203 
 5204 /**
 5205  * Compare two nodes whether they are based on the same input and
 5206  * can be considered as hardlinks to the same file objects.
 5207  *
 5208  * @param n1
 5209  *     The first node to compare.
 5210  * @param n2
 5211  *     The second node to compare.
 5212  * @return
 5213  *     -1 if n1 is smaller n2 , 0 if n1 matches n2 , 1 if n1 is larger n2
 5214  * @param flag
 5215  *     Bitfield for control purposes, unused yet, submit 0
 5216  * @since 0.6.20
 5217  */
 5218 int iso_node_cmp_ino(IsoNode *n1, IsoNode *n2, int flag);
 5219 
 5220 /**
 5221  * Add a new node to a dir. Note that this function don't add a new ref to
 5222  * the node, so you don't need to free it, it will be automatically freed
 5223  * when the dir is deleted. Of course, if you want to keep using the node
 5224  * after the dir life, you need to iso_node_ref() it.
 5225  *
 5226  * @param dir
 5227  *     the dir where to add the node
 5228  * @param child
 5229  *     the node to add. You must ensure that the node hasn't previously added
 5230  *     to other dir, and that the node name is unique inside the child.
 5231  *     Otherwise this function will return a failure, and the child won't be
 5232  *     inserted.
 5233  * @param replace
 5234  *     if the dir already contains a node with the same name, whether to
 5235  *     replace or not the old node with this.
 5236  * @return
 5237  *     number of nodes in dir if success, < 0 otherwise
 5238  *     Possible errors:
 5239  *         ISO_NULL_POINTER, if dir or child are NULL
 5240  *         ISO_NODE_ALREADY_ADDED, if child is already added to other dir
 5241  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 5242  *         ISO_WRONG_ARG_VALUE, if child == dir, or replace != (0,1)
 5243  *
 5244  * @since 0.6.2
 5245  */
 5246 int iso_dir_add_node(IsoDir *dir, IsoNode *child,
 5247                      enum iso_replace_mode replace);
 5248 
 5249 /**
 5250  * Locate a node inside a given dir.
 5251  *
 5252  * The IsoImage context defines a maximum permissible name length and a mode
 5253  * how to react on oversized names. See iso_image_set_truncate_mode().
 5254  * If the caller looks for an oversized name and image truncate mode is 1,
 5255  * then this call looks for the truncated name among the nodes of dir.
 5256  *
 5257  * @param image
 5258  *     The image object to which dir belongs.
 5259  * @param dir
 5260  *     The dir where to look for the node.
 5261  * @param name
 5262  *     The name of the node. (Will not be changed if truncation happens.)
 5263  * @param node
 5264  *     Location for a pointer to the node, it will filled with NULL if the dir
 5265  *     doesn't have a child with the given name.
 5266  *     The node will be owned by the dir and shouldn't be unref(). Just call
 5267  *     iso_node_ref() to get your own reference to the node.
 5268  *     Note that you can pass NULL is the only thing you want to do is check
 5269  *     if a node with such name already exists on dir.
 5270  * @param flag
 5271  *     Bitfield for control purposes.
 5272  *     bit0= do not truncate name but lookup exactly as given.
 5273  * @return
 5274  *     1 node found
 5275  *     0 no name truncation was needed, name not found in dir
 5276  *     2 name truncation happened, truncated name not found in dir
 5277  *     < 0 error, see iso_dir_get_node().
 5278  *
 5279  * @since 1.4.2
 5280  */
 5281 int iso_image_dir_get_node(IsoImage *image, IsoDir *dir, 
 5282                            const char *name, IsoNode **node, int flag);
 5283 
 5284 /**
 5285  *                            *** Deprecated ***
 5286  *             In most cases use iso_image_dir_get_node() instead.
 5287  *
 5288  * Locate a node inside a given dir without taking into respect name truncation
 5289  * mode of an IsoImage.
 5290  *
 5291  * @param dir
 5292  *     The dir where to look for the node.
 5293  * @param name
 5294  *     The name of the node
 5295  * @param node
 5296  *     Location for a pointer to the node. See iso_image_get_node().
 5297  * @return
 5298  *     1 node found, 0 child has no such node, < 0 error
 5299  *     Possible errors:
 5300  *         ISO_NULL_POINTER, if dir or name are NULL
 5301  *
 5302  * @since 0.6.2
 5303  */
 5304 int iso_dir_get_node(IsoDir *dir, const char *name, IsoNode **node);
 5305 
 5306 /**
 5307  * Get the number of children of a directory.
 5308  *
 5309  * @return
 5310  *     >= 0 number of items, < 0 error
 5311  *     Possible errors:
 5312  *         ISO_NULL_POINTER, if dir is NULL
 5313  *
 5314  * @since 0.6.2
 5315  */
 5316 int iso_dir_get_children_count(IsoDir *dir);
 5317 
 5318 /**
 5319  * Removes a child from a directory.
 5320  * The child is not freed, so you will become the owner of the node. Later
 5321  * you can add the node to another dir (calling iso_dir_add_node), or free
 5322  * it if you don't need it (with iso_node_unref).
 5323  *
 5324  * @return
 5325  *     1 on success, < 0 error
 5326  *     Possible errors:
 5327  *         ISO_NULL_POINTER, if node is NULL
 5328  *         ISO_NODE_NOT_ADDED_TO_DIR, if node doesn't belong to a dir
 5329  *
 5330  * @since 0.6.2
 5331  */
 5332 int iso_node_take(IsoNode *node);
 5333 
 5334 /**
 5335  * Removes a child from a directory and free (unref) it.
 5336  * If you want to keep the child alive, you need to iso_node_ref() it
 5337  * before this call, but in that case iso_node_take() is a better
 5338  * alternative.
 5339  *
 5340  * @return
 5341  *     1 on success, < 0 error
 5342  *
 5343  * @since 0.6.2
 5344  */
 5345 int iso_node_remove(IsoNode *node);
 5346 
 5347 /*
 5348  * Get the parent of the given iso tree node. No extra ref is added to the
 5349  * returned directory, you must take your ref. with iso_node_ref() if you
 5350  * need it.
 5351  *
 5352  * If node is the root node, the same node will be returned as its parent.
 5353  *
 5354  * This returns NULL if the node doesn't pertain to any tree
 5355  * (it was removed/taken).
 5356  *
 5357  * @since 0.6.2
 5358  */
 5359 IsoDir *iso_node_get_parent(IsoNode *node);
 5360 
 5361 /**
 5362  * Get an iterator for the children of the given dir.
 5363  *
 5364  * You can iterate over the children with iso_dir_iter_next. When finished,
 5365  * you should free the iterator with iso_dir_iter_free.
 5366  * You must not delete a child of the same dir, using iso_node_take() or
 5367  * iso_node_remove(), while you're using the iterator. You can use
 5368  * iso_dir_iter_take() or iso_dir_iter_remove() instead.
 5369  *
 5370  * You can use the iterator in the way like this
 5371  *
 5372  * IsoDirIter *iter;
 5373  * IsoNode *node;
 5374  * if ( iso_dir_get_children(dir, &iter) != 1 ) {
 5375  *     // handle error
 5376  * }
 5377  * while ( iso_dir_iter_next(iter, &node) == 1 ) {
 5378  *     // do something with the child
 5379  * }
 5380  * iso_dir_iter_free(iter);
 5381  *
 5382  * An iterator is intended to be used in a single iteration over the
 5383  * children of a dir. Thus, it should be treated as a temporary object,
 5384  * and free as soon as possible.
 5385  *
 5386  * @return
 5387  *     1 success, < 0 error
 5388  *     Possible errors:
 5389  *         ISO_NULL_POINTER, if dir or iter are NULL
 5390  *         ISO_OUT_OF_MEM
 5391  *
 5392  * @since 0.6.2
 5393  */
 5394 int iso_dir_get_children(const IsoDir *dir, IsoDirIter **iter);
 5395 
 5396 /**
 5397  * Get the next child.
 5398  * Take care that the node is owned by its parent, and will be unref() when
 5399  * the parent is freed. If you want your own ref to it, call iso_node_ref()
 5400  * on it.
 5401  *
 5402  * @return
 5403  *     1 success, 0 if dir has no more elements, < 0 error
 5404  *     Possible errors:
 5405  *         ISO_NULL_POINTER, if node or iter are NULL
 5406  *         ISO_ERROR, on wrong iter usage, usual caused by modiying the
 5407  *         dir during iteration
 5408  *
 5409  * @since 0.6.2
 5410  */
 5411 int iso_dir_iter_next(IsoDirIter *iter, IsoNode **node);
 5412 
 5413 /**
 5414  * Check if there're more children.
 5415  *
 5416  * @return
 5417  *     1 dir has more elements, 0 no, < 0 error
 5418  *     Possible errors:
 5419  *         ISO_NULL_POINTER, if iter is NULL
 5420  *
 5421  * @since 0.6.2
 5422  */
 5423 int iso_dir_iter_has_next(IsoDirIter *iter);
 5424 
 5425 /**
 5426  * Free a dir iterator.
 5427  *
 5428  * @since 0.6.2
 5429  */
 5430 void iso_dir_iter_free(IsoDirIter *iter);
 5431 
 5432 /**
 5433  * Removes a child from a directory during an iteration, without freeing it.
 5434  * It's like iso_node_take(), but to be used during a directory iteration.
 5435  * The node removed will be the last returned by the iteration.
 5436  *
 5437  * If you call this function twice without calling iso_dir_iter_next between
 5438  * them is not allowed and you will get an ISO_ERROR in second call.
 5439  *
 5440  * @return
 5441  *     1 on success, < 0 error
 5442  *     Possible errors:
 5443  *         ISO_NULL_POINTER, if iter is NULL
 5444  *         ISO_ERROR, on wrong iter usage, for example by call this before
 5445  *         iso_dir_iter_next.
 5446  *
 5447  * @since 0.6.2
 5448  */
 5449 int iso_dir_iter_take(IsoDirIter *iter);
 5450 
 5451 /**
 5452  * Removes a child from a directory during an iteration and unref() it.
 5453  * Like iso_node_remove(), but to be used during a directory iteration.
 5454  * The node removed will be the one returned by the previous iteration.
 5455  *
 5456  * It is not allowed to call this function twice without calling
 5457  * iso_dir_iter_next between the calls.
 5458  *
 5459  * @return
 5460  *     1 on success, < 0 error
 5461  *     Possible errors:
 5462  *         ISO_NULL_POINTER, if iter is NULL
 5463  *         ISO_ERROR, on wrong iter usage, for example by calling this before
 5464  *         iso_dir_iter_next.
 5465  *
 5466  * @since 0.6.2
 5467  */
 5468 int iso_dir_iter_remove(IsoDirIter *iter);
 5469 
 5470 /**
 5471  * Removes a node by iso_node_remove() or iso_dir_iter_remove(). If the node
 5472  * is a directory then the whole tree of nodes underneath is removed too.
 5473  *
 5474  * @param node
 5475  *      The node to be removed.
 5476  * @param boss_iter
 5477  *      If not NULL, then the node will be removed by
 5478  *      iso_dir_iter_remove(boss_iter)
 5479  *      else it will be removed by iso_node_remove(node).
 5480  * @return
 5481  *      1 is success, <0 indicates error
 5482  *
 5483  * @since 1.0.2
 5484  */
 5485 int iso_node_remove_tree(IsoNode *node, IsoDirIter *boss_iter);
 5486 
 5487 
 5488 /**
 5489  * @since 0.6.4
 5490  */
 5491 typedef struct iso_find_condition IsoFindCondition;
 5492 
 5493 /**
 5494  * Create a new condition that checks if the node name matches the given
 5495  * wildcard.
 5496  *
 5497  * @param wildcard
 5498  * @result
 5499  *      The created IsoFindCondition, NULL on error.
 5500  *
 5501  * @since 0.6.4
 5502  */
 5503 IsoFindCondition *iso_new_find_conditions_name(const char *wildcard);
 5504 
 5505 /**
 5506  * Create a new condition that checks the node mode against a mode mask. It
 5507  * can be used to check both file type and permissions.
 5508  *
 5509  * For example:
 5510  *
 5511  * iso_new_find_conditions_mode(S_IFREG) : search for regular files
 5512  * iso_new_find_conditions_mode(S_IFCHR | S_IWUSR) : search for character
 5513  *     devices where owner has write permissions.
 5514  *
 5515  * @param mask
 5516  *      Mode mask to AND against node mode.
 5517  * @result
 5518  *      The created IsoFindCondition, NULL on error.
 5519  *
 5520  * @since 0.6.4
 5521  */
 5522 IsoFindCondition *iso_new_find_conditions_mode(mode_t mask);
 5523 
 5524 /**
 5525  * Create a new condition that checks the node gid.
 5526  *
 5527  * @param gid
 5528  *      Desired Group Id.
 5529  * @result
 5530  *      The created IsoFindCondition, NULL on error.
 5531  *
 5532  * @since 0.6.4
 5533  */
 5534 IsoFindCondition *iso_new_find_conditions_gid(gid_t gid);
 5535 
 5536 /**
 5537  * Create a new condition that checks the node uid.
 5538  *
 5539  * @param uid
 5540  *      Desired User Id.
 5541  * @result
 5542  *      The created IsoFindCondition, NULL on error.
 5543  *
 5544  * @since 0.6.4
 5545  */
 5546 IsoFindCondition *iso_new_find_conditions_uid(uid_t uid);
 5547 
 5548 /**
 5549  * Possible comparison between IsoNode and given conditions.
 5550  *
 5551  * @since 0.6.4
 5552  */
 5553 enum iso_find_comparisons {
 5554     ISO_FIND_COND_GREATER,
 5555     ISO_FIND_COND_GREATER_OR_EQUAL,
 5556     ISO_FIND_COND_EQUAL,
 5557     ISO_FIND_COND_LESS,
 5558     ISO_FIND_COND_LESS_OR_EQUAL
 5559 };
 5560 
 5561 /**
 5562  * Create a new condition that checks the time of last access.
 5563  *
 5564  * @param time
 5565  *      Time to compare against IsoNode atime.
 5566  * @param comparison
 5567  *      Comparison to be done between IsoNode atime and submitted time.
 5568  *      Note that ISO_FIND_COND_GREATER, for example, is true if the node
 5569  *      time is greater than the submitted time.
 5570  * @result
 5571  *      The created IsoFindCondition, NULL on error.
 5572  *
 5573  * @since 0.6.4
 5574  */
 5575 IsoFindCondition *iso_new_find_conditions_atime(time_t time,
 5576                       enum iso_find_comparisons comparison);
 5577 
 5578 /**
 5579  * Create a new condition that checks the time of last modification.
 5580  *
 5581  * @param time
 5582  *      Time to compare against IsoNode mtime.
 5583  * @param comparison
 5584  *      Comparison to be done between IsoNode mtime and submitted time.
 5585  *      Note that ISO_FIND_COND_GREATER, for example, is true if the node
 5586  *      time is greater than the submitted time.
 5587  * @result
 5588  *      The created IsoFindCondition, NULL on error.
 5589  *
 5590  * @since 0.6.4
 5591  */
 5592 IsoFindCondition *iso_new_find_conditions_mtime(time_t time,
 5593                       enum iso_find_comparisons comparison);
 5594 
 5595 /**
 5596  * Create a new condition that checks the time of last status change.
 5597  *
 5598  * @param time
 5599  *      Time to compare against IsoNode ctime.
 5600  * @param comparison
 5601  *      Comparison to be done between IsoNode ctime and submitted time.
 5602  *      Note that ISO_FIND_COND_GREATER, for example, is true if the node
 5603  *      time is greater than the submitted time.
 5604  * @result
 5605  *      The created IsoFindCondition, NULL on error.
 5606  *
 5607  * @since 0.6.4
 5608  */
 5609 IsoFindCondition *iso_new_find_conditions_ctime(time_t time,
 5610                       enum iso_find_comparisons comparison);
 5611 
 5612 /**
 5613  * Create a new condition that check if the two given conditions are
 5614  * valid.
 5615  *
 5616  * @param a
 5617  * @param b
 5618  *      IsoFindCondition to compare
 5619  * @result
 5620  *      The created IsoFindCondition, NULL on error.
 5621  *
 5622  * @since 0.6.4
 5623  */
 5624 IsoFindCondition *iso_new_find_conditions_and(IsoFindCondition *a,
 5625                                               IsoFindCondition *b);
 5626 
 5627 /**
 5628  * Create a new condition that check if at least one the two given conditions
 5629  * is valid.
 5630  *
 5631  * @param a
 5632  * @param b
 5633  *      IsoFindCondition to compare
 5634  * @result
 5635  *      The created IsoFindCondition, NULL on error.
 5636  *
 5637  * @since 0.6.4
 5638  */
 5639 IsoFindCondition *iso_new_find_conditions_or(IsoFindCondition *a,
 5640                                               IsoFindCondition *b);
 5641 
 5642 /**
 5643  * Create a new condition that check if the given conditions is false.
 5644  *
 5645  * @param negate
 5646  * @result
 5647  *      The created IsoFindCondition, NULL on error.
 5648  *
 5649  * @since 0.6.4
 5650  */
 5651 IsoFindCondition *iso_new_find_conditions_not(IsoFindCondition *negate);
 5652 
 5653 /**
 5654  * Find all directory children that match the given condition.
 5655  *
 5656  * @param dir
 5657  *      Directory where we will search children.
 5658  * @param cond
 5659  *      Condition that the children must match in order to be returned.
 5660  *      It will be free together with the iterator. Remember to delete it
 5661  *      if this function return error.
 5662  * @param iter
 5663  *      Iterator that returns only the children that match condition.
 5664  * @return
 5665  *      1 on success, < 0 on error
 5666  *
 5667  * @since 0.6.4
 5668  */
 5669 int iso_dir_find_children(IsoDir* dir, IsoFindCondition *cond,
 5670                           IsoDirIter **iter);
 5671 
 5672 /**
 5673  * Get the destination of a node.
 5674  * The returned string belongs to the node and must not be modified nor
 5675  * freed. Use strdup if you really need your own copy.
 5676  *
 5677  * @since 0.6.2
 5678  */
 5679 const char *iso_symlink_get_dest(const IsoSymlink *link);
 5680 
 5681 /**
 5682  * Set the destination of a symbolic 
 5683  *
 5684  * @param link
 5685  *     The link node to be manipulated
 5686  * @param dest
 5687  *     New destination for the link. It must be a non-empty string, otherwise
 5688  *     this function doesn't modify previous destination.
 5689  * @return
 5690  *     1 on success, < 0 on error
 5691  *
 5692  * @since 0.6.2
 5693  */
 5694 int iso_symlink_set_dest(IsoSymlink *link, const char *dest);
 5695 
 5696 /**
 5697  * Sets the order in which a node will be written on image. The data content
 5698  * of files with high weight will be written to low block addresses.
 5699  *
 5700  * @param node
 5701  *      The node which weight will be changed. If it's a dir, this function
 5702  *      will change the weight of all its children. For nodes other that dirs
 5703  *      or regular files, this function has no effect.
 5704  * @param w
 5705  *      The weight as a integer number, the greater this value is, the
 5706  *      closer from the beginning of image the file will be written.
 5707  *      Default value at IsoNode creation is 0.
 5708  *
 5709  * @since 0.6.2
 5710  */
 5711 void iso_node_set_sort_weight(IsoNode *node, int w);
 5712 
 5713 /**
 5714  * Get the sort weight of a file.
 5715  *
 5716  * @since 0.6.2
 5717  */
 5718 int iso_file_get_sort_weight(IsoFile *file);
 5719 
 5720 /**
 5721  * Get the size of the file, in bytes
 5722  *
 5723  * @since 0.6.2
 5724  */
 5725 off_t iso_file_get_size(IsoFile *file);
 5726 
 5727 /**
 5728  * Get the device id (major/minor numbers) of the given block or
 5729  * character device file. The result is undefined for other kind
 5730  * of special files, of first be sure iso_node_get_mode() returns either
 5731  * S_IFBLK or S_IFCHR.
 5732  *
 5733  * @since 0.6.6
 5734  */
 5735 dev_t iso_special_get_dev(IsoSpecial *special);
 5736 
 5737 /**
 5738  * Get the IsoStream that represents the contents of the given IsoFile.
 5739  * The stream may be a filter stream which itself get its input from a
 5740  * further stream. This may be inquired by iso_stream_get_input_stream().
 5741  *
 5742  * If you iso_stream_open() the stream, iso_stream_close() it before
 5743  * image generation begins.
 5744  *
 5745  * @return
 5746  *      The IsoStream. No extra ref is added, so the IsoStream belongs to the
 5747  *      IsoFile, and it may be freed together with it. Add your own ref with
 5748  *      iso_stream_ref() if you need it.
 5749  *
 5750  * @since 0.6.4
 5751  */
 5752 IsoStream *iso_file_get_stream(IsoFile *file);
 5753 
 5754 /**
 5755  * Get the block lba of a file node, if it was imported from an old image.
 5756  *
 5757  * @param file
 5758  *      The file
 5759  * @param lba
 5760  *      Will be filled with the kba
 5761  * @param flag
 5762  *      Reserved for future usage, submit 0
 5763  * @return
 5764  *      1 if lba is valid (file comes from old image and has only one section),
 5765  *      0 if file was newly added, i.e. it does not come from an old image,
 5766  *      < 0 error, especially ISO_WRONG_ARG_VALUE if the file has more than
 5767  *      one file section.
 5768  *
 5769  * @since 0.6.4
 5770  *
 5771  * @deprecated Use iso_file_get_old_image_sections(), as this function does
 5772  *             not work with multi-extend files.
 5773  */
 5774 int iso_file_get_old_image_lba(IsoFile *file, uint32_t *lba, int flag);
 5775 
 5776 /**
 5777  * Get the start addresses and the sizes of the data extents of a file node
 5778  * if it was imported from an old image.
 5779  *
 5780  * @param file
 5781  *      The file
 5782  * @param section_count
 5783  *      Returns the number of extent entries in sections array.
 5784  * @param sections
 5785  *      Returns the array of file sections if section_count > 0.
 5786  *      In this case, apply free() to dispose it.
 5787  * @param flag
 5788  *      Reserved for future usage, submit 0
 5789  * @return
 5790  *      1 if there are valid extents (file comes from old image),
 5791  *      0 if file was newly added, i.e. it does not come from an old image,
 5792  *      < 0 error
 5793  *
 5794  * @since 0.6.8
 5795  */
 5796 int iso_file_get_old_image_sections(IsoFile *file, int *section_count,
 5797                                     struct iso_file_section **sections,
 5798                                     int flag);
 5799 
 5800 /*
 5801  * Like iso_file_get_old_image_lba(), but take an IsoNode.
 5802  *
 5803  * @return
 5804  *      1 if lba is valid (file comes from old image), 0 if file was newly
 5805  *      added, i.e. it does not come from an old image, 2 node type has no
 5806  *      LBA (no regular file), < 0 error
 5807  *
 5808  * @since 0.6.4
 5809  */
 5810 int iso_node_get_old_image_lba(IsoNode *node, uint32_t *lba, int flag);
 5811 
 5812 /**
 5813  * Add a new directory to the iso tree. Permissions, owner and hidden atts
 5814  * are taken from parent, you can modify them later.
 5815  *
 5816  * @param image
 5817  *      The image object to which the new directory shall belong.
 5818  * @param parent
 5819  *      The directory node where the new directory will be grafted in.
 5820  * @param name
 5821  *      Name for the new directory. If truncation mode is set to 1,
 5822  *      an oversized name gets truncated before further processing.
 5823  *      If a node with same name already exists on parent, this function
 5824  *      fails with ISO_NODE_NAME_NOT_UNIQUE.
 5825  * @param dir
 5826  *      place where to store a pointer to the newly created dir. No extra
 5827  *      ref is added, so you will need to call iso_node_ref() if you really
 5828  *      need it. You can pass NULL in this parameter if you don't need the
 5829  *      pointer.
 5830  * @return
 5831  *     number of nodes in parent if success, < 0 otherwise
 5832  *     Possible errors:
 5833  *         ISO_NULL_POINTER, if parent or name are NULL
 5834  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 5835  *         ISO_OUT_OF_MEM
 5836  *         ISO_RR_NAME_TOO_LONG
 5837  *
 5838  * @since 1.4.2
 5839  */
 5840 int iso_image_add_new_dir(IsoImage *image, IsoDir *parent, const char *name,
 5841                           IsoDir **dir);
 5842 
 5843 /**
 5844  *                            *** Deprecated ***
 5845  *                   use iso_image_add_new_dir() instead
 5846  *
 5847  * Add a new directory to the iso tree without taking into respect name
 5848  * truncation mode of an IsoImage.
 5849  * For detailed description of parameters, see above iso_image_add_new_dir().
 5850  *
 5851  * @param parent
 5852  *      the dir where the new directory will be created
 5853  * @param name
 5854  *      name for the new dir.
 5855  * @param dir
 5856  *      place where to store a pointer to the newly created dir.i
 5857  * @return
 5858  *     number of nodes in parent if success, < 0 otherwise
 5859  *     Possible errors:
 5860  *         ISO_NULL_POINTER, if parent or name are NULL
 5861  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 5862  *         ISO_OUT_OF_MEM
 5863  *
 5864  * @since 0.6.2
 5865  */
 5866 int iso_tree_add_new_dir(IsoDir *parent, const char *name, IsoDir **dir);
 5867 
 5868 /**
 5869  * Add a new regular file to the iso tree. Permissions are set to 0444,
 5870  * owner and hidden atts are taken from parent. You can modify any of them
 5871  * later.
 5872  *
 5873  * @param image
 5874  *      The image object to which the new file shall belong.
 5875   * @param parent
 5876  *      The directory node where the new directory will be grafted in.
 5877  * @param name
 5878  *      Name for the new file. If truncation mode is set to 1,
 5879  *      an oversized name gets truncated before further processing.
 5880  *      If a node with same name already exists on parent, this function
 5881  *      fails with ISO_NODE_NAME_NOT_UNIQUE.
 5882  * @param stream
 5883  *      IsoStream for the contents of the file. The reference will be taken
 5884  *      by the newly created file, you will need to take an extra ref to it
 5885  *      if you need it.
 5886  * @param file
 5887  *      place where to store a pointer to the newly created file. No extra
 5888  *      ref is added, so you will need to call iso_node_ref() if you really
 5889  *      need it. You can pass NULL in this parameter if you don't need the
 5890  *      pointer
 5891  * @return
 5892  *     number of nodes in parent if success, < 0 otherwise
 5893  *     Possible errors:
 5894  *         ISO_NULL_POINTER, if parent, name or dest are NULL
 5895  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 5896  *         ISO_OUT_OF_MEM
 5897  *         ISO_RR_NAME_TOO_LONG
 5898  *
 5899  * @since 1.4.2
 5900  */
 5901 int iso_image_add_new_file(IsoImage *image, IsoDir *parent, const char *name,
 5902                            IsoStream *stream, IsoFile **file);
 5903 
 5904 /**
 5905  *                            *** Deprecated ***
 5906  *                   use iso_image_add_new_file() instead
 5907  *
 5908  * Add a new regular file to the iso tree without taking into respect name
 5909  * truncation mode of an IsoImage.
 5910  * For detailed description of parameters, see above iso_image_add_new_file().
 5911  *
 5912  * @param parent
 5913  *      the dir where the new file will be created
 5914  * @param name
 5915  *      name for the new file.
 5916  * @param stream
 5917  *      IsoStream for the contents of the file.
 5918  * @param file
 5919  *      place where to store a pointer to the newly created file.
 5920  * @return
 5921  *     number of nodes in parent if success, < 0 otherwise
 5922  *     Possible errors:
 5923  *         ISO_NULL_POINTER, if parent, name or dest are NULL
 5924  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 5925  *         ISO_OUT_OF_MEM
 5926  *
 5927  * @since 0.6.4
 5928  */
 5929 int iso_tree_add_new_file(IsoDir *parent, const char *name, IsoStream *stream,
 5930                           IsoFile **file);
 5931 
 5932 /**
 5933  * Create an IsoStream object from content which is stored in a dynamically
 5934  * allocated memory buffer. The new stream will become owner of the buffer
 5935  * and apply free() to it when the stream finally gets destroyed itself.
 5936  *
 5937  * @param buf
 5938  *     The dynamically allocated memory buffer with the stream content.
 5939  * @param size
 5940  *     The number of bytes which may be read from buf.
 5941  * @param stream
 5942  *     Will return a reference to the newly created stream.
 5943  * @return
 5944  *     ISO_SUCCESS or <0 for error. E.g. ISO_NULL_POINTER, ISO_OUT_OF_MEM.
 5945  *
 5946  * @since 1.0.0
 5947  */
 5948 int iso_memory_stream_new(unsigned char *buf, size_t size, IsoStream **stream);
 5949 
 5950 /**
 5951  * Add a new symbolic link to the directory tree. Permissions are set to 0777,
 5952  * owner and hidden atts are taken from parent. You can modify any of them
 5953  * later.
 5954  *
 5955  * @param image
 5956  *      The image object to which the new directory shall belong.
 5957  * @param parent
 5958  *      The directory node where the new symlink will be grafted in.
 5959  * @param name
 5960  *      Name for the new symlink. If truncation mode is set to 1,
 5961  *      an oversized name gets truncated before further processing.
 5962  *      If a node with same name already exists on parent, this function
 5963  *      fails with ISO_NODE_NAME_NOT_UNIQUE.
 5964  * @param dest
 5965  *      The destination path of the link. The components of this path are
 5966  *      not checked for being oversized.
 5967  * @param link
 5968  *      Place where to store a pointer to the newly created link. No extra
 5969  *      ref is added, so you will need to call iso_node_ref() if you really
 5970  *      need it. You can pass NULL in this parameter if you don't need the
 5971  *      pointer
 5972  * @return
 5973  *     number of nodes in parent if success, < 0 otherwise
 5974  *     Possible errors:
 5975  *         ISO_NULL_POINTER, if parent, name or dest are NULL
 5976  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 5977  *         ISO_OUT_OF_MEM
 5978  *         ISO_RR_NAME_TOO_LONG
 5979  *
 5980  * @since 1.4.2
 5981  */
 5982 int iso_image_add_new_symlink(IsoImage *image, IsoDir *parent, 
 5983                               const char *name, const char *dest, 
 5984                               IsoSymlink **link);
 5985 
 5986 /**
 5987  *                            *** Deprecated ***
 5988  *                  use iso_image_add_new_symlink() instead
 5989  *
 5990  * Add a new symlink to the directory tree without taking into respect name
 5991  * truncation mode of an IsoImage.
 5992  * For detailed description of parameters, see above
 5993  * iso_image_add_new_isymlink().
 5994  *
 5995  * @param parent
 5996  *      the dir where the new symlink will be created
 5997  * @param name
 5998  *      name for the new symlink.
 5999  * @param dest
 6000  *      destination of the link
 6001  * @param link
 6002  *      place where to store a pointer to the newly created link.
 6003  * @return
 6004  *     number of nodes in parent if success, < 0 otherwise
 6005  *     Possible errors:
 6006  *         ISO_NULL_POINTER, if parent, name or dest are NULL
 6007  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 6008  *         ISO_OUT_OF_MEM
 6009  *
 6010  * @since 0.6.2
 6011  */
 6012 int iso_tree_add_new_symlink(IsoDir *parent, const char *name,
 6013                              const char *dest, IsoSymlink **link);
 6014 
 6015 /**
 6016  * Add a new special file to the directory tree. As far as libisofs concerns,
 6017  * a special file is a block device, a character device, a FIFO (named pipe)
 6018  * or a socket. You can choose the specific kind of file you want to add
 6019  * by setting mode properly (see man 2 stat).
 6020  *
 6021  * Note that special files are only written to image when Rock Ridge
 6022  * extensions are enabled. Moreover, a special file is just a directory entry
 6023  * in the image tree, no data is written beyond that.
 6024  *
 6025  * Owner and hidden atts are taken from parent. You can modify any of them
 6026  * later.
 6027  *
 6028  * @param image
 6029  *      The image object to which the new special file shall belong.
 6030  * @param parent
 6031  *      The directory node where the new special file will be grafted in.
 6032  * @param name
 6033  *      Name for the new special file. If truncation mode is set to 1,
 6034  *      an oversized name gets truncated before further processing.
 6035  *      If a node with same name already exists on parent, this function
 6036  *      fails with ISO_NODE_NAME_NOT_UNIQUE.
 6037  * @param mode
 6038  *      File type and permissions for the new node. Note that only the file
 6039  *      types S_IFSOCK, S_IFBLK, S_IFCHR, and S_IFIFO are allowed.
 6040  *      S_IFLNK, S_IFREG, or S_IFDIR are not.
 6041  * @param dev
 6042  *      Device ID, equivalent to the st_rdev field in man 2 stat.
 6043  * @param special
 6044  *      Place where to store a pointer to the newly created special file. No
 6045  *      extra ref is added, so you will need to call iso_node_ref() if you
 6046  *      really need it. You can pass NULL in this parameter if you don't need
 6047  *      the pointer.
 6048  * @return
 6049  *     Number of nodes in parent if success, < 0 otherwise
 6050  *     Possible errors:
 6051  *         ISO_NULL_POINTER, if parent, name or dest are NULL
 6052  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 6053  *         ISO_WRONG_ARG_VALUE if you select a incorrect mode
 6054  *         ISO_OUT_OF_MEM
 6055  *         ISO_RR_NAME_TOO_LONG
 6056  *
 6057  * @since 1.4.2
 6058  */
 6059 int iso_image_add_new_special(IsoImage *image, IsoDir *parent,
 6060                               const char *name, mode_t mode,
 6061                               dev_t dev, IsoSpecial **special);
 6062 
 6063 /**
 6064  *                            *** Deprecated ***
 6065  *                   use iso_image_add_new_special() instead
 6066  *
 6067  * Add a new special file to the directory tree without taking into respect name
 6068  * truncation mode of an IsoImage.
 6069  * For detailed description of parameters, see above
 6070  * iso_image_add_new_special().
 6071  *
 6072  * @param parent
 6073  *      the dir where the new special file will be created
 6074  * @param name
 6075  *      name for the new special file.
 6076  * @param mode
 6077  *      file type and permissions for the new node.
 6078  * @param dev
 6079  *      device ID, equivalent to the st_rdev field in man 2 stat.
 6080  * @param special
 6081  *      place where to store a pointer to the newly created special file.
 6082  * @return
 6083  *     number of nodes in parent if success, < 0 otherwise
 6084  *     Possible errors:
 6085  *         ISO_NULL_POINTER, if parent, name or dest are NULL
 6086  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 6087  *         ISO_WRONG_ARG_VALUE if you select a incorrect mode
 6088  *         ISO_OUT_OF_MEM
 6089  *
 6090  * @since 0.6.2
 6091  */
 6092 int iso_tree_add_new_special(IsoDir *parent, const char *name, mode_t mode,
 6093                              dev_t dev, IsoSpecial **special);
 6094 
 6095 /**
 6096  * Set whether to follow or not symbolic links when added a file from a source
 6097  * to IsoImage. Default behavior is to not follow symlinks.
 6098  *
 6099  * @since 0.6.2
 6100  */
 6101 void iso_tree_set_follow_symlinks(IsoImage *image, int follow);
 6102 
 6103 /**
 6104  * Get current setting for follow_symlinks.
 6105  *
 6106  * @see iso_tree_set_follow_symlinks
 6107  * @since 0.6.2
 6108  */
 6109 int iso_tree_get_follow_symlinks(IsoImage *image);
 6110 
 6111 /**
 6112  * Set whether to skip or not disk files with names beginning by '.'
 6113  * when adding a directory recursively.
 6114  * Default behavior is to not ignore them.
 6115  *
 6116  * Clarification: This is not related to the IsoNode property to be hidden
 6117  *                in one or more of the resulting image trees as of
 6118  *                IsoHideNodeFlag and iso_node_set_hidden().
 6119  *
 6120  * @since 0.6.2
 6121  */
 6122 void iso_tree_set_ignore_hidden(IsoImage *image, int skip);
 6123 
 6124 /**
 6125  * Get current setting for ignore_hidden.
 6126  *
 6127  * @see iso_tree_set_ignore_hidden
 6128  * @since 0.6.2
 6129  */
 6130 int iso_tree_get_ignore_hidden(IsoImage *image);
 6131 
 6132 /**
 6133  * Set the replace mode, that defines the behavior of libisofs when adding
 6134  * a node whit the same name that an existent one, during a recursive
 6135  * directory addition.
 6136  *
 6137  * @since 0.6.2
 6138  */
 6139 void iso_tree_set_replace_mode(IsoImage *image, enum iso_replace_mode mode);
 6140 
 6141 /**
 6142  * Get current setting for replace_mode.
 6143  *
 6144  * @see iso_tree_set_replace_mode
 6145  * @since 0.6.2
 6146  */
 6147 enum iso_replace_mode iso_tree_get_replace_mode(IsoImage *image);
 6148 
 6149 /**
 6150  * Set whether to skip or not special files. Default behavior is to not skip
 6151  * them. Note that, despite of this setting, special files will never be added
 6152  * to an image unless RR extensions were enabled.
 6153  *
 6154  * @param image
 6155  *      The image to manipulate.
 6156  * @param skip
 6157  *      Bitmask to determine what kind of special files will be skipped:
 6158  *          bit0: ignore FIFOs
 6159  *          bit1: ignore Sockets
 6160  *          bit2: ignore char devices
 6161  *          bit3: ignore block devices
 6162  *
 6163  * @since 0.6.2
 6164  */
 6165 void iso_tree_set_ignore_special(IsoImage *image, int skip);
 6166 
 6167 /**
 6168  * Get current setting for ignore_special.
 6169  *
 6170  * @see iso_tree_set_ignore_special
 6171  * @since 0.6.2
 6172  */
 6173 int iso_tree_get_ignore_special(IsoImage *image);
 6174 
 6175 /**
 6176  * Add a excluded path. These are paths that won't never added to image, and
 6177  * will be excluded even when adding recursively its parent directory.
 6178  *
 6179  * For example, in
 6180  *
 6181  *   iso_tree_add_exclude(image, "/home/user/data/private");
 6182  *   iso_tree_add_dir_rec(image, root, "/home/user/data");
 6183  *
 6184  * the directory /home/user/data/private won't be added to image.
 6185  *
 6186  * However, if you explicitly add a deeper dir, it won't be excluded. i.e.,
 6187  * in the following example.
 6188  *
 6189  *   iso_tree_add_exclude(image, "/home/user/data");
 6190  *   iso_tree_add_dir_rec(image, root, "/home/user/data/private");
 6191  *
 6192  * the directory /home/user/data/private is added. On the other, side, and
 6193  * following the example above,
 6194  *
 6195  *   iso_tree_add_dir_rec(image, root, "/home/user");
 6196  *
 6197  * will exclude the directory "/home/user/data".
 6198  *
 6199  * Absolute paths are not mandatory, you can, for example, add a relative
 6200  * path such as:
 6201  *
 6202  *   iso_tree_add_exclude(image, "private");
 6203  *   iso_tree_add_exclude(image, "user/data");
 6204  *
 6205  * to exclude, respectively, all files or dirs named private, and also all
 6206  * files or dirs named data that belong to a folder named "user". Note that the
 6207  * above rule about deeper dirs is still valid. i.e., if you call
 6208  *
 6209  *   iso_tree_add_dir_rec(image, root, "/home/user/data/music");
 6210  *
 6211  * it is included even containing "user/data" string. However, a possible
 6212  * "/home/user/data/music/user/data" is not added.
 6213  *
 6214  * Usual wildcards, such as * or ? are also supported, with the usual meaning
 6215  * as stated in "man 7 glob". For example
 6216  *
 6217  * // to exclude backup text files
 6218  * iso_tree_add_exclude(image, "*.~");
 6219  *
 6220  * @return
 6221  *      1 on success, < 0 on error
 6222  *
 6223  * @since 0.6.2
 6224  */
 6225 int iso_tree_add_exclude(IsoImage *image, const char *path);
 6226 
 6227 /**
 6228  * Remove a previously added exclude.
 6229  *
 6230  * @see iso_tree_add_exclude
 6231  * @return
 6232  *      1 on success, 0 exclude do not exists, < 0 on error
 6233  *
 6234  * @since 0.6.2
 6235  */
 6236 int iso_tree_remove_exclude(IsoImage *image, const char *path);
 6237 
 6238 /**
 6239  * Set a callback function that libisofs will call for each file that is
 6240  * added to the given image by a recursive addition function. This includes
 6241  * image import.
 6242  *
 6243  * @param image
 6244  *      The image to manipulate.
 6245  * @param report
 6246  *      pointer to a function that will be called just before a file will be
 6247  *      added to the image. You can control whether the file will be in fact
 6248  *      added or ignored.
 6249  *      This function should return 1 to add the file, 0 to ignore it and
 6250  *      continue, < 0 to abort the process
 6251  *      NULL is allowed if you don't want any callback.
 6252  *
 6253  * @since 0.6.2
 6254  */
 6255 void iso_tree_set_report_callback(IsoImage *image,
 6256                                   int (*report)(IsoImage*, IsoFileSource*));
 6257 
 6258 /**
 6259  * Add a new node to the image tree, from an existing file.
 6260  *
 6261  * TODO comment Builder and Filesystem related issues when exposing both
 6262  *
 6263  * All attributes will be taken from the source file. The appropriate file
 6264  * type will be created.
 6265  *
 6266  * @param image
 6267  *      The image
 6268  * @param parent
 6269  *      The directory in the image tree where the node will be added.
 6270  * @param path
 6271  *      The absolute path of the file in the local filesystem.
 6272  *      The node will have the same leaf name as the file on disk, possibly
 6273  *      truncated according to iso_image_set_truncate_mode().
 6274  *      Its directory path depends on the parent node.
 6275  * @param node
 6276  *      place where to store a pointer to the newly added file. No
 6277  *      extra ref is added, so you will need to call iso_node_ref() if you
 6278  *      really need it. You can pass NULL in this parameter if you don't need
 6279  *      the pointer.
 6280  * @return
 6281  *     number of nodes in parent if success, < 0 otherwise
 6282  *     Possible errors:
 6283  *         ISO_NULL_POINTER, if image, parent or path are NULL
 6284  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 6285  *         ISO_OUT_OF_MEM
 6286  *         ISO_RR_NAME_TOO_LONG
 6287  *
 6288  * @since 0.6.2
 6289  */
 6290 int iso_tree_add_node(IsoImage *image, IsoDir *parent, const char *path,
 6291                       IsoNode **node);
 6292 
 6293 /**
 6294  * This is a more versatile form of iso_tree_add_node which allows to set
 6295  * the node name in ISO image already when it gets added. 
 6296  *
 6297  * Add a new node to the image tree, from an existing file, and with the
 6298  * given name, that must not exist on dir.
 6299  *
 6300  * @param image
 6301  *      The image
 6302  * @param parent
 6303  *      The directory in the image tree where the node will be added.
 6304  * @param name
 6305  *      The leaf name that the node will have on image, possibly truncated
 6306  *      according to iso_image_set_truncate_mode().
 6307  *      Its directory path depends on the parent node.
 6308  * @param path
 6309  *      The absolute path of the file in the local filesystem.
 6310  * @param node
 6311  *      place where to store a pointer to the newly added file. No
 6312  *      extra ref is added, so you will need to call iso_node_ref() if you
 6313  *      really need it. You can pass NULL in this parameter if you don't need
 6314  *      the pointer.
 6315  * @return
 6316  *     number of nodes in parent if success, < 0 otherwise
 6317  *     Possible errors:
 6318  *         ISO_NULL_POINTER, if image, parent or path are NULL
 6319  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 6320  *         ISO_OUT_OF_MEM
 6321  *         ISO_RR_NAME_TOO_LONG
 6322  *
 6323  * @since 0.6.4
 6324  */
 6325 int iso_tree_add_new_node(IsoImage *image, IsoDir *parent, const char *name,
 6326                           const char *path, IsoNode **node);
 6327 
 6328 /**
 6329  * Add a new node to the image tree with the given name that must not exist
 6330  * on dir. The node data content will be a byte interval out of the data
 6331  * content of a file in the local filesystem.
 6332  *
 6333  * @param image
 6334  *      The image
 6335  * @param parent
 6336  *      The directory in the image tree where the node will be added.
 6337  * @param name
 6338  *      The leaf name that the node will have on image, possibly truncated
 6339  *      according to iso_image_set_truncate_mode().
 6340  *      Its directory path depends on the parent node.
 6341  * @param path
 6342  *      The absolute path of the file in the local filesystem. For now
 6343  *      only regular files and symlinks to regular files are supported.
 6344  * @param offset
 6345  *      Byte number in the given file from where to start reading data.
 6346  * @param size
 6347  *      Max size of the file. This may be more than actually available from
 6348  *      byte offset to the end of the file in the local filesystem.
 6349  * @param node
 6350  *      place where to store a pointer to the newly added file. No
 6351  *      extra ref is added, so you will need to call iso_node_ref() if you
 6352  *      really need it. You can pass NULL in this parameter if you don't need
 6353  *      the pointer.
 6354  * @return
 6355  *     number of nodes in parent if success, < 0 otherwise
 6356  *     Possible errors:
 6357  *         ISO_NULL_POINTER, if image, parent or path are NULL
 6358  *         ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists
 6359  *         ISO_OUT_OF_MEM
 6360  *         ISO_RR_NAME_TOO_LONG
 6361  *
 6362  * @since 0.6.4
 6363  */
 6364 int iso_tree_add_new_cut_out_node(IsoImage *image, IsoDir *parent,
 6365                                   const char *name, const char *path,
 6366                                   off_t offset, off_t size,
 6367                                   IsoNode **node);
 6368 
 6369 /**
 6370  * Create a copy of the given node under a different path. If the node is
 6371  * actually a directory then clone its whole subtree.
 6372  * This call may fail because an IsoFile is encountered which gets fed by an
 6373  * IsoStream which cannot be cloned. See also IsoStream_Iface method
 6374  * clone_stream().
 6375  * Surely clonable node types are:
 6376  *   IsoDir,
 6377  *   IsoSymlink,
 6378  *   IsoSpecial,
 6379  *   IsoFile from a loaded ISO image,
 6380  *   IsoFile referring to local filesystem files,
 6381  *   IsoFile created by iso_tree_add_new_file
 6382  *           from a stream created by iso_memory_stream_new(),
 6383  *   IsoFile created by iso_tree_add_new_cut_out_node()
 6384  * Silently ignored are nodes of type IsoBoot.
 6385  * An IsoFile node with IsoStream filters can be cloned if all those filters
 6386  * are clonable and the node would be clonable without filter.
 6387  * Clonable IsoStream filters are created by:
 6388  *   iso_file_add_zisofs_filter()
 6389  *   iso_file_add_gzip_filter()
 6390  *   iso_file_add_external_filter()
 6391  * An IsoNode with extended information as of iso_node_add_xinfo() can only be
 6392  * cloned if each of the iso_node_xinfo_func instances is associated to a
 6393  * clone function. See iso_node_xinfo_make_clonable().
 6394  * All internally used classes of extended information are clonable.
 6395  *
 6396  * The IsoImage context defines a maximum permissible name length and a mode
 6397  * how to react on oversized names. See iso_image_set_truncate_mode().
 6398  *
 6399  * @param image
 6400  *      The image object to which the node belongs.
 6401  * @param node
 6402  *      The node to be cloned.
 6403  * @param new_parent
 6404  *      The existing directory node where to insert the cloned node.
 6405  * @param new_name
 6406  *      The name for the cloned node. It must not yet exist in new_parent,
 6407  *      unless it is a directory and node is a directory and flag bit0 is set.
 6408  * @param new_node
 6409  *      Will return a pointer (without reference) to the newly created clone.
 6410  * @param flag
 6411  *      Bitfield for control purposes. Submit any undefined bits as 0.
 6412  *      bit0= Merge directories rather than returning ISO_NODE_NAME_NOT_UNIQUE.
 6413  *            This will not allow to overwrite any existing node.
 6414  *            Attributes of existing directories will not be overwritten.
 6415  *      bit1= issue warning in case of new_name truncation
 6416  * @return
 6417  *      <0 means error, 1 = new node created,
 6418  *      2 = if flag bit0 is set: new_node is a directory which already existed.
 6419  *
 6420  * @since 1.4.2
 6421  */
 6422 int iso_image_tree_clone(IsoImage *image, IsoNode *node, IsoDir *new_parent,
 6423                          char *new_name, IsoNode **new_node, int flag);
 6424 
 6425 /**
 6426  *                            *** Deprecated ***
 6427  *                   use iso_image_tree_clone() instead
 6428  *
 6429  * Create a copy of the given node under a different path without taking
 6430  * into respect name truncation mode of an IsoImage.
 6431  * 
 6432  * @param node
 6433  *      The node to be cloned.
 6434  * @param new_parent
 6435  *      The existing directory node where to insert the cloned node.
 6436  * @param new_name
 6437  *      The name for the cloned node. It must not yet exist in new_parent,
 6438  *      unless it is a directory and node is a directory and flag bit0 is set.
 6439  * @param new_node
 6440  *      Will return a pointer (without reference) to the newly created clone.
 6441  * @param flag
 6442  *      Bitfield for control purposes. Submit any undefined bits as 0.
 6443  *      bit0= Merge directories rather than returning ISO_NODE_NAME_NOT_UNIQUE.
 6444  *            This will not allow to overwrite any existing node.
 6445  *            Attributes of existing directories will not be overwritten.
 6446  * @return
 6447  *      <0 means error, 1 = new node created,
 6448  *      2 = if flag bit0 is set: new_node is a directory which already existed.
 6449  *
 6450  * @since 1.0.2
 6451  */
 6452 int iso_tree_clone(IsoNode *node,
 6453                    IsoDir *new_parent, char *new_name, IsoNode **new_node,
 6454                    int flag);
 6455 
 6456 /**
 6457  * Add the contents of a dir to a given directory of the iso tree.
 6458  *
 6459  * There are several options to control what files are added or how they are
 6460  * managed. Take a look at iso_tree_set_* functions to see different options
 6461  * for recursive directory addition.
 6462  *
 6463  * TODO comment Builder and Filesystem related issues when exposing both
 6464  *
 6465  * @param image
 6466  *      The image to which the directory belongs.
 6467  * @param parent
 6468  *      Directory on the image tree where to add the contents of the dir
 6469  * @param dir
 6470  *      Path to a dir in the filesystem
 6471  * @return
 6472  *     number of nodes in parent if success, < 0 otherwise
 6473  *
 6474  * @since 0.6.2
 6475  */
 6476 int iso_tree_add_dir_rec(IsoImage *image, IsoDir *parent, const char *dir);
 6477 
 6478 /**
 6479  * Inquire whether some local filesystem xattr namespace could not be explored
 6480  * during node building.This may happen due to lack of administrator privileges
 6481  * e.g. on FreeBSD namespace "system".
 6482  * It may well be that the processed local files have no attributes which
 6483  * would require special privileges. But already their existence was neither
 6484  * denied nor confirmed.
 6485  *
 6486  * @param image
 6487  *      The image to inquire.
 6488  * @param flag
 6489  *      Bitfield for control purposes:
 6490  *      bit0 = reset internal value to 0
 6491  * @return
 6492  *      1 = Exploration was prevented
 6493  *      0 = No such prevention occurred
 6494  *
 6495  * @since 1.5.0
 6496  */
 6497 int iso_image_was_blind_attrs(IsoImage *image, int flag);
 6498 
 6499 
 6500 /**
 6501  * Locate a node by its absolute path in the image.
 6502  * The IsoImage context defines a maximum permissible name length and a mode
 6503  * how to react on oversized names. See iso_image_set_truncate_mode().
 6504  *
 6505  * @param image
 6506  *     The image to which the node belongs.
 6507  * @param path
 6508  *     File path beginning at the root directory of image. If truncation mode
 6509  *     is set to 1, oversized path components will be truncated before lookup.
 6510  * @param node
 6511  *     Location for a pointer to the node, it will be filled with NULL if the
 6512  *     given path does not exists on image.
 6513  *     The node will be owned by the image and shouldn't be unref(). Just call
 6514  *     iso_node_ref() to get your own reference to the node.
 6515  *     Note that you can pass NULL is the only thing you want to do is check
 6516  *     if a node with such path really exists.
 6517  *
 6518  * @return
 6519  *     1 node found
 6520  *     0 no truncation was needed, path not found in image
 6521  *     2 truncation happened, truncated path component not found in parent dir
 6522  *     < 0 error, see iso_dir_get_node().
 6523  *
 6524  * @since 1.4.2
 6525  */
 6526 int iso_image_path_to_node(IsoImage *image, const char *path, IsoNode **node);
 6527 
 6528 /**
 6529  *                            *** Deprecated ***
 6530  *              In most cases use iso_image_path_to_node() instead
 6531  *
 6532  * Locate a node by its absolute path on image without taking into respect
 6533  * name truncation mode of the image.
 6534  *
 6535  * @param image
 6536  *     The image to which the node belongs.
 6537  * @param path
 6538  *     File path beginning at the root directory of image. No truncation will
 6539  *     happen.
 6540  * @param node
 6541  *     Location for a pointer to the node, it will be filled with NULL if the
 6542  *     given path does not exists on image. See iso_image_path_to_node().
 6543  * @return
 6544  *      1 found, 0 not found, < 0 error
 6545  *
 6546  * @since 0.6.2
 6547  */
 6548 int iso_tree_path_to_node(IsoImage *image, const char *path, IsoNode **node);
 6549 
 6550 /**
 6551  * Get the absolute path on image of the given node.
 6552  *
 6553  * @return
 6554  *      The path on the image, that must be freed when no more needed. If the
 6555  *      given node is not added to any image, this returns NULL.
 6556  * @since 0.6.4
 6557  */
 6558 char *iso_tree_get_node_path(IsoNode *node);
 6559 
 6560 /**
 6561  * Get the destination node of a symbolic link within the IsoImage.
 6562  *
 6563  * @param img
 6564  *      The image wherein to try resolving the link.
 6565  * @param sym
 6566  *      The symbolic link node which to resolve.
 6567  * @param res
 6568  *      Will return the found destination node, in case of success.
 6569  *      Call iso_node_ref() / iso_node_unref() if you intend to use the node
 6570  *      over API calls which might in any event delete it.
 6571  * @param depth
 6572  *      Prevents endless loops. Submit as 0.
 6573  * @param flag
 6574  *      Bitfield for control purposes. Submit 0 for now.
 6575  * @return
 6576  *      1 on success,
 6577  *      < 0 on failure, especially ISO_DEEP_SYMLINK and ISO_DEAD_SYMLINK
 6578  *
 6579  * @since 1.2.4
 6580  */
 6581 int iso_tree_resolve_symlink(IsoImage *img, IsoSymlink *sym, IsoNode **res,
 6582                              int *depth, int flag);
 6583 
 6584 /* Maximum number link resolution steps before ISO_DEEP_SYMLINK gets
 6585  * returned by iso_tree_resolve_symlink().
 6586  *
 6587  * @since 1.2.4
 6588 */
 6589 #define LIBISO_MAX_LINK_DEPTH 100
 6590 
 6591 /**
 6592  * Increments the reference counting of the given IsoDataSource.
 6593  *
 6594  * @since 0.6.2
 6595  */
 6596 void iso_data_source_ref(IsoDataSource *src);
 6597 
 6598 /**
 6599  * Decrements the reference counting of the given IsoDataSource, freeing it
 6600  * if refcount reach 0.
 6601  *
 6602  * @since 0.6.2
 6603  */
 6604 void iso_data_source_unref(IsoDataSource *src);
 6605 
 6606 /**
 6607  * Create a new IsoDataSource from a local file. This is suitable for
 6608  * accessing regular files or block devices with ISO images.
 6609  *
 6610  * @param path
 6611  *     The absolute path of the file
 6612  * @param src
 6613  *     Will be filled with the pointer to the newly created data source.
 6614  * @return
 6615  *    1 on success, < 0 on error.
 6616  *
 6617  * @since 0.6.2
 6618  */
 6619 int iso_data_source_new_from_file(const char *path, IsoDataSource **src);
 6620 
 6621 /**
 6622  * Get the status of the buffer used by a burn_source.
 6623  *
 6624  * @param b
 6625  *      A burn_source previously obtained with
 6626  *      iso_image_create_burn_source().
 6627  * @param size
 6628  *      Will be filled with the total size of the buffer, in bytes
 6629  * @param free_bytes
 6630  *      Will be filled with the bytes currently available in buffer
 6631  * @return
 6632  *      < 0 error, > 0 state:
 6633  *           1="active"    : input and consumption are active
 6634  *           2="ending"    : input has ended without error
 6635  *           3="failing"   : input had error and ended,
 6636  *           5="abandoned" : consumption has ended prematurely
 6637  *           6="ended"     : consumption has ended without input error
 6638  *           7="aborted"   : consumption has ended after input error
 6639  *
 6640  * @since 0.6.2
 6641  */
 6642 int iso_ring_buffer_get_status(struct burn_source *b, size_t *size,
 6643                                size_t *free_bytes);
 6644 
 6645 #define ISO_MSGS_MESSAGE_LEN 4096
 6646 
 6647 /**
 6648  * Control queueing and stderr printing of messages from libisofs.
 6649  * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
 6650  * "NOTE", "UPDATE", "DEBUG", "ALL".
 6651  *
 6652  * @param queue_severity Gives the minimum limit for messages to be queued.
 6653  *                       Default: "NEVER". If you queue messages then you
 6654  *                       must consume them by iso_obtain_msgs().
 6655  * @param print_severity Does the same for messages to be printed directly
 6656  *                       to stderr.
 6657  * @param print_id       A text prefix to be printed before the message.
 6658  * @return               >0 for success, <=0 for error
 6659  *
 6660  * @since 0.6.2
 6661  */
 6662 int iso_set_msgs_severities(char *queue_severity, char *print_severity,
 6663                             char *print_id);
 6664 
 6665 /**
 6666  * Obtain the oldest pending libisofs message from the queue which has at
 6667  * least the given minimum_severity. This message and any older message of
 6668  * lower severity will get discarded from the queue and is then lost forever.
 6669  *
 6670  * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
 6671  * "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER"
 6672  * will discard the whole queue.
 6673  *
 6674  * @param minimum_severity
 6675  *     Threshold
 6676  * @param error_code
 6677  *     Will become a unique error code as listed at the end of this header
 6678  * @param imgid
 6679  *     Id of the image that was issued the message.
 6680  * @param msg_text
 6681  *     Must provide at least ISO_MSGS_MESSAGE_LEN bytes.
 6682  * @param severity
 6683  *     Will become the severity related to the message and should provide at
 6684  *     least 80 bytes.
 6685  * @return
 6686  *     1 if a matching item was found, 0 if not, <0 for severe errors
 6687  *
 6688  * @since 0.6.2
 6689  */
 6690 int iso_obtain_msgs(char *minimum_severity, int *error_code, int *imgid,
 6691                     char msg_text[], char severity[]);
 6692 
 6693 
 6694 /**
 6695  * Submit a message to the libisofs queueing system. It will be queued or
 6696  * printed as if it was generated by libisofs itself.
 6697  *
 6698  * @param error_code
 6699  *      The unique error code of your message.
 6700  *      Submit 0 if you do not have reserved error codes within the libburnia
 6701  *      project.
 6702  * @param msg_text
 6703  *      Not more than ISO_MSGS_MESSAGE_LEN characters of message text.
 6704  * @param os_errno
 6705  *      Eventual errno related to the message. Submit 0 if the message is not
 6706  *      related to a operating system error.
 6707  * @param severity
 6708  *      One of "ABORT", "FATAL", "FAILURE", "SORRY", "WARNING", "HINT", "NOTE",
 6709  *      "UPDATE", "DEBUG". Defaults to "FATAL".
 6710  * @param origin
 6711  *      Submit 0 for now.
 6712  * @return
 6713  *      1 if message was delivered, <=0 if failure
 6714  *
 6715  * @since 0.6.4
 6716  */
 6717 int iso_msgs_submit(int error_code, char msg_text[], int os_errno,
 6718                     char severity[], int origin);
 6719 
 6720 
 6721 /**
 6722  * Convert a severity name into a severity number, which gives the severity
 6723  * rank of the name.
 6724  *
 6725  * @param severity_name
 6726  *      A name as with iso_msgs_submit(), e.g. "SORRY".
 6727  * @param severity_number
 6728  *      The rank number: the higher, the more severe.
 6729  * @return
 6730  *      >0 success, <=0 failure
 6731  *
 6732  * @since 0.6.4
 6733  */
 6734 int iso_text_to_sev(char *severity_name, int *severity_number);
 6735 
 6736 
 6737 /**
 6738  * Convert a severity number into a severity name
 6739  *
 6740  * @param severity_number
 6741  *      The rank number: the higher, the more severe.
 6742  * @param severity_name
 6743  *      A name as with iso_msgs_submit(), e.g. "SORRY".
 6744  *
 6745  * @since 0.6.4
 6746  */
 6747 int iso_sev_to_text(int severity_number, char **severity_name);
 6748 
 6749 
 6750 /**
 6751  * Get the id of an IsoImage, used for message reporting. This message id,
 6752  * retrieved with iso_obtain_msgs(), can be used to distinguish what
 6753  * IsoImage has issued a given message.
 6754  *
 6755  * @since 0.6.2
 6756  */
 6757 int iso_image_get_msg_id(IsoImage *image);
 6758 
 6759 /**
 6760  * Get a textual description of a libisofs error.
 6761  *
 6762  * @since 0.6.2
 6763  */
 6764 const char *iso_error_to_msg(int errcode);
 6765 
 6766 /**
 6767  * Get the severity of a given error code
 6768  * @return
 6769  *       0x10000000 -> DEBUG
 6770  *       0x20000000 -> UPDATE
 6771  *       0x30000000 -> NOTE
 6772  *       0x40000000 -> HINT
 6773  *       0x50000000 -> WARNING
 6774  *       0x60000000 -> SORRY
 6775  *       0x64000000 -> MISHAP
 6776  *       0x68000000 -> FAILURE
 6777  *       0x70000000 -> FATAL
 6778  *       0x71000000 -> ABORT
 6779  *
 6780  * @since 0.6.2
 6781  */
 6782 int iso_error_get_severity(int e);
 6783 
 6784 /**
 6785  * Get the priority of a given error.
 6786  * @return
 6787  *      0x00000000 -> ZERO
 6788  *      0x10000000 -> LOW
 6789  *      0x20000000 -> MEDIUM
 6790  *      0x30000000 -> HIGH
 6791  *
 6792  * @since 0.6.2
 6793  */
 6794 int iso_error_get_priority(int e);
 6795 
 6796 /**
 6797  * Get the message queue code of a libisofs error.
 6798  */
 6799 int iso_error_get_code(int e);
 6800 
 6801 /**
 6802  * Set the minimum error severity that causes a libisofs operation to
 6803  * be aborted as soon as possible.
 6804  *
 6805  * @param severity
 6806  *      one of "FAILURE", "MISHAP", "SORRY", "WARNING", "HINT", "NOTE".
 6807  *      Severities greater or equal than FAILURE always cause program to abort.
 6808  *      Severities under NOTE won't never cause function abort.
 6809  * @return
 6810  *      Previous abort priority on success, < 0 on error.
 6811  *
 6812  * @since 0.6.2
 6813  */
 6814 int iso_set_abort_severity(char *severity);
 6815 
 6816 /**
 6817  * Return the messenger object handle used by libisofs. This handle
 6818  * may be used by related libraries to  their own compatible
 6819  * messenger objects and thus to direct their messages to the libisofs
 6820  * message queue. See also: libburn, API function burn_set_messenger().
 6821  *
 6822  * @return the handle. Do only use with compatible
 6823  *
 6824  * @since 0.6.2
 6825  */
 6826 void *iso_get_messenger();
 6827 
 6828 /**
 6829  * Take a ref to the given IsoFileSource.
 6830  *
 6831  * @since 0.6.2
 6832  */
 6833 void iso_file_source_ref(IsoFileSource *src);
 6834 
 6835 /**
 6836  * Drop your ref to the given IsoFileSource, eventually freeing the associated
 6837  * system resources.
 6838  *
 6839  * @since 0.6.2
 6840  */
 6841 void iso_file_source_unref(IsoFileSource *src);
 6842 
 6843 /*
 6844  * this are just helpers to invoque methods in class
 6845  */
 6846 
 6847 /**
 6848  * Get the absolute path in the filesystem this file source belongs to.
 6849  *
 6850  * @return
 6851  *     the path of the FileSource inside the filesystem, it should be
 6852  *     freed when no more needed.
 6853  *
 6854  * @since 0.6.2
 6855  */
 6856 char* iso_file_source_get_path(IsoFileSource *src);
 6857 
 6858 /**
 6859  * Get the name of the file, with the dir component of the path.
 6860  *
 6861  * @return
 6862  *     the name of the file, it should be freed when no more needed.
 6863  *
 6864  * @since 0.6.2
 6865  */
 6866 char* iso_file_source_get_name(IsoFileSource *src);
 6867 
 6868 /**
 6869  * Get information about the file.
 6870  * @return
 6871  *    1 success, < 0 error
 6872  *      Error codes:
 6873  *         ISO_FILE_ACCESS_DENIED
 6874  *         ISO_FILE_BAD_PATH
 6875  *         ISO_FILE_DOESNT_EXIST
 6876  *         ISO_OUT_OF_MEM
 6877  *         ISO_FILE_ERROR
 6878  *         ISO_NULL_POINTER
 6879  *
 6880  * @since 0.6.2
 6881  */
 6882 int iso_file_source_lstat(IsoFileSource *src, struct stat *info);
 6883 
 6884 /**
 6885  * Check if the process has access to read file contents. Note that this
 6886  * is not necessarily related with (l)stat functions. For example, in a
 6887  * filesystem implementation to deal with an ISO image, if the user has
 6888  * read access to the image it will be able to read all files inside it,
 6889  * despite of the particular permission of each file in the RR tree, that
 6890  * are what the above functions return.
 6891  *
 6892  * @return
 6893  *     1 if process has read access, < 0 on error
 6894  *      Error codes:
 6895  *         ISO_FILE_ACCESS_DENIED
 6896  *         ISO_FILE_BAD_PATH
 6897  *         ISO_FILE_DOESNT_EXIST
 6898  *         ISO_OUT_OF_MEM
 6899  *         ISO_FILE_ERROR
 6900  *         ISO_NULL_POINTER
 6901  *
 6902  * @since 0.6.2
 6903  */
 6904 int iso_file_source_access(IsoFileSource *src);
 6905 
 6906 /**
 6907  * Get information about the file. If the file is a symlink, the info
 6908  * returned refers to the destination.
 6909  *
 6910  * @return
 6911  *    1 success, < 0 error
 6912  *      Error codes:
 6913  *         ISO_FILE_ACCESS_DENIED
 6914  *         ISO_FILE_BAD_PATH
 6915  *         ISO_FILE_DOESNT_EXIST
 6916  *         ISO_OUT_OF_MEM
 6917  *         ISO_FILE_ERROR
 6918  *         ISO_NULL_POINTER
 6919  *
 6920  * @since 0.6.2
 6921  */
 6922 int iso_file_source_stat(IsoFileSource *src, struct stat *info);
 6923 
 6924 /**
 6925  * Opens the source.
 6926  * @return 1 on success, < 0 on error
 6927  *      Error codes:
 6928  *         ISO_FILE_ALREADY_OPENED
 6929  *         ISO_FILE_ACCESS_DENIED
 6930  *         ISO_FILE_BAD_PATH
 6931  *         ISO_FILE_DOESNT_EXIST
 6932  *         ISO_OUT_OF_MEM
 6933  *         ISO_FILE_ERROR
 6934  *         ISO_NULL_POINTER
 6935  *
 6936  * @since 0.6.2
 6937  */
 6938 int iso_file_source_open(IsoFileSource *src);
 6939 
 6940 /**
 6941  * Close a previously opened file
 6942  * @return 1 on success, < 0 on error
 6943  *      Error codes:
 6944  *         ISO_FILE_ERROR
 6945  *         ISO_NULL_POINTER
 6946  *         ISO_FILE_NOT_OPENED
 6947  *
 6948  * @since 0.6.2
 6949  */
 6950 int iso_file_source_close(IsoFileSource *src);
 6951 
 6952 /**
 6953  * Attempts to read up to count bytes from the given source into
 6954  * the buffer starting at buf.
 6955  *
 6956  * The file src must be open() before calling this, and close() when no
 6957  * more needed. Not valid for dirs. On symlinks it reads the destination
 6958  * file.
 6959  *
 6960  * @param src
 6961  *     The given source
 6962  * @param buf
 6963  *     Pointer to a buffer of at least count bytes where the read data will be
 6964  *     stored
 6965  * @param count
 6966  *     Bytes to read
 6967  * @return
 6968  *     number of bytes read, 0 if EOF, < 0 on error
 6969  *      Error codes:
 6970  *         ISO_FILE_ERROR
 6971  *         ISO_NULL_POINTER
 6972  *         ISO_FILE_NOT_OPENED
 6973  *         ISO_WRONG_ARG_VALUE -> if count == 0
 6974  *         ISO_FILE_IS_DIR
 6975  *         ISO_OUT_OF_MEM
 6976  *         ISO_INTERRUPTED
 6977  *
 6978  * @since 0.6.2
 6979  */
 6980 int iso_file_source_read(IsoFileSource *src, void *buf, size_t count);
 6981 
 6982 /**
 6983  * Repositions the offset of the given IsoFileSource (must be opened) to the
 6984  * given offset according to the value of flag.
 6985  *
 6986  * @param src
 6987  *     The given source
 6988  * @param offset
 6989  *      in bytes
 6990  * @param flag
 6991  *      0 The offset is set to offset bytes (SEEK_SET)
 6992  *      1 The offset is set to its current location plus offset bytes
 6993  *        (SEEK_CUR)
 6994  *      2 The offset is set to the size of the file plus offset bytes
 6995  *        (SEEK_END).
 6996  * @return
 6997  *      Absolute offset position on the file, or < 0 on error. Cast the
 6998  *      returning value to int to get a valid libisofs error.
 6999  * @since 0.6.4
 7000  */
 7001 off_t iso_file_source_lseek(IsoFileSource *src, off_t offset, int flag);
 7002 
 7003 /**
 7004  * Read a directory.
 7005  *
 7006  * Each call to this function will return a new child, until we reach
 7007  * the end of file (i.e, no more children), in that case it returns 0.
 7008  *
 7009  * The dir must be open() before calling this, and close() when no more
 7010  * needed. Only valid for dirs.
 7011  *
 7012  * Note that "." and ".." children MUST NOT BE returned.
 7013  *
 7014  * @param src
 7015  *     The given source
 7016  * @param child
 7017  *     pointer to be filled with the given child. Undefined on error or OEF
 7018  * @return
 7019  *     1 on success, 0 if EOF (no more children), < 0 on error
 7020  *      Error codes:
 7021  *         ISO_FILE_ERROR
 7022  *         ISO_NULL_POINTER
 7023  *         ISO_FILE_NOT_OPENED
 7024  *         ISO_FILE_IS_NOT_DIR
 7025  *         ISO_OUT_OF_MEM
 7026  *
 7027  * @since 0.6.2
 7028  */
 7029 int iso_file_source_readdir(IsoFileSource *src, IsoFileSource **child);