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