00001 /* 00002 * Copyright (c) 2007-2008 Vreixo Formoso, Mario Danic 00003 * Copyright (c) 2009-2010 Thomas Schmitt 00004 * 00005 * This file is part of the libisofs project; you can redistribute it and/or 00006 * modify it under the terms of the GNU General Public License version 2 00007 * or later as published by the Free Software Foundation. 00008 * See COPYING file for details. 00009 */ 00010 00011 /* Important: If you add a public API function then add its name to file 00012 libisofs/libisofs.ver 00013 */ 00014 00015 /* 00016 * 00017 * Applications must use 64 bit off_t, e.g. on 32-bit GNU/Linux by defining 00018 * #define _LARGEFILE_SOURCE 00019 * #define _FILE_OFFSET_BITS 64 00020 * or take special precautions to interface with the library by 64 bit integers 00021 * where this .h files prescribe off_t. Not to use 64 bit file i/o will keep 00022 * the application from producing and processing ISO images of more than 2 GB 00023 * size. 00024 * 00025 */ 00026 00027 #ifndef LIBISO_LIBISOFS_H_ 00028 #define LIBISO_LIBISOFS_H_ 00029 00030 #include <sys/stat.h> 00031 #include <stdint.h> 00032 #include <stdlib.h> 00033 00034 struct burn_source; 00035 00036 /** 00037 * Context for image creation. It holds the files that will be added to image, 00038 * and several options to control libisofs behavior. 00039 * 00040 * @since 0.6.2 00041 */ 00042 typedef struct Iso_Image IsoImage; 00043 00044 /* 00045 * A node in the iso tree, i.e. a file that will be written to image. 00046 * 00047 * It can represent any kind of files. When needed, you can get the type with 00048 * iso_node_get_type() and cast it to the appropiate subtype. Useful macros 00049 * are provided, see below. 00050 * 00051 * @since 0.6.2 00052 */ 00053 typedef struct Iso_Node IsoNode; 00054 00055 /** 00056 * A directory in the iso tree. It is an special type of IsoNode and can be 00057 * casted to it in any case. 00058 * 00059 * @since 0.6.2 00060 */ 00061 typedef struct Iso_Dir IsoDir; 00062 00063 /** 00064 * A symbolic link in the iso tree. It is an special type of IsoNode and can be 00065 * casted to it in any case. 00066 * 00067 * @since 0.6.2 00068 */ 00069 typedef struct Iso_Symlink IsoSymlink; 00070 00071 /** 00072 * A regular file in the iso tree. It is an special type of IsoNode and can be 00073 * casted to it in any case. 00074 * 00075 * @since 0.6.2 00076 */ 00077 typedef struct Iso_File IsoFile; 00078 00079 /** 00080 * An special file in the iso tree. This is used to represent any POSIX file 00081 * other that regular files, directories or symlinks, i.e.: socket, block and 00082 * character devices, and fifos. 00083 * It is an special type of IsoNode and can be casted to it in any case. 00084 * 00085 * @since 0.6.2 00086 */ 00087 typedef struct Iso_Special IsoSpecial; 00088 00089 /** 00090 * The type of an IsoNode. 00091 * 00092 * When an user gets an IsoNode from an image, (s)he can use 00093 * iso_node_get_type() to get the current type of the node, and then 00094 * cast to the appropriate subtype. For example: 00095 * 00096 * ... 00097 * IsoNode *node; 00098 * res = iso_dir_iter_next(iter, &node); 00099 * if (res == 1 && iso_node_get_type(node) == LIBISO_DIR) { 00100 * IsoDir *dir = (IsoDir *)node; 00101 * ... 00102 * } 00103 * 00104 * @since 0.6.2 00105 */ 00106 enum IsoNodeType { 00107 LIBISO_DIR, 00108 LIBISO_FILE, 00109 LIBISO_SYMLINK, 00110 LIBISO_SPECIAL, 00111 LIBISO_BOOT 00112 }; 00113 00114 /* macros to check node type */ 00115 #define ISO_NODE_IS_DIR(n) (iso_node_get_type(n) == LIBISO_DIR) 00116 #define ISO_NODE_IS_FILE(n) (iso_node_get_type(n) == LIBISO_FILE) 00117 #define ISO_NODE_IS_SYMLINK(n) (iso_node_get_type(n) == LIBISO_SYMLINK) 00118 #define ISO_NODE_IS_SPECIAL(n) (iso_node_get_type(n) == LIBISO_SPECIAL) 00119 #define ISO_NODE_IS_BOOTCAT(n) (iso_node_get_type(n) == LIBISO_BOOT) 00120 00121 /* macros for safe downcasting */ 00122 #define ISO_DIR(n) ((IsoDir*)(ISO_NODE_IS_DIR(n) ? n : NULL)) 00123 #define ISO_FILE(n) ((IsoFile*)(ISO_NODE_IS_FILE(n) ? n : NULL)) 00124 #define ISO_SYMLINK(n) ((IsoSymlink*)(ISO_NODE_IS_SYMLINK(n) ? n : NULL)) 00125 #define ISO_SPECIAL(n) ((IsoSpecial*)(ISO_NODE_IS_SPECIAL(n) ? n : NULL)) 00126 00127 #define ISO_NODE(n) ((IsoNode*)n) 00128 00129 /** 00130 * File section in an old image. 00131 * 00132 * @since 0.6.8 00133 */ 00134 struct iso_file_section 00135 { 00136 uint32_t block; 00137 uint32_t size; 00138 }; 00139 00140 /** 00141 * Context for iterate on directory children. 00142 * @see iso_dir_get_children() 00143 * 00144 * @since 0.6.2 00145 */ 00146 typedef struct Iso_Dir_Iter IsoDirIter; 00147 00148 /** 00149 * It represents an El-Torito boot image. 00150 * 00151 * @since 0.6.2 00152 */ 00153 typedef struct el_torito_boot_image ElToritoBootImage; 00154 00155 /** 00156 * An special type of IsoNode that acts as a placeholder for an El-Torito 00157 * boot catalog. Once written, it will appear as a regular file. 00158 * 00159 * @since 0.6.2 00160 */ 00161 typedef struct Iso_Boot IsoBoot; 00162 00163 /** 00164 * Flag used to hide a file in the RR/ISO or Joliet tree. 00165 * 00166 * @see iso_node_set_hidden 00167 * @since 0.6.2 00168 */ 00169 enum IsoHideNodeFlag { 00170 /** Hide the node in the ECMA-119 / RR tree */ 00171 LIBISO_HIDE_ON_RR = 1 << 0, 00172 /** Hide the node in the Joliet tree, if Joliet extension are enabled */ 00173 LIBISO_HIDE_ON_JOLIET = 1 << 1, 00174 /** Hide the node in the ISO-9660:1999 tree, if that format is enabled */ 00175 LIBISO_HIDE_ON_1999 = 1 << 2, 00176 00177 /** With IsoNode and IsoBoot: Write data content even if the node is 00178 * not visible in any tree. 00179 * With directory nodes : Write data content of IsoNode and IsoBoot 00180 * in the directory's tree unless they are 00181 * explicitely marked LIBISO_HIDE_ON_RR 00182 * without LIBISO_HIDE_BUT_WRITE. 00183 * @since 0.6.34 00184 */ 00185 LIBISO_HIDE_BUT_WRITE = 1 << 3 00186 }; 00187 00188 /** 00189 * El-Torito bootable image type. 00190 * 00191 * @since 0.6.2 00192 */ 00193 enum eltorito_boot_media_type { 00194 ELTORITO_FLOPPY_EMUL, 00195 ELTORITO_HARD_DISC_EMUL, 00196 ELTORITO_NO_EMUL 00197 }; 00198 00199 /** 00200 * Replace mode used when addding a node to a file. 00201 * This controls how libisofs will act when you tried to add to a dir a file 00202 * with the same name that an existing file. 00203 * 00204 * @since 0.6.2 00205 */ 00206 enum iso_replace_mode { 00207 /** 00208 * Never replace an existing node, and instead fail with 00209 * ISO_NODE_NAME_NOT_UNIQUE. 00210 */ 00211 ISO_REPLACE_NEVER, 00212 /** 00213 * Always replace the old node with the new. 00214 */ 00215 ISO_REPLACE_ALWAYS, 00216 /** 00217 * Replace with the new node if it is the same file type 00218 */ 00219 ISO_REPLACE_IF_SAME_TYPE, 00220 /** 00221 * Replace with the new node if it is the same file type and its ctime 00222 * is newer than the old one. 00223 */ 00224 ISO_REPLACE_IF_SAME_TYPE_AND_NEWER, 00225 /** 00226 * Replace with the new node if its ctime is newer than the old one. 00227 */ 00228 ISO_REPLACE_IF_NEWER 00229 /* 00230 * TODO #00006 define more values 00231 * -if both are dirs, add contents (and what to do with conflicts?) 00232 */ 00233 }; 00234 00235 /** 00236 * Options for image written. 00237 * @see iso_write_opts_new() 00238 * @since 0.6.2 00239 */ 00240 typedef struct iso_write_opts IsoWriteOpts; 00241 00242 /** 00243 * Options for image reading or import. 00244 * @see iso_read_opts_new() 00245 * @since 0.6.2 00246 */ 00247 typedef struct iso_read_opts IsoReadOpts; 00248 00249 /** 00250 * Source for image reading. 00251 * 00252 * @see struct iso_data_source 00253 * @since 0.6.2 00254 */ 00255 typedef struct iso_data_source IsoDataSource; 00256 00257 /** 00258 * Data source used by libisofs for reading an existing image. 00259 * 00260 * It offers homogeneous read access to arbitrary blocks to different sources 00261 * for images, such as .iso files, CD/DVD drives, etc... 00262 * 00263 * To create a multisession image, libisofs needs a IsoDataSource, that the 00264 * user must provide. The function iso_data_source_new_from_file() constructs 00265 * an IsoDataSource that uses POSIX I/O functions to access data. You can use 00266 * it with regular .iso images, and also with block devices that represent a 00267 * drive. 00268 * 00269 * @since 0.6.2 00270 */ 00271 struct iso_data_source 00272 { 00273 00274 /* reserved for future usage, set to 0 */ 00275 int version; 00276 00277 /** 00278 * Reference count for the data source. Should be 1 when a new source 00279 * is created. Don't access it directly, but with iso_data_source_ref() 00280 * and iso_data_source_unref() functions. 00281 */ 00282 unsigned int refcount; 00283 00284 /** 00285 * Opens the given source. You must open() the source before any attempt 00286 * to read data from it. The open is the right place for grabbing the 00287 * underlying resources. 00288 * 00289 * @return 00290 * 1 if success, < 0 on error (has to be a valid libisofs error code) 00291 */ 00292 int (*open)(IsoDataSource *src); 00293 00294 /** 00295 * Close a given source, freeing all system resources previously grabbed in 00296 * open(). 00297 * 00298 * @return 00299 * 1 if success, < 0 on error (has to be a valid libisofs error code) 00300 */ 00301 int (*close)(IsoDataSource *src); 00302 00303 /** 00304 * Read an arbitrary block (2048 bytes) of data from the source. 00305 * 00306 * @param lba 00307 * Block to be read. 00308 * @param buffer 00309 * Buffer where the data will be written. It should have at least 00310 * 2048 bytes. 00311 * @return 00312 * 1 if success, 00313 * < 0 if error. This function has to emit a valid libisofs error code. 00314 * Predifined (but not mandatory) for this purpose are: 00315 * ISO_DATA_SOURCE_SORRY , ISO_DATA_SOURCE_MISHAP, 00316 * ISO_DATA_SOURCE_FAILURE , ISO_DATA_SOURCE_FATAL 00317 */ 00318 int (*read_block)(IsoDataSource *src, uint32_t lba, uint8_t *buffer); 00319 00320 /** 00321 * Clean up the source specific data. Never call this directly, it is 00322 * automatically called by iso_data_source_unref() when refcount reach 00323 * 0. 00324 */ 00325 void (*free_data)(IsoDataSource *); 00326 00327 /** Source specific data */ 00328 void *data; 00329 }; 00330 00331 /** 00332 * Return information for image. This is optionally allocated by libisofs, 00333 * as a way to inform user about the features of an existing image, such as 00334 * extensions present, size, ... 00335 * 00336 * @see iso_image_import() 00337 * @since 0.6.2 00338 */ 00339 typedef struct iso_read_image_features IsoReadImageFeatures; 00340 00341 /** 00342 * POSIX abstraction for source files. 00343 * 00344 * @see struct iso_file_source 00345 * @since 0.6.2 00346 */ 00347 typedef struct iso_file_source IsoFileSource; 00348 00349 /** 00350 * Abstract for source filesystems. 00351 * 00352 * @see struct iso_filesystem 00353 * @since 0.6.2 00354 */ 00355 typedef struct iso_filesystem IsoFilesystem; 00356 00357 /** 00358 * Interface that defines the operations (methods) available for an 00359 * IsoFileSource. 00360 * 00361 * @see struct IsoFileSource_Iface 00362 * @since 0.6.2 00363 */ 00364 typedef struct IsoFileSource_Iface IsoFileSourceIface; 00365 00366 /** 00367 * IsoFilesystem implementation to deal with ISO images, and to offer a way to 00368 * access specific information of the image, such as several volume attributes, 00369 * extensions being used, El-Torito artifacts... 00370 * 00371 * @since 0.6.2 00372 */ 00373 typedef IsoFilesystem IsoImageFilesystem; 00374 00375 /** 00376 * See IsoFilesystem->get_id() for info about this. 00377 * @since 0.6.2 00378 */ 00379 extern unsigned int iso_fs_global_id; 00380 00381 /** 00382 * An IsoFilesystem is a handler for a source of files, or a "filesystem". 00383 * That is defined as a set of files that are organized in a hierarchical 00384 * structure. 00385 * 00386 * A filesystem allows libisofs to access files from several sources in 00387 * an homogeneous way, thus abstracting the underlying operations needed to 00388 * access and read file contents. Note that this doesn't need to be tied 00389 * to the disc filesystem used in the partition being accessed. For example, 00390 * we have an IsoFilesystem implementation to access any mounted filesystem, 00391 * using standard POSIX functions. It is also legal, of course, to implement 00392 * an IsoFilesystem to deal with a specific filesystem over raw partitions. 00393 * That is what we do, for example, to access an ISO Image. 00394 * 00395 * Each file inside an IsoFilesystem is represented as an IsoFileSource object, 00396 * that defines POSIX-like interface for accessing files. 00397 * 00398 * @since 0.6.2 00399 */ 00400 struct iso_filesystem 00401 { 00402 /** 00403 * Type of filesystem. 00404 * "file" -> local filesystem 00405 * "iso " -> iso image filesystem 00406 */ 00407 char type[4]; 00408 00409 /* reserved for future usage, set to 0 */ 00410 int version; 00411 00412 /** 00413 * Get the root of a filesystem. 00414 * 00415 * @return 00416 * 1 on success, < 0 on error (has to be a valid libisofs error code) 00417 */ 00418 int (*get_root)(IsoFilesystem *fs, IsoFileSource **root); 00419 00420 /** 00421 * Retrieve a file from its absolute path inside the filesystem. 00422 * 00423 * @return 00424 * 1 success, < 0 error (has to be a valid libisofs error code) 00425 * Error codes: 00426 * ISO_FILE_ACCESS_DENIED 00427 * ISO_FILE_BAD_PATH 00428 * ISO_FILE_DOESNT_EXIST 00429 * ISO_OUT_OF_MEM 00430 * ISO_FILE_ERROR 00431 * ISO_NULL_POINTER 00432 */ 00433 int (*get_by_path)(IsoFilesystem *fs, const char *path, 00434 IsoFileSource **file); 00435 00436 /** 00437 * Get filesystem identifier. 00438 * 00439 * If the filesystem is able to generate correct values of the st_dev 00440 * and st_ino fields for the struct stat of each file, this should 00441 * return an unique number, greater than 0. 00442 * 00443 * To get a identifier for your filesystem implementation you should 00444 * use iso_fs_global_id, incrementing it by one each time. 00445 * 00446 * Otherwise, if you can't ensure values in the struct stat are valid, 00447 * this should return 0. 00448 */ 00449 unsigned int (*get_id)(IsoFilesystem *fs); 00450 00451 /** 00452 * Opens the filesystem for several read operations. Calling this funcion 00453 * is not needed at all, each time that the underlying system resource 00454 * needs to be accessed, it is openned propertly. 00455 * However, if you plan to execute several operations on the filesystem, 00456 * it is a good idea to open it previously, to prevent several open/close 00457 * operations to occur. 00458 * 00459 * @return 1 on success, < 0 on error (has to be a valid libisofs error code) 00460 */ 00461 int (*open)(IsoFilesystem *fs); 00462 00463 /** 00464 * Close the filesystem, thus freeing all system resources. You should 00465 * call this function if you have previously open() it. 00466 * Note that you can open()/close() a filesystem several times. 00467 * 00468 * @return 1 on success, < 0 on error (has to be a valid libisofs error code) 00469 */ 00470 int (*close)(IsoFilesystem *fs); 00471 00472 /** 00473 * Free implementation specific data. Should never be called by user. 00474 * Use iso_filesystem_unref() instead. 00475 */ 00476 void (*free)(IsoFilesystem *fs); 00477 00478 /* internal usage, do never access them directly */ 00479 unsigned int refcount; 00480 void *data; 00481 }; 00482 00483 /** 00484 * Interface definition for an IsoFileSource. Defines the POSIX-like function 00485 * to access files and abstract underlying source. 00486 * 00487 * @since 0.6.2 00488 */ 00489 struct IsoFileSource_Iface 00490 { 00491 /** 00492 * Tells the version of the interface: 00493 * Version 0 provides functions up to (*lseek)(). 00494 * @since 0.6.2 00495 * Version 1 additionally provides function *(get_aa_string)(). 00496 * @since 0.6.14 00497 */ 00498 int version; 00499 00500 /** 00501 * Get the absolute path in the filesystem this file source belongs to. 00502 * 00503 * @return 00504 * the path of the FileSource inside the filesystem, it should be 00505 * freed when no more needed. 00506 */ 00507 char* (*get_path)(IsoFileSource *src); 00508 00509 /** 00510 * Get the name of the file, with the dir component of the path. 00511 * 00512 * @return 00513 * the name of the file, it should be freed when no more needed. 00514 */ 00515 char* (*get_name)(IsoFileSource *src); 00516 00517 /** 00518 * Get information about the file. It is equivalent to lstat(2). 00519 * 00520 * @return 00521 * 1 success, < 0 error (has to be a valid libisofs error code) 00522 * Error codes: 00523 * ISO_FILE_ACCESS_DENIED 00524 * ISO_FILE_BAD_PATH 00525 * ISO_FILE_DOESNT_EXIST 00526 * ISO_OUT_OF_MEM 00527 * ISO_FILE_ERROR 00528 * ISO_NULL_POINTER 00529 */ 00530 int (*lstat)(IsoFileSource *src, struct stat *info); 00531 00532 /** 00533 * Get information about the file. If the file is a symlink, the info 00534 * returned refers to the destination. It is equivalent to stat(2). 00535 * 00536 * @return 00537 * 1 success, < 0 error 00538 * Error codes: 00539 * ISO_FILE_ACCESS_DENIED 00540 * ISO_FILE_BAD_PATH 00541 * ISO_FILE_DOESNT_EXIST 00542 * ISO_OUT_OF_MEM 00543 * ISO_FILE_ERROR 00544 * ISO_NULL_POINTER 00545 */ 00546 int (*stat)(IsoFileSource *src, struct stat *info); 00547 00548 /** 00549 * Check if the process has access to read file contents. Note that this 00550 * is not necessarily related with (l)stat functions. For example, in a 00551 * filesystem implementation to deal with an ISO image, if the user has 00552 * read access to the image it will be able to read all files inside it, 00553 * despite of the particular permission of each file in the RR tree, that 00554 * are what the above functions return. 00555 * 00556 * @return 00557 * 1 if process has read access, < 0 on error (has to be a valid 00558 * libisofs error code) 00559 * Error codes: 00560 * ISO_FILE_ACCESS_DENIED 00561 * ISO_FILE_BAD_PATH 00562 * ISO_FILE_DOESNT_EXIST 00563 * ISO_OUT_OF_MEM 00564 * ISO_FILE_ERROR 00565 * ISO_NULL_POINTER 00566 */ 00567 int (*access)(IsoFileSource *src); 00568 00569 /** 00570 * Opens the source. 00571 * @return 1 on success, < 0 on error (has to be a valid libisofs error code) 00572 * Error codes: 00573 * ISO_FILE_ALREADY_OPENED 00574 * ISO_FILE_ACCESS_DENIED 00575 * ISO_FILE_BAD_PATH 00576 * ISO_FILE_DOESNT_EXIST 00577 * ISO_OUT_OF_MEM 00578 * ISO_FILE_ERROR 00579 * ISO_NULL_POINTER 00580 */ 00581 int (*open)(IsoFileSource *src); 00582 00583 /** 00584 * Close a previuously openned file 00585 * @return 1 on success, < 0 on error 00586 * Error codes: 00587 * ISO_FILE_ERROR 00588 * ISO_NULL_POINTER 00589 * ISO_FILE_NOT_OPENED 00590 */ 00591 int (*close)(IsoFileSource *src); 00592 00593 /** 00594 * Attempts to read up to count bytes from the given source into 00595 * the buffer starting at buf. 00596 * 00597 * The file src must be open() before calling this, and close() when no 00598 * more needed. Not valid for dirs. On symlinks it reads the destination 00599 * file. 00600 * 00601 * @return 00602 * number of bytes read, 0 if EOF, < 0 on error (has to be a valid 00603 * libisofs error code) 00604 * Error codes: 00605 * ISO_FILE_ERROR 00606 * ISO_NULL_POINTER 00607 * ISO_FILE_NOT_OPENED 00608 * ISO_WRONG_ARG_VALUE -> if count == 0 00609 * ISO_FILE_IS_DIR 00610 * ISO_OUT_OF_MEM 00611 * ISO_INTERRUPTED 00612 */ 00613 int (*read)(IsoFileSource *src, void *buf, size_t count); 00614 00615 /** 00616 * Read a directory. 00617 * 00618 * Each call to this function will return a new children, until we reach 00619 * the end of file (i.e, no more children), in that case it returns 0. 00620 * 00621 * The dir must be open() before calling this, and close() when no more 00622 * needed. Only valid for dirs. 00623 * 00624 * Note that "." and ".." children MUST NOT BE returned. 00625 * 00626 * @param child 00627 * pointer to be filled with the given child. Undefined on error or OEF 00628 * @return 00629 * 1 on success, 0 if EOF (no more children), < 0 on error (has to be 00630 * a valid libisofs error code) 00631 * Error codes: 00632 * ISO_FILE_ERROR 00633 * ISO_NULL_POINTER 00634 * ISO_FILE_NOT_OPENED 00635 * ISO_FILE_IS_NOT_DIR 00636 * ISO_OUT_OF_MEM 00637 */ 00638 int (*readdir)(IsoFileSource *src, IsoFileSource **child); 00639 00640 /** 00641 * Read the destination of a symlink. You don't need to open the file 00642 * to call this. 00643 * 00644 * @param buf 00645 * allocated buffer of at least bufsiz bytes. 00646 * The dest. will be copied there, and it will be NULL-terminated 00647 * @param bufsiz 00648 * characters to be copied. Destination link will be truncated if 00649 * it is larger than given size. This include the 0x0 character. 00650 * @return 00651 * 1 on success, < 0 on error (has to be a valid libisofs error code) 00652 * Error codes: 00653 * ISO_FILE_ERROR 00654 * ISO_NULL_POINTER 00655 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 00656 * ISO_FILE_IS_NOT_SYMLINK 00657 * ISO_OUT_OF_MEM 00658 * ISO_FILE_BAD_PATH 00659 * ISO_FILE_DOESNT_EXIST 00660 * 00661 */ 00662 int (*readlink)(IsoFileSource *src, char *buf, size_t bufsiz); 00663 00664 /** 00665 * Get the filesystem for this source. No extra ref is added, so you 00666 * musn't unref the IsoFilesystem. 00667 * 00668 * @return 00669 * The filesystem, NULL on error 00670 */ 00671 IsoFilesystem* (*get_filesystem)(IsoFileSource *src); 00672 00673 /** 00674 * Free implementation specific data. Should never be called by user. 00675 * Use iso_file_source_unref() instead. 00676 */ 00677 void (*free)(IsoFileSource *src); 00678 00679 /** 00680 * Repositions the offset of the IsoFileSource (must be opened) to the 00681 * given offset according to the value of flag. 00682 * 00683 * @param offset 00684 * in bytes 00685 * @param flag 00686 * 0 The offset is set to offset bytes (SEEK_SET) 00687 * 1 The offset is set to its current location plus offset bytes 00688 * (SEEK_CUR) 00689 * 2 The offset is set to the size of the file plus offset bytes 00690 * (SEEK_END). 00691 * @return 00692 * Absolute offset position of the file, or < 0 on error. Cast the 00693 * returning value to int to get a valid libisofs error. 00694 * 00695 * @since 0.6.4 00696 */ 00697 off_t (*lseek)(IsoFileSource *src, off_t offset, int flag); 00698 00699 /* Add-ons of .version 1 begin here */ 00700 00701 /** 00702 * Valid only if .version is > 0. See above. 00703 * Get the AAIP string with encoded ACL and xattr. 00704 * (Not to be confused with ECMA-119 Extended Attributes). 00705 * 00706 * bit1 and bit2 of flag should be implemented so that freshly fetched 00707 * info does not include the undesired ACL or xattr. Nevertheless if the 00708 * aa_string is cached, then it is permissible that ACL and xattr are still 00709 * delivered. 00710 * 00711 * @param flag Bitfield for control purposes 00712 * bit0= Transfer ownership of AAIP string data. 00713 * src will free the eventual cached data and might 00714 * not be able to produce it again. 00715 * bit1= No need to get ACL (no guarantee of exclusion) 00716 * bit2= No need to get xattr (no guarantee of exclusion) 00717 * @param aa_string Returns a pointer to the AAIP string data. If no AAIP 00718 * string is available, *aa_string becomes NULL. 00719 * (See doc/susp_aaip_*_*.txt for the meaning of AAIP and 00720 * libisofs/aaip_0_2.h for encoding and decoding.) 00721 * The caller is responsible for finally calling free() 00722 * on non-NULL results. 00723 * @return 1 means success (*aa_string == NULL is possible) 00724 * <0 means failure and must b a valid libisofs error code 00725 * (e.g. ISO_FILE_ERROR if no better one can be found). 00726 * @since 0.6.14 00727 */ 00728 int (*get_aa_string)(IsoFileSource *src, 00729 unsigned char **aa_string, int flag); 00730 00731 /* 00732 * TODO #00004 Add a get_mime_type() function. 00733 * This can be useful for GUI apps, to choose the icon of the file 00734 */ 00735 }; 00736 00737 #ifndef __cplusplus 00738 #ifndef Libisofs_h_as_cpluspluS 00739 00740 /** 00741 * An IsoFile Source is a POSIX abstraction of a file. 00742 * 00743 * @since 0.6.2 00744 */ 00745 struct iso_file_source 00746 { 00747 const IsoFileSourceIface *class; 00748 int refcount; 00749 void *data; 00750 }; 00751 00752 #endif /* ! Libisofs_h_as_cpluspluS */ 00753 #endif /* ! __cplusplus */ 00754 00755 /** 00756 * Representation of file contents. It is an stream of bytes, functionally 00757 * like a pipe. 00758 * 00759 * @since 0.6.4 00760 */ 00761 typedef struct iso_stream IsoStream; 00762 00763 /** 00764 * Interface that defines the operations (methods) available for an 00765 * IsoStream. 00766 * 00767 * @see struct IsoStream_Iface 00768 * @since 0.6.4 00769 */ 00770 typedef struct IsoStream_Iface IsoStreamIface; 00771 00772 /** 00773 * Serial number to be used when you can't get a valid id for a Stream by other 00774 * means. If you use this, both fs_id and dev_id should be set to 0. 00775 * This must be incremented each time you get a reference to it. 00776 * 00777 * @see IsoStreamIface->get_id() 00778 * @since 0.6.4 00779 */ 00780 extern ino_t serial_id; 00781 00782 /** 00783 * Interface definition for IsoStream methods. It is public to allow 00784 * implementation of own stream types. 00785 * The methods defined here typically make use of stream.data which points 00786 * to the individual state data of stream instances. 00787 * 00788 * @since 0.6.4 00789 */ 00790 struct IsoStream_Iface 00791 { 00792 /* 00793 * Current version of the interface, set to 1 or 2. 00794 * Version 0 (since 0.6.4) 00795 * deprecated but still valid. 00796 * Version 1 (since 0.6.8) 00797 * update_size() added. 00798 * Version 2 (since 0.6.18) 00799 * get_input_stream() added. A filter stream must have version 2. 00800 * Version 3 (since 0.6.20) 00801 * compare() added. A filter stream should have version 3. 00802 */ 00803 int version; 00804 00805 /** 00806 * Type of Stream. 00807 * "fsrc" -> Read from file source 00808 * "cout" -> Cut out interval from disk file 00809 * "mem " -> Read from memory 00810 * "boot" -> Boot catalog 00811 * "extf" -> External filter program 00812 * "ziso" -> zisofs compression 00813 * "osiz" -> zisofs uncompression 00814 * "gzip" -> gzip compression 00815 * "pizg" -> gzip uncompression (gunzip) 00816 * "user" -> User supplied stream 00817 */ 00818 char type[4]; 00819 00820 /** 00821 * Opens the stream. 00822 * 00823 * @return 00824 * 1 on success, 2 file greater than expected, 3 file smaller than 00825 * expected, < 0 on error (has to be a valid libisofs error code) 00826 */ 00827 int (*open)(IsoStream *stream); 00828 00829 /** 00830 * Close the Stream. 00831 * @return 00832 * 1 on success, < 0 on error (has to be a valid libisofs error code) 00833 */ 00834 int (*close)(IsoStream *stream); 00835 00836 /** 00837 * Get the size (in bytes) of the stream. This function should always 00838 * return the same size, even if the underlying source size changes, 00839 * unless you call update_size() method. 00840 */ 00841 off_t (*get_size)(IsoStream *stream); 00842 00843 /** 00844 * Attempts to read up to count bytes from the given stream into 00845 * the buffer starting at buf. The implementation has to make sure that 00846 * either the full desired count of bytes is delivered or that the 00847 * next call to this function will return EOF or error. 00848 * I.e. only the last read block may be shorter than parameter count. 00849 * 00850 * The stream must be open() before calling this, and close() when no 00851 * more needed. 00852 * 00853 * @return 00854 * number of bytes read, 0 if EOF, < 0 on error (has to be a valid 00855 * libisofs error code) 00856 */ 00857 int (*read)(IsoStream *stream, void *buf, size_t count); 00858 00859 /** 00860 * Whether this IsoStream can be read several times, with the same results. 00861 * For example, a regular file is repeatable, you can read it as many 00862 * times as you want. However, a pipe isn't. 00863 * 00864 * This function doesn't take into account if the file has been modified 00865 * between the two reads. 00866 * 00867 * @return 00868 * 1 if stream is repeatable, 0 if not, 00869 * < 0 on error (has to be a valid libisofs error code) 00870 */ 00871 int (*is_repeatable)(IsoStream *stream); 00872 00873 /** 00874 * Get an unique identifier for the IsoStream. 00875 */ 00876 void (*get_id)(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, 00877 ino_t *ino_id); 00878 00879 /** 00880 * Free implementation specific data. Should never be called by user. 00881 * Use iso_stream_unref() instead. 00882 */ 00883 void (*free)(IsoStream *stream); 00884 00885 /** 00886 * Updates the size of the IsoStream with the current size of the 00887 * underlying source. After calling this, get_size() will return 00888 * the new size. This should never be called after 00889 * iso_image_create_burn_source() was called and the image was not 00890 * completely written. To update the size of all files before written the 00891 * image, you may want to call iso_image_update_sizes() just before 00892 * iso_image_create_burn_source(). 00893 * 00894 * @return 00895 * 1 if ok, < 0 on error (has to be a valid libisofs error code) 00896 * 00897 * @since 0.6.8 00898 * Present if .version is 1 or higher. 00899 */ 00900 int (*update_size)(IsoStream *stream); 00901 00902 /** 00903 * Obtains the eventual input stream of a filter stream. 00904 * 00905 * @param stream 00906 * The eventual filter stream to be inquired. 00907 * @param flag 00908 * Bitfield for control purposes. Submit 0 for now. 00909 * @return 00910 * The input stream, if one exists. Elsewise NULL. 00911 * No extra reference to the stream is taken by this call. 00912 * 00913 * @since 0.6.18 00914 * Present if .version is 2 or higher. 00915 */ 00916 IsoStream *(*get_input_stream)(IsoStream *stream, int flag); 00917 00918 /** 00919 * Compare two streams whether they are based on the same input and will 00920 * produce the same output. If in any doubt, then this comparison should 00921 * indicate no match. A match might allow hardlinking of IsoFile objects. 00922 * 00923 * This function has to establish an equivalence and order relation: 00924 * cmp_ino(A,A) == 0 00925 * cmp_ino(A,B) == -cmp_ino(B,A) 00926 * if cmp_ino(A,B) == 0 && cmp_ino(B,C) == 0 then cmp_ino(A,C) == 0 00927 * if cmp_ino(A,B) < 0 && cmp_ino(B,C) < 0 then cmp_ino(A,C) < 0 00928 * 00929 * A big hazard to the last constraint are tests which do not apply to some 00930 * types of streams. In this case for any A that is applicable and any B 00931 * that is not applicable, cmp_ino(A,B) must have the same non-zero 00932 * result. I.e. a pair of applicable and non-applicable streams must 00933 * return that non-zero result before the test for a pair of applicable 00934 * streams would happen. 00935 * 00936 * A function s1.(*cmp_ino)() must only accept stream s2 if function 00937 * s2.(*cmp_ino)() would accept s1. Best is to accept only the own stream 00938 * type or to have the same function for a family of similar stream types. 00939 * 00940 * If the function cannot accept one of the given stream types, then 00941 * the decision must be delegated to 00942 * iso_stream_cmp_ino(s1, s2, 1); 00943 * This is also appropriate if one has reason to implement stream.cmp_ino() 00944 * without special comparison algorithm. 00945 * With filter streams the decision whether the underlying chains of 00946 * streams match should be delegated to 00947 * iso_stream_cmp_ino(iso_stream_get_input_stream(s1, 0), 00948 * iso_stream_get_input_stream(s2, 0), 0); 00949 * 00950 * @param s1 00951 * The first stream to compare. Expect foreign stream types. 00952 * @param s2 00953 * The second stream to compare. Expect foreign stream types. 00954 * @return 00955 * -1 if s1 is smaller s2 , 0 if s1 matches s2 , 1 if s1 is larger s2 00956 * 00957 * @since 0.6.20 00958 * Present if .version is 3 or higher. 00959 */ 00960 int (*cmp_ino)(IsoStream *s1, IsoStream *s2); 00961 00962 }; 00963 00964 #ifndef __cplusplus 00965 #ifndef Libisofs_h_as_cpluspluS 00966 00967 /** 00968 * Representation of file contents as a stream of bytes. 00969 * 00970 * @since 0.6.4 00971 */ 00972 struct iso_stream 00973 { 00974 IsoStreamIface *class; 00975 int refcount; 00976 void *data; 00977 }; 00978 00979 #endif /* ! Libisofs_h_as_cpluspluS */ 00980 #endif /* ! __cplusplus */ 00981 00982 00983 /** 00984 * Initialize libisofs. Before any usage of the library you must either call 00985 * this function or iso_init_with_flag(). 00986 * Only exception from this rule: iso_lib_version(), iso_lib_is_compatible(). 00987 * @return 1 on success, < 0 on error 00988 * 00989 * @since 0.6.2 00990 */ 00991 int iso_init(); 00992 00993 /** 00994 * Initialize libisofs. Before any usage of the library you must either call 00995 * this function or iso_init() which is equivalent to iso_init_with_flag(0). 00996 * Only exception from this rule: iso_lib_version(), iso_lib_is_compatible(). 00997 * @param flag 00998 * Bitfield for control purposes 00999 * bit0= do not set up locale by LC_* environment variables 01000 * @return 1 on success, < 0 on error 01001 * 01002 * @since 0.6.18 01003 */ 01004 int iso_init_with_flag(int flag); 01005 01006 /** 01007 * Finalize libisofs. 01008 * 01009 * @since 0.6.2 01010 */ 01011 void iso_finish(); 01012 01013 /** 01014 * Override the reply of libc function nl_langinfo(CODESET) which may or may 01015 * not give the name of the character set which is in effect for your 01016 * environment. So this call can compensate for inconsistent terminal setups. 01017 * Another use case is to choose UTF-8 as intermediate character set for a 01018 * conversion from an exotic input character set to an exotic output set. 01019 * 01020 * @param name 01021 * Name of the character set to be assumed as "local" one. 01022 * @param flag 01023 * Unused yet. Submit 0. 01024 * @return 01025 * 1 indicates success, <=0 failure 01026 * 01027 * @since 0.6.12 01028 */ 01029 int iso_set_local_charset(char *name, int flag); 01030 01031 /** 01032 * Obtain the local charset as currently assumed by libisofs. 01033 * The result points to internal memory. It is volatile and must not be 01034 * altered. 01035 * 01036 * @param flag 01037 * Unused yet. Submit 0. 01038 * 01039 * @since 0.6.12 01040 */ 01041 char *iso_get_local_charset(int flag); 01042 01043 /** 01044 * Create a new image, empty. 01045 * 01046 * The image will be owned by you and should be unref() when no more needed. 01047 * 01048 * @param name 01049 * Name of the image. This will be used as volset_id and volume_id. 01050 * @param image 01051 * Location where the image pointer will be stored. 01052 * @return 01053 * 1 sucess, < 0 error 01054 * 01055 * @since 0.6.2 01056 */ 01057 int iso_image_new(const char *name, IsoImage **image); 01058 01059 01060 /** 01061 * Control whether ACL and xattr will be imported from external filesystems 01062 * (typically the local POSIX filesystem) when new nodes get inserted. If 01063 * enabled by iso_write_opts_set_aaip() they will later be written into the 01064 * image as AAIP extension fields. 01065 * 01066 * A change of this setting does neither affect existing IsoNode objects 01067 * nor the way how ACL and xattr are handled when loading an ISO image. 01068 * The latter is controlled by iso_read_opts_set_no_aaip(). 01069 * 01070 * @param image 01071 * The image of which the behavior is to be controlled 01072 * @param what 01073 * A bit field which sets the behavior: 01074 * bit0= ignore ACLs if the external file object bears some 01075 * bit1= ignore xattr if the external file object bears some 01076 * all other bits are reserved 01077 * 01078 * @since 0.6.14 01079 */ 01080 void iso_image_set_ignore_aclea(IsoImage *image, int what); 01081 01082 01083 /** 01084 * The following two functions three macros are utilities to help ensuring 01085 * version match of application, compile time header, and runtime library. 01086 */ 01087 /** 01088 * Get version of the libisofs library at runtime. 01089 * NOTE: This function may be called before iso_init(). 01090 * 01091 * @since 0.6.2 01092 */ 01093 void iso_lib_version(int *major, int *minor, int *micro); 01094 01095 /** 01096 * Check at runtime if the library is ABI compatible with the given version. 01097 * NOTE: This function may be called before iso_init(). 01098 * 01099 * @return 01100 * 1 lib is compatible, 0 is not. 01101 * 01102 * @since 0.6.2 01103 */ 01104 int iso_lib_is_compatible(int major, int minor, int micro); 01105 01106 01107 /** 01108 * These three release version numbers tell the revision of this header file 01109 * and of the API it describes. They are memorized by applications at 01110 * compile time. 01111 * They must show the same values as these symbols in ./configure.ac 01112 * LIBISOFS_MAJOR_VERSION=... 01113 * LIBISOFS_MINOR_VERSION=... 01114 * LIBISOFS_MICRO_VERSION=... 01115 * Note to anybody who does own work inside libisofs: 01116 * Any change of configure.ac or libisofs.h has to keep up this equality ! 01117 * 01118 * Before usage of these macros on your code, please read the usage discussion 01119 * below. 01120 * 01121 * @since 0.6.2 01122 */ 01123 #define iso_lib_header_version_major 0 01124 #define iso_lib_header_version_minor 6 01125 #define iso_lib_header_version_micro 38 01126 01127 /** 01128 * Usage discussion: 01129 * 01130 * Some developers of the libburnia project have differing opinions how to 01131 * ensure the compatibility of libaries and applications. 01132 * 01133 * It is about whether to use at compile time and at runtime the version 01134 * numbers provided here. Thomas Schmitt advises to use them. Vreixo Formoso 01135 * advises to use other means. 01136 * 01137 * At compile time: 01138 * 01139 * Vreixo Formoso advises to leave proper version matching to properly 01140 * programmed checks in the the application's build system, which will 01141 * eventually refuse compilation. 01142 * 01143 * Thomas Schmitt advises to use the macros defined here for comparison with 01144 * the application's requirements of library revisions and to eventually 01145 * break compilation. 01146 * 01147 * Both advises are combinable. I.e. be master of your build system and have 01148 * #if checks in the source code of your application, nevertheless. 01149 * 01150 * At runtime (via iso_lib_is_compatible()): 01151 * 01152 * Vreixo Formoso advises to compare the application's requirements of 01153 * library revisions with the runtime library. This is to allow runtime 01154 * libraries which are young enough for the application but too old for 01155 * the lib*.h files seen at compile time. 01156 * 01157 * Thomas Schmitt advises to compare the header revisions defined here with 01158 * the runtime library. This is to enforce a strictly monotonous chain of 01159 * revisions from app to header to library, at the cost of excluding some older 01160 * libraries. 01161 * 01162 * These two advises are mutually exclusive. 01163 */ 01164 01165 01166 /** 01167 * Creates an IsoWriteOpts for writing an image. You should set the options 01168 * desired with the correspondent setters. 01169 * 01170 * Options by default are determined by the selected profile. Fifo size is set 01171 * by default to 2 MB. 01172 * 01173 * @param opts 01174 * Pointer to the location where the newly created IsoWriteOpts will be 01175 * stored. You should free it with iso_write_opts_free() when no more 01176 * needed. 01177 * @param profile 01178 * Default profile for image creation. For now the following values are 01179 * defined: 01180 * ---> 0 [BASIC] 01181 * No extensions are enabled, and ISO level is set to 1. Only suitable 01182 * for usage for very old and limited systems (like MS-DOS), or by a 01183 * start point from which to set your custom options. 01184 * ---> 1 [BACKUP] 01185 * POSIX compatibility for backup. Simple settings, ISO level is set to 01186 * 3 and RR extensions are enabled. Useful for backup purposes. 01187 * Note that ACL and xattr are not enabled by default. 01188 * If you enable them, expect them not to show up in the mounted image. 01189 * They will have to be retrieved by libisofs applications like xorriso. 01190 * ---> 2 [DISTRIBUTION] 01191 * Setting for information distribution. Both RR and Joliet are enabled 01192 * to maximize compatibility with most systems. Permissions are set to 01193 * default values, and timestamps to the time of recording. 01194 * @return 01195 * 1 success, < 0 error 01196 * 01197 * @since 0.6.2 01198 */ 01199 int iso_write_opts_new(IsoWriteOpts **opts, int profile); 01200 01201 /** 01202 * Free an IsoWriteOpts previously allocated with iso_write_opts_new(). 01203 * 01204 * @since 0.6.2 01205 */ 01206 void iso_write_opts_free(IsoWriteOpts *opts); 01207 01208 /** 01209 * Set the ISO-9960 level to write at. 01210 * 01211 * @param opts 01212 * The option set to be manipulated. 01213 * @param level 01214 * -> 1 for higher compatibility with old systems. With this level 01215 * filenames are restricted to 8.3 characters. 01216 * -> 2 to allow up to 31 filename characters. 01217 * -> 3 to allow files greater than 4GB 01218 * @return 01219 * 1 success, < 0 error 01220 * 01221 * @since 0.6.2 01222 */ 01223 int iso_write_opts_set_iso_level(IsoWriteOpts *opts, int level); 01224 01225 /** 01226 * Whether to use or not Rock Ridge extensions. 01227 * 01228 * This are standard extensions to ECMA-119, intended to add POSIX filesystem 01229 * features to ECMA-119 images. Thus, usage of this flag is highly recommended 01230 * for images used on GNU/Linux systems. With the usage of RR extension, the 01231 * resulting image will have long filenames (up to 255 characters), deeper 01232 * directory structure, POSIX permissions and owner info on files and 01233 * directories, support for symbolic links or special files... All that 01234 * attributes can be modified/setted with the appropiate function. 01235 * 01236 * @param opts 01237 * The option set to be manipulated. 01238 * @param enable 01239 * 1 to enable RR extension, 0 to not add them 01240 * @return 01241 * 1 success, < 0 error 01242 * 01243 * @since 0.6.2 01244 */ 01245 int iso_write_opts_set_rockridge(IsoWriteOpts *opts, int enable); 01246 01247 /** 01248 * Whether to add the non-standard Joliet extension to the image. 01249 * 01250 * This extensions are heavily used in Microsoft Windows systems, so if you 01251 * plan to use your disc on such a system you should add this extension. 01252 * Usage of Joliet supplies longer filesystem length (up to 64 unicode 01253 * characters), and deeper directory structure. 01254 * 01255 * @param opts 01256 * The option set to be manipulated. 01257 * @param enable 01258 * 1 to enable Joliet extension, 0 to not add them 01259 * @return 01260 * 1 success, < 0 error 01261 * 01262 * @since 0.6.2 01263 */ 01264 int iso_write_opts_set_joliet(IsoWriteOpts *opts, int enable); 01265 01266 /** 01267 * Whether to use newer ISO-9660:1999 version. 01268 * 01269 * This is the second version of ISO-9660. It allows longer filenames and has 01270 * less restrictions than old ISO-9660. However, nobody is using it so there 01271 * are no much reasons to enable this. 01272 * 01273 * @since 0.6.2 01274 */ 01275 int iso_write_opts_set_iso1999(IsoWriteOpts *opts, int enable); 01276 01277 /** 01278 * Control generation of non-unique inode numbers for the emerging image. 01279 * Inode numbers get written as "file serial number" with PX entries as of 01280 * RRIP-1.12. They may mark families of hardlinks. 01281 * RRIP-1.10 prescribes a PX entry without file serial number. If not overriden 01282 * by iso_write_opts_set_rrip_1_10_px_ino() there will be no file serial number 01283 * written into RRIP-1.10 images. 01284 * 01285 * Inode number generation does not affect IsoNode objects which imported their 01286 * inode numbers from the old ISO image (see iso_read_opts_set_new_inos()) 01287 * and which have not been altered since import. It rather applies to IsoNode 01288 * objects which were newly added to the image, or to IsoNode which brought no 01289 * inode number from the old image, or to IsoNode where certain properties 01290 * have been altered since image import. 01291 * 01292 * If two IsoNode are found with same imported inode number but differing 01293 * properties, then one of them will get assigned a new unique inode number. 01294 * I.e. the hardlink relation between both IsoNode objects ends. 01295 * 01296 * @param opts 01297 * The option set to be manipulated. 01298 * @param enable 01299 * 1 = Collect IsoNode objects which have identical data sources and 01300 * properties. 01301 * 0 = Generate unique inode numbers for all IsoNode objects which do not 01302 * have a valid inode number from an imported ISO image. 01303 * All other values are reserved. 01304 * 01305 * @since 0.6.20 01306 */ 01307 int iso_write_opts_set_hardlinks(IsoWriteOpts *opts, int enable); 01308 01309 /** 01310 * Control writing of AAIP informations for ACL and xattr. 01311 * For importing ACL and xattr when inserting nodes from external filesystems 01312 * (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea(). 01313 * For loading of this information from images see iso_read_opts_set_no_aaip(). 01314 * 01315 * @param opts 01316 * The option set to be manipulated. 01317 * @param enable 01318 * 1 = write AAIP information from nodes into the image 01319 * 0 = do not write AAIP information into the image 01320 * All other values are reserved. 01321 * 01322 * @since 0.6.14 01323 */ 01324 int iso_write_opts_set_aaip(IsoWriteOpts *opts, int enable); 01325 01326 /** 01327 * Omit the version number (";1") at the end of the ISO-9660 identifiers. 01328 * This breaks ECMA-119 specification, but version numbers are usually not 01329 * used, so it should work on most systems. Use with caution. 01330 * @param opts 01331 * The option set to be manipulated. 01332 * @param omit 01333 * bit0= omit version number with ECMA-119 and Joliet 01334 * bit1= omit version number with Joliet alone (@since 0.6.30) 01335 * @since 0.6.2 01336 */ 01337 int iso_write_opts_set_omit_version_numbers(IsoWriteOpts *opts, int omit); 01338 01339 /** 01340 * Allow ISO-9660 directory hierarchy to be deeper than 8 levels. 01341 * This breaks ECMA-119 specification. Use with caution. 01342 * 01343 * @since 0.6.2 01344 */ 01345 int iso_write_opts_set_allow_deep_paths(IsoWriteOpts *opts, int allow); 01346 01347 /** 01348 * Allow path in the ISO-9660 tree to have more than 255 characters. 01349 * This breaks ECMA-119 specification. Use with caution. 01350 * 01351 * @since 0.6.2 01352 */ 01353 int iso_write_opts_set_allow_longer_paths(IsoWriteOpts *opts, int allow); 01354 01355 /** 01356 * Allow a single file or directory hierarchy to have up to 37 characters. 01357 * This is larger than the 31 characters allowed by ISO level 2, and the 01358 * extra space is taken from the version number, so this also forces 01359 * omit_version_numbers. 01360 * This breaks ECMA-119 specification and could lead to buffer overflow 01361 * problems on old systems. Use with caution. 01362 * 01363 * @since 0.6.2 01364 */ 01365 int iso_write_opts_set_max_37_char_filenames(IsoWriteOpts *opts, int allow); 01366 01367 /** 01368 * ISO-9660 forces filenames to have a ".", that separates file name from 01369 * extension. libisofs adds it if original filename doesn't has one. Set 01370 * this to 1 to prevent this behavior. 01371 * This breaks ECMA-119 specification. Use with caution. 01372 * 01373 * @param opts 01374 * The option set to be manipulated. 01375 * @param no 01376 * bit0= no forced dot with ECMA-119 01377 * bit1= no forced dot with Joliet (@since 0.6.30) 01378 * 01379 * @since 0.6.2 01380 */ 01381 int iso_write_opts_set_no_force_dots(IsoWriteOpts *opts, int no); 01382 01383 /** 01384 * Allow lowercase characters in ISO-9660 filenames. By default, only 01385 * uppercase characters, numbers and a few other characters are allowed. 01386 * This breaks ECMA-119 specification. Use with caution. 01387 * 01388 * @since 0.6.2 01389 */ 01390 int iso_write_opts_set_allow_lowercase(IsoWriteOpts *opts, int allow); 01391 01392 /** 01393 * Allow all ASCII characters to be appear on an ISO-9660 filename. Note 01394 * that "/" and 0x0 characters are never allowed, even in RR names. 01395 * This breaks ECMA-119 specification. Use with caution. 01396 * 01397 * @since 0.6.2 01398 */ 01399 int iso_write_opts_set_allow_full_ascii(IsoWriteOpts *opts, int allow); 01400 01401 /** 01402 * Allow all characters to be part of Volume and Volset identifiers on 01403 * the Primary Volume Descriptor. This breaks ISO-9660 contraints, but 01404 * should work on modern systems. 01405 * 01406 * @since 0.6.2 01407 */ 01408 int iso_write_opts_set_relaxed_vol_atts(IsoWriteOpts *opts, int allow); 01409 01410 /** 01411 * Allow paths in the Joliet tree to have more than 240 characters. 01412 * This breaks Joliet specification. Use with caution. 01413 * 01414 * @since 0.6.2 01415 */ 01416 int iso_write_opts_set_joliet_longer_paths(IsoWriteOpts *opts, int allow); 01417 01418 /** 01419 * Write Rock Ridge info as of specification RRIP-1.10 rather than RRIP-1.12: 01420 * signature "RRIP_1991A" rather than "IEEE_1282", field PX without file 01421 * serial number. 01422 * 01423 * @since 0.6.12 01424 */ 01425 int iso_write_opts_set_rrip_version_1_10(IsoWriteOpts *opts, int oldvers); 01426 01427 /** 01428 * Write field PX with file serial number (i.e. inode number) even if 01429 * iso_write_opts_set_rrip_version_1_10(,1) is in effect. 01430 * This clearly violates the RRIP-1.10 specs. But it is done by mkisofs since 01431 * a while and no widespread protest is visible in the web. 01432 * If this option is not enabled, then iso_write_opts_set_hardlinks() will 01433 * only have an effect with iso_write_opts_set_rrip_version_1_10(,0). 01434 * 01435 * @since 0.6.20 01436 */ 01437 int iso_write_opts_set_rrip_1_10_px_ino(IsoWriteOpts *opts, int enable); 01438 01439 /** 01440 * Write AAIP as extension according to SUSP 1.10 rather than SUSP 1.12. 01441 * I.e. without announcing it by an ER field and thus without the need 01442 * to preceed the RRIP fields and the AAIP field by ES fields. 01443 * This saves 5 to 10 bytes per file and might avoid problems with readers 01444 * which dislike ER fields other than the ones for RRIP. 01445 * On the other hand, SUSP 1.12 frowns on such unannounced extensions 01446 * and prescribes ER and ES. It does this since the year 1994. 01447 * 01448 * In effect only if above iso_write_opts_set_aaip() enables writing of AAIP. 01449 * 01450 * @since 0.6.14 01451 */ 01452 int iso_write_opts_set_aaip_susp_1_10(IsoWriteOpts *opts, int oldvers); 01453 01454 /** 01455 * Store as ECMA-119 Directory Record timestamp the mtime of the source 01456 * rather than the image creation time. 01457 * 01458 * @since 0.6.12 01459 */ 01460 int iso_write_opts_set_dir_rec_mtime(IsoWriteOpts *opts, int allow); 01461 01462 /** 01463 * Whether to sort files based on their weight. 01464 * 01465 * @see iso_node_set_sort_weight 01466 * @since 0.6.2 01467 */ 01468 int iso_write_opts_set_sort_files(IsoWriteOpts *opts, int sort); 01469 01470 /** 01471 * Whether to compute and record MD5 checksums for the whole session and/or 01472 * for each single IsoFile object. The checksums represent the data as they 01473 * were written into the image output stream, not necessarily as they were 01474 * on hard disk at any point of time. 01475 * See also calls iso_image_get_session_md5() and iso_file_get_md5(). 01476 * @param opts 01477 * The option set to be manipulated. 01478 * @param session 01479 * If bit0 set: Compute session checksum 01480 * @param files 01481 * If bit0 set: Compute a checksum for each single IsoFile object which 01482 * gets its data content written into the session. Copy 01483 * checksums from files which keep their data in older 01484 * sessions. 01485 * If bit1 set: Check content stability (only with bit0). I.e. before 01486 * writing the file content into to image stream, read it 01487 * once and compute a MD5. Do a second reading for writing 01488 * into the image stream. Afterwards compare both MD5 and 01489 * issue a MISHAP event ISO_MD5_STREAM_CHANGE if they do not 01490 * match. 01491 * Such a mismatch indicates content changes between the 01492 * time point when the first MD5 reading started and the 01493 * time point when the last block was read for writing. 01494 * So there is high risk that the image stream was fed from 01495 * changing and possibly inconsistent file content. 01496 * 01497 * @since 0.6.22 01498 */ 01499 int iso_write_opts_set_record_md5(IsoWriteOpts *opts, int session, int files); 01500 01501 /** 01502 * Set the parameters "name" and "timestamp" for a scdbackup checksum tag. 01503 * It will be appended to the libisofs session tag if the image starts at 01504 * LBA 0 (see iso_write_opts_set_ms_block()). The scdbackup tag can be used 01505 * to verify the image by command scdbackup_verify device -auto_end. 01506 * See scdbackup/README appendix VERIFY for its inner details. 01507 * 01508 * @param opts 01509 * The option set to be manipulated. 01510 * @param name 01511 * A word of up to 80 characters. Typically volno_totalno telling 01512 * that this is volume volno of a total of totalno volumes. 01513 * @param timestamp 01514 * A string of 13 characters YYMMDD.hhmmss (e.g. A90831.190324). 01515 * A9 = 2009, B0 = 2010, B1 = 2011, ... C0 = 2020, ... 01516 * @param tag_written 01517 * Either NULL or the address of an array with at least 512 characters. 01518 * In the latter case the eventually produced scdbackup tag will be 01519 * copied to this array when the image gets written. This call sets 01520 * scdbackup_tag_written[0] = 0 to mark its preliminary invalidity. 01521 * @return 01522 * 1 indicates success, <0 is error 01523 * 01524 * @since 0.6.24 01525 */ 01526 int iso_write_opts_set_scdbackup_tag(IsoWriteOpts *opts, 01527 char *name, char *timestamp, 01528 char *tag_written); 01529 01530 /** 01531 * Whether to set default values for files and directory permissions, gid and 01532 * uid. All these take one of three values: 0, 1 or 2. 01533 * 01534 * If 0, the corresponding attribute will be kept as set in the IsoNode. 01535 * Unless you have changed it, it corresponds to the value on disc, so it 01536 * is suitable for backup purposes. If set to 1, the corresponding attrib. 01537 * will be changed by a default suitable value. Finally, if you set it to 01538 * 2, the attrib. will be changed with the value specified by the functioins 01539 * below. Note that for mode attributes, only the permissions are set, the 01540 * file type remains unchanged. 01541 * 01542 * @see iso_write_opts_set_default_dir_mode 01543 * @see iso_write_opts_set_default_file_mode 01544 * @see iso_write_opts_set_default_uid 01545 * @see iso_write_opts_set_default_gid 01546 * @since 0.6.2 01547 */ 01548 int iso_write_opts_set_replace_mode(IsoWriteOpts *opts, int dir_mode, 01549 int file_mode, int uid, int gid); 01550 01551 /** 01552 * Set the mode to use on dirs when you set the replace_mode of dirs to 2. 01553 * 01554 * @see iso_write_opts_set_replace_mode 01555 * @since 0.6.2 01556 */ 01557 int iso_write_opts_set_default_dir_mode(IsoWriteOpts *opts, mode_t dir_mode); 01558 01559 /** 01560 * Set the mode to use on files when you set the replace_mode of files to 2. 01561 * 01562 * @see iso_write_opts_set_replace_mode 01563 * @since 0.6.2 01564 */ 01565 int iso_write_opts_set_default_file_mode(IsoWriteOpts *opts, mode_t file_mode); 01566 01567 /** 01568 * Set the uid to use when you set the replace_uid to 2. 01569 * 01570 * @see iso_write_opts_set_replace_mode 01571 * @since 0.6.2 01572 */ 01573 int iso_write_opts_set_default_uid(IsoWriteOpts *opts, uid_t uid); 01574 01575 /** 01576 * Set the gid to use when you set the replace_gid to 2. 01577 * 01578 * @see iso_write_opts_set_replace_mode 01579 * @since 0.6.2 01580 */ 01581 int iso_write_opts_set_default_gid(IsoWriteOpts *opts, gid_t gid); 01582 01583 /** 01584 * 0 to use IsoNode timestamps, 1 to use recording time, 2 to use 01585 * values from timestamp field. This has only meaning if RR extensions 01586 * are enabled. 01587 * 01588 * @see iso_write_opts_set_default_timestamp 01589 * @since 0.6.2 01590 */ 01591 int iso_write_opts_set_replace_timestamps(IsoWriteOpts *opts, int replace); 01592 01593 /** 01594 * Set the timestamp to use when you set the replace_timestamps to 2. 01595 * 01596 * @see iso_write_opts_set_replace_timestamps 01597 * @since 0.6.2 01598 */ 01599 int iso_write_opts_set_default_timestamp(IsoWriteOpts *opts, time_t timestamp); 01600 01601 /** 01602 * Whether to always record timestamps in GMT. 01603 * 01604 * By default, libisofs stores local time information on image. You can set 01605 * this to always store timestamps converted to GMT. This prevents any 01606 * discrimination of the timezone of the image preparer by the image reader. 01607 * 01608 * It is useful if you want to hide your timezone, or you live in a timezone 01609 * that can't be represented in ECMA-119. These are timezones with an offset 01610 * from GMT greater than +13 hours, lower than -12 hours, or not a multiple 01611 * of 15 minutes. 01612 * Negative timezones (west of GMT) can trigger bugs in some operating systems 01613 * which typically appear in mounted ISO images as if the timezone shift from 01614 * GMT was applied twice (e.g. in New York 22:36 becomes 17:36). 01615 * 01616 * @since 0.6.2 01617 */ 01618 int iso_write_opts_set_always_gmt(IsoWriteOpts *opts, int gmt); 01619 01620 /** 01621 * Set the charset to use for the RR names of the files that will be created 01622 * on the image. 01623 * NULL to use default charset, that is the locale charset. 01624 * You can obtain the list of charsets supported on your system executing 01625 * "iconv -l" in a shell. 01626 * 01627 * @since 0.6.2 01628 */ 01629 int iso_write_opts_set_output_charset(IsoWriteOpts *opts, const char *charset); 01630 01631 /** 01632 * Set the type of image creation in case there was already an existing 01633 * image imported. Libisofs supports two types of creation: 01634 * stand-alone and appended. 01635 * 01636 * A stand-alone image is an image that does not need the old image any more 01637 * for being mounted by the operating system or imported by libisofs. It may 01638 * be written beginning with byte 0 of optical media or disk file objects. 01639 * There will be no distinction between files from the old image and those 01640 * which have been added by the new image generation. 01641 * 01642 * On the other side, an appended image is not self contained. It may refer 01643 * to files that stay stored in the imported existing image. 01644 * This usage model is inspired by CD multi-session. It demands that the 01645 * appended image is finally written to the same media resp. disk file 01646 * as the imported image at an address behind the end of that imported image. 01647 * The exact address may depend on media peculiarities and thus has to be 01648 * announced by the application via iso_write_opts_set_ms_block(). 01649 * The real address where the data will be written is under control of the 01650 * consumer of the struct burn_source which takes the output of libisofs 01651 * image generation. It may be the one announced to libisofs or an intermediate 01652 * one. Nevertheless, the image will be readable only at the announced address. 01653 * 01654 * If you have not imported a previous image by iso_image_import(), then the 01655 * image will always be a stand-alone image, as there is no previous data to 01656 * refer to. 01657 * 01658 * @param opts 01659 * The option set to be manipulated. 01660 * @param append 01661 * 1 to create an appended image, 0 for an stand-alone one. 01662 * 01663 * @since 0.6.2 01664 */ 01665 int iso_write_opts_set_appendable(IsoWriteOpts *opts, int append); 01666 01667 /** 01668 * Set the start block of the image. It is supposed to be the lba where the 01669 * first block of the image will be written on disc. All references inside the 01670 * ISO image will take this into account, thus providing a mountable image. 01671 * 01672 * For appendable images, that are written to a new session, you should 01673 * pass here the lba of the next writable address on disc. 01674 * 01675 * In stand alone images this is usually 0. However, you may want to 01676 * provide a different ms_block if you don't plan to burn the image in the 01677 * first session on disc, such as in some CD-Extra disc whether the data 01678 * image is written in a new session after some audio tracks. 01679 * 01680 * @since 0.6.2 01681 */ 01682 int iso_write_opts_set_ms_block(IsoWriteOpts *opts, uint32_t ms_block); 01683 01684 /** 01685 * Sets the buffer where to store the descriptors which shall be written 01686 * at the beginning of an overwriteable media to point to the newly written 01687 * image. 01688 * This is needed if the write start address of the image is not 0. 01689 * In this case the first 64 KiB of the media have to be overwritten 01690 * by the buffer content after the session was written and the buffer 01691 * was updated by libisofs. Otherwise the new session would not be 01692 * found by operating system function mount() or by libisoburn. 01693 * (One could still mount that session if its start address is known.) 01694 * 01695 * If you do not need this information, for example because you are creating a 01696 * new image for LBA 0 or because you will create an image for a true 01697 * multisession media, just do not use this call or set buffer to NULL. 01698 * 01699 * Use cases: 01700 * 01701 * - Together with iso_write_opts_set_appendable(opts, 1) the buffer serves 01702 * for the growing of an image as done in growisofs by Andy Polyakov. 01703 * This allows appending of a new session to non-multisession media, such 01704 * as DVD+RW. The new session will refer to the data of previous sessions 01705 * on the same media. 01706 * libisoburn emulates multisession appendability on overwriteable media 01707 * and disk files by performing this use case. 01708 * 01709 * - Together with iso_write_opts_set_appendable(opts, 0) the buffer allows 01710 * to write the first session on overwriteable media to start addresses 01711 * other than 0. 01712 * This address must not be smaller than 32 blocks plus the eventual 01713 * partition offset as defined by iso_write_opts_set_part_offset(). 01714 * libisoburn in most cases writes the first session on overwriteable media 01715 * and disk files to LBA (32 + partition_offset) in order to preserve its 01716 * descriptors from the subsequent overwriting by the descriptor buffer of 01717 * later sessions. 01718 * 01719 * @param opts 01720 * The option set to be manipulated. 01721 * @param overwrite 01722 * When not NULL, it should point to at least 64KiB of memory, where 01723 * libisofs will install the contents that shall be written at the 01724 * beginning of overwriteable media. 01725 * You should initialize the buffer either with 0s, or with the contents 01726 * of the first 32 blocks of the image you are growing. In most cases, 01727 * 0 is good enought. 01728 * IMPORTANT: If you use iso_write_opts_set_part_offset() then the 01729 * overwrite buffer must be larger by the offset defined there. 01730 * 01731 * @since 0.6.2 01732 */ 01733 int iso_write_opts_set_overwrite_buf(IsoWriteOpts *opts, uint8_t *overwrite); 01734 01735 /** 01736 * Set the size, in number of blocks, of the ring buffer used between the 01737 * writer thread and the burn_source. You have to provide at least a 32 01738 * blocks buffer. Default value is set to 2MB, if that is ok for you, you 01739 * don't need to call this function. 01740 * 01741 * @since 0.6.2 01742 */ 01743 int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size); 01744 01745 /* 01746 * Attach 32 kB of binary data which shall get written to the first 32 kB 01747 * of the ISO image, the ECMA-119 System Area. This space is intended for 01748 * system dependent boot software, e.g. a Master Boot Record which allows to 01749 * boot from USB sticks or hard disks. ECMA-119 makes no own assumptions or 01750 * prescriptions about the byte content. 01751 * 01752 * If system area data are given or options bit0 is set, then bit1 of 01753 * el_torito_set_isolinux_options() is automatically disabled. 01754 * @param data 01755 * Either NULL or 32 kB of data. Do not submit less bytes ! 01756 * @param options 01757 * Can cause manipulations of submitted data before they get written: 01758 * bit0= Only with System area type 0 = MBR 01759 * Apply a --protective-msdos-label as of grub-mkisofs. 01760 * This means to patch bytes 446 to 512 of the system area so 01761 * that one partition is defined which begins at the second 01762 * 512-byte block of the image and ends where the image ends. 01763 * This works with and without system_area_data. 01764 * bit1= Only with System area type 0 = MBR 01765 * Apply isohybrid MBR patching to the system area. 01766 * This works only with system area data from SYSLINUX plus an 01767 * ISOLINUX boot image (see iso_image_set_boot_image()) and 01768 * only if not bit0 is set. 01769 * bit2-7= System area type 01770 * 0= with bit0 or bit1: MBR 01771 * else: unspecified type which will be used unaltered. 01772 * @since 0.6.38 01773 * 1= MIPS Big Endian Volume Header 01774 * Submit up to 15 MIPS Big Endian boot files by 01775 * iso_image_add_mips_boot_file(). 01776 * This will overwrite the first 512 bytes of the submitted 01777 * data. 01778 * 2= DEC Boot Block for MIPS Little Endian 01779 * The first boot file submitted by 01780 * iso_image_add_mips_boot_file() will be activated. 01781 * This will overwrite the first 512 bytes of the submitted 01782 * data. 01783 * @param flag 01784 * bit0 = invalidate any attached system area data. Same as data == NULL 01785 * (This re-activates eventually loaded image System Area data. 01786 * To erase those, submit 32 kB of zeros without flag bit0.) 01787 * bit1 = keep data unaltered 01788 * bit2 = keep options unaltered 01789 * @return 01790 * ISO_SUCCESS or error 01791 * @since 0.6.30 01792 */ 01793 int iso_write_opts_set_system_area(IsoWriteOpts *opts, char data[32768], 01794 int options, int flag); 01795 01796 /** 01797 * Explicitely set the four timestamps of the emerging Primary Volume 01798 * Descriptor. Default with all parameters is 0. 01799 * ECMA-119 defines them as: 01800 * @param opts 01801 * The option set to be manipulated. 01802 * @param vol_creation_time 01803 * When "the information in the volume was created." 01804 * A value of 0 means that the timepoint of write start is to be used. 01805 * @param vol_modification_time 01806 * When "the information in the volume was last modified." 01807 * A value of 0 means that the timepoint of write start is to be used. 01808 * @param vol_expiration_time 01809 * When "the information in the volume may be regarded as obsolete." 01810 * A value of 0 means that the information never shall expire. 01811 * @param vol_effective_time 01812 * When "the information in the volume may be used." 01813 * A value of 0 means that not such retention is intended. 01814 * @param vol_uuid 01815 * If this text is not empty, then it overrides vol_creation_time and 01816 * vol_modification_time by copying the first 16 decimal digits from 01817 * uuid, eventually padding up with decimal '1', and writing a NUL-byte 01818 * as timezone. 01819 * Other than with vol_*_time the resulting string in the ISO image 01820 * is fully predictable and free of timezone pitfalls. 01821 * It should express a reasonable time in form YYYYMMDDhhmmsscc 01822 * E.g.: "2010040711405800" = 7 Apr 2010 11:40:58 (+0 centiseconds) 01823 * @return 01824 * ISO_SUCCESS or error 01825 * 01826 * @since 0.6.30 01827 */ 01828 int iso_write_opts_set_pvd_times(IsoWriteOpts *opts, 01829 time_t vol_creation_time, time_t vol_modification_time, 01830 time_t vol_expiration_time, time_t vol_effective_time, 01831 char *vol_uuid); 01832 01833 01834 /* 01835 * Control production of a second set of volume descriptors (superblock) 01836 * and directory trees, together with a partition table in the MBR where the 01837 * first partition has non-zero start address and the others are zeroed. 01838 * The first partition stretches to the end of the whole ISO image. 01839 * The additional volume descriptor set and trees will allow to mount the 01840 * ISO image at the start of the first partition, while it is still possible 01841 * to mount it via the normal first volume descriptor set and tree at the 01842 * start of the image resp. storage device. 01843 * This makes few sense on optical media. But on USB sticks it creates a 01844 * conventional partition table which makes it mountable on e.g. Linux via 01845 * /dev/sdb and /dev/sdb1 alike. 01846 * IMPORTANT: When submitting memory by iso_write_opts_set_overwrite_buf() 01847 * then its size must be at least 64 KiB + partition offset. 01848 * 01849 * @param opts 01850 * The option set to be manipulated. 01851 * @param block_offset_2k 01852 * The offset of the partition start relative to device start. 01853 * This is counted in 2 kB blocks. The partition table will show the 01854 * according number of 512 byte sectors. 01855 * Default is 0 which causes no special partition table preparations. 01856 * If it is not 0 then it must not be smaller than 16. 01857 * @param secs_512_per_head 01858 * Number of 512 byte sectors per head. 1 to 63. 0=automatic. 01859 * @param heads_per_cyl 01860 * Number of heads per cylinder. 1 to 255. 0=automatic. 01861 * @return 01862 * ISO_SUCCESS or error 01863 * 01864 * @since 0.6.36 01865 */ 01866 int iso_write_opts_set_part_offset(IsoWriteOpts *opts, 01867 uint32_t block_offset_2k, 01868 int secs_512_per_head, int heads_per_cyl); 01869 01870 01871 /** The minimum version of libjte to be used with this version of libisofs 01872 at compile time. The use of libjte is optional and depends on configure 01873 tests. It can be prevented by ./configure option --disable-libjte . 01874 @since 0.6.38 01875 */ 01876 #define iso_libjte_req_major 0 01877 #define iso_libjte_req_minor 1 01878 #define iso_libjte_req_micro 1 01879 01880 /** 01881 * Associate a libjte environment object to the upcomming write run. 01882 * libjte implements Jigdo Template Extraction as of Steve McIntyre and 01883 * Richard Atterer. 01884 * The call will fail if no libjte support was enabled at compile time. 01885 * @param opts 01886 * The option set to be manipulated. 01887 * @param libjte_handle 01888 * Pointer to a struct libjte_env e.g. created by libjte_new(). 01889 * It must stay existent from the start of image generation by 01890 * iso_image_create_burn_source() until the write thread has ended. 01891 * This can be inquired by iso_image_generator_is_running(). 01892 * In order to keep the libisofs API identical with and without 01893 * libjte support the parameter type is (void *). 01894 * @return 01895 * ISO_SUCCESS or error 01896 * 01897 * @since 0.6.38 01898 */ 01899 int iso_write_opts_attach_jte(IsoWriteOpts *opts, void *libjte_handle); 01900 01901 /** 01902 * Remove eventual association to a libjte environment handle. 01903 * The call will fail if no libjte support was enabled at compile time. 01904 * @param opts 01905 * The option set to be manipulated. 01906 * @param libjte_handle 01907 * If not submitted as NULL, this will return the previously set 01908 * libjte handle. 01909 * @return 01910 * ISO_SUCCESS or error 01911 * 01912 * @since 0.6.38 01913 */ 01914 int iso_write_opts_detach_jte(IsoWriteOpts *opts, void **libjte_handle); 01915 01916 01917 /** 01918 * Cause a number of blocks with zero bytes to be written after the payload 01919 * data, but before the eventual checksum data. Unlike libburn tail padding, 01920 * these blocks are counted as part of the image and covered by eventual 01921 * image checksums. 01922 * A reason for such padding can be the wish to prevent the Linux read-ahead 01923 * bug by sacrificial data which still belong to image and Jigdo template. 01924 * Normally such padding would be the job of the burn program which should know 01925 * that it is needed with CD write type TAO if Linux read(2) shall be able 01926 * to read all payload blocks. 01927 * 150 blocks = 300 kB is the traditional sacrifice to the Linux kernel. 01928 * @param opts 01929 * The option set to be manipulated. 01930 * @param num_blocks 01931 * Number of extra 2 kB blocks to be written. 01932 * @return 01933 * ISO_SUCCESS or error 01934 * 01935 * @since 0.6.38 01936 */ 01937 int iso_write_opts_set_tail_blocks(IsoWriteOpts *opts, uint32_t num_blocks); 01938 01939 /** 01940 * Cause an arbitrary data file to be appended to the ISO image and to be 01941 * described by a partition table entry in an MBR at the start of the 01942 * ISO image. 01943 * The partition entry will bear the size of the image file rounded up to 01944 * the next multiple of 2048 bytes. 01945 * @param opts 01946 * The option set to be manipulated. 01947 * @param partition_number 01948 * Depicts the partition table entry which shall describe the 01949 * appended image. Range 1 to 4. 01950 * 1 will cause the whole ISO image to be unclaimable space before 01951 * partition 1. 01952 * @param image_path 01953 * File address in the local file system. 01954 * @param image_type 01955 * The partition type. E.g. FAT12 = 0x01 , FAT16 = 0x06, 01956 * Linux Native Partition = 0x83. See fdisk command L. 01957 * @return 01958 * ISO_SUCCESS or error 01959 * 01960 * @since 0.6.38 01961 */ 01962 int iso_write_opts_set_partition_img(IsoWriteOpts *opts, int partition_number, 01963 uint8_t partition_type, char *image_path, int flag); 01964 01965 01966 /** 01967 * Inquire the start address of the file data blocks after having used 01968 * IsoWriteOpts with iso_image_create_burn_source(). 01969 * @param opts 01970 * The option set that was used when starting image creation 01971 * @param data_start 01972 * Returns the logical block address if it is already valid 01973 * @param flag 01974 * Reserved for future usage, set to 0. 01975 * @return 01976 * 1 indicates valid data_start, <0 indicates invalid data_start 01977 * 01978 * @since 0.6.16 01979 */ 01980 int iso_write_opts_get_data_start(IsoWriteOpts *opts, uint32_t *data_start, 01981 int flag); 01982 01983 /** 01984 * Update the sizes of all files added to image. 01985 * 01986 * This may be called just before iso_image_create_burn_source() to force 01987 * libisofs to check the file sizes again (they're already checked when added 01988 * to IsoImage). It is useful if you have changed some files after adding then 01989 * to the image. 01990 * 01991 * @return 01992 * 1 on success, < 0 on error 01993 * @since 0.6.8 01994 */ 01995 int iso_image_update_sizes(IsoImage *image); 01996 01997 /** 01998 * Create a burn_source and a thread which immediately begins to generate 01999 * the image. That burn_source can be used with libburn as a data source 02000 * for a track. A copy of its public declaration in libburn.h can be found 02001 * further below in this text. 02002 * 02003 * If image generation shall be aborted by the application program, then 02004 * the .cancel() method of the burn_source must be called to end the 02005 * generation thread: burn_src->cancel(burn_src); 02006 * 02007 * @param image 02008 * The image to write. 02009 * @param opts 02010 * The options for image generation. All needed data will be copied, so 02011 * you can free the given struct once this function returns. 02012 * @param burn_src 02013 * Location where the pointer to the burn_source will be stored 02014 * @return 02015 * 1 on success, < 0 on error 02016 * 02017 * @since 0.6.2 02018 */ 02019 int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts, 02020 struct burn_source **burn_src); 02021 02022 /** 02023 * Inquire whether the image generator thread is still at work. As soon as the 02024 * reply is 0, the caller of iso_image_create_burn_source() may assume that 02025 * the image generation has ended. 02026 * Nevertheless there may still be readily formatted output data pending in 02027 * the burn_source or its consumers. So the final delivery of the image has 02028 * also to be checked at the data consumer side,e.g. by burn_drive_get_status() 02029 * in case of libburn as consumer. 02030 * @param image 02031 * The image to inquire. 02032 * @return 02033 * 1 generating of image stream is still in progress 02034 * 0 generating of image stream has ended meanwhile 02035 * 02036 * @since 0.6.38 02037 */ 02038 int iso_image_generator_is_running(IsoImage *image); 02039 02040 /** 02041 * Creates an IsoReadOpts for reading an existent image. You should set the 02042 * options desired with the correspondent setters. Note that you may want to 02043 * set the start block value. 02044 * 02045 * Options by default are determined by the selected profile. 02046 * 02047 * @param opts 02048 * Pointer to the location where the newly created IsoReadOpts will be 02049 * stored. You should free it with iso_read_opts_free() when no more 02050 * needed. 02051 * @param profile 02052 * Default profile for image reading. For now the following values are 02053 * defined: 02054 * ---> 0 [STANDARD] 02055 * Suitable for most situations. Most extension are read. When both 02056 * Joliet and RR extension are present, RR is used. 02057 * AAIP for ACL and xattr is not enabled by default. 02058 * @return 02059 * 1 success, < 0 error 02060 * 02061 * @since 0.6.2 02062 */ 02063 int iso_read_opts_new(IsoReadOpts **opts, int profile); 02064 02065 /** 02066 * Free an IsoReadOpts previously allocated with iso_read_opts_new(). 02067 * 02068 * @since 0.6.2 02069 */ 02070 void iso_read_opts_free(IsoReadOpts *opts); 02071 02072 /** 02073 * Set the block where the image begins. It is usually 0, but may be different 02074 * on a multisession disc. 02075 * 02076 * @since 0.6.2 02077 */ 02078 int iso_read_opts_set_start_block(IsoReadOpts *opts, uint32_t block); 02079 02080 /** 02081 * Do not read Rock Ridge extensions. 02082 * In most cases you don't want to use this. It could be useful if RR info 02083 * is damaged, or if you want to use the Joliet tree. 02084 * 02085 * @since 0.6.2 02086 */ 02087 int iso_read_opts_set_no_rockridge(IsoReadOpts *opts, int norr); 02088 02089 /** 02090 * Do not read Joliet extensions. 02091 * 02092 * @since 0.6.2 02093 */ 02094 int iso_read_opts_set_no_joliet(IsoReadOpts *opts, int nojoliet); 02095 02096 /** 02097 * Do not read ISO 9660:1999 enhanced tree 02098 * 02099 * @since 0.6.2 02100 */ 02101 int iso_read_opts_set_no_iso1999(IsoReadOpts *opts, int noiso1999); 02102 02103 /** 02104 * Control reading of AAIP informations about ACL and xattr when loading 02105 * existing images. 02106 * For importing ACL and xattr when inserting nodes from external filesystems 02107 * (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea(). 02108 * For eventual writing of this information see iso_write_opts_set_aaip(). 02109 * 02110 * @param opts 02111 * The option set to be manipulated 02112 * @param noaaip 02113 * 1 = Do not read AAIP information 02114 * 0 = Read AAIP information if available 02115 * All other values are reserved. 02116 * @since 0.6.14 02117 */ 02118 int iso_read_opts_set_no_aaip(IsoReadOpts *opts, int noaaip); 02119 02120 /** 02121 * Control reading of an array of MD5 checksums which is eventually stored 02122 * at the end of a session. See also iso_write_opts_set_record_md5(). 02123 * Important: Loading of the MD5 array will only work if AAIP is enabled 02124 * because its position and layout is recorded in xattr "isofs.ca". 02125 * 02126 * @param opts 02127 * The option set to be manipulated 02128 * @param no_md5 02129 * 1 = Do not read MD5 checksum array 02130 * 0 = Read Md% array if available 02131 * All other values are reserved. 02132 * 02133 * @since 0.6.22 02134 */ 02135 int iso_read_opts_set_no_md5(IsoReadOpts *opts, int no_md5); 02136 02137 02138 /** 02139 * Control discarding of eventual inode numbers from existing images. 02140 * Such numbers may come from RRIP 1.12 entries PX. If not discarded they 02141 * get written unchanged when the file object gets written into an ISO image. 02142 * If this inode number is missing with a file in the imported image, 02143 * or if it has been discarded during image reading, then a unique inode number 02144 * will be generated at some time before the file gets written into an ISO 02145 * image. 02146 * Two image nodes which have the same inode number represent two hardlinks 02147 * of the same file object. So discarding the numbers splits hardlinks. 02148 * 02149 * @param opts 02150 * The option set to be manipulated 02151 * @param new_inos 02152 * 1 = Discard imported inode numbers and finally hand out a unique new 02153 * one to each single file before it gets written into an ISO image. 02154 * 0 = Keep eventual inode numbers from PX entries. 02155 * All other values are reserved. 02156 * @since 0.6.20 02157 */ 02158 int iso_read_opts_set_new_inos(IsoReadOpts *opts, int new_inos); 02159 02160 /** 02161 * Whether to prefer Joliet over RR. libisofs usually prefers RR over 02162 * Joliet, as it give us much more info about files. So, if both extensions 02163 * are present, RR is used. You can set this if you prefer Joliet, but 02164 * note that this is not very recommended. This doesn't mean than RR 02165 * extensions are not read: if no Joliet is present, libisofs will read 02166 * RR tree. 02167 * 02168 * @since 0.6.2 02169 */ 02170 int iso_read_opts_set_preferjoliet(IsoReadOpts *opts, int preferjoliet); 02171 02172 /** 02173 * Set default uid for files when RR extensions are not present. 02174 * 02175 * @since 0.6.2 02176 */ 02177 int iso_read_opts_set_default_uid(IsoReadOpts *opts, uid_t uid); 02178 02179 /** 02180 * Set default gid for files when RR extensions are not present. 02181 * 02182 * @since 0.6.2 02183 */ 02184 int iso_read_opts_set_default_gid(IsoReadOpts *opts, gid_t gid); 02185 02186 /** 02187 * Set default permissions for files when RR extensions are not present. 02188 * 02189 * @param opts 02190 * The option set to be manipulated 02191 * @param file_perm 02192 * Permissions for files. 02193 * @param dir_perm 02194 * Permissions for directories. 02195 * 02196 * @since 0.6.2 02197 */ 02198 int iso_read_opts_set_default_permissions(IsoReadOpts *opts, mode_t file_perm, 02199 mode_t dir_perm); 02200 02201 /** 02202 * Set the input charset of the file names on the image. NULL to use locale 02203 * charset. You have to specify a charset if the image filenames are encoded 02204 * in a charset different that the local one. This could happen, for example, 02205 * if the image was created on a system with different charset. 02206 * 02207 * @param opts 02208 * The option set to be manipulated 02209 * @param charset 02210 * The charset to use as input charset. You can obtain the list of 02211 * charsets supported on your system executing "iconv -l" in a shell. 02212 * 02213 * @since 0.6.2 02214 */ 02215 int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset); 02216 02217 /** 02218 * Enable or disable methods to automatically choose an input charset. 02219 * This eventually overrides the name set via iso_read_opts_set_input_charset() 02220 * 02221 * @param opts 02222 * The option set to be manipulated 02223 * @param mode 02224 * Bitfield for control purposes: 02225 * bit0= Allow to use the input character set name which is eventually 02226 * stored in attribute "isofs.cs" of the root directory. 02227 * Applications may attach this xattr by iso_node_set_attrs() to 02228 * the root node, call iso_write_opts_set_output_charset() with the 02229 * same name and enable iso_write_opts_set_aaip() when writing 02230 * an image. 02231 * Submit any other bits with value 0. 02232 * 02233 * @since 0.6.18 02234 * 02235 */ 02236 int iso_read_opts_auto_input_charset(IsoReadOpts *opts, int mode); 02237 02238 /** 02239 * Enable or disable loading of the first 32768 bytes of the session. 02240 * 02241 * @param opts 02242 * The option set to be manipulated 02243 * @param mode 02244 * Bitfield for control purposes: 02245 * bit0= Load System Area data and attach them to the image so that they 02246 * get written by the next session, if not overridden by 02247 * iso_write_opts_set_system_area(). 02248 * Submit any other bits with value 0. 02249 * 02250 * @since 0.6.30 02251 * 02252 */ 02253 int iso_read_opts_load_system_area(IsoReadOpts *opts, int mode); 02254 02255 /** 02256 * Import a previous session or image, for growing or modify. 02257 * 02258 * @param image 02259 * The image context to which old image will be imported. Note that all 02260 * files added to image, and image attributes, will be replaced with the 02261 * contents of the old image. 02262 * TODO #00025 support for merging old image files 02263 * @param src 02264 * Data Source from which old image will be read. A extra reference is 02265 * added, so you still need to iso_data_source_unref() yours. 02266 * @param opts 02267 * Options for image import. All needed data will be copied, so you 02268 * can free the given struct once this function returns. 02269 * @param features 02270 * If not NULL, a new IsoReadImageFeatures will be allocated and filled 02271 * with the features of the old image. It should be freed with 02272 * iso_read_image_features_destroy() when no more needed. You can pass 02273 * NULL if you're not interested on them. 02274 * @return 02275 * 1 on success, < 0 on error 02276 * 02277 * @since 0.6.2 02278 */ 02279 int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts, 02280 IsoReadImageFeatures **features); 02281 02282 /** 02283 * Destroy an IsoReadImageFeatures object obtained with iso_image_import. 02284 * 02285 * @since 0.6.2 02286 */ 02287 void iso_read_image_features_destroy(IsoReadImageFeatures *f); 02288 02289 /** 02290 * Get the size (in 2048 byte block) of the image, as reported in the PVM. 02291 * 02292 * @since 0.6.2 02293 */ 02294 uint32_t iso_read_image_features_get_size(IsoReadImageFeatures *f); 02295 02296 /** 02297 * Whether RockRidge extensions are present in the image imported. 02298 * 02299 * @since 0.6.2 02300 */ 02301 int iso_read_image_features_has_rockridge(IsoReadImageFeatures *f); 02302 02303 /** 02304 * Whether Joliet extensions are present in the image imported. 02305 * 02306 * @since 0.6.2 02307 */ 02308 int iso_read_image_features_has_joliet(IsoReadImageFeatures *f); 02309 02310 /** 02311 * Whether the image is recorded according to ISO 9660:1999, i.e. it has 02312 * a version 2 Enhanced Volume Descriptor. 02313 * 02314 * @since 0.6.2 02315 */ 02316 int iso_read_image_features_has_iso1999(IsoReadImageFeatures *f); 02317 02318 /** 02319 * Whether El-Torito boot record is present present in the image imported. 02320 * 02321 * @since 0.6.2 02322 */ 02323 int iso_read_image_features_has_eltorito(IsoReadImageFeatures *f); 02324 02325 /** 02326 * Increments the reference counting of the given image. 02327 * 02328 * @since 0.6.2 02329 */ 02330 void iso_image_ref(IsoImage *image); 02331 02332 /** 02333 * Decrements the reference couting of the given image. 02334 * If it reaches 0, the image is free, together with its tree nodes (whether 02335 * their refcount reach 0 too, of course). 02336 * 02337 * @since 0.6.2 02338 */ 02339 void iso_image_unref(IsoImage *image); 02340 02341 /** 02342 * Attach user defined data to the image. Use this if your application needs 02343 * to store addition info together with the IsoImage. If the image already 02344 * has data attached, the old data will be freed. 02345 * 02346 * @param image 02347 * The image to which data shall be attached. 02348 * @param data 02349 * Pointer to application defined data that will be attached to the 02350 * image. You can pass NULL to remove any already attached data. 02351 * @param give_up 02352 * Function that will be called when the image does not need the data 02353 * any more. It receives the data pointer as an argumente, and eventually 02354 * causes data to be freed. It can be NULL if you don't need it. 02355 * @return 02356 * 1 on succes, < 0 on error 02357 * 02358 * @since 0.6.2 02359 */ 02360 int iso_image_attach_data(IsoImage *image, void *data, void (*give_up)(void*)); 02361 02362 /** 02363 * The the data previously attached with iso_image_attach_data() 02364 * 02365 * @since 0.6.2 02366 */ 02367 void *iso_image_get_attached_data(IsoImage *image); 02368 02369 /** 02370 * Get the root directory of the image. 02371 * No extra ref is added to it, so you musn't unref it. Use iso_node_ref() 02372 * if you want to get your own reference. 02373 * 02374 * @since 0.6.2 02375 */ 02376 IsoDir *iso_image_get_root(const IsoImage *image); 02377 02378 /** 02379 * Fill in the volset identifier for a image. 02380 * 02381 * @since 0.6.2 02382 */ 02383 void iso_image_set_volset_id(IsoImage *image, const char *volset_id); 02384 02385 /** 02386 * Get the volset identifier. 02387 * The returned string is owned by the image and should not be freed nor 02388 * changed. 02389 * 02390 * @since 0.6.2 02391 */ 02392 const char *iso_image_get_volset_id(const IsoImage *image); 02393 02394 /** 02395 * Fill in the volume identifier for a image. 02396 * 02397 * @since 0.6.2 02398 */ 02399 void iso_image_set_volume_id(IsoImage *image, const char *volume_id); 02400 02401 /** 02402 * Get the volume identifier. 02403 * The returned string is owned by the image and should not be freed nor 02404 * changed. 02405 * 02406 * @since 0.6.2 02407 */ 02408 const char *iso_image_get_volume_id(const IsoImage *image); 02409 02410 /** 02411 * Fill in the publisher for a image. 02412 * 02413 * @since 0.6.2 02414 */ 02415 void iso_image_set_publisher_id(IsoImage *image, const char *publisher_id); 02416 02417 /** 02418 * Get the publisher of a image. 02419 * The returned string is owned by the image and should not be freed nor 02420 * changed. 02421 * 02422 * @since 0.6.2 02423 */ 02424 const char *iso_image_get_publisher_id(const IsoImage *image); 02425 02426 /** 02427 * Fill in the data preparer for a image. 02428 * 02429 * @since 0.6.2 02430 */ 02431 void iso_image_set_data_preparer_id(IsoImage *image, 02432 const char *data_preparer_id); 02433 02434 /** 02435 * Get the data preparer of a image. 02436 * The returned string is owned by the image and should not be freed nor 02437 * changed. 02438 * 02439 * @since 0.6.2 02440 */ 02441 const char *iso_image_get_data_preparer_id(const IsoImage *image); 02442 02443 /** 02444 * Fill in the system id for a image. Up to 32 characters. 02445 * 02446 * @since 0.6.2 02447 */ 02448 void iso_image_set_system_id(IsoImage *image, const char *system_id); 02449 02450 /** 02451 * Get the system id of a image. 02452 * The returned string is owned by the image and should not be freed nor 02453 * changed. 02454 * 02455 * @since 0.6.2 02456 */ 02457 const char *iso_image_get_system_id(const IsoImage *image); 02458 02459 /** 02460 * Fill in the application id for a image. Up to 128 chars. 02461 * 02462 * @since 0.6.2 02463 */ 02464 void iso_image_set_application_id(IsoImage *image, const char *application_id); 02465 02466 /** 02467 * Get the application id of a image. 02468 * The returned string is owned by the image and should not be freed nor 02469 * changed. 02470 * 02471 * @since 0.6.2 02472 */ 02473 const char *iso_image_get_application_id(const IsoImage *image); 02474 02475 /** 02476 * Fill copyright information for the image. Usually this refers 02477 * to a file on disc. Up to 37 characters. 02478 * 02479 * @since 0.6.2 02480 */ 02481 void iso_image_set_copyright_file_id(IsoImage *image, 02482 const char *copyright_file_id); 02483 02484 /** 02485 * Get the copyright information of a image. 02486 * The returned string is owned by the image and should not be freed nor 02487 * changed. 02488 * 02489 * @since 0.6.2 02490 */ 02491 const char *iso_image_get_copyright_file_id(const IsoImage *image); 02492 02493 /** 02494 * Fill abstract information for the image. Usually this refers 02495 * to a file on disc. Up to 37 characters. 02496 * 02497 * @since 0.6.2 02498 */ 02499 void iso_image_set_abstract_file_id(IsoImage *image, 02500 const char *abstract_file_id); 02501 02502 /** 02503 * Get the abstract information of a image. 02504 * The returned string is owned by the image and should not be freed nor 02505 * changed. 02506 * 02507 * @since 0.6.2 02508 */ 02509 const char *iso_image_get_abstract_file_id(const IsoImage *image); 02510 02511 /** 02512 * Fill biblio information for the image. Usually this refers 02513 * to a file on disc. Up to 37 characters. 02514 * 02515 * @since 0.6.2 02516 */ 02517 void iso_image_set_biblio_file_id(IsoImage *image, const char *biblio_file_id); 02518 02519 /** 02520 * Get the biblio information of a image. 02521 * The returned string is owned by the image and should not be freed nor 02522 * changed. 02523 * 02524 * @since 0.6.2 02525 */ 02526 const char *iso_image_get_biblio_file_id(const IsoImage *image); 02527 02528 /** 02529 * Create a new set of El-Torito bootable images by adding a boot catalog 02530 * and the default boot image. 02531 * Further boot images may then be added by iso_image_add_boot_image(). 02532 * 02533 * @param image 02534 * The image to make bootable. If it was already bootable this function 02535 * returns an error and the image remains unmodified. 02536 * @param image_path 02537 * The absolute path of a IsoFile to be used as default boot image. 02538 * @param type 02539 * The boot media type. This can be one of 3 types: 02540 * - Floppy emulation: Boot image file must be exactly 02541 * 1200 kB, 1440 kB or 2880 kB. 02542 * - Hard disc emulation: The image must begin with a master 02543 * boot record with a single image. 02544 * - No emulation. You should specify load segment and load size 02545 * of image. 02546 * @param catalog_path 02547 * The absolute path in the image tree where the catalog will be stored. 02548 * The directory component of this path must be a directory existent on 02549 * the image tree, and the filename component must be unique among all 02550 * children of that directory on image. Otherwise a correspodent error 02551 * code will be returned. This function will add an IsoBoot node that acts 02552 * as a placeholder for the real catalog, that will be generated at image 02553 * creation time. 02554 * @param boot 02555 * Location where a pointer to the added boot image will be stored. That 02556 * object is owned by the IsoImage and should not be freed by the user, 02557 * nor dereferenced once the last reference to the IsoImage was disposed 02558 * via iso_image_unref(). A NULL value is allowed if you don't need a 02559 * reference to the boot image. 02560 * @return 02561 * 1 on success, < 0 on error 02562 * 02563 * @since 0.6.2 02564 */ 02565 int iso_image_set_boot_image(IsoImage *image, const char *image_path, 02566 enum eltorito_boot_media_type type, 02567 const char *catalog_path, 02568 ElToritoBootImage **boot); 02569 02570 /** 02571 * Add a further boot image to the set of El-Torito bootable images. 02572 * This set has already to be created by iso_image_set_boot_image(). 02573 * Up to 31 further boot images may be added. 02574 * 02575 * @param image 02576 * The image to which the boot image shall be added. 02577 * returns an error and the image remains unmodified. 02578 * @param image_path 02579 * The absolute path of a IsoFile to be used as default boot image. 02580 * @param type 02581 * The boot media type. See iso_image_set_boot_image 02582 * @param flag 02583 * Bitfield for control purposes. Unused yet. Submit 0. 02584 * @param boot 02585 * Location where a pointer to the added boot image will be stored. 02586 * See iso_image_set_boot_image 02587 * @return 02588 * 1 on success, < 0 on error 02589 * ISO_BOOT_NO_CATALOG means iso_image_set_boot_image() 02590 * was not called first. 02591 * 02592 * @since 0.6.32 02593 */ 02594 int iso_image_add_boot_image(IsoImage *image, const char *image_path, 02595 enum eltorito_boot_media_type type, int flag, 02596 ElToritoBootImage **boot); 02597 02598 /** 02599 * Get the El-Torito boot catalog and the default boot image of an ISO image. 02600 * 02601 * This can be useful, for example, to check if a volume read from a previous 02602 * session or an existing image is bootable. It can also be useful to get 02603 * the image and catalog tree nodes. An application would want those, for 02604 * example, to prevent the user removing it. 02605 * 02606 * Both nodes are owned by libisofs and should not be freed. You can get your 02607 * own ref with iso_node_ref(). You can also check if the node is already 02608 * on the tree by getting its parent (note that when reading El-Torito info 02609 * from a previous image, the nodes might not be on the tree even if you haven't 02610 * removed them). Remember that you'll need to get a new ref 02611 * (with iso_node_ref()) before inserting them again to the tree, and probably 02612 * you will also need to set the name or permissions. 02613 * 02614 * @param image 02615 * The image from which to get the boot image. 02616 * @param boot 02617 * If not NULL, it will be filled with a pointer to the boot image, if 02618 * any. That object is owned by the IsoImage and should not be freed by 02619 * the user, nor dereferenced once the last reference to the IsoImage was 02620 * disposed via iso_image_unref(). 02621 * @param imgnode 02622 * When not NULL, it will be filled with the image tree node. No extra ref 02623 * is added, you can use iso_node_ref() to get one if you need it. 02624 * @param catnode 02625 * When not NULL, it will be filled with the catnode tree node. No extra 02626 * ref is added, you can use iso_node_ref() to get one if you need it. 02627 * @return 02628 * 1 on success, 0 is the image is not bootable (i.e., it has no El-Torito 02629 * image), < 0 error. 02630 * 02631 * @since 0.6.2 02632 */ 02633 int iso_image_get_boot_image(IsoImage *image, ElToritoBootImage **boot, 02634 IsoFile **imgnode, IsoBoot **catnode); 02635 02636 /** 02637 * Get all El-Torito boot images of an ISO image. 02638 * 02639 * The first of these boot images is the same as returned by 02640 * iso_image_get_boot_image(). The others are alternative boot images. 02641 * 02642 * @param image 02643 * The image from which to get the boot images. 02644 * @param num_boots 02645 * The number of available array elements in boots and bootnodes. 02646 * @param boots 02647 * Returns NULL or an allocated array of pointers to boot images. 02648 * Apply system call free(boots) to dispose it. 02649 * @param bootnodes 02650 * Returns NULL or an allocated array of pointers to the IsoFile nodes 02651 * which bear the content of the boot images in boots. 02652 * @param flag 02653 * Bitfield for control purposes. Unused yet. Submit 0. 02654 * @return 02655 * 1 on success, 0 no El-Torito catalog and boot image attached, 02656 * < 0 error. 02657 * 02658 * @since 0.6.32 02659 */ 02660 int iso_image_get_all_boot_imgs(IsoImage *image, int *num_boots, 02661 ElToritoBootImage ***boots, IsoFile ***bootnodes, int flag); 02662 02663 02664 /** 02665 * Removes all El-Torito boot images from the ISO image. 02666 * 02667 * The IsoBoot node that acts as placeholder for the catalog is also removed 02668 * for the image tree, if there. 02669 * If the image is not bootable (don't have el-torito boot image) this function 02670 * just returns. 02671 * 02672 * @since 0.6.2 02673 */ 02674 void iso_image_remove_boot_image(IsoImage *image); 02675 02676 /** 02677 * Sets the sort weight of the boot catalog that is attached to an IsoImage. 02678 * 02679 * For the meaning of sort weights see iso_node_set_sort_weight(). 02680 * That function cannot be applied to the emerging boot catalog because 02681 * it is not represented by an IsoFile. 02682 * 02683 * @param image 02684 * The image to manipulate. 02685 * @param sort_weight 02686 * The larger this value, the lower will be the block address of the 02687 * boot catalog record. 02688 * @return 02689 * 0= no boot catalog attached , 1= ok , <0 = error 02690 * 02691 * @since 0.6.32 02692 */ 02693 int iso_image_set_boot_catalog_weight(IsoImage *image, int sort_weight); 02694 02695 /** 02696 * Hides the boot catalog file from directory trees. 02697 * 02698 * For the meaning of hiding files see iso_node_set_hidden(). 02699 * 02700 * 02701 * @param image 02702 * The image to manipulate. 02703 * @param hide_attrs 02704 * Or-combination of values from enum IsoHideNodeFlag to set the trees 02705 * in which the record. 02706 * @return 02707 * 0= no boot catalog attached , 1= ok , <0 = error 02708 * 02709 * @since 0.6.34 02710 */ 02711 int iso_image_set_boot_catalog_hidden(IsoImage *image, int hide_attrs); 02712 02713 02714 /** 02715 * Get the boot media type as of parameter "type" of iso_image_set_boot_image() 02716 * resp. iso_image_add_boot_image(). 02717 * 02718 * @param bootimg 02719 * The image to inquire 02720 * @param media_type 02721 * Returns the media type 02722 * @return 02723 * 1 = ok , < 0 = error 02724 * 02725 * @since 0.6.32 02726 */ 02727 int el_torito_get_boot_media_type(ElToritoBootImage *bootimg, 02728 enum eltorito_boot_media_type *media_type); 02729 02730 /** 02731 * Sets the platform ID of the boot image. 02732 * 02733 * The Platform ID gets written into the boot catalog at byte 1 of the 02734 * Validation Entry, or at byte 1 of a Section Header Entry. 02735 * If Platform ID and ID String of two consequtive bootimages are the same 02736 * 02737 * @param bootimg 02738 * The image to manipulate. 02739 * @param id 02740 * A Platform ID as of 02741 * El Torito 1.0 : 0x00= 80x86, 0x01= PowerPC, 0x02= Mac 02742 * Others : 0xef= EFI 02743 * @return 02744 * 1 ok , <=0 error 02745 * 02746 * @since 0.6.32 02747 */ 02748 int el_torito_set_boot_platform_id(ElToritoBootImage *bootimg, uint8_t id); 02749 02750 /** 02751 * Get the platform ID value. See el_torito_set_boot_platform_id(). 02752 * 02753 * @param bootimg 02754 * The image to inquire 02755 * @return 02756 * 0 - 255 : The platform ID 02757 * < 0 : error 02758 * 02759 * @since 0.6.32 02760 */ 02761 int el_torito_get_boot_platform_id(ElToritoBootImage *bootimg); 02762 02763 /** 02764 * Sets the load segment for the initial boot image. This is only for 02765 * no emulation boot images, and is a NOP for other image types. 02766 * 02767 * @since 0.6.2 02768 */ 02769 void el_torito_set_load_seg(ElToritoBootImage *bootimg, short segment); 02770 02771 /** 02772 * Get the load segment value. See el_torito_set_load_seg(). 02773 * 02774 * @param bootimg 02775 * The image to inquire 02776 * @return 02777 * 0 - 65535 : The load segment value 02778 * < 0 : error 02779 * 02780 * @since 0.6.32 02781 */ 02782 int el_torito_get_load_seg(ElToritoBootImage *bootimg); 02783 02784 /** 02785 * Sets the number of sectors (512b) to be load at load segment during 02786 * the initial boot procedure. This is only for 02787 * no emulation boot images, and is a NOP for other image types. 02788 * 02789 * @since 0.6.2 02790 */ 02791 void el_torito_set_load_size(ElToritoBootImage *bootimg, short sectors); 02792 02793 /** 02794 * Get the load size. See el_torito_set_load_size(). 02795 * 02796 * @param bootimg 02797 * The image to inquire 02798 * @return 02799 * 0 - 65535 : The load size value 02800 * < 0 : error 02801 * 02802 * @since 0.6.32 02803 */ 02804 int el_torito_get_load_size(ElToritoBootImage *bootimg); 02805 02806 /** 02807 * Marks the specified boot image as not bootable 02808 * 02809 * @since 0.6.2 02810 */ 02811 void el_torito_set_no_bootable(ElToritoBootImage *bootimg); 02812 02813 /** 02814 * Get the bootability flag. See el_torito_set_no_bootable(). 02815 * 02816 * @param bootimg 02817 * The image to inquire 02818 * @return 02819 * 0 = not bootable, 1 = bootable , <0 = error 02820 * 02821 * @since 0.6.32 02822 */ 02823 int el_torito_get_bootable(ElToritoBootImage *bootimg); 02824 02825 /** 02826 * Set the id_string of the Validation Entry resp. Sector Header Entry which 02827 * will govern the boot image Section Entry in the El Torito Catalog. 02828 * 02829 * @param bootimg 02830 * The image to manipulate. 02831 * @param id_string 02832 * The first boot image puts 24 bytes of ID string into the Validation 02833 * Entry, where they shall "identify the manufacturer/developer of 02834 * the CD-ROM". 02835 * Further boot images put 28 bytes into their Section Header. 02836 * El Torito 1.0 states that "If the BIOS understands the ID string, it 02837 * may choose to boot the * system using one of these entries in place 02838 * of the INITIAL/DEFAULT entry." (The INITIAL/DEFAULT entry points to the 02839 * first boot image.) 02840 * @return 02841 * 1 = ok , <0 = error 02842 * 02843 * @since 0.6.32 02844 */ 02845 int el_torito_set_id_string(ElToritoBootImage *bootimg, uint8_t id_string[28]); 02846 02847 /** 02848 * Get the id_string as of el_torito_set_id_string(). 02849 * 02850 * @param bootimg 02851 * The image to inquire 02852 * @param id_string 02853 * Returns 28 bytes of id string 02854 * @return 02855 * 1 = ok , <0 = error 02856 * 02857 * @since 0.6.32 02858 */ 02859 int el_torito_get_id_string(ElToritoBootImage *bootimg, uint8_t id_string[28]); 02860 02861 /** 02862 * Set the Selection Criteria of a boot image. 02863 * 02864 * @param bootimg 02865 * The image to manipulate. 02866 * @param crit 02867 * The first boot image has no selection criteria. They will be ignored. 02868 * Further boot images put 1 byte of Selection Criteria Type and 19 02869 * bytes of data into their Section Entry. 02870 * El Torito 1.0 states that "The format of the selection criteria is 02871 * a function of the BIOS vendor. In the case of a foreign language 02872 * BIOS three bytes would be used to identify the language". 02873 * Type byte == 0 means "no criteria", 02874 * type byte == 1 means "Language and Version Information (IBM)". 02875 * @return 02876 * 1 = ok , <0 = error 02877 * 02878 * @since 0.6.32 02879 */ 02880 int el_torito_set_selection_crit(ElToritoBootImage *bootimg, uint8_t crit[20]); 02881 02882 /** 02883 * Get the Selection Criteria bytes as of el_torito_set_selection_crit(). 02884 * 02885 * @param bootimg 02886 * The image to inquire 02887 * @param id_string 02888 * Returns 20 bytes of type and data 02889 * @return 02890 * 1 = ok , <0 = error 02891 * 02892 * @since 0.6.32 02893 */ 02894 int el_torito_get_selection_crit(ElToritoBootImage *bootimg, uint8_t crit[20]); 02895 02896 02897 /** 02898 * Makes a guess whether the boot image was patched by a boot information 02899 * table. It is advisable to patch such boot images if their content gets 02900 * copied to a new location. See el_torito_set_isolinux_options(). 02901 * Note: The reply can be positive only if the boot image was imported 02902 * from an existing ISO image. 02903 * 02904 * @param bootimg 02905 * The image to inquire 02906 * @param flag 02907 * Reserved for future usage, set to 0. 02908 * @return 02909 * 1 = seems to contain oot info table , 0 = quite surely not 02910 * @since 0.6.32 02911 */ 02912 int el_torito_seems_boot_info_table(ElToritoBootImage *bootimg, int flag); 02913 02914 /** 02915 * Specifies options for ISOLINUX or GRUB boot images. This should only be used 02916 * if the type of boot image is known. 02917 * 02918 * @param options 02919 * bitmask style flag. The following values are defined: 02920 * 02921 * bit 0 -> 1 to patch the boot info table of the boot image. 02922 * 1 does the same as mkisofs option -boot-info-table. 02923 * Needed for ISOLINUX or GRUB boot images with platform ID 0. 02924 * The table is located at byte 8 of the boot image file. 02925 * Its size is 56 bytes. 02926 * The original boot image file on disk will not be modified. 02927 * 02928 * One may use el_torito_seems_boot_info_table() for a 02929 * qualified guess whether a boot info table is present in 02930 * the boot image. If the result is 1 then it should get bit0 02931 * set if its content gets copied to a new LBA. 02932 * 02933 * bit 1 -> 1 to generate a ISOLINUX isohybrid image with MBR. 02934 * ---------------------------------------------------------- 02935 * @deprecated since 31 Mar 2010: 02936 * The author of syslinux, H. Peter Anvin requested that this 02937 * feature shall not be used any more. He intends to cease 02938 * support for the MBR template that is included in libisofs. 02939 * ---------------------------------------------------------- 02940 * A hybrid image is a boot image that boots from either 02941 * CD/DVD media or from disk-like media, e.g. USB stick. 02942 * For that you need isolinux.bin from SYSLINUX 3.72 or later. 02943 * IMPORTANT: The application has to take care that the image 02944 * on media gets padded up to the next full MB. 02945 * @param bootimg 02946 * The image to set options on 02947 * @param flag 02948 * Reserved for future usage, set to 0. 02949 * @return 02950 * 1 success, < 0 on error 02951 * @since 0.6.12 02952 */ 02953 int el_torito_set_isolinux_options(ElToritoBootImage *bootimg, 02954 int options, int flag); 02955 02956 /** 02957 * Get the options as of el_torito_set_isolinux_options(). 02958 * 02959 * @param bootimg 02960 * The image to inquire 02961 * @param flag 02962 * Reserved for future usage, set to 0. 02963 * @return 02964 * >= 0 returned option bits , <0 = error 02965 * 02966 * @since 0.6.32 02967 */ 02968 int el_torito_get_isolinux_options(ElToritoBootImage *bootimg, int flag); 02969 02970 /** Deprecated: 02971 * Specifies that this image needs to be patched. This involves the writing 02972 * of a 16 bytes boot information table at offset 8 of the boot image file. 02973 * The original boot image file won't be modified. 02974 * This is needed for isolinux boot images. 02975 * 02976 * @since 0.6.2 02977 * @deprecated Use el_torito_set_isolinux_options() instead 02978 */ 02979 void el_torito_patch_isolinux_image(ElToritoBootImage *bootimg); 02980 02981 /** 02982 * Obtain a copy of the eventually loaded first 32768 bytes of the imported 02983 * session, the System Area. 02984 * It will be written to the start of the next session unless it gets 02985 * overwritten by iso_write_opts_set_system_area(). 02986 * 02987 * @param img 02988 * The image to be inquired. 02989 * @param data 02990 * A byte array of at least 32768 bytesi to take the loaded bytes. 02991 * @param options 02992 * The option bits which will be applied if not overridden by 02993 * iso_write_opts_set_system_area(). See there. 02994 * @param flag 02995 * Bitfield for control purposes, unused yet, submit 0 02996 * @return 02997 * 1 on success, 0 if no System Area was loaded, < 0 error. 02998 * @since 0.6.30 02999 */ 03000 int iso_image_get_system_area(IsoImage *img, char data[32768], 03001 int *options, int flag); 03002 03003 /** 03004 * Add a MIPS boot file path to the image. 03005 * Up to 15 such files can be written into a MIPS Big Endian Volume Header 03006 * if this is enabled by value 1 in iso_write_opts_set_system_area() option 03007 * bits 2 to 7. 03008 * A single file can be written into a DEC Boot Block if this is enabled by 03009 * value 2 in iso_write_opts_set_system_area() option bits 2 to 7. So only 03010 * the first added file gets into effect with this system area type. 03011 * The data files which shall serve as MIPS boot files have to be brought into 03012 * the image by the normal means. 03013 * @param img 03014 * The image to be manipulated. 03015 * @param path 03016 * Absolute path of the boot file in the ISO 9660 Rock Ridge tree. 03017 * @param flag 03018 * Bitfield for control purposes, unused yet, submit 0 03019 * @return 03020 * 1 on success, < 0 error 03021 * @since 0.6.38 03022 */ 03023 int iso_image_add_mips_boot_file(IsoImage *image, char *path, int flag); 03024 03025 /** 03026 * Obtain the number of added MIPS Big Endian boot files and pointers to 03027 * their paths in the ISO 9660 Rock Ridge tree. 03028 * @param img 03029 * The image to be inquired. 03030 * @param paths 03031 * An array of pointers to be set to the registered boot file paths. 03032 * This are just pointers to data inside IsoImage. Do not free() them. 03033 * Eventually make own copies of the data before manipulating the image. 03034 * @param flag 03035 * Bitfield for control purposes, unused yet, submit 0 03036 * @return 03037 * >= 0 is the number of valid path pointers , <0 means error 03038 * @since 0.6.38 03039 */ 03040 int iso_image_get_mips_boot_files(IsoImage *image, char *paths[15], int flag); 03041 03042 /** 03043 * Clear the list of MIPS Big Endian boot file paths. 03044 * @param img 03045 * The image to be manipulated. 03046 * @param flag 03047 * Bitfield for control purposes, unused yet, submit 0 03048 * @return 03049 * 1 is success , <0 means error 03050 * @since 0.6.38 03051 */ 03052 int iso_image_give_up_mips_boot(IsoImage *image, int flag); 03053 03054 03055 /** 03056 * Increments the reference counting of the given node. 03057 * 03058 * @since 0.6.2 03059 */ 03060 void iso_node_ref(IsoNode *node); 03061 03062 /** 03063 * Decrements the reference couting of the given node. 03064 * If it reach 0, the node is free, and, if the node is a directory, 03065 * its children will be unref() too. 03066 * 03067 * @since 0.6.2 03068 */ 03069 void iso_node_unref(IsoNode *node); 03070 03071 /** 03072 * Get the type of an IsoNode. 03073 * 03074 * @since 0.6.2 03075 */ 03076 enum IsoNodeType iso_node_get_type(IsoNode *node); 03077 03078 /** 03079 * Function to handle particular extended information. The function 03080 * pointer acts as an identifier for the type of the information. Structs 03081 * with same information type must use the same function. 03082 * 03083 * @param data 03084 * Attached data 03085 * @param flag 03086 * What to do with the data. At this time the following values are 03087 * defined: 03088 * -> 1 the data must be freed 03089 * @return 03090 * 1 in any case. 03091 * 03092 * @since 0.6.4 03093 */ 03094 typedef int (*iso_node_xinfo_func)(void *data, int flag); 03095 03096 /** 03097 * Add extended information to the given node. Extended info allows 03098 * applications (and libisofs itself) to add more information to an IsoNode. 03099 * You can use this facilities to associate temporary information with a given 03100 * node. This information is not written into the ISO 9660 image on media 03101 * and thus does not persist longer than the node memory object. 03102 * 03103 * Each node keeps a list of added extended info, meaning you can add several 03104 * extended info data to each node. Each extended info you add is identified 03105 * by the proc parameter, a pointer to a function that knows how to manage 03106 * the external info data. Thus, in order to add several types of extended 03107 * info, you need to define a "proc" function for each type. 03108 * 03109 * @param node 03110 * The node where to add the extended info 03111 * @param proc 03112 * A function pointer used to identify the type of the data, and that 03113 * knows how to manage it 03114 * @param data 03115 * Extended info to add. 03116 * @return 03117 * 1 if success, 0 if the given node already has extended info of the 03118 * type defined by the "proc" function, < 0 on error 03119 * 03120 * @since 0.6.4 03121 */ 03122 int iso_node_add_xinfo(IsoNode *node, iso_node_xinfo_func proc, void *data); 03123 03124 /** 03125 * Remove the given extended info (defined by the proc function) from the 03126 * given node. 03127 * 03128 * @return 03129 * 1 on success, 0 if node does not have extended info of the requested 03130 * type, < 0 on error 03131 * 03132 * @since 0.6.4 03133 */ 03134 int iso_node_remove_xinfo(IsoNode *node, iso_node_xinfo_func proc); 03135 03136 /** 03137 * Get the given extended info (defined by the proc function) from the 03138 * given node. 03139 * 03140 * @param node 03141 * The node to inquire 03142 * @param proc 03143 * The function pointer which serves as key 03144 * @param data 03145 * Will be filled with the extended info corresponding to the given proc 03146 * function 03147 * @return 03148 * 1 on success, 0 if node does not have extended info of the requested 03149 * type, < 0 on error 03150 * 03151 * @since 0.6.4 03152 */ 03153 int iso_node_get_xinfo(IsoNode *node, iso_node_xinfo_func proc, void **data); 03154 03155 /** 03156 * Set the name of a node. Note that if the node is already added to a dir 03157 * this can fail if dir already contains a node with the new name. 03158 * 03159 * @param node 03160 * The node whose name you want to change. Note that you can't change 03161 * the name of the root. 03162 * @param name 03163 * The name for the node. If you supply an empty string or a 03164 * name greater than 255 characters this returns with failure, and 03165 * node name is not modified. 03166 * @return 03167 * 1 on success, < 0 on error 03168 * 03169 * @since 0.6.2 03170 */ 03171 int iso_node_set_name(IsoNode *node, const char *name); 03172 03173 /** 03174 * Get the name of a node. 03175 * The returned string belongs to the node and should not be modified nor 03176 * freed. Use strdup if you really need your own copy. 03177 * 03178 * @since 0.6.2 03179 */ 03180 const char *iso_node_get_name(const IsoNode *node); 03181 03182 /** 03183 * Set the permissions for the node. This attribute is only useful when 03184 * Rock Ridge extensions are enabled. 03185 * 03186 * @param node 03187 * The node to change 03188 * @param mode 03189 * bitmask with the permissions of the node, as specified in 'man 2 stat'. 03190 * The file type bitfields will be ignored, only file permissions will be 03191 * modified. 03192 * 03193 * @since 0.6.2 03194 */ 03195 void iso_node_set_permissions(IsoNode *node, mode_t mode); 03196 03197 /** 03198 * Get the permissions for the node 03199 * 03200 * @since 0.6.2 03201 */ 03202 mode_t iso_node_get_permissions(const IsoNode *node); 03203 03204 /** 03205 * Get the mode of the node, both permissions and file type, as specified in 03206 * 'man 2 stat'. 03207 * 03208 * @since 0.6.2 03209 */ 03210 mode_t iso_node_get_mode(const IsoNode *node); 03211 03212 /** 03213 * Set the user id for the node. This attribute is only useful when 03214 * Rock Ridge extensions are enabled. 03215 * 03216 * @since 0.6.2 03217 */ 03218 void iso_node_set_uid(IsoNode *node, uid_t uid); 03219 03220 /** 03221 * Get the user id of the node. 03222 * 03223 * @since 0.6.2 03224 */ 03225 uid_t iso_node_get_uid(const IsoNode *node); 03226 03227 /** 03228 * Set the group id for the node. This attribute is only useful when 03229 * Rock Ridge extensions are enabled. 03230 * 03231 * @since 0.6.2 03232 */ 03233 void iso_node_set_gid(IsoNode *node, gid_t gid); 03234 03235 /** 03236 * Get the group id of the node. 03237 * 03238 * @since 0.6.2 03239 */ 03240 gid_t iso_node_get_gid(const IsoNode *node); 03241 03242 /** 03243 * Set the time of last modification of the file 03244 * 03245 * @since 0.6.2 03246 */ 03247 void iso_node_set_mtime(IsoNode *node, time_t time); 03248 03249 /** 03250 * Get the time of last modification of the file 03251 * 03252 * @since 0.6.2 03253 */ 03254 time_t iso_node_get_mtime(const IsoNode *node); 03255 03256 /** 03257 * Set the time of last access to the file 03258 * 03259 * @since 0.6.2 03260 */ 03261 void iso_node_set_atime(IsoNode *node, time_t time); 03262 03263 /** 03264 * Get the time of last access to the file 03265 * 03266 * @since 0.6.2 03267 */ 03268 time_t iso_node_get_atime(const IsoNode *node); 03269 03270 /** 03271 * Set the time of last status change of the file 03272 * 03273 * @since 0.6.2 03274 */ 03275 void iso_node_set_ctime(IsoNode *node, time_t time); 03276 03277 /** 03278 * Get the time of last status change of the file 03279 * 03280 * @since 0.6.2 03281 */ 03282 time_t iso_node_get_ctime(const IsoNode *node); 03283 03284 /** 03285 * Set whether the node will be hidden in the directory trees of RR/ISO 9660, 03286 * or of Joliet (if enabled at all), or of ISO-9660:1999 (if enabled at all). 03287 * 03288 * A hidden file does not show up by name in the affected directory tree. 03289 * For example, if a file is hidden only in Joliet, it will normally 03290 * not be visible on Windows systems, while being shown on GNU/Linux. 03291 * 03292 * If a file is not shown in any of the enabled trees, then its content will 03293 * not be written to the image, unless LIBISO_HIDE_BUT_WRITE is given (which 03294 * is available only since release 0.6.34). 03295 * 03296 * @param node 03297 * The node that is to be hidden. 03298 * @param hide_attrs 03299 * Or-combination of values from enum IsoHideNodeFlag to set the trees 03300 * in which the node's name shall be hidden. 03301 * 03302 * @since 0.6.2 03303 */ 03304 void iso_node_set_hidden(IsoNode *node, int hide_attrs); 03305 03306 /** 03307 * Get the hide_attrs as eventually set by iso_node_set_hidden(). 03308 * 03309 * @param node 03310 * The node to inquire. 03311 * @return 03312 * Or-combination of values from enum IsoHideNodeFlag which are 03313 * currently set for the node. 03314 * 03315 * @since 0.6.34 03316 */ 03317 int iso_node_get_hidden(IsoNode *node); 03318 03319 /** 03320 * Compare two nodes whether they are based on the same input and 03321 * can be considered as hardlinks to the same file objects. 03322 * 03323 * @param n1 03324 * The first node to compare. 03325 * @param n2 03326 * The second node to compare. 03327 * @return 03328 * -1 if s1 is smaller s2 , 0 if s1 matches s2 , 1 if s1 is larger s2 03329 * @param flag 03330 * Bitfield for control purposes, unused yet, submit 0 03331 * @since 0.6.20 03332 */ 03333 int iso_node_cmp_ino(IsoNode *n1, IsoNode *n2, int flag); 03334 03335 /** 03336 * Add a new node to a dir. Note that this function don't add a new ref to 03337 * the node, so you don't need to free it, it will be automatically freed 03338 * when the dir is deleted. Of course, if you want to keep using the node 03339 * after the dir life, you need to iso_node_ref() it. 03340 * 03341 * @param dir 03342 * the dir where to add the node 03343 * @param child 03344 * the node to add. You must ensure that the node hasn't previously added 03345 * to other dir, and that the node name is unique inside the child. 03346 * Otherwise this function will return a failure, and the child won't be 03347 * inserted. 03348 * @param replace 03349 * if the dir already contains a node with the same name, whether to 03350 * replace or not the old node with this. 03351 * @return 03352 * number of nodes in dir if succes, < 0 otherwise 03353 * Possible errors: 03354 * ISO_NULL_POINTER, if dir or child are NULL 03355 * ISO_NODE_ALREADY_ADDED, if child is already added to other dir 03356 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03357 * ISO_WRONG_ARG_VALUE, if child == dir, or replace != (0,1) 03358 * 03359 * @since 0.6.2 03360 */ 03361 int iso_dir_add_node(IsoDir *dir, IsoNode *child, 03362 enum iso_replace_mode replace); 03363 03364 /** 03365 * Locate a node inside a given dir. 03366 * 03367 * @param dir 03368 * The dir where to look for the node. 03369 * @param name 03370 * The name of the node 03371 * @param node 03372 * Location for a pointer to the node, it will filled with NULL if the dir 03373 * doesn't have a child with the given name. 03374 * The node will be owned by the dir and shouldn't be unref(). Just call 03375 * iso_node_ref() to get your own reference to the node. 03376 * Note that you can pass NULL is the only thing you want to do is check 03377 * if a node with such name already exists on dir. 03378 * @return 03379 * 1 node found, 0 child has no such node, < 0 error 03380 * Possible errors: 03381 * ISO_NULL_POINTER, if dir or name are NULL 03382 * 03383 * @since 0.6.2 03384 */ 03385 int iso_dir_get_node(IsoDir *dir, const char *name, IsoNode **node); 03386 03387 /** 03388 * Get the number of children of a directory. 03389 * 03390 * @return 03391 * >= 0 number of items, < 0 error 03392 * Possible errors: 03393 * ISO_NULL_POINTER, if dir is NULL 03394 * 03395 * @since 0.6.2 03396 */ 03397 int iso_dir_get_children_count(IsoDir *dir); 03398 03399 /** 03400 * Removes a child from a directory. 03401 * The child is not freed, so you will become the owner of the node. Later 03402 * you can add the node to another dir (calling iso_dir_add_node), or free 03403 * it if you don't need it (with iso_node_unref). 03404 * 03405 * @return 03406 * 1 on success, < 0 error 03407 * Possible errors: 03408 * ISO_NULL_POINTER, if node is NULL 03409 * ISO_NODE_NOT_ADDED_TO_DIR, if node doesn't belong to a dir 03410 * 03411 * @since 0.6.2 03412 */ 03413 int iso_node_take(IsoNode *node); 03414 03415 /** 03416 * Removes a child from a directory and free (unref) it. 03417 * If you want to keep the child alive, you need to iso_node_ref() it 03418 * before this call, but in that case iso_node_take() is a better 03419 * alternative. 03420 * 03421 * @return 03422 * 1 on success, < 0 error 03423 * 03424 * @since 0.6.2 03425 */ 03426 int iso_node_remove(IsoNode *node); 03427 03428 /* 03429 * Get the parent of the given iso tree node. No extra ref is added to the 03430 * returned directory, you must take your ref. with iso_node_ref() if you 03431 * need it. 03432 * 03433 * If node is the root node, the same node will be returned as its parent. 03434 * 03435 * This returns NULL if the node doesn't pertain to any tree 03436 * (it was removed/taken). 03437 * 03438 * @since 0.6.2 03439 */ 03440 IsoDir *iso_node_get_parent(IsoNode *node); 03441 03442 /** 03443 * Get an iterator for the children of the given dir. 03444 * 03445 * You can iterate over the children with iso_dir_iter_next. When finished, 03446 * you should free the iterator with iso_dir_iter_free. 03447 * You musn't delete a child of the same dir, using iso_node_take() or 03448 * iso_node_remove(), while you're using the iterator. You can use 03449 * iso_dir_iter_take() or iso_dir_iter_remove() instead. 03450 * 03451 * You can use the iterator in the way like this 03452 * 03453 * IsoDirIter *iter; 03454 * IsoNode *node; 03455 * if ( iso_dir_get_children(dir, &iter) != 1 ) { 03456 * // handle error 03457 * } 03458 * while ( iso_dir_iter_next(iter, &node) == 1 ) { 03459 * // do something with the child 03460 * } 03461 * iso_dir_iter_free(iter); 03462 * 03463 * An iterator is intended to be used in a single iteration over the 03464 * children of a dir. Thus, it should be treated as a temporary object, 03465 * and free as soon as possible. 03466 * 03467 * @return 03468 * 1 success, < 0 error 03469 * Possible errors: 03470 * ISO_NULL_POINTER, if dir or iter are NULL 03471 * ISO_OUT_OF_MEM 03472 * 03473 * @since 0.6.2 03474 */ 03475 int iso_dir_get_children(const IsoDir *dir, IsoDirIter **iter); 03476 03477 /** 03478 * Get the next child. 03479 * Take care that the node is owned by its parent, and will be unref() when 03480 * the parent is freed. If you want your own ref to it, call iso_node_ref() 03481 * on it. 03482 * 03483 * @return 03484 * 1 success, 0 if dir has no more elements, < 0 error 03485 * Possible errors: 03486 * ISO_NULL_POINTER, if node or iter are NULL 03487 * ISO_ERROR, on wrong iter usage, usual caused by modiying the 03488 * dir during iteration 03489 * 03490 * @since 0.6.2 03491 */ 03492 int iso_dir_iter_next(IsoDirIter *iter, IsoNode **node); 03493 03494 /** 03495 * Check if there're more children. 03496 * 03497 * @return 03498 * 1 dir has more elements, 0 no, < 0 error 03499 * Possible errors: 03500 * ISO_NULL_POINTER, if iter is NULL 03501 * 03502 * @since 0.6.2 03503 */ 03504 int iso_dir_iter_has_next(IsoDirIter *iter); 03505 03506 /** 03507 * Free a dir iterator. 03508 * 03509 * @since 0.6.2 03510 */ 03511 void iso_dir_iter_free(IsoDirIter *iter); 03512 03513 /** 03514 * Removes a child from a directory during an iteration, without freeing it. 03515 * It's like iso_node_take(), but to be used during a directory iteration. 03516 * The node removed will be the last returned by the iteration. 03517 * 03518 * If you call this function twice without calling iso_dir_iter_next between 03519 * them is not allowed and you will get an ISO_ERROR in second call. 03520 * 03521 * @return 03522 * 1 on succes, < 0 error 03523 * Possible errors: 03524 * ISO_NULL_POINTER, if iter is NULL 03525 * ISO_ERROR, on wrong iter usage, for example by call this before 03526 * iso_dir_iter_next. 03527 * 03528 * @since 0.6.2 03529 */ 03530 int iso_dir_iter_take(IsoDirIter *iter); 03531 03532 /** 03533 * Removes a child from a directory during an iteration and unref() it. 03534 * It's like iso_node_remove(), but to be used during a directory iteration. 03535 * The node removed will be the last returned by the iteration. 03536 * 03537 * If you call this function twice without calling iso_dir_iter_next between 03538 * them is not allowed and you will get an ISO_ERROR in second call. 03539 * 03540 * @return 03541 * 1 on succes, < 0 error 03542 * Possible errors: 03543 * ISO_NULL_POINTER, if iter is NULL 03544 * ISO_ERROR, on wrong iter usage, for example by call this before 03545 * iso_dir_iter_next. 03546 * 03547 * @since 0.6.2 03548 */ 03549 int iso_dir_iter_remove(IsoDirIter *iter); 03550 03551 03552 /** 03553 * @since 0.6.4 03554 */ 03555 typedef struct iso_find_condition IsoFindCondition; 03556 03557 /** 03558 * Create a new condition that checks if the node name matches the given 03559 * wildcard. 03560 * 03561 * @param wildcard 03562 * @result 03563 * The created IsoFindCondition, NULL on error. 03564 * 03565 * @since 0.6.4 03566 */ 03567 IsoFindCondition *iso_new_find_conditions_name(const char *wildcard); 03568 03569 /** 03570 * Create a new condition that checks the node mode against a mode mask. It 03571 * can be used to check both file type and permissions. 03572 * 03573 * For example: 03574 * 03575 * iso_new_find_conditions_mode(S_IFREG) : search for regular files 03576 * iso_new_find_conditions_mode(S_IFCHR | S_IWUSR) : search for character 03577 * devices where owner has write permissions. 03578 * 03579 * @param mask 03580 * Mode mask to AND against node mode. 03581 * @result 03582 * The created IsoFindCondition, NULL on error. 03583 * 03584 * @since 0.6.4 03585 */ 03586 IsoFindCondition *iso_new_find_conditions_mode(mode_t mask); 03587 03588 /** 03589 * Create a new condition that checks the node gid. 03590 * 03591 * @param gid 03592 * Desired Group Id. 03593 * @result 03594 * The created IsoFindCondition, NULL on error. 03595 * 03596 * @since 0.6.4 03597 */ 03598 IsoFindCondition *iso_new_find_conditions_gid(gid_t gid); 03599 03600 /** 03601 * Create a new condition that checks the node uid. 03602 * 03603 * @param uid 03604 * Desired User Id. 03605 * @result 03606 * The created IsoFindCondition, NULL on error. 03607 * 03608 * @since 0.6.4 03609 */ 03610 IsoFindCondition *iso_new_find_conditions_uid(uid_t uid); 03611 03612 /** 03613 * Possible comparison between IsoNode and given conditions. 03614 * 03615 * @since 0.6.4 03616 */ 03617 enum iso_find_comparisons { 03618 ISO_FIND_COND_GREATER, 03619 ISO_FIND_COND_GREATER_OR_EQUAL, 03620 ISO_FIND_COND_EQUAL, 03621 ISO_FIND_COND_LESS, 03622 ISO_FIND_COND_LESS_OR_EQUAL 03623 }; 03624 03625 /** 03626 * Create a new condition that checks the time of last access. 03627 * 03628 * @param time 03629 * Time to compare against IsoNode atime. 03630 * @param comparison 03631 * Comparison to be done between IsoNode atime and submitted time. 03632 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 03633 * time is greater than the submitted time. 03634 * @result 03635 * The created IsoFindCondition, NULL on error. 03636 * 03637 * @since 0.6.4 03638 */ 03639 IsoFindCondition *iso_new_find_conditions_atime(time_t time, 03640 enum iso_find_comparisons comparison); 03641 03642 /** 03643 * Create a new condition that checks the time of last modification. 03644 * 03645 * @param time 03646 * Time to compare against IsoNode mtime. 03647 * @param comparison 03648 * Comparison to be done between IsoNode mtime and submitted time. 03649 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 03650 * time is greater than the submitted time. 03651 * @result 03652 * The created IsoFindCondition, NULL on error. 03653 * 03654 * @since 0.6.4 03655 */ 03656 IsoFindCondition *iso_new_find_conditions_mtime(time_t time, 03657 enum iso_find_comparisons comparison); 03658 03659 /** 03660 * Create a new condition that checks the time of last status change. 03661 * 03662 * @param time 03663 * Time to compare against IsoNode ctime. 03664 * @param comparison 03665 * Comparison to be done between IsoNode ctime and submitted time. 03666 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 03667 * time is greater than the submitted time. 03668 * @result 03669 * The created IsoFindCondition, NULL on error. 03670 * 03671 * @since 0.6.4 03672 */ 03673 IsoFindCondition *iso_new_find_conditions_ctime(time_t time, 03674 enum iso_find_comparisons comparison); 03675 03676 /** 03677 * Create a new condition that check if the two given conditions are 03678 * valid. 03679 * 03680 * @param a 03681 * @param b 03682 * IsoFindCondition to compare 03683 * @result 03684 * The created IsoFindCondition, NULL on error. 03685 * 03686 * @since 0.6.4 03687 */ 03688 IsoFindCondition *iso_new_find_conditions_and(IsoFindCondition *a, 03689 IsoFindCondition *b); 03690 03691 /** 03692 * Create a new condition that check if at least one the two given conditions 03693 * is valid. 03694 * 03695 * @param a 03696 * @param b 03697 * IsoFindCondition to compare 03698 * @result 03699 * The created IsoFindCondition, NULL on error. 03700 * 03701 * @since 0.6.4 03702 */ 03703 IsoFindCondition *iso_new_find_conditions_or(IsoFindCondition *a, 03704 IsoFindCondition *b); 03705 03706 /** 03707 * Create a new condition that check if the given conditions is false. 03708 * 03709 * @param negate 03710 * @result 03711 * The created IsoFindCondition, NULL on error. 03712 * 03713 * @since 0.6.4 03714 */ 03715 IsoFindCondition *iso_new_find_conditions_not(IsoFindCondition *negate); 03716 03717 /** 03718 * Find all directory children that match the given condition. 03719 * 03720 * @param dir 03721 * Directory where we will search children. 03722 * @param cond 03723 * Condition that the children must match in order to be returned. 03724 * It will be free together with the iterator. Remember to delete it 03725 * if this function return error. 03726 * @param iter 03727 * Iterator that returns only the children that match condition. 03728 * @return 03729 * 1 on success, < 0 on error 03730 * 03731 * @since 0.6.4 03732 */ 03733 int iso_dir_find_children(IsoDir* dir, IsoFindCondition *cond, 03734 IsoDirIter **iter); 03735 03736 /** 03737 * Get the destination of a node. 03738 * The returned string belongs to the node and should not be modified nor 03739 * freed. Use strdup if you really need your own copy. 03740 * 03741 * @since 0.6.2 03742 */ 03743 const char *iso_symlink_get_dest(const IsoSymlink *link); 03744 03745 /** 03746 * Set the destination of a link. 03747 * 03748 * @param opts 03749 * The option set to be manipulated 03750 * @param dest 03751 * New destination for the link. It must be a non-empty string, otherwise 03752 * this function doesn't modify previous destination. 03753 * @return 03754 * 1 on success, < 0 on error 03755 * 03756 * @since 0.6.2 03757 */ 03758 int iso_symlink_set_dest(IsoSymlink *link, const char *dest); 03759 03760 /** 03761 * Sets the order in which a node will be written on image. The data content 03762 * of files with high weight will be written to low block addresses. 03763 * 03764 * @param node 03765 * The node which weight will be changed. If it's a dir, this function 03766 * will change the weight of all its children. For nodes other that dirs 03767 * or regular files, this function has no effect. 03768 * @param w 03769 * The weight as a integer number, the greater this value is, the 03770 * closer from the begining of image the file will be written. 03771 * Default value at IsoNode creation is 0. 03772 * 03773 * @since 0.6.2 03774 */ 03775 void iso_node_set_sort_weight(IsoNode *node, int w); 03776 03777 /** 03778 * Get the sort weight of a file. 03779 * 03780 * @since 0.6.2 03781 */ 03782 int iso_file_get_sort_weight(IsoFile *file); 03783 03784 /** 03785 * Get the size of the file, in bytes 03786 * 03787 * @since 0.6.2 03788 */ 03789 off_t iso_file_get_size(IsoFile *file); 03790 03791 /** 03792 * Get the device id (major/minor numbers) of the given block or 03793 * character device file. The result is undefined for other kind 03794 * of special files, of first be sure iso_node_get_mode() returns either 03795 * S_IFBLK or S_IFCHR. 03796 * 03797 * @since 0.6.6 03798 */ 03799 dev_t iso_special_get_dev(IsoSpecial *special); 03800 03801 /** 03802 * Get the IsoStream that represents the contents of the given IsoFile. 03803 * The stream may be a filter stream which itself get its input from a 03804 * further stream. This may be inquired by iso_stream_get_input_stream(). 03805 * 03806 * If you iso_stream_open() the stream, iso_stream_close() it before 03807 * image generation begins. 03808 * 03809 * @return 03810 * The IsoStream. No extra ref is added, so the IsoStream belongs to the 03811 * IsoFile, and it may be freed together with it. Add your own ref with 03812 * iso_stream_ref() if you need it. 03813 * 03814 * @since 0.6.4 03815 */ 03816 IsoStream *iso_file_get_stream(IsoFile *file); 03817 03818 /** 03819 * Get the block lba of a file node, if it was imported from an old image. 03820 * 03821 * @param file 03822 * The file 03823 * @param lba 03824 * Will be filled with the kba 03825 * @param flag 03826 * Reserved for future usage, submit 0 03827 * @return 03828 * 1 if lba is valid (file comes from old image), 0 if file was newly 03829 * added, i.e. it does not come from an old image, < 0 error 03830 * 03831 * @since 0.6.4 03832 * 03833 * @deprecated Use iso_file_get_old_image_sections(), as this function does 03834 * not work with multi-extend files. 03835 */ 03836 int iso_file_get_old_image_lba(IsoFile *file, uint32_t *lba, int flag); 03837 03838 /** 03839 * Get the start addresses and the sizes of the data extents of a file node 03840 * if it was imported from an old image. 03841 * 03842 * @param file 03843 * The file 03844 * @param section_count 03845 * Returns the number of extent entries in sections array. 03846 * @param sections 03847 * Returns the array of file sections. Apply free() to dispose it. 03848 * @param flag 03849 * Reserved for future usage, submit 0 03850 * @return 03851 * 1 if there are valid extents (file comes from old image), 03852 * 0 if file was newly added, i.e. it does not come from an old image, 03853 * < 0 error 03854 * 03855 * @since 0.6.8 03856 */ 03857 int iso_file_get_old_image_sections(IsoFile *file, int *section_count, 03858 struct iso_file_section **sections, 03859 int flag); 03860 03861 /* 03862 * Like iso_file_get_old_image_lba(), but take an IsoNode. 03863 * 03864 * @return 03865 * 1 if lba is valid (file comes from old image), 0 if file was newly 03866 * added, i.e. it does not come from an old image, 2 node type has no 03867 * LBA (no regular file), < 0 error 03868 * 03869 * @since 0.6.4 03870 */ 03871 int iso_node_get_old_image_lba(IsoNode *node, uint32_t *lba, int flag); 03872 03873 /** 03874 * Add a new directory to the iso tree. Permissions, owner and hidden atts 03875 * are taken from parent, you can modify them later. 03876 * 03877 * @param parent 03878 * the dir where the new directory will be created 03879 * @param name 03880 * name for the new dir. If a node with same name already exists on 03881 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03882 * @param dir 03883 * place where to store a pointer to the newly created dir. No extra 03884 * ref is addded, so you will need to call iso_node_ref() if you really 03885 * need it. You can pass NULL in this parameter if you don't need the 03886 * pointer. 03887 * @return 03888 * number of nodes in parent if success, < 0 otherwise 03889 * Possible errors: 03890 * ISO_NULL_POINTER, if parent or name are NULL 03891 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03892 * ISO_OUT_OF_MEM 03893 * 03894 * @since 0.6.2 03895 */ 03896 int iso_tree_add_new_dir(IsoDir *parent, const char *name, IsoDir **dir); 03897 03898 /** 03899 * Add a new regular file to the iso tree. Permissions are set to 0444, 03900 * owner and hidden atts are taken from parent. You can modify any of them 03901 * later. 03902 * 03903 * @param parent 03904 * the dir where the new file will be created 03905 * @param name 03906 * name for the new file. If a node with same name already exists on 03907 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03908 * @param stream 03909 * IsoStream for the contents of the file. The reference will be taken 03910 * by the newly created file, you will need to take an extra ref to it 03911 * if you need it. 03912 * @param file 03913 * place where to store a pointer to the newly created file. No extra 03914 * ref is addded, so you will need to call iso_node_ref() if you really 03915 * need it. You can pass NULL in this parameter if you don't need the 03916 * pointer 03917 * @return 03918 * number of nodes in parent if success, < 0 otherwise 03919 * Possible errors: 03920 * ISO_NULL_POINTER, if parent, name or dest are NULL 03921 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03922 * ISO_OUT_OF_MEM 03923 * 03924 * @since 0.6.4 03925 */ 03926 int iso_tree_add_new_file(IsoDir *parent, const char *name, IsoStream *stream, 03927 IsoFile **file); 03928 03929 /** 03930 * Add a new symlink to the directory tree. Permissions are set to 0777, 03931 * owner and hidden atts are taken from parent. You can modify any of them 03932 * later. 03933 * 03934 * @param parent 03935 * the dir where the new symlink will be created 03936 * @param name 03937 * name for the new symlink. If a node with same name already exists on 03938 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03939 * @param dest 03940 * destination of the link 03941 * @param link 03942 * place where to store a pointer to the newly created link. No extra 03943 * ref is addded, so you will need to call iso_node_ref() if you really 03944 * need it. You can pass NULL in this parameter if you don't need the 03945 * pointer 03946 * @return 03947 * number of nodes in parent if success, < 0 otherwise 03948 * Possible errors: 03949 * ISO_NULL_POINTER, if parent, name or dest are NULL 03950 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03951 * ISO_OUT_OF_MEM 03952 * 03953 * @since 0.6.2 03954 */ 03955 int iso_tree_add_new_symlink(IsoDir *parent, const char *name, 03956 const char *dest, IsoSymlink **link); 03957 03958 /** 03959 * Add a new special file to the directory tree. As far as libisofs concerns, 03960 * an special file is a block device, a character device, a FIFO (named pipe) 03961 * or a socket. You can choose the specific kind of file you want to add 03962 * by setting mode propertly (see man 2 stat). 03963 * 03964 * Note that special files are only written to image when Rock Ridge 03965 * extensions are enabled. Moreover, a special file is just a directory entry 03966 * in the image tree, no data is written beyond that. 03967 * 03968 * Owner and hidden atts are taken from parent. You can modify any of them 03969 * later. 03970 * 03971 * @param parent 03972 * the dir where the new special file will be created 03973 * @param name 03974 * name for the new special file. If a node with same name already exists 03975 * on parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03976 * @param mode 03977 * file type and permissions for the new node. Note that you can't 03978 * specify any kind of file here, only special types are allowed. i.e, 03979 * S_IFSOCK, S_IFBLK, S_IFCHR and S_IFIFO are valid types; S_IFLNK, 03980 * S_IFREG and S_IFDIR aren't. 03981 * @param dev 03982 * device ID, equivalent to the st_rdev field in man 2 stat. 03983 * @param special 03984 * place where to store a pointer to the newly created special file. No 03985 * extra ref is addded, so you will need to call iso_node_ref() if you 03986 * really need it. You can pass NULL in this parameter if you don't need 03987 * the pointer. 03988 * @return 03989 * number of nodes in parent if success, < 0 otherwise 03990 * Possible errors: 03991 * ISO_NULL_POINTER, if parent, name or dest are NULL 03992 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03993 * ISO_WRONG_ARG_VALUE if you select a incorrect mode 03994 * ISO_OUT_OF_MEM 03995 * 03996 * @since 0.6.2 03997 */ 03998 int iso_tree_add_new_special(IsoDir *parent, const char *name, mode_t mode, 03999 dev_t dev, IsoSpecial **special); 04000 04001 /** 04002 * Set whether to follow or not symbolic links when added a file from a source 04003 * to IsoImage. Default behavior is to not follow symlinks. 04004 * 04005 * @since 0.6.2 04006 */ 04007 void iso_tree_set_follow_symlinks(IsoImage *image, int follow); 04008 04009 /** 04010 * Get current setting for follow_symlinks. 04011 * 04012 * @see iso_tree_set_follow_symlinks 04013 * @since 0.6.2 04014 */ 04015 int iso_tree_get_follow_symlinks(IsoImage *image); 04016 04017 /** 04018 * Set whether to skip or not disk files with names beginning by '.' 04019 * when adding a directory recursively. 04020 * Default behavior is to not ignore them. 04021 * 04022 * Clarification: This is not related to the IsoNode property to be hidden 04023 * in one or more of the resulting image trees as of 04024 * IsoHideNodeFlag and iso_node_set_hidden(). 04025 * 04026 * @since 0.6.2 04027 */ 04028 void iso_tree_set_ignore_hidden(IsoImage *image, int skip); 04029 04030 /** 04031 * Get current setting for ignore_hidden. 04032 * 04033 * @see iso_tree_set_ignore_hidden 04034 * @since 0.6.2 04035 */ 04036 int iso_tree_get_ignore_hidden(IsoImage *image); 04037 04038 /** 04039 * Set the replace mode, that defines the behavior of libisofs when adding 04040 * a node whit the same name that an existent one, during a recursive 04041 * directory addition. 04042 * 04043 * @since 0.6.2 04044 */ 04045 void iso_tree_set_replace_mode(IsoImage *image, enum iso_replace_mode mode); 04046 04047 /** 04048 * Get current setting for replace_mode. 04049 * 04050 * @see iso_tree_set_replace_mode 04051 * @since 0.6.2 04052 */ 04053 enum iso_replace_mode iso_tree_get_replace_mode(IsoImage *image); 04054 04055 /** 04056 * Set whether to skip or not special files. Default behavior is to not skip 04057 * them. Note that, despite of this setting, special files will never be added 04058 * to an image unless RR extensions were enabled. 04059 * 04060 * @param image 04061 * The image to manipulate. 04062 * @param skip 04063 * Bitmask to determine what kind of special files will be skipped: 04064 * bit0: ignore FIFOs 04065 * bit1: ignore Sockets 04066 * bit2: ignore char devices 04067 * bit3: ignore block devices 04068 * 04069 * @since 0.6.2 04070 */ 04071 void iso_tree_set_ignore_special(IsoImage *image, int skip); 04072 04073 /** 04074 * Get current setting for ignore_special. 04075 * 04076 * @see iso_tree_set_ignore_special 04077 * @since 0.6.2 04078 */ 04079 int iso_tree_get_ignore_special(IsoImage *image); 04080 04081 /** 04082 * Add a excluded path. These are paths that won't never added to image, and 04083 * will be excluded even when adding recursively its parent directory. 04084 * 04085 * For example, in 04086 * 04087 * iso_tree_add_exclude(image, "/home/user/data/private"); 04088 * iso_tree_add_dir_rec(image, root, "/home/user/data"); 04089 * 04090 * the directory /home/user/data/private won't be added to image. 04091 * 04092 * However, if you explicity add a deeper dir, it won't be excluded. i.e., 04093 * in the following example. 04094 * 04095 * iso_tree_add_exclude(image, "/home/user/data"); 04096 * iso_tree_add_dir_rec(image, root, "/home/user/data/private"); 04097 * 04098 * the directory /home/user/data/private is added. On the other, side, and 04099 * foollowing the the example above, 04100 * 04101 * iso_tree_add_dir_rec(image, root, "/home/user"); 04102 * 04103 * will exclude the directory "/home/user/data". 04104 * 04105 * Absolute paths are not mandatory, you can, for example, add a relative 04106 * path such as: 04107 * 04108 * iso_tree_add_exclude(image, "private"); 04109 * iso_tree_add_exclude(image, "user/data"); 04110 * 04111 * to excluve, respectively, all files or dirs named private, and also all 04112 * files or dirs named data that belong to a folder named "user". Not that the 04113 * above rule about deeper dirs is still valid. i.e., if you call 04114 * 04115 * iso_tree_add_dir_rec(image, root, "/home/user/data/music"); 04116 * 04117 * it is included even containing "user/data" string. However, a possible 04118 * "/home/user/data/music/user/data" is not added. 04119 * 04120 * Usual wildcards, such as * or ? are also supported, with the usual meaning 04121 * as stated in "man 7 glob". For example 04122 * 04123 * // to exclude backup text files 04124 * iso_tree_add_exclude(image, "*.~"); 04125 * 04126 * @return 04127 * 1 on success, < 0 on error 04128 * 04129 * @since 0.6.2 04130 */ 04131 int iso_tree_add_exclude(IsoImage *image, const char *path); 04132 04133 /** 04134 * Remove a previously added exclude. 04135 * 04136 * @see iso_tree_add_exclude 04137 * @return 04138 * 1 on success, 0 exclude do not exists, < 0 on error 04139 * 04140 * @since 0.6.2 04141 */ 04142 int iso_tree_remove_exclude(IsoImage *image, const char *path); 04143 04144 /** 04145 * Set a callback function that libisofs will call for each file that is 04146 * added to the given image by a recursive addition function. This includes 04147 * image import. 04148 * 04149 * @param image 04150 * The image to manipulate. 04151 * @param report 04152 * pointer to a function that will be called just before a file will be 04153 * added to the image. You can control whether the file will be in fact 04154 * added or ignored. 04155 * This function should return 1 to add the file, 0 to ignore it and 04156 * continue, < 0 to abort the process 04157 * NULL is allowed if you don't want any callback. 04158 * 04159 * @since 0.6.2 04160 */ 04161 void iso_tree_set_report_callback(IsoImage *image, 04162 int (*report)(IsoImage*, IsoFileSource*)); 04163 04164 /** 04165 * Add a new node to the image tree, from an existing file. 04166 * 04167 * TODO comment Builder and Filesystem related issues when exposing both 04168 * 04169 * All attributes will be taken from the source file. The appropriate file 04170 * type will be created. 04171 * 04172 * @param image 04173 * The image 04174 * @param parent 04175 * The directory in the image tree where the node will be added. 04176 * @param path 04177 * The absolute path of the file in the local filesystem. 04178 * The node will have the same leaf name as the file on disk. 04179 * Its directory path depends on the parent node. 04180 * @param node 04181 * place where to store a pointer to the newly added file. No 04182 * extra ref is addded, so you will need to call iso_node_ref() if you 04183 * really need it. You can pass NULL in this parameter if you don't need 04184 * the pointer. 04185 * @return 04186 * number of nodes in parent if success, < 0 otherwise 04187 * Possible errors: 04188 * ISO_NULL_POINTER, if image, parent or path are NULL 04189 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 04190 * ISO_OUT_OF_MEM 04191 * 04192 * @since 0.6.2 04193 */ 04194 int iso_tree_add_node(IsoImage *image, IsoDir *parent, const char *path, 04195 IsoNode **node); 04196 04197 /** 04198 * This is a more versatile form of iso_tree_add_node which allows to set 04199 * the node name in ISO image already when it gets added. 04200 * 04201 * Add a new node to the image tree, from an existing file, and with the 04202 * given name, that must not exist on dir. 04203 * 04204 * @param image 04205 * The image 04206 * @param parent 04207 * The directory in the image tree where the node will be added. 04208 * @param name 04209 * The leaf name that the node will have on image. 04210 * Its directory path depends on the parent node. 04211 * @param path 04212 * The absolute path of the file in the local filesystem. 04213 * @param node 04214 * place where to store a pointer to the newly added file. No 04215 * extra ref is addded, so you will need to call iso_node_ref() if you 04216 * really need it. You can pass NULL in this parameter if you don't need 04217 * the pointer. 04218 * @return 04219 * number of nodes in parent if success, < 0 otherwise 04220 * Possible errors: 04221 * ISO_NULL_POINTER, if image, parent or path are NULL 04222 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 04223 * ISO_OUT_OF_MEM 04224 * 04225 * @since 0.6.4 04226 */ 04227 int iso_tree_add_new_node(IsoImage *image, IsoDir *parent, const char *name, 04228 const char *path, IsoNode **node); 04229 04230 /** 04231 * Add a new node to the image tree with the given name that must not exist 04232 * on dir. The node data content will be a byte interval out of the data 04233 * content of a file in the local filesystem. 04234 * 04235 * @param image 04236 * The image 04237 * @param parent 04238 * The directory in the image tree where the node will be added. 04239 * @param name 04240 * The leaf name that the node will have on image. 04241 * Its directory path depends on the parent node. 04242 * @param path 04243 * The absolute path of the file in the local filesystem. For now 04244 * only regular files and symlinks to regular files are supported. 04245 * @param offset 04246 * Byte number in the given file from where to start reading data. 04247 * @param size 04248 * Max size of the file. This may be more than actually available from 04249 * byte offset to the end of the file in the local filesystem. 04250 * @param node 04251 * place where to store a pointer to the newly added file. No 04252 * extra ref is addded, so you will need to call iso_node_ref() if you 04253 * really need it. You can pass NULL in this parameter if you don't need 04254 * the pointer. 04255 * @return 04256 * number of nodes in parent if success, < 0 otherwise 04257 * Possible errors: 04258 * ISO_NULL_POINTER, if image, parent or path are NULL 04259 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 04260 * ISO_OUT_OF_MEM 04261 * 04262 * @since 0.6.4 04263 */ 04264 int iso_tree_add_new_cut_out_node(IsoImage *image, IsoDir *parent, 04265 const char *name, const char *path, 04266 off_t offset, off_t size, 04267 IsoNode **node); 04268 04269 /** 04270 * Add the contents of a dir to a given directory of the iso tree. 04271 * 04272 * There are several options to control what files are added or how they are 04273 * managed. Take a look at iso_tree_set_* functions to see diferent options 04274 * for recursive directory addition. 04275 * 04276 * TODO comment Builder and Filesystem related issues when exposing both 04277 * 04278 * @param image 04279 * The image to which the directory belongs. 04280 * @param parent 04281 * Directory on the image tree where to add the contents of the dir 04282 * @param dir 04283 * Path to a dir in the filesystem 04284 * @return 04285 * number of nodes in parent if success, < 0 otherwise 04286 * 04287 * @since 0.6.2 04288 */ 04289 int iso_tree_add_dir_rec(IsoImage *image, IsoDir *parent, const char *dir); 04290 04291 /** 04292 * Locate a node by its absolute path on image. 04293 * 04294 * @param image 04295 * The image to which the node belongs. 04296 * @param node 04297 * Location for a pointer to the node, it will filled with NULL if the 04298 * given path does not exists on image. 04299 * The node will be owned by the image and shouldn't be unref(). Just call 04300 * iso_node_ref() to get your own reference to the node. 04301 * Note that you can pass NULL is the only thing you want to do is check 04302 * if a node with such path really exists. 04303 * @return 04304 * 1 found, 0 not found, < 0 error 04305 * 04306 * @since 0.6.2 04307 */ 04308 int iso_tree_path_to_node(IsoImage *image, const char *path, IsoNode **node); 04309 04310 /** 04311 * Get the absolute path on image of the given node. 04312 * 04313 * @return 04314 * The path on the image, that must be freed when no more needed. If the 04315 * given node is not added to any image, this returns NULL. 04316 * @since 0.6.4 04317 */ 04318 char *iso_tree_get_node_path(IsoNode *node); 04319 04320 /** 04321 * Increments the reference counting of the given IsoDataSource. 04322 * 04323 * @since 0.6.2 04324 */ 04325 void iso_data_source_ref(IsoDataSource *src); 04326 04327 /** 04328 * Decrements the reference counting of the given IsoDataSource, freeing it 04329 * if refcount reach 0. 04330 * 04331 * @since 0.6.2 04332 */ 04333 void iso_data_source_unref(IsoDataSource *src); 04334 04335 /** 04336 * Create a new IsoDataSource from a local file. This is suitable for 04337 * accessing regular files or block devices with ISO images. 04338 * 04339 * @param path 04340 * The absolute path of the file 04341 * @param src 04342 * Will be filled with the pointer to the newly created data source. 04343 * @return 04344 * 1 on success, < 0 on error. 04345 * 04346 * @since 0.6.2 04347 */ 04348 int iso_data_source_new_from_file(const char *path, IsoDataSource **src); 04349 04350 /** 04351 * Get the status of the buffer used by a burn_source. 04352 * 04353 * @param b 04354 * A burn_source previously obtained with 04355 * iso_image_create_burn_source(). 04356 * @param size 04357 * Will be filled with the total size of the buffer, in bytes 04358 * @param free_bytes 04359 * Will be filled with the bytes currently available in buffer 04360 * @return 04361 * < 0 error, > 0 state: 04362 * 1="active" : input and consumption are active 04363 * 2="ending" : input has ended without error 04364 * 3="failing" : input had error and ended, 04365 * 5="abandoned" : consumption has ended prematurely 04366 * 6="ended" : consumption has ended without input error 04367 * 7="aborted" : consumption has ended after input error 04368 * 04369 * @since 0.6.2 04370 */ 04371 int iso_ring_buffer_get_status(struct burn_source *b, size_t *size, 04372 size_t *free_bytes); 04373 04374 #define ISO_MSGS_MESSAGE_LEN 4096 04375 04376 /** 04377 * Control queueing and stderr printing of messages from libisofs. 04378 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 04379 * "NOTE", "UPDATE", "DEBUG", "ALL". 04380 * 04381 * @param queue_severity Gives the minimum limit for messages to be queued. 04382 * Default: "NEVER". If you queue messages then you 04383 * must consume them by iso_msgs_obtain(). 04384 * @param print_severity Does the same for messages to be printed directly 04385 * to stderr. 04386 * @param print_id A text prefix to be printed before the message. 04387 * @return >0 for success, <=0 for error 04388 * 04389 * @since 0.6.2 04390 */ 04391 int iso_set_msgs_severities(char *queue_severity, char *print_severity, 04392 char *print_id); 04393 04394 /** 04395 * Obtain the oldest pending libisofs message from the queue which has at 04396 * least the given minimum_severity. This message and any older message of 04397 * lower severity will get discarded from the queue and is then lost forever. 04398 * 04399 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 04400 * "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER" 04401 * will discard the whole queue. 04402 * 04403 * @param minimum_severity 04404 * Threshhold 04405 * @param error_code 04406 * Will become a unique error code as listed at the end of this header 04407 * @param imgid 04408 * Id of the image that was issued the message. 04409 * @param msg_text 04410 * Must provide at least ISO_MSGS_MESSAGE_LEN bytes. 04411 * @param severity 04412 * Will become the severity related to the message and should provide at 04413 * least 80 bytes. 04414 * @return 04415 * 1 if a matching item was found, 0 if not, <0 for severe errors 04416 * 04417 * @since 0.6.2 04418 */ 04419 int iso_obtain_msgs(char *minimum_severity, int *error_code, int *imgid, 04420 char msg_text[], char severity[]); 04421 04422 04423 /** 04424 * Submit a message to the libisofs queueing system. It will be queued or 04425 * printed as if it was generated by libisofs itself. 04426 * 04427 * @param error_code 04428 * The unique error code of your message. 04429 * Submit 0 if you do not have reserved error codes within the libburnia 04430 * project. 04431 * @param msg_text 04432 * Not more than ISO_MSGS_MESSAGE_LEN characters of message text. 04433 * @param os_errno 04434 * Eventual errno related to the message. Submit 0 if the message is not 04435 * related to a operating system error. 04436 * @param severity 04437 * One of "ABORT", "FATAL", "FAILURE", "SORRY", "WARNING", "HINT", "NOTE", 04438 * "UPDATE", "DEBUG". Defaults to "FATAL". 04439 * @param origin 04440 * Submit 0 for now. 04441 * @return 04442 * 1 if message was delivered, <=0 if failure 04443 * 04444 * @since 0.6.4 04445 */ 04446 int iso_msgs_submit(int error_code, char msg_text[], int os_errno, 04447 char severity[], int origin); 04448 04449 04450 /** 04451 * Convert a severity name into a severity number, which gives the severity 04452 * rank of the name. 04453 * 04454 * @param severity_name 04455 * A name as with iso_msgs_submit(), e.g. "SORRY". 04456 * @param severity_number 04457 * The rank number: the higher, the more severe. 04458 * @return 04459 * >0 success, <=0 failure 04460 * 04461 * @since 0.6.4 04462 */ 04463 int iso_text_to_sev(char *severity_name, int *severity_number); 04464 04465 04466 /** 04467 * Convert a severity number into a severity name 04468 * 04469 * @param severity_number 04470 * The rank number: the higher, the more severe. 04471 * @param severity_name 04472 * A name as with iso_msgs_submit(), e.g. "SORRY". 04473 * 04474 * @since 0.6.4 04475 */ 04476 int iso_sev_to_text(int severity_number, char **severity_name); 04477 04478 04479 /** 04480 * Get the id of an IsoImage, used for message reporting. This message id, 04481 * retrieved with iso_obtain_msgs(), can be used to distinguish what 04482 * IsoImage has isssued a given message. 04483 * 04484 * @since 0.6.2 04485 */ 04486 int iso_image_get_msg_id(IsoImage *image); 04487 04488 /** 04489 * Get a textual description of a libisofs error. 04490 * 04491 * @since 0.6.2 04492 */ 04493 const char *iso_error_to_msg(int errcode); 04494 04495 /** 04496 * Get the severity of a given error code 04497 * @return 04498 * 0x10000000 -> DEBUG 04499 * 0x20000000 -> UPDATE 04500 * 0x30000000 -> NOTE 04501 * 0x40000000 -> HINT 04502 * 0x50000000 -> WARNING 04503 * 0x60000000 -> SORRY 04504 * 0x64000000 -> MISHAP 04505 * 0x68000000 -> FAILURE 04506 * 0x70000000 -> FATAL 04507 * 0x71000000 -> ABORT 04508 * 04509 * @since 0.6.2 04510 */ 04511 int iso_error_get_severity(int e); 04512 04513 /** 04514 * Get the priority of a given error. 04515 * @return 04516 * 0x00000000 -> ZERO 04517 * 0x10000000 -> LOW 04518 * 0x20000000 -> MEDIUM 04519 * 0x30000000 -> HIGH 04520 * 04521 * @since 0.6.2 04522 */ 04523 int iso_error_get_priority(int e); 04524 04525 /** 04526 * Get the message queue code of a libisofs error. 04527 */ 04528 int iso_error_get_code(int e); 04529 04530 /** 04531 * Set the minimum error severity that causes a libisofs operation to 04532 * be aborted as soon as possible. 04533 * 04534 * @param severity 04535 * one of "FAILURE", "MISHAP", "SORRY", "WARNING", "HINT", "NOTE". 04536 * Severities greater or equal than FAILURE always cause program to abort. 04537 * Severities under NOTE won't never cause function abort. 04538 * @return 04539 * Previous abort priority on success, < 0 on error. 04540 * 04541 * @since 0.6.2 04542 */ 04543 int iso_set_abort_severity(char *severity); 04544 04545 /** 04546 * Return the messenger object handle used by libisofs. This handle 04547 * may be used by related libraries to their own compatible 04548 * messenger objects and thus to direct their messages to the libisofs 04549 * message queue. See also: libburn, API function burn_set_messenger(). 04550 * 04551 * @return the handle. Do only use with compatible 04552 * 04553 * @since 0.6.2 04554 */ 04555 void *iso_get_messenger(); 04556 04557 /** 04558 * Take a ref to the given IsoFileSource. 04559 * 04560 * @since 0.6.2 04561 */ 04562 void iso_file_source_ref(IsoFileSource *src); 04563 04564 /** 04565 * Drop your ref to the given IsoFileSource, eventually freeing the associated 04566 * system resources. 04567 * 04568 * @since 0.6.2 04569 */ 04570 void iso_file_source_unref(IsoFileSource *src); 04571 04572 /* 04573 * this are just helpers to invoque methods in class 04574 */ 04575 04576 /** 04577 * Get the absolute path in the filesystem this file source belongs to. 04578 * 04579 * @return 04580 * the path of the FileSource inside the filesystem, it should be 04581 * freed when no more needed. 04582 * 04583 * @since 0.6.2 04584 */ 04585 char* iso_file_source_get_path(IsoFileSource *src); 04586 04587 /** 04588 * Get the name of the file, with the dir component of the path. 04589 * 04590 * @return 04591 * the name of the file, it should be freed when no more needed. 04592 * 04593 * @since 0.6.2 04594 */ 04595 char* iso_file_source_get_name(IsoFileSource *src); 04596 04597 /** 04598 * Get information about the file. 04599 * @return 04600 * 1 success, < 0 error 04601 * Error codes: 04602 * ISO_FILE_ACCESS_DENIED 04603 * ISO_FILE_BAD_PATH 04604 * ISO_FILE_DOESNT_EXIST 04605 * ISO_OUT_OF_MEM 04606 * ISO_FILE_ERROR 04607 * ISO_NULL_POINTER 04608 * 04609 * @since 0.6.2 04610 */ 04611 int iso_file_source_lstat(IsoFileSource *src, struct stat *info); 04612 04613 /** 04614 * Check if the process has access to read file contents. Note that this 04615 * is not necessarily related with (l)stat functions. For example, in a 04616 * filesystem implementation to deal with an ISO image, if the user has 04617 * read access to the image it will be able to read all files inside it, 04618 * despite of the particular permission of each file in the RR tree, that 04619 * are what the above functions return. 04620 * 04621 * @return 04622 * 1 if process has read access, < 0 on error 04623 * Error codes: 04624 * ISO_FILE_ACCESS_DENIED 04625 * ISO_FILE_BAD_PATH 04626 * ISO_FILE_DOESNT_EXIST 04627 * ISO_OUT_OF_MEM 04628 * ISO_FILE_ERROR 04629 * ISO_NULL_POINTER 04630 * 04631 * @since 0.6.2 04632 */ 04633 int iso_file_source_access(IsoFileSource *src); 04634 04635 /** 04636 * Get information about the file. If the file is a symlink, the info 04637 * returned refers to the destination. 04638 * 04639 * @return 04640 * 1 success, < 0 error 04641 * Error codes: 04642 * ISO_FILE_ACCESS_DENIED 04643 * ISO_FILE_BAD_PATH 04644 * ISO_FILE_DOESNT_EXIST 04645 * ISO_OUT_OF_MEM 04646 * ISO_FILE_ERROR 04647 * ISO_NULL_POINTER 04648 * 04649 * @since 0.6.2 04650 */ 04651 int iso_file_source_stat(IsoFileSource *src, struct stat *info); 04652 04653 /** 04654 * Opens the source. 04655 * @return 1 on success, < 0 on error 04656 * Error codes: 04657 * ISO_FILE_ALREADY_OPENED 04658 * ISO_FILE_ACCESS_DENIED 04659 * ISO_FILE_BAD_PATH 04660 * ISO_FILE_DOESNT_EXIST 04661 * ISO_OUT_OF_MEM 04662 * ISO_FILE_ERROR 04663 * ISO_NULL_POINTER 04664 * 04665 * @since 0.6.2 04666 */ 04667 int iso_file_source_open(IsoFileSource *src); 04668 04669 /** 04670 * Close a previuously openned file 04671 * @return 1 on success, < 0 on error 04672 * Error codes: 04673 * ISO_FILE_ERROR 04674 * ISO_NULL_POINTER 04675 * ISO_FILE_NOT_OPENED 04676 * 04677 * @since 0.6.2 04678 */ 04679 int iso_file_source_close(IsoFileSource *src); 04680 04681 /** 04682 * Attempts to read up to count bytes from the given source into 04683 * the buffer starting at buf. 04684 * 04685 * The file src must be open() before calling this, and close() when no 04686 * more needed. Not valid for dirs. On symlinks it reads the destination 04687 * file. 04688 * 04689 * @param src 04690 * The given source 04691 * @param buf 04692 * Pointer to a buffer of at least count bytes where the read data will be 04693 * stored 04694 * @param count 04695 * Bytes to read 04696 * @return 04697 * number of bytes read, 0 if EOF, < 0 on error 04698 * Error codes: 04699 * ISO_FILE_ERROR 04700 * ISO_NULL_POINTER 04701 * ISO_FILE_NOT_OPENED 04702 * ISO_WRONG_ARG_VALUE -> if count == 0 04703 * ISO_FILE_IS_DIR 04704 * ISO_OUT_OF_MEM 04705 * ISO_INTERRUPTED 04706 * 04707 * @since 0.6.2 04708 */ 04709 int iso_file_source_read(IsoFileSource *src, void *buf, size_t count); 04710 04711 /** 04712 * Repositions the offset of the given IsoFileSource (must be opened) to the 04713 * given offset according to the value of flag. 04714 * 04715 * @param src 04716 * The given source 04717 * @param offset 04718 * in bytes 04719 * @param flag 04720 * 0 The offset is set to offset bytes (SEEK_SET) 04721 * 1 The offset is set to its current location plus offset bytes 04722 * (SEEK_CUR) 04723 * 2 The offset is set to the size of the file plus offset bytes 04724 * (SEEK_END). 04725 * @return 04726 * Absolute offset posistion on the file, or < 0 on error. Cast the 04727 * returning value to int to get a valid libisofs error. 04728 * @since 0.6.4 04729 */ 04730 off_t iso_file_source_lseek(IsoFileSource *src, off_t offset, int flag); 04731 04732 /** 04733 * Read a directory. 04734 * 04735 * Each call to this function will return a new child, until we reach 04736 * the end of file (i.e, no more children), in that case it returns 0. 04737 * 04738 * The dir must be open() before calling this, and close() when no more 04739 * needed. Only valid for dirs. 04740 * 04741 * Note that "." and ".." children MUST NOT BE returned. 04742 * 04743 * @param src 04744 * The given source 04745 * @param child 04746 * pointer to be filled with the given child. Undefined on error or OEF 04747 * @return 04748 * 1 on success, 0 if EOF (no more children), < 0 on error 04749 * Error codes: 04750 * ISO_FILE_ERROR 04751 * ISO_NULL_POINTER 04752 * ISO_FILE_NOT_OPENED 04753 * ISO_FILE_IS_NOT_DIR 04754 * ISO_OUT_OF_MEM 04755 * 04756 * @since 0.6.2 04757 */ 04758 int iso_file_source_readdir(IsoFileSource *src, IsoFileSource **child); 04759 04760 /** 04761 * Read the destination of a symlink. You don't need to open the file 04762 * to call this. 04763 * 04764 * @param src 04765 * An IsoFileSource corresponding to a symbolic link. 04766 * @param buf 04767 * allocated buffer of at least bufsiz bytes. 04768 * The dest. will be copied there, and it will be NULL-terminated 04769 * @param bufsiz 04770 * characters to be copied. Destination link will be truncated if 04771 * it is larger than given size. This includes the 0x0 character. 04772 * @return 04773 * 1 on success, < 0 on error 04774 * Error codes: 04775 * ISO_FILE_ERROR 04776 * ISO_NULL_POINTER 04777 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 04778 * ISO_FILE_IS_NOT_SYMLINK 04779 * ISO_OUT_OF_MEM 04780 * ISO_FILE_BAD_PATH 04781 * ISO_FILE_DOESNT_EXIST 04782 * 04783 * @since 0.6.2 04784 */ 04785 int iso_file_source_readlink(IsoFileSource *src, char *buf, size_t bufsiz); 04786 04787 04788 /** 04789 * Get the AAIP string with encoded ACL and xattr. 04790 * (Not to be confused with ECMA-119 Extended Attributes). 04791 * @param src The file source object to be inquired. 04792 * @param aa_string Returns a pointer to the AAIP string data. If no AAIP 04793 * string is available, *aa_string becomes NULL. 04794 * (See doc/susp_aaip_2_0.txt for the meaning of AAIP.) 04795 * The caller is responsible for finally calling free() 04796 * on non-NULL results. 04797 * @param flag Bitfield for control purposes 04798 * bit0= Transfer ownership of AAIP string data. 04799 * src will free the eventual cached data and might 04800 * not be able to produce it again. 04801 * bit1= No need to get ACL (but no guarantee of exclusion) 04802 * bit2= No need to get xattr (but no guarantee of exclusion) 04803 * @return 1 means success (*aa_string == NULL is possible) 04804 * <0 means failure and must b a valid libisofs error code 04805 * (e.g. ISO_FILE_ERROR if no better one can be found). 04806 * @since 0.6.14 04807 */ 04808 int iso_file_source_get_aa_string(IsoFileSource *src, 04809 unsigned char **aa_string, int flag); 04810 04811 /** 04812 * Get the filesystem for this source. No extra ref is added, so you 04813 * musn't unref the IsoFilesystem. 04814 * 04815 * @return 04816 * The filesystem, NULL on error 04817 * 04818 * @since 0.6.2 04819 */ 04820 IsoFilesystem* iso_file_source_get_filesystem(IsoFileSource *src); 04821 04822 /** 04823 * Take a ref to the given IsoFilesystem 04824 * 04825 * @since 0.6.2 04826 */ 04827 void iso_filesystem_ref(IsoFilesystem *fs); 04828 04829 /** 04830 * Drop your ref to the given IsoFilesystem, evetually freeing associated 04831 * resources. 04832 * 04833 * @since 0.6.2 04834 */ 04835 void iso_filesystem_unref(IsoFilesystem *fs); 04836 04837 /** 04838 * Create a new IsoFilesystem to access a existent ISO image. 04839 * 04840 * @param src 04841 * Data source to access data. 04842 * @param opts 04843 * Image read options 04844 * @param msgid 04845 * An image identifer, obtained with iso_image_get_msg_id(), used to 04846 * associated messages issued by the filesystem implementation with an 04847 * existent image. If you are not using this filesystem in relation with 04848 * any image context, just use 0x1fffff as the value for this parameter. 04849 * @param fs 04850 * Will be filled with a pointer to the filesystem that can be used 04851 * to access image contents. 04852 * @param 04853 * 1 on success, < 0 on error 04854 * 04855 * @since 0.6.2 04856 */ 04857 int iso_image_filesystem_new(IsoDataSource *src, IsoReadOpts *opts, int msgid, 04858 IsoImageFilesystem **fs); 04859 04860 /** 04861 * Get the volset identifier for an existent image. The returned string belong 04862 * to the IsoImageFilesystem and shouldn't be free() nor modified. 04863 * 04864 * @since 0.6.2 04865 */ 04866 const char *iso_image_fs_get_volset_id(IsoImageFilesystem *fs); 04867 04868 /** 04869 * Get the volume identifier for an existent image. The returned string belong 04870 * to the IsoImageFilesystem and shouldn't be free() nor modified. 04871 * 04872 * @since 0.6.2 04873 */ 04874 const char *iso_image_fs_get_volume_id(IsoImageFilesystem *fs); 04875 04876 /** 04877 * Get the publisher identifier for an existent image. The returned string 04878 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04879 * 04880 * @since 0.6.2 04881 */ 04882 const char *iso_image_fs_get_publisher_id(IsoImageFilesystem *fs); 04883 04884 /** 04885 * Get the data preparer identifier for an existent image. The returned string 04886 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04887 * 04888 * @since 0.6.2 04889 */ 04890 const char *iso_image_fs_get_data_preparer_id(IsoImageFilesystem *fs); 04891 04892 /** 04893 * Get the system identifier for an existent image. The returned string belong 04894 * to the IsoImageFilesystem and shouldn't be free() nor modified. 04895 * 04896 * @since 0.6.2 04897 */ 04898 const char *iso_image_fs_get_system_id(IsoImageFilesystem *fs); 04899 04900 /** 04901 * Get the application identifier for an existent image. The returned string 04902 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04903 * 04904 * @since 0.6.2 04905 */ 04906 const char *iso_image_fs_get_application_id(IsoImageFilesystem *fs); 04907 04908 /** 04909 * Get the copyright file identifier for an existent image. The returned string 04910 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04911 * 04912 * @since 0.6.2 04913 */ 04914 const char *iso_image_fs_get_copyright_file_id(IsoImageFilesystem *fs); 04915 04916 /** 04917 * Get the abstract file identifier for an existent image. The returned string 04918 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04919 * 04920 * @since 0.6.2 04921 */ 04922 const char *iso_image_fs_get_abstract_file_id(IsoImageFilesystem *fs); 04923 04924 /** 04925 * Get the biblio file identifier for an existent image. The returned string 04926 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04927 * 04928 * @since 0.6.2 04929 */ 04930 const char *iso_image_fs_get_biblio_file_id(IsoImageFilesystem *fs); 04931 04932 /** 04933 * Increment reference count of an IsoStream. 04934 * 04935 * @since 0.6.4 04936 */ 04937 void iso_stream_ref(IsoStream *stream); 04938 04939 /** 04940 * Decrement reference count of an IsoStream, and eventually free it if 04941 * refcount reach 0. 04942 * 04943 * @since 0.6.4 04944 */ 04945 void iso_stream_unref(IsoStream *stream); 04946 04947 /** 04948 * Opens the given stream. Remember to close the Stream before writing the 04949 * image. 04950 * 04951 * @return 04952 * 1 on success, 2 file greater than expected, 3 file smaller than 04953 * expected, < 0 on error 04954 * 04955 * @since 0.6.4 04956 */ 04957 int iso_stream_open(IsoStream *stream); 04958 04959 /** 04960 * Close a previously openned IsoStream. 04961 * 04962 * @return 04963 * 1 on success, < 0 on error 04964 * 04965 * @since 0.6.4 04966 */ 04967 int iso_stream_close(IsoStream *stream); 04968 04969 /** 04970 * Get the size of a given stream. This function should always return the same 04971 * size, even if the underlying source size changes, unless you call 04972 * iso_stream_update_size(). 04973 * 04974 * @return 04975 * IsoStream size in bytes 04976 * 04977 * @since 0.6.4 04978 */ 04979 off_t iso_stream_get_size(IsoStream *stream); 04980 04981 /** 04982 * Attempts to read up to count bytes from the given stream into 04983 * the buffer starting at buf. 04984 * 04985 * The stream must be open() before calling this, and close() when no 04986 * more needed. 04987 * 04988 * @return 04989 * number of bytes read, 0 if EOF, < 0 on error 04990 * 04991 * @since 0.6.4 04992 */ 04993 int iso_stream_read(IsoStream *stream, void *buf, size_t count); 04994 04995 /** 04996 * Whether the given IsoStream can be read several times, with the same 04997 * results. 04998 * For example, a regular file is repeatable, you can read it as many 04999 * times as you want. However, a pipe isn't. 05000 * 05001 * This function doesn't take into account if the file has been modified 05002 * between the two reads. 05003 * 05004 * @return 05005 * 1 if stream is repeatable, 0 if not, < 0 on error 05006 * 05007 * @since 0.6.4 05008 */ 05009 int iso_stream_is_repeatable(IsoStream *stream); 05010 05011 /** 05012 * Updates the size of the IsoStream with the current size of the 05013 * underlying source. 05014 * 05015 * @return 05016 * 1 if ok, < 0 on error (has to be a valid libisofs error code), 05017 * 0 if the IsoStream does not support this function. 05018 * @since 0.6.8 05019 */ 05020 int iso_stream_update_size(IsoStream *stream); 05021 05022 /** 05023 * Get an unique identifier for a given IsoStream. 05024 * 05025 * @since 0.6.4 05026 */ 05027 void iso_stream_get_id(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, 05028 ino_t *ino_id); 05029 05030 /** 05031 * Try to get eventual source path string of a stream. Meaning and availability 05032 * of this string depends on the stream.class . Expect valid results with 05033 * types "fsrc" and "cout". Result formats are 05034 * fsrc: result of file_source_get_path() 05035 * cout: result of file_source_get_path() " " offset " " size 05036 * @param stream 05037 * The stream to be inquired. 05038 * @param flag 05039 * Bitfield for control purposes, unused yet, submit 0 05040 * @return 05041 * A copy of the path string. Apply free() when no longer needed. 05042 * NULL if no path string is available. 05043 * 05044 * @since 0.6.18 05045 */ 05046 char *iso_stream_get_source_path(IsoStream *stream, int flag); 05047 05048 /** 05049 * Compare two streams whether they are based on the same input and will 05050 * produce the same output. If in any doubt, then this comparison will 05051 * indicate no match. 05052 * 05053 * @param s1 05054 * The first stream to compare. 05055 * @param s2 05056 * The second stream to compare. 05057 * @return 05058 * -1 if s1 is smaller s2 , 0 if s1 matches s2 , 1 if s1 is larger s2 05059 * @param flag 05060 * bit0= do not use s1->class->compare() even if available 05061 * (e.g. because iso_stream_cmp_ino(0 is called as fallback 05062 * from said stream->class->compare()) 05063 * 05064 * @since 0.6.20 05065 */ 05066 int iso_stream_cmp_ino(IsoStream *s1, IsoStream *s2, int flag); 05067 05068 /* --------------------------------- AAIP --------------------------------- */ 05069 05070 /** 05071 * Function to identify and manage AAIP strings as xinfo of IsoNode. 05072 * 05073 * An AAIP string contains the Attribute List with the xattr and ACL of a node 05074 * in the image tree. It is formatted according to libisofs specification 05075 * AAIP-2.0 and ready to be written into the System Use Area resp. Continuation 05076 * Area of a directory entry in an ISO image. 05077 * 05078 * Applications are not supposed to manipulate AAIP strings directly. 05079 * They should rather make use of the appropriate iso_node_get_* and 05080 * iso_node_set_* calls. 05081 * 05082 * AAIP represents ACLs as xattr with empty name and AAIP-specific binary 05083 * content. Local filesystems may represent ACLs as xattr with names like 05084 * "system.posix_acl_access". libisofs does not interpret those local 05085 * xattr representations of ACL directly but rather uses the ACL interface of 05086 * the local system. By default the local xattr representations of ACL will 05087 * not become part of the AAIP Attribute List via iso_local_get_attrs() and 05088 * not be attached to local files via iso_local_set_attrs(). 05089 * 05090 * @since 0.6.14 05091 */ 05092 int aaip_xinfo_func(void *data, int flag); 05093 05094 05095 /** 05096 * Get the eventual ACLs which are associated with the node. 05097 * The result will be in "long" text form as of man acl resp. acl_to_text(). 05098 * Call this function with flag bit15 to finally release the memory 05099 * occupied by an ACL inquiry. 05100 * 05101 * @param node 05102 * The node that is to be inquired. 05103 * @param access_text 05104 * Will return a pointer to the eventual "access" ACL text or NULL if it 05105 * is not available and flag bit 4 is set. 05106 * @param default_text 05107 * Will return a pointer to the eventual "default" ACL or NULL if it 05108 * is not available. 05109 * (GNU/Linux directories can have a "default" ACL which influences 05110 * the permissions of newly created files.) 05111 * @param flag 05112 * Bitfield for control purposes 05113 * bit4= if no "access" ACL is available: return *access_text == NULL 05114 * else: produce ACL from stat(2) permissions 05115 * bit15= free memory and return 1 (node may be NULL) 05116 * @return 05117 * 2 *access_text was produced from stat(2) permissions 05118 * 1 *access_text was produced from ACL of node 05119 * 0 if flag bit4 is set and no ACL is available 05120 * < 0 on error 05121 * 05122 * @since 0.6.14 05123 */ 05124 int iso_node_get_acl_text(IsoNode *node, 05125 char **access_text, char **default_text, int flag); 05126 05127 05128 /** 05129 * Set the ACLs of the given node to the lists in parameters access_text and 05130 * default_text or delete them. 05131 * 05132 * The stat(2) permission bits get updated according to the new "access" ACL if 05133 * neither bit1 of parameter flag is set nor parameter access_text is NULL. 05134 * Note that S_IRWXG permission bits correspond to ACL mask permissions 05135 * if a "mask::" entry exists in the ACL. Only if there is no "mask::" then 05136 * the "group::" entry corresponds to to S_IRWXG. 05137 * 05138 * @param node 05139 * The node that is to be manipulated. 05140 * @param access_text 05141 * The text to be set into effect as "access" ACL. NULL will delete an 05142 * eventually existing "access" ACL of the node. 05143 * @param default_text 05144 * The text to be set into effect as "default" ACL. NULL will delete an 05145 * eventually existing "default" ACL of the node. 05146 * (GNU/Linux directories can have a "default" ACL which influences 05147 * the permissions of newly created files.) 05148 * @param flag 05149 * Bitfield for control purposes 05150 * bit1= ignore text parameters but rather update eventual "access" ACL 05151 * to the stat(2) permissions of node. If no "access" ACL exists, 05152 * then do nothing and return success. 05153 * @return 05154 * > 0 success 05155 * < 0 failure 05156 * 05157 * @since 0.6.14 05158 */ 05159 int iso_node_set_acl_text(IsoNode *node, 05160 char *access_text, char *default_text, int flag); 05161 05162 /** 05163 * Like iso_node_get_permissions but reflecting ACL entry "group::" in S_IRWXG 05164 * rather than ACL entry "mask::". This is necessary if the permissions of a 05165 * node with ACL shall be restored to a filesystem without restoring the ACL. 05166 * The same mapping happens internally when the ACL of a node is deleted. 05167 * If the node has no ACL then the result is iso_node_get_permissions(node). 05168 * @param node 05169 * The node that is to be inquired. 05170 * @return 05171 * Permission bits as of stat(2) 05172 * 05173 * @since 0.6.14 05174 */ 05175 mode_t iso_node_get_perms_wo_acl(const IsoNode *node); 05176 05177 05178 /** 05179 * Get the list of xattr which is associated with the node. 05180 * The resulting data may finally be disposed by a call to this function 05181 * with flag bit15 set, or its components may be freed one-by-one. 05182 * The following values are either NULL or malloc() memory: 05183 * *names, *value_lengths, *values, (*names)[i], (*values)[i] 05184 * with 0 <= i < *num_attrs. 05185 * It is allowed to replace or reallocate those memory items in order to 05186 * to manipulate the attribute list before submitting it to other calls. 05187 * 05188 * If enabled by flag bit0, this list possibly includes the ACLs of the node. 05189 * They are eventually encoded in a pair with empty name. It is not advisable 05190 * to alter the value or name of that pair. One may decide to erase both ACLs 05191 * by deleting this pair or to copy both ACLs by copying the content of this 05192 * pair to an empty named pair of another node. 05193 * For all other ACL purposes use iso_node_get_acl_text(). 05194 * 05195 * @param node 05196 * The node that is to be inquired. 05197 * @param num_attrs 05198 * Will return the number of name-value pairs 05199 * @param names 05200 * Will return an array of pointers to 0-terminated names 05201 * @param value_lengths 05202 * Will return an arry with the lenghts of values 05203 * @param values 05204 * Will return an array of pointers to strings of 8-bit bytes 05205 * @param flag 05206 * Bitfield for control purposes 05207 * bit0= obtain eventual ACLs as attribute with empty name 05208 * bit2= with bit0: do not obtain attributes other than ACLs 05209 * bit15= free memory (node may be NULL) 05210 * @return 05211 * 1 = ok (but *num_attrs may be 0) 05212 * < 0 = error 05213 * 05214 * @since 0.6.14 05215 */ 05216 int iso_node_get_attrs(IsoNode *node, size_t *num_attrs, 05217 char ***names, size_t **value_lengths, char ***values, int flag); 05218 05219 05220 /** 05221 * Obtain the value of a particular xattr name. Eventually make a copy of 05222 * that value and add a trailing 0 byte for caller convenience. 05223 * @param node 05224 * The node that is to be inquired. 05225 * @param name 05226 * The xattr name that shall be looked up. 05227 * @param value_length 05228 * Will return the lenght of value 05229 * @param value 05230 * Will return a string of 8-bit bytes. free() it when no longer needed. 05231 * @param flag 05232 * Bitfield for control purposes, unused yet, submit 0 05233 * @return 05234 * 1= name found , 0= name not found , <0 indicates error 05235 * 05236 * @since 0.6.18 05237 */ 05238 int iso_node_lookup_attr(IsoNode *node, char *name, 05239 size_t *value_length, char **value, int flag); 05240 05241 /** 05242 * Set the list of xattr which is associated with the node. 05243 * The data get copied so that you may dispose your input data afterwards. 05244 * 05245 * If enabled by flag bit0 then the submitted list of attributes will not only 05246 * overwrite xattr but also both eventual ACLs of the node. Eventual ACL in 05247 * the submitted list have to reside in an attribute with empty name. 05248 * 05249 * @param node 05250 * The node that is to be manipulated. 05251 * @param num_attrs 05252 * Number of attributes 05253 * @param names 05254 * Array of pointers to 0 terminated name strings 05255 * @param value_lengths 05256 * Array of byte lengths for each value 05257 * @param values 05258 * Array of pointers to the value bytes 05259 * @param flag 05260 * Bitfield for control purposes 05261 * bit0= Do not maintain eventual existing ACL of the node. 05262 * Set eventual new ACL from value of empty name. 05263 * bit1= Do not clear the existing attribute list but merge it with 05264 * the list given by this call. 05265 * The given values override the values of their eventually existing 05266 * names. If no xattr with a given name exists, then it will be 05267 * added as new xattr. So this bit can be used to set a single 05268 * xattr without inquiring any other xattr of the node. 05269 * bit2= Delete the attributes with the given names 05270 * bit3= Allow to affect non-user attributes. 05271 * I.e. those with a non-empty name which does not begin by "user." 05272 * (The empty name is always allowed and governed by bit0.) This 05273 * deletes all previously existing attributes if not bit1 is set. 05274 * @return 05275 * 1 = ok 05276 * < 0 = error 05277 * 05278 * @since 0.6.14 05279 */ 05280 int iso_node_set_attrs(IsoNode *node, size_t num_attrs, char **names, 05281 size_t *value_lengths, char **values, int flag); 05282 05283 05284 /* ----- This is an interface to ACL and xattr of the local filesystem ----- */ 05285 05286 /** 05287 * libisofs has an internal system dependent adapter to ACL and xattr 05288 * operations. For the sake of completeness and simplicity it exposes this 05289 * functionality to its applications which might want to get and set ACLs 05290 * from local files. 05291 */ 05292 05293 /** 05294 * Get an ACL of the given file in the local filesystem in long text form. 05295 * 05296 * @param disk_path 05297 * Absolute path to the file 05298 * @param text 05299 * Will return a pointer to the ACL text. If not NULL the text will be 05300 * 0 terminated and finally has to be disposed by a call to this function 05301 * with bit15 set. 05302 * @param flag 05303 * Bitfield for control purposes 05304 * bit0= get "default" ACL rather than "access" ACL 05305 * bit4= set *text = NULL and return 2 05306 * if the ACL matches st_mode permissions. 05307 * bit5= in case of symbolic link: inquire link target 05308 * bit15= free text and return 1 05309 * @return 05310 * 1 ok 05311 * 2 ok, trivial ACL found while bit4 is set, *text is NULL 05312 * 0 no ACL manipulation adapter available / ACL not supported on fs 05313 * -1 failure of system ACL service (see errno) 05314 * -2 attempt to inquire ACL of a symbolic link without bit4 or bit5 05315 * resp. with no suitable link target 05316 * 05317 * @since 0.6.14 05318 */ 05319 int iso_local_get_acl_text(char *disk_path, char **text, int flag); 05320 05321 05322 /** 05323 * Set the ACL of the given file in the local filesystem to a given list 05324 * in long text form. 05325 * 05326 * @param disk_path 05327 * Absolute path to the file 05328 * @param text 05329 * The input text (0 terminated, ACL long text form) 05330 * @param flag 05331 * Bitfield for control purposes 05332 * bit0= set "default" ACL rather than "access" ACL 05333 * bit5= in case of symbolic link: manipulate link target 05334 * @return 05335 * > 0 ok 05336 * 0 no ACL manipulation adapter available 05337 * -1 failure of system ACL service (see errno) 05338 * -2 attempt to manipulate ACL of a symbolic link without bit5 05339 * resp. with no suitable link target 05340 * 05341 * @since 0.6.14 05342 */ 05343 int iso_local_set_acl_text(char *disk_path, char *text, int flag); 05344 05345 05346 /** 05347 * Obtain permissions of a file in the local filesystem which shall reflect 05348 * ACL entry "group::" in S_IRWXG rather than ACL entry "mask::". This is 05349 * necessary if the permissions of a disk file with ACL shall be copied to 05350 * an object which has no ACL. 05351 * @param disk_path 05352 * Absolute path to the local file which may have an "access" ACL or not. 05353 * @param flag 05354 * Bitfield for control purposes 05355 * bit5= in case of symbolic link: inquire link target 05356 * @param st_mode 05357 * Returns permission bits as of stat(2) 05358 * @return 05359 * 1 success 05360 * -1 failure of lstat() resp. stat() (see errno) 05361 * 05362 * @since 0.6.14 05363 */ 05364 int iso_local_get_perms_wo_acl(char *disk_path, mode_t *st_mode, int flag); 05365 05366 05367 /** 05368 * Get xattr and non-trivial ACLs of the given file in the local filesystem. 05369 * The resulting data has finally to be disposed by a call to this function 05370 * with flag bit15 set. 05371 * 05372 * Eventual ACLs will get encoded as attribute pair with empty name if this is 05373 * enabled by flag bit0. An ACL which simply replects stat(2) permissions 05374 * will not be put into the result. 05375 * 05376 * @param disk_path 05377 * Absolute path to the file 05378 * @param num_attrs 05379 * Will return the number of name-value pairs 05380 * @param names 05381 * Will return an array of pointers to 0-terminated names 05382 * @param value_lengths 05383 * Will return an arry with the lenghts of values 05384 * @param values 05385 * Will return an array of pointers to 8-bit values 05386 * @param flag 05387 * Bitfield for control purposes 05388 * bit0= obtain eventual ACLs as attribute with empty name 05389 * bit2= do not obtain attributes other than ACLs 05390 * bit3= do not ignore eventual non-user attributes. 05391 * I.e. those with a name which does not begin by "user." 05392 * bit5= in case of symbolic link: inquire link target 05393 * bit15= free memory 05394 * @return 05395 * 1 ok 05396 * < 0 failure 05397 * 05398 * @since 0.6.14 05399 */ 05400 int iso_local_get_attrs(char *disk_path, size_t *num_attrs, char ***names, 05401 size_t **value_lengths, char ***values, int flag); 05402 05403 05404 /** 05405 * Attach a list of xattr and ACLs to the given file in the local filesystem. 05406 * 05407 * Eventual ACLs have to be encoded as attribute pair with empty name. 05408 * 05409 * @param disk_path 05410 * Absolute path to the file 05411 * @param num_attrs 05412 * Number of attributes 05413 * @param names 05414 * Array of pointers to 0 terminated name strings 05415 * @param value_lengths 05416 * Array of byte lengths for each attribute payload 05417 * @param values 05418 * Array of pointers to the attribute payload bytes 05419 * @param flag 05420 * Bitfield for control purposes 05421 * bit0= do not attach ACLs from an eventual attribute with empty name 05422 * bit3= do not ignore eventual non-user attributes. 05423 * I.e. those with a name which does not begin by "user." 05424 * bit5= in case of symbolic link: manipulate link target 05425 * @return 05426 * 1 = ok 05427 * < 0 = error 05428 * 05429 * @since 0.6.14 05430 */ 05431 int iso_local_set_attrs(char *disk_path, size_t num_attrs, char **names, 05432 size_t *value_lengths, char **values, int flag); 05433 05434 05435 /* Default in case that the compile environment has no macro PATH_MAX. 05436 */ 05437 #define Libisofs_default_path_maX 4096 05438 05439 05440 /* --------------------------- Filters in General -------------------------- */ 05441 05442 /* 05443 * A filter is an IsoStream which uses another IsoStream as input. It gets 05444 * attached to an IsoFile by specialized calls iso_file_add_*_filter() which 05445 * replace its current IsoStream by the filter stream which takes over the 05446 * current IsoStream as input. 05447 * The consequences are: 05448 * iso_file_get_stream() will return the filter stream. 05449 * iso_stream_get_size() will return the (cached) size of the filtered data, 05450 * iso_stream_open() will start eventual child processes, 05451 * iso_stream_close() will kill eventual child processes, 05452 * iso_stream_read() will return filtered data. E.g. as data file content 05453 * during ISO image generation. 05454 * 05455 * There are external filters which run child processes 05456 * iso_file_add_external_filter() 05457 * and internal filters 05458 * iso_file_add_zisofs_filter() 05459 * iso_file_add_gzip_filter() 05460 * which may or may not be available depending on compile time settings and 05461 * installed software packages like libz. 05462 * 05463 * During image generation filters get not in effect if the original IsoStream 05464 * is an "fsrc" stream based on a file in the loaded ISO image and if the 05465 * image generation type is set to 1 by iso_write_opts_set_appendable(). 05466 */ 05467 05468 /** 05469 * Delete the top filter stream from a data file. This is the most recent one 05470 * which was added by iso_file_add_*_filter(). 05471 * Caution: One should not do this while the IsoStream of the file is opened. 05472 * For now there is no general way to determine this state. 05473 * Filter stream implementations are urged to eventually call .close() 05474 * inside method .free() . This will close the input stream too. 05475 * @param file 05476 * The data file node which shall get rid of one layer of content 05477 * filtering. 05478 * @param flag 05479 * Bitfield for control purposes, unused yet, submit 0. 05480 * @return 05481 * 1 on success, 0 if no filter was present 05482 * <0 on error 05483 * 05484 * @since 0.6.18 05485 */ 05486 int iso_file_remove_filter(IsoFile *file, int flag); 05487 05488 /** 05489 * Obtain the eventual input stream of a filter stream. 05490 * @param stream 05491 * The eventual filter stream to be inquired. 05492 * @param flag 05493 * Bitfield for control purposes. Submit 0 for now. 05494 * @return 05495 * The input stream, if one exists. Elsewise NULL. 05496 * No extra reference to the stream is taken by this call. 05497 * 05498 * @since 0.6.18 05499 */ 05500 IsoStream *iso_stream_get_input_stream(IsoStream *stream, int flag); 05501 05502 05503 /* ---------------------------- External Filters --------------------------- */ 05504 05505 /** 05506 * Representation of an external program that shall serve as filter for 05507 * an IsoStream. This object may be shared among many IsoStream objects. 05508 * It is to be created and disposed by the application. 05509 * 05510 * The filter will act as proxy between the original IsoStream of an IsoFile. 05511 * Up to completed image generation it will be run at least twice: 05512 * for IsoStream.class.get_size() and for .open() with subsequent .read(). 05513 * So the original IsoStream has to return 1 by its .class.is_repeatable(). 05514 * The filter program has to be repeateable too. I.e. it must produce the same 05515 * output on the same input. 05516 * 05517 * @since 0.6.18 05518 */ 05519 struct iso_external_filter_command 05520 { 05521 /* Will indicate future extensions. It has to be 0 for now. */ 05522 int version; 05523 05524 /* Tells how many IsoStream objects depend on this command object. 05525 * One may only dispose an IsoExternalFilterCommand when this count is 0. 05526 * Initially this value has to be 0. 05527 */ 05528 int refcount; 05529 05530 /* An optional instance id. 05531 * Set to empty text if no individual name for this object is intended. 05532 */ 05533 char *name; 05534 05535 /* Absolute local filesystem path to the executable program. */ 05536 char *path; 05537 05538 /* Tells the number of arguments. */ 05539 int argc; 05540 05541 /* NULL terminated list suitable for system call execv(3). 05542 * I.e. argv[0] points to the alleged program name, 05543 * argv[1] to argv[argc] point to program arguments (if argc > 0) 05544 * argv[argc+1] is NULL 05545 */ 05546 char **argv; 05547 05548 /* A bit field which controls behavior variations: 05549 * bit0= Do not install filter if the input has size 0. 05550 * bit1= Do not install filter if the output is not smaller than the input. 05551 * bit2= Do not install filter if the number of output blocks is 05552 * not smaller than the number of input blocks. Block size is 2048. 05553 * Assume that non-empty input yields non-empty output and thus do 05554 * not attempt to attach a filter to files smaller than 2049 bytes. 05555 * bit3= suffix removed rather than added. 05556 * (Removal and adding suffixes is the task of the application. 05557 * This behavior bit serves only as reminder for the application.) 05558 */ 05559 int behavior; 05560 05561 /* The eventual suffix which is supposed to be added to the IsoFile name 05562 * resp. to be removed from the name. 05563 * (This is to be done by the application, not by calls 05564 * iso_file_add_external_filter() or iso_file_remove_filter(). 05565 * The value recorded here serves only as reminder for the application.) 05566 */ 05567 char *suffix; 05568 }; 05569 05570 typedef struct iso_external_filter_command IsoExternalFilterCommand; 05571 05572 /** 05573 * Install an external filter command on top of the content stream of a data 05574 * file. The filter process must be repeatable. It will be run once by this 05575 * call in order to cache the output size. 05576 * @param file 05577 * The data file node which shall show filtered content. 05578 * @param cmd 05579 * The external program and its arguments which shall do the filtering. 05580 * @param flag 05581 * Bitfield for control purposes, unused yet, submit 0. 05582 * @return 05583 * 1 on success, 2 if filter installation revoked (e.g. cmd.behavior bit1) 05584 * <0 on error 05585 * 05586 * @since 0.6.18 05587 */ 05588 int iso_file_add_external_filter(IsoFile *file, IsoExternalFilterCommand *cmd, 05589 int flag); 05590 05591 /** 05592 * Obtain the IsoExternalFilterCommand which is eventually associated with the 05593 * given stream. (Typically obtained from an IsoFile by iso_file_get_stream() 05594 * or from an IsoStream by iso_stream_get_input_stream()). 05595 * @param stream 05596 * The stream to be inquired. 05597 * @param cmd 05598 * Will return the external IsoExternalFilterCommand. Valid only if 05599 * the call returns 1. This does not increment cmd->refcount. 05600 * @param flag 05601 * Bitfield for control purposes, unused yet, submit 0. 05602 * @return 05603 * 1 on success, 0 if the stream is not an external filter 05604 * <0 on error 05605 * 05606 * @since 0.6.18 05607 */ 05608 int iso_stream_get_external_filter(IsoStream *stream, 05609 IsoExternalFilterCommand **cmd, int flag); 05610 05611 05612 /* ---------------------------- Internal Filters --------------------------- */ 05613 05614 05615 /** 05616 * Install a zisofs filter on top of the content stream of a data file. 05617 * zisofs is a compression format which is decompressed by some Linux kernels. 05618 * See also doc/zisofs_format.txt . 05619 * The filter will not be installed if its output size is not smaller than 05620 * the size of the input stream. 05621 * This is only enabled if the use of libz was enabled at compile time. 05622 * @param file 05623 * The data file node which shall show filtered content. 05624 * @param flag 05625 * Bitfield for control purposes 05626 * bit0= Do not install filter if the number of output blocks is 05627 * not smaller than the number of input blocks. Block size is 2048. 05628 * bit1= Install a decompression filter rather than one for compression. 05629 * bit2= Only inquire availability of zisofs filtering. file may be NULL. 05630 * If available return 2, else return error. 05631 * bit3= is reserved for internal use and will be forced to 0 05632 * @return 05633 * 1 on success, 2 if filter available but installation revoked 05634 * <0 on error, e.g. ISO_ZLIB_NOT_ENABLED 05635 * 05636 * @since 0.6.18 05637 */ 05638 int iso_file_add_zisofs_filter(IsoFile *file, int flag); 05639 05640 /** 05641 * Inquire the number of zisofs compression and uncompression filters which 05642 * are in use. 05643 * @param ziso_count 05644 * Will return the number of currently installed compression filters. 05645 * @param osiz_count 05646 * Will return the number of currently installed uncompression filters. 05647 * @param flag 05648 * Bitfield for control purposes, unused yet, submit 0 05649 * @return 05650 * 1 on success, <0 on error 05651 * 05652 * @since 0.6.18 05653 */ 05654 int iso_zisofs_get_refcounts(off_t *ziso_count, off_t *osiz_count, int flag); 05655 05656 05657 /** 05658 * Parameter set for iso_zisofs_set_params(). 05659 * 05660 * @since 0.6.18 05661 */ 05662 struct iso_zisofs_ctrl { 05663 05664 /* Set to 0 for this version of the structure */ 05665 int version; 05666 05667 /* Compression level for zlib function compress2(). From <zlib.h>: 05668 * "between 0 and 9: 05669 * 1 gives best speed, 9 gives best compression, 0 gives no compression" 05670 * Default is 6. 05671 */ 05672 int compression_level; 05673 05674 /* Log2 of the block size for compression filters. Allowed values are: 05675 * 15 = 32 kiB , 16 = 64 kiB , 17 = 128 kiB 05676 */ 05677 uint8_t block_size_log2; 05678 05679 }; 05680 05681 /** 05682 * Set the global parameters for zisofs filtering. 05683 * This is only allowed while no zisofs compression filters are installed. 05684 * i.e. ziso_count returned by iso_zisofs_get_refcounts() has to be 0. 05685 * @param params 05686 * Pointer to a structure with the intended settings. 05687 * @param flag 05688 * Bitfield for control purposes, unused yet, submit 0 05689 * @return 05690 * 1 on success, <0 on error 05691 * 05692 * @since 0.6.18 05693 */ 05694 int iso_zisofs_set_params(struct iso_zisofs_ctrl *params, int flag); 05695 05696 /** 05697 * Get the current global parameters for zisofs filtering. 05698 * @param params 05699 * Pointer to a caller provided structure which shall take the settings. 05700 * @param flag 05701 * Bitfield for control purposes, unused yet, submit 0 05702 * @return 05703 * 1 on success, <0 on error 05704 * 05705 * @since 0.6.18 05706 */ 05707 int iso_zisofs_get_params(struct iso_zisofs_ctrl *params, int flag); 05708 05709 05710 /** 05711 * Check for the given node or for its subtree whether the data file content 05712 * effectively bears zisofs file headers and eventually mark the outcome 05713 * by an xinfo data record if not already marked by a zisofs compressor filter. 05714 * This does not install any filter but only a hint for image generation 05715 * that the already compressed files shall get written with zisofs ZF entries. 05716 * Use this if you insert the compressed reults of program mkzftree from disk 05717 * into the image. 05718 * @param node 05719 * The node which shall be checked and eventually marked. 05720 * @param flag 05721 * Bitfield for control purposes, unused yet, submit 0 05722 * bit0= prepare for a run with iso_write_opts_set_appendable(,1). 05723 * Take into account that files from the imported image 05724 * do not get their content filtered. 05725 * bit1= permission to overwrite existing zisofs_zf_info 05726 * bit2= if no zisofs header is found: 05727 * create xinfo with parameters which indicate no zisofs 05728 * bit3= no tree recursion if node is a directory 05729 * bit4= skip files which stem from the imported image 05730 * @return 05731 * 0= no zisofs data found 05732 * 1= zf xinfo added 05733 * 2= found existing zf xinfo and flag bit1 was not set 05734 * 3= both encountered: 1 and 2 05735 * <0 means error 05736 * 05737 * @since 0.6.18 05738 */ 05739 int iso_node_zf_by_magic(IsoNode *node, int flag); 05740 05741 05742 /** 05743 * Install a gzip or gunzip filter on top of the content stream of a data file. 05744 * gzip is a compression format which is used by programs gzip and gunzip. 05745 * The filter will not be installed if its output size is not smaller than 05746 * the size of the input stream. 05747 * This is only enabled if the use of libz was enabled at compile time. 05748 * @param file 05749 * The data file node which shall show filtered content. 05750 * @param flag 05751 * Bitfield for control purposes 05752 * bit0= Do not install filter if the number of output blocks is 05753 * not smaller than the number of input blocks. Block size is 2048. 05754 * bit1= Install a decompression filter rather than one for compression. 05755 * bit2= Only inquire availability of gzip filtering. file may be NULL. 05756 * If available return 2, else return error. 05757 * bit3= is reserved for internal use and will be forced to 0 05758 * @return 05759 * 1 on success, 2 if filter available but installation revoked 05760 * <0 on error, e.g. ISO_ZLIB_NOT_ENABLED 05761 * 05762 * @since 0.6.18 05763 */ 05764 int iso_file_add_gzip_filter(IsoFile *file, int flag); 05765 05766 05767 /** 05768 * Inquire the number of gzip compression and uncompression filters which 05769 * are in use. 05770 * @param gzip_count 05771 * Will return the number of currently installed compression filters. 05772 * @param gunzip_count 05773 * Will return the number of currently installed uncompression filters. 05774 * @param flag 05775 * Bitfield for control purposes, unused yet, submit 0 05776 * @return 05777 * 1 on success, <0 on error 05778 * 05779 * @since 0.6.18 05780 */ 05781 int iso_gzip_get_refcounts(off_t *gzip_count, off_t *gunzip_count, int flag); 05782 05783 05784 /* ---------------------------- MD5 Checksums --------------------------- */ 05785 05786 /* Production and loading of MD5 checksums is controlled by calls 05787 iso_write_opts_set_record_md5() and iso_read_opts_set_no_md5(). 05788 For data representation details see doc/checksums.txt . 05789 */ 05790 05791 /** 05792 * Eventually obtain the recorded MD5 checksum of the session which was 05793 * loaded as ISO image. Such a checksum may be stored together with others 05794 * in a contiguous array at the end of the session. The session checksum 05795 * covers the data blocks from address start_lba to address end_lba - 1. 05796 * It does not cover the recorded array of md5 checksums. 05797 * Layout, size, and position of the checksum array is recorded in the xattr 05798 * "isofs.ca" of the session root node. 05799 * @param image 05800 * The image to inquire 05801 * @param start_lba 05802 * Eventually returns the first block address covered by md5 05803 * @param end_lba 05804 * Eventually returns the first block address not covered by md5 any more 05805 * @param md5 05806 * Eventually returns 16 byte of MD5 checksum 05807 * @param flag 05808 * Bitfield for control purposes, unused yet, submit 0 05809 * @return 05810 * 1= md5 found , 0= no md5 available , <0 indicates error 05811 * 05812 * @since 0.6.22 05813 */ 05814 int iso_image_get_session_md5(IsoImage *image, uint32_t *start_lba, 05815 uint32_t *end_lba, char md5[16], int flag); 05816 05817 /** 05818 * Eventually obtain the recorded MD5 checksum of a data file from the loaded 05819 * ISO image. Such a checksum may be stored with others in a contiguous 05820 * array at the end of the loaded session. The data file eventually has an 05821 * xattr "isofs.cx" which gives the index in that array. 05822 * @param image 05823 * The image from which file stems. 05824 * @param file 05825 * The file object to inquire 05826 * @param md5 05827 * Eventually returns 16 byte of MD5 checksum 05828 * @param flag 05829 * Bitfield for control purposes 05830 * bit0= only determine return value, do not touch parameter md5 05831 * @return 05832 * 1= md5 found , 0= no md5 available , <0 indicates error 05833 * 05834 * @since 0.6.22 05835 */ 05836 int iso_file_get_md5(IsoImage *image, IsoFile *file, char md5[16], int flag); 05837 05838 /** 05839 * Read the content of an IsoFile object, compute its MD5 and attach it to 05840 * the IsoFile. It can then be inquired by iso_file_get_md5() and will get 05841 * written into the next session if this is enabled at write time and if the 05842 * image write process does not compute an MD5 from content which it copies. 05843 * So this call can be used to equip nodes from the old image with checksums 05844 * or to make available checksums of newly added files before the session gets 05845 * written. 05846 * @param file 05847 * The file object to read data from and to which to attach the checksum. 05848 * If the file is from the imported image, then its most original stream 05849 * will be checksummed. Else the eventual filter streams will get into 05850 * effect. 05851 * @param flag 05852 * Bitfield for control purposes. Unused yet. Submit 0. 05853 * @return 05854 * 1= ok, MD5 is computed and attached , <0 indicates error 05855 * 05856 * @since 0.6.22 05857 */ 05858 int iso_file_make_md5(IsoFile *file, int flag); 05859 05860 /** 05861 * Check a data block whether it is a libisofs session checksum tag and 05862 * eventually obtain its recorded parameters. These tags get written after 05863 * volume descriptors, directory tree and checksum array and can be detected 05864 * without loading the image tree. 05865 * One may start reading and computing MD5 at the suspected image session 05866 * start and look out for a session tag on the fly. See doc/checksum.txt . 05867 * @param data 05868 * A complete and aligned data block read from an ISO image session. 05869 * @param tag_type 05870 * 0= no tag 05871 * 1= session tag 05872 * 2= superblock tag 05873 * 3= tree tag 05874 * 4= relocated 64 kB superblock tag (at LBA 0 of overwriteable media) 05875 * @param pos 05876 * Returns the LBA where the tag supposes itself to be stored. 05877 * If this does not match the data block LBA then the tag might be 05878 * image data payload and should be ignored for image checksumming. 05879 * @param range_start 05880 * Returns the block address where the session is supposed to start. 05881 * If this does not match the session start on media then the image 05882 * volume descriptors have been been relocated. 05883 * A proper checksum will only emerge if computing started at range_start. 05884 * @param range_size 05885 * Returns the number of blocks beginning at range_start which are 05886 * covered by parameter md5. 05887 * @param next_tag 05888 * Returns the predicted block address of the next tag. 05889 * next_tag is valid only if not 0 and only with return values 2, 3, 4. 05890 * With tag types 2 and 3, reading shall go on sequentially and the MD5 05891 * computation shall continue up to that address. 05892 * With tag type 4, reading shall resume either at LBA 32 for the first 05893 * session or at the given address for the session which is to be loaded 05894 * by default. In both cases the MD5 computation shall be re-started from 05895 * scratch. 05896 * @param md5 05897 * Returns 16 byte of MD5 checksum. 05898 * @param flag 05899 * Bitfield for control purposes: 05900 * bit0-bit7= tag type being looked for 05901 * 0= any checksum tag 05902 * 1= session tag 05903 * 2= superblock tag 05904 * 3= tree tag 05905 * 4= relocated superblock tag 05906 * @return 05907 * 0= not a checksum tag, return parameters are invalid 05908 * 1= checksum tag found, return parameters are valid 05909 * <0= error 05910 * (return parameters are valid with error ISO_MD5_AREA_CORRUPTED 05911 * but not trustworthy because the tag seems corrupted) 05912 * 05913 * @since 0.6.22 05914 */ 05915 int iso_util_decode_md5_tag(char data[2048], int *tag_type, uint32_t *pos, 05916 uint32_t *range_start, uint32_t *range_size, 05917 uint32_t *next_tag, char md5[16], int flag); 05918 05919 05920 /* The following functions allow to do own MD5 computations. E.g for 05921 comparing the result with a recorded checksum. 05922 */ 05923 /** 05924 * Create a MD5 computation context and hand out an opaque handle. 05925 * 05926 * @param md5_context 05927 * Returns the opaque handle. Submitted *md5_context must be NULL or 05928 * point to freeable memory. 05929 * @return 05930 * 1= success , <0 indicates error 05931 * 05932 * @since 0.6.22 05933 */ 05934 int iso_md5_start(void **md5_context); 05935 05936 /** 05937 * Advance the computation of a MD5 checksum by a chunk of data bytes. 05938 * 05939 * @param md5_context 05940 * An opaque handle once returned by iso_md5_start() or iso_md5_clone(). 05941 * @param data 05942 * The bytes which shall be processed into to the checksum. 05943 * @param datalen 05944 * The number of bytes to be processed. 05945 * @return 05946 * 1= success , <0 indicates error 05947 * 05948 * @since 0.6.22 05949 */ 05950 int iso_md5_compute(void *md5_context, char *data, int datalen); 05951 05952 /** 05953 * Create a MD5 computation context as clone of an existing one. One may call 05954 * iso_md5_clone(old, &new, 0) and then iso_md5_end(&new, result, 0) in order 05955 * to obtain an intermediate MD5 sum before the computation goes on. 05956 * 05957 * @param old_md5_context 05958 * An opaque handle once returned by iso_md5_start() or iso_md5_clone(). 05959 * @param new_md5_context 05960 * Returns the opaque handle to the new MD5 context. Submitted 05961 * *md5_context must be NULL or point to freeable memory. 05962 * @return 05963 * 1= success , <0 indicates error 05964 * 05965 * @since 0.6.22 05966 */ 05967 int iso_md5_clone(void *old_md5_context, void **new_md5_context); 05968 05969 /** 05970 * Obtain the MD5 checksum from a MD5 computation context and dispose this 05971 * context. (If you want to keep the context then call iso_md5_clone() and 05972 * apply iso_md5_end() to the clone.) 05973 * 05974 * @param md5_context 05975 * A pointer to an opaque handle once returned by iso_md5_start() or 05976 * iso_md5_clone(). *md5_context will be set to NULL in this call. 05977 * @param result 05978 * Gets filled with the 16 bytes of MD5 checksum. 05979 * @return 05980 * 1= success , <0 indicates error 05981 * 05982 * @since 0.6.22 05983 */ 05984 int iso_md5_end(void **md5_context, char result[16]); 05985 05986 /** 05987 * Inquire whether two MD5 checksums match. (This is trivial but such a call 05988 * is convenient and completes the interface.) 05989 * @param first_md5 05990 * A MD5 byte string as returned by iso_md5_end() 05991 * @param second_md5 05992 * A MD5 byte string as returned by iso_md5_end() 05993 * @return 05994 * 1= match , 0= mismatch 05995 * 05996 * @since 0.6.22 05997 */ 05998 int iso_md5_match(char first_md5[16], char second_md5[16]); 05999 06000 06001 /************ Error codes and return values for libisofs ********************/ 06002 06003 /** successfully execution */ 06004 #define ISO_SUCCESS 1 06005 06006 /** 06007 * special return value, it could be or not an error depending on the 06008 * context. 06009 */ 06010 #define ISO_NONE 0 06011 06012 /** Operation canceled (FAILURE,HIGH, -1) */ 06013 #define ISO_CANCELED 0xE830FFFF 06014 06015 /** Unknown or unexpected fatal error (FATAL,HIGH, -2) */ 06016 #define ISO_FATAL_ERROR 0xF030FFFE 06017 06018 /** Unknown or unexpected error (FAILURE,HIGH, -3) */ 06019 #define ISO_ERROR 0xE830FFFD 06020 06021 /** Internal programming error. Please report this bug (FATAL,HIGH, -4) */ 06022 #define ISO_ASSERT_FAILURE 0xF030FFFC 06023 06024 /** 06025 * NULL pointer as value for an arg. that doesn't allow NULL (FAILURE,HIGH, -5) 06026 */ 06027 #define ISO_NULL_POINTER 0xE830FFFB 06028 06029 /** Memory allocation error (FATAL,HIGH, -6) */ 06030 #define ISO_OUT_OF_MEM 0xF030FFFA 06031 06032 /** Interrupted by a signal (FATAL,HIGH, -7) */ 06033 #define ISO_INTERRUPTED 0xF030FFF9 06034 06035 /** Invalid parameter value (FAILURE,HIGH, -8) */ 06036 #define ISO_WRONG_ARG_VALUE 0xE830FFF8 06037 06038 /** Can't create a needed thread (FATAL,HIGH, -9) */ 06039 #define ISO_THREAD_ERROR 0xF030FFF7 06040 06041 /** Write error (FAILURE,HIGH, -10) */ 06042 #define ISO_WRITE_ERROR 0xE830FFF6 06043 06044 /** Buffer read error (FAILURE,HIGH, -11) */ 06045 #define ISO_BUF_READ_ERROR 0xE830FFF5 06046 06047 /** Trying to add to a dir a node already added to a dir (FAILURE,HIGH, -64) */ 06048 #define ISO_NODE_ALREADY_ADDED 0xE830FFC0 06049 06050 /** Node with same name already exists (FAILURE,HIGH, -65) */ 06051 #define ISO_NODE_NAME_NOT_UNIQUE 0xE830FFBF 06052 06053 /** Trying to remove a node that was not added to dir (FAILURE,HIGH, -65) */ 06054 #define ISO_NODE_NOT_ADDED_TO_DIR 0xE830FFBE 06055 06056 /** A requested node does not exist (FAILURE,HIGH, -66) */ 06057 #define ISO_NODE_DOESNT_EXIST 0xE830FFBD 06058 06059 /** 06060 * Try to set the boot image of an already bootable image (FAILURE,HIGH, -67) 06061 */ 06062 #define ISO_IMAGE_ALREADY_BOOTABLE 0xE830FFBC 06063 06064 /** Trying to use an invalid file as boot image (FAILURE,HIGH, -68) */ 06065 #define ISO_BOOT_IMAGE_NOT_VALID 0xE830FFBB 06066 06067 /** Too many boot images (FAILURE,HIGH, -69) */ 06068 #define ISO_BOOT_IMAGE_OVERFLOW 0xE830FFBA 06069 06070 /** No boot catalog created yet ((FAILURE,HIGH, -70) */ /* @since 0.6.34 */ 06071 #define ISO_BOOT_NO_CATALOG 0xE830FFB9 06072 06073 06074 /** 06075 * Error on file operation (FAILURE,HIGH, -128) 06076 * (take a look at more specified error codes below) 06077 */ 06078 #define ISO_FILE_ERROR 0xE830FF80 06079 06080 /** Trying to open an already opened file (FAILURE,HIGH, -129) */ 06081 #define ISO_FILE_ALREADY_OPENED 0xE830FF7F 06082 06083 /* @deprecated use ISO_FILE_ALREADY_OPENED instead */ 06084 #define ISO_FILE_ALREADY_OPENNED 0xE830FF7F 06085 06086 /** Access to file is not allowed (FAILURE,HIGH, -130) */ 06087 #define ISO_FILE_ACCESS_DENIED 0xE830FF7E 06088 06089 /** Incorrect path to file (FAILURE,HIGH, -131) */ 06090 #define ISO_FILE_BAD_PATH 0xE830FF7D 06091 06092 /** The file does not exist in the filesystem (FAILURE,HIGH, -132) */ 06093 #define ISO_FILE_DOESNT_EXIST 0xE830FF7C 06094 06095 /** Trying to read or close a file not openned (FAILURE,HIGH, -133) */ 06096 #define ISO_FILE_NOT_OPENED 0xE830FF7B 06097 06098 /* @deprecated use ISO_FILE_NOT_OPENED instead */ 06099 #define ISO_FILE_NOT_OPENNED ISO_FILE_NOT_OPENED 06100 06101 /** Directory used where no dir is expected (FAILURE,HIGH, -134) */ 06102 #define ISO_FILE_IS_DIR 0xE830FF7A 06103 06104 /** Read error (FAILURE,HIGH, -135) */ 06105 #define ISO_FILE_READ_ERROR 0xE830FF79 06106 06107 /** Not dir used where a dir is expected (FAILURE,HIGH, -136) */ 06108 #define ISO_FILE_IS_NOT_DIR 0xE830FF78 06109 06110 /** Not symlink used where a symlink is expected (FAILURE,HIGH, -137) */ 06111 #define ISO_FILE_IS_NOT_SYMLINK 0xE830FF77 06112 06113 /** Can't seek to specified location (FAILURE,HIGH, -138) */ 06114 #define ISO_FILE_SEEK_ERROR 0xE830FF76 06115 06116 /** File not supported in ECMA-119 tree and thus ignored (WARNING,MEDIUM, -139) */ 06117 #define ISO_FILE_IGNORED 0xD020FF75 06118 06119 /* A file is bigger than supported by used standard (WARNING,MEDIUM, -140) */ 06120 #define ISO_FILE_TOO_BIG 0xD020FF74 06121 06122 /* File read error during image creation (MISHAP,HIGH, -141) */ 06123 #define ISO_FILE_CANT_WRITE 0xE430FF73 06124 06125 /* Can't convert filename to requested charset (WARNING,MEDIUM, -142) */ 06126 #define ISO_FILENAME_WRONG_CHARSET 0xD020FF72 06127 /* This was once a HINT. Deprecated now. */ 06128 #define ISO_FILENAME_WRONG_CHARSET_OLD 0xC020FF72 06129 06130 /* File can't be added to the tree (SORRY,HIGH, -143) */ 06131 #define ISO_FILE_CANT_ADD 0xE030FF71 06132 06133 /** 06134 * File path break specification constraints and will be ignored 06135 * (WARNING,MEDIUM, -144) 06136 */ 06137 #define ISO_FILE_IMGPATH_WRONG 0xD020FF70 06138 06139 /** 06140 * Offset greater than file size (FAILURE,HIGH, -150) 06141 * @since 0.6.4 06142 */ 06143 #define ISO_FILE_OFFSET_TOO_BIG 0xE830FF6A 06144 06145 06146 /** Charset conversion error (FAILURE,HIGH, -256) */ 06147 #define ISO_CHARSET_CONV_ERROR 0xE830FF00 06148 06149 /** 06150 * Too many files to mangle, i.e. we cannot guarantee unique file names 06151 * (FAILURE,HIGH, -257) 06152 */ 06153 #define ISO_MANGLE_TOO_MUCH_FILES 0xE830FEFF 06154 06155 /* image related errors */ 06156 06157 /** 06158 * Wrong or damaged Primary Volume Descriptor (FAILURE,HIGH, -320) 06159 * This could mean that the file is not a valid ISO image. 06160 */ 06161 #define ISO_WRONG_PVD 0xE830FEC0 06162 06163 /** Wrong or damaged RR entry (SORRY,HIGH, -321) */ 06164 #define ISO_WRONG_RR 0xE030FEBF 06165 06166 /** Unsupported RR feature (SORRY,HIGH, -322) */ 06167 #define ISO_UNSUPPORTED_RR 0xE030FEBE 06168 06169 /** Wrong or damaged ECMA-119 (FAILURE,HIGH, -323) */ 06170 #define ISO_WRONG_ECMA119 0xE830FEBD 06171 06172 /** Unsupported ECMA-119 feature (FAILURE,HIGH, -324) */ 06173 #define ISO_UNSUPPORTED_ECMA119 0xE830FEBC 06174 06175 /** Wrong or damaged El-Torito catalog (WARN,HIGH, -325) */ 06176 #define ISO_WRONG_EL_TORITO 0xD030FEBB 06177 06178 /** Unsupported El-Torito feature (WARN,HIGH, -326) */ 06179 #define ISO_UNSUPPORTED_EL_TORITO 0xD030FEBA 06180 06181 /** Can't patch an isolinux boot image (SORRY,HIGH, -327) */ 06182 #define ISO_ISOLINUX_CANT_PATCH 0xE030FEB9 06183 06184 /** Unsupported SUSP feature (SORRY,HIGH, -328) */ 06185 #define ISO_UNSUPPORTED_SUSP 0xE030FEB8 06186 06187 /** Error on a RR entry that can be ignored (WARNING,HIGH, -329) */ 06188 #define ISO_WRONG_RR_WARN 0xD030FEB7 06189 06190 /** Error on a RR entry that can be ignored (HINT,MEDIUM, -330) */ 06191 #define ISO_SUSP_UNHANDLED 0xC020FEB6 06192 06193 /** Multiple ER SUSP entries found (WARNING,HIGH, -331) */ 06194 #define ISO_SUSP_MULTIPLE_ER 0xD030FEB5 06195 06196 /** Unsupported volume descriptor found (HINT,MEDIUM, -332) */ 06197 #define ISO_UNSUPPORTED_VD 0xC020FEB4 06198 06199 /** El-Torito related warning (WARNING,HIGH, -333) */ 06200 #define ISO_EL_TORITO_WARN 0xD030FEB3 06201 06202 /** Image write cancelled (MISHAP,HIGH, -334) */ 06203 #define ISO_IMAGE_WRITE_CANCELED 0xE430FEB2 06204 06205 /** El-Torito image is hidden (WARNING,HIGH, -335) */ 06206 #define ISO_EL_TORITO_HIDDEN 0xD030FEB1 06207 06208 06209 /** AAIP info with ACL or xattr in ISO image will be ignored 06210 (NOTE, HIGH, -336) */ 06211 #define ISO_AAIP_IGNORED 0xB030FEB0 06212 06213 /** Error with decoding ACL from AAIP info (FAILURE, HIGH, -337) */ 06214 #define ISO_AAIP_BAD_ACL 0xE830FEAF 06215 06216 /** Error with encoding ACL for AAIP (FAILURE, HIGH, -338) */ 06217 #define ISO_AAIP_BAD_ACL_TEXT 0xE830FEAE 06218 06219 /** AAIP processing for ACL or xattr not enabled at compile time 06220 (FAILURE, HIGH, -339) */ 06221 #define ISO_AAIP_NOT_ENABLED 0xE830FEAD 06222 06223 /** Error with decoding AAIP info for ACL or xattr (FAILURE, HIGH, -340) */ 06224 #define ISO_AAIP_BAD_AASTRING 0xE830FEAC 06225 06226 /** Error with reading ACL or xattr from local file (FAILURE, HIGH, -341) */ 06227 #define ISO_AAIP_NO_GET_LOCAL 0xE830FEAB 06228 06229 /** Error with attaching ACL or xattr to local file (FAILURE, HIGH, -342) */ 06230 #define ISO_AAIP_NO_SET_LOCAL 0xE830FEAA 06231 06232 /** Unallowed attempt to set an xattr with non-userspace name 06233 (FAILURE, HIGH, -343) */ 06234 #define ISO_AAIP_NON_USER_NAME 0xE830FEA9 06235 06236 06237 /** Too many references on a single IsoExternalFilterCommand 06238 (FAILURE, HIGH, -344) */ 06239 #define ISO_EXTF_TOO_OFTEN 0xE830FEA8 06240 06241 /** Use of zlib was not enabled at compile time (FAILURE, HIGH, -345) */ 06242 #define ISO_ZLIB_NOT_ENABLED 0xE830FEA7 06243 06244 /** Cannot apply zisofs filter to file >= 4 GiB (FAILURE, HIGH, -346) */ 06245 #define ISO_ZISOFS_TOO_LARGE 0xE830FEA6 06246 06247 /** Filter input differs from previous run (FAILURE, HIGH, -347) */ 06248 #define ISO_FILTER_WRONG_INPUT 0xE830FEA5 06249 06250 /** zlib compression/decompression error (FAILURE, HIGH, -348) */ 06251 #define ISO_ZLIB_COMPR_ERR 0xE830FEA4 06252 06253 /** Input stream is not in zisofs format (FAILURE, HIGH, -349) */ 06254 #define ISO_ZISOFS_WRONG_INPUT 0xE830FEA3 06255 06256 /** Cannot set global zisofs parameters while filters exist 06257 (FAILURE, HIGH, -350) */ 06258 #define ISO_ZISOFS_PARAM_LOCK 0xE830FEA2 06259 06260 /** Premature EOF of zlib input stream (FAILURE, HIGH, -351) */ 06261 #define ISO_ZLIB_EARLY_EOF 0xE830FEA1 06262 06263 /** 06264 * Checksum area or checksum tag appear corrupted (WARNING,HIGH, -352) 06265 * @since 0.6.22 06266 */ 06267 #define ISO_MD5_AREA_CORRUPTED 0xD030FEA0 06268 06269 /** 06270 * Checksum mismatch between checksum tag and data blocks 06271 * (FAILURE, HIGH, -353) 06272 * @since 0.6.22 06273 */ 06274 #define ISO_MD5_TAG_MISMATCH 0xE830FE9F 06275 06276 /** 06277 * Checksum mismatch in System Area, Volume Descriptors, or directory tree. 06278 * (FAILURE, HIGH, -354) 06279 * @since 0.6.22 06280 */ 06281 #define ISO_SB_TREE_CORRUPTED 0xE830FE9E 06282 06283 /** 06284 * Unexpected checksum tag type encountered. (WARNING, HIGH, -355) 06285 * @since 0.6.22 06286 */ 06287 #define ISO_MD5_TAG_UNEXPECTED 0xD030FE9D 06288 06289 /** 06290 * Misplaced checksum tag encountered. (WARNING, HIGH, -356) 06291 * @since 0.6.22 06292 */ 06293 #define ISO_MD5_TAG_MISPLACED 0xD030FE9C 06294 06295 /** 06296 * Checksum tag with unexpected address range encountered. 06297 * (WARNING, HIGH, -357) 06298 * @since 0.6.22 06299 */ 06300 #define ISO_MD5_TAG_OTHER_RANGE 0xD030FE9B 06301 06302 /** 06303 * Detected file content changes while it was written into the image. 06304 * (MISHAP, HIGH, -358) 06305 * @since 0.6.22 06306 */ 06307 #define ISO_MD5_STREAM_CHANGE 0xE430FE9A 06308 06309 /** 06310 * Session does not start at LBA 0. scdbackup checksum tag not written. 06311 * (WARNING, HIGH, -359) 06312 * @since 0.6.24 06313 */ 06314 #define ISO_SCDBACKUP_TAG_NOT_0 0xD030FE99 06315 06316 /** 06317 * The setting of iso_write_opts_set_ms_block() leaves not enough room 06318 * for the prescibed size of iso_write_opts_set_overwrite_buf(). 06319 * (FAILURE, HIGH, -360) 06320 * @since 0.6.36 06321 */ 06322 #define ISO_OVWRT_MS_TOO_SMALL 0xE830FE98 06323 06324 /** 06325 * The partition offset is not 0 and leaves not not enough room for 06326 * system area, volume descriptors, and checksum tags of the first tree. 06327 * (FAILURE, HIGH, -361) 06328 */ 06329 #define ISO_PART_OFFST_TOO_SMALL 0xE830FE97 06330 06331 /** 06332 * The ring buffer is smaller than 64 kB + partition offset. 06333 * (FAILURE, HIGH, -362) 06334 */ 06335 #define ISO_OVWRT_FIFO_TOO_SMALL 0xE830FE96 06336 06337 /** Use of libjte was not enabled at compile time (FAILURE, HIGH, -363) */ 06338 #define ISO_LIBJTE_NOT_ENABLED 0xE830FE95 06339 06340 /** Failed to start up Jigdo Template Extraction (FAILURE, HIGH, -364) */ 06341 #define ISO_LIBJTE_START_FAILED 0xE830FE94 06342 06343 /** Failed to finish Jigdo Template Extraction (FAILURE, HIGH, -365) */ 06344 #define ISO_LIBJTE_END_FAILED 0xE830FE93 06345 06346 /** Failed to process file for Jigdo Template Extraction 06347 (MISHAP, HIGH, -366) */ 06348 #define ISO_LIBJTE_FILE_FAILED 0xE430FE92 06349 06350 /** Too many MIPS Big Endian boot files given (max. 15) (FAILURE, HIGH, -367)*/ 06351 #define ISO_BOOT_TOO_MANY_MIPS 0xE830FE91 06352 06353 /** Boot file missing in image (MISHAP, HIGH, -368) */ 06354 #define ISO_BOOT_FILE_MISSING 0xE430FE90 06355 06356 /** Partition number out of range (FAILURE, HIGH, -369) */ 06357 #define ISO_BAD_PARTITION_NO 0xE830FE8F 06358 06359 /** Cannot open data file for appended partition (FAILURE, HIGH, -370) */ 06360 #define ISO_BAD_PARTITION_FILE 0xE830FE8E 06361 06362 /** May not combine appended partition with non-MBR system area 06363 (FAILURE, HIGH, -371) */ 06364 #define ISO_NON_MBR_SYS_AREA 0xE830FE8D 06365 06366 06367 /* Internal developer note: 06368 Place new error codes directly above this comment. 06369 Newly introduced errors must get a message entry in 06370 libisofs/message.c, function iso_error_to_msg() 06371 */ 06372 06373 /* ! PLACE NEW ERROR CODES ABOVE. NOT AFTER THIS LINE ! */ 06374 06375 06376 /** Read error occured with IsoDataSource (SORRY,HIGH, -513) */ 06377 #define ISO_DATA_SOURCE_SORRY 0xE030FCFF 06378 06379 /** Read error occured with IsoDataSource (MISHAP,HIGH, -513) */ 06380 #define ISO_DATA_SOURCE_MISHAP 0xE430FCFF 06381 06382 /** Read error occured with IsoDataSource (FAILURE,HIGH, -513) */ 06383 #define ISO_DATA_SOURCE_FAILURE 0xE830FCFF 06384 06385 /** Read error occured with IsoDataSource (FATAL,HIGH, -513) */ 06386 #define ISO_DATA_SOURCE_FATAL 0xF030FCFF 06387 06388 06389 /* ! PLACE NEW ERROR CODES SEVERAL LINES ABOVE. NOT HERE ! */ 06390 06391 06392 /* ------------------------------------------------------------------------- */ 06393 06394 #ifdef LIBISOFS_WITHOUT_LIBBURN 06395 06396 /** 06397 This is a copy from the API of libburn-0.6.0 (under GPL). 06398 It is supposed to be as stable as any overall include of libburn.h. 06399 I.e. if this definition is out of sync then you cannot rely on any 06400 contract that was made with libburn.h. 06401 06402 Libisofs does not need to be linked with libburn at all. But if it is 06403 linked with libburn then it must be libburn-0.4.2 or later. 06404 06405 An application that provides own struct burn_source objects and does not 06406 include libburn/libburn.h has to define LIBISOFS_WITHOUT_LIBBURN before 06407 including libisofs/libisofs.h in order to make this copy available. 06408 */ 06409 06410 06411 /** Data source interface for tracks. 06412 This allows to use arbitrary program code as provider of track input data. 06413 06414 Objects compliant to this interface are either provided by the application 06415 or by API calls of libburn: burn_fd_source_new() , burn_file_source_new(), 06416 and burn_fifo_source_new(). 06417 06418 The API calls allow to use any file object as data source. Consider to feed 06419 an eventual custom data stream asynchronously into a pipe(2) and to let 06420 libburn handle the rest. 06421 In this case the following rule applies: 06422 Call burn_source_free() exactly once for every source obtained from 06423 libburn API. You MUST NOT otherwise use or manipulate its components. 06424 06425 In general, burn_source objects can be freed as soon as they are attached 06426 to track objects. The track objects will keep them alive and dispose them 06427 when they are no longer needed. With a fifo burn_source it makes sense to 06428 keep the own reference for inquiring its state while burning is in 06429 progress. 06430 06431 --- 06432 06433 The following description of burn_source applies only to application 06434 implemented burn_source objects. You need not to know it for API provided 06435 ones. 06436 06437 If you really implement an own passive data producer by this interface, 06438 then beware: it can do anything and it can spoil everything. 06439 06440 In this case the functions (*read), (*get_size), (*set_size), (*free_data) 06441 MUST be implemented by the application and attached to the object at 06442 creation time. 06443 Function (*read_sub) is allowed to be NULL or it MUST be implemented and 06444 attached. 06445 06446 burn_source.refcount MUST be handled properly: If not exactly as many 06447 references are freed as have been obtained, then either memory leaks or 06448 corrupted memory are the consequence. 06449 All objects which are referred to by *data must be kept existent until 06450 (*free_data) is called via burn_source_free() by the last referer. 06451 */ 06452 struct burn_source { 06453 06454 /** Reference count for the data source. MUST be 1 when a new source 06455 is created and thus the first reference is handed out. Increment 06456 it to take more references for yourself. Use burn_source_free() 06457 to destroy your references to it. */ 06458 int refcount; 06459 06460 06461 /** Read data from the source. Semantics like with read(2), but MUST 06462 either deliver the full buffer as defined by size or MUST deliver 06463 EOF (return 0) or failure (return -1) at this call or at the 06464 next following call. I.e. the only incomplete buffer may be the 06465 last one from that source. 06466 libburn will read a single sector by each call to (*read). 06467 The size of a sector depends on BURN_MODE_*. The known range is 06468 2048 to 2352. 06469 06470 If this call is reading from a pipe then it will learn 06471 about the end of data only when that pipe gets closed on the 06472 feeder side. So if the track size is not fixed or if the pipe 06473 delivers less than the predicted amount or if the size is not 06474 block aligned, then burning will halt until the input process 06475 closes the pipe. 06476 06477 IMPORTANT: 06478 If this function pointer is NULL, then the struct burn_source is of 06479 version >= 1 and the job of .(*read)() is done by .(*read_xt)(). 06480 See below, member .version. 06481 */ 06482 int (*read)(struct burn_source *, unsigned char *buffer, int size); 06483 06484 06485 /** Read subchannel data from the source (NULL if lib generated) 06486 WARNING: This is an obscure feature with CD raw write modes. 06487 Unless you checked the libburn code for correctness in that aspect 06488 you should not rely on raw writing with own subchannels. 06489 ADVICE: Set this pointer to NULL. 06490 */ 06491 int (*read_sub)(struct burn_source *, unsigned char *buffer, int size); 06492 06493 06494 /** Get the size of the source's data. Return 0 means unpredictable 06495 size. If application provided (*get_size) allows return 0, then 06496 the application MUST provide a fully functional (*set_size). 06497 */ 06498 off_t (*get_size)(struct burn_source *); 06499 06500 06501 /* @since 0.3.2 */ 06502 /** Program the reply of (*get_size) to a fixed value. It is advised 06503 to implement this by a attribute off_t fixed_size; in *data . 06504 The read() function does not have to take into respect this fake 06505 setting. It is rather a note of libburn to itself. Eventually 06506 necessary truncation or padding is done in libburn. Truncation 06507 is usually considered a misburn. Padding is considered ok. 06508 06509 libburn is supposed to work even if (*get_size) ignores the 06510 setting by (*set_size). But your application will not be able to 06511 enforce fixed track sizes by burn_track_set_size() and possibly 06512 even padding might be left out. 06513 */ 06514 int (*set_size)(struct burn_source *source, off_t size); 06515 06516 06517 /** Clean up the source specific data. This function will be called 06518 once by burn_source_free() when the last referer disposes the 06519 source. 06520 */ 06521 void (*free_data)(struct burn_source *); 06522 06523 06524 /** Next source, for when a source runs dry and padding is disabled 06525 WARNING: This is an obscure feature. Set to NULL at creation and 06526 from then on leave untouched and uninterpreted. 06527 */ 06528 struct burn_source *next; 06529 06530 06531 /** Source specific data. Here the various source classes express their 06532 specific properties and the instance objects store their individual 06533 management data. 06534 E.g. data could point to a struct like this: 06535 struct app_burn_source 06536 { 06537 struct my_app *app_handle; 06538 ... other individual source parameters ... 06539 off_t fixed_size; 06540 }; 06541 06542 Function (*free_data) has to be prepared to clean up and free 06543 the struct. 06544 */ 06545 void *data; 06546 06547 06548 /* @since 0.4.2 */ 06549 /** Valid only if above member .(*read)() is NULL. This indicates a 06550 version of struct burn_source younger than 0. 06551 From then on, member .version tells which further members exist 06552 in the memory layout of struct burn_source. libburn will only touch 06553 those announced extensions. 06554 06555 Versions: 06556 0 has .(*read)() != NULL, not even .version is present. 06557 1 has .version, .(*read_xt)(), .(*cancel)() 06558 */ 06559 int version; 06560 06561 /** This substitutes for (*read)() in versions above 0. */ 06562 int (*read_xt)(struct burn_source *, unsigned char *buffer, int size); 06563 06564 /** Informs the burn_source that the consumer of data prematurely 06565 ended reading. This call may or may not be issued by libburn 06566 before (*free_data)() is called. 06567 */ 06568 int (*cancel)(struct burn_source *source); 06569 }; 06570 06571 #endif /* LIBISOFS_WITHOUT_LIBBURN */ 06572 06573 /* ----------------------------- Bug Fixes ----------------------------- */ 06574 06575 /* currently none being tested */ 06576 06577 06578 /* ---------------------------- Improvements --------------------------- */ 06579 06580 /* currently none being tested */ 06581 06582 06583 /* ---------------------------- Experiments ---------------------------- */ 06584 06585 06586 /* Experiment: Write obsolete RR entries with Rock Ridge. 06587 I suspect Solaris wants to see them. 06588 DID NOT HELP: Solaris knows only RRIP_1991A. 06589 06590 #define Libisofs_with_rrip_rR yes 06591 */ 06592 06593 06594 #endif /*LIBISO_LIBISOFS_H_*/