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