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