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 path, relative to 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 20 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 set default values for files and directory permissions, gid and 01420 * uid. All these take one of three values: 0, 1 or 2. 01421 * 01422 * If 0, the corresponding attribute will be kept as setted in the IsoNode. 01423 * Unless you have changed it, it corresponds to the value on disc, so it 01424 * is suitable for backup purposes. If set to 1, the corresponding attrib. 01425 * will be changed by a default suitable value. Finally, if you set it to 01426 * 2, the attrib. will be changed with the value specified by the functioins 01427 * below. Note that for mode attributes, only the permissions are set, the 01428 * file type remains unchanged. 01429 * 01430 * @see iso_write_opts_set_default_dir_mode 01431 * @see iso_write_opts_set_default_file_mode 01432 * @see iso_write_opts_set_default_uid 01433 * @see iso_write_opts_set_default_gid 01434 * @since 0.6.2 01435 */ 01436 int iso_write_opts_set_replace_mode(IsoWriteOpts *opts, int dir_mode, 01437 int file_mode, int uid, int gid); 01438 01439 /** 01440 * Set the mode to use on dirs when you set the replace_mode of dirs to 2. 01441 * 01442 * @see iso_write_opts_set_replace_mode 01443 * @since 0.6.2 01444 */ 01445 int iso_write_opts_set_default_dir_mode(IsoWriteOpts *opts, mode_t dir_mode); 01446 01447 /** 01448 * Set the mode to use on files when you set the replace_mode of files to 2. 01449 * 01450 * @see iso_write_opts_set_replace_mode 01451 * @since 0.6.2 01452 */ 01453 int iso_write_opts_set_default_file_mode(IsoWriteOpts *opts, mode_t file_mode); 01454 01455 /** 01456 * Set the uid to use when you set the replace_uid to 2. 01457 * 01458 * @see iso_write_opts_set_replace_mode 01459 * @since 0.6.2 01460 */ 01461 int iso_write_opts_set_default_uid(IsoWriteOpts *opts, uid_t uid); 01462 01463 /** 01464 * Set the gid to use when you set the replace_gid to 2. 01465 * 01466 * @see iso_write_opts_set_replace_mode 01467 * @since 0.6.2 01468 */ 01469 int iso_write_opts_set_default_gid(IsoWriteOpts *opts, gid_t gid); 01470 01471 /** 01472 * 0 to use IsoNode timestamps, 1 to use recording time, 2 to use 01473 * values from timestamp field. This has only meaning if RR extensions 01474 * are enabled. 01475 * 01476 * @see iso_write_opts_set_default_timestamp 01477 * @since 0.6.2 01478 */ 01479 int iso_write_opts_set_replace_timestamps(IsoWriteOpts *opts, int replace); 01480 01481 /** 01482 * Set the timestamp to use when you set the replace_timestamps to 2. 01483 * 01484 * @see iso_write_opts_set_replace_timestamps 01485 * @since 0.6.2 01486 */ 01487 int iso_write_opts_set_default_timestamp(IsoWriteOpts *opts, time_t timestamp); 01488 01489 /** 01490 * Whether to always record timestamps in GMT. 01491 * 01492 * By default, libisofs stores local time information on image. You can set 01493 * this to always store timestamps converted to GMT. This prevents any 01494 * discrimination of the timezone of the image preparer by the image reader. 01495 * 01496 * It is useful if you want to hide your timezone, or you live in a timezone 01497 * that can't be represented in ECMA-119. These are timezones with an offset 01498 * from GMT greater than +13 hours, lower than -12 hours, or not a multiple 01499 * of 15 minutes. 01500 * Negative timezones (west of GMT) can trigger bugs in some operating systems 01501 * which typically appear in mounted ISO images as if the timezone shift from 01502 * GMT was applied twice (e.g. in New York 22:36 becomes 17:36). 01503 * 01504 * @since 0.6.2 01505 */ 01506 int iso_write_opts_set_always_gmt(IsoWriteOpts *opts, int gmt); 01507 01508 /** 01509 * Set the charset to use for the RR names of the files that will be created 01510 * on the image. 01511 * NULL to use default charset, that is the locale charset. 01512 * You can obtain the list of charsets supported on your system executing 01513 * "iconv -l" in a shell. 01514 * 01515 * @since 0.6.2 01516 */ 01517 int iso_write_opts_set_output_charset(IsoWriteOpts *opts, const char *charset); 01518 01519 /** 01520 * Set the type of image creation in case there was already an existing 01521 * image imported. Libisofs supports two types of creation: 01522 * stand-alone and appended. 01523 * 01524 * A stand-alone image is an image that does not need the old image any more 01525 * for being mounted by the operating system or imported by libisofs. It may 01526 * be written beginning with byte 0 of optical media or disk file objects. 01527 * There will be no distinction between files from the old image and those 01528 * which have been added by the new image generation. 01529 * 01530 * On the other side, an appended image is not self contained. It may refer 01531 * to files that stay stored in the imported existing image. 01532 * This usage model is inspired by CD multi-session. It demands that the 01533 * appended image is finally written to the same media resp. disk file 01534 * as the imported image at an address behind the end of that imported image. 01535 * The exact address may depend on media peculiarities and thus has to be 01536 * announced by the application via iso_write_opts_set_ms_block(). 01537 * The real address where the data will be written is under control of the 01538 * consumer of the struct burn_source which takes the output of libisofs 01539 * image generation. It may be the one announced to libisofs or an intermediate 01540 * one. Nevertheless, the image will be readable only at the announced address. 01541 * 01542 * If you have not imported a previous image by iso_image_import(), then the 01543 * image will always be a stand-alone image, as there is no previous data to 01544 * refer to. 01545 * 01546 * @param append 01547 * 1 to create an appended image, 0 for an stand-alone one. 01548 * 01549 * @since 0.6.2 01550 */ 01551 int iso_write_opts_set_appendable(IsoWriteOpts *opts, int append); 01552 01553 /** 01554 * Set the start block of the image. It is supposed to be the lba where the 01555 * first block of the image will be written on disc. All references inside the 01556 * ISO image will take this into account, thus providing a mountable image. 01557 * 01558 * For appendable images, that are written to a new session, you should 01559 * pass here the lba of the next writable address on disc. 01560 * 01561 * In stand alone images this is usually 0. However, you may want to 01562 * provide a different ms_block if you don't plan to burn the image in the 01563 * first session on disc, such as in some CD-Extra disc whether the data 01564 * image is written in a new session after some audio tracks. 01565 * 01566 * @since 0.6.2 01567 */ 01568 int iso_write_opts_set_ms_block(IsoWriteOpts *opts, uint32_t ms_block); 01569 01570 /** 01571 * Sets the buffer where to store the descriptors which shall to be written 01572 * at the beginning of an overwriteable media to point to the newly written 01573 * image. 01574 * This is needed if the write start address of the image is not 0. 01575 * In this case the first 64 KiB of the media have to be overwritten 01576 * by the buffer content after the session was written and the buffer 01577 * was updated by libisofs. Otherwise the new session would not be 01578 * found by operating system function mount() or by libisoburn. 01579 * (One could still mount that session if its start address is known.) 01580 * 01581 * If you do not need this information, for example because you are creating a 01582 * new image for LBA 0 or because you will create an image for a true 01583 * multisession media, just do not use this call or set buffer to NULL. 01584 * 01585 * Use cases: 01586 * 01587 * - Together with iso_write_opts_set_appendable(opts, 1) the buffer serves 01588 * for the growing of an image as done in growisofs by Andy Polyakov. 01589 * This allows appending of a new session to non-multisession media, such 01590 * as DVD+RW. The new session will refer to the data of previous sessions 01591 * on the same media. 01592 * libisoburn emulates multisession appendability on overwriteable media 01593 * and disk files by performing this use case. 01594 * 01595 * - Together with iso_write_opts_set_appendable(opts, 0) the buffer allows 01596 * to write the first session on overwriteable media to start addresses 01597 * other than 0. 01598 * libisoburn in most cases writes the first session on overwriteable media 01599 * and disk files to LBA 32 in order to preserve its descriptors from the 01600 * subsequent overwriting by the descriptor buffer of later sessions. 01601 * 01602 * @param buffer 01603 * When not NULL, it should point to at least 64KiB of memory, where 01604 * libisofs will install the contents that shall be written at the 01605 * beginning of overwriteable media. 01606 * You should initialize the buffer either with 0s, or with the contents 01607 * of the first 32 blocks of the image you are growing. In most cases, 01608 * 0 is good enought. 01609 * 01610 * @since 0.6.2 01611 */ 01612 int iso_write_opts_set_overwrite_buf(IsoWriteOpts *opts, uint8_t *overwrite); 01613 01614 /** 01615 * Set the size, in number of blocks, of the FIFO buffer used between the 01616 * writer thread and the burn_source. You have to provide at least a 32 01617 * blocks buffer. Default value is set to 2MB, if that is ok for you, you 01618 * don't need to call this function. 01619 * 01620 * @since 0.6.2 01621 */ 01622 int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size); 01623 01624 /** 01625 * Inquire the start address of the file data blocks after having used 01626 * IsoWriteOpts with iso_image_create_burn_source(). 01627 * @param opts 01628 * The option set that was used when starting image creation 01629 * @param data_start 01630 * Returns the logical block address if it is already valid 01631 * @param flag 01632 * Reserved for future usage, set to 0. 01633 * @return 01634 * 1 indicates valid data_start, <0 indicates invalid data_start 01635 * 01636 * @since 0.6.16 01637 */ 01638 int iso_write_opts_get_data_start(IsoWriteOpts *opts, uint32_t *data_start, 01639 int flag); 01640 01641 /** 01642 * Create a burn_source and a thread which immediately begins to generate 01643 * the image. That burn_source can be used with libburn as a data source 01644 * for a track. A copy of its public declaration in libburn.h can be found 01645 * further below in this text. 01646 * 01647 * If image generation shall be aborted by the application program, then 01648 * the .cancel() method of the burn_source must be called to end the 01649 * generation thread: burn_src->cancel(burn_src); 01650 * 01651 * @param image 01652 * The image to write. 01653 * @param opts 01654 * The options for image generation. All needed data will be copied, so 01655 * you can free the given struct once this function returns. 01656 * @param burn_src 01657 * Location where the pointer to the burn_source will be stored 01658 * @return 01659 * 1 on success, < 0 on error 01660 * 01661 * @since 0.6.2 01662 */ 01663 int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts, 01664 struct burn_source **burn_src); 01665 01666 /** 01667 * Update the sizes of all files added to image. 01668 * 01669 * This may be called just before iso_image_create_burn_source() to force 01670 * libisofs to check the file sizes again (they're already checked when added 01671 * to IsoImage). It is useful if you have changed some files after adding then 01672 * to the image. 01673 * 01674 * @return 01675 * 1 on success, < 0 on error 01676 * @since 0.6.8 01677 */ 01678 int iso_image_update_sizes(IsoImage *image); 01679 01680 /** 01681 * Creates an IsoReadOpts for reading an existent image. You should set the 01682 * options desired with the correspondent setters. Note that you may want to 01683 * set the start block value. 01684 * 01685 * Options by default are determined by the selected profile. 01686 * 01687 * @param opts 01688 * Pointer to the location where the newly created IsoReadOpts will be 01689 * stored. You should free it with iso_read_opts_free() when no more 01690 * needed. 01691 * @param profile 01692 * Default profile for image reading. For now the following values are 01693 * defined: 01694 * ---> 0 [STANDARD] 01695 * Suitable for most situations. Most extension are read. When both 01696 * Joliet and RR extension are present, RR is used. 01697 * AAIP for ACL and xattr is not enabled by default. 01698 * @return 01699 * 1 success, < 0 error 01700 * 01701 * @since 0.6.2 01702 */ 01703 int iso_read_opts_new(IsoReadOpts **opts, int profile); 01704 01705 /** 01706 * Free an IsoReadOpts previously allocated with iso_read_opts_new(). 01707 * 01708 * @since 0.6.2 01709 */ 01710 void iso_read_opts_free(IsoReadOpts *opts); 01711 01712 /** 01713 * Set the block where the image begins. It is usually 0, but may be different 01714 * on a multisession disc. 01715 * 01716 * @since 0.6.2 01717 */ 01718 int iso_read_opts_set_start_block(IsoReadOpts *opts, uint32_t block); 01719 01720 /** 01721 * Do not read Rock Ridge extensions. 01722 * In most cases you don't want to use this. It could be useful if RR info 01723 * is damaged, or if you want to use the Joliet tree. 01724 * 01725 * @since 0.6.2 01726 */ 01727 int iso_read_opts_set_no_rockridge(IsoReadOpts *opts, int norr); 01728 01729 /** 01730 * Do not read Joliet extensions. 01731 * 01732 * @since 0.6.2 01733 */ 01734 int iso_read_opts_set_no_joliet(IsoReadOpts *opts, int nojoliet); 01735 01736 /** 01737 * Do not read ISO 9660:1999 enhanced tree 01738 * 01739 * @since 0.6.2 01740 */ 01741 int iso_read_opts_set_no_iso1999(IsoReadOpts *opts, int noiso1999); 01742 01743 /** 01744 * Control reading of AAIP informations about ACL and xattr when loading 01745 * existing images. 01746 * For importing ACL and xattr when inserting nodes from external filesystems 01747 * (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea(). 01748 * For eventual writing of this information see iso_write_opts_set_aaip(). 01749 * 01750 * @param noaaip 01751 * 1 = Do not read AAIP information 01752 * 0 = Read AAIP information if available 01753 * All other values are reserved. 01754 * @since 0.6.14 01755 */ 01756 int iso_read_opts_set_no_aaip(IsoReadOpts *opts, int noaaip); 01757 01758 /** 01759 * Control discarding of eventual inode numbers from existing images. 01760 * Such numbers may come from RRIP 1.12 entries PX. If not discarded they 01761 * get written unchanged when the file object gets written into an ISO image. 01762 * If this inode number is missing with a file in the imported image, 01763 * or if it has been discarded during image reading, then a unique inode number 01764 * will be generated at some time before the file gets written into an ISO 01765 * image. 01766 * Two image nodes which have the same inode number represent two hardlinks 01767 * of the same file object. So discarding the numbers splits hardlinks. 01768 * 01769 * @param new_inos 01770 * 1 = Discard imported inode numbers and finally hand out a unique new 01771 * one to each single file before it gets written into an ISO image. 01772 * 0 = Keep eventual inode numbers from PX entries. 01773 * All other values are reserved. 01774 * @since 0.6.20 01775 */ 01776 int iso_read_opts_set_new_inos(IsoReadOpts *opts, int new_inos); 01777 01778 /** 01779 * Whether to prefer Joliet over RR. libisofs usually prefers RR over 01780 * Joliet, as it give us much more info about files. So, if both extensions 01781 * are present, RR is used. You can set this if you prefer Joliet, but 01782 * note that this is not very recommended. This doesn't mean than RR 01783 * extensions are not read: if no Joliet is present, libisofs will read 01784 * RR tree. 01785 * 01786 * @since 0.6.2 01787 */ 01788 int iso_read_opts_set_preferjoliet(IsoReadOpts *opts, int preferjoliet); 01789 01790 /** 01791 * Set default uid for files when RR extensions are not present. 01792 * 01793 * @since 0.6.2 01794 */ 01795 int iso_read_opts_set_default_uid(IsoReadOpts *opts, uid_t uid); 01796 01797 /** 01798 * Set default gid for files when RR extensions are not present. 01799 * 01800 * @since 0.6.2 01801 */ 01802 int iso_read_opts_set_default_gid(IsoReadOpts *opts, gid_t gid); 01803 01804 /** 01805 * Set default permissions for files when RR extensions are not present. 01806 * 01807 * @param file_perm 01808 * Permissions for files. 01809 * @param dir_perm 01810 * Permissions for directories. 01811 * 01812 * @since 0.6.2 01813 */ 01814 int iso_read_opts_set_default_permissions(IsoReadOpts *opts, mode_t file_perm, 01815 mode_t dir_perm); 01816 01817 /** 01818 * Set the input charset of the file names on the image. NULL to use locale 01819 * charset. You have to specify a charset if the image filenames are encoded 01820 * in a charset different that the local one. This could happen, for example, 01821 * if the image was created on a system with different charset. 01822 * 01823 * @param charset 01824 * The charset to use as input charset. You can obtain the list of 01825 * charsets supported on your system executing "iconv -l" in a shell. 01826 * 01827 * @since 0.6.2 01828 */ 01829 int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset); 01830 01831 /** 01832 * Enable or disable methods to automatically choose an input charset. 01833 * This eventually overrides the name set via iso_read_opts_set_input_charset() 01834 * 01835 * @param mode 01836 * Bitfield for control purposes: 01837 * bit0= Allow to use the input character set name which is eventually 01838 * stored in attribute "isofs.cs" of the root directory. 01839 * Applications may attach this xattr by iso_node_set_attrs() to 01840 * the root node, call iso_write_opts_set_output_charset() with the 01841 * same name and enable iso_write_opts_set_aaip() when writing 01842 * an image. 01843 * Submit any other bits with value 0. 01844 * 01845 * @since 0.6.18 01846 * 01847 */ 01848 int iso_read_opts_auto_input_charset(IsoReadOpts *opts, int mode); 01849 01850 01851 /** 01852 * Import a previous session or image, for growing or modify. 01853 * 01854 * @param image 01855 * The image context to which old image will be imported. Note that all 01856 * files added to image, and image attributes, will be replaced with the 01857 * contents of the old image. 01858 * TODO #00025 support for merging old image files 01859 * @param src 01860 * Data Source from which old image will be read. A extra reference is 01861 * added, so you still need to iso_data_source_unref() yours. 01862 * @param opts 01863 * Options for image import. All needed data will be copied, so you 01864 * can free the given struct once this function returns. 01865 * @param features 01866 * If not NULL, a new IsoReadImageFeatures will be allocated and filled 01867 * with the features of the old image. It should be freed with 01868 * iso_read_image_features_destroy() when no more needed. You can pass 01869 * NULL if you're not interested on them. 01870 * @return 01871 * 1 on success, < 0 on error 01872 * 01873 * @since 0.6.2 01874 */ 01875 int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts, 01876 IsoReadImageFeatures **features); 01877 01878 /** 01879 * Destroy an IsoReadImageFeatures object obtained with iso_image_import. 01880 * 01881 * @since 0.6.2 01882 */ 01883 void iso_read_image_features_destroy(IsoReadImageFeatures *f); 01884 01885 /** 01886 * Get the size (in 2048 byte block) of the image, as reported in the PVM. 01887 * 01888 * @since 0.6.2 01889 */ 01890 uint32_t iso_read_image_features_get_size(IsoReadImageFeatures *f); 01891 01892 /** 01893 * Whether RockRidge extensions are present in the image imported. 01894 * 01895 * @since 0.6.2 01896 */ 01897 int iso_read_image_features_has_rockridge(IsoReadImageFeatures *f); 01898 01899 /** 01900 * Whether Joliet extensions are present in the image imported. 01901 * 01902 * @since 0.6.2 01903 */ 01904 int iso_read_image_features_has_joliet(IsoReadImageFeatures *f); 01905 01906 /** 01907 * Whether the image is recorded according to ISO 9660:1999, i.e. it has 01908 * a version 2 Enhanced Volume Descriptor. 01909 * 01910 * @since 0.6.2 01911 */ 01912 int iso_read_image_features_has_iso1999(IsoReadImageFeatures *f); 01913 01914 /** 01915 * Whether El-Torito boot record is present present in the image imported. 01916 * 01917 * @since 0.6.2 01918 */ 01919 int iso_read_image_features_has_eltorito(IsoReadImageFeatures *f); 01920 01921 /** 01922 * Increments the reference counting of the given image. 01923 * 01924 * @since 0.6.2 01925 */ 01926 void iso_image_ref(IsoImage *image); 01927 01928 /** 01929 * Decrements the reference couting of the given image. 01930 * If it reaches 0, the image is free, together with its tree nodes (whether 01931 * their refcount reach 0 too, of course). 01932 * 01933 * @since 0.6.2 01934 */ 01935 void iso_image_unref(IsoImage *image); 01936 01937 /** 01938 * Attach user defined data to the image. Use this if your application needs 01939 * to store addition info together with the IsoImage. If the image already 01940 * has data attached, the old data will be freed. 01941 * 01942 * @param data 01943 * Pointer to application defined data that will be attached to the 01944 * image. You can pass NULL to remove any already attached data. 01945 * @param give_up 01946 * Function that will be called when the image does not need the data 01947 * any more. It receives the data pointer as an argumente, and eventually 01948 * causes data to be freed. It can be NULL if you don't need it. 01949 * @return 01950 * 1 on succes, < 0 on error 01951 * 01952 * @since 0.6.2 01953 */ 01954 int iso_image_attach_data(IsoImage *image, void *data, void (*give_up)(void*)); 01955 01956 /** 01957 * The the data previously attached with iso_image_attach_data() 01958 * 01959 * @since 0.6.2 01960 */ 01961 void *iso_image_get_attached_data(IsoImage *image); 01962 01963 /** 01964 * Get the root directory of the image. 01965 * No extra ref is added to it, so you musn't unref it. Use iso_node_ref() 01966 * if you want to get your own reference. 01967 * 01968 * @since 0.6.2 01969 */ 01970 IsoDir *iso_image_get_root(const IsoImage *image); 01971 01972 /** 01973 * Fill in the volset identifier for a image. 01974 * 01975 * @since 0.6.2 01976 */ 01977 void iso_image_set_volset_id(IsoImage *image, const char *volset_id); 01978 01979 /** 01980 * Get the volset identifier. 01981 * The returned string is owned by the image and should not be freed nor 01982 * changed. 01983 * 01984 * @since 0.6.2 01985 */ 01986 const char *iso_image_get_volset_id(const IsoImage *image); 01987 01988 /** 01989 * Fill in the volume identifier for a image. 01990 * 01991 * @since 0.6.2 01992 */ 01993 void iso_image_set_volume_id(IsoImage *image, const char *volume_id); 01994 01995 /** 01996 * Get the volume identifier. 01997 * The returned string is owned by the image and should not be freed nor 01998 * changed. 01999 * 02000 * @since 0.6.2 02001 */ 02002 const char *iso_image_get_volume_id(const IsoImage *image); 02003 02004 /** 02005 * Fill in the publisher for a image. 02006 * 02007 * @since 0.6.2 02008 */ 02009 void iso_image_set_publisher_id(IsoImage *image, const char *publisher_id); 02010 02011 /** 02012 * Get the publisher of a image. 02013 * The returned string is owned by the image and should not be freed nor 02014 * changed. 02015 * 02016 * @since 0.6.2 02017 */ 02018 const char *iso_image_get_publisher_id(const IsoImage *image); 02019 02020 /** 02021 * Fill in the data preparer for a image. 02022 * 02023 * @since 0.6.2 02024 */ 02025 void iso_image_set_data_preparer_id(IsoImage *image, 02026 const char *data_preparer_id); 02027 02028 /** 02029 * Get the data preparer of a image. 02030 * The returned string is owned by the image and should not be freed nor 02031 * changed. 02032 * 02033 * @since 0.6.2 02034 */ 02035 const char *iso_image_get_data_preparer_id(const IsoImage *image); 02036 02037 /** 02038 * Fill in the system id for a image. Up to 32 characters. 02039 * 02040 * @since 0.6.2 02041 */ 02042 void iso_image_set_system_id(IsoImage *image, const char *system_id); 02043 02044 /** 02045 * Get the system id of a image. 02046 * The returned string is owned by the image and should not be freed nor 02047 * changed. 02048 * 02049 * @since 0.6.2 02050 */ 02051 const char *iso_image_get_system_id(const IsoImage *image); 02052 02053 /** 02054 * Fill in the application id for a image. Up to 128 chars. 02055 * 02056 * @since 0.6.2 02057 */ 02058 void iso_image_set_application_id(IsoImage *image, const char *application_id); 02059 02060 /** 02061 * Get the application id of a image. 02062 * The returned string is owned by the image and should not be freed nor 02063 * changed. 02064 * 02065 * @since 0.6.2 02066 */ 02067 const char *iso_image_get_application_id(const IsoImage *image); 02068 02069 /** 02070 * Fill copyright information for the image. Usually this refers 02071 * to a file on disc. Up to 37 characters. 02072 * 02073 * @since 0.6.2 02074 */ 02075 void iso_image_set_copyright_file_id(IsoImage *image, 02076 const char *copyright_file_id); 02077 02078 /** 02079 * Get the copyright information of a image. 02080 * The returned string is owned by the image and should not be freed nor 02081 * changed. 02082 * 02083 * @since 0.6.2 02084 */ 02085 const char *iso_image_get_copyright_file_id(const IsoImage *image); 02086 02087 /** 02088 * Fill abstract information for the image. Usually this refers 02089 * to a file on disc. Up to 37 characters. 02090 * 02091 * @since 0.6.2 02092 */ 02093 void iso_image_set_abstract_file_id(IsoImage *image, 02094 const char *abstract_file_id); 02095 02096 /** 02097 * Get the abstract information of a image. 02098 * The returned string is owned by the image and should not be freed nor 02099 * changed. 02100 * 02101 * @since 0.6.2 02102 */ 02103 const char *iso_image_get_abstract_file_id(const IsoImage *image); 02104 02105 /** 02106 * Fill biblio information for the image. Usually this refers 02107 * to a file on disc. Up to 37 characters. 02108 * 02109 * @since 0.6.2 02110 */ 02111 void iso_image_set_biblio_file_id(IsoImage *image, const char *biblio_file_id); 02112 02113 /** 02114 * Get the biblio information of a image. 02115 * The returned string is owned by the image and should not be freed nor 02116 * changed. 02117 * 02118 * @since 0.6.2 02119 */ 02120 const char *iso_image_get_biblio_file_id(const IsoImage *image); 02121 02122 /** 02123 * Create a bootable image by adding a El-Torito boot image. 02124 * 02125 * This also add a catalog boot node to the image filesystem tree. 02126 * 02127 * @param image 02128 * The image to make bootable. If it was already bootable this function 02129 * returns an error and the image remains unmodified. 02130 * @param image_path 02131 * The path on the image tree of a regular file to use as default boot 02132 * image. 02133 * @param type 02134 * The boot media type. This can be one of 3 types: 02135 * - Floppy emulation: Boot image file must be exactly 02136 * 1200 kB, 1440 kB or 2880 kB. 02137 * - Hard disc emulation: The image must begin with a master 02138 * boot record with a single image. 02139 * - No emulation. You should specify load segment and load size 02140 * of image. 02141 * @param catalog_path 02142 * The path on the image tree where the catalog will be stored. The 02143 * directory component of this path must be a directory existent on the 02144 * image tree, and the filename component must be unique among all 02145 * children of that directory on image. Otherwise a correspodent error 02146 * code will be returned. This function will add an IsoBoot node that acts 02147 * as a placeholder for the real catalog, that will be generated at image 02148 * creation time. 02149 * @param boot 02150 * Location where a pointer to the added boot image will be stored. That 02151 * object is owned by the IsoImage and should not be freed by the user, 02152 * nor dereferenced once the last reference to the IsoImage was disposed 02153 * via iso_image_unref(). A NULL value is allowed if you don't need a 02154 * reference to the boot image. 02155 * @return 02156 * 1 on success, < 0 on error 02157 * 02158 * @since 0.6.2 02159 */ 02160 int iso_image_set_boot_image(IsoImage *image, const char *image_path, 02161 enum eltorito_boot_media_type type, 02162 const char *catalog_path, 02163 ElToritoBootImage **boot); 02164 02165 /* TODO #00026 : add support for "hidden" bootable images. */ 02166 02167 /** 02168 * Get El-Torito boot image of an ISO image, if any. 02169 * 02170 * This can be useful, for example, to check if a volume read from a previous 02171 * session or an existing image is bootable. It can also be useful to get 02172 * the image and catalog tree nodes. An application would want those, for 02173 * example, to prevent the user removing it. 02174 * 02175 * Both nodes are owned by libisofs and should not be freed. You can get your 02176 * own ref with iso_node_ref(). You can can also check if the node is already 02177 * on the tree by getting its parent (note that when reading El-Torito info 02178 * from a previous image, the nodes might not be on the tree even if you haven't 02179 * removed them). Remember that you'll need to get a new ref 02180 * (with iso_node_ref()) before inserting them again to the tree, and probably 02181 * you will also need to set the name or permissions. 02182 * 02183 * @param image 02184 * The image from which to get the boot image. 02185 * @param boot 02186 * If not NULL, it will be filled with a pointer to the boot image, if 02187 * any. That object is owned by the IsoImage and should not be freed by 02188 * the user, nor dereferenced once the last reference to the IsoImage was 02189 * disposed via iso_image_unref(). 02190 * @param imgnode 02191 * When not NULL, it will be filled with the image tree node. No extra ref 02192 * is added, you can use iso_node_ref() to get one if you need it. 02193 * @param catnode 02194 * When not NULL, it will be filled with the catnode tree node. No extra 02195 * ref is added, you can use iso_node_ref() to get one if you need it. 02196 * @return 02197 * 1 on success, 0 is the image is not bootable (i.e., it has no El-Torito 02198 * image), < 0 error. 02199 * 02200 * @since 0.6.2 02201 */ 02202 int iso_image_get_boot_image(IsoImage *image, ElToritoBootImage **boot, 02203 IsoFile **imgnode, IsoBoot **catnode); 02204 02205 /** 02206 * Removes the El-Torito bootable image. 02207 * 02208 * The IsoBoot node that acts as placeholder for the catalog is also removed 02209 * for the image tree, if there. 02210 * If the image is not bootable (don't have el-torito boot image) this function 02211 * just returns. 02212 * 02213 * @since 0.6.2 02214 */ 02215 void iso_image_remove_boot_image(IsoImage *image); 02216 02217 /** 02218 * Sets the load segment for the initial boot image. This is only for 02219 * no emulation boot images, and is a NOP for other image types. 02220 * 02221 * @since 0.6.2 02222 */ 02223 void el_torito_set_load_seg(ElToritoBootImage *bootimg, short segment); 02224 02225 /** 02226 * Sets the number of sectors (512b) to be load at load segment during 02227 * the initial boot procedure. This is only for 02228 * no emulation boot images, and is a NOP for other image types. 02229 * 02230 * @since 0.6.2 02231 */ 02232 void el_torito_set_load_size(ElToritoBootImage *bootimg, short sectors); 02233 02234 /** 02235 * Marks the specified boot image as not bootable 02236 * 02237 * @since 0.6.2 02238 */ 02239 void el_torito_set_no_bootable(ElToritoBootImage *bootimg); 02240 02241 /** 02242 * Specifies that this image needs to be patched. This involves the writing 02243 * of a 56 bytes boot information table at offset 8 of the boot image file. 02244 * The original boot image file won't be modified. 02245 * This is needed for isolinux boot images. 02246 * 02247 * @since 0.6.2 02248 * @deprecated Use el_torito_set_isolinux_options() instead 02249 */ 02250 void el_torito_patch_isolinux_image(ElToritoBootImage *bootimg); 02251 02252 /** 02253 * Specifies options for IsoLinux boot images. This should only be used with 02254 * isolinux boot images. 02255 * 02256 * @param options 02257 * bitmask style flag. The following values are defined: 02258 * 02259 * bit 0 -> 1 to path the image, 0 to not 02260 * Patching the image involves the writing of a 56 bytes 02261 * boot information table at offset 8 of the boot image file. 02262 * The original boot image file will not be modified. This is 02263 * needed to allow isolinux images to be bootable. 02264 * bit 1 -> 1 to generate an hybrid image with MBR, 0 to not 02265 * An hybrid image is a boot image that boots from either 02266 * CD/DVD media or from disk-like media, e.g. USB stick. 02267 * For that you need isolinux.bin from SYSLINUX 3.72 or later. 02268 * IMPORTANT: The application has to take care that the image 02269 * on media gets padded up to the next full MB. 02270 * @param flag 02271 * Reserved for future usage, set to 0. 02272 * @return 02273 * 1 success, < 0 on error 02274 * @since 0.6.12 02275 */ 02276 int el_torito_set_isolinux_options(ElToritoBootImage *bootimg, int options, int flag); 02277 02278 /** 02279 * Increments the reference counting of the given node. 02280 * 02281 * @since 0.6.2 02282 */ 02283 void iso_node_ref(IsoNode *node); 02284 02285 /** 02286 * Decrements the reference couting of the given node. 02287 * If it reach 0, the node is free, and, if the node is a directory, 02288 * its children will be unref() too. 02289 * 02290 * @since 0.6.2 02291 */ 02292 void iso_node_unref(IsoNode *node); 02293 02294 /** 02295 * Get the type of an IsoNode. 02296 * 02297 * @since 0.6.2 02298 */ 02299 enum IsoNodeType iso_node_get_type(IsoNode *node); 02300 02301 /** 02302 * Function to handle particular extended information. The function 02303 * pointer acts as an identifier for the type of the information. Structs 02304 * with same information type must use the same function. 02305 * 02306 * @param data 02307 * Attached data 02308 * @param flag 02309 * What to do with the data. At this time the following values are 02310 * defined: 02311 * -> 1 the data must be freed 02312 * @return 02313 * 1 in any case. 02314 * 02315 * @since 0.6.4 02316 */ 02317 typedef int (*iso_node_xinfo_func)(void *data, int flag); 02318 02319 /** 02320 * Add extended information to the given node. Extended info allows 02321 * applications (and libisofs itself) to add more information to an IsoNode. 02322 * You can use this facilities to associate temporary information with a given 02323 * node. This information is not written into the ISO 9660 image on media 02324 * and thus does not persist longer than the node memory object. 02325 * 02326 * Each node keeps a list of added extended info, meaning you can add several 02327 * extended info data to each node. Each extended info you add is identified 02328 * by the proc parameter, a pointer to a function that knows how to manage 02329 * the external info data. Thus, in order to add several types of extended 02330 * info, you need to define a "proc" function for each type. 02331 * 02332 * @param node 02333 * The node where to add the extended info 02334 * @param proc 02335 * A function pointer used to identify the type of the data, and that 02336 * knows how to manage it 02337 * @param data 02338 * Extended info to add. 02339 * @return 02340 * 1 if success, 0 if the given node already has extended info of the 02341 * type defined by the "proc" function, < 0 on error 02342 * 02343 * @since 0.6.4 02344 */ 02345 int iso_node_add_xinfo(IsoNode *node, iso_node_xinfo_func proc, void *data); 02346 02347 /** 02348 * Remove the given extended info (defined by the proc function) from the 02349 * given node. 02350 * 02351 * @return 02352 * 1 on success, 0 if node does not have extended info of the requested 02353 * type, < 0 on error 02354 * 02355 * @since 0.6.4 02356 */ 02357 int iso_node_remove_xinfo(IsoNode *node, iso_node_xinfo_func proc); 02358 02359 /** 02360 * Get the given extended info (defined by the proc function) from the 02361 * given node. 02362 * 02363 * @param data 02364 * Will be filled with the extended info corresponding to the given proc 02365 * function 02366 * @return 02367 * 1 on success, 0 if node does not have extended info of the requested 02368 * type, < 0 on error 02369 * 02370 * @since 0.6.4 02371 */ 02372 int iso_node_get_xinfo(IsoNode *node, iso_node_xinfo_func proc, void **data); 02373 02374 /** 02375 * Set the name of a node. Note that if the node is already added to a dir 02376 * this can fail if dir already contains a node with the new name. 02377 * 02378 * @param node 02379 * The node whose name you want to change. Note that you can't change 02380 * the name of the root. 02381 * @param name 02382 * The name for the node. If you supply an empty string or a 02383 * name greater than 255 characters this returns with failure, and 02384 * node name is not modified. 02385 * @return 02386 * 1 on success, < 0 on error 02387 * 02388 * @since 0.6.2 02389 */ 02390 int iso_node_set_name(IsoNode *node, const char *name); 02391 02392 /** 02393 * Get the name of a node. 02394 * The returned string belongs to the node and should not be modified nor 02395 * freed. Use strdup if you really need your own copy. 02396 * 02397 * @since 0.6.2 02398 */ 02399 const char *iso_node_get_name(const IsoNode *node); 02400 02401 /** 02402 * Set the permissions for the node. This attribute is only useful when 02403 * Rock Ridge extensions are enabled. 02404 * 02405 * @param mode 02406 * bitmask with the permissions of the node, as specified in 'man 2 stat'. 02407 * The file type bitfields will be ignored, only file permissions will be 02408 * modified. 02409 * 02410 * @since 0.6.2 02411 */ 02412 void iso_node_set_permissions(IsoNode *node, mode_t mode); 02413 02414 /** 02415 * Get the permissions for the node 02416 * 02417 * @since 0.6.2 02418 */ 02419 mode_t iso_node_get_permissions(const IsoNode *node); 02420 02421 /** 02422 * Get the mode of the node, both permissions and file type, as specified in 02423 * 'man 2 stat'. 02424 * 02425 * @since 0.6.2 02426 */ 02427 mode_t iso_node_get_mode(const IsoNode *node); 02428 02429 /** 02430 * Set the user id for the node. This attribute is only useful when 02431 * Rock Ridge extensions are enabled. 02432 * 02433 * @since 0.6.2 02434 */ 02435 void iso_node_set_uid(IsoNode *node, uid_t uid); 02436 02437 /** 02438 * Get the user id of the node. 02439 * 02440 * @since 0.6.2 02441 */ 02442 uid_t iso_node_get_uid(const IsoNode *node); 02443 02444 /** 02445 * Set the group id for the node. This attribute is only useful when 02446 * Rock Ridge extensions are enabled. 02447 * 02448 * @since 0.6.2 02449 */ 02450 void iso_node_set_gid(IsoNode *node, gid_t gid); 02451 02452 /** 02453 * Get the group id of the node. 02454 * 02455 * @since 0.6.2 02456 */ 02457 gid_t iso_node_get_gid(const IsoNode *node); 02458 02459 /** 02460 * Set the time of last modification of the file 02461 * 02462 * @since 0.6.2 02463 */ 02464 void iso_node_set_mtime(IsoNode *node, time_t time); 02465 02466 /** 02467 * Get the time of last modification of the file 02468 * 02469 * @since 0.6.2 02470 */ 02471 time_t iso_node_get_mtime(const IsoNode *node); 02472 02473 /** 02474 * Set the time of last access to the file 02475 * 02476 * @since 0.6.2 02477 */ 02478 void iso_node_set_atime(IsoNode *node, time_t time); 02479 02480 /** 02481 * Get the time of last access to the file 02482 * 02483 * @since 0.6.2 02484 */ 02485 time_t iso_node_get_atime(const IsoNode *node); 02486 02487 /** 02488 * Set the time of last status change of the file 02489 * 02490 * @since 0.6.2 02491 */ 02492 void iso_node_set_ctime(IsoNode *node, time_t time); 02493 02494 /** 02495 * Get the time of last status change of the file 02496 * 02497 * @since 0.6.2 02498 */ 02499 time_t iso_node_get_ctime(const IsoNode *node); 02500 02501 /** 02502 * Set if the node will be hidden in RR/ISO tree, Joliet tree or both. 02503 * 02504 * If the file is set as hidden in one tree, it won't be included there, so 02505 * it won't be visible in a OS accessing CD using that tree. For example, 02506 * GNU/Linux systems access to Rock Ridge / ISO9960 tree in order to see 02507 * what is recorded on CD, while MS Windows make use of the Joliet tree. If a 02508 * file is hidden only in Joliet, it won't be visible in Windows systems, 02509 * while still visible in Linux. 02510 * 02511 * If a file is hidden in both trees, it won't be written to image. 02512 * 02513 * @param node 02514 * The node that is to be hidden. 02515 * @param hide_attrs 02516 * IsoHideNodeFlag's to set the trees in which file will be hidden. 02517 * 02518 * @since 0.6.2 02519 */ 02520 void iso_node_set_hidden(IsoNode *node, int hide_attrs); 02521 02522 /** 02523 * Compare two nodes whether they are based on the same input and 02524 * can be considered as hardlinks to the same file objects. 02525 * 02526 * @param n1 02527 * The first node to compare. 02528 * @param n2 02529 * The second node to compare. 02530 * @return 02531 * -1 if s1 is smaller s2 , 0 if s1 matches s2 , 1 if s1 is larger s2 02532 * @param flag 02533 * Bitfield for control purposes, unused yet, submit 0 02534 * @since 0.6.20 02535 */ 02536 int iso_node_cmp_ino(IsoNode *n1, IsoNode *n2, int flag); 02537 02538 /** 02539 * Add a new node to a dir. Note that this function don't add a new ref to 02540 * the node, so you don't need to free it, it will be automatically freed 02541 * when the dir is deleted. Of course, if you want to keep using the node 02542 * after the dir life, you need to iso_node_ref() it. 02543 * 02544 * @param dir 02545 * the dir where to add the node 02546 * @param child 02547 * the node to add. You must ensure that the node hasn't previously added 02548 * to other dir, and that the node name is unique inside the child. 02549 * Otherwise this function will return a failure, and the child won't be 02550 * inserted. 02551 * @param replace 02552 * if the dir already contains a node with the same name, whether to 02553 * replace or not the old node with this. 02554 * @return 02555 * number of nodes in dir if succes, < 0 otherwise 02556 * Possible errors: 02557 * ISO_NULL_POINTER, if dir or child are NULL 02558 * ISO_NODE_ALREADY_ADDED, if child is already added to other dir 02559 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02560 * ISO_WRONG_ARG_VALUE, if child == dir, or replace != (0,1) 02561 * 02562 * @since 0.6.2 02563 */ 02564 int iso_dir_add_node(IsoDir *dir, IsoNode *child, 02565 enum iso_replace_mode replace); 02566 02567 /** 02568 * Locate a node inside a given dir. 02569 * 02570 * @param dir 02571 * The dir where to look for the node. 02572 * @param name 02573 * The name of the node 02574 * @param node 02575 * Location for a pointer to the node, it will filled with NULL if the dir 02576 * doesn't have a child with the given name. 02577 * The node will be owned by the dir and shouldn't be unref(). Just call 02578 * iso_node_ref() to get your own reference to the node. 02579 * Note that you can pass NULL is the only thing you want to do is check 02580 * if a node with such name already exists on dir. 02581 * @return 02582 * 1 node found, 0 child has no such node, < 0 error 02583 * Possible errors: 02584 * ISO_NULL_POINTER, if dir or name are NULL 02585 * 02586 * @since 0.6.2 02587 */ 02588 int iso_dir_get_node(IsoDir *dir, const char *name, IsoNode **node); 02589 02590 /** 02591 * Get the number of children of a directory. 02592 * 02593 * @return 02594 * >= 0 number of items, < 0 error 02595 * Possible errors: 02596 * ISO_NULL_POINTER, if dir is NULL 02597 * 02598 * @since 0.6.2 02599 */ 02600 int iso_dir_get_children_count(IsoDir *dir); 02601 02602 /** 02603 * Removes a child from a directory. 02604 * The child is not freed, so you will become the owner of the node. Later 02605 * you can add the node to another dir (calling iso_dir_add_node), or free 02606 * it if you don't need it (with iso_node_unref). 02607 * 02608 * @return 02609 * 1 on success, < 0 error 02610 * Possible errors: 02611 * ISO_NULL_POINTER, if node is NULL 02612 * ISO_NODE_NOT_ADDED_TO_DIR, if node doesn't belong to a dir 02613 * 02614 * @since 0.6.2 02615 */ 02616 int iso_node_take(IsoNode *node); 02617 02618 /** 02619 * Removes a child from a directory and free (unref) it. 02620 * If you want to keep the child alive, you need to iso_node_ref() it 02621 * before this call, but in that case iso_node_take() is a better 02622 * alternative. 02623 * 02624 * @return 02625 * 1 on success, < 0 error 02626 * 02627 * @since 0.6.2 02628 */ 02629 int iso_node_remove(IsoNode *node); 02630 02631 /* 02632 * Get the parent of the given iso tree node. No extra ref is added to the 02633 * returned directory, you must take your ref. with iso_node_ref() if you 02634 * need it. 02635 * 02636 * If node is the root node, the same node will be returned as its parent. 02637 * 02638 * This returns NULL if the node doesn't pertain to any tree 02639 * (it was removed/taken). 02640 * 02641 * @since 0.6.2 02642 */ 02643 IsoDir *iso_node_get_parent(IsoNode *node); 02644 02645 /** 02646 * Get an iterator for the children of the given dir. 02647 * 02648 * You can iterate over the children with iso_dir_iter_next. When finished, 02649 * you should free the iterator with iso_dir_iter_free. 02650 * You musn't delete a child of the same dir, using iso_node_take() or 02651 * iso_node_remove(), while you're using the iterator. You can use 02652 * iso_dir_iter_take() or iso_dir_iter_remove() instead. 02653 * 02654 * You can use the iterator in the way like this 02655 * 02656 * IsoDirIter *iter; 02657 * IsoNode *node; 02658 * if ( iso_dir_get_children(dir, &iter) != 1 ) { 02659 * // handle error 02660 * } 02661 * while ( iso_dir_iter_next(iter, &node) == 1 ) { 02662 * // do something with the child 02663 * } 02664 * iso_dir_iter_free(iter); 02665 * 02666 * An iterator is intended to be used in a single iteration over the 02667 * children of a dir. Thus, it should be treated as a temporary object, 02668 * and free as soon as possible. 02669 * 02670 * @return 02671 * 1 success, < 0 error 02672 * Possible errors: 02673 * ISO_NULL_POINTER, if dir or iter are NULL 02674 * ISO_OUT_OF_MEM 02675 * 02676 * @since 0.6.2 02677 */ 02678 int iso_dir_get_children(const IsoDir *dir, IsoDirIter **iter); 02679 02680 /** 02681 * Get the next child. 02682 * Take care that the node is owned by its parent, and will be unref() when 02683 * the parent is freed. If you want your own ref to it, call iso_node_ref() 02684 * on it. 02685 * 02686 * @return 02687 * 1 success, 0 if dir has no more elements, < 0 error 02688 * Possible errors: 02689 * ISO_NULL_POINTER, if node or iter are NULL 02690 * ISO_ERROR, on wrong iter usage, usual caused by modiying the 02691 * dir during iteration 02692 * 02693 * @since 0.6.2 02694 */ 02695 int iso_dir_iter_next(IsoDirIter *iter, IsoNode **node); 02696 02697 /** 02698 * Check if there're more children. 02699 * 02700 * @return 02701 * 1 dir has more elements, 0 no, < 0 error 02702 * Possible errors: 02703 * ISO_NULL_POINTER, if iter is NULL 02704 * 02705 * @since 0.6.2 02706 */ 02707 int iso_dir_iter_has_next(IsoDirIter *iter); 02708 02709 /** 02710 * Free a dir iterator. 02711 * 02712 * @since 0.6.2 02713 */ 02714 void iso_dir_iter_free(IsoDirIter *iter); 02715 02716 /** 02717 * Removes a child from a directory during an iteration, without freeing it. 02718 * It's like iso_node_take(), but to be used during a directory iteration. 02719 * The node removed will be the last returned by the iteration. 02720 * 02721 * If you call this function twice without calling iso_dir_iter_next between 02722 * them is not allowed and you will get an ISO_ERROR in second call. 02723 * 02724 * @return 02725 * 1 on succes, < 0 error 02726 * Possible errors: 02727 * ISO_NULL_POINTER, if iter is NULL 02728 * ISO_ERROR, on wrong iter usage, for example by call this before 02729 * iso_dir_iter_next. 02730 * 02731 * @since 0.6.2 02732 */ 02733 int iso_dir_iter_take(IsoDirIter *iter); 02734 02735 /** 02736 * Removes a child from a directory during an iteration and unref() it. 02737 * It's like iso_node_remove(), but to be used during a directory iteration. 02738 * The node removed will be the last returned by the iteration. 02739 * 02740 * If you call this function twice without calling iso_dir_iter_next between 02741 * them is not allowed and you will get an ISO_ERROR in second call. 02742 * 02743 * @return 02744 * 1 on succes, < 0 error 02745 * Possible errors: 02746 * ISO_NULL_POINTER, if iter is NULL 02747 * ISO_ERROR, on wrong iter usage, for example by call this before 02748 * iso_dir_iter_next. 02749 * 02750 * @since 0.6.2 02751 */ 02752 int iso_dir_iter_remove(IsoDirIter *iter); 02753 02754 02755 /** 02756 * @since 0.6.4 02757 */ 02758 typedef struct iso_find_condition IsoFindCondition; 02759 02760 /** 02761 * Create a new condition that checks if the node name matches the given 02762 * wildcard. 02763 * 02764 * @param wildcard 02765 * @result 02766 * The created IsoFindCondition, NULL on error. 02767 * 02768 * @since 0.6.4 02769 */ 02770 IsoFindCondition *iso_new_find_conditions_name(const char *wildcard); 02771 02772 /** 02773 * Create a new condition that checks the node mode against a mode mask. It 02774 * can be used to check both file type and permissions. 02775 * 02776 * For example: 02777 * 02778 * iso_new_find_conditions_mode(S_IFREG) : search for regular files 02779 * iso_new_find_conditions_mode(S_IFCHR | S_IWUSR) : search for character 02780 * devices where owner has write permissions. 02781 * 02782 * @param mask 02783 * Mode mask to AND against node mode. 02784 * @result 02785 * The created IsoFindCondition, NULL on error. 02786 * 02787 * @since 0.6.4 02788 */ 02789 IsoFindCondition *iso_new_find_conditions_mode(mode_t mask); 02790 02791 /** 02792 * Create a new condition that checks the node gid. 02793 * 02794 * @param gid 02795 * Desired Group Id. 02796 * @result 02797 * The created IsoFindCondition, NULL on error. 02798 * 02799 * @since 0.6.4 02800 */ 02801 IsoFindCondition *iso_new_find_conditions_gid(gid_t gid); 02802 02803 /** 02804 * Create a new condition that checks the node uid. 02805 * 02806 * @param uid 02807 * Desired User Id. 02808 * @result 02809 * The created IsoFindCondition, NULL on error. 02810 * 02811 * @since 0.6.4 02812 */ 02813 IsoFindCondition *iso_new_find_conditions_uid(uid_t uid); 02814 02815 /** 02816 * Possible comparison between IsoNode and given conditions. 02817 * 02818 * @since 0.6.4 02819 */ 02820 enum iso_find_comparisons { 02821 ISO_FIND_COND_GREATER, 02822 ISO_FIND_COND_GREATER_OR_EQUAL, 02823 ISO_FIND_COND_EQUAL, 02824 ISO_FIND_COND_LESS, 02825 ISO_FIND_COND_LESS_OR_EQUAL 02826 }; 02827 02828 /** 02829 * Create a new condition that checks the time of last access. 02830 * 02831 * @param time 02832 * Time to compare against IsoNode atime. 02833 * @param comparison 02834 * Comparison to be done between IsoNode atime and submitted time. 02835 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02836 * time is greater than the submitted time. 02837 * @result 02838 * The created IsoFindCondition, NULL on error. 02839 * 02840 * @since 0.6.4 02841 */ 02842 IsoFindCondition *iso_new_find_conditions_atime(time_t time, 02843 enum iso_find_comparisons comparison); 02844 02845 /** 02846 * Create a new condition that checks the time of last modification. 02847 * 02848 * @param time 02849 * Time to compare against IsoNode mtime. 02850 * @param comparison 02851 * Comparison to be done between IsoNode mtime and submitted time. 02852 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02853 * time is greater than the submitted time. 02854 * @result 02855 * The created IsoFindCondition, NULL on error. 02856 * 02857 * @since 0.6.4 02858 */ 02859 IsoFindCondition *iso_new_find_conditions_mtime(time_t time, 02860 enum iso_find_comparisons comparison); 02861 02862 /** 02863 * Create a new condition that checks the time of last status change. 02864 * 02865 * @param time 02866 * Time to compare against IsoNode ctime. 02867 * @param comparison 02868 * Comparison to be done between IsoNode ctime and submitted time. 02869 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02870 * time is greater than the submitted time. 02871 * @result 02872 * The created IsoFindCondition, NULL on error. 02873 * 02874 * @since 0.6.4 02875 */ 02876 IsoFindCondition *iso_new_find_conditions_ctime(time_t time, 02877 enum iso_find_comparisons comparison); 02878 02879 /** 02880 * Create a new condition that check if the two given conditions are 02881 * valid. 02882 * 02883 * @param a 02884 * @param b 02885 * IsoFindCondition to compare 02886 * @result 02887 * The created IsoFindCondition, NULL on error. 02888 * 02889 * @since 0.6.4 02890 */ 02891 IsoFindCondition *iso_new_find_conditions_and(IsoFindCondition *a, 02892 IsoFindCondition *b); 02893 02894 /** 02895 * Create a new condition that check if at least one the two given conditions 02896 * is valid. 02897 * 02898 * @param a 02899 * @param b 02900 * IsoFindCondition to compare 02901 * @result 02902 * The created IsoFindCondition, NULL on error. 02903 * 02904 * @since 0.6.4 02905 */ 02906 IsoFindCondition *iso_new_find_conditions_or(IsoFindCondition *a, 02907 IsoFindCondition *b); 02908 02909 /** 02910 * Create a new condition that check if the given conditions is false. 02911 * 02912 * @param negate 02913 * @result 02914 * The created IsoFindCondition, NULL on error. 02915 * 02916 * @since 0.6.4 02917 */ 02918 IsoFindCondition *iso_new_find_conditions_not(IsoFindCondition *negate); 02919 02920 /** 02921 * Find all directory children that match the given condition. 02922 * 02923 * @param dir 02924 * Directory where we will search children. 02925 * @param cond 02926 * Condition that the children must match in order to be returned. 02927 * It will be free together with the iterator. Remember to delete it 02928 * if this function return error. 02929 * @param iter 02930 * Iterator that returns only the children that match condition. 02931 * @return 02932 * 1 on success, < 0 on error 02933 * 02934 * @since 0.6.4 02935 */ 02936 int iso_dir_find_children(IsoDir* dir, IsoFindCondition *cond, 02937 IsoDirIter **iter); 02938 02939 /** 02940 * Get the destination of a node. 02941 * The returned string belongs to the node and should not be modified nor 02942 * freed. Use strdup if you really need your own copy. 02943 * 02944 * @since 0.6.2 02945 */ 02946 const char *iso_symlink_get_dest(const IsoSymlink *link); 02947 02948 /** 02949 * Set the destination of a link. 02950 * 02951 * @param dest 02952 * New destination for the link. It must be a non-empty string, otherwise 02953 * this function doesn't modify previous destination. 02954 * @return 02955 * 1 on success, < 0 on error 02956 * 02957 * @since 0.6.2 02958 */ 02959 int iso_symlink_set_dest(IsoSymlink *link, const char *dest); 02960 02961 /** 02962 * Sets the order in which a node will be written on image. High weihted files 02963 * will be written first, so in a disc them will be written near the center. 02964 * 02965 * @param node 02966 * The node which weight will be changed. If it's a dir, this function 02967 * will change the weight of all its children. For nodes other that dirs 02968 * or regular files, this function has no effect. 02969 * @param w 02970 * The weight as a integer number, the greater this value is, the 02971 * closer from the begining of image the file will be written. 02972 * 02973 * @since 0.6.2 02974 */ 02975 void iso_node_set_sort_weight(IsoNode *node, int w); 02976 02977 /** 02978 * Get the sort weight of a file. 02979 * 02980 * @since 0.6.2 02981 */ 02982 int iso_file_get_sort_weight(IsoFile *file); 02983 02984 /** 02985 * Get the size of the file, in bytes 02986 * 02987 * @since 0.6.2 02988 */ 02989 off_t iso_file_get_size(IsoFile *file); 02990 02991 /** 02992 * Get the device id (major/minor numbers) of the given block or 02993 * character device file. The result is undefined for other kind 02994 * of special files, of first be sure iso_node_get_mode() returns either 02995 * S_IFBLK or S_IFCHR. 02996 * 02997 * @since 0.6.6 02998 */ 02999 dev_t iso_special_get_dev(IsoSpecial *special); 03000 03001 /** 03002 * Get the IsoStream that represents the contents of the given IsoFile. 03003 * The stream may be a filter stream which itself get its input from a 03004 * further stream. This may be inquired by iso_stream_get_input_stream(). 03005 * 03006 * If you iso_stream_open() the stream, iso_stream_close() it before 03007 * image generation begins. 03008 * 03009 * @return 03010 * The IsoStream. No extra ref is added, so the IsoStream belongs to the 03011 * IsoFile, and it may be freed together with it. Add your own ref with 03012 * iso_stream_ref() if you need it. 03013 * 03014 * @since 0.6.4 03015 */ 03016 IsoStream *iso_file_get_stream(IsoFile *file); 03017 03018 /** 03019 * Get the block lba of a file node, if it was imported from an old image. 03020 * 03021 * @param file 03022 * The file 03023 * @param lba 03024 * Will be filled with the kba 03025 * @param flag 03026 * Reserved for future usage, submit 0 03027 * @return 03028 * 1 if lba is valid (file comes from old image), 0 if file was newly 03029 * added, i.e. it does not come from an old image, < 0 error 03030 * 03031 * @since 0.6.4 03032 * 03033 * @deprecated Use iso_file_get_old_image_sections(), as this function does 03034 * not work with multi-extend files. 03035 */ 03036 int iso_file_get_old_image_lba(IsoFile *file, uint32_t *lba, int flag); 03037 03038 /** 03039 * Get the start addresses and the sizes of the data extents of a file node 03040 * if it was imported from an old image. 03041 * 03042 * @param file 03043 * The file 03044 * @param section_count 03045 * Returns the number of extent entries in sections array. 03046 * @param sections 03047 * Returns the array of file sections. Apply free() to dispose it. 03048 * @param flag 03049 * Reserved for future usage, submit 0 03050 * @return 03051 * 1 if there are valid extents (file comes from old image), 03052 * 0 if file was newly added, i.e. it does not come from an old image, 03053 * < 0 error 03054 * 03055 * @since 0.6.8 03056 */ 03057 int iso_file_get_old_image_sections(IsoFile *file, int *section_count, 03058 struct iso_file_section **sections, 03059 int flag); 03060 03061 /* 03062 * Like iso_file_get_old_image_lba(), but take an IsoNode. 03063 * 03064 * @return 03065 * 1 if lba is valid (file comes from old image), 0 if file was newly 03066 * added, i.e. it does not come from an old image, 2 node type has no 03067 * LBA (no regular file), < 0 error 03068 * 03069 * @since 0.6.4 03070 */ 03071 int iso_node_get_old_image_lba(IsoNode *node, uint32_t *lba, int flag); 03072 03073 /** 03074 * Add a new directory to the iso tree. Permissions, owner and hidden atts 03075 * are taken from parent, you can modify them later. 03076 * 03077 * @param parent 03078 * the dir where the new directory will be created 03079 * @param name 03080 * name for the new dir. If a node with same name already exists on 03081 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03082 * @param dir 03083 * place where to store a pointer to the newly created dir. No extra 03084 * ref is addded, so you will need to call iso_node_ref() if you really 03085 * need it. You can pass NULL in this parameter if you don't need the 03086 * pointer. 03087 * @return 03088 * number of nodes in parent if success, < 0 otherwise 03089 * Possible errors: 03090 * ISO_NULL_POINTER, if parent or name are NULL 03091 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03092 * ISO_OUT_OF_MEM 03093 * 03094 * @since 0.6.2 03095 */ 03096 int iso_tree_add_new_dir(IsoDir *parent, const char *name, IsoDir **dir); 03097 03098 /** 03099 * Add a new regular file to the iso tree. Permissions are set to 0444, 03100 * owner and hidden atts are taken from parent. You can modify any of them 03101 * later. 03102 * 03103 * @param parent 03104 * the dir where the new file will be created 03105 * @param name 03106 * name for the new file. If a node with same name already exists on 03107 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03108 * @param stream 03109 * IsoStream for the contents of the file. The reference will be taken 03110 * by the newly created file, you will need to take an extra ref to it 03111 * if you need it. 03112 * @param file 03113 * place where to store a pointer to the newly created file. No extra 03114 * ref is addded, so you will need to call iso_node_ref() if you really 03115 * need it. You can pass NULL in this parameter if you don't need the 03116 * pointer 03117 * @return 03118 * number of nodes in parent if success, < 0 otherwise 03119 * Possible errors: 03120 * ISO_NULL_POINTER, if parent, name or dest are NULL 03121 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03122 * ISO_OUT_OF_MEM 03123 * 03124 * @since 0.6.4 03125 */ 03126 int iso_tree_add_new_file(IsoDir *parent, const char *name, IsoStream *stream, 03127 IsoFile **file); 03128 03129 /** 03130 * Add a new symlink to the directory tree. Permissions are set to 0777, 03131 * owner and hidden atts are taken from parent. You can modify any of them 03132 * later. 03133 * 03134 * @param parent 03135 * the dir where the new symlink will be created 03136 * @param name 03137 * name for the new symlink. If a node with same name already exists on 03138 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03139 * @param dest 03140 * destination of the link 03141 * @param link 03142 * place where to store a pointer to the newly created link. No extra 03143 * ref is addded, so you will need to call iso_node_ref() if you really 03144 * need it. You can pass NULL in this parameter if you don't need the 03145 * pointer 03146 * @return 03147 * number of nodes in parent if success, < 0 otherwise 03148 * Possible errors: 03149 * ISO_NULL_POINTER, if parent, name or dest are NULL 03150 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03151 * ISO_OUT_OF_MEM 03152 * 03153 * @since 0.6.2 03154 */ 03155 int iso_tree_add_new_symlink(IsoDir *parent, const char *name, 03156 const char *dest, IsoSymlink **link); 03157 03158 /** 03159 * Add a new special file to the directory tree. As far as libisofs concerns, 03160 * an special file is a block device, a character device, a FIFO (named pipe) 03161 * or a socket. You can choose the specific kind of file you want to add 03162 * by setting mode propertly (see man 2 stat). 03163 * 03164 * Note that special files are only written to image when Rock Ridge 03165 * extensions are enabled. Moreover, a special file is just a directory entry 03166 * in the image tree, no data is written beyond that. 03167 * 03168 * Owner and hidden atts are taken from parent. You can modify any of them 03169 * later. 03170 * 03171 * @param parent 03172 * the dir where the new special file will be created 03173 * @param name 03174 * name for the new special file. If a node with same name already exists 03175 * on parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 03176 * @param mode 03177 * file type and permissions for the new node. Note that you can't 03178 * specify any kind of file here, only special types are allowed. i.e, 03179 * S_IFSOCK, S_IFBLK, S_IFCHR and S_IFIFO are valid types; S_IFLNK, 03180 * S_IFREG and S_IFDIR aren't. 03181 * @param dev 03182 * device ID, equivalent to the st_rdev field in man 2 stat. 03183 * @param special 03184 * place where to store a pointer to the newly created special file. No 03185 * extra ref is addded, so you will need to call iso_node_ref() if you 03186 * really need it. You can pass NULL in this parameter if you don't need 03187 * the pointer. 03188 * @return 03189 * number of nodes in parent if success, < 0 otherwise 03190 * Possible errors: 03191 * ISO_NULL_POINTER, if parent, name or dest are NULL 03192 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03193 * ISO_WRONG_ARG_VALUE if you select a incorrect mode 03194 * ISO_OUT_OF_MEM 03195 * 03196 * @since 0.6.2 03197 */ 03198 int iso_tree_add_new_special(IsoDir *parent, const char *name, mode_t mode, 03199 dev_t dev, IsoSpecial **special); 03200 03201 /** 03202 * Set whether to follow or not symbolic links when added a file from a source 03203 * to IsoImage. Default behavior is to not follow symlinks. 03204 * 03205 * @since 0.6.2 03206 */ 03207 void iso_tree_set_follow_symlinks(IsoImage *image, int follow); 03208 03209 /** 03210 * Get current setting for follow_symlinks. 03211 * 03212 * @see iso_tree_set_follow_symlinks 03213 * @since 0.6.2 03214 */ 03215 int iso_tree_get_follow_symlinks(IsoImage *image); 03216 03217 /** 03218 * Set whether to skip or not hidden files when adding a directory recursibely. 03219 * Default behavior is to not ignore them, i.e., to add hidden files to image. 03220 * 03221 * @since 0.6.2 03222 */ 03223 void iso_tree_set_ignore_hidden(IsoImage *image, int skip); 03224 03225 /** 03226 * Get current setting for ignore_hidden. 03227 * 03228 * @see iso_tree_set_ignore_hidden 03229 * @since 0.6.2 03230 */ 03231 int iso_tree_get_ignore_hidden(IsoImage *image); 03232 03233 /** 03234 * Set the replace mode, that defines the behavior of libisofs when adding 03235 * a node whit the same name that an existent one, during a recursive 03236 * directory addition. 03237 * 03238 * @since 0.6.2 03239 */ 03240 void iso_tree_set_replace_mode(IsoImage *image, enum iso_replace_mode mode); 03241 03242 /** 03243 * Get current setting for replace_mode. 03244 * 03245 * @see iso_tree_set_replace_mode 03246 * @since 0.6.2 03247 */ 03248 enum iso_replace_mode iso_tree_get_replace_mode(IsoImage *image); 03249 03250 /** 03251 * Set whether to skip or not special files. Default behavior is to not skip 03252 * them. Note that, despite of this setting, special files won't never be added 03253 * to an image unless RR extensions were enabled. 03254 * 03255 * @param skip 03256 * Bitmask to determine what kind of special files will be skipped: 03257 * bit0: ignore FIFOs 03258 * bit1: ignore Sockets 03259 * bit2: ignore char devices 03260 * bit3: ignore block devices 03261 * 03262 * @since 0.6.2 03263 */ 03264 void iso_tree_set_ignore_special(IsoImage *image, int skip); 03265 03266 /** 03267 * Get current setting for ignore_special. 03268 * 03269 * @see iso_tree_set_ignore_special 03270 * @since 0.6.2 03271 */ 03272 int iso_tree_get_ignore_special(IsoImage *image); 03273 03274 /** 03275 * Add a excluded path. These are paths that won't never added to image, 03276 * and will be excluded even when adding recursively its parent directory. 03277 * 03278 * For example, in 03279 * 03280 * iso_tree_add_exclude(image, "/home/user/data/private"); 03281 * iso_tree_add_dir_rec(image, root, "/home/user/data"); 03282 * 03283 * the directory /home/user/data/private won't be added to image. 03284 * 03285 * However, if you explicity add a deeper dir, it won't be excluded. i.e., 03286 * in the following example. 03287 * 03288 * iso_tree_add_exclude(image, "/home/user/data"); 03289 * iso_tree_add_dir_rec(image, root, "/home/user/data/private"); 03290 * 03291 * the directory /home/user/data/private is added. On the other, side, and 03292 * foollowing the the example above, 03293 * 03294 * iso_tree_add_dir_rec(image, root, "/home/user"); 03295 * 03296 * will exclude the directory "/home/user/data". 03297 * 03298 * Absolute paths are not mandatory, you can, for example, add a relative 03299 * path such as: 03300 * 03301 * iso_tree_add_exclude(image, "private"); 03302 * iso_tree_add_exclude(image, "user/data"); 03303 * 03304 * to excluve, respectively, all files or dirs named private, and also all 03305 * files or dirs named data that belong to a folder named "user". Not that the 03306 * above rule about deeper dirs is still valid. i.e., if you call 03307 * 03308 * iso_tree_add_dir_rec(image, root, "/home/user/data/music"); 03309 * 03310 * it is included even containing "user/data" string. However, a possible 03311 * "/home/user/data/music/user/data" is not added. 03312 * 03313 * Usual wildcards, such as * or ? are also supported, with the usual meaning 03314 * as stated in "man 7 glob". For example 03315 * 03316 * // to exclude backup text files 03317 * iso_tree_add_exclude(image, "*.~"); 03318 * 03319 * @return 03320 * 1 on success, < 0 on error 03321 * 03322 * @since 0.6.2 03323 */ 03324 int iso_tree_add_exclude(IsoImage *image, const char *path); 03325 03326 /** 03327 * Remove a previously added exclude. 03328 * 03329 * @see iso_tree_add_exclude 03330 * @return 03331 * 1 on success, 0 exclude do not exists, < 0 on error 03332 * 03333 * @since 0.6.2 03334 */ 03335 int iso_tree_remove_exclude(IsoImage *image, const char *path); 03336 03337 /** 03338 * Set a callback function that libisofs will call for each file that is 03339 * added to the given image by a recursive addition function. This includes 03340 * image import. 03341 * 03342 * @param report 03343 * pointer to a function that will be called just before a file will be 03344 * added to the image. You can control whether the file will be in fact 03345 * added or ignored. 03346 * This function should return 1 to add the file, 0 to ignore it and 03347 * continue, < 0 to abort the process 03348 * NULL is allowed if you don't want any callback. 03349 * 03350 * @since 0.6.2 03351 */ 03352 void iso_tree_set_report_callback(IsoImage *image, 03353 int (*report)(IsoImage*, IsoFileSource*)); 03354 03355 /** 03356 * Add a new node to the image tree, from an existing file. 03357 * 03358 * TODO comment Builder and Filesystem related issues when exposing both 03359 * 03360 * All attributes will be taken from the source file. The appropriate file 03361 * type will be created. 03362 * 03363 * @param image 03364 * The image 03365 * @param parent 03366 * The directory in the image tree where the node will be added. 03367 * @param path 03368 * The path of the file to add in the filesystem. 03369 * @param node 03370 * place where to store a pointer to the newly added file. No 03371 * extra ref is addded, so you will need to call iso_node_ref() if you 03372 * really need it. You can pass NULL in this parameter if you don't need 03373 * the pointer. 03374 * @return 03375 * number of nodes in parent if success, < 0 otherwise 03376 * Possible errors: 03377 * ISO_NULL_POINTER, if image, parent or path are NULL 03378 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03379 * ISO_OUT_OF_MEM 03380 * 03381 * @since 0.6.2 03382 */ 03383 int iso_tree_add_node(IsoImage *image, IsoDir *parent, const char *path, 03384 IsoNode **node); 03385 03386 /** 03387 * This is a more versatile form of iso_tree_add_node which allows to set 03388 * the node name in ISO image already when it gets added. 03389 * 03390 * Add a new node to the image tree, from an existing file, and with the 03391 * given name, that must not exist on dir. 03392 * 03393 * @param image 03394 * The image 03395 * @param parent 03396 * The directory in the image tree where the node will be added. 03397 * @param name 03398 * The name that the node will have on image. 03399 * @param path 03400 * The path of the file to add in the filesystem. 03401 * @param node 03402 * place where to store a pointer to the newly added file. No 03403 * extra ref is addded, so you will need to call iso_node_ref() if you 03404 * really need it. You can pass NULL in this parameter if you don't need 03405 * the pointer. 03406 * @return 03407 * number of nodes in parent if success, < 0 otherwise 03408 * Possible errors: 03409 * ISO_NULL_POINTER, if image, parent or path are NULL 03410 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03411 * ISO_OUT_OF_MEM 03412 * 03413 * @since 0.6.4 03414 */ 03415 int iso_tree_add_new_node(IsoImage *image, IsoDir *parent, const char *name, 03416 const char *path, IsoNode **node); 03417 03418 /** 03419 * Add a new node to the image tree, from an existing file, and with the 03420 * given name, that must not exist on dir. The node will be cut-out to the 03421 * submitted size, and its contents will be read from the given offset. This 03422 * function is thus suitable for adding only a piece of a file to the image. 03423 * 03424 * @param image 03425 * The image 03426 * @param parent 03427 * The directory in the image tree where the node will be added. 03428 * @param name 03429 * The name that the node will have on image. 03430 * @param path 03431 * The path of the file to add in the filesystem. For now only regular 03432 * files and symlinks to regular files are supported. 03433 * @param offset 03434 * Offset on the given file from where to start reading data. 03435 * @param size 03436 * Max size of the file. 03437 * @param node 03438 * place where to store a pointer to the newly added file. No 03439 * extra ref is addded, so you will need to call iso_node_ref() if you 03440 * really need it. You can pass NULL in this parameter if you don't need 03441 * the pointer. 03442 * @return 03443 * number of nodes in parent if success, < 0 otherwise 03444 * Possible errors: 03445 * ISO_NULL_POINTER, if image, parent or path are NULL 03446 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03447 * ISO_OUT_OF_MEM 03448 * 03449 * @since 0.6.4 03450 */ 03451 int iso_tree_add_new_cut_out_node(IsoImage *image, IsoDir *parent, 03452 const char *name, const char *path, 03453 off_t offset, off_t size, 03454 IsoNode **node); 03455 03456 /** 03457 * Add the contents of a dir to a given directory of the iso tree. 03458 * 03459 * There are several options to control what files are added or how they are 03460 * managed. Take a look at iso_tree_set_* functions to see diferent options 03461 * for recursive directory addition. 03462 * 03463 * TODO comment Builder and Filesystem related issues when exposing both 03464 * 03465 * @param image 03466 * The image to which the directory belong. 03467 * @param parent 03468 * Directory on the image tree where to add the contents of the dir 03469 * @param dir 03470 * Path to a dir in the filesystem 03471 * @return 03472 * number of nodes in parent if success, < 0 otherwise 03473 * 03474 * @since 0.6.2 03475 */ 03476 int iso_tree_add_dir_rec(IsoImage *image, IsoDir *parent, const char *dir); 03477 03478 /** 03479 * Locate a node by its path on image. 03480 * 03481 * @param node 03482 * Location for a pointer to the node, it will filled with NULL if the 03483 * given path does not exists on image. 03484 * The node will be owned by the image and shouldn't be unref(). Just call 03485 * iso_node_ref() to get your own reference to the node. 03486 * Note that you can pass NULL is the only thing you want to do is check 03487 * if a node with such path really exists. 03488 * @return 03489 * 1 found, 0 not found, < 0 error 03490 * 03491 * @since 0.6.2 03492 */ 03493 int iso_tree_path_to_node(IsoImage *image, const char *path, IsoNode **node); 03494 03495 /** 03496 * Get the path on image of the given node. 03497 * 03498 * @return 03499 * The path on the image, that must be freed when no more needed. If the 03500 * given node is not added to any image, this returns NULL. 03501 * @since 0.6.4 03502 */ 03503 char *iso_tree_get_node_path(IsoNode *node); 03504 03505 /** 03506 * Increments the reference counting of the given IsoDataSource. 03507 * 03508 * @since 0.6.2 03509 */ 03510 void iso_data_source_ref(IsoDataSource *src); 03511 03512 /** 03513 * Decrements the reference counting of the given IsoDataSource, freeing it 03514 * if refcount reach 0. 03515 * 03516 * @since 0.6.2 03517 */ 03518 void iso_data_source_unref(IsoDataSource *src); 03519 03520 /** 03521 * Create a new IsoDataSource from a local file. This is suitable for 03522 * accessing regular .iso images, or to acces drives via its block device 03523 * and standard POSIX I/O calls. 03524 * 03525 * @param path 03526 * The path of the file 03527 * @param src 03528 * Will be filled with the pointer to the newly created data source. 03529 * @return 03530 * 1 on success, < 0 on error. 03531 * 03532 * @since 0.6.2 03533 */ 03534 int iso_data_source_new_from_file(const char *path, IsoDataSource **src); 03535 03536 /** 03537 * Get the status of the buffer used by a burn_source. 03538 * 03539 * @param b 03540 * A burn_source previously obtained with 03541 * iso_image_create_burn_source(). 03542 * @param size 03543 * Will be filled with the total size of the buffer, in bytes 03544 * @param free_bytes 03545 * Will be filled with the bytes currently available in buffer 03546 * @return 03547 * < 0 error, > 0 state: 03548 * 1="active" : input and consumption are active 03549 * 2="ending" : input has ended without error 03550 * 3="failing" : input had error and ended, 03551 * 5="abandoned" : consumption has ended prematurely 03552 * 6="ended" : consumption has ended without input error 03553 * 7="aborted" : consumption has ended after input error 03554 * 03555 * @since 0.6.2 03556 */ 03557 int iso_ring_buffer_get_status(struct burn_source *b, size_t *size, 03558 size_t *free_bytes); 03559 03560 #define ISO_MSGS_MESSAGE_LEN 4096 03561 03562 /** 03563 * Control queueing and stderr printing of messages from libisofs. 03564 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 03565 * "NOTE", "UPDATE", "DEBUG", "ALL". 03566 * 03567 * @param queue_severity Gives the minimum limit for messages to be queued. 03568 * Default: "NEVER". If you queue messages then you 03569 * must consume them by iso_msgs_obtain(). 03570 * @param print_severity Does the same for messages to be printed directly 03571 * to stderr. 03572 * @param print_id A text prefix to be printed before the message. 03573 * @return >0 for success, <=0 for error 03574 * 03575 * @since 0.6.2 03576 */ 03577 int iso_set_msgs_severities(char *queue_severity, char *print_severity, 03578 char *print_id); 03579 03580 /** 03581 * Obtain the oldest pending libisofs message from the queue which has at 03582 * least the given minimum_severity. This message and any older message of 03583 * lower severity will get discarded from the queue and is then lost forever. 03584 * 03585 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 03586 * "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER" 03587 * will discard the whole queue. 03588 * 03589 * @param error_code 03590 * Will become a unique error code as listed at the end of this header 03591 * @param imgid 03592 * Id of the image that was issued the message. 03593 * @param msg_text 03594 * Must provide at least ISO_MSGS_MESSAGE_LEN bytes. 03595 * @param severity 03596 * Will become the severity related to the message and should provide at 03597 * least 80 bytes. 03598 * @return 03599 * 1 if a matching item was found, 0 if not, <0 for severe errors 03600 * 03601 * @since 0.6.2 03602 */ 03603 int iso_obtain_msgs(char *minimum_severity, int *error_code, int *imgid, 03604 char msg_text[], char severity[]); 03605 03606 03607 /** 03608 * Submit a message to the libisofs queueing system. It will be queued or 03609 * printed as if it was generated by libisofs itself. 03610 * 03611 * @param error_code 03612 * The unique error code of your message. 03613 * Submit 0 if you do not have reserved error codes within the libburnia 03614 * project. 03615 * @param msg_text 03616 * Not more than ISO_MSGS_MESSAGE_LEN characters of message text. 03617 * @param os_errno 03618 * Eventual errno related to the message. Submit 0 if the message is not 03619 * related to a operating system error. 03620 * @param severity 03621 * One of "ABORT", "FATAL", "FAILURE", "SORRY", "WARNING", "HINT", "NOTE", 03622 * "UPDATE", "DEBUG". Defaults to "FATAL". 03623 * @param origin 03624 * Submit 0 for now. 03625 * @return 03626 * 1 if message was delivered, <=0 if failure 03627 * 03628 * @since 0.6.4 03629 */ 03630 int iso_msgs_submit(int error_code, char msg_text[], int os_errno, 03631 char severity[], int origin); 03632 03633 03634 /** 03635 * Convert a severity name into a severity number, which gives the severity 03636 * rank of the name. 03637 * 03638 * @param severity_name 03639 * A name as with iso_msgs_submit(), e.g. "SORRY". 03640 * @param severity_number 03641 * The rank number: the higher, the more severe. 03642 * @return 03643 * >0 success, <=0 failure 03644 * 03645 * @since 0.6.4 03646 */ 03647 int iso_text_to_sev(char *severity_name, int *severity_number); 03648 03649 03650 /** 03651 * Convert a severity number into a severity name 03652 * 03653 * @param severity_number 03654 * The rank number: the higher, the more severe. 03655 * @param severity_name 03656 * A name as with iso_msgs_submit(), e.g. "SORRY". 03657 * 03658 * @since 0.6.4 03659 */ 03660 int iso_sev_to_text(int severity_number, char **severity_name); 03661 03662 03663 /** 03664 * Get the id of an IsoImage, used for message reporting. This message id, 03665 * retrieved with iso_obtain_msgs(), can be used to distinguish what 03666 * IsoImage has isssued a given message. 03667 * 03668 * @since 0.6.2 03669 */ 03670 int iso_image_get_msg_id(IsoImage *image); 03671 03672 /** 03673 * Get a textual description of a libisofs error. 03674 * 03675 * @since 0.6.2 03676 */ 03677 const char *iso_error_to_msg(int errcode); 03678 03679 /** 03680 * Get the severity of a given error code 03681 * @return 03682 * 0x10000000 -> DEBUG 03683 * 0x20000000 -> UPDATE 03684 * 0x30000000 -> NOTE 03685 * 0x40000000 -> HINT 03686 * 0x50000000 -> WARNING 03687 * 0x60000000 -> SORRY 03688 * 0x64000000 -> MISHAP 03689 * 0x68000000 -> FAILURE 03690 * 0x70000000 -> FATAL 03691 * 0x71000000 -> ABORT 03692 * 03693 * @since 0.6.2 03694 */ 03695 int iso_error_get_severity(int e); 03696 03697 /** 03698 * Get the priority of a given error. 03699 * @return 03700 * 0x00000000 -> ZERO 03701 * 0x10000000 -> LOW 03702 * 0x20000000 -> MEDIUM 03703 * 0x30000000 -> HIGH 03704 * 03705 * @since 0.6.2 03706 */ 03707 int iso_error_get_priority(int e); 03708 03709 /** 03710 * Get the message queue code of a libisofs error. 03711 */ 03712 int iso_error_get_code(int e); 03713 03714 /** 03715 * Set the minimum error severity that causes a libisofs operation to 03716 * be aborted as soon as possible. 03717 * 03718 * @param severity 03719 * one of "FAILURE", "MISHAP", "SORRY", "WARNING", "HINT", "NOTE". 03720 * Severities greater or equal than FAILURE always cause program to abort. 03721 * Severities under NOTE won't never cause function abort. 03722 * @return 03723 * Previous abort priority on success, < 0 on error. 03724 * 03725 * @since 0.6.2 03726 */ 03727 int iso_set_abort_severity(char *severity); 03728 03729 /** 03730 * Return the messenger object handle used by libisofs. This handle 03731 * may be used by related libraries to their own compatible 03732 * messenger objects and thus to direct their messages to the libisofs 03733 * message queue. See also: libburn, API function burn_set_messenger(). 03734 * 03735 * @return the handle. Do only use with compatible 03736 * 03737 * @since 0.6.2 03738 */ 03739 void *iso_get_messenger(); 03740 03741 /** 03742 * Take a ref to the given IsoFileSource. 03743 * 03744 * @since 0.6.2 03745 */ 03746 void iso_file_source_ref(IsoFileSource *src); 03747 03748 /** 03749 * Drop your ref to the given IsoFileSource, eventually freeing the associated 03750 * system resources. 03751 * 03752 * @since 0.6.2 03753 */ 03754 void iso_file_source_unref(IsoFileSource *src); 03755 03756 /* 03757 * this are just helpers to invoque methods in class 03758 */ 03759 03760 /** 03761 * Get the path, relative to the filesystem this file source 03762 * belongs to. 03763 * 03764 * @return 03765 * the path of the FileSource inside the filesystem, it should be 03766 * freed when no more needed. 03767 * 03768 * @since 0.6.2 03769 */ 03770 char* iso_file_source_get_path(IsoFileSource *src); 03771 03772 /** 03773 * Get the name of the file, with the dir component of the path. 03774 * 03775 * @return 03776 * the name of the file, it should be freed when no more needed. 03777 * 03778 * @since 0.6.2 03779 */ 03780 char* iso_file_source_get_name(IsoFileSource *src); 03781 03782 /** 03783 * Get information about the file. 03784 * @return 03785 * 1 success, < 0 error 03786 * Error codes: 03787 * ISO_FILE_ACCESS_DENIED 03788 * ISO_FILE_BAD_PATH 03789 * ISO_FILE_DOESNT_EXIST 03790 * ISO_OUT_OF_MEM 03791 * ISO_FILE_ERROR 03792 * ISO_NULL_POINTER 03793 * 03794 * @since 0.6.2 03795 */ 03796 int iso_file_source_lstat(IsoFileSource *src, struct stat *info); 03797 03798 /** 03799 * Check if the process has access to read file contents. Note that this 03800 * is not necessarily related with (l)stat functions. For example, in a 03801 * filesystem implementation to deal with an ISO image, if the user has 03802 * read access to the image it will be able to read all files inside it, 03803 * despite of the particular permission of each file in the RR tree, that 03804 * are what the above functions return. 03805 * 03806 * @return 03807 * 1 if process has read access, < 0 on error 03808 * Error codes: 03809 * ISO_FILE_ACCESS_DENIED 03810 * ISO_FILE_BAD_PATH 03811 * ISO_FILE_DOESNT_EXIST 03812 * ISO_OUT_OF_MEM 03813 * ISO_FILE_ERROR 03814 * ISO_NULL_POINTER 03815 * 03816 * @since 0.6.2 03817 */ 03818 int iso_file_source_access(IsoFileSource *src); 03819 03820 /** 03821 * Get information about the file. If the file is a symlink, the info 03822 * returned refers to the destination. 03823 * 03824 * @return 03825 * 1 success, < 0 error 03826 * Error codes: 03827 * ISO_FILE_ACCESS_DENIED 03828 * ISO_FILE_BAD_PATH 03829 * ISO_FILE_DOESNT_EXIST 03830 * ISO_OUT_OF_MEM 03831 * ISO_FILE_ERROR 03832 * ISO_NULL_POINTER 03833 * 03834 * @since 0.6.2 03835 */ 03836 int iso_file_source_stat(IsoFileSource *src, struct stat *info); 03837 03838 /** 03839 * Opens the source. 03840 * @return 1 on success, < 0 on error 03841 * Error codes: 03842 * ISO_FILE_ALREADY_OPENED 03843 * ISO_FILE_ACCESS_DENIED 03844 * ISO_FILE_BAD_PATH 03845 * ISO_FILE_DOESNT_EXIST 03846 * ISO_OUT_OF_MEM 03847 * ISO_FILE_ERROR 03848 * ISO_NULL_POINTER 03849 * 03850 * @since 0.6.2 03851 */ 03852 int iso_file_source_open(IsoFileSource *src); 03853 03854 /** 03855 * Close a previuously openned file 03856 * @return 1 on success, < 0 on error 03857 * Error codes: 03858 * ISO_FILE_ERROR 03859 * ISO_NULL_POINTER 03860 * ISO_FILE_NOT_OPENED 03861 * 03862 * @since 0.6.2 03863 */ 03864 int iso_file_source_close(IsoFileSource *src); 03865 03866 /** 03867 * Attempts to read up to count bytes from the given source into 03868 * the buffer starting at buf. 03869 * 03870 * The file src must be open() before calling this, and close() when no 03871 * more needed. Not valid for dirs. On symlinks it reads the destination 03872 * file. 03873 * 03874 * @param src 03875 * The given source 03876 * @param buf 03877 * Pointer to a buffer of at least count bytes where the read data will be 03878 * stored 03879 * @param count 03880 * Bytes to read 03881 * @return 03882 * number of bytes read, 0 if EOF, < 0 on error 03883 * Error codes: 03884 * ISO_FILE_ERROR 03885 * ISO_NULL_POINTER 03886 * ISO_FILE_NOT_OPENED 03887 * ISO_WRONG_ARG_VALUE -> if count == 0 03888 * ISO_FILE_IS_DIR 03889 * ISO_OUT_OF_MEM 03890 * ISO_INTERRUPTED 03891 * 03892 * @since 0.6.2 03893 */ 03894 int iso_file_source_read(IsoFileSource *src, void *buf, size_t count); 03895 03896 /** 03897 * Repositions the offset of the given IsoFileSource (must be opened) to the 03898 * given offset according to the value of flag. 03899 * 03900 * @param offset 03901 * in bytes 03902 * @param flag 03903 * 0 The offset is set to offset bytes (SEEK_SET) 03904 * 1 The offset is set to its current location plus offset bytes 03905 * (SEEK_CUR) 03906 * 2 The offset is set to the size of the file plus offset bytes 03907 * (SEEK_END). 03908 * @return 03909 * Absolute offset posistion on the file, or < 0 on error. Cast the 03910 * returning value to int to get a valid libisofs error. 03911 * @since 0.6.4 03912 */ 03913 off_t iso_file_source_lseek(IsoFileSource *src, off_t offset, int flag); 03914 03915 /** 03916 * Read a directory. 03917 * 03918 * Each call to this function will return a new children, until we reach 03919 * the end of file (i.e, no more children), in that case it returns 0. 03920 * 03921 * The dir must be open() before calling this, and close() when no more 03922 * needed. Only valid for dirs. 03923 * 03924 * Note that "." and ".." children MUST NOT BE returned. 03925 * 03926 * @param child 03927 * pointer to be filled with the given child. Undefined on error or OEF 03928 * @return 03929 * 1 on success, 0 if EOF (no more children), < 0 on error 03930 * Error codes: 03931 * ISO_FILE_ERROR 03932 * ISO_NULL_POINTER 03933 * ISO_FILE_NOT_OPENED 03934 * ISO_FILE_IS_NOT_DIR 03935 * ISO_OUT_OF_MEM 03936 * 03937 * @since 0.6.2 03938 */ 03939 int iso_file_source_readdir(IsoFileSource *src, IsoFileSource **child); 03940 03941 /** 03942 * Read the destination of a symlink. You don't need to open the file 03943 * to call this. 03944 * 03945 * @param src 03946 * An IsoFileSource corresponding to a symbolic link. 03947 * @param buf 03948 * allocated buffer of at least bufsiz bytes. 03949 * The dest. will be copied there, and it will be NULL-terminated 03950 * @param bufsiz 03951 * characters to be copied. Destination link will be truncated if 03952 * it is larger than given size. This include the '\0' character. 03953 * @return 03954 * 1 on success, < 0 on error 03955 * Error codes: 03956 * ISO_FILE_ERROR 03957 * ISO_NULL_POINTER 03958 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 03959 * ISO_FILE_IS_NOT_SYMLINK 03960 * ISO_OUT_OF_MEM 03961 * ISO_FILE_BAD_PATH 03962 * ISO_FILE_DOESNT_EXIST 03963 * 03964 * @since 0.6.2 03965 */ 03966 int iso_file_source_readlink(IsoFileSource *src, char *buf, size_t bufsiz); 03967 03968 03969 /** 03970 * Get the AAIP string with encoded ACL and xattr. 03971 * (Not to be confused with ECMA-119 Extended Attributes). 03972 * @param src The file source object to be inquired. 03973 * @param aa_string Returns a pointer to the AAIP string data. If no AAIP 03974 * string is available, *aa_string becomes NULL. 03975 * (See doc/susp_aaip_2_0.txt for the meaning of AAIP.) 03976 * The caller is responsible for finally calling free() 03977 * on non-NULL results. 03978 * @param flag Bitfield for control purposes 03979 * bit0= Transfer ownership of AAIP string data. 03980 * src will free the eventual cached data and might 03981 * not be able to produce it again. 03982 * bit1= No need to get ACL (but no guarantee of exclusion) 03983 * bit2= No need to get xattr (but no guarantee of exclusion) 03984 * @return 1 means success (*aa_string == NULL is possible) 03985 * <0 means failure and must b a valid libisofs error code 03986 * (e.g. ISO_FILE_ERROR if no better one can be found). 03987 * @since 0.6.14 03988 */ 03989 int iso_file_source_get_aa_string(IsoFileSource *src, 03990 unsigned char **aa_string, int flag); 03991 03992 /** 03993 * Get the filesystem for this source. No extra ref is added, so you 03994 * musn't unref the IsoFilesystem. 03995 * 03996 * @return 03997 * The filesystem, NULL on error 03998 * 03999 * @since 0.6.2 04000 */ 04001 IsoFilesystem* iso_file_source_get_filesystem(IsoFileSource *src); 04002 04003 /** 04004 * Take a ref to the given IsoFilesystem 04005 * 04006 * @since 0.6.2 04007 */ 04008 void iso_filesystem_ref(IsoFilesystem *fs); 04009 04010 /** 04011 * Drop your ref to the given IsoFilesystem, evetually freeing associated 04012 * resources. 04013 * 04014 * @since 0.6.2 04015 */ 04016 void iso_filesystem_unref(IsoFilesystem *fs); 04017 04018 /** 04019 * Create a new IsoFilesystem to access a existent ISO image. 04020 * 04021 * @param src 04022 * Data source to access data. 04023 * @param opts 04024 * Image read options 04025 * @param msgid 04026 * An image identifer, obtained with iso_image_get_msg_id(), used to 04027 * associated messages issued by the filesystem implementation with an 04028 * existent image. If you are not using this filesystem in relation with 04029 * any image context, just use 0x1fffff as the value for this parameter. 04030 * @param fs 04031 * Will be filled with a pointer to the filesystem that can be used 04032 * to access image contents. 04033 * @param 04034 * 1 on success, < 0 on error 04035 * 04036 * @since 0.6.2 04037 */ 04038 int iso_image_filesystem_new(IsoDataSource *src, IsoReadOpts *opts, int msgid, 04039 IsoImageFilesystem **fs); 04040 04041 /** 04042 * Get the volset identifier for an existent image. The returned string belong 04043 * to the IsoImageFilesystem and shouldn't be free() nor modified. 04044 * 04045 * @since 0.6.2 04046 */ 04047 const char *iso_image_fs_get_volset_id(IsoImageFilesystem *fs); 04048 04049 /** 04050 * Get the volume identifier for an existent image. The returned string belong 04051 * to the IsoImageFilesystem and shouldn't be free() nor modified. 04052 * 04053 * @since 0.6.2 04054 */ 04055 const char *iso_image_fs_get_volume_id(IsoImageFilesystem *fs); 04056 04057 /** 04058 * Get the publisher identifier for an existent image. The returned string 04059 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04060 * 04061 * @since 0.6.2 04062 */ 04063 const char *iso_image_fs_get_publisher_id(IsoImageFilesystem *fs); 04064 04065 /** 04066 * Get the data preparer identifier for an existent image. The returned string 04067 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04068 * 04069 * @since 0.6.2 04070 */ 04071 const char *iso_image_fs_get_data_preparer_id(IsoImageFilesystem *fs); 04072 04073 /** 04074 * Get the system identifier for an existent image. The returned string belong 04075 * to the IsoImageFilesystem and shouldn't be free() nor modified. 04076 * 04077 * @since 0.6.2 04078 */ 04079 const char *iso_image_fs_get_system_id(IsoImageFilesystem *fs); 04080 04081 /** 04082 * Get the application identifier for an existent image. The returned string 04083 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04084 * 04085 * @since 0.6.2 04086 */ 04087 const char *iso_image_fs_get_application_id(IsoImageFilesystem *fs); 04088 04089 /** 04090 * Get the copyright file identifier for an existent image. The returned string 04091 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04092 * 04093 * @since 0.6.2 04094 */ 04095 const char *iso_image_fs_get_copyright_file_id(IsoImageFilesystem *fs); 04096 04097 /** 04098 * Get the abstract file identifier for an existent image. The returned string 04099 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04100 * 04101 * @since 0.6.2 04102 */ 04103 const char *iso_image_fs_get_abstract_file_id(IsoImageFilesystem *fs); 04104 04105 /** 04106 * Get the biblio file identifier for an existent image. The returned string 04107 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 04108 * 04109 * @since 0.6.2 04110 */ 04111 const char *iso_image_fs_get_biblio_file_id(IsoImageFilesystem *fs); 04112 04113 /** 04114 * Increment reference count of an IsoStream. 04115 * 04116 * @since 0.6.4 04117 */ 04118 void iso_stream_ref(IsoStream *stream); 04119 04120 /** 04121 * Decrement reference count of an IsoStream, and eventually free it if 04122 * refcount reach 0. 04123 * 04124 * @since 0.6.4 04125 */ 04126 void iso_stream_unref(IsoStream *stream); 04127 04128 /** 04129 * Opens the given stream. Remember to close the Stream before writing the 04130 * image. 04131 * 04132 * @return 04133 * 1 on success, 2 file greater than expected, 3 file smaller than 04134 * expected, < 0 on error 04135 * 04136 * @since 0.6.4 04137 */ 04138 int iso_stream_open(IsoStream *stream); 04139 04140 /** 04141 * Close a previously openned IsoStream. 04142 * 04143 * @return 04144 * 1 on success, < 0 on error 04145 * 04146 * @since 0.6.4 04147 */ 04148 int iso_stream_close(IsoStream *stream); 04149 04150 /** 04151 * Get the size of a given stream. This function should always return the same 04152 * size, even if the underlying source size changes, unless you call 04153 * iso_stream_update_size(). 04154 * 04155 * @return 04156 * IsoStream size in bytes 04157 * 04158 * @since 0.6.4 04159 */ 04160 off_t iso_stream_get_size(IsoStream *stream); 04161 04162 /** 04163 * Attempts to read up to count bytes from the given stream into 04164 * the buffer starting at buf. 04165 * 04166 * The stream must be open() before calling this, and close() when no 04167 * more needed. 04168 * 04169 * @return 04170 * number of bytes read, 0 if EOF, < 0 on error 04171 * 04172 * @since 0.6.4 04173 */ 04174 int iso_stream_read(IsoStream *stream, void *buf, size_t count); 04175 04176 /** 04177 * Whether the given IsoStream can be read several times, with the same 04178 * results. 04179 * For example, a regular file is repeatable, you can read it as many 04180 * times as you want. However, a pipe isn't. 04181 * 04182 * This function doesn't take into account if the file has been modified 04183 * between the two reads. 04184 * 04185 * @return 04186 * 1 if stream is repeatable, 0 if not, < 0 on error 04187 * 04188 * @since 0.6.4 04189 */ 04190 int iso_stream_is_repeatable(IsoStream *stream); 04191 04192 /** 04193 * Updates the size of the IsoStream with the current size of the 04194 * underlying source. 04195 * 04196 * @return 04197 * 1 if ok, < 0 on error (has to be a valid libisofs error code), 04198 * 0 if the IsoStream does not support this function. 04199 * @since 0.6.8 04200 */ 04201 int iso_stream_update_size(IsoStream *stream); 04202 04203 /** 04204 * Get an unique identifier for a given IsoStream. 04205 * 04206 * @since 0.6.4 04207 */ 04208 void iso_stream_get_id(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, 04209 ino_t *ino_id); 04210 04211 /** 04212 * Try to get eventual source path string of a stream. Meaning and availability 04213 * of this string depends on the stream.class . Expect valid results with 04214 * types "fsrc" and "cout". Result formats are 04215 * fsrc: result of file_source_get_path() 04216 * cout: result of file_source_get_path() " " offset " " size 04217 * @param stream 04218 * The stream to be inquired. 04219 * @param flag 04220 * Bitfield for control purposes, unused yet, submit 0 04221 * @return 04222 * A copy of the path string. Apply free() when no longer needed. 04223 * NULL if no path string is available. 04224 * 04225 * @since 0.6.18 04226 */ 04227 char *iso_stream_get_source_path(IsoStream *stream, int flag); 04228 04229 /** 04230 * Compare two streams whether they are based on the same input and will 04231 * produce the same output. If in any doubt, then this comparison will 04232 * indicate no match. 04233 * 04234 * @param s1 04235 * The first stream to compare. 04236 * @param s2 04237 * The second stream to compare. 04238 * @return 04239 * -1 if s1 is smaller s2 , 0 if s1 matches s2 , 1 if s1 is larger s2 04240 * @param flag 04241 * bit0= do not use s1->class->compare() even if available 04242 * (e.g. because iso_stream_cmp_ino(0 is called as fallback 04243 * from said stream->class->compare()) 04244 * 04245 * @since 0.6.20 04246 */ 04247 int iso_stream_cmp_ino(IsoStream *s1, IsoStream *s2, int flag); 04248 04249 /* --------------------------------- AAIP --------------------------------- */ 04250 04251 /** 04252 * Function to identify and manage AAIP strings as xinfo of IsoNode. 04253 * 04254 * An AAIP string contains the Attribute List with the xattr and ACL of a node 04255 * in the image tree. It is formatted according to libisofs specification 04256 * AAIP-2.0 and ready to be written into the System Use Area resp. Continuation 04257 * Area of a directory entry in an ISO image. 04258 * 04259 * Applications are not supposed to manipulate AAIP strings directly. 04260 * They should rather make use of the appropriate iso_node_get_* and 04261 * iso_node_set_* calls. 04262 * 04263 * AAIP represents ACLs as xattr with empty name and AAIP-specific binary 04264 * content. Local filesystems may represent ACLs as xattr with names like 04265 * "system.posix_acl_access". libisofs does not interpret those local 04266 * xattr representations of ACL directly but rather uses the ACL interface of 04267 * the local system. By default the local xattr representations of ACL will 04268 * not become part of the AAIP Attribute List via iso_local_get_attrs() and 04269 * not be attached to local files via iso_local_set_attrs(). 04270 * 04271 * @since 0.6.14 04272 */ 04273 int aaip_xinfo_func(void *data, int flag); 04274 04275 04276 /** 04277 * Get the eventual ACLs which are associated with the node. 04278 * The result will be in "long" text form as of man acl resp. acl_to_text(). 04279 * Call this function with flag bit15 to finally release the memory 04280 * occupied by an ACL inquiry. 04281 * 04282 * @param node 04283 * The node that is to be inquired. 04284 * @param access_text 04285 * Will return a pointer to the eventual "access" ACL text or NULL if it 04286 * is not available and flag bit 4 is set. 04287 * @param default_text 04288 * Will return a pointer to the eventual "default" ACL or NULL if it 04289 * is not available. 04290 * (Linux directories can have a "default" ACL which influences 04291 * the permissions of newly created files.) 04292 * @param flag 04293 * Bitfield for control purposes 04294 * bit4= if no "access" ACL is available: return *access_text == NULL 04295 * else: produce ACL from stat(2) permissions 04296 * bit15= free memory and return 1 (node may be NULL) 04297 * @return 04298 * 2 *access_text was produced from stat(2) permissions 04299 * 1 *access_text was produced from ACL of node 04300 * 0 if flag bit4 is set and no ACL is available 04301 * < 0 on error 04302 * 04303 * @since 0.6.14 04304 */ 04305 int iso_node_get_acl_text(IsoNode *node, 04306 char **access_text, char **default_text, int flag); 04307 04308 04309 /** 04310 * Set the ACLs of the given node to the lists in parameters access_text and 04311 * default_text or delete them. 04312 * 04313 * The stat(2) permission bits get updated according to the new "access" ACL if 04314 * neither bit1 of parameter flag is set nor parameter access_text is NULL. 04315 * Note that S_IRWXG permission bits correspond to ACL mask permissions 04316 * if a "mask::" entry exists in the ACL. Only if there is no "mask::" then 04317 * the "group::" entry corresponds to to S_IRWXG. 04318 * 04319 * @param node 04320 * The node that is to be manipulated. 04321 * @param access_text 04322 * The text to be set into effect as "access" ACL. NULL will delete an 04323 * eventually existing "access" ACL of the node. 04324 * @param default_text 04325 * The text to be set into effect as "default" ACL. NULL will delete an 04326 * eventually existing "default" ACL of the node. 04327 * (Linux directories can have a "default" ACL which influences 04328 * the permissions of newly created files.) 04329 * @param flag 04330 * Bitfield for control purposes 04331 * bit1= ignore text parameters but rather update eventual "access" ACL 04332 * to the stat(2) permissions of node. If no "access" ACL exists, 04333 * then do nothing and return success. 04334 * @return 04335 * > 0 success 04336 * < 0 failure 04337 * 04338 * @since 0.6.14 04339 */ 04340 int iso_node_set_acl_text(IsoNode *node, 04341 char *access_text, char *default_text, int flag); 04342 04343 /** 04344 * Like iso_node_get_permissions but reflecting ACL entry "group::" in S_IRWXG 04345 * rather than ACL entry "mask::". This is necessary if the permissions of a 04346 * node with ACL shall be restored to a filesystem without restoring the ACL. 04347 * The same mapping happens internally when the ACL of a node is deleted. 04348 * If the node has no ACL then the result is iso_node_get_permissions(node). 04349 * @param node 04350 * The node that is to be inquired. 04351 * @return 04352 * Permission bits as of stat(2) 04353 * 04354 * @since 0.6.14 04355 */ 04356 mode_t iso_node_get_perms_wo_acl(const IsoNode *node); 04357 04358 04359 /** 04360 * Get the list of xattr which is associated with the node. 04361 * The resulting data may finally be disposed by a call to this function 04362 * with flag bit15 set, or its components may be freed one-by-one. 04363 * The following values are either NULL or malloc() memory: 04364 * *names, *value_lengths, *values, (*names)[i], (*values)[i] 04365 * with 0 <= i < *num_attrs. 04366 * It is allowed to replace or reallocate those memory items in order to 04367 * to manipulate the attribute list before submitting it to other calls. 04368 * 04369 * If enabled by flag bit0, this list possibly includes the ACLs of the node. 04370 * They are eventually encoded in a pair with empty name. It is not advisable 04371 * to alter the value or name of that pair. One may decide to erase both ACLs 04372 * by deleting this pair or to copy both ACLs by copying the content of this 04373 * pair to an empty named pair of another node. 04374 * For all other ACL purposes use iso_node_get_acl_text(). 04375 * 04376 * @param node 04377 * The node that is to be inquired. 04378 * @param num_attrs 04379 * Will return the number of name-value pairs 04380 * @param names 04381 * Will return an array of pointers to 0-terminated names 04382 * @param value_lengths 04383 * Will return an arry with the lenghts of values 04384 * @param values 04385 * Will return an array of pointers to strings of 8-bit bytes 04386 * @param flag 04387 * Bitfield for control purposes 04388 * bit0= obtain eventual ACLs as attribute with empty name 04389 * bit2= with bit0: do not obtain attributes other than ACLs 04390 * bit15= free memory (node may be NULL) 04391 * @return 04392 * 1 = ok (but *num_attrs may be 0) 04393 * < 0 = error 04394 * 04395 * @since 0.6.14 04396 */ 04397 int iso_node_get_attrs(IsoNode *node, size_t *num_attrs, 04398 char ***names, size_t **value_lengths, char ***values, int flag); 04399 04400 04401 /** 04402 * Obtain the value of a particular xattr name. Eventually make a copy of 04403 * that value and add a trailing 0 byte for caller convenience. 04404 * @param node 04405 * The node that is to be inquired. 04406 * @param name 04407 * The xattr name that shall be looked up. 04408 * @param value_length 04409 * Will return the lenght of value 04410 * @param value 04411 * Will return a string of 8-bit bytes. free() it when no longer needed. 04412 * @param flag 04413 * Bitfield for control purposes, unused yet, submit 0 04414 * @return 04415 * 1= name found , 0= name not found , <0 indicates error error 04416 * 04417 * @since 0.6.18 04418 */ 04419 int iso_node_lookup_attr(IsoNode *node, char *name, 04420 size_t *value_length, char **value, int flag); 04421 04422 /** 04423 * Set the list of xattr which is associated with the node. 04424 * The data get copied so that you may dispose your input data afterwards. 04425 * 04426 * If enabled by flag bit0 then the submitted list of attributes will not only 04427 * overwrite xattr but also both eventual ACLs of the node. Eventual ACL in 04428 * the submitted list have to reside in an attribute with empty name. 04429 * 04430 * @param node 04431 * The node that is to be manipulated. 04432 * @param num_attrs 04433 * Number of attributes 04434 * @param names 04435 * Array of pointers to 0 terminated name strings 04436 * @param value_lengths 04437 * Array of byte lengths for each value 04438 * @param values 04439 * Array of pointers to the value bytes 04440 * @param flag 04441 * Bitfield for control purposes 04442 * bit0= Do not maintain eventual existing ACL of the node. 04443 * Set eventual new ACL from value of empty name. 04444 * bit1= Do not clear the existing attribute list but merge it with 04445 * the list given by this call 04446 * bit2= Delete the attributes with the given names 04447 * bit3= Allow to affect non-user attributes. 04448 * I.e. those with a non-empty name which does not begin by "user." 04449 * (The empty name is always allowed and governed by bit0.) This 04450 * deletes all previously existing attributes if not bit1 is set. 04451 * @return 04452 * 1 = ok 04453 * < 0 = error 04454 * 04455 * @since 0.6.14 04456 */ 04457 int iso_node_set_attrs(IsoNode *node, size_t num_attrs, char **names, 04458 size_t *value_lengths, char **values, int flag); 04459 04460 04461 /* ----- This is an interface to ACL and xattr of the local filesystem ----- */ 04462 04463 /** 04464 * libisofs has an internal system dependent adapter to ACL and xattr 04465 * operations. For the sake of completeness and simplicity it exposes this 04466 * functionality to its applications which might want to get and set ACLs 04467 * from local files. 04468 */ 04469 04470 /** 04471 * Get an ACL of the given file in the local filesystem in long text form. 04472 * 04473 * @param disk_path 04474 * Path to the file 04475 * @param text 04476 * Will return a pointer to the ACL text. If not NULL the text will be 04477 * 0 terminated and finally has to be disposed by a call to this function 04478 * with bit15 set. 04479 * @param flag 04480 * Bitfield for control purposes 04481 * bit0= get "default" ACL rather than "access" ACL 04482 * bit4= set *text = NULL and return 2 04483 * if the ACL matches st_mode permissions. 04484 * bit5= in case of symbolic link: inquire link target 04485 * bit15= free text and return 1 04486 * @return 04487 * 1 ok 04488 * 2 ok, trivial ACL found while bit4 is set, *text is NULL 04489 * 0 no ACL manipulation adapter available 04490 * -1 failure of system ACL service (see errno) 04491 * -2 attempt to inquire ACL of a symbolic link without bit4 or bit5 04492 * resp. with no suitable link target 04493 * 04494 * @since 0.6.14 04495 */ 04496 int iso_local_get_acl_text(char *disk_path, char **text, int flag); 04497 04498 04499 /** 04500 * Set the ACL of the given file in the local filesystem to a given list 04501 * in long text form. 04502 * 04503 * @param disk_path 04504 * Path to the file 04505 * @param text 04506 * The input text (0 terminated, ACL long text form) 04507 * @param flag 04508 * Bitfield for control purposes 04509 * bit0= set "default" ACL rather than "access" ACL 04510 * bit5= in case of symbolic link: manipulate link target 04511 * @return 04512 * > 0 ok 04513 * 0 no ACL manipulation adapter available 04514 * -1 failure of system ACL service (see errno) 04515 * -2 attempt to manipulate ACL of a symbolic link without bit5 04516 * resp. with no suitable link target 04517 * 04518 * @since 0.6.14 04519 */ 04520 int iso_local_set_acl_text(char *disk_path, char *text, int flag); 04521 04522 04523 /** 04524 * Obtain permissions of a file in the local filesystem which shall reflect 04525 * ACL entry "group::" in S_IRWXG rather than ACL entry "mask::". This is 04526 * necessary if the permissions of a disk file with ACL shall be copied to 04527 * an object which has no ACL. 04528 * @param disk_path 04529 * Path to the local file which may have an "access" ACL or not. 04530 * @param flag 04531 * Bitfield for control purposes 04532 * bit5= in case of symbolic link: inquire link target 04533 * @param st_mode 04534 * Returns permission bits as of stat(2) 04535 * @return 04536 * 1 success 04537 * -1 failure of lstat() resp. stat() (see errno) 04538 * 04539 * @since 0.6.14 04540 */ 04541 int iso_local_get_perms_wo_acl(char *disk_path, mode_t *st_mode, int flag); 04542 04543 04544 /** 04545 * Get xattr and non-trivial ACLs of the given file in the local filesystem. 04546 * The resulting data has finally to be disposed by a call to this function 04547 * with flag bit15 set. 04548 * 04549 * Eventual ACLs will get encoded as attribute pair with empty name if this is 04550 * enabled by flag bit0. An ACL which simply replects stat(2) permissions 04551 * will not be put into the result. 04552 * 04553 * @param disk_path 04554 * Path to the file 04555 * @param num_attrs 04556 * Will return the number of name-value pairs 04557 * @param names 04558 * Will return an array of pointers to 0-terminated names 04559 * @param value_lengths 04560 * Will return an arry with the lenghts of values 04561 * @param values 04562 * Will return an array of pointers to 8-bit values 04563 * @param flag 04564 * Bitfield for control purposes 04565 * bit0= obtain eventual ACLs as attribute with empty name 04566 * bit2= do not obtain attributes other than ACLs 04567 * bit3= do not ignore eventual non-user attributes. 04568 * I.e. those with a name which does not begin by "user." 04569 * bit5= in case of symbolic link: inquire link target 04570 * bit15= free memory 04571 * @return 04572 * 1 ok 04573 * < 0 failure 04574 * 04575 * @since 0.6.14 04576 */ 04577 int iso_local_get_attrs(char *disk_path, size_t *num_attrs, char ***names, 04578 size_t **value_lengths, char ***values, int flag); 04579 04580 04581 /** 04582 * Attach a list of xattr and ACLs to the given file in the local filesystem. 04583 * 04584 * Eventual ACLs have to be encoded as attribute pair with empty name. 04585 * 04586 * @param disk_path 04587 * Path to the file 04588 * @param num_attrs 04589 * Number of attributes 04590 * @param names 04591 * Array of pointers to 0 terminated name strings 04592 * @param value_lengths 04593 * Array of byte lengths for each attribute payload 04594 * @param values 04595 * Array of pointers to the attribute payload bytes 04596 * @param flag 04597 * Bitfield for control purposes 04598 * bit0= do not attach ACLs from an eventual attribute with empty name 04599 * bit3= do not ignore eventual non-user attributes. 04600 * I.e. those with a name which does not begin by "user." 04601 * bit5= in case of symbolic link: manipulate link target 04602 * @return 04603 * 1 = ok 04604 * < 0 = error 04605 * 04606 * @since 0.6.14 04607 */ 04608 int iso_local_set_attrs(char *disk_path, size_t num_attrs, char **names, 04609 size_t *value_lengths, char **values, int flag); 04610 04611 04612 /* --------------------------- Filters in General -------------------------- */ 04613 04614 /* 04615 * A filter is an IsoStream which uses another IsoStream as input. It gets 04616 * attached to an IsoFile by specialized calls iso_file_add_*_filter() which 04617 * replace its current IsoStream by the filter stream which takes over the 04618 * current IsoStream as input. 04619 * The consequences are: 04620 * iso_file_get_stream() will return the filter stream. 04621 * iso_stream_get_size() will return the (cached) size of the filtered data, 04622 * iso_stream_open() will start eventual child processes, 04623 * iso_stream_close() will kill eventual child processes, 04624 * iso_stream_read() will return filtered data. E.g. as data file content 04625 * during ISO image generation. 04626 * 04627 * There are external filters which run child processes 04628 * iso_file_add_external_filter() 04629 * and internal filters 04630 * iso_file_add_zisofs_filter() 04631 * iso_file_add_gzip_filter() 04632 * which may or may not be available depending on compile time settings and 04633 * installed software packages like libz. 04634 * 04635 * During image generation filters get not in effect if the original IsoStream 04636 * is an "fsrc" stream based on a file in the loaded ISO image and if the 04637 * image generation type is set to 1 by iso_write_opts_set_appendable(). 04638 */ 04639 04640 /** 04641 * Delete the top filter stream from a data file. This is the most recent one 04642 * which was added by iso_file_add_*_filter(). 04643 * Caution: One should not do this while the IsoStream of the file is opened. 04644 * For now there is no general way to determine this state. 04645 * Filter stream implementations are urged to eventually call .close() 04646 * inside method .free() . This will close the input stream too. 04647 * @param file 04648 * The data file node which shall get rid of one layer of content 04649 * filtering. 04650 * @param flag 04651 * Bitfield for control purposes, unused yet, submit 0. 04652 * @return 04653 * 1 on success, 0 if no filter was present 04654 * <0 on error 04655 * 04656 * @since 0.6.18 04657 */ 04658 int iso_file_remove_filter(IsoFile *file, int flag); 04659 04660 /** 04661 * Obtain the eventual input stream of a filter stream. 04662 * @param stream 04663 * The eventual filter stream to be inquired. 04664 * @param flag 04665 * Bitfield for control purposes. Submit 0 for now. 04666 * @return 04667 * The input stream, if one exists. Elsewise NULL. 04668 * No extra reference to the stream is taken by this call. 04669 * 04670 * @since 0.6.18 04671 */ 04672 IsoStream *iso_stream_get_input_stream(IsoStream *stream, int flag); 04673 04674 04675 /* ---------------------------- External Filters --------------------------- */ 04676 04677 /** 04678 * Representation of an external program that shall serve as filter for 04679 * an IsoStream. This object may be shared among many IsoStream objects. 04680 * It is to be created and disposed by the application. 04681 * 04682 * The filter will act as proxy between the original IsoStream of an IsoFile. 04683 * Up to completed image generation it will be run at least twice: 04684 * for IsoStream.class.get_size() and for .open() with subsequent .read(). 04685 * So the original IsoStream has to return 1 by its .class.is_repeatable(). 04686 * The filter program has to be repeateable too. I.e. it must produce the same 04687 * output on the same input. 04688 * 04689 * @since 0.6.18 04690 */ 04691 struct iso_external_filter_command 04692 { 04693 /* Will indicate future extensions. It has to be 0 for now. */ 04694 int version; 04695 04696 /* Tells how many IsoStream objects depend on this command object. 04697 * One may only dispose an IsoExternalFilterCommand when this count is 0. 04698 * Initially this value has to be 0. 04699 */ 04700 int refcount; 04701 04702 /* An optional instance id. 04703 * Set to empty text if no individual name for this object is intended. 04704 */ 04705 char *name; 04706 04707 /* Absolute local filesystem path to the executable program. */ 04708 char *path; 04709 04710 /* Tells the number of arguments. */ 04711 int argc; 04712 04713 /* NULL terminated list suitable for system call execv(3). 04714 * I.e. argv[0] points to the alleged program name, 04715 * argv[1] to argv[argc] point to program arguments (if argc > 0) 04716 * argv[argc+1] is NULL 04717 */ 04718 char **argv; 04719 04720 /* A bit field which controls behavior variations: 04721 * bit0= Do not install filter if the input has size 0. 04722 * bit1= Do not install filter if the output is not smaller than the input. 04723 * bit2= Do not install filter if the number of output blocks is 04724 * not smaller than the number of input blocks. Block size is 2048. 04725 * Assume that non-empty input yields non-empty output and thus do 04726 * not attempt to attach a filter to files smaller than 2049 bytes. 04727 * bit3= suffix removed rather than added. 04728 * (Removal and adding suffixes is the task of the application. 04729 * This behavior bit serves only as reminder for the application.) 04730 */ 04731 int behavior; 04732 04733 /* The eventual suffix which is supposed to be added to the IsoFile name 04734 * resp. to be removed from the name. 04735 * (This is to be done by the application, not by calls 04736 * iso_file_add_external_filter() or iso_file_remove_filter(). 04737 * The value recorded here serves only as reminder for the application.) 04738 */ 04739 char *suffix; 04740 }; 04741 04742 typedef struct iso_external_filter_command IsoExternalFilterCommand; 04743 04744 /** 04745 * Install an external filter command on top of the content stream of a data 04746 * file. The filter process must be repeatable. It will be run once by this 04747 * call in order to cache the output size. 04748 * @param file 04749 * The data file node which shall show filtered content. 04750 * @param cmd 04751 * The external program and its arguments which shall do the filtering. 04752 * @param flag 04753 * Bitfield for control purposes, unused yet, submit 0. 04754 * @return 04755 * 1 on success, 2 if filter installation revoked (e.g. cmd.behavior bit1) 04756 * <0 on error 04757 * 04758 * @since 0.6.18 04759 */ 04760 int iso_file_add_external_filter(IsoFile *file, IsoExternalFilterCommand *cmd, 04761 int flag); 04762 04763 /** 04764 * Obtain the IsoExternalFilterCommand which is eventually associated with the 04765 * given stream. (Typically obtained from an IsoFile by iso_file_get_stream() 04766 * or from an IsoStream by iso_stream_get_input_stream()). 04767 * @param stream 04768 * The stream to be inquired. 04769 * @param cmd 04770 * Will return the external IsoExternalFilterCommand. Valid only if 04771 * the call returns 1. This does not increment cmd->refcount. 04772 * @param flag 04773 * Bitfield for control purposes, unused yet, submit 0. 04774 * @return 04775 * 1 on success, 0 if the stream is not an external filter 04776 * <0 on error 04777 * 04778 * @since 0.6.18 04779 */ 04780 int iso_stream_get_external_filter(IsoStream *stream, 04781 IsoExternalFilterCommand **cmd, int flag); 04782 04783 04784 /* ---------------------------- Internal Filters --------------------------- */ 04785 04786 04787 /** 04788 * Install a zisofs filter on top of the content stream of a data file. 04789 * zisofs is a compression format which is decompressed by some Linux kernels. 04790 * See also doc/zisofs_format.txt . 04791 * The filter will not be installed if its output size is not smaller than 04792 * the size of the input stream. 04793 * This is only enabled if the use of libz was enabled at compile time. 04794 * @param file 04795 * The data file node which shall show filtered content. 04796 * @param flag 04797 * Bitfield for control purposes 04798 * bit0= Do not install filter if the number of output blocks is 04799 * not smaller than the number of input blocks. Block size is 2048. 04800 * bit1= Install a decompression filter rather than one for compression. 04801 * bit2= Only inquire availability of zisofs filtering. file may be NULL. 04802 * If available return 2, else return error. 04803 * bit3= is reserved for internal use and will be forced to 0 04804 * @return 04805 * 1 on success, 2 if filter available but installation revoked 04806 * <0 on error, e.g. ISO_ZLIB_NOT_ENABLED 04807 * 04808 * @since 0.6.18 04809 */ 04810 int iso_file_add_zisofs_filter(IsoFile *file, int flag); 04811 04812 /** 04813 * Inquire the number of zisofs compression and uncompression filters which 04814 * are in use. 04815 * @param ziso_count 04816 * Will return the number of currently installed compression filters. 04817 * @param osiz_count 04818 * Will return the number of currently installed uncompression filters. 04819 * @param flag 04820 * Bitfield for control purposes, unused yet, submit 0 04821 * @return 04822 * 1 on success, <0 on error 04823 * 04824 * @since 0.6.18 04825 */ 04826 int iso_zisofs_get_refcounts(off_t *ziso_count, off_t *osiz_count, int flag); 04827 04828 04829 /** 04830 * Parameter set for iso_zisofs_set_params(). 04831 * 04832 * @since 0.6.18 04833 */ 04834 struct iso_zisofs_ctrl { 04835 04836 /* Set to 0 for this version of the structure */ 04837 int version; 04838 04839 /* Compression level for zlib function compress2(). From <zlib.h>: 04840 * "between 0 and 9: 04841 * 1 gives best speed, 9 gives best compression, 0 gives no compression" 04842 * Default is 6. 04843 */ 04844 int compression_level; 04845 04846 /* Log2 of the block size for compression filters. Allowed values are: 04847 * 15 = 32 kiB , 16 = 64 kiB , 17 = 128 kiB 04848 */ 04849 uint8_t block_size_log2; 04850 04851 }; 04852 04853 /** 04854 * Set the global parameters for zisofs filtering. 04855 * This is only allowed while no zisofs compression filters are installed. 04856 * i.e. ziso_count returned by iso_zisofs_get_refcounts() has to be 0. 04857 * @param params 04858 * Pointer to a structure with the intended settings. 04859 * @param flag 04860 * Bitfield for control purposes, unused yet, submit 0 04861 * @return 04862 * 1 on success, <0 on error 04863 * 04864 * @since 0.6.18 04865 */ 04866 int iso_zisofs_set_params(struct iso_zisofs_ctrl *params, int flag); 04867 04868 /** 04869 * Get the current global parameters for zisofs filtering. 04870 * @param params 04871 * Pointer to a caller provided structure which shall take the settings. 04872 * @param flag 04873 * Bitfield for control purposes, unused yet, submit 0 04874 * @return 04875 * 1 on success, <0 on error 04876 * 04877 * @since 0.6.18 04878 */ 04879 int iso_zisofs_get_params(struct iso_zisofs_ctrl *params, int flag); 04880 04881 04882 /** 04883 * Check for the given node or for its subtree whether the data file content 04884 * effectively bears zisofs file headers and eventually mark the outcome 04885 * by an xinfo data record if not already marked by a zisofs compressor filter. 04886 * This does not install any filter but only a hint for image generation 04887 * that the already compressed files shall get written with zisofs ZF entries. 04888 * Use this if you insert the compressed reults of program mkzftree from disk 04889 * into the image. 04890 * @param node 04891 * The node which shall be checked and eventually marked. 04892 * @param flag 04893 * Bitfield for control purposes, unused yet, submit 0 04894 * bit0= prepare for a run with iso_write_opts_set_appendable(,1). 04895 * Take into account that files from the imported image 04896 * do not get their content filtered. 04897 * bit1= permission to overwrite existing zisofs_zf_info 04898 * bit2= if no zisofs header is found: 04899 * create xinfo with parameters which indicate no zisofs 04900 * bit3= no tree recursion if node is a directory 04901 * bit4= skip files which stem from the imported image 04902 * @return 04903 * 0= no zisofs data found 04904 * 1= zf xinfo added 04905 * 2= found existing zf xinfo and flag bit1 was not set 04906 * 3= both encountered: 1 and 2 04907 * <0 means error 04908 * 04909 * @since 0.6.18 04910 */ 04911 int iso_node_zf_by_magic(IsoNode *node, int flag); 04912 04913 04914 /** 04915 * Install a gzip or gunzip filter on top of the content stream of a data file. 04916 * gzip is a compression format which is used by programs gzip and gunzip. 04917 * The filter will not be installed if its output size is not smaller than 04918 * the size of the input stream. 04919 * This is only enabled if the use of libz was enabled at compile time. 04920 * @param file 04921 * The data file node which shall show filtered content. 04922 * @param flag 04923 * Bitfield for control purposes 04924 * bit0= Do not install filter if the number of output blocks is 04925 * not smaller than the number of input blocks. Block size is 2048. 04926 * bit1= Install a decompression filter rather than one for compression. 04927 * bit2= Only inquire availability of gzip filtering. file may be NULL. 04928 * If available return 2, else return error. 04929 * bit3= is reserved for internal use and will be forced to 0 04930 * @return 04931 * 1 on success, 2 if filter available but installation revoked 04932 * <0 on error, e.g. ISO_ZLIB_NOT_ENABLED 04933 * 04934 * @since 0.6.18 04935 */ 04936 int iso_file_add_gzip_filter(IsoFile *file, int flag); 04937 04938 04939 /** 04940 * Inquire the number of gzip compression and uncompression filters which 04941 * are in use. 04942 * @param gzip_count 04943 * Will return the number of currently installed compression filters. 04944 * @param gunzip_count 04945 * Will return the number of currently installed uncompression filters. 04946 * @param flag 04947 * Bitfield for control purposes, unused yet, submit 0 04948 * @return 04949 * 1 on success, <0 on error 04950 * 04951 * @since 0.6.18 04952 */ 04953 int iso_gzip_get_refcounts(off_t *gzip_count, off_t *gunzip_count, int flag); 04954 04955 04956 /************ Error codes and return values for libisofs ********************/ 04957 04958 /** successfully execution */ 04959 #define ISO_SUCCESS 1 04960 04961 /** 04962 * special return value, it could be or not an error depending on the 04963 * context. 04964 */ 04965 #define ISO_NONE 0 04966 04967 /** Operation canceled (FAILURE,HIGH, -1) */ 04968 #define ISO_CANCELED 0xE830FFFF 04969 04970 /** Unknown or unexpected fatal error (FATAL,HIGH, -2) */ 04971 #define ISO_FATAL_ERROR 0xF030FFFE 04972 04973 /** Unknown or unexpected error (FAILURE,HIGH, -3) */ 04974 #define ISO_ERROR 0xE830FFFD 04975 04976 /** Internal programming error. Please report this bug (FATAL,HIGH, -4) */ 04977 #define ISO_ASSERT_FAILURE 0xF030FFFC 04978 04979 /** 04980 * NULL pointer as value for an arg. that doesn't allow NULL (FAILURE,HIGH, -5) 04981 */ 04982 #define ISO_NULL_POINTER 0xE830FFFB 04983 04984 /** Memory allocation error (FATAL,HIGH, -6) */ 04985 #define ISO_OUT_OF_MEM 0xF030FFFA 04986 04987 /** Interrupted by a signal (FATAL,HIGH, -7) */ 04988 #define ISO_INTERRUPTED 0xF030FFF9 04989 04990 /** Invalid parameter value (FAILURE,HIGH, -8) */ 04991 #define ISO_WRONG_ARG_VALUE 0xE830FFF8 04992 04993 /** Can't create a needed thread (FATAL,HIGH, -9) */ 04994 #define ISO_THREAD_ERROR 0xF030FFF7 04995 04996 /** Write error (FAILURE,HIGH, -10) */ 04997 #define ISO_WRITE_ERROR 0xE830FFF6 04998 04999 /** Buffer read error (FAILURE,HIGH, -11) */ 05000 #define ISO_BUF_READ_ERROR 0xE830FFF5 05001 05002 /** Trying to add to a dir a node already added to a dir (FAILURE,HIGH, -64) */ 05003 #define ISO_NODE_ALREADY_ADDED 0xE830FFC0 05004 05005 /** Node with same name already exists (FAILURE,HIGH, -65) */ 05006 #define ISO_NODE_NAME_NOT_UNIQUE 0xE830FFBF 05007 05008 /** Trying to remove a node that was not added to dir (FAILURE,HIGH, -65) */ 05009 #define ISO_NODE_NOT_ADDED_TO_DIR 0xE830FFBE 05010 05011 /** A requested node does not exist (FAILURE,HIGH, -66) */ 05012 #define ISO_NODE_DOESNT_EXIST 0xE830FFBD 05013 05014 /** 05015 * Try to set the boot image of an already bootable image (FAILURE,HIGH, -67) 05016 */ 05017 #define ISO_IMAGE_ALREADY_BOOTABLE 0xE830FFBC 05018 05019 /** Trying to use an invalid file as boot image (FAILURE,HIGH, -68) */ 05020 #define ISO_BOOT_IMAGE_NOT_VALID 0xE830FFBB 05021 05022 /** 05023 * Error on file operation (FAILURE,HIGH, -128) 05024 * (take a look at more specified error codes below) 05025 */ 05026 #define ISO_FILE_ERROR 0xE830FF80 05027 05028 /** Trying to open an already opened file (FAILURE,HIGH, -129) */ 05029 #define ISO_FILE_ALREADY_OPENED 0xE830FF7F 05030 05031 /* @deprecated use ISO_FILE_ALREADY_OPENED instead */ 05032 #define ISO_FILE_ALREADY_OPENNED 0xE830FF7F 05033 05034 /** Access to file is not allowed (FAILURE,HIGH, -130) */ 05035 #define ISO_FILE_ACCESS_DENIED 0xE830FF7E 05036 05037 /** Incorrect path to file (FAILURE,HIGH, -131) */ 05038 #define ISO_FILE_BAD_PATH 0xE830FF7D 05039 05040 /** The file does not exist in the filesystem (FAILURE,HIGH, -132) */ 05041 #define ISO_FILE_DOESNT_EXIST 0xE830FF7C 05042 05043 /** Trying to read or close a file not openned (FAILURE,HIGH, -133) */ 05044 #define ISO_FILE_NOT_OPENED 0xE830FF7B 05045 05046 /* @deprecated use ISO_FILE_NOT_OPENED instead */ 05047 #define ISO_FILE_NOT_OPENNED ISO_FILE_NOT_OPENED 05048 05049 /** Directory used where no dir is expected (FAILURE,HIGH, -134) */ 05050 #define ISO_FILE_IS_DIR 0xE830FF7A 05051 05052 /** Read error (FAILURE,HIGH, -135) */ 05053 #define ISO_FILE_READ_ERROR 0xE830FF79 05054 05055 /** Not dir used where a dir is expected (FAILURE,HIGH, -136) */ 05056 #define ISO_FILE_IS_NOT_DIR 0xE830FF78 05057 05058 /** Not symlink used where a symlink is expected (FAILURE,HIGH, -137) */ 05059 #define ISO_FILE_IS_NOT_SYMLINK 0xE830FF77 05060 05061 /** Can't seek to specified location (FAILURE,HIGH, -138) */ 05062 #define ISO_FILE_SEEK_ERROR 0xE830FF76 05063 05064 /** File not supported in ECMA-119 tree and thus ignored (WARNING,MEDIUM, -139) */ 05065 #define ISO_FILE_IGNORED 0xD020FF75 05066 05067 /* A file is bigger than supported by used standard (WARNING,MEDIUM, -140) */ 05068 #define ISO_FILE_TOO_BIG 0xD020FF74 05069 05070 /* File read error during image creation (MISHAP,HIGH, -141) */ 05071 #define ISO_FILE_CANT_WRITE 0xE430FF73 05072 05073 /* Can't convert filename to requested charset (WARNING,MEDIUM, -142) */ 05074 #define ISO_FILENAME_WRONG_CHARSET 0xD020FF72 05075 /* This was once a HINT. Deprecated now. */ 05076 #define ISO_FILENAME_WRONG_CHARSET_OLD 0xC020FF72 05077 05078 /* File can't be added to the tree (SORRY,HIGH, -143) */ 05079 #define ISO_FILE_CANT_ADD 0xE030FF71 05080 05081 /** 05082 * File path break specification constraints and will be ignored 05083 * (WARNING,MEDIUM, -144) 05084 */ 05085 #define ISO_FILE_IMGPATH_WRONG 0xD020FF70 05086 05087 /** 05088 * Offset greater than file size (FAILURE,HIGH, -145) 05089 * @since 0.6.4 05090 */ 05091 #define ISO_FILE_OFFSET_TOO_BIG 0xE830FF6A 05092 05093 /** Charset conversion error (FAILURE,HIGH, -256) */ 05094 #define ISO_CHARSET_CONV_ERROR 0xE830FF00 05095 05096 /** 05097 * Too many files to mangle, i.e. we cannot guarantee unique file names 05098 * (FAILURE,HIGH, -257) 05099 */ 05100 #define ISO_MANGLE_TOO_MUCH_FILES 0xE830FEFF 05101 05102 /* image related errors */ 05103 05104 /** 05105 * Wrong or damaged Primary Volume Descriptor (FAILURE,HIGH, -320) 05106 * This could mean that the file is not a valid ISO image. 05107 */ 05108 #define ISO_WRONG_PVD 0xE830FEC0 05109 05110 /** Wrong or damaged RR entry (SORRY,HIGH, -321) */ 05111 #define ISO_WRONG_RR 0xE030FEBF 05112 05113 /** Unsupported RR feature (SORRY,HIGH, -322) */ 05114 #define ISO_UNSUPPORTED_RR 0xE030FEBE 05115 05116 /** Wrong or damaged ECMA-119 (FAILURE,HIGH, -323) */ 05117 #define ISO_WRONG_ECMA119 0xE830FEBD 05118 05119 /** Unsupported ECMA-119 feature (FAILURE,HIGH, -324) */ 05120 #define ISO_UNSUPPORTED_ECMA119 0xE830FEBC 05121 05122 /** Wrong or damaged El-Torito catalog (SORRY,HIGH, -325) */ 05123 #define ISO_WRONG_EL_TORITO 0xE030FEBB 05124 05125 /** Unsupported El-Torito feature (SORRY,HIGH, -326) */ 05126 #define ISO_UNSUPPORTED_EL_TORITO 0xE030FEBA 05127 05128 /** Can't patch an isolinux boot image (SORRY,HIGH, -327) */ 05129 #define ISO_ISOLINUX_CANT_PATCH 0xE030FEB9 05130 05131 /** Unsupported SUSP feature (SORRY,HIGH, -328) */ 05132 #define ISO_UNSUPPORTED_SUSP 0xE030FEB8 05133 05134 /** Error on a RR entry that can be ignored (WARNING,HIGH, -329) */ 05135 #define ISO_WRONG_RR_WARN 0xD030FEB7 05136 05137 /** Error on a RR entry that can be ignored (HINT,MEDIUM, -330) */ 05138 #define ISO_SUSP_UNHANDLED 0xC020FEB6 05139 05140 /** Multiple ER SUSP entries found (WARNING,HIGH, -331) */ 05141 #define ISO_SUSP_MULTIPLE_ER 0xD030FEB5 05142 05143 /** Unsupported volume descriptor found (HINT,MEDIUM, -332) */ 05144 #define ISO_UNSUPPORTED_VD 0xC020FEB4 05145 05146 /** El-Torito related warning (WARNING,HIGH, -333) */ 05147 #define ISO_EL_TORITO_WARN 0xD030FEB3 05148 05149 /** Image write cancelled (MISHAP,HIGH, -334) */ 05150 #define ISO_IMAGE_WRITE_CANCELED 0xE430FEB2 05151 05152 /** El-Torito image is hidden (WARNING,HIGH, -335) */ 05153 #define ISO_EL_TORITO_HIDDEN 0xD030FEB1 05154 05155 05156 /** AAIP info with ACL or xattr in ISO image will be ignored 05157 (NOTE, HIGH, -336) */ 05158 #define ISO_AAIP_IGNORED 0xB030FEB0 05159 05160 /** Error with decoding ACL from AAIP info (FAILURE, HIGH, -337) */ 05161 #define ISO_AAIP_BAD_ACL 0xE830FEAF 05162 05163 /** Error with encoding ACL for AAIP (FAILURE, HIGH, -338) */ 05164 #define ISO_AAIP_BAD_ACL_TEXT 0xE830FEAE 05165 05166 /** AAIP processing for ACL or xattr not enabled at compile time 05167 (FAILURE, HIGH, -339) */ 05168 #define ISO_AAIP_NOT_ENABLED 0xE830FEAD 05169 05170 /** Error with decoding AAIP info for ACL or xattr (FAILURE, HIGH, -340) */ 05171 #define ISO_AAIP_BAD_AASTRING 0xE830FEAC 05172 05173 /** Error with reading ACL or xattr from local file (FAILURE, HIGH, -341) */ 05174 #define ISO_AAIP_NO_GET_LOCAL 0xE830FEAB 05175 05176 /** Error with attaching ACL or xattr to local file (FAILURE, HIGH, -342) */ 05177 #define ISO_AAIP_NO_SET_LOCAL 0xE830FEAA 05178 05179 /** Unallowed attempt to set an xattr with non-userspace name 05180 (FAILURE, HIGH, -343) */ 05181 #define ISO_AAIP_NON_USER_NAME 0xE830FEA9 05182 05183 05184 /** Too many references on a single IsoExternalFilterCommand 05185 (FAILURE, HIGH, -344) */ 05186 #define ISO_EXTF_TOO_OFTEN 0xE830FEA8 05187 05188 /** Use of zlib was not enabled at compile time (FAILURE, HIGH, -345) */ 05189 #define ISO_ZLIB_NOT_ENABLED 0xE830FEA7 05190 05191 /** Cannot apply zisofs filter to file >= 4 GiB (FAILURE, HIGH, -346) */ 05192 #define ISO_ZISOFS_TOO_LARGE 0xE830FEA6 05193 05194 /** Filter input differs from previous run (FAILURE, HIGH, -347) */ 05195 #define ISO_FILTER_WRONG_INPUT 0xE830FEA5 05196 05197 /** zlib compression/decompression error (FAILURE, HIGH, -348) */ 05198 #define ISO_ZLIB_COMPR_ERR 0xE830FEA4 05199 05200 /** Input stream is not in zisofs format (FAILURE, HIGH, -349) */ 05201 #define ISO_ZISOFS_WRONG_INPUT 0xE830FEA3 05202 05203 /** Cannot set global zisofs parameters while filters exist 05204 (FAILURE, HIGH, -350) */ 05205 #define ISO_ZISOFS_PARAM_LOCK 0xE830FEA2 05206 05207 /** Premature EOF of zlib input stream (FAILURE, HIGH, -351) */ 05208 #define ISO_ZLIB_EARLY_EOF 0xE830FEA1 05209 05210 05211 /* ! PLACE NEW ERROR CODES HERE ! */ 05212 05213 05214 /** Read error occured with IsoDataSource (SORRY,HIGH, -513) */ 05215 #define ISO_DATA_SOURCE_SORRY 0xE030FCFF 05216 05217 /** Read error occured with IsoDataSource (MISHAP,HIGH, -513) */ 05218 #define ISO_DATA_SOURCE_MISHAP 0xE430FCFF 05219 05220 /** Read error occured with IsoDataSource (FAILURE,HIGH, -513) */ 05221 #define ISO_DATA_SOURCE_FAILURE 0xE830FCFF 05222 05223 /** Read error occured with IsoDataSource (FATAL,HIGH, -513) */ 05224 #define ISO_DATA_SOURCE_FATAL 0xF030FCFF 05225 05226 05227 /* ! PLACE NEW ERROR CODES ABOVE. NOT HERE ! */ 05228 05229 05230 /* ------------------------------------------------------------------------- */ 05231 05232 #ifdef LIBISOFS_WITHOUT_LIBBURN 05233 05234 /** 05235 This is a copy from the API of libburn-0.6.0 (under GPL). 05236 It is supposed to be as stable as any overall include of libburn.h. 05237 I.e. if this definition is out of sync then you cannot rely on any 05238 contract that was made with libburn.h. 05239 05240 Libisofs does not need to be linked with libburn at all. But if it is 05241 linked with libburn then it must be libburn-0.4.2 or later. 05242 05243 An application that provides own struct burn_source objects and does not 05244 include libburn/libburn.h has to define LIBISOFS_WITHOUT_LIBBURN before 05245 including libisofs/libisofs.h in order to make this copy available. 05246 */ 05247 05248 05249 /** Data source interface for tracks. 05250 This allows to use arbitrary program code as provider of track input data. 05251 05252 Objects compliant to this interface are either provided by the application 05253 or by API calls of libburn: burn_fd_source_new() , burn_file_source_new(), 05254 and burn_fifo_source_new(). 05255 05256 The API calls allow to use any file object as data source. Consider to feed 05257 an eventual custom data stream asynchronously into a pipe(2) and to let 05258 libburn handle the rest. 05259 In this case the following rule applies: 05260 Call burn_source_free() exactly once for every source obtained from 05261 libburn API. You MUST NOT otherwise use or manipulate its components. 05262 05263 In general, burn_source objects can be freed as soon as they are attached 05264 to track objects. The track objects will keep them alive and dispose them 05265 when they are no longer needed. With a fifo burn_source it makes sense to 05266 keep the own reference for inquiring its state while burning is in 05267 progress. 05268 05269 --- 05270 05271 The following description of burn_source applies only to application 05272 implemented burn_source objects. You need not to know it for API provided 05273 ones. 05274 05275 If you really implement an own passive data producer by this interface, 05276 then beware: it can do anything and it can spoil everything. 05277 05278 In this case the functions (*read), (*get_size), (*set_size), (*free_data) 05279 MUST be implemented by the application and attached to the object at 05280 creation time. 05281 Function (*read_sub) is allowed to be NULL or it MUST be implemented and 05282 attached. 05283 05284 burn_source.refcount MUST be handled properly: If not exactly as many 05285 references are freed as have been obtained, then either memory leaks or 05286 corrupted memory are the consequence. 05287 All objects which are referred to by *data must be kept existent until 05288 (*free_data) is called via burn_source_free() by the last referer. 05289 */ 05290 struct burn_source { 05291 05292 /** Reference count for the data source. MUST be 1 when a new source 05293 is created and thus the first reference is handed out. Increment 05294 it to take more references for yourself. Use burn_source_free() 05295 to destroy your references to it. */ 05296 int refcount; 05297 05298 05299 /** Read data from the source. Semantics like with read(2), but MUST 05300 either deliver the full buffer as defined by size or MUST deliver 05301 EOF (return 0) or failure (return -1) at this call or at the 05302 next following call. I.e. the only incomplete buffer may be the 05303 last one from that source. 05304 libburn will read a single sector by each call to (*read). 05305 The size of a sector depends on BURN_MODE_*. The known range is 05306 2048 to 2352. 05307 05308 If this call is reading from a pipe then it will learn 05309 about the end of data only when that pipe gets closed on the 05310 feeder side. So if the track size is not fixed or if the pipe 05311 delivers less than the predicted amount or if the size is not 05312 block aligned, then burning will halt until the input process 05313 closes the pipe. 05314 05315 IMPORTANT: 05316 If this function pointer is NULL, then the struct burn_source is of 05317 version >= 1 and the job of .(*read)() is done by .(*read_xt)(). 05318 See below, member .version. 05319 */ 05320 int (*read)(struct burn_source *, unsigned char *buffer, int size); 05321 05322 05323 /** Read subchannel data from the source (NULL if lib generated) 05324 WARNING: This is an obscure feature with CD raw write modes. 05325 Unless you checked the libburn code for correctness in that aspect 05326 you should not rely on raw writing with own subchannels. 05327 ADVICE: Set this pointer to NULL. 05328 */ 05329 int (*read_sub)(struct burn_source *, unsigned char *buffer, int size); 05330 05331 05332 /** Get the size of the source's data. Return 0 means unpredictable 05333 size. If application provided (*get_size) allows return 0, then 05334 the application MUST provide a fully functional (*set_size). 05335 */ 05336 off_t (*get_size)(struct burn_source *); 05337 05338 05339 /* @since 0.3.2 */ 05340 /** Program the reply of (*get_size) to a fixed value. It is advised 05341 to implement this by a attribute off_t fixed_size; in *data . 05342 The read() function does not have to take into respect this fake 05343 setting. It is rather a note of libburn to itself. Eventually 05344 necessary truncation or padding is done in libburn. Truncation 05345 is usually considered a misburn. Padding is considered ok. 05346 05347 libburn is supposed to work even if (*get_size) ignores the 05348 setting by (*set_size). But your application will not be able to 05349 enforce fixed track sizes by burn_track_set_size() and possibly 05350 even padding might be left out. 05351 */ 05352 int (*set_size)(struct burn_source *source, off_t size); 05353 05354 05355 /** Clean up the source specific data. This function will be called 05356 once by burn_source_free() when the last referer disposes the 05357 source. 05358 */ 05359 void (*free_data)(struct burn_source *); 05360 05361 05362 /** Next source, for when a source runs dry and padding is disabled 05363 WARNING: This is an obscure feature. Set to NULL at creation and 05364 from then on leave untouched and uninterpreted. 05365 */ 05366 struct burn_source *next; 05367 05368 05369 /** Source specific data. Here the various source classes express their 05370 specific properties and the instance objects store their individual 05371 management data. 05372 E.g. data could point to a struct like this: 05373 struct app_burn_source 05374 { 05375 struct my_app *app_handle; 05376 ... other individual source parameters ... 05377 off_t fixed_size; 05378 }; 05379 05380 Function (*free_data) has to be prepared to clean up and free 05381 the struct. 05382 */ 05383 void *data; 05384 05385 05386 /* @since 0.4.2 */ 05387 /** Valid only if above member .(*read)() is NULL. This indicates a 05388 version of struct burn_source younger than 0. 05389 From then on, member .version tells which further members exist 05390 in the memory layout of struct burn_source. libburn will only touch 05391 those announced extensions. 05392 05393 Versions: 05394 0 has .(*read)() != NULL, not even .version is present. 05395 1 has .version, .(*read_xt)(), .(*cancel)() 05396 */ 05397 int version; 05398 05399 /** This substitutes for (*read)() in versions above 0. */ 05400 int (*read_xt)(struct burn_source *, unsigned char *buffer, int size); 05401 05402 /** Informs the burn_source that the consumer of data prematurely 05403 ended reading. This call may or may not be issued by libburn 05404 before (*free_data)() is called. 05405 */ 05406 int (*cancel)(struct burn_source *source); 05407 }; 05408 05409 #endif /* LIBISOFS_WITHOUT_LIBBURN */ 05410 05411 /* ----------------------------- Bug Fixes ----------------------------- */ 05412 05413 /* currently none being tested */ 05414 05415 /* ---------------------------- Improvements --------------------------- */ 05416 05417 /* currently none being tested */ 05418 05419 /* ---------------------------- Experiments ---------------------------- */ 05420 05421 /* Hardlinks : During image generation accompany the tree of IsoFileSrc 05422 by a sorted array of Ecma119Node. 05423 The sorting order shall bring together candidates for being 05424 hardlink siblings resp. having identical content. 05425 05426 This is in sync with the IsoFileSrc unification by IsoRBTree 05427 and iso_file_src_cmp(). 05428 That tree cannot be obsoleted because Joliet and ISO1999 depend 05429 on it. On the other hand, the Ecma119Node array includes objects 05430 which have no IsoFileSrc attached. So both, tree and array, are 05431 needed. 05432 */ 05433 #define Libisofs_hardlink_matcheR yes 05434 05435 05436 /* Hardlinks : Override Libisofs_new_fs_image_inO and preserve inode numbers 05437 from session to session. 05438 */ 05439 #define Libisofs_hardlink_prooF yes 05440 05441 05442 /* Experiment: Ignore PX inode numbers, 05443 have boot image inode number counted by fs_give_ino_number() 05444 05445 Overridden if Libisofs_hardlink_prooF is defined. 05446 #define Libisofs_new_fs_image_inO yes 05447 */ 05448 05449 05450 /* Experiment: Write obsolete RR entries with Rock Ridge. 05451 I suspect Solaris wants to see them. 05452 DID NOT HELP: Solaris knows only RRIP_1991A. 05453 05454 #define Libisofs_with_rrip_rR yes 05455 */ 05456 05457 05458 05459 #endif /*LIBISO_LIBISOFS_H_*/