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 AA 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 AA 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 AA string data. If no AA 00703 * string is available, *aa_string becomes NULL. 00704 * (See doc/susp_aaip_0_2.txt for the meaning of AA 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. 00763 * 00764 * @since 0.6.4 00765 */ 00766 struct IsoStream_Iface 00767 { 00768 /* 00769 * Current version of the interface, set to 1. 00770 * 00771 * -version 1 (since 0.6.8) 00772 * update_size() added. 00773 */ 00774 int version; 00775 00776 /** 00777 * Type of Stream. 00778 * "fsrc" -> Read from file source 00779 * "mem " -> Read from memory 00780 * "boot" -> Boot catalog 00781 * "user" -> User supplied stream 00782 */ 00783 char type[4]; 00784 00785 /** 00786 * Opens the stream. 00787 * 00788 * @return 00789 * 1 on success, 2 file greater than expected, 3 file smaller than 00790 * expected, < 0 on error (has to be a valid libisofs error code) 00791 */ 00792 int (*open)(IsoStream *stream); 00793 00794 /** 00795 * Close the Stream. 00796 * @return 00797 * 1 on success, < 0 on error (has to be a valid libisofs error code) 00798 */ 00799 int (*close)(IsoStream *stream); 00800 00801 /** 00802 * Get the size (in bytes) of the stream. This function should always 00803 * return the same size, even if the underlying source size changes, 00804 * unless you call update_size() method. 00805 */ 00806 off_t (*get_size)(IsoStream *stream); 00807 00808 /** 00809 * Attempts to read up to count bytes from the given stream into 00810 * the buffer starting at buf. 00811 * 00812 * The stream must be open() before calling this, and close() when no 00813 * more needed. 00814 * 00815 * @return 00816 * number of bytes read, 0 if EOF, < 0 on error (has to be a valid 00817 * libisofs error code) 00818 */ 00819 int (*read)(IsoStream *stream, void *buf, size_t count); 00820 00821 /** 00822 * Whether this IsoStream can be read several times, with the same results. 00823 * For example, a regular file is repeatable, you can read it as many 00824 * times as you want. However, a pipe isn't. 00825 * 00826 * This function doesn't take into account if the file has been modified 00827 * between the two reads. 00828 * 00829 * @return 00830 * 1 if stream is repeatable, 0 if not, 00831 * < 0 on error (has to be a valid libisofs error code) 00832 */ 00833 int (*is_repeatable)(IsoStream *stream); 00834 00835 /** 00836 * Get an unique identifier for the IsoStream. 00837 */ 00838 void (*get_id)(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, 00839 ino_t *ino_id); 00840 00841 /** 00842 * Free implementation specific data. Should never be called by user. 00843 * Use iso_stream_unref() instead. 00844 */ 00845 void (*free)(IsoStream *stream); 00846 00847 /** 00848 * Updates the size of the IsoStream with the current size of the 00849 * underlying source. After calling this, get_size() will return 00850 * the new size. This should never be called after 00851 * iso_image_create_burn_source() was called and the image was not 00852 * completely written. To update the size of all files before written the 00853 * image, you may want to call iso_image_update_sizes() just before 00854 * iso_image_create_burn_source(). 00855 * 00856 * @return 00857 * 1 if ok, < 0 on error (has to be a valid libisofs error code) 00858 * @since 0.6.8 00859 */ 00860 int (*update_size)(IsoStream *stream); 00861 }; 00862 00863 /** 00864 * Representation of file contents as a stream of bytes. 00865 * 00866 * @since 0.6.4 00867 */ 00868 struct iso_stream 00869 { 00870 IsoStreamIface *class; 00871 int refcount; 00872 void *data; 00873 }; 00874 00875 /** 00876 * Initialize libisofs. You must call this before any usage of the library. 00877 * @return 1 on success, < 0 on error 00878 * 00879 * @since 0.6.2 00880 */ 00881 int iso_init(); 00882 00883 /** 00884 * Finalize libisofs. 00885 * 00886 * @since 0.6.2 00887 */ 00888 void iso_finish(); 00889 00890 /** 00891 * Override the reply of libc function nl_langinfo(CODESET) which may or may 00892 * not give the name of the character set which is in effect for your 00893 * environment. So this call can compensate for inconsistent terminal setups. 00894 * Another use case is to choose UTF-8 as intermediate character set for a 00895 * conversion from an exotic input character set to an exotic output set. 00896 * 00897 * @param name 00898 * Name of the character set to be assumed as "local" one. 00899 * @param flag 00900 * Unused yet. Submit 0. 00901 * @return 00902 * 1 indicates success, <=0 failure 00903 * 00904 * @since 0.6.12 00905 */ 00906 int iso_set_local_charset(char *name, int flag); 00907 00908 /** 00909 * Obtain the local charset as currently assumed by libisofs. 00910 * The result points to internal memory. It is volatile and must not be 00911 * altered. 00912 * 00913 * @param flag 00914 * Unused yet. Submit 0. 00915 * 00916 * @since 0.6.12 00917 */ 00918 char *iso_get_local_charset(int flag); 00919 00920 /** 00921 * Create a new image, empty. 00922 * 00923 * The image will be owned by you and should be unref() when no more needed. 00924 * 00925 * @param name 00926 * Name of the image. This will be used as volset_id and volume_id. 00927 * @param image 00928 * Location where the image pointer will be stored. 00929 * @return 00930 * 1 sucess, < 0 error 00931 * 00932 * @since 0.6.2 00933 */ 00934 int iso_image_new(const char *name, IsoImage **image); 00935 00936 00937 /** 00938 * Control whether ACL and xattr will be imported from external filesystems 00939 * (typically the local POSIX filesystem) when new nodes get inserted. If 00940 * enabled by iso_write_opts_set_aaip() they will later be written into the 00941 * image as AAIP extension fields. 00942 * 00943 * A change of this setting does neither affect existing IsoNode objects 00944 * nor the way how ACL and xattr are handled when loading an ISO image. 00945 * The latter is controlled by iso_read_opts_set_no_aaip(). 00946 * 00947 * @param image 00948 * The image of which the behavior is to be controlled 00949 * @param what 00950 * A bit field which sets the behavior: 00951 * bit0= ignore ACLs if the external file object bears some 00952 * bit1= ignore xattr if the external file object bears some 00953 * all other bits are reserved 00954 * 00955 * @since 0.6.14 00956 */ 00957 void iso_image_set_ignore_aclea(IsoImage *image, int what); 00958 00959 00960 /** 00961 * The following two functions three macros are utilities to help ensuring 00962 * version match of application, compile time header, and runtime library. 00963 */ 00964 /** 00965 * Get version of the libisofs library at runtime. 00966 * 00967 * @since 0.6.2 00968 */ 00969 void iso_lib_version(int *major, int *minor, int *micro); 00970 00971 /** 00972 * Check at runtime if the library is ABI compatible with the given version. 00973 * 00974 * @return 00975 * 1 lib is compatible, 0 is not. 00976 * 00977 * @since 0.6.2 00978 */ 00979 int iso_lib_is_compatible(int major, int minor, int micro); 00980 00981 00982 /** 00983 * These three release version numbers tell the revision of this header file 00984 * and of the API it describes. They are memorized by applications at 00985 * compile time. 00986 * They must show the same values as these symbols in ./configure.ac 00987 * LIBISOFS_MAJOR_VERSION=... 00988 * LIBISOFS_MINOR_VERSION=... 00989 * LIBISOFS_MICRO_VERSION=... 00990 * Note to anybody who does own work inside libisofs: 00991 * Any change of configure.ac or libisofs.h has to keep up this equality ! 00992 * 00993 * Before usage of these macros on your code, please read the usage discussion 00994 * below. 00995 * 00996 * @since 0.6.2 00997 */ 00998 #define iso_lib_header_version_major 0 00999 #define iso_lib_header_version_minor 6 01000 #define iso_lib_header_version_micro 16 01001 01002 /** 01003 * Usage discussion: 01004 * 01005 * Some developers of the libburnia project have differing opinions how to 01006 * ensure the compatibility of libaries and applications. 01007 * 01008 * It is about whether to use at compile time and at runtime the version 01009 * numbers provided here. Thomas Schmitt advises to use them. Vreixo Formoso 01010 * advises to use other means. 01011 * 01012 * At compile time: 01013 * 01014 * Vreixo Formoso advises to leave proper version matching to properly 01015 * programmed checks in the the application's build system, which will 01016 * eventually refuse compilation. 01017 * 01018 * Thomas Schmitt advises to use the macros defined here for comparison with 01019 * the application's requirements of library revisions and to eventually 01020 * break compilation. 01021 * 01022 * Both advises are combinable. I.e. be master of your build system and have 01023 * #if checks in the source code of your application, nevertheless. 01024 * 01025 * At runtime (via iso_lib_is_compatible()): 01026 * 01027 * Vreixo Formoso advises to compare the application's requirements of 01028 * library revisions with the runtime library. This is to allow runtime 01029 * libraries which are young enough for the application but too old for 01030 * the lib*.h files seen at compile time. 01031 * 01032 * Thomas Schmitt advises to compare the header revisions defined here with 01033 * the runtime library. This is to enforce a strictly monotonous chain of 01034 * revisions from app to header to library, at the cost of excluding some older 01035 * libraries. 01036 * 01037 * These two advises are mutually exclusive. 01038 */ 01039 01040 01041 /** 01042 * Creates an IsoWriteOpts for writing an image. You should set the options 01043 * desired with the correspondent setters. 01044 * 01045 * Options by default are determined by the selected profile. Fifo size is set 01046 * by default to 2 MB. 01047 * 01048 * @param opts 01049 * Pointer to the location where the newly created IsoWriteOpts will be 01050 * stored. You should free it with iso_write_opts_free() when no more 01051 * needed. 01052 * @param profile 01053 * Default profile for image creation. For now the following values are 01054 * defined: 01055 * ---> 0 [BASIC] 01056 * No extensions are enabled, and ISO level is set to 1. Only suitable 01057 * for usage for very old and limited systems (like MS-DOS), or by a 01058 * start point from which to set your custom options. 01059 * ---> 1 [BACKUP] 01060 * POSIX compatibility for backup. Simple settings, ISO level is set to 01061 * 3 and RR extensions are enabled. Useful for backup purposes. 01062 * Note that ACL and xattr are not enabled by default. 01063 * If you enable them, expect them not to show up in the mounted image. 01064 * They will have to be retrieved by libisofs applications like xorriso. 01065 * ---> 2 [DISTRIBUTION] 01066 * Setting for information distribution. Both RR and Joliet are enabled 01067 * to maximize compatibility with most systems. Permissions are set to 01068 * default values, and timestamps to the time of recording. 01069 * @return 01070 * 1 success, < 0 error 01071 * 01072 * @since 0.6.2 01073 */ 01074 int iso_write_opts_new(IsoWriteOpts **opts, int profile); 01075 01076 /** 01077 * Free an IsoWriteOpts previously allocated with iso_write_opts_new(). 01078 * 01079 * @since 0.6.2 01080 */ 01081 void iso_write_opts_free(IsoWriteOpts *opts); 01082 01083 /** 01084 * Set the ISO-9960 level to write at. 01085 * 01086 * @param level 01087 * -> 1 for higher compatibility with old systems. With this level 01088 * filenames are restricted to 8.3 characters. 01089 * -> 2 to allow up to 31 filename characters. 01090 * -> 3 to allow files greater than 4GB 01091 * @return 01092 * 1 success, < 0 error 01093 * 01094 * @since 0.6.2 01095 */ 01096 int iso_write_opts_set_iso_level(IsoWriteOpts *opts, int level); 01097 01098 /** 01099 * Whether to use or not Rock Ridge extensions. 01100 * 01101 * This are standard extensions to ECMA-119, intended to add POSIX filesystem 01102 * features to ECMA-119 images. Thus, usage of this flag is highly recommended 01103 * for images used on GNU/Linux systems. With the usage of RR extension, the 01104 * resulting image will have long filenames (up to 255 characters), deeper 01105 * directory structure, POSIX permissions and owner info on files and 01106 * directories, support for symbolic links or special files... All that 01107 * attributes can be modified/setted with the appropiate function. 01108 * 01109 * @param enable 01110 * 1 to enable RR extension, 0 to not add them 01111 * @return 01112 * 1 success, < 0 error 01113 * 01114 * @since 0.6.2 01115 */ 01116 int iso_write_opts_set_rockridge(IsoWriteOpts *opts, int enable); 01117 01118 /** 01119 * Whether to add the non-standard Joliet extension to the image. 01120 * 01121 * This extensions are heavily used in Microsoft Windows systems, so if you 01122 * plan to use your disc on such a system you should add this extension. 01123 * Usage of Joliet supplies longer filesystem length (up to 64 unicode 01124 * characters), and deeper directory structure. 01125 * 01126 * @param enable 01127 * 1 to enable Joliet extension, 0 to not add them 01128 * @return 01129 * 1 success, < 0 error 01130 * 01131 * @since 0.6.2 01132 */ 01133 int iso_write_opts_set_joliet(IsoWriteOpts *opts, int enable); 01134 01135 /** 01136 * Whether to use newer ISO-9660:1999 version. 01137 * 01138 * This is the second version of ISO-9660. It allows longer filenames and has 01139 * less restrictions than old ISO-9660. However, nobody is using it so there 01140 * are no much reasons to enable this. 01141 * 01142 * @since 0.6.2 01143 */ 01144 int iso_write_opts_set_iso1999(IsoWriteOpts *opts, int enable); 01145 01146 /** 01147 * Control writing of AAIP informations for ACL and xattr. 01148 * For importing ACL and xattr when inserting nodes from external filesystems 01149 * (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea(). 01150 * For loading of this information from images see iso_read_opts_set_no_aaip(). 01151 * 01152 * @param enable 1 = do not read AAIP information 01153 * 0 = read AAIP information if available 01154 * All other values are reserved. 01155 * @since 0.6.14 01156 */ 01157 int iso_write_opts_set_aaip(IsoWriteOpts *opts, int enable); 01158 01159 /** 01160 * Omit the version number (";1") at the end of the ISO-9660 identifiers. 01161 * This breaks ECMA-119 specification, but version numbers are usually not 01162 * used, so it should work on most systems. Use with caution. 01163 * 01164 * @since 0.6.2 01165 */ 01166 int iso_write_opts_set_omit_version_numbers(IsoWriteOpts *opts, int omit); 01167 01168 /** 01169 * Allow ISO-9660 directory hierarchy to be deeper than 8 levels. 01170 * This breaks ECMA-119 specification. Use with caution. 01171 * 01172 * @since 0.6.2 01173 */ 01174 int iso_write_opts_set_allow_deep_paths(IsoWriteOpts *opts, int allow); 01175 01176 /** 01177 * Allow path in the ISO-9660 tree to have more than 255 characters. 01178 * This breaks ECMA-119 specification. Use with caution. 01179 * 01180 * @since 0.6.2 01181 */ 01182 int iso_write_opts_set_allow_longer_paths(IsoWriteOpts *opts, int allow); 01183 01184 /** 01185 * Allow a single file or directory hierarchy to have up to 37 characters. 01186 * This is larger than the 31 characters allowed by ISO level 2, and the 01187 * extra space is taken from the version number, so this also forces 01188 * omit_version_numbers. 01189 * This breaks ECMA-119 specification and could lead to buffer overflow 01190 * problems on old systems. Use with caution. 01191 * 01192 * @since 0.6.2 01193 */ 01194 int iso_write_opts_set_max_37_char_filenames(IsoWriteOpts *opts, int allow); 01195 01196 /** 01197 * ISO-9660 forces filenames to have a ".", that separates file name from 01198 * extension. libisofs adds it if original filename doesn't has one. Set 01199 * this to 1 to prevent this behavior. 01200 * This breaks ECMA-119 specification. Use with caution. 01201 * 01202 * @since 0.6.2 01203 */ 01204 int iso_write_opts_set_no_force_dots(IsoWriteOpts *opts, int no); 01205 01206 /** 01207 * Allow lowercase characters in ISO-9660 filenames. By default, only 01208 * uppercase characters, numbers and a few other characters are allowed. 01209 * This breaks ECMA-119 specification. Use with caution. 01210 * 01211 * @since 0.6.2 01212 */ 01213 int iso_write_opts_set_allow_lowercase(IsoWriteOpts *opts, int allow); 01214 01215 /** 01216 * Allow all ASCII characters to be appear on an ISO-9660 filename. Note 01217 * that "/" and "\0" characters are never allowed, even in RR names. 01218 * This breaks ECMA-119 specification. Use with caution. 01219 * 01220 * @since 0.6.2 01221 */ 01222 int iso_write_opts_set_allow_full_ascii(IsoWriteOpts *opts, int allow); 01223 01224 /** 01225 * Allow all characters to be part of Volume and Volset identifiers on 01226 * the Primary Volume Descriptor. This breaks ISO-9660 contraints, but 01227 * should work on modern systems. 01228 * 01229 * @since 0.6.2 01230 */ 01231 int iso_write_opts_set_relaxed_vol_atts(IsoWriteOpts *opts, int allow); 01232 01233 /** 01234 * Allow paths in the Joliet tree to have more than 240 characters. 01235 * This breaks Joliet specification. Use with caution. 01236 * 01237 * @since 0.6.2 01238 */ 01239 int iso_write_opts_set_joliet_longer_paths(IsoWriteOpts *opts, int allow); 01240 01241 /** 01242 * Write Rock Ridge info as of specification RRIP-1.10 rather than RRIP-1.12: 01243 * signature "RRIP_1991A" rather than "IEEE_1282", field PX without file 01244 * serial number. 01245 * 01246 * @since 0.6.12 01247 */ 01248 int iso_write_opts_set_rrip_version_1_10(IsoWriteOpts *opts, int oldvers); 01249 01250 /** 01251 * Write AAIP as extension according to SUSP 1.10 rather than SUSP 1.12. 01252 * I.e. without announcing it by an ER field and thus without the need 01253 * to preceed the RRIP fields and the AA field by ES fields. 01254 * This saves 5 to 10 bytes per file and might avoid problems with readers 01255 * which dislike ER fields other than the ones for RRIP. 01256 * On the other hand, SUSP 1.12 frowns on such unannounced extensions 01257 * and prescribes ER and ES. It does this since the year 1994. 01258 * 01259 * In effect only if above iso_write_opts_set_aaip() enables writing of AAIP. 01260 * 01261 * @since 0.6.14 01262 */ 01263 int iso_write_opts_set_aaip_susp_1_10(IsoWriteOpts *opts, int oldvers); 01264 01265 /** 01266 * Store as ECMA-119 Directory Record timestamp the mtime of the source 01267 * rather than the image creation time. 01268 * 01269 * @since 0.6.12 01270 */ 01271 int iso_write_opts_set_dir_rec_mtime(IsoWriteOpts *opts, int allow); 01272 01273 /** 01274 * Whether to sort files based on their weight. 01275 * 01276 * @see iso_node_set_sort_weight 01277 * @since 0.6.2 01278 */ 01279 int iso_write_opts_set_sort_files(IsoWriteOpts *opts, int sort); 01280 01281 /** 01282 * Whether to set default values for files and directory permissions, gid and 01283 * uid. All these take one of three values: 0, 1 or 2. 01284 * 01285 * If 0, the corresponding attribute will be kept as setted in the IsoNode. 01286 * Unless you have changed it, it corresponds to the value on disc, so it 01287 * is suitable for backup purposes. If set to 1, the corresponding attrib. 01288 * will be changed by a default suitable value. Finally, if you set it to 01289 * 2, the attrib. will be changed with the value specified by the functioins 01290 * below. Note that for mode attributes, only the permissions are set, the 01291 * file type remains unchanged. 01292 * 01293 * @see iso_write_opts_set_default_dir_mode 01294 * @see iso_write_opts_set_default_file_mode 01295 * @see iso_write_opts_set_default_uid 01296 * @see iso_write_opts_set_default_gid 01297 * @since 0.6.2 01298 */ 01299 int iso_write_opts_set_replace_mode(IsoWriteOpts *opts, int dir_mode, 01300 int file_mode, int uid, int gid); 01301 01302 /** 01303 * Set the mode to use on dirs when you set the replace_mode of dirs to 2. 01304 * 01305 * @see iso_write_opts_set_replace_mode 01306 * @since 0.6.2 01307 */ 01308 int iso_write_opts_set_default_dir_mode(IsoWriteOpts *opts, mode_t dir_mode); 01309 01310 /** 01311 * Set the mode to use on files when you set the replace_mode of files to 2. 01312 * 01313 * @see iso_write_opts_set_replace_mode 01314 * @since 0.6.2 01315 */ 01316 int iso_write_opts_set_default_file_mode(IsoWriteOpts *opts, mode_t file_mode); 01317 01318 /** 01319 * Set the uid to use when you set the replace_uid to 2. 01320 * 01321 * @see iso_write_opts_set_replace_mode 01322 * @since 0.6.2 01323 */ 01324 int iso_write_opts_set_default_uid(IsoWriteOpts *opts, uid_t uid); 01325 01326 /** 01327 * Set the gid to use when you set the replace_gid to 2. 01328 * 01329 * @see iso_write_opts_set_replace_mode 01330 * @since 0.6.2 01331 */ 01332 int iso_write_opts_set_default_gid(IsoWriteOpts *opts, gid_t gid); 01333 01334 /** 01335 * 0 to use IsoNode timestamps, 1 to use recording time, 2 to use 01336 * values from timestamp field. This has only meaning if RR extensions 01337 * are enabled. 01338 * 01339 * @see iso_write_opts_set_default_timestamp 01340 * @since 0.6.2 01341 */ 01342 int iso_write_opts_set_replace_timestamps(IsoWriteOpts *opts, int replace); 01343 01344 /** 01345 * Set the timestamp to use when you set the replace_timestamps to 2. 01346 * 01347 * @see iso_write_opts_set_replace_timestamps 01348 * @since 0.6.2 01349 */ 01350 int iso_write_opts_set_default_timestamp(IsoWriteOpts *opts, time_t timestamp); 01351 01352 /** 01353 * Whether to always record timestamps in GMT. 01354 * 01355 * By default, libisofs stores local time information on image. You can set 01356 * this to always store timestamps converted to GMT. This prevents any 01357 * discrimination of the timezone of the image preparer by the image reader. 01358 * 01359 * It is useful if you want to hide your timezone, or you live in a timezone 01360 * that can't be represented in ECMA-119. These are timezones with an offset 01361 * from GMT greater than +13 hours, lower than -12 hours, or not a multiple 01362 * of 15 minutes. 01363 * Negative timezones (west of GMT) can trigger bugs in some operating systems 01364 * which typically appear in mounted ISO images as if the timezone shift from 01365 * GMT was applied twice (e.g. in New York 22:36 becomes 17:36). 01366 * 01367 * @since 0.6.2 01368 */ 01369 int iso_write_opts_set_always_gmt(IsoWriteOpts *opts, int gmt); 01370 01371 /** 01372 * Set the charset to use for the RR names of the files that will be created 01373 * on the image. 01374 * NULL to use default charset, that is the locale charset. 01375 * You can obtain the list of charsets supported on your system executing 01376 * "iconv -l" in a shell. 01377 * 01378 * @since 0.6.2 01379 */ 01380 int iso_write_opts_set_output_charset(IsoWriteOpts *opts, const char *charset); 01381 01382 /** 01383 * Set the type of the image to create. Libisofs support two kind of images: 01384 * stand-alone and appendable. 01385 * 01386 * A stand-alone image is an image that is valid alone, and that can be 01387 * mounted by its own. This is the kind of image you will want to create 01388 * in most cases. A stand-alone image can be burned in an empty CD or DVD, 01389 * or write to an .iso file for future burning or distribution. 01390 * 01391 * On the other side, an appendable image is not self contained, it refers 01392 * to serveral files that are stored outside the image. Its usage is for 01393 * multisession discs, where you add data in a new session, while the 01394 * previous session data can still be accessed. In those cases, the old 01395 * data is not written again. Instead, the new image refers to it, and thus 01396 * it's only valid when appended to the original. Note that in those cases 01397 * the image will be written after the original, and thus you will want 01398 * to use a ms_block greater than 0. 01399 * 01400 * Note that if you haven't import a previous image (by means of 01401 * iso_image_import()), the image will always be a stand-alone image, as 01402 * there is no previous data to refer to. 01403 * 01404 * @param appendable 01405 * 1 to create an appendable image, 0 for an stand-alone one. 01406 * 01407 * @since 0.6.2 01408 */ 01409 int iso_write_opts_set_appendable(IsoWriteOpts *opts, int appendable); 01410 01411 /** 01412 * Set the start block of the image. It is supposed to be the lba where the 01413 * first block of the image will be written on disc. All references inside the 01414 * ISO image will take this into account, thus providing a mountable image. 01415 * 01416 * For appendable images, that are written to a new session, you should 01417 * pass here the lba of the next writable address on disc. 01418 * 01419 * In stand alone images this is usually 0. However, you may want to 01420 * provide a different ms_block if you don't plan to burn the image in the 01421 * first session on disc, such as in some CD-Extra disc whether the data 01422 * image is written in a new session after some audio tracks. 01423 * 01424 * @since 0.6.2 01425 */ 01426 int iso_write_opts_set_ms_block(IsoWriteOpts *opts, uint32_t ms_block); 01427 01428 /** 01429 * Sets the buffer where to store the descriptors which shall to be written 01430 * at the beginning of an overwriteable media to point to the newly written 01431 * image. 01432 * This is needed if the write start address of the image is not 0. 01433 * In this case the first 64 KiB of the media have to be overwritten 01434 * by the buffer content after the session was written and the buffer 01435 * was updated by libisofs. Otherwise the new session would not be 01436 * found by operating system function mount() or by libisoburn. 01437 * (One could still mount that session if its start address is known.) 01438 * 01439 * If you do not need this information, for example because you are creating a 01440 * new image for LBA 0 or because you will create an image for a true 01441 * multisession media, just do not use this call or set buffer to NULL. 01442 * 01443 * Use cases: 01444 * 01445 * - Together with iso_write_opts_set_appendable(opts, 1) the buffer serves 01446 * for the growing of an image as done in growisofs by Andy Polyakov. 01447 * This allows appending of a new session to non-multisession media, such 01448 * as DVD+RW. The new session will refer to the data of previous sessions 01449 * on the same media. 01450 * libisoburn emulates multisession appendability on overwriteable media 01451 * and disk files by performing this use case. 01452 * 01453 * - Together with iso_write_opts_set_appendable(opts, 0) the buffer allows 01454 * to write the first session on overwriteable media to start addresses 01455 * other than 0. 01456 * libisoburn in most cases writes the first session on overwriteable media 01457 * and disk files to LBA 32 in order to preserve its descriptors from the 01458 * subsequent overwriting by the descriptor buffer of later sessions. 01459 * 01460 * @param buffer 01461 * When not NULL, it should point to at least 64KiB of memory, where 01462 * libisofs will install the contents that shall be written at the 01463 * beginning of overwriteable media. 01464 * You should initialize the buffer either with 0s, or with the contents 01465 * of the first 32 blocks of the image you are growing. In most cases, 01466 * 0 is good enought. 01467 * 01468 * @since 0.6.2 01469 */ 01470 int iso_write_opts_set_overwrite_buf(IsoWriteOpts *opts, uint8_t *overwrite); 01471 01472 /** 01473 * Set the size, in number of blocks, of the FIFO buffer used between the 01474 * writer thread and the burn_source. You have to provide at least a 32 01475 * blocks buffer. Default value is set to 2MB, if that is ok for you, you 01476 * don't need to call this function. 01477 * 01478 * @since 0.6.2 01479 */ 01480 int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size); 01481 01482 /** 01483 * Inquire the start address of the file data blocks after having used 01484 * IsoWriteOpts with iso_image_create_burn_source(). 01485 * @param opts 01486 * The option set that was used when starting image creation 01487 * @param data_start 01488 * Returns the logical block address if it is already valid 01489 * @param flag 01490 * Reserved for future usage, set to 0. 01491 * @return 01492 * 1 indicates valid data_start, <0 indicates invalid data_start 01493 * 01494 * @since 0.6.16 01495 */ 01496 int iso_write_opts_get_data_start(IsoWriteOpts *opts, uint32_t *data_start, 01497 int flag); 01498 01499 /** 01500 * Create a burn_source and a thread which immediately begins to generate 01501 * the image. That burn_source can be used with libburn as a data source 01502 * for a track. For its public declaration see libburn.h. 01503 * 01504 * If image generation shall be aborted by the application program, then 01505 * the .cancel() method of the burn_source must be called to end the 01506 * generation thread: burn_src->cancel(burn_src); 01507 * 01508 * @param image 01509 * The image to write. 01510 * @param opts 01511 * The options for image generation. All needed data will be copied, so 01512 * you can free the given struct once this function returns. 01513 * @param burn_src 01514 * Location where the pointer to the burn_source will be stored 01515 * @return 01516 * 1 on success, < 0 on error 01517 * 01518 * @since 0.6.2 01519 */ 01520 int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts, 01521 struct burn_source **burn_src); 01522 01523 /** 01524 * Update the sizes of all files added to image. 01525 * 01526 * This may be called just before iso_image_create_burn_source() to force 01527 * libisofs to check the file sizes again (they're already checked when added 01528 * to IsoImage). It is useful if you have changed some files after adding then 01529 * to the image. 01530 * 01531 * @return 01532 * 1 on success, < 0 on error 01533 * @since 0.6.8 01534 */ 01535 int iso_image_update_sizes(IsoImage *image); 01536 01537 /** 01538 * Creates an IsoReadOpts for reading an existent image. You should set the 01539 * options desired with the correspondent setters. Note that you may want to 01540 * set the start block value. 01541 * 01542 * Options by default are determined by the selected profile. 01543 * 01544 * @param opts 01545 * Pointer to the location where the newly created IsoReadOpts will be 01546 * stored. You should free it with iso_read_opts_free() when no more 01547 * needed. 01548 * @param profile 01549 * Default profile for image reading. For now the following values are 01550 * defined: 01551 * ---> 0 [STANDARD] 01552 * Suitable for most situations. Most extension are read. When both 01553 * Joliet and RR extension are present, RR is used. 01554 * AAIP for ACL and xattr is not enabled by default. 01555 * @return 01556 * 1 success, < 0 error 01557 * 01558 * @since 0.6.2 01559 */ 01560 int iso_read_opts_new(IsoReadOpts **opts, int profile); 01561 01562 /** 01563 * Free an IsoReadOpts previously allocated with iso_read_opts_new(). 01564 * 01565 * @since 0.6.2 01566 */ 01567 void iso_read_opts_free(IsoReadOpts *opts); 01568 01569 /** 01570 * Set the block where the image begins. It is usually 0, but may be different 01571 * on a multisession disc. 01572 * 01573 * @since 0.6.2 01574 */ 01575 int iso_read_opts_set_start_block(IsoReadOpts *opts, uint32_t block); 01576 01577 /** 01578 * Do not read Rock Ridge extensions. 01579 * In most cases you don't want to use this. It could be useful if RR info 01580 * is damaged, or if you want to use the Joliet tree. 01581 * 01582 * @since 0.6.2 01583 */ 01584 int iso_read_opts_set_no_rockridge(IsoReadOpts *opts, int norr); 01585 01586 /** 01587 * Do not read Joliet extensions. 01588 * 01589 * @since 0.6.2 01590 */ 01591 int iso_read_opts_set_no_joliet(IsoReadOpts *opts, int nojoliet); 01592 01593 /** 01594 * Do not read ISO 9660:1999 enhanced tree 01595 * 01596 * @since 0.6.2 01597 */ 01598 int iso_read_opts_set_no_iso1999(IsoReadOpts *opts, int noiso1999); 01599 01600 /** 01601 * Control reading of AAIP informations about ACL and xattr when loading 01602 * existing images. 01603 * For importing ACL and xattr when inserting nodes from external filesystems 01604 * (e.g. the local POSIX filesystem) see iso_image_set_ignore_aclea(). 01605 * For eventual writing of this information see iso_write_opts_set_aaip(). 01606 * 01607 * @param noaaip 1 = do not read AAIP information 01608 * 0 = read AAIP information if available 01609 * All other values are reserved. 01610 * @since 0.6.14 01611 */ 01612 int iso_read_opts_set_no_aaip(IsoReadOpts *opts, int noaaip); 01613 01614 /** 01615 * Whether to prefer Joliet over RR. libisofs usually prefers RR over 01616 * Joliet, as it give us much more info about files. So, if both extensions 01617 * are present, RR is used. You can set this if you prefer Joliet, but 01618 * note that this is not very recommended. This doesn't mean than RR 01619 * extensions are not read: if no Joliet is present, libisofs will read 01620 * RR tree. 01621 * 01622 * @since 0.6.2 01623 */ 01624 int iso_read_opts_set_preferjoliet(IsoReadOpts *opts, int preferjoliet); 01625 01626 /** 01627 * Set default uid for files when RR extensions are not present. 01628 * 01629 * @since 0.6.2 01630 */ 01631 int iso_read_opts_set_default_uid(IsoReadOpts *opts, uid_t uid); 01632 01633 /** 01634 * Set default gid for files when RR extensions are not present. 01635 * 01636 * @since 0.6.2 01637 */ 01638 int iso_read_opts_set_default_gid(IsoReadOpts *opts, gid_t gid); 01639 01640 /** 01641 * Set default permissions for files when RR extensions are not present. 01642 * 01643 * @param file_perm 01644 * Permissions for files. 01645 * @param dir_perm 01646 * Permissions for directories. 01647 * 01648 * @since 0.6.2 01649 */ 01650 int iso_read_opts_set_default_permissions(IsoReadOpts *opts, mode_t file_perm, 01651 mode_t dir_perm); 01652 01653 /** 01654 * Set the input charset of the file names on the image. NULL to use locale 01655 * charset. You have to specify a charset if the image filenames are encoded 01656 * in a charset different that the local one. This could happen, for example, 01657 * if the image was created on a system with different charset. 01658 * 01659 * @param charset 01660 * The charset to use as input charset. You can obtain the list of 01661 * charsets supported on your system executing "iconv -l" in a shell. 01662 * 01663 * @since 0.6.2 01664 */ 01665 int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset); 01666 01667 /** 01668 * Import a previous session or image, for growing or modify. 01669 * 01670 * @param image 01671 * The image context to which old image will be imported. Note that all 01672 * files added to image, and image attributes, will be replaced with the 01673 * contents of the old image. 01674 * TODO #00025 support for merging old image files 01675 * @param src 01676 * Data Source from which old image will be read. A extra reference is 01677 * added, so you still need to iso_data_source_unref() yours. 01678 * @param opts 01679 * Options for image import. All needed data will be copied, so you 01680 * can free the given struct once this function returns. 01681 * @param features 01682 * If not NULL, a new IsoReadImageFeatures will be allocated and filled 01683 * with the features of the old image. It should be freed with 01684 * iso_read_image_features_destroy() when no more needed. You can pass 01685 * NULL if you're not interested on them. 01686 * @return 01687 * 1 on success, < 0 on error 01688 * 01689 * @since 0.6.2 01690 */ 01691 int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts, 01692 IsoReadImageFeatures **features); 01693 01694 /** 01695 * Destroy an IsoReadImageFeatures object obtained with iso_image_import. 01696 * 01697 * @since 0.6.2 01698 */ 01699 void iso_read_image_features_destroy(IsoReadImageFeatures *f); 01700 01701 /** 01702 * Get the size (in 2048 byte block) of the image, as reported in the PVM. 01703 * 01704 * @since 0.6.2 01705 */ 01706 uint32_t iso_read_image_features_get_size(IsoReadImageFeatures *f); 01707 01708 /** 01709 * Whether RockRidge extensions are present in the image imported. 01710 * 01711 * @since 0.6.2 01712 */ 01713 int iso_read_image_features_has_rockridge(IsoReadImageFeatures *f); 01714 01715 /** 01716 * Whether Joliet extensions are present in the image imported. 01717 * 01718 * @since 0.6.2 01719 */ 01720 int iso_read_image_features_has_joliet(IsoReadImageFeatures *f); 01721 01722 /** 01723 * Whether the image is recorded according to ISO 9660:1999, i.e. it has 01724 * a version 2 Enhanced Volume Descriptor. 01725 * 01726 * @since 0.6.2 01727 */ 01728 int iso_read_image_features_has_iso1999(IsoReadImageFeatures *f); 01729 01730 /** 01731 * Whether El-Torito boot record is present present in the image imported. 01732 * 01733 * @since 0.6.2 01734 */ 01735 int iso_read_image_features_has_eltorito(IsoReadImageFeatures *f); 01736 01737 /** 01738 * Increments the reference counting of the given image. 01739 * 01740 * @since 0.6.2 01741 */ 01742 void iso_image_ref(IsoImage *image); 01743 01744 /** 01745 * Decrements the reference couting of the given image. 01746 * If it reaches 0, the image is free, together with its tree nodes (whether 01747 * their refcount reach 0 too, of course). 01748 * 01749 * @since 0.6.2 01750 */ 01751 void iso_image_unref(IsoImage *image); 01752 01753 /** 01754 * Attach user defined data to the image. Use this if your application needs 01755 * to store addition info together with the IsoImage. If the image already 01756 * has data attached, the old data will be freed. 01757 * 01758 * @param data 01759 * Pointer to application defined data that will be attached to the 01760 * image. You can pass NULL to remove any already attached data. 01761 * @param give_up 01762 * Function that will be called when the image does not need the data 01763 * any more. It receives the data pointer as an argumente, and eventually 01764 * causes data to be freed. It can be NULL if you don't need it. 01765 * @return 01766 * 1 on succes, < 0 on error 01767 * 01768 * @since 0.6.2 01769 */ 01770 int iso_image_attach_data(IsoImage *image, void *data, void (*give_up)(void*)); 01771 01772 /** 01773 * The the data previously attached with iso_image_attach_data() 01774 * 01775 * @since 0.6.2 01776 */ 01777 void *iso_image_get_attached_data(IsoImage *image); 01778 01779 /** 01780 * Get the root directory of the image. 01781 * No extra ref is added to it, so you musn't unref it. Use iso_node_ref() 01782 * if you want to get your own reference. 01783 * 01784 * @since 0.6.2 01785 */ 01786 IsoDir *iso_image_get_root(const IsoImage *image); 01787 01788 /** 01789 * Fill in the volset identifier for a image. 01790 * 01791 * @since 0.6.2 01792 */ 01793 void iso_image_set_volset_id(IsoImage *image, const char *volset_id); 01794 01795 /** 01796 * Get the volset identifier. 01797 * The returned string is owned by the image and should not be freed nor 01798 * changed. 01799 * 01800 * @since 0.6.2 01801 */ 01802 const char *iso_image_get_volset_id(const IsoImage *image); 01803 01804 /** 01805 * Fill in the volume identifier for a image. 01806 * 01807 * @since 0.6.2 01808 */ 01809 void iso_image_set_volume_id(IsoImage *image, const char *volume_id); 01810 01811 /** 01812 * Get the volume identifier. 01813 * The returned string is owned by the image and should not be freed nor 01814 * changed. 01815 * 01816 * @since 0.6.2 01817 */ 01818 const char *iso_image_get_volume_id(const IsoImage *image); 01819 01820 /** 01821 * Fill in the publisher for a image. 01822 * 01823 * @since 0.6.2 01824 */ 01825 void iso_image_set_publisher_id(IsoImage *image, const char *publisher_id); 01826 01827 /** 01828 * Get the publisher of a image. 01829 * The returned string is owned by the image and should not be freed nor 01830 * changed. 01831 * 01832 * @since 0.6.2 01833 */ 01834 const char *iso_image_get_publisher_id(const IsoImage *image); 01835 01836 /** 01837 * Fill in the data preparer for a image. 01838 * 01839 * @since 0.6.2 01840 */ 01841 void iso_image_set_data_preparer_id(IsoImage *image, 01842 const char *data_preparer_id); 01843 01844 /** 01845 * Get the data preparer of a image. 01846 * The returned string is owned by the image and should not be freed nor 01847 * changed. 01848 * 01849 * @since 0.6.2 01850 */ 01851 const char *iso_image_get_data_preparer_id(const IsoImage *image); 01852 01853 /** 01854 * Fill in the system id for a image. Up to 32 characters. 01855 * 01856 * @since 0.6.2 01857 */ 01858 void iso_image_set_system_id(IsoImage *image, const char *system_id); 01859 01860 /** 01861 * Get the system id of a image. 01862 * The returned string is owned by the image and should not be freed nor 01863 * changed. 01864 * 01865 * @since 0.6.2 01866 */ 01867 const char *iso_image_get_system_id(const IsoImage *image); 01868 01869 /** 01870 * Fill in the application id for a image. Up to 128 chars. 01871 * 01872 * @since 0.6.2 01873 */ 01874 void iso_image_set_application_id(IsoImage *image, const char *application_id); 01875 01876 /** 01877 * Get the application id of a image. 01878 * The returned string is owned by the image and should not be freed nor 01879 * changed. 01880 * 01881 * @since 0.6.2 01882 */ 01883 const char *iso_image_get_application_id(const IsoImage *image); 01884 01885 /** 01886 * Fill copyright information for the image. Usually this refers 01887 * to a file on disc. Up to 37 characters. 01888 * 01889 * @since 0.6.2 01890 */ 01891 void iso_image_set_copyright_file_id(IsoImage *image, 01892 const char *copyright_file_id); 01893 01894 /** 01895 * Get the copyright information of a image. 01896 * The returned string is owned by the image and should not be freed nor 01897 * changed. 01898 * 01899 * @since 0.6.2 01900 */ 01901 const char *iso_image_get_copyright_file_id(const IsoImage *image); 01902 01903 /** 01904 * Fill abstract information for the image. Usually this refers 01905 * to a file on disc. Up to 37 characters. 01906 * 01907 * @since 0.6.2 01908 */ 01909 void iso_image_set_abstract_file_id(IsoImage *image, 01910 const char *abstract_file_id); 01911 01912 /** 01913 * Get the abstract information of a image. 01914 * The returned string is owned by the image and should not be freed nor 01915 * changed. 01916 * 01917 * @since 0.6.2 01918 */ 01919 const char *iso_image_get_abstract_file_id(const IsoImage *image); 01920 01921 /** 01922 * Fill biblio information for the image. Usually this refers 01923 * to a file on disc. Up to 37 characters. 01924 * 01925 * @since 0.6.2 01926 */ 01927 void iso_image_set_biblio_file_id(IsoImage *image, const char *biblio_file_id); 01928 01929 /** 01930 * Get the biblio information of a image. 01931 * The returned string is owned by the image and should not be freed nor 01932 * changed. 01933 * 01934 * @since 0.6.2 01935 */ 01936 const char *iso_image_get_biblio_file_id(const IsoImage *image); 01937 01938 /** 01939 * Create a bootable image by adding a El-Torito boot image. 01940 * 01941 * This also add a catalog boot node to the image filesystem tree. 01942 * 01943 * @param image 01944 * The image to make bootable. If it was already bootable this function 01945 * returns an error and the image remains unmodified. 01946 * @param image_path 01947 * The path on the image tree of a regular file to use as default boot 01948 * image. 01949 * @param type 01950 * The boot media type. This can be one of 3 types: 01951 * - Floppy emulation: Boot image file must be exactly 01952 * 1200 kB, 1440 kB or 2880 kB. 01953 * - Hard disc emulation: The image must begin with a master 01954 * boot record with a single image. 01955 * - No emulation. You should specify load segment and load size 01956 * of image. 01957 * @param catalog_path 01958 * The path on the image tree where the catalog will be stored. The 01959 * directory component of this path must be a directory existent on the 01960 * image tree, and the filename component must be unique among all 01961 * children of that directory on image. Otherwise a correspodent error 01962 * code will be returned. This function will add an IsoBoot node that acts 01963 * as a placeholder for the real catalog, that will be generated at image 01964 * creation time. 01965 * @param boot 01966 * Location where a pointer to the added boot image will be stored. That 01967 * object is owned by the IsoImage and should not be freed by the user, 01968 * nor dereferenced once the last reference to the IsoImage was disposed 01969 * via iso_image_unref(). A NULL value is allowed if you don't need a 01970 * reference to the boot image. 01971 * @return 01972 * 1 on success, < 0 on error 01973 * 01974 * @since 0.6.2 01975 */ 01976 int iso_image_set_boot_image(IsoImage *image, const char *image_path, 01977 enum eltorito_boot_media_type type, 01978 const char *catalog_path, 01979 ElToritoBootImage **boot); 01980 01981 /* TODO #00026 : add support for "hidden" bootable images. */ 01982 01983 /** 01984 * Get El-Torito boot image of an ISO image, if any. 01985 * 01986 * This can be useful, for example, to check if a volume read from a previous 01987 * session or an existing image is bootable. It can also be useful to get 01988 * the image and catalog tree nodes. An application would want those, for 01989 * example, to prevent the user removing it. 01990 * 01991 * Both nodes are owned by libisofs and should not be freed. You can get your 01992 * own ref with iso_node_ref(). You can can also check if the node is already 01993 * on the tree by getting its parent (note that when reading El-Torito info 01994 * from a previous image, the nodes might not be on the tree even if you haven't 01995 * removed them). Remember that you'll need to get a new ref 01996 * (with iso_node_ref()) before inserting them again to the tree, and probably 01997 * you will also need to set the name or permissions. 01998 * 01999 * @param image 02000 * The image from which to get the boot image. 02001 * @param boot 02002 * If not NULL, it will be filled with a pointer to the boot image, if 02003 * any. That object is owned by the IsoImage and should not be freed by 02004 * the user, nor dereferenced once the last reference to the IsoImage was 02005 * disposed via iso_image_unref(). 02006 * @param imgnode 02007 * When not NULL, it will be filled with the image tree node. No extra ref 02008 * is added, you can use iso_node_ref() to get one if you need it. 02009 * @param catnode 02010 * When not NULL, it will be filled with the catnode tree node. No extra 02011 * ref is added, you can use iso_node_ref() to get one if you need it. 02012 * @return 02013 * 1 on success, 0 is the image is not bootable (i.e., it has no El-Torito 02014 * image), < 0 error. 02015 * 02016 * @since 0.6.2 02017 */ 02018 int iso_image_get_boot_image(IsoImage *image, ElToritoBootImage **boot, 02019 IsoFile **imgnode, IsoBoot **catnode); 02020 02021 /** 02022 * Removes the El-Torito bootable image. 02023 * 02024 * The IsoBoot node that acts as placeholder for the catalog is also removed 02025 * for the image tree, if there. 02026 * If the image is not bootable (don't have el-torito boot image) this function 02027 * just returns. 02028 * 02029 * @since 0.6.2 02030 */ 02031 void iso_image_remove_boot_image(IsoImage *image); 02032 02033 /** 02034 * Sets the load segment for the initial boot image. This is only for 02035 * no emulation boot images, and is a NOP for other image types. 02036 * 02037 * @since 0.6.2 02038 */ 02039 void el_torito_set_load_seg(ElToritoBootImage *bootimg, short segment); 02040 02041 /** 02042 * Sets the number of sectors (512b) to be load at load segment during 02043 * the initial boot procedure. This is only for 02044 * no emulation boot images, and is a NOP for other image types. 02045 * 02046 * @since 0.6.2 02047 */ 02048 void el_torito_set_load_size(ElToritoBootImage *bootimg, short sectors); 02049 02050 /** 02051 * Marks the specified boot image as not bootable 02052 * 02053 * @since 0.6.2 02054 */ 02055 void el_torito_set_no_bootable(ElToritoBootImage *bootimg); 02056 02057 /** 02058 * Specifies that this image needs to be patched. This involves the writting 02059 * of a 56 bytes boot information table at offset 8 of the boot image file. 02060 * The original boot image file won't be modified. 02061 * This is needed for isolinux boot images. 02062 * 02063 * @since 0.6.2 02064 * @deprecated Use el_torito_set_isolinux_options() instead 02065 */ 02066 void el_torito_patch_isolinux_image(ElToritoBootImage *bootimg); 02067 02068 /** 02069 * Specifies options for IsoLinux boot images. This should only be used with 02070 * isolinux boot images. 02071 * 02072 * @param options 02073 * bitmask style flag. The following values are defined: 02074 * 02075 * bit 0 -> 1 to path the image, 0 to not 02076 * Patching the image involves the writing of a 56 bytes 02077 * boot information table at offset 8 of the boot image file. 02078 * The original boot image file will not be modified. This is 02079 * needed to allow isolinux images to be bootable. 02080 * bit 1 -> 1 to generate an hybrid image with MBR, 0 to not 02081 * An hybrid image is a boot image that boots from either 02082 * CD/DVD media or from disk-like media, e.g. USB stick. 02083 * For that you need isolinux.bin from SYSLINUX 3.72 or later. 02084 * IMPORTANT: The application has to take care that the image 02085 * on media gets padded up to the next full MB. 02086 * @param flag 02087 * Reserved for future usage, set to 0. 02088 * @return 02089 * 1 success, < 0 on error 02090 * @since 0.6.12 02091 */ 02092 int el_torito_set_isolinux_options(ElToritoBootImage *bootimg, int options, int flag); 02093 02094 /** 02095 * Increments the reference counting of the given node. 02096 * 02097 * @since 0.6.2 02098 */ 02099 void iso_node_ref(IsoNode *node); 02100 02101 /** 02102 * Decrements the reference couting of the given node. 02103 * If it reach 0, the node is free, and, if the node is a directory, 02104 * its children will be unref() too. 02105 * 02106 * @since 0.6.2 02107 */ 02108 void iso_node_unref(IsoNode *node); 02109 02110 /** 02111 * Get the type of an IsoNode. 02112 * 02113 * @since 0.6.2 02114 */ 02115 enum IsoNodeType iso_node_get_type(IsoNode *node); 02116 02117 /** 02118 * Function to handle particular extended information. The function 02119 * pointer acts as an identifier for the type of the information. Structs 02120 * with same information type must use the same function. 02121 * 02122 * @param data 02123 * Attached data 02124 * @param flag 02125 * What to do with the data. At this time the following values are 02126 * defined: 02127 * -> 1 the data must be freed 02128 * @return 02129 * 1 in any case. 02130 * 02131 * @since 0.6.4 02132 */ 02133 typedef int (*iso_node_xinfo_func)(void *data, int flag); 02134 02135 /** 02136 * Add extended information to the given node. Extended info allows 02137 * applications (and libisofs itself) to add more information to an IsoNode. 02138 * You can use this facilities to associate temporary information with a given 02139 * node. This information is not written into the ISO 9660 image on media 02140 * and thus does not persist longer than the node memory object. 02141 * 02142 * Each node keeps a list of added extended info, meaning you can add several 02143 * extended info data to each node. Each extended info you add is identified 02144 * by the proc parameter, a pointer to a function that knows how to manage 02145 * the external info data. Thus, in order to add several types of extended 02146 * info, you need to define a "proc" function for each type. 02147 * 02148 * @param node 02149 * The node where to add the extended info 02150 * @param proc 02151 * A function pointer used to identify the type of the data, and that 02152 * knows how to manage it 02153 * @param data 02154 * Extended info to add. 02155 * @return 02156 * 1 if success, 0 if the given node already has extended info of the 02157 * type defined by the "proc" function, < 0 on error 02158 * 02159 * @since 0.6.4 02160 */ 02161 int iso_node_add_xinfo(IsoNode *node, iso_node_xinfo_func proc, void *data); 02162 02163 /** 02164 * Remove the given extended info (defined by the proc function) from the 02165 * given node. 02166 * 02167 * @return 02168 * 1 on success, 0 if node does not have extended info of the requested 02169 * type, < 0 on error 02170 * 02171 * @since 0.6.4 02172 */ 02173 int iso_node_remove_xinfo(IsoNode *node, iso_node_xinfo_func proc); 02174 02175 /** 02176 * Get the given extended info (defined by the proc function) from the 02177 * given node. 02178 * 02179 * @param data 02180 * Will be filled with the extended info corresponding to the given proc 02181 * function 02182 * @return 02183 * 1 on success, 0 if node does not have extended info of the requested 02184 * type, < 0 on error 02185 * 02186 * @since 0.6.4 02187 */ 02188 int iso_node_get_xinfo(IsoNode *node, iso_node_xinfo_func proc, void **data); 02189 02190 /** 02191 * Set the name of a node. Note that if the node is already added to a dir 02192 * this can fail if dir already contains a node with the new name. 02193 * 02194 * @param node 02195 * The node whose name you want to change. Note that you can't change 02196 * the name of the root. 02197 * @param name 02198 * The name for the node. If you supply an empty string or a 02199 * name greater than 255 characters this returns with failure, and 02200 * node name is not modified. 02201 * @return 02202 * 1 on success, < 0 on error 02203 * 02204 * @since 0.6.2 02205 */ 02206 int iso_node_set_name(IsoNode *node, const char *name); 02207 02208 /** 02209 * Get the name of a node. 02210 * The returned string belongs to the node and should not be modified nor 02211 * freed. Use strdup if you really need your own copy. 02212 * 02213 * @since 0.6.2 02214 */ 02215 const char *iso_node_get_name(const IsoNode *node); 02216 02217 /** 02218 * Set the permissions for the node. This attribute is only useful when 02219 * Rock Ridge extensions are enabled. 02220 * 02221 * @param mode 02222 * bitmask with the permissions of the node, as specified in 'man 2 stat'. 02223 * The file type bitfields will be ignored, only file permissions will be 02224 * modified. 02225 * 02226 * @since 0.6.2 02227 */ 02228 void iso_node_set_permissions(IsoNode *node, mode_t mode); 02229 02230 /** 02231 * Get the permissions for the node 02232 * 02233 * @since 0.6.2 02234 */ 02235 mode_t iso_node_get_permissions(const IsoNode *node); 02236 02237 /** 02238 * Get the mode of the node, both permissions and file type, as specified in 02239 * 'man 2 stat'. 02240 * 02241 * @since 0.6.2 02242 */ 02243 mode_t iso_node_get_mode(const IsoNode *node); 02244 02245 /** 02246 * Set the user id for the node. This attribute is only useful when 02247 * Rock Ridge extensions are enabled. 02248 * 02249 * @since 0.6.2 02250 */ 02251 void iso_node_set_uid(IsoNode *node, uid_t uid); 02252 02253 /** 02254 * Get the user id of the node. 02255 * 02256 * @since 0.6.2 02257 */ 02258 uid_t iso_node_get_uid(const IsoNode *node); 02259 02260 /** 02261 * Set the group id for the node. This attribute is only useful when 02262 * Rock Ridge extensions are enabled. 02263 * 02264 * @since 0.6.2 02265 */ 02266 void iso_node_set_gid(IsoNode *node, gid_t gid); 02267 02268 /** 02269 * Get the group id of the node. 02270 * 02271 * @since 0.6.2 02272 */ 02273 gid_t iso_node_get_gid(const IsoNode *node); 02274 02275 /** 02276 * Set the time of last modification of the file 02277 * 02278 * @since 0.6.2 02279 */ 02280 void iso_node_set_mtime(IsoNode *node, time_t time); 02281 02282 /** 02283 * Get the time of last modification of the file 02284 * 02285 * @since 0.6.2 02286 */ 02287 time_t iso_node_get_mtime(const IsoNode *node); 02288 02289 /** 02290 * Set the time of last access to the file 02291 * 02292 * @since 0.6.2 02293 */ 02294 void iso_node_set_atime(IsoNode *node, time_t time); 02295 02296 /** 02297 * Get the time of last access to the file 02298 * 02299 * @since 0.6.2 02300 */ 02301 time_t iso_node_get_atime(const IsoNode *node); 02302 02303 /** 02304 * Set the time of last status change of the file 02305 * 02306 * @since 0.6.2 02307 */ 02308 void iso_node_set_ctime(IsoNode *node, time_t time); 02309 02310 /** 02311 * Get the time of last status change of the file 02312 * 02313 * @since 0.6.2 02314 */ 02315 time_t iso_node_get_ctime(const IsoNode *node); 02316 02317 /** 02318 * Set if the node will be hidden in RR/ISO tree, Joliet tree or both. 02319 * 02320 * If the file is setted as hidden in one tree, it won't be included there, so 02321 * it won't be visible in a OS accessing CD using that tree. For example, 02322 * GNU/Linux systems access to Rock Ridge / ISO9960 tree in order to see 02323 * what is recorded on CD, while MS Windows make use of the Joliet tree. If a 02324 * file is hidden only in Joliet, it won't be visible in Windows systems, 02325 * while still visible in Linux. 02326 * 02327 * If a file is hidden in both trees, it won't be written to image. 02328 * 02329 * @param node 02330 * The node that is to be hidden. 02331 * @param hide_attrs 02332 * IsoHideNodeFlag's to set the trees in which file will be hidden. 02333 * 02334 * @since 0.6.2 02335 */ 02336 void iso_node_set_hidden(IsoNode *node, int hide_attrs); 02337 02338 /** 02339 * Add a new node to a dir. Note that this function don't add a new ref to 02340 * the node, so you don't need to free it, it will be automatically freed 02341 * when the dir is deleted. Of course, if you want to keep using the node 02342 * after the dir life, you need to iso_node_ref() it. 02343 * 02344 * @param dir 02345 * the dir where to add the node 02346 * @param child 02347 * the node to add. You must ensure that the node hasn't previously added 02348 * to other dir, and that the node name is unique inside the child. 02349 * Otherwise this function will return a failure, and the child won't be 02350 * inserted. 02351 * @param replace 02352 * if the dir already contains a node with the same name, whether to 02353 * replace or not the old node with this. 02354 * @return 02355 * number of nodes in dir if succes, < 0 otherwise 02356 * Possible errors: 02357 * ISO_NULL_POINTER, if dir or child are NULL 02358 * ISO_NODE_ALREADY_ADDED, if child is already added to other dir 02359 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02360 * ISO_WRONG_ARG_VALUE, if child == dir, or replace != (0,1) 02361 * 02362 * @since 0.6.2 02363 */ 02364 int iso_dir_add_node(IsoDir *dir, IsoNode *child, 02365 enum iso_replace_mode replace); 02366 02367 /** 02368 * Locate a node inside a given dir. 02369 * 02370 * @param dir 02371 * The dir where to look for the node. 02372 * @param name 02373 * The name of the node 02374 * @param node 02375 * Location for a pointer to the node, it will filled with NULL if the dir 02376 * doesn't have a child with the given name. 02377 * The node will be owned by the dir and shouldn't be unref(). Just call 02378 * iso_node_ref() to get your own reference to the node. 02379 * Note that you can pass NULL is the only thing you want to do is check 02380 * if a node with such name already exists on dir. 02381 * @return 02382 * 1 node found, 0 child has no such node, < 0 error 02383 * Possible errors: 02384 * ISO_NULL_POINTER, if dir or name are NULL 02385 * 02386 * @since 0.6.2 02387 */ 02388 int iso_dir_get_node(IsoDir *dir, const char *name, IsoNode **node); 02389 02390 /** 02391 * Get the number of children of a directory. 02392 * 02393 * @return 02394 * >= 0 number of items, < 0 error 02395 * Possible errors: 02396 * ISO_NULL_POINTER, if dir is NULL 02397 * 02398 * @since 0.6.2 02399 */ 02400 int iso_dir_get_children_count(IsoDir *dir); 02401 02402 /** 02403 * Removes a child from a directory. 02404 * The child is not freed, so you will become the owner of the node. Later 02405 * you can add the node to another dir (calling iso_dir_add_node), or free 02406 * it if you don't need it (with iso_node_unref). 02407 * 02408 * @return 02409 * 1 on success, < 0 error 02410 * Possible errors: 02411 * ISO_NULL_POINTER, if node is NULL 02412 * ISO_NODE_NOT_ADDED_TO_DIR, if node doesn't belong to a dir 02413 * 02414 * @since 0.6.2 02415 */ 02416 int iso_node_take(IsoNode *node); 02417 02418 /** 02419 * Removes a child from a directory and free (unref) it. 02420 * If you want to keep the child alive, you need to iso_node_ref() it 02421 * before this call, but in that case iso_node_take() is a better 02422 * alternative. 02423 * 02424 * @return 02425 * 1 on success, < 0 error 02426 * 02427 * @since 0.6.2 02428 */ 02429 int iso_node_remove(IsoNode *node); 02430 02431 /* 02432 * Get the parent of the given iso tree node. No extra ref is added to the 02433 * returned directory, you must take your ref. with iso_node_ref() if you 02434 * need it. 02435 * 02436 * If node is the root node, the same node will be returned as its parent. 02437 * 02438 * This returns NULL if the node doesn't pertain to any tree 02439 * (it was removed/take). 02440 * 02441 * @since 0.6.2 02442 */ 02443 IsoDir *iso_node_get_parent(IsoNode *node); 02444 02445 /** 02446 * Get an iterator for the children of the given dir. 02447 * 02448 * You can iterate over the children with iso_dir_iter_next. When finished, 02449 * you should free the iterator with iso_dir_iter_free. 02450 * You musn't delete a child of the same dir, using iso_node_take() or 02451 * iso_node_remove(), while you're using the iterator. You can use 02452 * iso_dir_iter_take() or iso_dir_iter_remove() instead. 02453 * 02454 * You can use the iterator in the way like this 02455 * 02456 * IsoDirIter *iter; 02457 * IsoNode *node; 02458 * if ( iso_dir_get_children(dir, &iter) != 1 ) { 02459 * // handle error 02460 * } 02461 * while ( iso_dir_iter_next(iter, &node) == 1 ) { 02462 * // do something with the child 02463 * } 02464 * iso_dir_iter_free(iter); 02465 * 02466 * An iterator is intended to be used in a single iteration over the 02467 * children of a dir. Thus, it should be treated as a temporary object, 02468 * and free as soon as possible. 02469 * 02470 * @return 02471 * 1 success, < 0 error 02472 * Possible errors: 02473 * ISO_NULL_POINTER, if dir or iter are NULL 02474 * ISO_OUT_OF_MEM 02475 * 02476 * @since 0.6.2 02477 */ 02478 int iso_dir_get_children(const IsoDir *dir, IsoDirIter **iter); 02479 02480 /** 02481 * Get the next child. 02482 * Take care that the node is owned by its parent, and will be unref() when 02483 * the parent is freed. If you want your own ref to it, call iso_node_ref() 02484 * on it. 02485 * 02486 * @return 02487 * 1 success, 0 if dir has no more elements, < 0 error 02488 * Possible errors: 02489 * ISO_NULL_POINTER, if node or iter are NULL 02490 * ISO_ERROR, on wrong iter usage, usual caused by modiying the 02491 * dir during iteration 02492 * 02493 * @since 0.6.2 02494 */ 02495 int iso_dir_iter_next(IsoDirIter *iter, IsoNode **node); 02496 02497 /** 02498 * Check if there're more children. 02499 * 02500 * @return 02501 * 1 dir has more elements, 0 no, < 0 error 02502 * Possible errors: 02503 * ISO_NULL_POINTER, if iter is NULL 02504 * 02505 * @since 0.6.2 02506 */ 02507 int iso_dir_iter_has_next(IsoDirIter *iter); 02508 02509 /** 02510 * Free a dir iterator. 02511 * 02512 * @since 0.6.2 02513 */ 02514 void iso_dir_iter_free(IsoDirIter *iter); 02515 02516 /** 02517 * Removes a child from a directory during an iteration, without freeing it. 02518 * It's like iso_node_take(), but to be used during a directory iteration. 02519 * The node removed will be the last returned by the iteration. 02520 * 02521 * If you call this function twice without calling iso_dir_iter_next between 02522 * them is not allowed and you will get an ISO_ERROR in second call. 02523 * 02524 * @return 02525 * 1 on succes, < 0 error 02526 * Possible errors: 02527 * ISO_NULL_POINTER, if iter is NULL 02528 * ISO_ERROR, on wrong iter usage, for example by call this before 02529 * iso_dir_iter_next. 02530 * 02531 * @since 0.6.2 02532 */ 02533 int iso_dir_iter_take(IsoDirIter *iter); 02534 02535 /** 02536 * Removes a child from a directory during an iteration and unref() it. 02537 * It's like iso_node_remove(), but to be used during a directory iteration. 02538 * The node removed will be the last returned by the iteration. 02539 * 02540 * If you call this function twice without calling iso_dir_iter_next between 02541 * them is not allowed and you will get an ISO_ERROR in second call. 02542 * 02543 * @return 02544 * 1 on succes, < 0 error 02545 * Possible errors: 02546 * ISO_NULL_POINTER, if iter is NULL 02547 * ISO_ERROR, on wrong iter usage, for example by call this before 02548 * iso_dir_iter_next. 02549 * 02550 * @since 0.6.2 02551 */ 02552 int iso_dir_iter_remove(IsoDirIter *iter); 02553 02554 02555 /** 02556 * @since 0.6.4 02557 */ 02558 typedef struct iso_find_condition IsoFindCondition; 02559 02560 /** 02561 * Create a new condition that checks if the node name matches the given 02562 * wildcard. 02563 * 02564 * @param wildcard 02565 * @result 02566 * The created IsoFindCondition, NULL on error. 02567 * 02568 * @since 0.6.4 02569 */ 02570 IsoFindCondition *iso_new_find_conditions_name(const char *wildcard); 02571 02572 /** 02573 * Create a new condition that checks the node mode against a mode mask. It 02574 * can be used to check both file type and permissions. 02575 * 02576 * For example: 02577 * 02578 * iso_new_find_conditions_mode(S_IFREG) : search for regular files 02579 * iso_new_find_conditions_mode(S_IFCHR | S_IWUSR) : search for character 02580 * devices where owner has write permissions. 02581 * 02582 * @param mask 02583 * Mode mask to AND against node mode. 02584 * @result 02585 * The created IsoFindCondition, NULL on error. 02586 * 02587 * @since 0.6.4 02588 */ 02589 IsoFindCondition *iso_new_find_conditions_mode(mode_t mask); 02590 02591 /** 02592 * Create a new condition that checks the node gid. 02593 * 02594 * @param gid 02595 * Desired Group Id. 02596 * @result 02597 * The created IsoFindCondition, NULL on error. 02598 * 02599 * @since 0.6.4 02600 */ 02601 IsoFindCondition *iso_new_find_conditions_gid(gid_t gid); 02602 02603 /** 02604 * Create a new condition that checks the node uid. 02605 * 02606 * @param uid 02607 * Desired User Id. 02608 * @result 02609 * The created IsoFindCondition, NULL on error. 02610 * 02611 * @since 0.6.4 02612 */ 02613 IsoFindCondition *iso_new_find_conditions_uid(uid_t uid); 02614 02615 /** 02616 * Possible comparison between IsoNode and given conditions. 02617 * 02618 * @since 0.6.4 02619 */ 02620 enum iso_find_comparisons { 02621 ISO_FIND_COND_GREATER, 02622 ISO_FIND_COND_GREATER_OR_EQUAL, 02623 ISO_FIND_COND_EQUAL, 02624 ISO_FIND_COND_LESS, 02625 ISO_FIND_COND_LESS_OR_EQUAL 02626 }; 02627 02628 /** 02629 * Create a new condition that checks the time of last access. 02630 * 02631 * @param time 02632 * Time to compare against IsoNode atime. 02633 * @param comparison 02634 * Comparison to be done between IsoNode atime and submitted time. 02635 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02636 * time is greater than the submitted time. 02637 * @result 02638 * The created IsoFindCondition, NULL on error. 02639 * 02640 * @since 0.6.4 02641 */ 02642 IsoFindCondition *iso_new_find_conditions_atime(time_t time, 02643 enum iso_find_comparisons comparison); 02644 02645 /** 02646 * Create a new condition that checks the time of last modification. 02647 * 02648 * @param time 02649 * Time to compare against IsoNode mtime. 02650 * @param comparison 02651 * Comparison to be done between IsoNode mtime and submitted time. 02652 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02653 * time is greater than the submitted time. 02654 * @result 02655 * The created IsoFindCondition, NULL on error. 02656 * 02657 * @since 0.6.4 02658 */ 02659 IsoFindCondition *iso_new_find_conditions_mtime(time_t time, 02660 enum iso_find_comparisons comparison); 02661 02662 /** 02663 * Create a new condition that checks the time of last status change. 02664 * 02665 * @param time 02666 * Time to compare against IsoNode ctime. 02667 * @param comparison 02668 * Comparison to be done between IsoNode ctime and submitted time. 02669 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02670 * time is greater than the submitted time. 02671 * @result 02672 * The created IsoFindCondition, NULL on error. 02673 * 02674 * @since 0.6.4 02675 */ 02676 IsoFindCondition *iso_new_find_conditions_ctime(time_t time, 02677 enum iso_find_comparisons comparison); 02678 02679 /** 02680 * Create a new condition that check if the two given conditions are 02681 * valid. 02682 * 02683 * @param a 02684 * @param b 02685 * IsoFindCondition to compare 02686 * @result 02687 * The created IsoFindCondition, NULL on error. 02688 * 02689 * @since 0.6.4 02690 */ 02691 IsoFindCondition *iso_new_find_conditions_and(IsoFindCondition *a, 02692 IsoFindCondition *b); 02693 02694 /** 02695 * Create a new condition that check if at least one the two given conditions 02696 * is valid. 02697 * 02698 * @param a 02699 * @param b 02700 * IsoFindCondition to compare 02701 * @result 02702 * The created IsoFindCondition, NULL on error. 02703 * 02704 * @since 0.6.4 02705 */ 02706 IsoFindCondition *iso_new_find_conditions_or(IsoFindCondition *a, 02707 IsoFindCondition *b); 02708 02709 /** 02710 * Create a new condition that check if the given conditions is false. 02711 * 02712 * @param negate 02713 * @result 02714 * The created IsoFindCondition, NULL on error. 02715 * 02716 * @since 0.6.4 02717 */ 02718 IsoFindCondition *iso_new_find_conditions_not(IsoFindCondition *negate); 02719 02720 /** 02721 * Find all directory children that match the given condition. 02722 * 02723 * @param dir 02724 * Directory where we will search children. 02725 * @param cond 02726 * Condition that the children must match in order to be returned. 02727 * It will be free together with the iterator. Remember to delete it 02728 * if this function return error. 02729 * @param iter 02730 * Iterator that returns only the children that match condition. 02731 * @return 02732 * 1 on success, < 0 on error 02733 * 02734 * @since 0.6.4 02735 */ 02736 int iso_dir_find_children(IsoDir* dir, IsoFindCondition *cond, 02737 IsoDirIter **iter); 02738 02739 /** 02740 * Get the destination of a node. 02741 * The returned string belongs to the node and should not be modified nor 02742 * freed. Use strdup if you really need your own copy. 02743 * 02744 * @since 0.6.2 02745 */ 02746 const char *iso_symlink_get_dest(const IsoSymlink *link); 02747 02748 /** 02749 * Set the destination of a link. 02750 * 02751 * @param dest 02752 * New destination for the link. It must be a non-empty string, otherwise 02753 * this function doesn't modify previous destination. 02754 * @return 02755 * 1 on success, < 0 on error 02756 * 02757 * @since 0.6.2 02758 */ 02759 int iso_symlink_set_dest(IsoSymlink *link, const char *dest); 02760 02761 /** 02762 * Sets the order in which a node will be written on image. High weihted files 02763 * will be written first, so in a disc them will be written near the center. 02764 * 02765 * @param node 02766 * The node which weight will be changed. If it's a dir, this function 02767 * will change the weight of all its children. For nodes other that dirs 02768 * or regular files, this function has no effect. 02769 * @param w 02770 * The weight as a integer number, the greater this value is, the 02771 * closer from the begining of image the file will be written. 02772 * 02773 * @since 0.6.2 02774 */ 02775 void iso_node_set_sort_weight(IsoNode *node, int w); 02776 02777 /** 02778 * Get the sort weight of a file. 02779 * 02780 * @since 0.6.2 02781 */ 02782 int iso_file_get_sort_weight(IsoFile *file); 02783 02784 /** 02785 * Get the size of the file, in bytes 02786 * 02787 * @since 0.6.2 02788 */ 02789 off_t iso_file_get_size(IsoFile *file); 02790 02791 /** 02792 * Get the device id (major/minor numbers) of the given block or 02793 * character device file. The result is undefined for other kind 02794 * of special files, of first be sure iso_node_get_mode() returns either 02795 * S_IFBLK or S_IFCHR. 02796 * 02797 * @since 0.6.6 02798 */ 02799 dev_t iso_special_get_dev(IsoSpecial *special); 02800 02801 /** 02802 * Get the IsoStream that represents the contents of the given IsoFile. 02803 * 02804 * If you open() the stream, it should be close() before image generation. 02805 * 02806 * @return 02807 * The IsoStream. No extra ref is added, so the IsoStream belong to the 02808 * IsoFile, and it may be freed together with it. Add your own ref with 02809 * iso_stream_ref() if you need it. 02810 * 02811 * @since 0.6.4 02812 */ 02813 IsoStream *iso_file_get_stream(IsoFile *file); 02814 02815 /** 02816 * Get the block lba of a file node, if it was imported from an old image. 02817 * 02818 * @param file 02819 * The file 02820 * @param lba 02821 * Will be filled with the kba 02822 * @param flag 02823 * Reserved for future usage, submit 0 02824 * @return 02825 * 1 if lba is valid (file comes from old image), 0 if file was newly 02826 * added, i.e. it does not come from an old image, < 0 error 02827 * 02828 * @since 0.6.4 02829 * 02830 * @deprecated Use iso_file_get_old_image_sections(), as this function does 02831 * not work with multi-extend files. 02832 */ 02833 int iso_file_get_old_image_lba(IsoFile *file, uint32_t *lba, int flag); 02834 02835 /** 02836 * Get the start addresses and the sizes of the data extents of a file node 02837 * if it was imported from an old image. 02838 * 02839 * @param file 02840 * The file 02841 * @param section_count 02842 * Returns the number of extent entries in sections array. 02843 * @param sections 02844 * Returns the array of file sections. Apply free() to dispose it. 02845 * @param flag 02846 * Reserved for future usage, submit 0 02847 * @return 02848 * 1 if there are valid extents (file comes from old image), 02849 * 0 if file was newly added, i.e. it does not come from an old image, 02850 * < 0 error 02851 * 02852 * @since 0.6.8 02853 */ 02854 int iso_file_get_old_image_sections(IsoFile *file, int *section_count, 02855 struct iso_file_section **sections, 02856 int flag); 02857 02858 /* 02859 * Like iso_file_get_old_image_lba(), but take an IsoNode. 02860 * 02861 * @return 02862 * 1 if lba is valid (file comes from old image), 0 if file was newly 02863 * added, i.e. it does not come from an old image, 2 node type has no 02864 * LBA (no regular file), < 0 error 02865 * 02866 * @since 0.6.4 02867 */ 02868 int iso_node_get_old_image_lba(IsoNode *node, uint32_t *lba, int flag); 02869 02870 /** 02871 * Add a new directory to the iso tree. Permissions, owner and hidden atts 02872 * are taken from parent, you can modify them later. 02873 * 02874 * @param parent 02875 * the dir where the new directory will be created 02876 * @param name 02877 * name for the new dir. If a node with same name already exists on 02878 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02879 * @param dir 02880 * place where to store a pointer to the newly created dir. No extra 02881 * ref is addded, so you will need to call iso_node_ref() if you really 02882 * need it. You can pass NULL in this parameter if you don't need the 02883 * pointer. 02884 * @return 02885 * number of nodes in parent if success, < 0 otherwise 02886 * Possible errors: 02887 * ISO_NULL_POINTER, if parent or name are NULL 02888 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02889 * ISO_OUT_OF_MEM 02890 * 02891 * @since 0.6.2 02892 */ 02893 int iso_tree_add_new_dir(IsoDir *parent, const char *name, IsoDir **dir); 02894 02895 /** 02896 * Add a new regular file to the iso tree. Permissions are set to 0444, 02897 * owner and hidden atts are taken from parent. You can modify any of them 02898 * later. 02899 * 02900 * @param parent 02901 * the dir where the new file will be created 02902 * @param name 02903 * name for the new file. If a node with same name already exists on 02904 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02905 * @param stream 02906 * IsoStream for the contents of the file. The reference will be taken 02907 * by the newly created file, you will need to take an extra ref to it 02908 * if you need it. 02909 * @param file 02910 * place where to store a pointer to the newly created file. No extra 02911 * ref is addded, so you will need to call iso_node_ref() if you really 02912 * need it. You can pass NULL in this parameter if you don't need the 02913 * pointer 02914 * @return 02915 * number of nodes in parent if success, < 0 otherwise 02916 * Possible errors: 02917 * ISO_NULL_POINTER, if parent, name or dest are NULL 02918 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02919 * ISO_OUT_OF_MEM 02920 * 02921 * @since 0.6.4 02922 */ 02923 int iso_tree_add_new_file(IsoDir *parent, const char *name, IsoStream *stream, 02924 IsoFile **file); 02925 02926 /** 02927 * Add a new symlink to the directory tree. Permissions are set to 0777, 02928 * owner and hidden atts are taken from parent. You can modify any of them 02929 * later. 02930 * 02931 * @param parent 02932 * the dir where the new symlink will be created 02933 * @param name 02934 * name for the new symlink. If a node with same name already exists on 02935 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02936 * @param dest 02937 * destination of the link 02938 * @param link 02939 * place where to store a pointer to the newly created link. No extra 02940 * ref is addded, so you will need to call iso_node_ref() if you really 02941 * need it. You can pass NULL in this parameter if you don't need the 02942 * pointer 02943 * @return 02944 * number of nodes in parent if success, < 0 otherwise 02945 * Possible errors: 02946 * ISO_NULL_POINTER, if parent, name or dest are NULL 02947 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02948 * ISO_OUT_OF_MEM 02949 * 02950 * @since 0.6.2 02951 */ 02952 int iso_tree_add_new_symlink(IsoDir *parent, const char *name, 02953 const char *dest, IsoSymlink **link); 02954 02955 /** 02956 * Add a new special file to the directory tree. As far as libisofs concerns, 02957 * an special file is a block device, a character device, a FIFO (named pipe) 02958 * or a socket. You can choose the specific kind of file you want to add 02959 * by setting mode propertly (see man 2 stat). 02960 * 02961 * Note that special files are only written to image when Rock Ridge 02962 * extensions are enabled. Moreover, a special file is just a directory entry 02963 * in the image tree, no data is written beyond that. 02964 * 02965 * Owner and hidden atts are taken from parent. You can modify any of them 02966 * later. 02967 * 02968 * @param parent 02969 * the dir where the new special file will be created 02970 * @param name 02971 * name for the new special file. If a node with same name already exists 02972 * on parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02973 * @param mode 02974 * file type and permissions for the new node. Note that you can't 02975 * specify any kind of file here, only special types are allowed. i.e, 02976 * S_IFSOCK, S_IFBLK, S_IFCHR and S_IFIFO are valid types; S_IFLNK, 02977 * S_IFREG and S_IFDIR aren't. 02978 * @param dev 02979 * device ID, equivalent to the st_rdev field in man 2 stat. 02980 * @param special 02981 * place where to store a pointer to the newly created special file. No 02982 * extra ref is addded, so you will need to call iso_node_ref() if you 02983 * really need it. You can pass NULL in this parameter if you don't need 02984 * the pointer. 02985 * @return 02986 * number of nodes in parent if success, < 0 otherwise 02987 * Possible errors: 02988 * ISO_NULL_POINTER, if parent, name or dest are NULL 02989 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02990 * ISO_WRONG_ARG_VALUE if you select a incorrect mode 02991 * ISO_OUT_OF_MEM 02992 * 02993 * @since 0.6.2 02994 */ 02995 int iso_tree_add_new_special(IsoDir *parent, const char *name, mode_t mode, 02996 dev_t dev, IsoSpecial **special); 02997 02998 /** 02999 * Set whether to follow or not symbolic links when added a file from a source 03000 * to IsoImage. Default behavior is to not follow symlinks. 03001 * 03002 * @since 0.6.2 03003 */ 03004 void iso_tree_set_follow_symlinks(IsoImage *image, int follow); 03005 03006 /** 03007 * Get current setting for follow_symlinks. 03008 * 03009 * @see iso_tree_set_follow_symlinks 03010 * @since 0.6.2 03011 */ 03012 int iso_tree_get_follow_symlinks(IsoImage *image); 03013 03014 /** 03015 * Set whether to skip or not hidden files when adding a directory recursibely. 03016 * Default behavior is to not ignore them, i.e., to add hidden files to image. 03017 * 03018 * @since 0.6.2 03019 */ 03020 void iso_tree_set_ignore_hidden(IsoImage *image, int skip); 03021 03022 /** 03023 * Get current setting for ignore_hidden. 03024 * 03025 * @see iso_tree_set_ignore_hidden 03026 * @since 0.6.2 03027 */ 03028 int iso_tree_get_ignore_hidden(IsoImage *image); 03029 03030 /** 03031 * Set the replace mode, that defines the behavior of libisofs when adding 03032 * a node whit the same name that an existent one, during a recursive 03033 * directory addition. 03034 * 03035 * @since 0.6.2 03036 */ 03037 void iso_tree_set_replace_mode(IsoImage *image, enum iso_replace_mode mode); 03038 03039 /** 03040 * Get current setting for replace_mode. 03041 * 03042 * @see iso_tree_set_replace_mode 03043 * @since 0.6.2 03044 */ 03045 enum iso_replace_mode iso_tree_get_replace_mode(IsoImage *image); 03046 03047 /** 03048 * Set whether to skip or not special files. Default behavior is to not skip 03049 * them. Note that, despite of this setting, special files won't never be added 03050 * to an image unless RR extensions were enabled. 03051 * 03052 * @param skip 03053 * Bitmask to determine what kind of special files will be skipped: 03054 * bit0: ignore FIFOs 03055 * bit1: ignore Sockets 03056 * bit2: ignore char devices 03057 * bit3: ignore block devices 03058 * 03059 * @since 0.6.2 03060 */ 03061 void iso_tree_set_ignore_special(IsoImage *image, int skip); 03062 03063 /** 03064 * Get current setting for ignore_special. 03065 * 03066 * @see iso_tree_set_ignore_special 03067 * @since 0.6.2 03068 */ 03069 int iso_tree_get_ignore_special(IsoImage *image); 03070 03071 /** 03072 * Add a excluded path. These are paths that won't never added to image, 03073 * and will be excluded even when adding recursively its parent directory. 03074 * 03075 * For example, in 03076 * 03077 * iso_tree_add_exclude(image, "/home/user/data/private"); 03078 * iso_tree_add_dir_rec(image, root, "/home/user/data"); 03079 * 03080 * the directory /home/user/data/private won't be added to image. 03081 * 03082 * However, if you explicity add a deeper dir, it won't be excluded. i.e., 03083 * in the following example. 03084 * 03085 * iso_tree_add_exclude(image, "/home/user/data"); 03086 * iso_tree_add_dir_rec(image, root, "/home/user/data/private"); 03087 * 03088 * the directory /home/user/data/private is added. On the other, side, and 03089 * foollowing the the example above, 03090 * 03091 * iso_tree_add_dir_rec(image, root, "/home/user"); 03092 * 03093 * will exclude the directory "/home/user/data". 03094 * 03095 * Absolute paths are not mandatory, you can, for example, add a relative 03096 * path such as: 03097 * 03098 * iso_tree_add_exclude(image, "private"); 03099 * iso_tree_add_exclude(image, "user/data"); 03100 * 03101 * to excluve, respectively, all files or dirs named private, and also all 03102 * files or dirs named data that belong to a folder named "user". Not that the 03103 * above rule about deeper dirs is still valid. i.e., if you call 03104 * 03105 * iso_tree_add_dir_rec(image, root, "/home/user/data/music"); 03106 * 03107 * it is included even containing "user/data" string. However, a possible 03108 * "/home/user/data/music/user/data" is not added. 03109 * 03110 * Usual wildcards, such as * or ? are also supported, with the usual meaning 03111 * as stated in "man 7 glob". For example 03112 * 03113 * // to exclude backup text files 03114 * iso_tree_add_exclude(image, "*.~"); 03115 * 03116 * @return 03117 * 1 on success, < 0 on error 03118 * 03119 * @since 0.6.2 03120 */ 03121 int iso_tree_add_exclude(IsoImage *image, const char *path); 03122 03123 /** 03124 * Remove a previously added exclude. 03125 * 03126 * @see iso_tree_add_exclude 03127 * @return 03128 * 1 on success, 0 exclude do not exists, < 0 on error 03129 * 03130 * @since 0.6.2 03131 */ 03132 int iso_tree_remove_exclude(IsoImage *image, const char *path); 03133 03134 /** 03135 * Set a callback function that libisofs will call for each file that is 03136 * added to the given image by a recursive addition function. This includes 03137 * image import. 03138 * 03139 * @param report 03140 * pointer to a function that will be called just before a file will be 03141 * added to the image. You can control whether the file will be in fact 03142 * added or ignored. 03143 * This function should return 1 to add the file, 0 to ignore it and 03144 * continue, < 0 to abort the process 03145 * NULL is allowed if you don't want any callback. 03146 * 03147 * @since 0.6.2 03148 */ 03149 void iso_tree_set_report_callback(IsoImage *image, 03150 int (*report)(IsoImage*, IsoFileSource*)); 03151 03152 /** 03153 * Add a new node to the image tree, from an existing file. 03154 * 03155 * TODO comment Builder and Filesystem related issues when exposing both 03156 * 03157 * All attributes will be taken from the source file. The appropriate file 03158 * type will be created. 03159 * 03160 * @param image 03161 * The image 03162 * @param parent 03163 * The directory in the image tree where the node will be added. 03164 * @param path 03165 * The path of the file to add in the filesystem. 03166 * @param node 03167 * place where to store a pointer to the newly added file. No 03168 * extra ref is addded, so you will need to call iso_node_ref() if you 03169 * really need it. You can pass NULL in this parameter if you don't need 03170 * the pointer. 03171 * @return 03172 * number of nodes in parent if success, < 0 otherwise 03173 * Possible errors: 03174 * ISO_NULL_POINTER, if image, parent or path are NULL 03175 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03176 * ISO_OUT_OF_MEM 03177 * 03178 * @since 0.6.2 03179 */ 03180 int iso_tree_add_node(IsoImage *image, IsoDir *parent, const char *path, 03181 IsoNode **node); 03182 03183 /** 03184 * This is a more versatile form of iso_tree_add_node which allows to set 03185 * the node name in ISO image already when it gets added. 03186 * 03187 * Add a new node to the image tree, from an existing file, and with the 03188 * given name, that must not exist on dir. 03189 * 03190 * @param image 03191 * The image 03192 * @param parent 03193 * The directory in the image tree where the node will be added. 03194 * @param name 03195 * The name that the node will have on image. 03196 * @param path 03197 * The path of the file to add in the filesystem. 03198 * @param node 03199 * place where to store a pointer to the newly added file. No 03200 * extra ref is addded, so you will need to call iso_node_ref() if you 03201 * really need it. You can pass NULL in this parameter if you don't need 03202 * the pointer. 03203 * @return 03204 * number of nodes in parent if success, < 0 otherwise 03205 * Possible errors: 03206 * ISO_NULL_POINTER, if image, parent or path are NULL 03207 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03208 * ISO_OUT_OF_MEM 03209 * 03210 * @since 0.6.4 03211 */ 03212 int iso_tree_add_new_node(IsoImage *image, IsoDir *parent, const char *name, 03213 const char *path, IsoNode **node); 03214 03215 /** 03216 * Add a new node to the image tree, from an existing file, and with the 03217 * given name, that must not exist on dir. The node will be cut-out to the 03218 * submitted size, and its contents will be read from the given offset. This 03219 * function is thus suitable for adding only a piece of a file to the image. 03220 * 03221 * @param image 03222 * The image 03223 * @param parent 03224 * The directory in the image tree where the node will be added. 03225 * @param name 03226 * The name that the node will have on image. 03227 * @param path 03228 * The path of the file to add in the filesystem. For now only regular 03229 * files and symlinks to regular files are supported. 03230 * @param offset 03231 * Offset on the given file from where to start reading data. 03232 * @param size 03233 * Max size of the file. 03234 * @param node 03235 * place where to store a pointer to the newly added file. No 03236 * extra ref is addded, so you will need to call iso_node_ref() if you 03237 * really need it. You can pass NULL in this parameter if you don't need 03238 * the pointer. 03239 * @return 03240 * number of nodes in parent if success, < 0 otherwise 03241 * Possible errors: 03242 * ISO_NULL_POINTER, if image, parent or path are NULL 03243 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 03244 * ISO_OUT_OF_MEM 03245 * 03246 * @since 0.6.4 03247 */ 03248 int iso_tree_add_new_cut_out_node(IsoImage *image, IsoDir *parent, 03249 const char *name, const char *path, 03250 off_t offset, off_t size, 03251 IsoNode **node); 03252 03253 /** 03254 * Add the contents of a dir to a given directory of the iso tree. 03255 * 03256 * There are several options to control what files are added or how they are 03257 * managed. Take a look at iso_tree_set_* functions to see diferent options 03258 * for recursive directory addition. 03259 * 03260 * TODO comment Builder and Filesystem related issues when exposing both 03261 * 03262 * @param image 03263 * The image to which the directory belong. 03264 * @param parent 03265 * Directory on the image tree where to add the contents of the dir 03266 * @param dir 03267 * Path to a dir in the filesystem 03268 * @return 03269 * number of nodes in parent if success, < 0 otherwise 03270 * 03271 * @since 0.6.2 03272 */ 03273 int iso_tree_add_dir_rec(IsoImage *image, IsoDir *parent, const char *dir); 03274 03275 /** 03276 * Locate a node by its path on image. 03277 * 03278 * @param node 03279 * Location for a pointer to the node, it will filled with NULL if the 03280 * given path does not exists on image. 03281 * The node will be owned by the image and shouldn't be unref(). Just call 03282 * iso_node_ref() to get your own reference to the node. 03283 * Note that you can pass NULL is the only thing you want to do is check 03284 * if a node with such path really exists. 03285 * @return 03286 * 1 found, 0 not found, < 0 error 03287 * 03288 * @since 0.6.2 03289 */ 03290 int iso_tree_path_to_node(IsoImage *image, const char *path, IsoNode **node); 03291 03292 /** 03293 * Get the path on image of the given node. 03294 * 03295 * @return 03296 * The path on the image, that must be freed when no more needed. If the 03297 * given node is not added to any image, this returns NULL. 03298 * @since 0.6.4 03299 */ 03300 char *iso_tree_get_node_path(IsoNode *node); 03301 03302 /** 03303 * Increments the reference counting of the given IsoDataSource. 03304 * 03305 * @since 0.6.2 03306 */ 03307 void iso_data_source_ref(IsoDataSource *src); 03308 03309 /** 03310 * Decrements the reference counting of the given IsoDataSource, freeing it 03311 * if refcount reach 0. 03312 * 03313 * @since 0.6.2 03314 */ 03315 void iso_data_source_unref(IsoDataSource *src); 03316 03317 /** 03318 * Create a new IsoDataSource from a local file. This is suitable for 03319 * accessing regular .iso images, or to acces drives via its block device 03320 * and standard POSIX I/O calls. 03321 * 03322 * @param path 03323 * The path of the file 03324 * @param src 03325 * Will be filled with the pointer to the newly created data source. 03326 * @return 03327 * 1 on success, < 0 on error. 03328 * 03329 * @since 0.6.2 03330 */ 03331 int iso_data_source_new_from_file(const char *path, IsoDataSource **src); 03332 03333 /** 03334 * Get the status of the buffer used by a burn_source. 03335 * 03336 * @param b 03337 * A burn_source previously obtained with 03338 * iso_image_create_burn_source(). 03339 * @param size 03340 * Will be filled with the total size of the buffer, in bytes 03341 * @param free_bytes 03342 * Will be filled with the bytes currently available in buffer 03343 * @return 03344 * < 0 error, > 0 state: 03345 * 1="active" : input and consumption are active 03346 * 2="ending" : input has ended without error 03347 * 3="failing" : input had error and ended, 03348 * 5="abandoned" : consumption has ended prematurely 03349 * 6="ended" : consumption has ended without input error 03350 * 7="aborted" : consumption has ended after input error 03351 * 03352 * @since 0.6.2 03353 */ 03354 int iso_ring_buffer_get_status(struct burn_source *b, size_t *size, 03355 size_t *free_bytes); 03356 03357 #define ISO_MSGS_MESSAGE_LEN 4096 03358 03359 /** 03360 * Control queueing and stderr printing of messages from libisofs. 03361 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 03362 * "NOTE", "UPDATE", "DEBUG", "ALL". 03363 * 03364 * @param queue_severity Gives the minimum limit for messages to be queued. 03365 * Default: "NEVER". If you queue messages then you 03366 * must consume them by iso_msgs_obtain(). 03367 * @param print_severity Does the same for messages to be printed directly 03368 * to stderr. 03369 * @param print_id A text prefix to be printed before the message. 03370 * @return >0 for success, <=0 for error 03371 * 03372 * @since 0.6.2 03373 */ 03374 int iso_set_msgs_severities(char *queue_severity, char *print_severity, 03375 char *print_id); 03376 03377 /** 03378 * Obtain the oldest pending libisofs message from the queue which has at 03379 * least the given minimum_severity. This message and any older message of 03380 * lower severity will get discarded from the queue and is then lost forever. 03381 * 03382 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 03383 * "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER" 03384 * will discard the whole queue. 03385 * 03386 * @param error_code 03387 * Will become a unique error code as listed at the end of this header 03388 * @param imgid 03389 * Id of the image that was issued the message. 03390 * @param msg_text 03391 * Must provide at least ISO_MSGS_MESSAGE_LEN bytes. 03392 * @param severity 03393 * Will become the severity related to the message and should provide at 03394 * least 80 bytes. 03395 * @return 03396 * 1 if a matching item was found, 0 if not, <0 for severe errors 03397 * 03398 * @since 0.6.2 03399 */ 03400 int iso_obtain_msgs(char *minimum_severity, int *error_code, int *imgid, 03401 char msg_text[], char severity[]); 03402 03403 03404 /** 03405 * Submit a message to the libisofs queueing system. It will be queued or 03406 * printed as if it was generated by libisofs itself. 03407 * 03408 * @param error_code 03409 * The unique error code of your message. 03410 * Submit 0 if you do not have reserved error codes within the libburnia 03411 * project. 03412 * @param msg_text 03413 * Not more than ISO_MSGS_MESSAGE_LEN characters of message text. 03414 * @param os_errno 03415 * Eventual errno related to the message. Submit 0 if the message is not 03416 * related to a operating system error. 03417 * @param severity 03418 * One of "ABORT", "FATAL", "FAILURE", "SORRY", "WARNING", "HINT", "NOTE", 03419 * "UPDATE", "DEBUG". Defaults to "FATAL". 03420 * @param origin 03421 * Submit 0 for now. 03422 * @return 03423 * 1 if message was delivered, <=0 if failure 03424 * 03425 * @since 0.6.4 03426 */ 03427 int iso_msgs_submit(int error_code, char msg_text[], int os_errno, 03428 char severity[], int origin); 03429 03430 03431 /** 03432 * Convert a severity name into a severity number, which gives the severity 03433 * rank of the name. 03434 * 03435 * @param severity_name 03436 * A name as with iso_msgs_submit(), e.g. "SORRY". 03437 * @param severity_number 03438 * The rank number: the higher, the more severe. 03439 * @return 03440 * >0 success, <=0 failure 03441 * 03442 * @since 0.6.4 03443 */ 03444 int iso_text_to_sev(char *severity_name, int *severity_number); 03445 03446 03447 /** 03448 * Convert a severity number into a severity name 03449 * 03450 * @param severity_number 03451 * The rank number: the higher, the more severe. 03452 * @param severity_name 03453 * A name as with iso_msgs_submit(), e.g. "SORRY". 03454 * 03455 * @since 0.6.4 03456 */ 03457 int iso_sev_to_text(int severity_number, char **severity_name); 03458 03459 03460 /** 03461 * Get the id of an IsoImage, used for message reporting. This message id, 03462 * retrieved with iso_obtain_msgs(), can be used to distinguish what 03463 * IsoImage has isssued a given message. 03464 * 03465 * @since 0.6.2 03466 */ 03467 int iso_image_get_msg_id(IsoImage *image); 03468 03469 /** 03470 * Get a textual description of a libisofs error. 03471 * 03472 * @since 0.6.2 03473 */ 03474 const char *iso_error_to_msg(int errcode); 03475 03476 /** 03477 * Get the severity of a given error code 03478 * @return 03479 * 0x10000000 -> DEBUG 03480 * 0x20000000 -> UPDATE 03481 * 0x30000000 -> NOTE 03482 * 0x40000000 -> HINT 03483 * 0x50000000 -> WARNING 03484 * 0x60000000 -> SORRY 03485 * 0x64000000 -> MISHAP 03486 * 0x68000000 -> FAILURE 03487 * 0x70000000 -> FATAL 03488 * 0x71000000 -> ABORT 03489 * 03490 * @since 0.6.2 03491 */ 03492 int iso_error_get_severity(int e); 03493 03494 /** 03495 * Get the priority of a given error. 03496 * @return 03497 * 0x00000000 -> ZERO 03498 * 0x10000000 -> LOW 03499 * 0x20000000 -> MEDIUM 03500 * 0x30000000 -> HIGH 03501 * 03502 * @since 0.6.2 03503 */ 03504 int iso_error_get_priority(int e); 03505 03506 /** 03507 * Get the message queue code of a libisofs error. 03508 */ 03509 int iso_error_get_code(int e); 03510 03511 /** 03512 * Set the minimum error severity that causes a libisofs operation to 03513 * be aborted as soon as possible. 03514 * 03515 * @param severity 03516 * one of "FAILURE", "MISHAP", "SORRY", "WARNING", "HINT", "NOTE". 03517 * Severities greater or equal than FAILURE always cause program to abort. 03518 * Severities under NOTE won't never cause function abort. 03519 * @return 03520 * Previous abort priority on success, < 0 on error. 03521 * 03522 * @since 0.6.2 03523 */ 03524 int iso_set_abort_severity(char *severity); 03525 03526 /** 03527 * Return the messenger object handle used by libisofs. This handle 03528 * may be used by related libraries to their own compatible 03529 * messenger objects and thus to direct their messages to the libisofs 03530 * message queue. See also: libburn, API function burn_set_messenger(). 03531 * 03532 * @return the handle. Do only use with compatible 03533 * 03534 * @since 0.6.2 03535 */ 03536 void *iso_get_messenger(); 03537 03538 /** 03539 * Take a ref to the given IsoFileSource. 03540 * 03541 * @since 0.6.2 03542 */ 03543 void iso_file_source_ref(IsoFileSource *src); 03544 03545 /** 03546 * Drop your ref to the given IsoFileSource, eventually freeing the associated 03547 * system resources. 03548 * 03549 * @since 0.6.2 03550 */ 03551 void iso_file_source_unref(IsoFileSource *src); 03552 03553 /* 03554 * this are just helpers to invoque methods in class 03555 */ 03556 03557 /** 03558 * Get the path, relative to the filesystem this file source 03559 * belongs to. 03560 * 03561 * @return 03562 * the path of the FileSource inside the filesystem, it should be 03563 * freed when no more needed. 03564 * 03565 * @since 0.6.2 03566 */ 03567 char* iso_file_source_get_path(IsoFileSource *src); 03568 03569 /** 03570 * Get the name of the file, with the dir component of the path. 03571 * 03572 * @return 03573 * the name of the file, it should be freed when no more needed. 03574 * 03575 * @since 0.6.2 03576 */ 03577 char* iso_file_source_get_name(IsoFileSource *src); 03578 03579 /** 03580 * Get information about the file. 03581 * @return 03582 * 1 success, < 0 error 03583 * Error codes: 03584 * ISO_FILE_ACCESS_DENIED 03585 * ISO_FILE_BAD_PATH 03586 * ISO_FILE_DOESNT_EXIST 03587 * ISO_OUT_OF_MEM 03588 * ISO_FILE_ERROR 03589 * ISO_NULL_POINTER 03590 * 03591 * @since 0.6.2 03592 */ 03593 int iso_file_source_lstat(IsoFileSource *src, struct stat *info); 03594 03595 /** 03596 * Check if the process has access to read file contents. Note that this 03597 * is not necessarily related with (l)stat functions. For example, in a 03598 * filesystem implementation to deal with an ISO image, if the user has 03599 * read access to the image it will be able to read all files inside it, 03600 * despite of the particular permission of each file in the RR tree, that 03601 * are what the above functions return. 03602 * 03603 * @return 03604 * 1 if process has read access, < 0 on error 03605 * Error codes: 03606 * ISO_FILE_ACCESS_DENIED 03607 * ISO_FILE_BAD_PATH 03608 * ISO_FILE_DOESNT_EXIST 03609 * ISO_OUT_OF_MEM 03610 * ISO_FILE_ERROR 03611 * ISO_NULL_POINTER 03612 * 03613 * @since 0.6.2 03614 */ 03615 int iso_file_source_access(IsoFileSource *src); 03616 03617 /** 03618 * Get information about the file. If the file is a symlink, the info 03619 * returned refers to the destination. 03620 * 03621 * @return 03622 * 1 success, < 0 error 03623 * Error codes: 03624 * ISO_FILE_ACCESS_DENIED 03625 * ISO_FILE_BAD_PATH 03626 * ISO_FILE_DOESNT_EXIST 03627 * ISO_OUT_OF_MEM 03628 * ISO_FILE_ERROR 03629 * ISO_NULL_POINTER 03630 * 03631 * @since 0.6.2 03632 */ 03633 int iso_file_source_stat(IsoFileSource *src, struct stat *info); 03634 03635 /** 03636 * Opens the source. 03637 * @return 1 on success, < 0 on error 03638 * Error codes: 03639 * ISO_FILE_ALREADY_OPENED 03640 * ISO_FILE_ACCESS_DENIED 03641 * ISO_FILE_BAD_PATH 03642 * ISO_FILE_DOESNT_EXIST 03643 * ISO_OUT_OF_MEM 03644 * ISO_FILE_ERROR 03645 * ISO_NULL_POINTER 03646 * 03647 * @since 0.6.2 03648 */ 03649 int iso_file_source_open(IsoFileSource *src); 03650 03651 /** 03652 * Close a previuously openned file 03653 * @return 1 on success, < 0 on error 03654 * Error codes: 03655 * ISO_FILE_ERROR 03656 * ISO_NULL_POINTER 03657 * ISO_FILE_NOT_OPENED 03658 * 03659 * @since 0.6.2 03660 */ 03661 int iso_file_source_close(IsoFileSource *src); 03662 03663 /** 03664 * Attempts to read up to count bytes from the given source into 03665 * the buffer starting at buf. 03666 * 03667 * The file src must be open() before calling this, and close() when no 03668 * more needed. Not valid for dirs. On symlinks it reads the destination 03669 * file. 03670 * 03671 * @param src 03672 * The given source 03673 * @param buf 03674 * Pointer to a buffer of at least count bytes where the read data will be 03675 * stored 03676 * @param count 03677 * Bytes to read 03678 * @return 03679 * number of bytes read, 0 if EOF, < 0 on error 03680 * Error codes: 03681 * ISO_FILE_ERROR 03682 * ISO_NULL_POINTER 03683 * ISO_FILE_NOT_OPENED 03684 * ISO_WRONG_ARG_VALUE -> if count == 0 03685 * ISO_FILE_IS_DIR 03686 * ISO_OUT_OF_MEM 03687 * ISO_INTERRUPTED 03688 * 03689 * @since 0.6.2 03690 */ 03691 int iso_file_source_read(IsoFileSource *src, void *buf, size_t count); 03692 03693 /** 03694 * Repositions the offset of the given IsoFileSource (must be opened) to the 03695 * given offset according to the value of flag. 03696 * 03697 * @param offset 03698 * in bytes 03699 * @param flag 03700 * 0 The offset is set to offset bytes (SEEK_SET) 03701 * 1 The offset is set to its current location plus offset bytes 03702 * (SEEK_CUR) 03703 * 2 The offset is set to the size of the file plus offset bytes 03704 * (SEEK_END). 03705 * @return 03706 * Absolute offset posistion on the file, or < 0 on error. Cast the 03707 * returning value to int to get a valid libisofs error. 03708 * @since 0.6.4 03709 */ 03710 off_t iso_file_source_lseek(IsoFileSource *src, off_t offset, int flag); 03711 03712 /** 03713 * Read a directory. 03714 * 03715 * Each call to this function will return a new children, until we reach 03716 * the end of file (i.e, no more children), in that case it returns 0. 03717 * 03718 * The dir must be open() before calling this, and close() when no more 03719 * needed. Only valid for dirs. 03720 * 03721 * Note that "." and ".." children MUST NOT BE returned. 03722 * 03723 * @param child 03724 * pointer to be filled with the given child. Undefined on error or OEF 03725 * @return 03726 * 1 on success, 0 if EOF (no more children), < 0 on error 03727 * Error codes: 03728 * ISO_FILE_ERROR 03729 * ISO_NULL_POINTER 03730 * ISO_FILE_NOT_OPENED 03731 * ISO_FILE_IS_NOT_DIR 03732 * ISO_OUT_OF_MEM 03733 * 03734 * @since 0.6.2 03735 */ 03736 int iso_file_source_readdir(IsoFileSource *src, IsoFileSource **child); 03737 03738 /** 03739 * Read the destination of a symlink. You don't need to open the file 03740 * to call this. 03741 * 03742 * @param src 03743 * An IsoFileSource corresponding to a symbolic link. 03744 * @param buf 03745 * allocated buffer of at least bufsiz bytes. 03746 * The dest. will be copied there, and it will be NULL-terminated 03747 * @param bufsiz 03748 * characters to be copied. Destination link will be truncated if 03749 * it is larger than given size. This include the '\0' character. 03750 * @return 03751 * 1 on success, < 0 on error 03752 * Error codes: 03753 * ISO_FILE_ERROR 03754 * ISO_NULL_POINTER 03755 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 03756 * ISO_FILE_IS_NOT_SYMLINK 03757 * ISO_OUT_OF_MEM 03758 * ISO_FILE_BAD_PATH 03759 * ISO_FILE_DOESNT_EXIST 03760 * 03761 * @since 0.6.2 03762 */ 03763 int iso_file_source_readlink(IsoFileSource *src, char *buf, size_t bufsiz); 03764 03765 03766 /** 03767 * Get the AA string with encoded ACL and xattr. 03768 * (Not to be confused with ECMA-119 Extended Attributes). 03769 * @param src The file source object to be inquired. 03770 * @param aa_string Returns a pointer to the AA string data. If no AA 03771 * string is available, *aa_string becomes NULL. 03772 * (See doc/susp_aaip_0_2.txt for the meaning of AA and 03773 * libisofs/aaip_0_2.h for encoding and decoding.) 03774 * The caller is responsible for finally calling free() 03775 * on non-NULL results. 03776 * @param flag Bitfield for control purposes 03777 * bit0= Transfer ownership of AA string data. 03778 * src will free the eventual cached data and might 03779 * not be able to produce it again. 03780 * bit1= No need to get ACL (but no guarantee of exclusion) 03781 * bit2= No need to get xattr (but no guarantee of exclusion) 03782 * @return 1 means success (*aa_string == NULL is possible) 03783 * <0 means failure and must b a valid libisofs error code 03784 * (e.g. ISO_FILE_ERROR if no better one can be found). 03785 * @since 0.6.14 03786 */ 03787 int iso_file_source_get_aa_string(IsoFileSource *src, 03788 unsigned char **aa_string, int flag); 03789 03790 /** 03791 * Get the filesystem for this source. No extra ref is added, so you 03792 * musn't unref the IsoFilesystem. 03793 * 03794 * @return 03795 * The filesystem, NULL on error 03796 * 03797 * @since 0.6.2 03798 */ 03799 IsoFilesystem* iso_file_source_get_filesystem(IsoFileSource *src); 03800 03801 /** 03802 * Take a ref to the given IsoFilesystem 03803 * 03804 * @since 0.6.2 03805 */ 03806 void iso_filesystem_ref(IsoFilesystem *fs); 03807 03808 /** 03809 * Drop your ref to the given IsoFilesystem, evetually freeing associated 03810 * resources. 03811 * 03812 * @since 0.6.2 03813 */ 03814 void iso_filesystem_unref(IsoFilesystem *fs); 03815 03816 /** 03817 * Create a new IsoFilesystem to access a existent ISO image. 03818 * 03819 * @param src 03820 * Data source to access data. 03821 * @param opts 03822 * Image read options 03823 * @param msgid 03824 * An image identifer, obtained with iso_image_get_msg_id(), used to 03825 * associated messages issued by the filesystem implementation with an 03826 * existent image. If you are not using this filesystem in relation with 03827 * any image context, just use 0x1fffff as the value for this parameter. 03828 * @param fs 03829 * Will be filled with a pointer to the filesystem that can be used 03830 * to access image contents. 03831 * @param 03832 * 1 on success, < 0 on error 03833 * 03834 * @since 0.6.2 03835 */ 03836 int iso_image_filesystem_new(IsoDataSource *src, IsoReadOpts *opts, int msgid, 03837 IsoImageFilesystem **fs); 03838 03839 /** 03840 * Get the volset identifier for an existent image. The returned string belong 03841 * to the IsoImageFilesystem and shouldn't be free() nor modified. 03842 * 03843 * @since 0.6.2 03844 */ 03845 const char *iso_image_fs_get_volset_id(IsoImageFilesystem *fs); 03846 03847 /** 03848 * Get the volume identifier for an existent image. The returned string belong 03849 * to the IsoImageFilesystem and shouldn't be free() nor modified. 03850 * 03851 * @since 0.6.2 03852 */ 03853 const char *iso_image_fs_get_volume_id(IsoImageFilesystem *fs); 03854 03855 /** 03856 * Get the publisher identifier for an existent image. The returned string 03857 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03858 * 03859 * @since 0.6.2 03860 */ 03861 const char *iso_image_fs_get_publisher_id(IsoImageFilesystem *fs); 03862 03863 /** 03864 * Get the data preparer identifier for an existent image. The returned string 03865 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03866 * 03867 * @since 0.6.2 03868 */ 03869 const char *iso_image_fs_get_data_preparer_id(IsoImageFilesystem *fs); 03870 03871 /** 03872 * Get the system identifier for an existent image. The returned string belong 03873 * to the IsoImageFilesystem and shouldn't be free() nor modified. 03874 * 03875 * @since 0.6.2 03876 */ 03877 const char *iso_image_fs_get_system_id(IsoImageFilesystem *fs); 03878 03879 /** 03880 * Get the application identifier for an existent image. The returned string 03881 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03882 * 03883 * @since 0.6.2 03884 */ 03885 const char *iso_image_fs_get_application_id(IsoImageFilesystem *fs); 03886 03887 /** 03888 * Get the copyright file identifier for an existent image. The returned string 03889 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03890 * 03891 * @since 0.6.2 03892 */ 03893 const char *iso_image_fs_get_copyright_file_id(IsoImageFilesystem *fs); 03894 03895 /** 03896 * Get the abstract file identifier for an existent image. The returned string 03897 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03898 * 03899 * @since 0.6.2 03900 */ 03901 const char *iso_image_fs_get_abstract_file_id(IsoImageFilesystem *fs); 03902 03903 /** 03904 * Get the biblio file identifier for an existent image. The returned string 03905 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03906 * 03907 * @since 0.6.2 03908 */ 03909 const char *iso_image_fs_get_biblio_file_id(IsoImageFilesystem *fs); 03910 03911 /** 03912 * Increment reference count of an IsoStream. 03913 * 03914 * @since 0.6.4 03915 */ 03916 void iso_stream_ref(IsoStream *stream); 03917 03918 /** 03919 * Decrement reference count of an IsoStream, and eventually free it if 03920 * refcount reach 0. 03921 * 03922 * @since 0.6.4 03923 */ 03924 void iso_stream_unref(IsoStream *stream); 03925 03926 /** 03927 * Opens the given stream. Remember to close the Stream before writing the 03928 * image. 03929 * 03930 * @return 03931 * 1 on success, 2 file greater than expected, 3 file smaller than 03932 * expected, < 0 on error 03933 * 03934 * @since 0.6.4 03935 */ 03936 int iso_stream_open(IsoStream *stream); 03937 03938 /** 03939 * Close a previously openned IsoStream. 03940 * 03941 * @return 03942 * 1 on success, < 0 on error 03943 * 03944 * @since 0.6.4 03945 */ 03946 int iso_stream_close(IsoStream *stream); 03947 03948 /** 03949 * Get the size of a given stream. This function should always return the same 03950 * size, even if the underlying source size changes, unless you call 03951 * iso_stream_update_size(). 03952 * 03953 * @return 03954 * IsoStream size in bytes 03955 * 03956 * @since 0.6.4 03957 */ 03958 off_t iso_stream_get_size(IsoStream *stream); 03959 03960 /** 03961 * Attempts to read up to count bytes from the given stream into 03962 * the buffer starting at buf. 03963 * 03964 * The stream must be open() before calling this, and close() when no 03965 * more needed. 03966 * 03967 * @return 03968 * number of bytes read, 0 if EOF, < 0 on error 03969 * 03970 * @since 0.6.4 03971 */ 03972 int iso_stream_read(IsoStream *stream, void *buf, size_t count); 03973 03974 /** 03975 * Whether the given IsoStream can be read several times, with the same 03976 * results. 03977 * For example, a regular file is repeatable, you can read it as many 03978 * times as you want. However, a pipe isn't. 03979 * 03980 * This function doesn't take into account if the file has been modified 03981 * between the two reads. 03982 * 03983 * @return 03984 * 1 if stream is repeatable, 0 if not, < 0 on error 03985 * 03986 * @since 0.6.4 03987 */ 03988 int iso_stream_is_repeatable(IsoStream *stream); 03989 03990 /** 03991 * Updates the size of the IsoStream with the current size of the 03992 * underlying source. 03993 * 03994 * @return 03995 * 1 if ok, < 0 on error (has to be a valid libisofs error code), 03996 * 0 if the IsoStream does not support this function. 03997 * @since 0.6.8 03998 */ 03999 int iso_stream_update_size(IsoStream *stream); 04000 04001 /** 04002 * Get an unique identifier for a given IsoStream. 04003 * 04004 * @since 0.6.4 04005 */ 04006 void iso_stream_get_id(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, 04007 ino_t *ino_id); 04008 04009 /************ Error codes and return values for libisofs ********************/ 04010 04011 /** successfully execution */ 04012 #define ISO_SUCCESS 1 04013 04014 /** 04015 * special return value, it could be or not an error depending on the 04016 * context. 04017 */ 04018 #define ISO_NONE 0 04019 04020 /** Operation canceled (FAILURE,HIGH, -1) */ 04021 #define ISO_CANCELED 0xE830FFFF 04022 04023 /** Unknown or unexpected fatal error (FATAL,HIGH, -2) */ 04024 #define ISO_FATAL_ERROR 0xF030FFFE 04025 04026 /** Unknown or unexpected error (FAILURE,HIGH, -3) */ 04027 #define ISO_ERROR 0xE830FFFD 04028 04029 /** Internal programming error. Please report this bug (FATAL,HIGH, -4) */ 04030 #define ISO_ASSERT_FAILURE 0xF030FFFC 04031 04032 /** 04033 * NULL pointer as value for an arg. that doesn't allow NULL (FAILURE,HIGH, -5) 04034 */ 04035 #define ISO_NULL_POINTER 0xE830FFFB 04036 04037 /** Memory allocation error (FATAL,HIGH, -6) */ 04038 #define ISO_OUT_OF_MEM 0xF030FFFA 04039 04040 /** Interrupted by a signal (FATAL,HIGH, -7) */ 04041 #define ISO_INTERRUPTED 0xF030FFF9 04042 04043 /** Invalid parameter value (FAILURE,HIGH, -8) */ 04044 #define ISO_WRONG_ARG_VALUE 0xE830FFF8 04045 04046 /** Can't create a needed thread (FATAL,HIGH, -9) */ 04047 #define ISO_THREAD_ERROR 0xF030FFF7 04048 04049 /** Write error (FAILURE,HIGH, -10) */ 04050 #define ISO_WRITE_ERROR 0xE830FFF6 04051 04052 /** Buffer read error (FAILURE,HIGH, -11) */ 04053 #define ISO_BUF_READ_ERROR 0xE830FFF5 04054 04055 /** Trying to add to a dir a node already added to a dir (FAILURE,HIGH, -64) */ 04056 #define ISO_NODE_ALREADY_ADDED 0xE830FFC0 04057 04058 /** Node with same name already exists (FAILURE,HIGH, -65) */ 04059 #define ISO_NODE_NAME_NOT_UNIQUE 0xE830FFBF 04060 04061 /** Trying to remove a node that was not added to dir (FAILURE,HIGH, -65) */ 04062 #define ISO_NODE_NOT_ADDED_TO_DIR 0xE830FFBE 04063 04064 /** A requested node does not exist (FAILURE,HIGH, -66) */ 04065 #define ISO_NODE_DOESNT_EXIST 0xE830FFBD 04066 04067 /** 04068 * Try to set the boot image of an already bootable image (FAILURE,HIGH, -67) 04069 */ 04070 #define ISO_IMAGE_ALREADY_BOOTABLE 0xE830FFBC 04071 04072 /** Trying to use an invalid file as boot image (FAILURE,HIGH, -68) */ 04073 #define ISO_BOOT_IMAGE_NOT_VALID 0xE830FFBB 04074 04075 /** 04076 * Error on file operation (FAILURE,HIGH, -128) 04077 * (take a look at more specified error codes below) 04078 */ 04079 #define ISO_FILE_ERROR 0xE830FF80 04080 04081 /** Trying to open an already opened file (FAILURE,HIGH, -129) */ 04082 #define ISO_FILE_ALREADY_OPENED 0xE830FF7F 04083 04084 /* @deprecated use ISO_FILE_ALREADY_OPENED instead */ 04085 #define ISO_FILE_ALREADY_OPENNED 0xE830FF7F 04086 04087 /** Access to file is not allowed (FAILURE,HIGH, -130) */ 04088 #define ISO_FILE_ACCESS_DENIED 0xE830FF7E 04089 04090 /** Incorrect path to file (FAILURE,HIGH, -131) */ 04091 #define ISO_FILE_BAD_PATH 0xE830FF7D 04092 04093 /** The file does not exist in the filesystem (FAILURE,HIGH, -132) */ 04094 #define ISO_FILE_DOESNT_EXIST 0xE830FF7C 04095 04096 /** Trying to read or close a file not openned (FAILURE,HIGH, -133) */ 04097 #define ISO_FILE_NOT_OPENED 0xE830FF7B 04098 04099 /* @deprecated use ISO_FILE_NOT_OPENED instead */ 04100 #define ISO_FILE_NOT_OPENNED ISO_FILE_NOT_OPENED 04101 04102 /** Directory used where no dir is expected (FAILURE,HIGH, -134) */ 04103 #define ISO_FILE_IS_DIR 0xE830FF7A 04104 04105 /** Read error (FAILURE,HIGH, -135) */ 04106 #define ISO_FILE_READ_ERROR 0xE830FF79 04107 04108 /** Not dir used where a dir is expected (FAILURE,HIGH, -136) */ 04109 #define ISO_FILE_IS_NOT_DIR 0xE830FF78 04110 04111 /** Not symlink used where a symlink is expected (FAILURE,HIGH, -137) */ 04112 #define ISO_FILE_IS_NOT_SYMLINK 0xE830FF77 04113 04114 /** Can't seek to specified location (FAILURE,HIGH, -138) */ 04115 #define ISO_FILE_SEEK_ERROR 0xE830FF76 04116 04117 /** File not supported in ECMA-119 tree and thus ignored (WARNING,MEDIUM, -139) */ 04118 #define ISO_FILE_IGNORED 0xD020FF75 04119 04120 /* A file is bigger than supported by used standard (WARNING,MEDIUM, -140) */ 04121 #define ISO_FILE_TOO_BIG 0xD020FF74 04122 04123 /* File read error during image creation (MISHAP,HIGH, -141) */ 04124 #define ISO_FILE_CANT_WRITE 0xE430FF73 04125 04126 /* Can't convert filename to requested charset (WARNING,MEDIUM, -142) */ 04127 #define ISO_FILENAME_WRONG_CHARSET 0xD020FF72 04128 /* This was once a HINT. Deprecated now. */ 04129 #define ISO_FILENAME_WRONG_CHARSET_OLD 0xC020FF72 04130 04131 /* File can't be added to the tree (SORRY,HIGH, -143) */ 04132 #define ISO_FILE_CANT_ADD 0xE030FF71 04133 04134 /** 04135 * File path break specification constraints and will be ignored 04136 * (WARNING,MEDIUM, -144) 04137 */ 04138 #define ISO_FILE_IMGPATH_WRONG 0xD020FF70 04139 04140 /** 04141 * Offset greater than file size (FAILURE,HIGH, -145) 04142 * @since 0.6.4 04143 */ 04144 #define ISO_FILE_OFFSET_TOO_BIG 0xE830FF6A 04145 04146 /** Charset conversion error (FAILURE,HIGH, -256) */ 04147 #define ISO_CHARSET_CONV_ERROR 0xE830FF00 04148 04149 /** 04150 * Too much files to mangle, i.e. we cannot guarantee unique file names 04151 * (FAILURE,HIGH, -257) 04152 */ 04153 #define ISO_MANGLE_TOO_MUCH_FILES 0xE830FEFF 04154 04155 /* image related errors */ 04156 04157 /** 04158 * Wrong or damaged Primary Volume Descriptor (FAILURE,HIGH, -320) 04159 * This could mean that the file is not a valid ISO image. 04160 */ 04161 #define ISO_WRONG_PVD 0xE830FEC0 04162 04163 /** Wrong or damaged RR entry (SORRY,HIGH, -321) */ 04164 #define ISO_WRONG_RR 0xE030FEBF 04165 04166 /** Unsupported RR feature (SORRY,HIGH, -322) */ 04167 #define ISO_UNSUPPORTED_RR 0xE030FEBE 04168 04169 /** Wrong or damaged ECMA-119 (FAILURE,HIGH, -323) */ 04170 #define ISO_WRONG_ECMA119 0xE830FEBD 04171 04172 /** Unsupported ECMA-119 feature (FAILURE,HIGH, -324) */ 04173 #define ISO_UNSUPPORTED_ECMA119 0xE830FEBC 04174 04175 /** Wrong or damaged El-Torito catalog (SORRY,HIGH, -325) */ 04176 #define ISO_WRONG_EL_TORITO 0xE030FEBB 04177 04178 /** Unsupported El-Torito feature (SORRY,HIGH, -326) */ 04179 #define ISO_UNSUPPORTED_EL_TORITO 0xE030FEBA 04180 04181 /** Can't patch an isolinux boot image (SORRY,HIGH, -327) */ 04182 #define ISO_ISOLINUX_CANT_PATCH 0xE030FEB9 04183 04184 /** Unsupported SUSP feature (SORRY,HIGH, -328) */ 04185 #define ISO_UNSUPPORTED_SUSP 0xE030FEB8 04186 04187 /** Error on a RR entry that can be ignored (WARNING,HIGH, -329) */ 04188 #define ISO_WRONG_RR_WARN 0xD030FEB7 04189 04190 /** Error on a RR entry that can be ignored (HINT,MEDIUM, -330) */ 04191 #define ISO_SUSP_UNHANDLED 0xC020FEB6 04192 04193 /** Multiple ER SUSP entries found (WARNING,HIGH, -331) */ 04194 #define ISO_SUSP_MULTIPLE_ER 0xD030FEB5 04195 04196 /** Unsupported volume descriptor found (HINT,MEDIUM, -332) */ 04197 #define ISO_UNSUPPORTED_VD 0xC020FEB4 04198 04199 /** El-Torito related warning (WARNING,HIGH, -333) */ 04200 #define ISO_EL_TORITO_WARN 0xD030FEB3 04201 04202 /** Image write cancelled (MISHAP,HIGH, -334) */ 04203 #define ISO_IMAGE_WRITE_CANCELED 0xE430FEB2 04204 04205 /** El-Torito image is hidden (WARNING,HIGH, -335) */ 04206 #define ISO_EL_TORITO_HIDDEN 0xD030FEB1 04207 04208 /** Read error occured with IsoDataSource (SORRY,HIGH, -513) */ 04209 #define ISO_DATA_SOURCE_SORRY 0xE030FCFF 04210 04211 /** Read error occured with IsoDataSource (MISHAP,HIGH, -513) */ 04212 #define ISO_DATA_SOURCE_MISHAP 0xE430FCFF 04213 04214 /** Read error occured with IsoDataSource (FAILURE,HIGH, -513) */ 04215 #define ISO_DATA_SOURCE_FAILURE 0xE830FCFF 04216 04217 /** Read error occured with IsoDataSource (FATAL,HIGH, -513) */ 04218 #define ISO_DATA_SOURCE_FATAL 0xF030FCFF 04219 04220 04221 /** AAIP info with ACL or xattr in ISO image will be ignored 04222 (NOTE, HIGH, -336) */ 04223 #define ISO_AAIP_IGNORED 0xB030FEB0 04224 04225 /** Error with decoding ACL from AAIP info (FAILURE, HIGH, -337) */ 04226 #define ISO_AAIP_BAD_ACL 0xE830FEAF 04227 04228 /** Error with encoding ACL for AAIP (FAILURE, HIGH, -338) */ 04229 #define ISO_AAIP_BAD_ACL_TEXT 0xE830FEAE 04230 04231 /** AAIP processing for ACL or xattr not enabled at compile time 04232 (FAILURE, HIGH, -339) */ 04233 #define ISO_AAIP_NOT_ENABLED 0xE830FEAD 04234 04235 /** Error with decoding AAIP info for ACL or xattr (FAILURE, HIGH, -340) */ 04236 #define ISO_AAIP_BAD_AASTRING 0xE830FEAC 04237 04238 /** Error with reading ACL or xattr from local file (FAILURE, HIGH, -341) */ 04239 #define ISO_AAIP_NO_GET_LOCAL 0xE830FEAB 04240 04241 /** Error with attaching ACL or xattr to local file (FAILURE, HIGH, -342) */ 04242 #define ISO_AAIP_NO_SET_LOCAL 0xE830FEAA 04243 04244 /** Unallowed attempt to set an xattr with non-userspace name 04245 (FAILURE, HIGH, -343) */ 04246 #define ISO_AAIP_NON_USER_NAME 0xE830FEA9 04247 04248 04249 /* --------------------------------- AAIP --------------------------------- */ 04250 04251 /** 04252 * Function to identify and manage AA strings as xinfo of IsoNode. 04253 * 04254 * An AA 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-1.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 AA strings directly. They should 04260 * rather make use of the appropriate iso_node_get_* and iso_node_set_* calls. 04261 * 04262 * AAIP represents ACLs as xattr with empty name and AAIP-specific binary 04263 * content. Local filesystems may represent ACLs as xattr with names like 04264 * "system.posix_acl_access". libisofs does not interpret those local 04265 * xattr representations of ACL directly but rather uses the ACL interface of 04266 * the local system. By default the local xattr representations of ACL will 04267 * not become part of the AAIP Attribute List via iso_local_get_attrs() and 04268 * not be attached to local files via iso_local_set_attrs(). 04269 * 04270 * @since 0.6.14 04271 */ 04272 int aaip_xinfo_func(void *data, int flag); 04273 04274 04275 /** 04276 * Get the eventual ACLs which are associated with the node. 04277 * The result will be in "long" text form as of man acl resp. acl_to_text(). 04278 * Call this function with flag bit15 to finally release the memory 04279 * occupied by an ACL inquiry. 04280 * 04281 * @param node 04282 * The node that is to be inquired. 04283 * @param access_text 04284 * Will return a pointer to the eventual "access" ACL text or NULL if it 04285 * is not available and flag bit 4 is set. 04286 * @param default_text 04287 * Will return a pointer to the eventual "default" ACL or NULL if it 04288 * is not available. 04289 * (Linux directories can have a "default" ACL which influences 04290 * the permissions of newly created files.) 04291 * @param flag 04292 * Bitfield for control purposes 04293 * bit4= if no "access" ACL is available: return *access_text == NULL 04294 * else: produce ACL from stat(2) permissions 04295 * bit15= free memory and return 1 (node may be NULL) 04296 * @return 04297 * 2 *access_text was produced from stat(2) permissions 04298 * 1 *access_text was produced from ACL of node 04299 * 0 if flag bit4 is set and no ACL is available 04300 * < 0 on error 04301 * 04302 * @since 0.6.14 04303 */ 04304 int iso_node_get_acl_text(IsoNode *node, 04305 char **access_text, char **default_text, int flag); 04306 04307 04308 /** 04309 * Set the ACLs of the given node to the lists in parameters access_text and 04310 * default_text or delete them. 04311 * 04312 * The stat(2) permission bits get updated according to the new "access" ACL if 04313 * neither bit1 of parameter flag is set nor parameter access_text is NULL. 04314 * Note that S_IRWXG permission bits correspond to ACL mask permissions 04315 * if a "mask::" entry exists in the ACL. Only if there is no "mask::" then 04316 * the "group::" entry corresponds to to S_IRWXG. 04317 * 04318 * @param node 04319 * The node that is to be manipulated. 04320 * @param access_text 04321 * The text to be set into effect as "access" ACL. NULL will delete an 04322 * eventually existing "access" ACL of the node. 04323 * @param default_text 04324 * The text to be set into effect as "default" ACL. NULL will delete an 04325 * eventually existing "default" ACL of the node. 04326 * (Linux directories can have a "default" ACL which influences 04327 * the permissions of newly created files.) 04328 * @param flag 04329 * Bitfield for control purposes 04330 * bit1= ignore text parameters but rather update eventual "access" ACL 04331 * to the stat(2) permissions of node. If no "access" ACL exists, 04332 * then do nothing and return success. 04333 * @return 04334 * > 0 success 04335 * < 0 failure 04336 * 04337 * @since 0.6.14 04338 */ 04339 int iso_node_set_acl_text(IsoNode *node, 04340 char *access_text, char *default_text, int flag); 04341 04342 /** 04343 * Like iso_node_get_permissions but reflecting ACL entry "group::" in S_IRWXG 04344 * rather than ACL entry "mask::". This is necessary if the permissions of a 04345 * node with ACL shall be restored to a filesystem without restoring the ACL. 04346 * The same mapping happens internally when the ACL of a node is deleted. 04347 * If the node has no ACL then the result is iso_node_get_permissions(node). 04348 * @param node 04349 * The node that is to be inquired. 04350 * @return 04351 * Permission bits as of stat(2) 04352 * 04353 * @since 0.6.14 04354 */ 04355 mode_t iso_node_get_perms_wo_acl(const IsoNode *node); 04356 04357 04358 /** 04359 * Get the list of xattr which is associated with the node. 04360 * The resulting data may finally be disposed by a call to this function 04361 * with flag bit15 set, or its components may be freed one-by-one. 04362 * The following values are either NULL or malloc() memory: 04363 * *names, *value_lengths, *values, (*names)[i], (*values)[i] 04364 * with 0 <= i < *num_attrs. 04365 * It is allowed to replace or reallocate those memory items in order to 04366 * to manipulate the attribute list before submitting it to other calls. 04367 * 04368 * If enabled by flag bit0, this list possibly includes the ACLs of the node. 04369 * They are eventually encoded in a pair with empty name. It is not advisable 04370 * to alter the value or name of that pair. One may decide to erase both ACLs 04371 * by deleting this pair or to copy both ACLs by copying the content of this 04372 * pair to an empty named pair of another node. 04373 * For all other ACL purposes use iso_node_get_acl_text(). 04374 * 04375 * @param node 04376 * The node that is to be manipulated. 04377 * @param num_attrs 04378 * Will return the number of name-value pairs 04379 * @param names 04380 * Will return an array of pointers to 0-terminated names 04381 * @param value_lengths 04382 * Will return an arry with the lenghts of values 04383 * @param values 04384 * Will return an array of pointers to 8-bit values 04385 * @param flag 04386 * Bitfield for control purposes 04387 * bit0= obtain eventual ACLs as attribute with empty name 04388 * bit2= with bit0: do not obtain attributes other than ACLs 04389 * bit15= free memory (node may be NULL) 04390 * @return 04391 * 1 = ok (but *num_attrs may be 0) 04392 * < 0 = error 04393 * 04394 * @since 0.6.14 04395 */ 04396 int iso_node_get_attrs(IsoNode *node, size_t *num_attrs, 04397 char ***names, size_t **value_lengths, char ***values, int flag); 04398 04399 /** 04400 * Set the list of xattr which is associated with the node. 04401 * The data get copied so that you may dispose your input data afterwards. 04402 * 04403 * If enabled by flag bit0 then the submitted list of attributes will not only 04404 * overwrite xattr but also both eventual ACLs of the node. Eventual ACL in 04405 * the submitted list have to reside in an attribute with empty name. 04406 * 04407 * @param node 04408 * The node that is to be manipulated. 04409 * @param num_attrs 04410 * Number of attributes 04411 * @param names 04412 * Array of pointers to 0 terminated name strings 04413 * @param value_lengths 04414 * Array of byte lengths for each value 04415 * @param values 04416 * Array of pointers to the value bytes 04417 * @param flag 04418 * Bitfield for control purposes 04419 * bit0= Do not maintain eventual existing ACL of the node. 04420 * Set eventual new ACL from value of empty name. 04421 * bit1= Do not clear the existing attribute list but merge it with 04422 * the list given by this call 04423 * bit2= Delete the attributes with the given names 04424 * bit3= Allow non-user attributes. 04425 * I.e. those with a non-empty name which does not begin by "user." 04426 * (The empty name is always allowed and governed by bit0.) This 04427 * deletes all previously existing attributes if not bit1 is set. 04428 * @return 04429 * 1 = ok 04430 * < 0 = error 04431 * 04432 * @since 0.6.14 04433 */ 04434 int iso_node_set_attrs(IsoNode *node, size_t num_attrs, char **names, 04435 size_t *value_lengths, char **values, int flag); 04436 04437 04438 /* ----- This is an interface to ACL and xattr of the local filesystem ----- */ 04439 04440 /** 04441 * libisofs has an internal system dependent adapter to ACL and xattr 04442 * operations. For the sake of completeness and simplicity it exposes this 04443 * functionality to its applications which might want to get and set ACLs 04444 * from local files. 04445 */ 04446 04447 /** 04448 * Get an ACL of the given file in the local filesystem in long text form. 04449 * 04450 * @param disk_path 04451 * Path to the file 04452 * @param text 04453 * Will return a pointer to the ACL text. If not NULL the text will be 04454 * 0 terminated and finally has to be disposed by a call to this function 04455 * with bit15 set. 04456 * @param flag 04457 * Bitfield for control purposes 04458 * bit0= get "default" ACL rather than "access" ACL 04459 * bit4= set *text = NULL and return 2 04460 * if the ACL matches st_mode permissions. 04461 * bit5= in case of symbolic link: inquire link target 04462 * bit15= free text and return 1 04463 * @return 04464 * 1 ok 04465 * 2 ok, trivial ACL found while bit4 is set, *text is NULL 04466 * 0 no ACL manipulation adapter available 04467 * -1 failure of system ACL service (see errno) 04468 * -2 attempt to inquire ACL of a symbolic link without bit4 or bit5 04469 * resp. with no suitable link target 04470 * 04471 * @since 0.6.14 04472 */ 04473 int iso_local_get_acl_text(char *disk_path, char **text, int flag); 04474 04475 04476 /** 04477 * Set the ACL of the given file in the local filesystem to a given list 04478 * in long text form. 04479 * 04480 * @param disk_path 04481 * Path to the file 04482 * @param text 04483 * The input text (0 terminated, ACL long text form) 04484 * @param flag 04485 * Bitfield for control purposes 04486 * bit0= set "default" ACL rather than "access" ACL 04487 * bit5= in case of symbolic link: manipulate link target 04488 * @return 04489 * > 0 ok 04490 * 0 no ACL manipulation adapter available 04491 * -1 failure of system ACL service (see errno) 04492 * -2 attempt to manipulate ACL of a symbolic link without bit5 04493 * resp. with no suitable link target 04494 * 04495 * @since 0.6.14 04496 */ 04497 int iso_local_set_acl_text(char *disk_path, char *text, int flag); 04498 04499 04500 /** 04501 * Obtain permissions of a file in the local filesystem which shall reflect 04502 * ACL entry "group::" in S_IRWXG rather than ACL entry "mask::". This is 04503 * necessary if the permissions of a disk file with ACL shall be copied to 04504 * an object which has no ACL. 04505 * @param disk_path 04506 * Path to the local file which may have an "access" ACL or not. 04507 * @param flag 04508 * Bitfield for control purposes 04509 * bit5= in case of symbolic link: inquire link target 04510 * @param st_mode 04511 * Returns permission bits as of stat(2) 04512 * @return 04513 * 1 success 04514 * -1 failure of lstat() resp. stat() (see errno) 04515 * 04516 * @since 0.6.14 04517 */ 04518 int iso_local_get_perms_wo_acl(char *disk_path, mode_t *st_mode, int flag); 04519 04520 04521 /** 04522 * Get xattr and non-trivial ACLs of the given file in the local filesystem. 04523 * The resulting data has finally to be disposed by a call to this function 04524 * with flag bit15 set. 04525 * 04526 * Eventual ACLs will get encoded as attribute pair with empty name if this is 04527 * enabled by flag bit0. An ACL which simply replects stat(2) permissions 04528 * will not be put into the result. 04529 * 04530 * @param disk_path 04531 * Path to the file 04532 * @param num_attrs 04533 * Will return the number of name-value pairs 04534 * @param names 04535 * Will return an array of pointers to 0-terminated names 04536 * @param value_lengths 04537 * Will return an arry with the lenghts of values 04538 * @param values 04539 * Will return an array of pointers to 8-bit values 04540 * @param flag 04541 * Bitfield for control purposes 04542 * bit0= obtain eventual ACLs as attribute with empty name 04543 * bit2= do not obtain attributes other than ACLs 04544 * bit3= do not ignore eventual non-user attributes. 04545 * I.e. those with a name which does not begin by "user." 04546 * bit5= in case of symbolic link: inquire link target 04547 * bit15= free memory 04548 * @return 04549 * 1 ok 04550 * < 0 failure 04551 * 04552 * @since 0.6.14 04553 */ 04554 int iso_local_get_attrs(char *disk_path, size_t *num_attrs, char ***names, 04555 size_t **value_lengths, char ***values, int flag); 04556 04557 04558 /** 04559 * Attach a list of xattr and ACLs to the given file in the local filesystem. 04560 * 04561 * Eventual ACLs have to be encoded as attribute pair with empty name. 04562 * 04563 * @param disk_path 04564 * Path to the file 04565 * @param num_attrs 04566 * Number of attributes 04567 * @param names 04568 * Array of pointers to 0 terminated name strings 04569 * @param value_lengths 04570 * Array of byte lengths for each attribute payload 04571 * @param values 04572 * Array of pointers to the attribute payload bytes 04573 * @param flag 04574 * Bitfield for control purposes 04575 * bit0= do not attach ACLs from an eventual attribute with empty name 04576 * bit3= do not ignore eventual non-user attributes. 04577 * I.e. those with a name which does not begin by "user." 04578 * bit5= in case of symbolic link: manipulate link target 04579 * @return 04580 * 1 = ok 04581 * < 0 = error 04582 * 04583 * @since 0.6.14 04584 */ 04585 int iso_local_set_attrs(char *disk_path, size_t num_attrs, char **names, 04586 size_t *value_lengths, char **values, int flag); 04587 04588 04589 /* ------------------------------------------------------------------------- */ 04590 04591 #ifdef LIBISOFS_WITHOUT_LIBBURN 04592 04593 /** 04594 This is a copy from the API of libburn-0.6.0 (under GPL). 04595 It is supposed to be as stable as any overall include of libburn.h. 04596 I.e. if this definition is out of sync then you cannot rely on any 04597 contract that was made with libburn.h. 04598 04599 Libisofs does not need to be linked with libburn at all. But if it is 04600 linked with libburn then it must be libburn-0.4.2 or later. 04601 04602 An application that provides own struct burn_source objects and does not 04603 include libburn/libburn.h has to define LIBISOFS_WITHOUT_LIBBURN before 04604 including libisofs/libisofs.h in order to make this copy available. 04605 */ 04606 04607 04608 /** Data source interface for tracks. 04609 This allows to use arbitrary program code as provider of track input data. 04610 04611 Objects compliant to this interface are either provided by the application 04612 or by API calls of libburn: burn_fd_source_new() , burn_file_source_new(), 04613 and burn_fifo_source_new(). 04614 04615 The API calls allow to use any file object as data source. Consider to feed 04616 an eventual custom data stream asynchronously into a pipe(2) and to let 04617 libburn handle the rest. 04618 In this case the following rule applies: 04619 Call burn_source_free() exactly once for every source obtained from 04620 libburn API. You MUST NOT otherwise use or manipulate its components. 04621 04622 In general, burn_source objects can be freed as soon as they are attached 04623 to track objects. The track objects will keep them alive and dispose them 04624 when they are no longer needed. With a fifo burn_source it makes sense to 04625 keep the own reference for inquiring its state while burning is in 04626 progress. 04627 04628 --- 04629 04630 The following description of burn_source applies only to application 04631 implemented burn_source objects. You need not to know it for API provided 04632 ones. 04633 04634 If you really implement an own passive data producer by this interface, 04635 then beware: it can do anything and it can spoil everything. 04636 04637 In this case the functions (*read), (*get_size), (*set_size), (*free_data) 04638 MUST be implemented by the application and attached to the object at 04639 creation time. 04640 Function (*read_sub) is allowed to be NULL or it MUST be implemented and 04641 attached. 04642 04643 burn_source.refcount MUST be handled properly: If not exactly as many 04644 references are freed as have been obtained, then either memory leaks or 04645 corrupted memory are the consequence. 04646 All objects which are referred to by *data must be kept existent until 04647 (*free_data) is called via burn_source_free() by the last referer. 04648 */ 04649 struct burn_source { 04650 04651 /** Reference count for the data source. MUST be 1 when a new source 04652 is created and thus the first reference is handed out. Increment 04653 it to take more references for yourself. Use burn_source_free() 04654 to destroy your references to it. */ 04655 int refcount; 04656 04657 04658 /** Read data from the source. Semantics like with read(2), but MUST 04659 either deliver the full buffer as defined by size or MUST deliver 04660 EOF (return 0) or failure (return -1) at this call or at the 04661 next following call. I.e. the only incomplete buffer may be the 04662 last one from that source. 04663 libburn will read a single sector by each call to (*read). 04664 The size of a sector depends on BURN_MODE_*. The known range is 04665 2048 to 2352. 04666 04667 If this call is reading from a pipe then it will learn 04668 about the end of data only when that pipe gets closed on the 04669 feeder side. So if the track size is not fixed or if the pipe 04670 delivers less than the predicted amount or if the size is not 04671 block aligned, then burning will halt until the input process 04672 closes the pipe. 04673 04674 IMPORTANT: 04675 If this function pointer is NULL, then the struct burn_source is of 04676 version >= 1 and the job of .(*read)() is done by .(*read_xt)(). 04677 See below, member .version. 04678 */ 04679 int (*read)(struct burn_source *, unsigned char *buffer, int size); 04680 04681 04682 /** Read subchannel data from the source (NULL if lib generated) 04683 WARNING: This is an obscure feature with CD raw write modes. 04684 Unless you checked the libburn code for correctness in that aspect 04685 you should not rely on raw writing with own subchannels. 04686 ADVICE: Set this pointer to NULL. 04687 */ 04688 int (*read_sub)(struct burn_source *, unsigned char *buffer, int size); 04689 04690 04691 /** Get the size of the source's data. Return 0 means unpredictable 04692 size. If application provided (*get_size) allows return 0, then 04693 the application MUST provide a fully functional (*set_size). 04694 */ 04695 off_t (*get_size)(struct burn_source *); 04696 04697 04698 /* @since 0.3.2 */ 04699 /** Program the reply of (*get_size) to a fixed value. It is advised 04700 to implement this by a attribute off_t fixed_size; in *data . 04701 The read() function does not have to take into respect this fake 04702 setting. It is rather a note of libburn to itself. Eventually 04703 necessary truncation or padding is done in libburn. Truncation 04704 is usually considered a misburn. Padding is considered ok. 04705 04706 libburn is supposed to work even if (*get_size) ignores the 04707 setting by (*set_size). But your application will not be able to 04708 enforce fixed track sizes by burn_track_set_size() and possibly 04709 even padding might be left out. 04710 */ 04711 int (*set_size)(struct burn_source *source, off_t size); 04712 04713 04714 /** Clean up the source specific data. This function will be called 04715 once by burn_source_free() when the last referer disposes the 04716 source. 04717 */ 04718 void (*free_data)(struct burn_source *); 04719 04720 04721 /** Next source, for when a source runs dry and padding is disabled 04722 WARNING: This is an obscure feature. Set to NULL at creation and 04723 from then on leave untouched and uninterpreted. 04724 */ 04725 struct burn_source *next; 04726 04727 04728 /** Source specific data. Here the various source classes express their 04729 specific properties and the instance objects store their individual 04730 management data. 04731 E.g. data could point to a struct like this: 04732 struct app_burn_source 04733 { 04734 struct my_app *app_handle; 04735 ... other individual source parameters ... 04736 off_t fixed_size; 04737 }; 04738 04739 Function (*free_data) has to be prepared to clean up and free 04740 the struct. 04741 */ 04742 void *data; 04743 04744 04745 /* @since 0.4.2 */ 04746 /** Valid only if above member .(*read)() is NULL. This indicates a 04747 version of struct burn_source younger than 0. 04748 From then on, member .version tells which further members exist 04749 in the memory layout of struct burn_source. libburn will only touch 04750 those announced extensions. 04751 04752 Versions: 04753 0 has .(*read)() != NULL, not even .version is present. 04754 1 has .version, .(*read_xt)(), .(*cancel)() 04755 */ 04756 int version; 04757 04758 /** This substitutes for (*read)() in versions above 0. */ 04759 int (*read_xt)(struct burn_source *, unsigned char *buffer, int size); 04760 04761 /** Informs the burn_source that the consumer of data prematurely 04762 ended reading. This call may or may not be issued by libburn 04763 before (*free_data)() is called. 04764 */ 04765 int (*cancel)(struct burn_source *source); 04766 }; 04767 04768 #endif /* LIBISOFS_WITHOUT_LIBBURN */ 04769 04770 /* ----------------------------- Bug Fixes ----------------------------- */ 04771 04772 04773 /* Bug Fix : Augment ecma119.c:write_dirs() by parameter parent 04774 and use that one for the second directory entry 001 = "..". 04775 04776 Everything else seems wrong. 04777 */ 04778 #define Libisofs_use_parent_for_dot_doT yes 04779 04780 04781 /* Bug fix : Use correct size of 237 if the ER of RRIP-1.10 shal be written 04782 (rather than size 182 of RRIP-1.12) 04783 04784 */ 04785 #define Libisofs_rrip_1_10_er_bugfiX yes 04786 04787 04788 /* ---------------------------- Experiments ---------------------------- */ 04789 04790 04791 /* Experiment: Ignore PX inode numbers, 04792 have boot image inode number counted by fs_give_ino_number() 04793 */ 04794 #define Libisofs_new_fs_image_inO yes 04795 04796 04797 /* Experiment: Trying to avoid the risk of losing file content by duplicate 04798 inodes. iso_file_src_cmp() shall compare sizes too. 04799 */ 04800 #define Libisofs_file_src_cmp_sizE yes 04801 04802 04803 /* Experiment: Revoke Ticket 144, use data file LBAs again. 04804 (will work only if not Libisofs_new_fs_image_inO 04805 and wll only be safe with Libisofs_file_src_cmp_sizE) 04806 #define Libisofs_ino_from_lbA yes 04807 */ 04808 04809 04810 /* Experiment: Write obsolete RR entries with Rock Ridge. 04811 I suspect Solaris wants to see them. 04812 DID NOT HELP: Solaris knows only RRIP_1991A. 04813 04814 #define Libisofs_with_rrip_rR yes 04815 */ 04816 04817 04818 /* Experiment: Use iso_iconv*() wrappers. 04819 They can print errno messages and they 04820 can avoid iconv() if the identical mapping is desired. 04821 One could install own simple conversion capabilities. 04822 #define Libisofs_with_iso_iconV yes 04823 */ 04824 04825 04826 #endif /*LIBISO_LIBISOFS_H_*/