00001 /* 00002 * Copyright (c) 2007-2008 Vreixo Formoso, Mario Danic 00003 * 00004 * This file is part of the libisofs project; you can redistribute it and/or 00005 * modify it under the terms of the GNU General Public License version 2 as 00006 * published by the Free Software Foundation. See COPYING file for details. 00007 */ 00008 #ifndef LIBISO_LIBISOFS_H_ 00009 #define LIBISO_LIBISOFS_H_ 00010 00011 #include <sys/stat.h> 00012 #include <stdint.h> 00013 #include <stdlib.h> 00014 00015 struct burn_source; 00016 00017 /** 00018 * Context for image creation. It holds the files that will be added to image, 00019 * and several options to control libisofs behavior. 00020 * 00021 * @since 0.6.2 00022 */ 00023 typedef struct Iso_Image IsoImage; 00024 00025 /* 00026 * A node in the iso tree, i.e. a file that will be written to image. 00027 * 00028 * It can represent any kind of files. When needed, you can get the type with 00029 * iso_node_get_type() and cast it to the appropiate subtype. Useful macros 00030 * are provided, see below. 00031 * 00032 * @since 0.6.2 00033 */ 00034 typedef struct Iso_Node IsoNode; 00035 00036 /** 00037 * A directory in the iso tree. It is an special type of IsoNode and can be 00038 * casted to it in any case. 00039 * 00040 * @since 0.6.2 00041 */ 00042 typedef struct Iso_Dir IsoDir; 00043 00044 /** 00045 * A symbolic link in the iso tree. It is an special type of IsoNode and can be 00046 * casted to it in any case. 00047 * 00048 * @since 0.6.2 00049 */ 00050 typedef struct Iso_Symlink IsoSymlink; 00051 00052 /** 00053 * A regular file in the iso tree. It is an special type of IsoNode and can be 00054 * casted to it in any case. 00055 * 00056 * @since 0.6.2 00057 */ 00058 typedef struct Iso_File IsoFile; 00059 00060 /** 00061 * An special file in the iso tree. This is used to represent any POSIX file 00062 * other that regular files, directories or symlinks, i.e.: socket, block and 00063 * character devices, and fifos. 00064 * It is an special type of IsoNode and can be casted to it in any case. 00065 * 00066 * @since 0.6.2 00067 */ 00068 typedef struct Iso_Special IsoSpecial; 00069 00070 /** 00071 * The type of an IsoNode. 00072 * 00073 * When an user gets an IsoNode from an image, (s)he can use 00074 * iso_node_get_type() to get the current type of the node, and then 00075 * cast to the appropriate subtype. For example: 00076 * 00077 * ... 00078 * IsoNode *node; 00079 * res = iso_dir_iter_next(iter, &node); 00080 * if (res == 1 && iso_node_get_type(node) == LIBISO_DIR) { 00081 * IsoDir *dir = (IsoDir *)node; 00082 * ... 00083 * } 00084 * 00085 * @since 0.6.2 00086 */ 00087 enum IsoNodeType { 00088 LIBISO_DIR, 00089 LIBISO_FILE, 00090 LIBISO_SYMLINK, 00091 LIBISO_SPECIAL, 00092 LIBISO_BOOT 00093 }; 00094 00095 /* macros to check node type */ 00096 #define ISO_NODE_IS_DIR(n) (iso_node_get_type(n) == LIBISO_DIR) 00097 #define ISO_NODE_IS_FILE(n) (iso_node_get_type(n) == LIBISO_FILE) 00098 #define ISO_NODE_IS_SYMLINK(n) (iso_node_get_type(n) == LIBISO_SYMLINK) 00099 #define ISO_NODE_IS_SPECIAL(n) (iso_node_get_type(n) == LIBISO_SPECIAL) 00100 #define ISO_NODE_IS_BOOTCAT(n) (iso_node_get_type(n) == LIBISO_BOOT) 00101 00102 /* macros for safe downcasting */ 00103 #define ISO_DIR(n) ((IsoDir*)(ISO_NODE_IS_DIR(n) ? n : NULL)) 00104 #define ISO_FILE(n) ((IsoFile*)(ISO_NODE_IS_FILE(n) ? n : NULL)) 00105 #define ISO_SYMLINK(n) ((IsoSymlink*)(ISO_NODE_IS_SYMLINK(n) ? n : NULL)) 00106 #define ISO_SPECIAL(n) ((IsoSpecial*)(ISO_NODE_IS_SPECIAL(n) ? n : NULL)) 00107 00108 #define ISO_NODE(n) ((IsoNode*)n) 00109 00110 /** 00111 * Context for iterate on directory children. 00112 * @see iso_dir_get_children() 00113 * 00114 * @since 0.6.2 00115 */ 00116 typedef struct Iso_Dir_Iter IsoDirIter; 00117 00118 /** 00119 * It represents an El-Torito boot image. 00120 * 00121 * @since 0.6.2 00122 */ 00123 typedef struct el_torito_boot_image ElToritoBootImage; 00124 00125 /** 00126 * An special type of IsoNode that acts as a placeholder for an El-Torito 00127 * boot catalog. Once written, it will appear as a regular file. 00128 * 00129 * @since 0.6.2 00130 */ 00131 typedef struct Iso_Boot IsoBoot; 00132 00133 /** 00134 * Flag used to hide a file in the RR/ISO or Joliet tree. 00135 * 00136 * @see iso_node_set_hidden 00137 * @since 0.6.2 00138 */ 00139 enum IsoHideNodeFlag { 00140 /** Hide the node in the ECMA-119 / RR tree */ 00141 LIBISO_HIDE_ON_RR = 1 << 0, 00142 /** Hide the node in the Joliet tree, if Joliet extension are enabled */ 00143 LIBISO_HIDE_ON_JOLIET = 1 << 1, 00144 /** Hide the node in the ISO-9660:1999 tree, if that format is enabled */ 00145 LIBISO_HIDE_ON_1999 = 1 << 2 00146 }; 00147 00148 /** 00149 * El-Torito bootable image type. 00150 * 00151 * @since 0.6.2 00152 */ 00153 enum eltorito_boot_media_type { 00154 ELTORITO_FLOPPY_EMUL, 00155 ELTORITO_HARD_DISC_EMUL, 00156 ELTORITO_NO_EMUL 00157 }; 00158 00159 /** 00160 * Replace mode used when addding a node to a file. 00161 * This controls how libisofs will act when you tried to add to a dir a file 00162 * with the same name that an existing file. 00163 * 00164 * @since 0.6.2 00165 */ 00166 enum iso_replace_mode { 00167 /** 00168 * Never replace an existing node, and instead fail with 00169 * ISO_NODE_NAME_NOT_UNIQUE. 00170 */ 00171 ISO_REPLACE_NEVER, 00172 /** 00173 * Always replace the old node with the new. 00174 */ 00175 ISO_REPLACE_ALWAYS, 00176 /** 00177 * Replace with the new node if it is the same file type 00178 */ 00179 ISO_REPLACE_IF_SAME_TYPE, 00180 /** 00181 * Replace with the new node if it is the same file type and its ctime 00182 * is newer than the old one. 00183 */ 00184 ISO_REPLACE_IF_SAME_TYPE_AND_NEWER, 00185 /** 00186 * Replace with the new node if its ctime is newer than the old one. 00187 */ 00188 ISO_REPLACE_IF_NEWER 00189 /* 00190 * TODO #00006 define more values 00191 * -if both are dirs, add contents (and what to do with conflicts?) 00192 */ 00193 }; 00194 00195 /** 00196 * Options for image written. 00197 * @see iso_write_opts_new() 00198 * @since 0.6.2 00199 */ 00200 typedef struct iso_write_opts IsoWriteOpts; 00201 00202 /** 00203 * Options for image reading or import. 00204 * @see iso_read_opts_new() 00205 * @since 0.6.2 00206 */ 00207 typedef struct iso_read_opts IsoReadOpts; 00208 00209 /** 00210 * Source for image reading. 00211 * 00212 * @see struct iso_data_source 00213 * @since 0.6.2 00214 */ 00215 typedef struct iso_data_source IsoDataSource; 00216 00217 /** 00218 * Data source used by libisofs for reading an existing image. 00219 * 00220 * It offers homogeneous read access to arbitrary blocks to different sources 00221 * for images, such as .iso files, CD/DVD drives, etc... 00222 * 00223 * To create a multisession image, libisofs needs a IsoDataSource, that the 00224 * user must provide. The function iso_data_source_new_from_file() constructs 00225 * an IsoDataSource that uses POSIX I/O functions to access data. You can use 00226 * it with regular .iso images, and also with block devices that represent a 00227 * drive. 00228 * 00229 * @since 0.6.2 00230 */ 00231 struct iso_data_source 00232 { 00233 00234 /* reserved for future usage, set to 0 */ 00235 int version; 00236 00237 /** 00238 * Reference count for the data source. Should be 1 when a new source 00239 * is created. Don't access it directly, but with iso_data_source_ref() 00240 * and iso_data_source_unref() functions. 00241 */ 00242 unsigned int refcount; 00243 00244 /** 00245 * Opens the given source. You must open() the source before any attempt 00246 * to read data from it. The open is the right place for grabbing the 00247 * underlying resources. 00248 * 00249 * @return 00250 * 1 if success, < 0 on error 00251 */ 00252 int (*open)(IsoDataSource *src); 00253 00254 /** 00255 * Close a given source, freeing all system resources previously grabbed in 00256 * open(). 00257 * 00258 * @return 00259 * 1 if success, < 0 on error 00260 */ 00261 int (*close)(IsoDataSource *src); 00262 00263 /** 00264 * Read an arbitrary block (2048 bytes) of data from the source. 00265 * 00266 * @param lba 00267 * Block to be read. 00268 * @param buffer 00269 * Buffer where the data will be written. It should have at least 00270 * 2048 bytes. 00271 * @return 00272 * 1 if success, < 0 on error 00273 */ 00274 int (*read_block)(IsoDataSource *src, uint32_t lba, uint8_t *buffer); 00275 00276 /** 00277 * Clean up the source specific data. Never call this directly, it is 00278 * automatically called by iso_data_source_unref() when refcount reach 00279 * 0. 00280 */ 00281 void (*free_data)(IsoDataSource *); 00282 00283 /** Source specific data */ 00284 void *data; 00285 }; 00286 00287 /** 00288 * Return information for image. This is optionally allocated by libisofs, 00289 * as a way to inform user about the features of an existing image, such as 00290 * extensions present, size, ... 00291 * 00292 * @see iso_image_import() 00293 * @since 0.6.2 00294 */ 00295 typedef struct iso_read_image_features IsoReadImageFeatures; 00296 00297 /** 00298 * POSIX abstraction for source files. 00299 * 00300 * @see struct iso_file_source 00301 * @since 0.6.2 00302 */ 00303 typedef struct iso_file_source IsoFileSource; 00304 00305 /** 00306 * Abstract for source filesystems. 00307 * 00308 * @see struct iso_filesystem 00309 * @since 0.6.2 00310 */ 00311 typedef struct iso_filesystem IsoFilesystem; 00312 00313 /** 00314 * Interface that defines the operations (methods) available for an 00315 * IsoFileSource. 00316 * 00317 * @see struct IsoFileSource_Iface 00318 * @since 0.6.2 00319 */ 00320 typedef struct IsoFileSource_Iface IsoFileSourceIface; 00321 00322 /** 00323 * IsoFilesystem implementation to deal with ISO images, and to offer a way to 00324 * access specific information of the image, such as several volume attributes, 00325 * extensions being used, El-Torito artifacts... 00326 * 00327 * @since 0.6.2 00328 */ 00329 typedef IsoFilesystem IsoImageFilesystem; 00330 00331 /** 00332 * See IsoFilesystem->get_id() for info about this. 00333 * @since 0.6.2 00334 */ 00335 extern unsigned int iso_fs_global_id; 00336 00337 /** 00338 * An IsoFilesystem is a handler for a source of files, or a "filesystem". 00339 * That is defined as a set of files that are organized in a hierarchical 00340 * structure. 00341 * 00342 * A filesystem allows libisofs to access files from several sources in 00343 * an homogeneous way, thus abstracting the underlying operations needed to 00344 * access and read file contents. Note that this doesn't need to be tied 00345 * to the disc filesystem used in the partition being accessed. For example, 00346 * we have an IsoFilesystem implementation to access any mounted filesystem, 00347 * using standard Linux functions. It is also legal, of course, to implement 00348 * an IsoFilesystem to deal with a specific filesystem over raw partitions. 00349 * That is what we do, for example, to access an ISO Image. 00350 * 00351 * Each file inside an IsoFilesystem is represented as an IsoFileSource object, 00352 * that defines POSIX-like interface for accessing files. 00353 * 00354 * @since 0.6.2 00355 */ 00356 struct iso_filesystem 00357 { 00358 /** 00359 * Type of filesystem. 00360 * "file" -> local filesystem 00361 * "iso " -> iso image filesystem 00362 */ 00363 char type[4]; 00364 00365 /* reserved for future usage, set to 0 */ 00366 int version; 00367 00368 /** 00369 * Get the root of a filesystem. 00370 * 00371 * @return 00372 * 1 on success, < 0 on error 00373 */ 00374 int (*get_root)(IsoFilesystem *fs, IsoFileSource **root); 00375 00376 /** 00377 * Retrieve a file from its absolute path inside the filesystem. 00378 * 00379 * @return 00380 * 1 success, < 0 error 00381 * Error codes: 00382 * ISO_FILE_ACCESS_DENIED 00383 * ISO_FILE_BAD_PATH 00384 * ISO_FILE_DOESNT_EXIST 00385 * ISO_OUT_OF_MEM 00386 * ISO_FILE_ERROR 00387 * ISO_NULL_POINTER 00388 */ 00389 int (*get_by_path)(IsoFilesystem *fs, const char *path, 00390 IsoFileSource **file); 00391 00392 /** 00393 * Get filesystem identifier. 00394 * 00395 * If the filesystem is able to generate correct values of the st_dev 00396 * and st_ino fields for the struct stat of each file, this should 00397 * return an unique number, greater than 0. 00398 * 00399 * To get a identifier for your filesystem implementation you should 00400 * use iso_fs_global_id, incrementing it by one each time. 00401 * 00402 * Otherwise, if you can't ensure values in the struct stat are valid, 00403 * this should return 0. 00404 */ 00405 unsigned int (*get_id)(IsoFilesystem *fs); 00406 00407 /** 00408 * Opens the filesystem for several read operations. Calling this funcion 00409 * is not needed at all, each time that the underlying system resource 00410 * needs to be accessed, it is openned propertly. 00411 * However, if you plan to execute several operations on the filesystem, 00412 * it is a good idea to open it previously, to prevent several open/close 00413 * operations to occur. 00414 * 00415 * @return 1 on success, < 0 on error 00416 */ 00417 int (*open)(IsoFilesystem *fs); 00418 00419 /** 00420 * Close the filesystem, thus freeing all system resources. You should 00421 * call this function if you have previously open() it. 00422 * Note that you can open()/close() a filesystem several times. 00423 * 00424 * @return 1 on success, < 0 on error 00425 */ 00426 int (*close)(IsoFilesystem *fs); 00427 00428 /** 00429 * Free implementation specific data. Should never be called by user. 00430 * Use iso_filesystem_unref() instead. 00431 */ 00432 void (*free)(IsoFilesystem *fs); 00433 00434 /* internal usage, do never access them directly */ 00435 unsigned int refcount; 00436 void *data; 00437 }; 00438 00439 /** 00440 * Interface definition for an IsoFileSource. Defines the POSIX-like function 00441 * to access files and abstract underlying source. 00442 * 00443 * @since 0.6.2 00444 */ 00445 struct IsoFileSource_Iface 00446 { 00447 /* reserved for future usage, set to 0 */ 00448 int version; 00449 00450 /** 00451 * Get the path, relative to the filesystem this file source belongs to. 00452 * 00453 * @return 00454 * the path of the FileSource inside the filesystem, it should be 00455 * freed when no more needed. 00456 */ 00457 char* (*get_path)(IsoFileSource *src); 00458 00459 /** 00460 * Get the name of the file, with the dir component of the path. 00461 * 00462 * @return 00463 * the name of the file, it should be freed when no more needed. 00464 */ 00465 char* (*get_name)(IsoFileSource *src); 00466 00467 /** 00468 * Get information about the file. It is equivalent to lstat(2). 00469 * 00470 * @return 00471 * 1 success, < 0 error 00472 * Error codes: 00473 * ISO_FILE_ACCESS_DENIED 00474 * ISO_FILE_BAD_PATH 00475 * ISO_FILE_DOESNT_EXIST 00476 * ISO_OUT_OF_MEM 00477 * ISO_FILE_ERROR 00478 * ISO_NULL_POINTER 00479 */ 00480 int (*lstat)(IsoFileSource *src, struct stat *info); 00481 00482 /** 00483 * Get information about the file. If the file is a symlink, the info 00484 * returned refers to the destination. It is equivalent to stat(2). 00485 * 00486 * @return 00487 * 1 success, < 0 error 00488 * Error codes: 00489 * ISO_FILE_ACCESS_DENIED 00490 * ISO_FILE_BAD_PATH 00491 * ISO_FILE_DOESNT_EXIST 00492 * ISO_OUT_OF_MEM 00493 * ISO_FILE_ERROR 00494 * ISO_NULL_POINTER 00495 */ 00496 int (*stat)(IsoFileSource *src, struct stat *info); 00497 00498 /** 00499 * Check if the process has access to read file contents. Note that this 00500 * is not necessarily related with (l)stat functions. For example, in a 00501 * filesystem implementation to deal with an ISO image, if the user has 00502 * read access to the image it will be able to read all files inside it, 00503 * despite of the particular permission of each file in the RR tree, that 00504 * are what the above functions return. 00505 * 00506 * @return 00507 * 1 if process has read access, < 0 on error 00508 * Error codes: 00509 * ISO_FILE_ACCESS_DENIED 00510 * ISO_FILE_BAD_PATH 00511 * ISO_FILE_DOESNT_EXIST 00512 * ISO_OUT_OF_MEM 00513 * ISO_FILE_ERROR 00514 * ISO_NULL_POINTER 00515 */ 00516 int (*access)(IsoFileSource *src); 00517 00518 /** 00519 * Opens the source. 00520 * @return 1 on success, < 0 on error 00521 * Error codes: 00522 * ISO_FILE_ALREADY_OPENED 00523 * ISO_FILE_ACCESS_DENIED 00524 * ISO_FILE_BAD_PATH 00525 * ISO_FILE_DOESNT_EXIST 00526 * ISO_OUT_OF_MEM 00527 * ISO_FILE_ERROR 00528 * ISO_NULL_POINTER 00529 */ 00530 int (*open)(IsoFileSource *src); 00531 00532 /** 00533 * Close a previuously openned file 00534 * @return 1 on success, < 0 on error 00535 * Error codes: 00536 * ISO_FILE_ERROR 00537 * ISO_NULL_POINTER 00538 * ISO_FILE_NOT_OPENED 00539 */ 00540 int (*close)(IsoFileSource *src); 00541 00542 /** 00543 * Attempts to read up to count bytes from the given source into 00544 * the buffer starting at buf. 00545 * 00546 * The file src must be open() before calling this, and close() when no 00547 * more needed. Not valid for dirs. On symlinks it reads the destination 00548 * file. 00549 * 00550 * @return 00551 * number of bytes read, 0 if EOF, < 0 on error 00552 * Error codes: 00553 * ISO_FILE_ERROR 00554 * ISO_NULL_POINTER 00555 * ISO_FILE_NOT_OPENED 00556 * ISO_WRONG_ARG_VALUE -> if count == 0 00557 * ISO_FILE_IS_DIR 00558 * ISO_OUT_OF_MEM 00559 * ISO_INTERRUPTED 00560 */ 00561 int (*read)(IsoFileSource *src, void *buf, size_t count); 00562 00563 /** 00564 * Read a directory. 00565 * 00566 * Each call to this function will return a new children, until we reach 00567 * the end of file (i.e, no more children), in that case it returns 0. 00568 * 00569 * The dir must be open() before calling this, and close() when no more 00570 * needed. Only valid for dirs. 00571 * 00572 * Note that "." and ".." children MUST NOT BE returned. 00573 * 00574 * @param child 00575 * pointer to be filled with the given child. Undefined on error or OEF 00576 * @return 00577 * 1 on success, 0 if EOF (no more children), < 0 on error 00578 * Error codes: 00579 * ISO_FILE_ERROR 00580 * ISO_NULL_POINTER 00581 * ISO_FILE_NOT_OPENED 00582 * ISO_FILE_IS_NOT_DIR 00583 * ISO_OUT_OF_MEM 00584 */ 00585 int (*readdir)(IsoFileSource *src, IsoFileSource **child); 00586 00587 /** 00588 * Read the destination of a symlink. You don't need to open the file 00589 * to call this. 00590 * 00591 * @param buf 00592 * allocated buffer of at least bufsiz bytes. 00593 * The dest. will be copied there, and it will be NULL-terminated 00594 * @param bufsiz 00595 * characters to be copied. Destination link will be truncated if 00596 * it is larger than given size. This include the \0 character. 00597 * @return 00598 * 1 on success, < 0 on error 00599 * Error codes: 00600 * ISO_FILE_ERROR 00601 * ISO_NULL_POINTER 00602 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 00603 * ISO_FILE_IS_NOT_SYMLINK 00604 * ISO_OUT_OF_MEM 00605 * ISO_FILE_BAD_PATH 00606 * ISO_FILE_DOESNT_EXIST 00607 * 00608 */ 00609 int (*readlink)(IsoFileSource *src, char *buf, size_t bufsiz); 00610 00611 /** 00612 * Get the filesystem for this source. No extra ref is added, so you 00613 * musn't unref the IsoFilesystem. 00614 * 00615 * @return 00616 * The filesystem, NULL on error 00617 */ 00618 IsoFilesystem* (*get_filesystem)(IsoFileSource *src); 00619 00620 /** 00621 * Free implementation specific data. Should never be called by user. 00622 * Use iso_file_source_unref() instead. 00623 */ 00624 void (*free)(IsoFileSource *src); 00625 00626 /** 00627 * Repositions the offset of the IsoFileSource (must be opened) to the 00628 * given offset according to the value of flag. 00629 * 00630 * @param offset 00631 * in bytes 00632 * @param flag 00633 * 0 The offset is set to offset bytes (SEEK_SET) 00634 * 1 The offset is set to its current location plus offset bytes 00635 * (SEEK_CUR) 00636 * 2 The offset is set to the size of the file plus offset bytes 00637 * (SEEK_END). 00638 * @return 00639 * Absolute offset posistion on the file, or < 0 on error. Cast the 00640 * returning value to int to get a valid libisofs error. 00641 * 00642 * @since 0.6.4 00643 */ 00644 off_t (*lseek)(IsoFileSource *src, off_t offset, int flag); 00645 00646 /* 00647 * TODO #00004 Add a get_mime_type() function. 00648 * This can be useful for GUI apps, to choose the icon of the file 00649 */ 00650 }; 00651 00652 /** 00653 * An IsoFile Source is a POSIX abstraction of a file. 00654 * 00655 * @since 0.6.2 00656 */ 00657 struct iso_file_source 00658 { 00659 const IsoFileSourceIface *class; 00660 int refcount; 00661 void *data; 00662 }; 00663 00664 /** 00665 * Representation of file contents. It is an stream of bytes, functionally 00666 * like a pipe. 00667 * 00668 * @since 0.6.4 00669 */ 00670 typedef struct iso_stream IsoStream; 00671 00672 /** 00673 * Interface that defines the operations (methods) available for an 00674 * IsoStream. 00675 * 00676 * @see struct IsoStream_Iface 00677 * @since 0.6.4 00678 */ 00679 typedef struct IsoStream_Iface IsoStreamIface; 00680 00681 /** 00682 * Serial number to be used when you can't get a valid id for a Stream by other 00683 * means. If you use this, both fs_id and dev_id should be set to 0. 00684 * This must be incremented each time you get a reference to it. 00685 * 00686 * @see IsoStreamIface->get_id() 00687 * @since 0.6.4 00688 */ 00689 extern ino_t serial_id; 00690 00691 /** 00692 * Interface definition for IsoStream methods. 00693 * 00694 * @since 0.6.4 00695 */ 00696 struct IsoStream_Iface 00697 { 00698 /* reserved for future usage, set to 0 */ 00699 int version; 00700 00701 /** 00702 * Type of Stream. 00703 * "fsrc" -> Read from file source 00704 * "mem " -> Read from memory 00705 * "boot" -> Boot catalog 00706 * "user" -> User supplied stream 00707 */ 00708 char type[4]; 00709 00710 /** 00711 * Opens the stream. 00712 * 00713 * @return 00714 * 1 on success, 2 file greater than expected, 3 file smaller than 00715 * expected, < 0 on error 00716 */ 00717 int (*open)(IsoStream *stream); 00718 00719 /** 00720 * Close the Stream. 00721 * @return 1 on success, < 0 on error 00722 */ 00723 int (*close)(IsoStream *stream); 00724 00725 /** 00726 * Get the size (in bytes) of the stream. This function should always 00727 * return the same size, even if the underlying source size changes. 00728 */ 00729 off_t (*get_size)(IsoStream *stream); 00730 00731 /** 00732 * Attempts to read up to count bytes from the given stream into 00733 * the buffer starting at buf. 00734 * 00735 * The stream must be open() before calling this, and close() when no 00736 * more needed. 00737 * 00738 * @return 00739 * number of bytes read, 0 if EOF, < 0 on error 00740 */ 00741 int (*read)(IsoStream *stream, void *buf, size_t count); 00742 00743 /** 00744 * Whether this IsoStream can be read several times, with the same results. 00745 * For example, a regular file is repeatable, you can read it as many 00746 * times as you want. However, a pipe isn't. 00747 * 00748 * This function doesn't take into account if the file has been modified 00749 * between the two reads. 00750 * 00751 * @return 00752 * 1 if stream is repeatable, 0 if not, < 0 on error 00753 */ 00754 int (*is_repeatable)(IsoStream *stream); 00755 00756 /** 00757 * Get an unique identifier for the IsoStream. 00758 */ 00759 void (*get_id)(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, 00760 ino_t *ino_id); 00761 00762 /** 00763 * Free implementation specific data. Should never be called by user. 00764 * Use iso_stream_unref() instead. 00765 */ 00766 void (*free)(IsoStream *stream); 00767 }; 00768 00769 /** 00770 * Representation of file contents as a stream of bytes. 00771 * 00772 * @since 0.6.4 00773 */ 00774 struct iso_stream 00775 { 00776 IsoStreamIface *class; 00777 int refcount; 00778 void *data; 00779 }; 00780 00781 /** 00782 * Initialize libisofs. You must call this before any usage of the library. 00783 * @return 1 on success, < 0 on error 00784 * 00785 * @since 0.6.2 00786 */ 00787 int iso_init(); 00788 00789 /** 00790 * Finalize libisofs. 00791 * 00792 * @since 0.6.2 00793 */ 00794 void iso_finish(); 00795 00796 /** 00797 * Create a new image, empty. 00798 * 00799 * The image will be owned by you and should be unref() when no more needed. 00800 * 00801 * @param name 00802 * Name of the image. This will be used as volset_id and volume_id. 00803 * @param image 00804 * Location where the image pointer will be stored. 00805 * @return 00806 * 1 sucess, < 0 error 00807 * 00808 * @since 0.6.2 00809 */ 00810 int iso_image_new(const char *name, IsoImage **image); 00811 00812 00813 /** 00814 * The following two functions three macros are utilities to help ensuring 00815 * version match of application, compile time header, and runtime library. 00816 */ 00817 /** 00818 * Get version of the libisofs library at runtime. 00819 * 00820 * @since 0.6.2 00821 */ 00822 void iso_lib_version(int *major, int *minor, int *micro); 00823 00824 /** 00825 * Check at runtime if the library is ABI compatible with the given version. 00826 * 00827 * @return 00828 * 1 lib is compatible, 0 is not. 00829 * 00830 * @since 0.6.2 00831 */ 00832 int iso_lib_is_compatible(int major, int minor, int micro); 00833 00834 00835 /** 00836 * These three release version numbers tell the revision of this header file 00837 * and of the API it describes. They are memorized by applications at 00838 * compile time. 00839 * They must show the same values as these symbols in ./configure.ac 00840 * LIBISOFS_MAJOR_VERSION=... 00841 * LIBISOFS_MINOR_VERSION=... 00842 * LIBISOFS_MICRO_VERSION=... 00843 * Note to anybody who does own work inside libisofs: 00844 * Any change of configure.ac or libisofs.h has to keep up this equality ! 00845 * 00846 * Before usage of these macros on your code, please read the usage discussion 00847 * below. 00848 * 00849 * @since 0.6.2 00850 */ 00851 #define iso_lib_header_version_major 0 00852 #define iso_lib_header_version_minor 6 00853 #define iso_lib_header_version_micro 6 00854 00855 /** 00856 * Usage discussion: 00857 * 00858 * Some developers of the libburnia project have differing opinions how to 00859 * ensure the compatibility of libaries and applications. 00860 * 00861 * It is about whether to use at compile time and at runtime the version 00862 * numbers provided here. Thomas Schmitt advises to use them. Vreixo Formoso 00863 * advises to use other means. 00864 * 00865 * At compile time: 00866 * 00867 * Vreixo Formoso advises to leave proper version matching to properly 00868 * programmed checks in the the application's build system, which will 00869 * eventually refuse compilation. 00870 * 00871 * Thomas Schmitt advises to use the macros defined here for comparison with 00872 * the application's requirements of library revisions and to eventually 00873 * break compilation. 00874 * 00875 * Both advises are combinable. I.e. be master of your build system and have 00876 * #if checks in the source code of your application, nevertheless. 00877 * 00878 * At runtime (via iso_lib_is_compatible()): 00879 * 00880 * Vreixo Formoso advises to compare the application's requirements of 00881 * library revisions with the runtime library. This is to allow runtime 00882 * libraries which are young enough for the application but too old for 00883 * the lib*.h files seen at compile time. 00884 * 00885 * Thomas Schmitt advises to compare the header revisions defined here with 00886 * the runtime library. This is to enforce a strictly monotonous chain of 00887 * revisions from app to header to library, at the cost of excluding some older 00888 * libraries. 00889 * 00890 * These two advises are mutually exclusive. 00891 */ 00892 00893 00894 /** 00895 * Creates an IsoWriteOpts for writing an image. You should set the options 00896 * desired with the correspondent setters. 00897 * 00898 * Options by default are determined by the selected profile. Fifo size is set 00899 * by default to 2 MB. 00900 * 00901 * @param opts 00902 * Pointer to the location where the newly created IsoWriteOpts will be 00903 * stored. You should free it with iso_write_opts_free() when no more 00904 * needed. 00905 * @param profile 00906 * Default profile for image creation. For now the following values are 00907 * defined: 00908 * ---> 0 [BASIC] 00909 * No extensions are enabled, and ISO level is set to 1. Only suitable 00910 * for usage for very old and limited systems (like MS-DOS), or by a 00911 * start point from which to set your custom options. 00912 * ---> 1 [BACKUP] 00913 * POSIX compatibility for backup. Simple settings, ISO level is set to 00914 * 2 and RR extensions are enabled. Useful for backup purposes. 00915 * ---> 2 [DISTRIBUTION] 00916 * Setting for information distribution. Both RR and Joliet are enabled 00917 * to maximize compatibility with most systems. Permissions are set to 00918 * default values, and timestamps to the time of recording. 00919 * @return 00920 * 1 success, < 0 error 00921 * 00922 * @since 0.6.2 00923 */ 00924 int iso_write_opts_new(IsoWriteOpts **opts, int profile); 00925 00926 /** 00927 * Free an IsoWriteOpts previously allocated with iso_write_opts_new(). 00928 * 00929 * @since 0.6.2 00930 */ 00931 void iso_write_opts_free(IsoWriteOpts *opts); 00932 00933 /** 00934 * Set the ISO-9960 level to write at. 00935 * 00936 * @param level 00937 * -> 1 for higher compatibility with old systems. With this level 00938 * filenames are restricted to 8.3 characters. 00939 * -> 2 to allow up to 31 filename characters. 00940 * @return 00941 * 1 success, < 0 error 00942 * 00943 * @since 0.6.2 00944 */ 00945 int iso_write_opts_set_iso_level(IsoWriteOpts *opts, int level); 00946 00947 /** 00948 * Whether to use or not Rock Ridge extensions. 00949 * 00950 * This are standard extensions to ECMA-119, intended to add POSIX filesystem 00951 * features to ECMA-119 images. Thus, usage of this flag is highly recommended 00952 * for images used on GNU/Linux systems. With the usage of RR extension, the 00953 * resulting image will have long filenames (up to 255 characters), deeper 00954 * directory structure, POSIX permissions and owner info on files and 00955 * directories, support for symbolic links or special files... All that 00956 * attributes can be modified/setted with the appropiate function. 00957 * 00958 * @param enable 00959 * 1 to enable RR extension, 0 to not add them 00960 * @return 00961 * 1 success, < 0 error 00962 * 00963 * @since 0.6.2 00964 */ 00965 int iso_write_opts_set_rockridge(IsoWriteOpts *opts, int enable); 00966 00967 /** 00968 * Whether to add the non-standard Joliet extension to the image. 00969 * 00970 * This extensions are heavily used in Microsoft Windows systems, so if you 00971 * plan to use your disc on such a system you should add this extension. 00972 * Usage of Joliet supplies longer filesystem length (up to 64 unicode 00973 * characters), and deeper directory structure. 00974 * 00975 * @param enable 00976 * 1 to enable Joliet extension, 0 to not add them 00977 * @return 00978 * 1 success, < 0 error 00979 * 00980 * @since 0.6.2 00981 */ 00982 int iso_write_opts_set_joliet(IsoWriteOpts *opts, int enable); 00983 00984 /** 00985 * Whether to use newer ISO-9660:1999 version. 00986 * 00987 * This is the second version of ISO-9660. It allows longer filenames and has 00988 * less restrictions than old ISO-9660. However, nobody is using it so there 00989 * are no much reasons to enable this. 00990 * 00991 * @since 0.6.2 00992 */ 00993 int iso_write_opts_set_iso1999(IsoWriteOpts *opts, int enable); 00994 00995 /** 00996 * Omit the version number (";1") at the end of the ISO-9660 identifiers. 00997 * This breaks ECMA-119 specification, but version numbers are usually not 00998 * used, so it should work on most systems. Use with caution. 00999 * 01000 * @since 0.6.2 01001 */ 01002 int iso_write_opts_set_omit_version_numbers(IsoWriteOpts *opts, int omit); 01003 01004 /** 01005 * Allow ISO-9660 directory hierarchy to be deeper than 8 levels. 01006 * This breaks ECMA-119 specification. Use with caution. 01007 * 01008 * @since 0.6.2 01009 */ 01010 int iso_write_opts_set_allow_deep_paths(IsoWriteOpts *opts, int allow); 01011 01012 /** 01013 * Allow path in the ISO-9660 tree to have more than 255 characters. 01014 * This breaks ECMA-119 specification. Use with caution. 01015 * 01016 * @since 0.6.2 01017 */ 01018 int iso_write_opts_set_allow_longer_paths(IsoWriteOpts *opts, int allow); 01019 01020 /** 01021 * Allow a single file or directory hierarchy to have up to 37 characters. 01022 * This is larger than the 31 characters allowed by ISO level 2, and the 01023 * extra space is taken from the version number, so this also forces 01024 * omit_version_numbers. 01025 * This breaks ECMA-119 specification and could lead to buffer overflow 01026 * problems on old systems. Use with caution. 01027 * 01028 * @since 0.6.2 01029 */ 01030 int iso_write_opts_set_max_37_char_filenames(IsoWriteOpts *opts, int allow); 01031 01032 /** 01033 * ISO-9660 forces filenames to have a ".", that separates file name from 01034 * extension. libisofs adds it if original filename doesn't has one. Set 01035 * this to 1 to prevent this behavior. 01036 * This breaks ECMA-119 specification. Use with caution. 01037 * 01038 * @since 0.6.2 01039 */ 01040 int iso_write_opts_set_no_force_dots(IsoWriteOpts *opts, int no); 01041 01042 /** 01043 * Allow lowercase characters in ISO-9660 filenames. By default, only 01044 * uppercase characters, numbers and a few other characters are allowed. 01045 * This breaks ECMA-119 specification. Use with caution. 01046 * 01047 * @since 0.6.2 01048 */ 01049 int iso_write_opts_set_allow_lowercase(IsoWriteOpts *opts, int allow); 01050 01051 /** 01052 * Allow all ASCII characters to be appear on an ISO-9660 filename. Note 01053 * that "/" and "\0" characters are never allowed, even in RR names. 01054 * This breaks ECMA-119 specification. Use with caution. 01055 * 01056 * @since 0.6.2 01057 */ 01058 int iso_write_opts_set_allow_full_ascii(IsoWriteOpts *opts, int allow); 01059 01060 /** 01061 * Allow all characters to be part of Volume and Volset identifiers on 01062 * the Primary Volume Descriptor. This breaks ISO-9660 contraints, but 01063 * should work on modern systems. 01064 * 01065 * @since 0.6.2 01066 */ 01067 int iso_write_opts_set_relaxed_vol_atts(IsoWriteOpts *opts, int allow); 01068 01069 /** 01070 * Allow paths in the Joliet tree to have more than 240 characters. 01071 * This breaks Joliet specification. Use with caution. 01072 * 01073 * @since 0.6.2 01074 */ 01075 int iso_write_opts_set_joliet_longer_paths(IsoWriteOpts *opts, int allow); 01076 01077 /** 01078 * Whether to sort files based on their weight. 01079 * 01080 * @see iso_node_set_sort_weight 01081 * @since 0.6.2 01082 */ 01083 int iso_write_opts_set_sort_files(IsoWriteOpts *opts, int sort); 01084 01085 /** 01086 * Whether to set default values for files and directory permissions, gid and 01087 * uid. All these take one of three values: 0, 1 or 2. 01088 * 01089 * If 0, the corresponding attribute will be kept as setted in the IsoNode. 01090 * Unless you have changed it, it corresponds to the value on disc, so it 01091 * is suitable for backup purposes. If set to 1, the corresponding attrib. 01092 * will be changed by a default suitable value. Finally, if you set it to 01093 * 2, the attrib. will be changed with the value specified by the functioins 01094 * below. Note that for mode attributes, only the permissions are set, the 01095 * file type remains unchanged. 01096 * 01097 * @see iso_write_opts_set_default_dir_mode 01098 * @see iso_write_opts_set_default_file_mode 01099 * @see iso_write_opts_set_default_uid 01100 * @see iso_write_opts_set_default_gid 01101 * @since 0.6.2 01102 */ 01103 int iso_write_opts_set_replace_mode(IsoWriteOpts *opts, int dir_mode, 01104 int file_mode, int uid, int gid); 01105 01106 /** 01107 * Set the mode to use on dirs when you set the replace_mode of dirs to 2. 01108 * 01109 * @see iso_write_opts_set_replace_mode 01110 * @since 0.6.2 01111 */ 01112 int iso_write_opts_set_default_dir_mode(IsoWriteOpts *opts, mode_t dir_mode); 01113 01114 /** 01115 * Set the mode to use on files when you set the replace_mode of files to 2. 01116 * 01117 * @see iso_write_opts_set_replace_mode 01118 * @since 0.6.2 01119 */ 01120 int iso_write_opts_set_default_file_mode(IsoWriteOpts *opts, mode_t file_mode); 01121 01122 /** 01123 * Set the uid to use when you set the replace_uid to 2. 01124 * 01125 * @see iso_write_opts_set_replace_mode 01126 * @since 0.6.2 01127 */ 01128 int iso_write_opts_set_default_uid(IsoWriteOpts *opts, uid_t uid); 01129 01130 /** 01131 * Set the gid to use when you set the replace_gid to 2. 01132 * 01133 * @see iso_write_opts_set_replace_mode 01134 * @since 0.6.2 01135 */ 01136 int iso_write_opts_set_default_gid(IsoWriteOpts *opts, gid_t gid); 01137 01138 /** 01139 * 0 to use IsoNode timestamps, 1 to use recording time, 2 to use 01140 * values from timestamp field. This has only meaning if RR extensions 01141 * are enabled. 01142 * 01143 * @see iso_write_opts_set_default_timestamp 01144 * @since 0.6.2 01145 */ 01146 int iso_write_opts_set_replace_timestamps(IsoWriteOpts *opts, int replace); 01147 01148 /** 01149 * Set the timestamp to use when you set the replace_timestamps to 2. 01150 * 01151 * @see iso_write_opts_set_replace_timestamps 01152 * @since 0.6.2 01153 */ 01154 int iso_write_opts_set_default_timestamp(IsoWriteOpts *opts, time_t timestamp); 01155 01156 /** 01157 * Whether to always record timestamps in GMT. 01158 * 01159 * By default, libisofs stores local time information on image. You can set 01160 * this to always store timestamps in GMT. This is useful if you want to hide 01161 * your timezone, or you live in a timezone that can't be represented in 01162 * ECMA-119. These are timezones whose offset from GMT is greater than +13 01163 * hours, lower than -12 hours, or not a multiple of 15 minutes. 01164 * 01165 * @since 0.6.2 01166 */ 01167 int iso_write_opts_set_always_gmt(IsoWriteOpts *opts, int gmt); 01168 01169 /** 01170 * Set the charset to use for the RR names of the files that will be created 01171 * on the image. 01172 * NULL to use default charset, that is the locale charset. 01173 * You can obtain the list of charsets supported on your system executing 01174 * "iconv -l" in a shell. 01175 * 01176 * @since 0.6.2 01177 */ 01178 int iso_write_opts_set_output_charset(IsoWriteOpts *opts, const char *charset); 01179 01180 /** 01181 * Set the type of the image to create. Libisofs support two kind of images: 01182 * stand-alone and appendable. 01183 * 01184 * A stand-alone image is an image that is valid alone, and that can be 01185 * mounted by its own. This is the kind of image you will want to create 01186 * in most cases. A stand-alone image can be burned in an empty CD or DVD, 01187 * or write to an .iso file for future burning or distribution. 01188 * 01189 * On the other side, an appendable image is not self contained, it refers 01190 * to serveral files that are stored outside the image. Its usage is for 01191 * multisession discs, where you add data in a new session, while the 01192 * previous session data can still be accessed. In those cases, the old 01193 * data is not written again. Instead, the new image refers to it, and thus 01194 * it's only valid when appended to the original. Note that in those cases 01195 * the image will be written after the original, and thus you will want 01196 * to use a ms_block greater than 0. 01197 * 01198 * Note that if you haven't import a previous image (by means of 01199 * iso_image_import()), the image will always be a stand-alone image, as 01200 * there is no previous data to refer to. 01201 * 01202 * @param appendable 01203 * 1 to create an appendable image, 0 for an stand-alone one. 01204 * 01205 * @since 0.6.2 01206 */ 01207 int iso_write_opts_set_appendable(IsoWriteOpts *opts, int appendable); 01208 01209 /** 01210 * Set the start block of the image. It is supposed to be the lba where the 01211 * first block of the image will be written on disc. All references inside the 01212 * ISO image will take this into account, thus providing a mountable image. 01213 * 01214 * For appendable images, that are written to a new session, you should 01215 * pass here the lba of the next writable address on disc. 01216 * 01217 * In stand alone images this is usually 0. However, you may want to 01218 * provide a different ms_block if you don't plan to burn the image in the 01219 * first session on disc, such as in some CD-Extra disc whether the data 01220 * image is written in a new session after some audio tracks. 01221 * 01222 * @since 0.6.2 01223 */ 01224 int iso_write_opts_set_ms_block(IsoWriteOpts *opts, uint32_t ms_block); 01225 01226 /** 01227 * Sets the buffer where to store the descriptors which shall to be written 01228 * at the beginning of an overwriteable media to point to the newly written 01229 * image. 01230 * This is needed if the write start address of the image is not 0. 01231 * In this case the first 64 KiB of the media have to be overwritten 01232 * by the buffer content after the session was written and the buffer 01233 * was updated by libisofs. Otherwise the new session would not be 01234 * found by operating system function mount() or by libisoburn. 01235 * (One could still mount that session if its start address is known.) 01236 * 01237 * If you do not need this information, for example because you are creating a 01238 * new image for LBA 0 or because you will create an image for a true 01239 * multisession media, just do not use this call or set buffer to NULL. 01240 * 01241 * Use cases: 01242 * 01243 * - Together with iso_write_opts_set_appendable(opts, 1) the buffer serves 01244 * for the growing of an image as done in growisofs by Andy Polyakov. 01245 * This allows appending of a new session to non-multisession media, such 01246 * as DVD+RW. The new session will refer to the data of previous sessions 01247 * on the same media. 01248 * libisoburn emulates multisession appendability on overwriteable media 01249 * and disk files by performing this use case. 01250 * 01251 * - Together with iso_write_opts_set_appendable(opts, 0) the buffer allows 01252 * to write the first session on overwriteable media to start addresses 01253 * other than 0. 01254 * libisoburn in most cases writes the first session on overwriteable media 01255 * and disk files to LBA 32 in order to preserve its descriptors from the 01256 * subsequent overwriting by the descriptor buffer of later sessions. 01257 * 01258 * @param buffer 01259 * When not NULL, it should point to at least 64KiB of memory, where 01260 * libisofs will install the contents that shall be written at the 01261 * beginning of overwriteable media. 01262 * You should initialize the buffer either with 0s, or with the contents 01263 * of the first 32 blocks of the image you are growing. In most cases, 01264 * 0 is good enought. 01265 * 01266 * @since 0.6.2 01267 */ 01268 int iso_write_opts_set_overwrite_buf(IsoWriteOpts *opts, uint8_t *overwrite); 01269 01270 /** 01271 * Set the size, in number of blocks, of the FIFO buffer used between the 01272 * writer thread and the burn_source. You have to provide at least a 32 01273 * blocks buffer. Default value is set to 2MB, if that is ok for you, you 01274 * don't need to call this function. 01275 * 01276 * @since 0.6.2 01277 */ 01278 int iso_write_opts_set_fifo_size(IsoWriteOpts *opts, size_t fifo_size); 01279 01280 /** 01281 * Create a burn_source to actually write the image. That burn_source can be 01282 * used with libburn as a data source for a track. 01283 * 01284 * @param image 01285 * The image to write. 01286 * @param opts 01287 * The options for image generation. All needed data will be copied, so 01288 * you can free the given struct once this function returns. 01289 * @param burn_src 01290 * Location where the pointer to the burn_source will be stored 01291 * @return 01292 * 1 on success, < 0 on error 01293 * 01294 * @since 0.6.2 01295 */ 01296 int iso_image_create_burn_source(IsoImage *image, IsoWriteOpts *opts, 01297 struct burn_source **burn_src); 01298 01299 /** 01300 * Creates an IsoReadOpts for reading an existent image. You should set the 01301 * options desired with the correspondent setters. Note that you may want to 01302 * set the start block value. 01303 * 01304 * Options by default are determined by the selected profile. 01305 * 01306 * @param opts 01307 * Pointer to the location where the newly created IsoReadOpts will be 01308 * stored. You should free it with iso_read_opts_free() when no more 01309 * needed. 01310 * @param profile 01311 * Default profile for image reading. For now the following values are 01312 * defined: 01313 * ---> 0 [STANDARD] 01314 * Suitable for most situations. All extension are read. When both 01315 * Joliet and RR extension are present, RR is used. 01316 * @return 01317 * 1 success, < 0 error 01318 * 01319 * @since 0.6.2 01320 */ 01321 int iso_read_opts_new(IsoReadOpts **opts, int profile); 01322 01323 /** 01324 * Free an IsoReadOpts previously allocated with iso_read_opts_new(). 01325 * 01326 * @since 0.6.2 01327 */ 01328 void iso_read_opts_free(IsoReadOpts *opts); 01329 01330 /** 01331 * Set the block where the image begins. It is usually 0, but may be different 01332 * on a multisession disc. 01333 * 01334 * @since 0.6.2 01335 */ 01336 int iso_read_opts_set_start_block(IsoReadOpts *opts, uint32_t block); 01337 01338 /** 01339 * Do not read Rock Ridge extensions. 01340 * In most cases you don't want to use this. It could be useful if RR info 01341 * is damaged, or if you want to use the Joliet tree. 01342 * 01343 * @since 0.6.2 01344 */ 01345 int iso_read_opts_set_no_rockridge(IsoReadOpts *opts, int norr); 01346 01347 /** 01348 * Do not read Joliet extensions. 01349 * 01350 * @since 0.6.2 01351 */ 01352 int iso_read_opts_set_no_joliet(IsoReadOpts *opts, int nojoliet); 01353 01354 /** 01355 * Do not read ISO 9660:1999 enhanced tree 01356 * 01357 * @since 0.6.2 01358 */ 01359 int iso_read_opts_set_no_iso1999(IsoReadOpts *opts, int noiso1999); 01360 01361 /** 01362 * Whether to prefer Joliet over RR. libisofs usually prefers RR over 01363 * Joliet, as it give us much more info about files. So, if both extensions 01364 * are present, RR is used. You can set this if you prefer Joliet, but 01365 * note that this is not very recommended. This doesn't mean than RR 01366 * extensions are not read: if no Joliet is present, libisofs will read 01367 * RR tree. 01368 * 01369 * @since 0.6.2 01370 */ 01371 int iso_read_opts_set_preferjoliet(IsoReadOpts *opts, int preferjoliet); 01372 01373 /** 01374 * Set default uid for files when RR extensions are not present. 01375 * 01376 * @since 0.6.2 01377 */ 01378 int iso_read_opts_set_default_uid(IsoReadOpts *opts, uid_t uid); 01379 01380 /** 01381 * Set default gid for files when RR extensions are not present. 01382 * 01383 * @since 0.6.2 01384 */ 01385 int iso_read_opts_set_default_gid(IsoReadOpts *opts, gid_t gid); 01386 01387 /** 01388 * Set default permissions for files when RR extensions are not present. 01389 * 01390 * @param file_perm 01391 * Permissions for files. 01392 * @param dir_perm 01393 * Permissions for directories. 01394 * 01395 * @since 0.6.2 01396 */ 01397 int iso_read_opts_set_default_permissions(IsoReadOpts *opts, mode_t file_perm, 01398 mode_t dir_perm); 01399 01400 /** 01401 * Set the input charset of the file names on the image. NULL to use locale 01402 * charset. You have to specify a charset if the image filenames are encoded 01403 * in a charset different that the local one. This could happen, for example, 01404 * if the image was created on a system with different charset. 01405 * 01406 * @param charset 01407 * The charset to use as input charset. You can obtain the list of 01408 * charsets supported on your system executing "iconv -l" in a shell. 01409 * 01410 * @since 0.6.2 01411 */ 01412 int iso_read_opts_set_input_charset(IsoReadOpts *opts, const char *charset); 01413 01414 /** 01415 * Import a previous session or image, for growing or modify. 01416 * 01417 * @param image 01418 * The image context to which old image will be imported. Note that all 01419 * files added to image, and image attributes, will be replaced with the 01420 * contents of the old image. 01421 * TODO #00025 support for merging old image files 01422 * @param src 01423 * Data Source from which old image will be read. A extra reference is 01424 * added, so you still need to iso_data_source_unref() yours. 01425 * @param opts 01426 * Options for image import. All needed data will be copied, so you 01427 * can free the given struct once this function returns. 01428 * @param features 01429 * If not NULL, a new IsoReadImageFeatures will be allocated and filled 01430 * with the features of the old image. It should be freed with 01431 * iso_read_image_features_destroy() when no more needed. You can pass 01432 * NULL if you're not interested on them. 01433 * @return 01434 * 1 on success, < 0 on error 01435 * 01436 * @since 0.6.2 01437 */ 01438 int iso_image_import(IsoImage *image, IsoDataSource *src, IsoReadOpts *opts, 01439 IsoReadImageFeatures **features); 01440 01441 /** 01442 * Destroy an IsoReadImageFeatures object obtained with iso_image_import. 01443 * 01444 * @since 0.6.2 01445 */ 01446 void iso_read_image_features_destroy(IsoReadImageFeatures *f); 01447 01448 /** 01449 * Get the size (in 2048 byte block) of the image, as reported in the PVM. 01450 * 01451 * @since 0.6.2 01452 */ 01453 uint32_t iso_read_image_features_get_size(IsoReadImageFeatures *f); 01454 01455 /** 01456 * Whether RockRidge extensions are present in the image imported. 01457 * 01458 * @since 0.6.2 01459 */ 01460 int iso_read_image_features_has_rockridge(IsoReadImageFeatures *f); 01461 01462 /** 01463 * Whether Joliet extensions are present in the image imported. 01464 * 01465 * @since 0.6.2 01466 */ 01467 int iso_read_image_features_has_joliet(IsoReadImageFeatures *f); 01468 01469 /** 01470 * Whether the image is recorded according to ISO 9660:1999, i.e. it has 01471 * a version 2 Enhanced Volume Descriptor. 01472 * 01473 * @since 0.6.2 01474 */ 01475 int iso_read_image_features_has_iso1999(IsoReadImageFeatures *f); 01476 01477 /** 01478 * Whether El-Torito boot record is present present in the image imported. 01479 * 01480 * @since 0.6.2 01481 */ 01482 int iso_read_image_features_has_eltorito(IsoReadImageFeatures *f); 01483 01484 /** 01485 * Increments the reference counting of the given image. 01486 * 01487 * @since 0.6.2 01488 */ 01489 void iso_image_ref(IsoImage *image); 01490 01491 /** 01492 * Decrements the reference couting of the given image. 01493 * If it reaches 0, the image is free, together with its tree nodes (whether 01494 * their refcount reach 0 too, of course). 01495 * 01496 * @since 0.6.2 01497 */ 01498 void iso_image_unref(IsoImage *image); 01499 01500 /** 01501 * Attach user defined data to the image. Use this if your application needs 01502 * to store addition info together with the IsoImage. If the image already 01503 * has data attached, the old data will be freed. 01504 * 01505 * @param data 01506 * Pointer to application defined data that will be attached to the 01507 * image. You can pass NULL to remove any already attached data. 01508 * @param give_up 01509 * Function that will be called when the image does not need the data 01510 * any more. It receives the data pointer as an argumente, and eventually 01511 * causes data to be freed. It can be NULL if you don't need it. 01512 * @return 01513 * 1 on succes, < 0 on error 01514 * 01515 * @since 0.6.2 01516 */ 01517 int iso_image_attach_data(IsoImage *image, void *data, void (*give_up)(void*)); 01518 01519 /** 01520 * The the data previously attached with iso_image_attach_data() 01521 * 01522 * @since 0.6.2 01523 */ 01524 void *iso_image_get_attached_data(IsoImage *image); 01525 01526 /** 01527 * Get the root directory of the image. 01528 * No extra ref is added to it, so you musn't unref it. Use iso_node_ref() 01529 * if you want to get your own reference. 01530 * 01531 * @since 0.6.2 01532 */ 01533 IsoDir *iso_image_get_root(const IsoImage *image); 01534 01535 /** 01536 * Fill in the volset identifier for a image. 01537 * 01538 * @since 0.6.2 01539 */ 01540 void iso_image_set_volset_id(IsoImage *image, const char *volset_id); 01541 01542 /** 01543 * Get the volset identifier. 01544 * The returned string is owned by the image and should not be freed nor 01545 * changed. 01546 * 01547 * @since 0.6.2 01548 */ 01549 const char *iso_image_get_volset_id(const IsoImage *image); 01550 01551 /** 01552 * Fill in the volume identifier for a image. 01553 * 01554 * @since 0.6.2 01555 */ 01556 void iso_image_set_volume_id(IsoImage *image, const char *volume_id); 01557 01558 /** 01559 * Get the volume identifier. 01560 * The returned string is owned by the image and should not be freed nor 01561 * changed. 01562 * 01563 * @since 0.6.2 01564 */ 01565 const char *iso_image_get_volume_id(const IsoImage *image); 01566 01567 /** 01568 * Fill in the publisher for a image. 01569 * 01570 * @since 0.6.2 01571 */ 01572 void iso_image_set_publisher_id(IsoImage *image, const char *publisher_id); 01573 01574 /** 01575 * Get the publisher of a image. 01576 * The returned string is owned by the image and should not be freed nor 01577 * changed. 01578 * 01579 * @since 0.6.2 01580 */ 01581 const char *iso_image_get_publisher_id(const IsoImage *image); 01582 01583 /** 01584 * Fill in the data preparer for a image. 01585 * 01586 * @since 0.6.2 01587 */ 01588 void iso_image_set_data_preparer_id(IsoImage *image, 01589 const char *data_preparer_id); 01590 01591 /** 01592 * Get the data preparer of a image. 01593 * The returned string is owned by the image and should not be freed nor 01594 * changed. 01595 * 01596 * @since 0.6.2 01597 */ 01598 const char *iso_image_get_data_preparer_id(const IsoImage *image); 01599 01600 /** 01601 * Fill in the system id for a image. Up to 32 characters. 01602 * 01603 * @since 0.6.2 01604 */ 01605 void iso_image_set_system_id(IsoImage *image, const char *system_id); 01606 01607 /** 01608 * Get the system id of a image. 01609 * The returned string is owned by the image and should not be freed nor 01610 * changed. 01611 * 01612 * @since 0.6.2 01613 */ 01614 const char *iso_image_get_system_id(const IsoImage *image); 01615 01616 /** 01617 * Fill in the application id for a image. Up to 128 chars. 01618 * 01619 * @since 0.6.2 01620 */ 01621 void iso_image_set_application_id(IsoImage *image, const char *application_id); 01622 01623 /** 01624 * Get the application id of a image. 01625 * The returned string is owned by the image and should not be freed nor 01626 * changed. 01627 * 01628 * @since 0.6.2 01629 */ 01630 const char *iso_image_get_application_id(const IsoImage *image); 01631 01632 /** 01633 * Fill copyright information for the image. Usually this refers 01634 * to a file on disc. Up to 37 characters. 01635 * 01636 * @since 0.6.2 01637 */ 01638 void iso_image_set_copyright_file_id(IsoImage *image, 01639 const char *copyright_file_id); 01640 01641 /** 01642 * Get the copyright information of a image. 01643 * The returned string is owned by the image and should not be freed nor 01644 * changed. 01645 * 01646 * @since 0.6.2 01647 */ 01648 const char *iso_image_get_copyright_file_id(const IsoImage *image); 01649 01650 /** 01651 * Fill abstract information for the image. Usually this refers 01652 * to a file on disc. Up to 37 characters. 01653 * 01654 * @since 0.6.2 01655 */ 01656 void iso_image_set_abstract_file_id(IsoImage *image, 01657 const char *abstract_file_id); 01658 01659 /** 01660 * Get the abstract information of a image. 01661 * The returned string is owned by the image and should not be freed nor 01662 * changed. 01663 * 01664 * @since 0.6.2 01665 */ 01666 const char *iso_image_get_abstract_file_id(const IsoImage *image); 01667 01668 /** 01669 * Fill biblio information for the image. Usually this refers 01670 * to a file on disc. Up to 37 characters. 01671 * 01672 * @since 0.6.2 01673 */ 01674 void iso_image_set_biblio_file_id(IsoImage *image, const char *biblio_file_id); 01675 01676 /** 01677 * Get the biblio information of a image. 01678 * The returned string is owned by the image and should not be freed nor 01679 * changed. 01680 * 01681 * @since 0.6.2 01682 */ 01683 const char *iso_image_get_biblio_file_id(const IsoImage *image); 01684 01685 /** 01686 * Create a bootable image by adding a El-Torito boot image. 01687 * 01688 * This also add a catalog boot node to the image filesystem tree. 01689 * 01690 * @param image 01691 * The image to make bootable. If it was already bootable this function 01692 * returns an error and the image remains unmodified. 01693 * @param image_path 01694 * The path on the image tree of a regular file to use as default boot 01695 * image. 01696 * @param type 01697 * The boot media type. This can be one of 3 types: 01698 * - Floppy emulation: Boot image file must be exactly 01699 * 1200 kB, 1440 kB or 2880 kB. 01700 * - Hard disc emulation: The image must begin with a master 01701 * boot record with a single image. 01702 * - No emulation. You should specify load segment and load size 01703 * of image. 01704 * @param catalog_path 01705 * The path on the image tree where the catalog will be stored. The 01706 * directory component of this path must be a directory existent on the 01707 * image tree, and the filename component must be unique among all 01708 * children of that directory on image. Otherwise a correspodent error 01709 * code will be returned. This function will add an IsoBoot node that acts 01710 * as a placeholder for the real catalog, that will be generated at image 01711 * creation time. 01712 * @param boot 01713 * Location where a pointer to the added boot image will be stored. That 01714 * object is owned by the IsoImage and should not be freed by the user, 01715 * nor dereferenced once the last reference to the IsoImage was disposed 01716 * via iso_image_unref(). A NULL value is allowed if you don't need a 01717 * reference to the boot image. 01718 * @return 01719 * 1 on success, < 0 on error 01720 * 01721 * @since 0.6.2 01722 */ 01723 int iso_image_set_boot_image(IsoImage *image, const char *image_path, 01724 enum eltorito_boot_media_type type, 01725 const char *catalog_path, 01726 ElToritoBootImage **boot); 01727 01728 /* TODO #00026 : add support for "hidden" bootable images. */ 01729 01730 /** 01731 * Get El-Torito boot image of an ISO image, if any. 01732 * 01733 * This can be useful, for example, to check if a volume read from a previous 01734 * session or an existing image is bootable. It can also be useful to get 01735 * the image and catalog tree nodes. An application would want those, for 01736 * example, to prevent the user removing it. 01737 * 01738 * Both nodes are owned by libisofs and should not be freed. You can get your 01739 * own ref with iso_node_ref(). You can can also check if the node is already 01740 * on the tree by getting its parent (note that when reading El-Torito info 01741 * from a previous image, the nodes might not be on the tree even if you haven't 01742 * removed them). Remember that you'll need to get a new ref 01743 * (with iso_node_ref()) before inserting them again to the tree, and probably 01744 * you will also need to set the name or permissions. 01745 * 01746 * @param image 01747 * The image from which to get the boot image. 01748 * @param boot 01749 * If not NULL, it will be filled with a pointer to the boot image, if 01750 * any. That object is owned by the IsoImage and should not be freed by 01751 * the user, nor dereferenced once the last reference to the IsoImage was 01752 * disposed via iso_image_unref(). 01753 * @param imgnode 01754 * When not NULL, it will be filled with the image tree node. No extra ref 01755 * is added, you can use iso_node_ref() to get one if you need it. 01756 * @param catnode 01757 * When not NULL, it will be filled with the catnode tree node. No extra 01758 * ref is added, you can use iso_node_ref() to get one if you need it. 01759 * @return 01760 * 1 on success, 0 is the image is not bootable (i.e., it has no El-Torito 01761 * image), < 0 error. 01762 * 01763 * @since 0.6.2 01764 */ 01765 int iso_image_get_boot_image(IsoImage *image, ElToritoBootImage **boot, 01766 IsoFile **imgnode, IsoBoot **catnode); 01767 01768 /** 01769 * Removes the El-Torito bootable image. 01770 * 01771 * The IsoBoot node that acts as placeholder for the catalog is also removed 01772 * for the image tree, if there. 01773 * If the image is not bootable (don't have el-torito boot image) this function 01774 * just returns. 01775 * 01776 * @since 0.6.2 01777 */ 01778 void iso_image_remove_boot_image(IsoImage *image); 01779 01780 /** 01781 * Sets the load segment for the initial boot image. This is only for 01782 * no emulation boot images, and is a NOP for other image types. 01783 * 01784 * @since 0.6.2 01785 */ 01786 void el_torito_set_load_seg(ElToritoBootImage *bootimg, short segment); 01787 01788 /** 01789 * Sets the number of sectors (512b) to be load at load segment during 01790 * the initial boot procedure. This is only for 01791 * no emulation boot images, and is a NOP for other image types. 01792 * 01793 * @since 0.6.2 01794 */ 01795 void el_torito_set_load_size(ElToritoBootImage *bootimg, short sectors); 01796 01797 /** 01798 * Marks the specified boot image as not bootable 01799 * 01800 * @since 0.6.2 01801 */ 01802 void el_torito_set_no_bootable(ElToritoBootImage *bootimg); 01803 01804 /** 01805 * Specifies that this image needs to be patched. This involves the writting 01806 * of a 56 bytes boot information table at offset 8 of the boot image file. 01807 * The original boot image file won't be modified. 01808 * This is needed for isolinux boot images. 01809 * 01810 * @since 0.6.2 01811 */ 01812 void el_torito_patch_isolinux_image(ElToritoBootImage *bootimg); 01813 01814 /** 01815 * Increments the reference counting of the given node. 01816 * 01817 * @since 0.6.2 01818 */ 01819 void iso_node_ref(IsoNode *node); 01820 01821 /** 01822 * Decrements the reference couting of the given node. 01823 * If it reach 0, the node is free, and, if the node is a directory, 01824 * its children will be unref() too. 01825 * 01826 * @since 0.6.2 01827 */ 01828 void iso_node_unref(IsoNode *node); 01829 01830 /** 01831 * Get the type of an IsoNode. 01832 * 01833 * @since 0.6.2 01834 */ 01835 enum IsoNodeType iso_node_get_type(IsoNode *node); 01836 01837 /** 01838 * Function to handle particular extended information. The function 01839 * pointer acts as an identifier for the type of the information. Structs 01840 * with same information type must use the same function. 01841 * 01842 * @param data 01843 * Attached data 01844 * @param flag 01845 * What to do with the data. At this time the following values are 01846 * defined: 01847 * -> 1 the data must be freed 01848 * @return 01849 * 1 in any case. 01850 * 01851 * @since 0.6.4 01852 */ 01853 typedef int (*iso_node_xinfo_func)(void *data, int flag); 01854 01855 /** 01856 * Add extended information to the given node. Extended info allows 01857 * applications (and libisofs itself) to add more information to an IsoNode. 01858 * You can use this facilities to associate new information with a given 01859 * node. 01860 * 01861 * Each node keeps a list of added extended info, meaning you can add several 01862 * extended info data to each node. Each extended info you add is identified 01863 * by the proc parameter, a pointer to a function that knows how to manage 01864 * the external info data. Thus, in order to add several types of extended 01865 * info, you need to define a "proc" function for each type. 01866 * 01867 * @param node 01868 * The node where to add the extended info 01869 * @param proc 01870 * A function pointer used to identify the type of the data, and that 01871 * knows how to manage it 01872 * @param data 01873 * Extended info to add. 01874 * @return 01875 * 1 if success, 0 if the given node already has extended info of the 01876 * type defined by the "proc" function, < 0 on error 01877 * 01878 * @since 0.6.4 01879 */ 01880 int iso_node_add_xinfo(IsoNode *node, iso_node_xinfo_func proc, void *data); 01881 01882 /** 01883 * Remove the given extended info (defined by the proc function) from the 01884 * given node. 01885 * 01886 * @return 01887 * 1 on success, 0 if node does not have extended info of the requested 01888 * type, < 0 on error 01889 * 01890 * @since 0.6.4 01891 */ 01892 int iso_node_remove_xinfo(IsoNode *node, iso_node_xinfo_func proc); 01893 01894 /** 01895 * Get the given extended info (defined by the proc function) from the 01896 * given node. 01897 * 01898 * @param data 01899 * Will be filled with the extended info corresponding to the given proc 01900 * function 01901 * @return 01902 * 1 on success, 0 if node does not have extended info of the requested 01903 * type, < 0 on error 01904 * 01905 * @since 0.6.4 01906 */ 01907 int iso_node_get_xinfo(IsoNode *node, iso_node_xinfo_func proc, void **data); 01908 01909 /** 01910 * Set the name of a node. Note that if the node is already added to a dir 01911 * this can fail if dir already contains a node with the new name. 01912 * 01913 * @param node 01914 * The node whose name you want to change. Note that you can't change 01915 * the name of the root. 01916 * @param name 01917 * The name for the node. If you supply an empty string or a 01918 * name greater than 255 characters this returns with failure, and 01919 * node name is not modified. 01920 * @return 01921 * 1 on success, < 0 on error 01922 * 01923 * @since 0.6.2 01924 */ 01925 int iso_node_set_name(IsoNode *node, const char *name); 01926 01927 /** 01928 * Get the name of a node. 01929 * The returned string belongs to the node and should not be modified nor 01930 * freed. Use strdup if you really need your own copy. 01931 * 01932 * @since 0.6.2 01933 */ 01934 const char *iso_node_get_name(const IsoNode *node); 01935 01936 /** 01937 * Set the permissions for the node. This attribute is only useful when 01938 * Rock Ridge extensions are enabled. 01939 * 01940 * @param mode 01941 * bitmask with the permissions of the node, as specified in 'man 2 stat'. 01942 * The file type bitfields will be ignored, only file permissions will be 01943 * modified. 01944 * 01945 * @since 0.6.2 01946 */ 01947 void iso_node_set_permissions(IsoNode *node, mode_t mode); 01948 01949 /** 01950 * Get the permissions for the node 01951 * 01952 * @since 0.6.2 01953 */ 01954 mode_t iso_node_get_permissions(const IsoNode *node); 01955 01956 /** 01957 * Get the mode of the node, both permissions and file type, as specified in 01958 * 'man 2 stat'. 01959 * 01960 * @since 0.6.2 01961 */ 01962 mode_t iso_node_get_mode(const IsoNode *node); 01963 01964 /** 01965 * Set the user id for the node. This attribute is only useful when 01966 * Rock Ridge extensions are enabled. 01967 * 01968 * @since 0.6.2 01969 */ 01970 void iso_node_set_uid(IsoNode *node, uid_t uid); 01971 01972 /** 01973 * Get the user id of the node. 01974 * 01975 * @since 0.6.2 01976 */ 01977 uid_t iso_node_get_uid(const IsoNode *node); 01978 01979 /** 01980 * Set the group id for the node. This attribute is only useful when 01981 * Rock Ridge extensions are enabled. 01982 * 01983 * @since 0.6.2 01984 */ 01985 void iso_node_set_gid(IsoNode *node, gid_t gid); 01986 01987 /** 01988 * Get the group id of the node. 01989 * 01990 * @since 0.6.2 01991 */ 01992 gid_t iso_node_get_gid(const IsoNode *node); 01993 01994 /** 01995 * Set the time of last modification of the file 01996 * 01997 * @since 0.6.2 01998 */ 01999 void iso_node_set_mtime(IsoNode *node, time_t time); 02000 02001 /** 02002 * Get the time of last modification of the file 02003 * 02004 * @since 0.6.2 02005 */ 02006 time_t iso_node_get_mtime(const IsoNode *node); 02007 02008 /** 02009 * Set the time of last access to the file 02010 * 02011 * @since 0.6.2 02012 */ 02013 void iso_node_set_atime(IsoNode *node, time_t time); 02014 02015 /** 02016 * Get the time of last access to the file 02017 * 02018 * @since 0.6.2 02019 */ 02020 time_t iso_node_get_atime(const IsoNode *node); 02021 02022 /** 02023 * Set the time of last status change of the file 02024 * 02025 * @since 0.6.2 02026 */ 02027 void iso_node_set_ctime(IsoNode *node, time_t time); 02028 02029 /** 02030 * Get the time of last status change of the file 02031 * 02032 * @since 0.6.2 02033 */ 02034 time_t iso_node_get_ctime(const IsoNode *node); 02035 02036 /** 02037 * Set if the node will be hidden in RR/ISO tree, Joliet tree or both. 02038 * 02039 * If the file is setted as hidden in one tree, it won't be included there, so 02040 * it won't be visible in a OS accessing CD using that tree. For example, 02041 * GNU/Linux systems access to Rock Ridge / ISO9960 tree in order to see 02042 * what is recorded on CD, while MS Windows make use of the Joliet tree. If a 02043 * file is hidden only in Joliet, it won't be visible in Windows systems, 02044 * while still visible in Linux. 02045 * 02046 * If a file is hidden in both trees, it won't be written to image. 02047 * 02048 * @param node 02049 * The node that is to be hidden. 02050 * @param hide_attrs 02051 * IsoHideNodeFlag's to set the trees in which file will be hidden. 02052 * 02053 * @since 0.6.2 02054 */ 02055 void iso_node_set_hidden(IsoNode *node, int hide_attrs); 02056 02057 /** 02058 * Add a new node to a dir. Note that this function don't add a new ref to 02059 * the node, so you don't need to free it, it will be automatically freed 02060 * when the dir is deleted. Of course, if you want to keep using the node 02061 * after the dir life, you need to iso_node_ref() it. 02062 * 02063 * @param dir 02064 * the dir where to add the node 02065 * @param child 02066 * the node to add. You must ensure that the node hasn't previously added 02067 * to other dir, and that the node name is unique inside the child. 02068 * Otherwise this function will return a failure, and the child won't be 02069 * inserted. 02070 * @param replace 02071 * if the dir already contains a node with the same name, whether to 02072 * replace or not the old node with this. 02073 * @return 02074 * number of nodes in dir if succes, < 0 otherwise 02075 * Possible errors: 02076 * ISO_NULL_POINTER, if dir or child are NULL 02077 * ISO_NODE_ALREADY_ADDED, if child is already added to other dir 02078 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02079 * ISO_WRONG_ARG_VALUE, if child == dir, or replace != (0,1) 02080 * 02081 * @since 0.6.2 02082 */ 02083 int iso_dir_add_node(IsoDir *dir, IsoNode *child, 02084 enum iso_replace_mode replace); 02085 02086 /** 02087 * Locate a node inside a given dir. 02088 * 02089 * @param dir 02090 * The dir where to look for the node. 02091 * @param name 02092 * The name of the node 02093 * @param node 02094 * Location for a pointer to the node, it will filled with NULL if the dir 02095 * doesn't have a child with the given name. 02096 * The node will be owned by the dir and shouldn't be unref(). Just call 02097 * iso_node_ref() to get your own reference to the node. 02098 * Note that you can pass NULL is the only thing you want to do is check 02099 * if a node with such name already exists on dir. 02100 * @return 02101 * 1 node found, 0 child has no such node, < 0 error 02102 * Possible errors: 02103 * ISO_NULL_POINTER, if dir or name are NULL 02104 * 02105 * @since 0.6.2 02106 */ 02107 int iso_dir_get_node(IsoDir *dir, const char *name, IsoNode **node); 02108 02109 /** 02110 * Get the number of children of a directory. 02111 * 02112 * @return 02113 * >= 0 number of items, < 0 error 02114 * Possible errors: 02115 * ISO_NULL_POINTER, if dir is NULL 02116 * 02117 * @since 0.6.2 02118 */ 02119 int iso_dir_get_children_count(IsoDir *dir); 02120 02121 /** 02122 * Removes a child from a directory. 02123 * The child is not freed, so you will become the owner of the node. Later 02124 * you can add the node to another dir (calling iso_dir_add_node), or free 02125 * it if you don't need it (with iso_node_unref). 02126 * 02127 * @return 02128 * 1 on success, < 0 error 02129 * Possible errors: 02130 * ISO_NULL_POINTER, if node is NULL 02131 * ISO_NODE_NOT_ADDED_TO_DIR, if node doesn't belong to a dir 02132 * 02133 * @since 0.6.2 02134 */ 02135 int iso_node_take(IsoNode *node); 02136 02137 /** 02138 * Removes a child from a directory and free (unref) it. 02139 * If you want to keep the child alive, you need to iso_node_ref() it 02140 * before this call, but in that case iso_node_take() is a better 02141 * alternative. 02142 * 02143 * @return 02144 * 1 on success, < 0 error 02145 * 02146 * @since 0.6.2 02147 */ 02148 int iso_node_remove(IsoNode *node); 02149 02150 /* 02151 * Get the parent of the given iso tree node. No extra ref is added to the 02152 * returned directory, you must take your ref. with iso_node_ref() if you 02153 * need it. 02154 * 02155 * If node is the root node, the same node will be returned as its parent. 02156 * 02157 * This returns NULL if the node doesn't pertain to any tree 02158 * (it was removed/take). 02159 * 02160 * @since 0.6.2 02161 */ 02162 IsoDir *iso_node_get_parent(IsoNode *node); 02163 02164 /** 02165 * Get an iterator for the children of the given dir. 02166 * 02167 * You can iterate over the children with iso_dir_iter_next. When finished, 02168 * you should free the iterator with iso_dir_iter_free. 02169 * You musn't delete a child of the same dir, using iso_node_take() or 02170 * iso_node_remove(), while you're using the iterator. You can use 02171 * iso_dir_iter_take() or iso_dir_iter_remove() instead. 02172 * 02173 * You can use the iterator in the way like this 02174 * 02175 * IsoDirIter *iter; 02176 * IsoNode *node; 02177 * if ( iso_dir_get_children(dir, &iter) != 1 ) { 02178 * // handle error 02179 * } 02180 * while ( iso_dir_iter_next(iter, &node) == 1 ) { 02181 * // do something with the child 02182 * } 02183 * iso_dir_iter_free(iter); 02184 * 02185 * An iterator is intended to be used in a single iteration over the 02186 * children of a dir. Thus, it should be treated as a temporary object, 02187 * and free as soon as possible. 02188 * 02189 * @return 02190 * 1 success, < 0 error 02191 * Possible errors: 02192 * ISO_NULL_POINTER, if dir or iter are NULL 02193 * ISO_OUT_OF_MEM 02194 * 02195 * @since 0.6.2 02196 */ 02197 int iso_dir_get_children(const IsoDir *dir, IsoDirIter **iter); 02198 02199 /** 02200 * Get the next child. 02201 * Take care that the node is owned by its parent, and will be unref() when 02202 * the parent is freed. If you want your own ref to it, call iso_node_ref() 02203 * on it. 02204 * 02205 * @return 02206 * 1 success, 0 if dir has no more elements, < 0 error 02207 * Possible errors: 02208 * ISO_NULL_POINTER, if node or iter are NULL 02209 * ISO_ERROR, on wrong iter usage, usual caused by modiying the 02210 * dir during iteration 02211 * 02212 * @since 0.6.2 02213 */ 02214 int iso_dir_iter_next(IsoDirIter *iter, IsoNode **node); 02215 02216 /** 02217 * Check if there're more children. 02218 * 02219 * @return 02220 * 1 dir has more elements, 0 no, < 0 error 02221 * Possible errors: 02222 * ISO_NULL_POINTER, if iter is NULL 02223 * 02224 * @since 0.6.2 02225 */ 02226 int iso_dir_iter_has_next(IsoDirIter *iter); 02227 02228 /** 02229 * Free a dir iterator. 02230 * 02231 * @since 0.6.2 02232 */ 02233 void iso_dir_iter_free(IsoDirIter *iter); 02234 02235 /** 02236 * Removes a child from a directory during an iteration, without freeing it. 02237 * It's like iso_node_take(), but to be used during a directory iteration. 02238 * The node removed will be the last returned by the iteration. 02239 * 02240 * If you call this function twice without calling iso_dir_iter_next between 02241 * them is not allowed and you will get an ISO_ERROR in second call. 02242 * 02243 * @return 02244 * 1 on succes, < 0 error 02245 * Possible errors: 02246 * ISO_NULL_POINTER, if iter is NULL 02247 * ISO_ERROR, on wrong iter usage, for example by call this before 02248 * iso_dir_iter_next. 02249 * 02250 * @since 0.6.2 02251 */ 02252 int iso_dir_iter_take(IsoDirIter *iter); 02253 02254 /** 02255 * Removes a child from a directory during an iteration and unref() it. 02256 * It's like iso_node_remove(), but to be used during a directory iteration. 02257 * The node removed will be the last returned by the iteration. 02258 * 02259 * If you call this function twice without calling iso_dir_iter_next between 02260 * them is not allowed and you will get an ISO_ERROR in second call. 02261 * 02262 * @return 02263 * 1 on succes, < 0 error 02264 * Possible errors: 02265 * ISO_NULL_POINTER, if iter is NULL 02266 * ISO_ERROR, on wrong iter usage, for example by call this before 02267 * iso_dir_iter_next. 02268 * 02269 * @since 0.6.2 02270 */ 02271 int iso_dir_iter_remove(IsoDirIter *iter); 02272 02273 02274 /** 02275 * @since 0.6.4 02276 */ 02277 typedef struct iso_find_condition IsoFindCondition; 02278 02279 /** 02280 * Create a new condition that checks if the node name matches the given 02281 * wildcard. 02282 * 02283 * @param wildcard 02284 * @result 02285 * The created IsoFindCondition, NULL on error. 02286 * 02287 * @since 0.6.4 02288 */ 02289 IsoFindCondition *iso_new_find_conditions_name(const char *wildcard); 02290 02291 /** 02292 * Create a new condition that checks the node mode against a mode mask. It 02293 * can be used to check both file type and permissions. 02294 * 02295 * For example: 02296 * 02297 * iso_new_find_conditions_mode(S_IFREG) : search for regular files 02298 * iso_new_find_conditions_mode(S_IFCHR | S_IWUSR) : search for character 02299 * devices where owner has write permissions. 02300 * 02301 * @param mask 02302 * Mode mask to AND against node mode. 02303 * @result 02304 * The created IsoFindCondition, NULL on error. 02305 * 02306 * @since 0.6.4 02307 */ 02308 IsoFindCondition *iso_new_find_conditions_mode(mode_t mask); 02309 02310 /** 02311 * Create a new condition that checks the node gid. 02312 * 02313 * @param gid 02314 * Desired Group Id. 02315 * @result 02316 * The created IsoFindCondition, NULL on error. 02317 * 02318 * @since 0.6.4 02319 */ 02320 IsoFindCondition *iso_new_find_conditions_gid(gid_t gid); 02321 02322 /** 02323 * Create a new condition that checks the node uid. 02324 * 02325 * @param uid 02326 * Desired User Id. 02327 * @result 02328 * The created IsoFindCondition, NULL on error. 02329 * 02330 * @since 0.6.4 02331 */ 02332 IsoFindCondition *iso_new_find_conditions_uid(uid_t uid); 02333 02334 /** 02335 * Possible comparison between IsoNode and given conditions. 02336 * 02337 * @since 0.6.4 02338 */ 02339 enum iso_find_comparisons { 02340 ISO_FIND_COND_GREATER, 02341 ISO_FIND_COND_GREATER_OR_EQUAL, 02342 ISO_FIND_COND_EQUAL, 02343 ISO_FIND_COND_LESS, 02344 ISO_FIND_COND_LESS_OR_EQUAL 02345 }; 02346 02347 /** 02348 * Create a new condition that checks the time of last access. 02349 * 02350 * @param time 02351 * Time to compare against IsoNode atime. 02352 * @param comparison 02353 * Comparison to be done between IsoNode atime and submitted time. 02354 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02355 * time is greater than the submitted time. 02356 * @result 02357 * The created IsoFindCondition, NULL on error. 02358 * 02359 * @since 0.6.4 02360 */ 02361 IsoFindCondition *iso_new_find_conditions_atime(time_t time, 02362 enum iso_find_comparisons comparison); 02363 02364 /** 02365 * Create a new condition that checks the time of last modification. 02366 * 02367 * @param time 02368 * Time to compare against IsoNode mtime. 02369 * @param comparison 02370 * Comparison to be done between IsoNode mtime and submitted time. 02371 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02372 * time is greater than the submitted time. 02373 * @result 02374 * The created IsoFindCondition, NULL on error. 02375 * 02376 * @since 0.6.4 02377 */ 02378 IsoFindCondition *iso_new_find_conditions_mtime(time_t time, 02379 enum iso_find_comparisons comparison); 02380 02381 /** 02382 * Create a new condition that checks the time of last status change. 02383 * 02384 * @param time 02385 * Time to compare against IsoNode ctime. 02386 * @param comparison 02387 * Comparison to be done between IsoNode ctime and submitted time. 02388 * Note that ISO_FIND_COND_GREATER, for example, is true if the node 02389 * time is greater than the submitted time. 02390 * @result 02391 * The created IsoFindCondition, NULL on error. 02392 * 02393 * @since 0.6.4 02394 */ 02395 IsoFindCondition *iso_new_find_conditions_ctime(time_t time, 02396 enum iso_find_comparisons comparison); 02397 02398 /** 02399 * Create a new condition that check if the two given conditions are 02400 * valid. 02401 * 02402 * @param a 02403 * @param b 02404 * IsoFindCondition to compare 02405 * @result 02406 * The created IsoFindCondition, NULL on error. 02407 * 02408 * @since 0.6.4 02409 */ 02410 IsoFindCondition *iso_new_find_conditions_and(IsoFindCondition *a, 02411 IsoFindCondition *b); 02412 02413 /** 02414 * Create a new condition that check if at least one the two given conditions 02415 * is valid. 02416 * 02417 * @param a 02418 * @param b 02419 * IsoFindCondition to compare 02420 * @result 02421 * The created IsoFindCondition, NULL on error. 02422 * 02423 * @since 0.6.4 02424 */ 02425 IsoFindCondition *iso_new_find_conditions_or(IsoFindCondition *a, 02426 IsoFindCondition *b); 02427 02428 /** 02429 * Create a new condition that check if the given conditions is false. 02430 * 02431 * @param negate 02432 * @result 02433 * The created IsoFindCondition, NULL on error. 02434 * 02435 * @since 0.6.4 02436 */ 02437 IsoFindCondition *iso_new_find_conditions_not(IsoFindCondition *negate); 02438 02439 /** 02440 * Find all directory children that match the given condition. 02441 * 02442 * @param dir 02443 * Directory where we will search children. 02444 * @param cond 02445 * Condition that the children must match in order to be returned. 02446 * It will be free together with the iterator. Remember to delete it 02447 * if this function return error. 02448 * @param iter 02449 * Iterator that returns only the children that match condition. 02450 * @return 02451 * 1 on success, < 0 on error 02452 * 02453 * @since 0.6.4 02454 */ 02455 int iso_dir_find_children(IsoDir* dir, IsoFindCondition *cond, 02456 IsoDirIter **iter); 02457 02458 /** 02459 * Get the destination of a node. 02460 * The returned string belongs to the node and should not be modified nor 02461 * freed. Use strdup if you really need your own copy. 02462 * 02463 * @since 0.6.2 02464 */ 02465 const char *iso_symlink_get_dest(const IsoSymlink *link); 02466 02467 /** 02468 * Set the destination of a link. 02469 * 02470 * @param dest 02471 * New destination for the link. It must be a non-empty string, otherwise 02472 * this function doesn't modify previous destination. 02473 * @return 02474 * 1 on success, < 0 on error 02475 * 02476 * @since 0.6.2 02477 */ 02478 int iso_symlink_set_dest(IsoSymlink *link, const char *dest); 02479 02480 /** 02481 * Sets the order in which a node will be written on image. High weihted files 02482 * will be written first, so in a disc them will be written near the center. 02483 * 02484 * @param node 02485 * The node which weight will be changed. If it's a dir, this function 02486 * will change the weight of all its children. For nodes other that dirs 02487 * or regular files, this function has no effect. 02488 * @param w 02489 * The weight as a integer number, the greater this value is, the 02490 * closer from the begining of image the file will be written. 02491 * 02492 * @since 0.6.2 02493 */ 02494 void iso_node_set_sort_weight(IsoNode *node, int w); 02495 02496 /** 02497 * Get the sort weight of a file. 02498 * 02499 * @since 0.6.2 02500 */ 02501 int iso_file_get_sort_weight(IsoFile *file); 02502 02503 /** 02504 * Get the size of the file, in bytes 02505 * 02506 * @since 0.6.2 02507 */ 02508 off_t iso_file_get_size(IsoFile *file); 02509 02510 /** 02511 * Get the device id (major/minor numbers) of the given block or 02512 * character device file. The result is undefined for other kind 02513 * of special files, of first be sure iso_node_get_mode() returns either 02514 * S_IFBLK or S_IFCHR. 02515 * 02516 * @since 0.6.6 02517 */ 02518 dev_t iso_special_get_dev(IsoSpecial *special); 02519 02520 /** 02521 * Get the IsoStream that represents the contents of the given IsoFile. 02522 * 02523 * If you open() the stream, it should be close() before image generation. 02524 * 02525 * @return 02526 * The IsoStream. No extra ref is added, so the IsoStream belong to the 02527 * IsoFile, and it may be freed together with it. Add your own ref with 02528 * iso_stream_ref() if you need it. 02529 * 02530 * @since 0.6.4 02531 */ 02532 IsoStream *iso_file_get_stream(IsoFile *file); 02533 02534 /** 02535 * Get the block lba of a file node, if it was imported from an old image. 02536 * 02537 * @param file 02538 * The file 02539 * @param lba 02540 * Will be filled with the kba 02541 * @param flag 02542 * Reserved for future usage, submit 0 02543 * @return 02544 * 1 if lba is valid (file comes from old image), 0 if file was newly 02545 * added, i.e. it does not come from an old image, < 0 error 02546 * 02547 * @since 0.6.4 02548 */ 02549 int iso_file_get_old_image_lba(IsoFile *file, uint32_t *lba, int flag); 02550 02551 /* 02552 * Like iso_file_get_old_image_lba(), but take an IsoNode. 02553 * 02554 * @return 02555 * 1 if lba is valid (file comes from old image), 0 if file was newly 02556 * added, i.e. it does not come from an old image, 2 node type has no 02557 * LBA (no regular file), < 0 error 02558 * 02559 * @since 0.6.4 02560 */ 02561 int iso_node_get_old_image_lba(IsoNode *node, uint32_t *lba, int flag); 02562 02563 /** 02564 * Add a new directory to the iso tree. Permissions, owner and hidden atts 02565 * are taken from parent, you can modify them later. 02566 * 02567 * @param parent 02568 * the dir where the new directory will be created 02569 * @param name 02570 * name for the new dir. If a node with same name already exists on 02571 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02572 * @param dir 02573 * place where to store a pointer to the newly created dir. No extra 02574 * ref is addded, so you will need to call iso_node_ref() if you really 02575 * need it. You can pass NULL in this parameter if you don't need the 02576 * pointer. 02577 * @return 02578 * number of nodes in parent if success, < 0 otherwise 02579 * Possible errors: 02580 * ISO_NULL_POINTER, if parent or name are NULL 02581 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02582 * ISO_OUT_OF_MEM 02583 * 02584 * @since 0.6.2 02585 */ 02586 int iso_tree_add_new_dir(IsoDir *parent, const char *name, IsoDir **dir); 02587 02588 /** 02589 * Add a new regular file to the iso tree. Permissions are set to 0444, 02590 * owner and hidden atts are taken from parent. You can modify any of them 02591 * later. 02592 * 02593 * @param parent 02594 * the dir where the new file will be created 02595 * @param name 02596 * name for the new file. If a node with same name already exists on 02597 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02598 * @param stream 02599 * IsoStream for the contents of the file. The reference will be taken 02600 * by the newly created file, you will need to take an extra ref to it 02601 * if you need it. 02602 * @param file 02603 * place where to store a pointer to the newly created file. No extra 02604 * ref is addded, so you will need to call iso_node_ref() if you really 02605 * need it. You can pass NULL in this parameter if you don't need the 02606 * pointer 02607 * @return 02608 * number of nodes in parent if success, < 0 otherwise 02609 * Possible errors: 02610 * ISO_NULL_POINTER, if parent, name or dest are NULL 02611 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02612 * ISO_OUT_OF_MEM 02613 * 02614 * @since 0.6.4 02615 */ 02616 int iso_tree_add_new_file(IsoDir *parent, const char *name, IsoStream *stream, 02617 IsoFile **file); 02618 02619 /** 02620 * Add a new symlink to the directory tree. Permissions are set to 0777, 02621 * owner and hidden atts are taken from parent. You can modify any of them 02622 * later. 02623 * 02624 * @param parent 02625 * the dir where the new symlink will be created 02626 * @param name 02627 * name for the new symlink. If a node with same name already exists on 02628 * parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02629 * @param dest 02630 * destination of the link 02631 * @param link 02632 * place where to store a pointer to the newly created link. No extra 02633 * ref is addded, so you will need to call iso_node_ref() if you really 02634 * need it. You can pass NULL in this parameter if you don't need the 02635 * pointer 02636 * @return 02637 * number of nodes in parent if success, < 0 otherwise 02638 * Possible errors: 02639 * ISO_NULL_POINTER, if parent, name or dest are NULL 02640 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02641 * ISO_OUT_OF_MEM 02642 * 02643 * @since 0.6.2 02644 */ 02645 int iso_tree_add_new_symlink(IsoDir *parent, const char *name, 02646 const char *dest, IsoSymlink **link); 02647 02648 /** 02649 * Add a new special file to the directory tree. As far as libisofs concerns, 02650 * an special file is a block device, a character device, a FIFO (named pipe) 02651 * or a socket. You can choose the specific kind of file you want to add 02652 * by setting mode propertly (see man 2 stat). 02653 * 02654 * Note that special files are only written to image when Rock Ridge 02655 * extensions are enabled. Moreover, a special file is just a directory entry 02656 * in the image tree, no data is written beyond that. 02657 * 02658 * Owner and hidden atts are taken from parent. You can modify any of them 02659 * later. 02660 * 02661 * @param parent 02662 * the dir where the new special file will be created 02663 * @param name 02664 * name for the new special file. If a node with same name already exists 02665 * on parent, this functions fails with ISO_NODE_NAME_NOT_UNIQUE. 02666 * @param mode 02667 * file type and permissions for the new node. Note that you can't 02668 * specify any kind of file here, only special types are allowed. i.e, 02669 * S_IFSOCK, S_IFBLK, S_IFCHR and S_IFIFO are valid types; S_IFLNK, 02670 * S_IFREG and S_IFDIR aren't. 02671 * @param dev 02672 * device ID, equivalent to the st_rdev field in man 2 stat. 02673 * @param special 02674 * place where to store a pointer to the newly created special file. No 02675 * extra ref is addded, so you will need to call iso_node_ref() if you 02676 * really need it. You can pass NULL in this parameter if you don't need 02677 * the pointer. 02678 * @return 02679 * number of nodes in parent if success, < 0 otherwise 02680 * Possible errors: 02681 * ISO_NULL_POINTER, if parent, name or dest are NULL 02682 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02683 * ISO_WRONG_ARG_VALUE if you select a incorrect mode 02684 * ISO_OUT_OF_MEM 02685 * 02686 * @since 0.6.2 02687 */ 02688 int iso_tree_add_new_special(IsoDir *parent, const char *name, mode_t mode, 02689 dev_t dev, IsoSpecial **special); 02690 02691 /** 02692 * Set whether to follow or not symbolic links when added a file from a source 02693 * to IsoImage. Default behavior is to not follow symlinks. 02694 * 02695 * @since 0.6.2 02696 */ 02697 void iso_tree_set_follow_symlinks(IsoImage *image, int follow); 02698 02699 /** 02700 * Get current setting for follow_symlinks. 02701 * 02702 * @see iso_tree_set_follow_symlinks 02703 * @since 0.6.2 02704 */ 02705 int iso_tree_get_follow_symlinks(IsoImage *image); 02706 02707 /** 02708 * Set whether to skip or not hidden files when adding a directory recursibely. 02709 * Default behavior is to not ignore them, i.e., to add hidden files to image. 02710 * 02711 * @since 0.6.2 02712 */ 02713 void iso_tree_set_ignore_hidden(IsoImage *image, int skip); 02714 02715 /** 02716 * Get current setting for ignore_hidden. 02717 * 02718 * @see iso_tree_set_ignore_hidden 02719 * @since 0.6.2 02720 */ 02721 int iso_tree_get_ignore_hidden(IsoImage *image); 02722 02723 /** 02724 * Set the replace mode, that defines the behavior of libisofs when adding 02725 * a node whit the same name that an existent one, during a recursive 02726 * directory addition. 02727 * 02728 * @since 0.6.2 02729 */ 02730 void iso_tree_set_replace_mode(IsoImage *image, enum iso_replace_mode mode); 02731 02732 /** 02733 * Get current setting for replace_mode. 02734 * 02735 * @see iso_tree_set_replace_mode 02736 * @since 0.6.2 02737 */ 02738 enum iso_replace_mode iso_tree_get_replace_mode(IsoImage *image); 02739 02740 /** 02741 * Set whether to skip or not special files. Default behavior is to not skip 02742 * them. Note that, despite of this setting, special files won't never be added 02743 * to an image unless RR extensions were enabled. 02744 * 02745 * @param skip 02746 * Bitmask to determine what kind of special files will be skipped: 02747 * bit0: ignore FIFOs 02748 * bit1: ignore Sockets 02749 * bit2: ignore char devices 02750 * bit3: ignore block devices 02751 * 02752 * @since 0.6.2 02753 */ 02754 void iso_tree_set_ignore_special(IsoImage *image, int skip); 02755 02756 /** 02757 * Get current setting for ignore_special. 02758 * 02759 * @see iso_tree_set_ignore_special 02760 * @since 0.6.2 02761 */ 02762 int iso_tree_get_ignore_special(IsoImage *image); 02763 02764 /** 02765 * Add a excluded path. These are paths that won't never added to image, 02766 * and will be excluded even when adding recursively its parent directory. 02767 * 02768 * For example, in 02769 * 02770 * iso_tree_add_exclude(image, "/home/user/data/private"); 02771 * iso_tree_add_dir_rec(image, root, "/home/user/data"); 02772 * 02773 * the directory /home/user/data/private won't be added to image. 02774 * 02775 * However, if you explicity add a deeper dir, it won't be excluded. i.e., 02776 * in the following example. 02777 * 02778 * iso_tree_add_exclude(image, "/home/user/data"); 02779 * iso_tree_add_dir_rec(image, root, "/home/user/data/private"); 02780 * 02781 * the directory /home/user/data/private is added. On the other, side, and 02782 * foollowing the the example above, 02783 * 02784 * iso_tree_add_dir_rec(image, root, "/home/user"); 02785 * 02786 * will exclude the directory "/home/user/data". 02787 * 02788 * Absolute paths are not mandatory, you can, for example, add a relative 02789 * path such as: 02790 * 02791 * iso_tree_add_exclude(image, "private"); 02792 * iso_tree_add_exclude(image, "user/data"); 02793 * 02794 * to excluve, respectively, all files or dirs named private, and also all 02795 * files or dirs named data that belong to a folder named "user". Not that the 02796 * above rule about deeper dirs is still valid. i.e., if you call 02797 * 02798 * iso_tree_add_dir_rec(image, root, "/home/user/data/music"); 02799 * 02800 * it is included even containing "user/data" string. However, a possible 02801 * "/home/user/data/music/user/data" is not added. 02802 * 02803 * Usual wildcards, such as * or ? are also supported, with the usual meaning 02804 * as stated in "man 7 glob". For example 02805 * 02806 * // to exclude backup text files 02807 * iso_tree_add_exclude(image, "*.~"); 02808 * 02809 * @return 02810 * 1 on success, < 0 on error 02811 * 02812 * @since 0.6.2 02813 */ 02814 int iso_tree_add_exclude(IsoImage *image, const char *path); 02815 02816 /** 02817 * Remove a previously added exclude. 02818 * 02819 * @see iso_tree_add_exclude 02820 * @return 02821 * 1 on success, 0 exclude do not exists, < 0 on error 02822 * 02823 * @since 0.6.2 02824 */ 02825 int iso_tree_remove_exclude(IsoImage *image, const char *path); 02826 02827 /** 02828 * Set a callback function that libisofs will call for each file that is 02829 * added to the given image by a recursive addition function. This includes 02830 * image import. 02831 * 02832 * @param report 02833 * pointer to a function that will be called just before a file will be 02834 * added to the image. You can control whether the file will be in fact 02835 * added or ignored. 02836 * This function should return 1 to add the file, 0 to ignore it and 02837 * continue, < 0 to abort the process 02838 * NULL is allowed if you don't want any callback. 02839 * 02840 * @since 0.6.2 02841 */ 02842 void iso_tree_set_report_callback(IsoImage *image, 02843 int (*report)(IsoImage*, IsoFileSource*)); 02844 02845 /** 02846 * Add a new node to the image tree, from an existing file. 02847 * 02848 * TODO comment Builder and Filesystem related issues when exposing both 02849 * 02850 * All attributes will be taken from the source file. The appropriate file 02851 * type will be created. 02852 * 02853 * @param image 02854 * The image 02855 * @param parent 02856 * The directory in the image tree where the node will be added. 02857 * @param path 02858 * The path of the file to add in the filesystem. 02859 * @param node 02860 * place where to store a pointer to the newly added file. No 02861 * extra ref is addded, so you will need to call iso_node_ref() if you 02862 * really need it. You can pass NULL in this parameter if you don't need 02863 * the pointer. 02864 * @return 02865 * number of nodes in parent if success, < 0 otherwise 02866 * Possible errors: 02867 * ISO_NULL_POINTER, if image, parent or path are NULL 02868 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02869 * ISO_OUT_OF_MEM 02870 * 02871 * @since 0.6.2 02872 */ 02873 int iso_tree_add_node(IsoImage *image, IsoDir *parent, const char *path, 02874 IsoNode **node); 02875 02876 /** 02877 * Add a new node to the image tree, from an existing file, and with the 02878 * given name, that must not exist on dir. 02879 * 02880 * @param image 02881 * The image 02882 * @param parent 02883 * The directory in the image tree where the node will be added. 02884 * @param name 02885 * The name that the node will have on image. 02886 * @param path 02887 * The path of the file to add in the filesystem. 02888 * @param node 02889 * place where to store a pointer to the newly added file. No 02890 * extra ref is addded, so you will need to call iso_node_ref() if you 02891 * really need it. You can pass NULL in this parameter if you don't need 02892 * the pointer. 02893 * @return 02894 * number of nodes in parent if success, < 0 otherwise 02895 * Possible errors: 02896 * ISO_NULL_POINTER, if image, parent or path are NULL 02897 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02898 * ISO_OUT_OF_MEM 02899 * 02900 * @since 0.6.4 02901 */ 02902 int iso_tree_add_new_node(IsoImage *image, IsoDir *parent, const char *name, 02903 const char *path, IsoNode **node); 02904 02905 /** 02906 * Add a new node to the image tree, from an existing file, and with the 02907 * given name, that must not exist on dir. The node will be cut-out to the 02908 * submitted size, and its contents will be read from the given offset. This 02909 * function is thus suitable for adding only a piece of a file to the image. 02910 * 02911 * @param image 02912 * The image 02913 * @param parent 02914 * The directory in the image tree where the node will be added. 02915 * @param name 02916 * The name that the node will have on image. 02917 * @param path 02918 * The path of the file to add in the filesystem. For now only regular 02919 * files and symlinks to regular files are supported. 02920 * @param offset 02921 * Offset on the given file from where to start reading data. 02922 * @param size 02923 * Max size of the file. 02924 * @param node 02925 * place where to store a pointer to the newly added file. No 02926 * extra ref is addded, so you will need to call iso_node_ref() if you 02927 * really need it. You can pass NULL in this parameter if you don't need 02928 * the pointer. 02929 * @return 02930 * number of nodes in parent if success, < 0 otherwise 02931 * Possible errors: 02932 * ISO_NULL_POINTER, if image, parent or path are NULL 02933 * ISO_NODE_NAME_NOT_UNIQUE, a node with same name already exists 02934 * ISO_OUT_OF_MEM 02935 * 02936 * @since 0.6.4 02937 */ 02938 int iso_tree_add_new_cut_out_node(IsoImage *image, IsoDir *parent, 02939 const char *name, const char *path, 02940 off_t offset, off_t size, 02941 IsoNode **node); 02942 02943 /** 02944 * Add the contents of a dir to a given directory of the iso tree. 02945 * 02946 * There are several options to control what files are added or how they are 02947 * managed. Take a look at iso_tree_set_* functions to see diferent options 02948 * for recursive directory addition. 02949 * 02950 * TODO comment Builder and Filesystem related issues when exposing both 02951 * 02952 * @param image 02953 * The image to which the directory belong. 02954 * @param parent 02955 * Directory on the image tree where to add the contents of the dir 02956 * @param dir 02957 * Path to a dir in the filesystem 02958 * @return 02959 * number of nodes in parent if success, < 0 otherwise 02960 * 02961 * @since 0.6.2 02962 */ 02963 int iso_tree_add_dir_rec(IsoImage *image, IsoDir *parent, const char *dir); 02964 02965 /** 02966 * Locate a node by its path on image. 02967 * 02968 * @param node 02969 * Location for a pointer to the node, it will filled with NULL if the 02970 * given path does not exists on image. 02971 * The node will be owned by the image and shouldn't be unref(). Just call 02972 * iso_node_ref() to get your own reference to the node. 02973 * Note that you can pass NULL is the only thing you want to do is check 02974 * if a node with such path really exists. 02975 * @return 02976 * 1 found, 0 not found, < 0 error 02977 * 02978 * @since 0.6.2 02979 */ 02980 int iso_tree_path_to_node(IsoImage *image, const char *path, IsoNode **node); 02981 02982 /** 02983 * Get the path on image of the given node. 02984 * 02985 * @return 02986 * The path on the image, that must be freed when no more needed. If the 02987 * given node is not added to any image, this returns NULL. 02988 * @since 0.6.4 02989 */ 02990 char *iso_tree_get_node_path(IsoNode *node); 02991 02992 /** 02993 * Increments the reference counting of the given IsoDataSource. 02994 * 02995 * @since 0.6.2 02996 */ 02997 void iso_data_source_ref(IsoDataSource *src); 02998 02999 /** 03000 * Decrements the reference counting of the given IsoDataSource, freeing it 03001 * if refcount reach 0. 03002 * 03003 * @since 0.6.2 03004 */ 03005 void iso_data_source_unref(IsoDataSource *src); 03006 03007 /** 03008 * Create a new IsoDataSource from a local file. This is suitable for 03009 * accessing regular .iso images, or to acces drives via its block device 03010 * and standard POSIX I/O calls. 03011 * 03012 * @param path 03013 * The path of the file 03014 * @param src 03015 * Will be filled with the pointer to the newly created data source. 03016 * @return 03017 * 1 on success, < 0 on error. 03018 * 03019 * @since 0.6.2 03020 */ 03021 int iso_data_source_new_from_file(const char *path, IsoDataSource **src); 03022 03023 /** 03024 * Get the status of the buffer used by a burn_source. 03025 * 03026 * @param b 03027 * A burn_source previously obtained with 03028 * iso_image_create_burn_source(). 03029 * @param size 03030 * Will be filled with the total size of the buffer, in bytes 03031 * @param free_bytes 03032 * Will be filled with the bytes currently available in buffer 03033 * @return 03034 * < 0 error, > 0 state: 03035 * 1="active" : input and consumption are active 03036 * 2="ending" : input has ended without error 03037 * 3="failing" : input had error and ended, 03038 * 5="abandoned" : consumption has ended prematurely 03039 * 6="ended" : consumption has ended without input error 03040 * 7="aborted" : consumption has ended after input error 03041 * 03042 * @since 0.6.2 03043 */ 03044 int iso_ring_buffer_get_status(struct burn_source *b, size_t *size, 03045 size_t *free_bytes); 03046 03047 #define ISO_MSGS_MESSAGE_LEN 4096 03048 03049 /** 03050 * Control queueing and stderr printing of messages from libisofs. 03051 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 03052 * "NOTE", "UPDATE", "DEBUG", "ALL". 03053 * 03054 * @param queue_severity Gives the minimum limit for messages to be queued. 03055 * Default: "NEVER". If you queue messages then you 03056 * must consume them by iso_msgs_obtain(). 03057 * @param print_severity Does the same for messages to be printed directly 03058 * to stderr. 03059 * @param print_id A text prefix to be printed before the message. 03060 * @return >0 for success, <=0 for error 03061 * 03062 * @since 0.6.2 03063 */ 03064 int iso_set_msgs_severities(char *queue_severity, char *print_severity, 03065 char *print_id); 03066 03067 /** 03068 * Obtain the oldest pending libisofs message from the queue which has at 03069 * least the given minimum_severity. This message and any older message of 03070 * lower severity will get discarded from the queue and is then lost forever. 03071 * 03072 * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT", 03073 * "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER" 03074 * will discard the whole queue. 03075 * 03076 * @param error_code 03077 * Will become a unique error code as listed at the end of this header 03078 * @param imgid 03079 * Id of the image that was issued the message. 03080 * @param msg_text 03081 * Must provide at least ISO_MSGS_MESSAGE_LEN bytes. 03082 * @param severity 03083 * Will become the severity related to the message and should provide at 03084 * least 80 bytes. 03085 * @return 03086 * 1 if a matching item was found, 0 if not, <0 for severe errors 03087 * 03088 * @since 0.6.2 03089 */ 03090 int iso_obtain_msgs(char *minimum_severity, int *error_code, int *imgid, 03091 char msg_text[], char severity[]); 03092 03093 03094 /** 03095 * Submit a message to the libisofs queueing system. It will be queued or 03096 * printed as if it was generated by libisofs itself. 03097 * 03098 * @param error_code 03099 * The unique error code of your message. 03100 * Submit 0 if you do not have reserved error codes within the libburnia 03101 * project. 03102 * @param msg_text 03103 * Not more than ISO_MSGS_MESSAGE_LEN characters of message text. 03104 * @param os_errno 03105 * Eventual errno related to the message. Submit 0 if the message is not 03106 * related to a operating system error. 03107 * @param severity 03108 * One of "ABORT", "FATAL", "FAILURE", "SORRY", "WARNING", "HINT", "NOTE", 03109 * "UPDATE", "DEBUG". Defaults to "FATAL". 03110 * @param origin 03111 * Submit 0 for now. 03112 * @return 03113 * 1 if message was delivered, <=0 if failure 03114 * 03115 * @since 0.6.4 03116 */ 03117 int iso_msgs_submit(int error_code, char msg_text[], int os_errno, 03118 char severity[], int origin); 03119 03120 03121 /** 03122 * Convert a severity name into a severity number, which gives the severity 03123 * rank of the name. 03124 * 03125 * @param severity_name 03126 * A name as with iso_msgs_submit(), e.g. "SORRY". 03127 * @param severity_number 03128 * The rank number: the higher, the more severe. 03129 * @return 03130 * >0 success, <=0 failure 03131 * 03132 * @since 0.6.4 03133 */ 03134 int iso_text_to_sev(char *severity_name, int *severity_number); 03135 03136 03137 /** 03138 * Convert a severity number into a severity name 03139 * 03140 * @param severity_number 03141 * The rank number: the higher, the more severe. 03142 * @param severity_name 03143 * A name as with iso_msgs_submit(), e.g. "SORRY". 03144 * 03145 * @since 0.6.4 03146 */ 03147 int iso_sev_to_text(int severity_number, char **severity_name); 03148 03149 03150 /** 03151 * Get the id of an IsoImage, used for message reporting. This message id, 03152 * retrieved with iso_obtain_msgs(), can be used to distinguish what 03153 * IsoImage has isssued a given message. 03154 * 03155 * @since 0.6.2 03156 */ 03157 int iso_image_get_msg_id(IsoImage *image); 03158 03159 /** 03160 * Get a textual description of a libisofs error. 03161 * 03162 * @since 0.6.2 03163 */ 03164 const char *iso_error_to_msg(int errcode); 03165 03166 /** 03167 * Get the severity of a given error code 03168 * @return 03169 * 0x10000000 -> DEBUG 03170 * 0x20000000 -> UPDATE 03171 * 0x30000000 -> NOTE 03172 * 0x40000000 -> HINT 03173 * 0x50000000 -> WARNING 03174 * 0x60000000 -> SORRY 03175 * 0x64000000 -> MISHAP 03176 * 0x68000000 -> FAILURE 03177 * 0x70000000 -> FATAL 03178 * 0x71000000 -> ABORT 03179 * 03180 * @since 0.6.2 03181 */ 03182 int iso_error_get_severity(int e); 03183 03184 /** 03185 * Get the priority of a given error. 03186 * @return 03187 * 0x00000000 -> ZERO 03188 * 0x10000000 -> LOW 03189 * 0x20000000 -> MEDIUM 03190 * 0x30000000 -> HIGH 03191 * 03192 * @since 0.6.2 03193 */ 03194 int iso_error_get_priority(int e); 03195 03196 /** 03197 * Get the message queue code of a libisofs error. 03198 */ 03199 int iso_error_get_code(int e); 03200 03201 /** 03202 * Set the minimum error severity that causes a libisofs operation to 03203 * be aborted as soon as possible. 03204 * 03205 * @param severity 03206 * one of "FAILURE", "MISHAP", "SORRY", "WARNING", "HINT", "NOTE". 03207 * Severities greater or equal than FAILURE always cause program to abort. 03208 * Severities under NOTE won't never cause function abort. 03209 * @return 03210 * Previous abort priority on success, < 0 on error. 03211 * 03212 * @since 0.6.2 03213 */ 03214 int iso_set_abort_severity(char *severity); 03215 03216 /** 03217 * Return the messenger object handle used by libisofs. This handle 03218 * may be used by related libraries to their own compatible 03219 * messenger objects and thus to direct their messages to the libisofs 03220 * message queue. See also: libburn, API function burn_set_messenger(). 03221 * 03222 * @return the handle. Do only use with compatible 03223 * 03224 * @since 0.6.2 03225 */ 03226 void *iso_get_messenger(); 03227 03228 /** 03229 * Take a ref to the given IsoFileSource. 03230 * 03231 * @since 0.6.2 03232 */ 03233 void iso_file_source_ref(IsoFileSource *src); 03234 03235 /** 03236 * Drop your ref to the given IsoFileSource, eventually freeing the associated 03237 * system resources. 03238 * 03239 * @since 0.6.2 03240 */ 03241 void iso_file_source_unref(IsoFileSource *src); 03242 03243 /* 03244 * this are just helpers to invoque methods in class 03245 */ 03246 03247 /** 03248 * Get the path, relative to the filesystem this file source 03249 * belongs to. 03250 * 03251 * @return 03252 * the path of the FileSource inside the filesystem, it should be 03253 * freed when no more needed. 03254 * 03255 * @since 0.6.2 03256 */ 03257 char* iso_file_source_get_path(IsoFileSource *src); 03258 03259 /** 03260 * Get the name of the file, with the dir component of the path. 03261 * 03262 * @return 03263 * the name of the file, it should be freed when no more needed. 03264 * 03265 * @since 0.6.2 03266 */ 03267 char* iso_file_source_get_name(IsoFileSource *src); 03268 03269 /** 03270 * Get information about the file. 03271 * @return 03272 * 1 success, < 0 error 03273 * Error codes: 03274 * ISO_FILE_ACCESS_DENIED 03275 * ISO_FILE_BAD_PATH 03276 * ISO_FILE_DOESNT_EXIST 03277 * ISO_OUT_OF_MEM 03278 * ISO_FILE_ERROR 03279 * ISO_NULL_POINTER 03280 * 03281 * @since 0.6.2 03282 */ 03283 int iso_file_source_lstat(IsoFileSource *src, struct stat *info); 03284 03285 /** 03286 * Check if the process has access to read file contents. Note that this 03287 * is not necessarily related with (l)stat functions. For example, in a 03288 * filesystem implementation to deal with an ISO image, if the user has 03289 * read access to the image it will be able to read all files inside it, 03290 * despite of the particular permission of each file in the RR tree, that 03291 * are what the above functions return. 03292 * 03293 * @return 03294 * 1 if process has read access, < 0 on error 03295 * Error codes: 03296 * ISO_FILE_ACCESS_DENIED 03297 * ISO_FILE_BAD_PATH 03298 * ISO_FILE_DOESNT_EXIST 03299 * ISO_OUT_OF_MEM 03300 * ISO_FILE_ERROR 03301 * ISO_NULL_POINTER 03302 * 03303 * @since 0.6.2 03304 */ 03305 int iso_file_source_access(IsoFileSource *src); 03306 03307 /** 03308 * Get information about the file. If the file is a symlink, the info 03309 * returned refers to the destination. 03310 * 03311 * @return 03312 * 1 success, < 0 error 03313 * Error codes: 03314 * ISO_FILE_ACCESS_DENIED 03315 * ISO_FILE_BAD_PATH 03316 * ISO_FILE_DOESNT_EXIST 03317 * ISO_OUT_OF_MEM 03318 * ISO_FILE_ERROR 03319 * ISO_NULL_POINTER 03320 * 03321 * @since 0.6.2 03322 */ 03323 int iso_file_source_stat(IsoFileSource *src, struct stat *info); 03324 03325 /** 03326 * Opens the source. 03327 * @return 1 on success, < 0 on error 03328 * Error codes: 03329 * ISO_FILE_ALREADY_OPENED 03330 * ISO_FILE_ACCESS_DENIED 03331 * ISO_FILE_BAD_PATH 03332 * ISO_FILE_DOESNT_EXIST 03333 * ISO_OUT_OF_MEM 03334 * ISO_FILE_ERROR 03335 * ISO_NULL_POINTER 03336 * 03337 * @since 0.6.2 03338 */ 03339 int iso_file_source_open(IsoFileSource *src); 03340 03341 /** 03342 * Close a previuously openned file 03343 * @return 1 on success, < 0 on error 03344 * Error codes: 03345 * ISO_FILE_ERROR 03346 * ISO_NULL_POINTER 03347 * ISO_FILE_NOT_OPENED 03348 * 03349 * @since 0.6.2 03350 */ 03351 int iso_file_source_close(IsoFileSource *src); 03352 03353 /** 03354 * Attempts to read up to count bytes from the given source into 03355 * the buffer starting at buf. 03356 * 03357 * The file src must be open() before calling this, and close() when no 03358 * more needed. Not valid for dirs. On symlinks it reads the destination 03359 * file. 03360 * 03361 * @param src 03362 * The given source 03363 * @param buf 03364 * Pointer to a buffer of at least count bytes where the read data will be 03365 * stored 03366 * @param count 03367 * Bytes to read 03368 * @return 03369 * number of bytes read, 0 if EOF, < 0 on error 03370 * Error codes: 03371 * ISO_FILE_ERROR 03372 * ISO_NULL_POINTER 03373 * ISO_FILE_NOT_OPENED 03374 * ISO_WRONG_ARG_VALUE -> if count == 0 03375 * ISO_FILE_IS_DIR 03376 * ISO_OUT_OF_MEM 03377 * ISO_INTERRUPTED 03378 * 03379 * @since 0.6.2 03380 */ 03381 int iso_file_source_read(IsoFileSource *src, void *buf, size_t count); 03382 03383 /** 03384 * Repositions the offset of the given IsoFileSource (must be opened) to the 03385 * given offset according to the value of flag. 03386 * 03387 * @param offset 03388 * in bytes 03389 * @param flag 03390 * 0 The offset is set to offset bytes (SEEK_SET) 03391 * 1 The offset is set to its current location plus offset bytes 03392 * (SEEK_CUR) 03393 * 2 The offset is set to the size of the file plus offset bytes 03394 * (SEEK_END). 03395 * @return 03396 * Absolute offset posistion on the file, or < 0 on error. Cast the 03397 * returning value to int to get a valid libisofs error. 03398 * @since 0.6.4 03399 */ 03400 off_t iso_file_source_lseek(IsoFileSource *src, off_t offset, int flag); 03401 03402 /** 03403 * Read a directory. 03404 * 03405 * Each call to this function will return a new children, until we reach 03406 * the end of file (i.e, no more children), in that case it returns 0. 03407 * 03408 * The dir must be open() before calling this, and close() when no more 03409 * needed. Only valid for dirs. 03410 * 03411 * Note that "." and ".." children MUST NOT BE returned. 03412 * 03413 * @param child 03414 * pointer to be filled with the given child. Undefined on error or OEF 03415 * @return 03416 * 1 on success, 0 if EOF (no more children), < 0 on error 03417 * Error codes: 03418 * ISO_FILE_ERROR 03419 * ISO_NULL_POINTER 03420 * ISO_FILE_NOT_OPENED 03421 * ISO_FILE_IS_NOT_DIR 03422 * ISO_OUT_OF_MEM 03423 * 03424 * @since 0.6.2 03425 */ 03426 int iso_file_source_readdir(IsoFileSource *src, IsoFileSource **child); 03427 03428 /** 03429 * Read the destination of a symlink. You don't need to open the file 03430 * to call this. 03431 * 03432 * @param src 03433 * An IsoFileSource corresponding to a symbolic link. 03434 * @param buf 03435 * allocated buffer of at least bufsiz bytes. 03436 * The dest. will be copied there, and it will be NULL-terminated 03437 * @param bufsiz 03438 * characters to be copied. Destination link will be truncated if 03439 * it is larger than given size. This include the '\0' character. 03440 * @return 03441 * 1 on success, < 0 on error 03442 * Error codes: 03443 * ISO_FILE_ERROR 03444 * ISO_NULL_POINTER 03445 * ISO_WRONG_ARG_VALUE -> if bufsiz <= 0 03446 * ISO_FILE_IS_NOT_SYMLINK 03447 * ISO_OUT_OF_MEM 03448 * ISO_FILE_BAD_PATH 03449 * ISO_FILE_DOESNT_EXIST 03450 * 03451 * @since 0.6.2 03452 */ 03453 int iso_file_source_readlink(IsoFileSource *src, char *buf, size_t bufsiz); 03454 03455 /** 03456 * Get the filesystem for this source. No extra ref is added, so you 03457 * musn't unref the IsoFilesystem. 03458 * 03459 * @return 03460 * The filesystem, NULL on error 03461 * 03462 * @since 0.6.2 03463 */ 03464 IsoFilesystem* iso_file_source_get_filesystem(IsoFileSource *src); 03465 03466 /** 03467 * Take a ref to the given IsoFilesystem 03468 * 03469 * @since 0.6.2 03470 */ 03471 void iso_filesystem_ref(IsoFilesystem *fs); 03472 03473 /** 03474 * Drop your ref to the given IsoFilesystem, evetually freeing associated 03475 * resources. 03476 * 03477 * @since 0.6.2 03478 */ 03479 void iso_filesystem_unref(IsoFilesystem *fs); 03480 03481 /** 03482 * Create a new IsoFilesystem to access a existent ISO image. 03483 * 03484 * @param src 03485 * Data source to access data. 03486 * @param opts 03487 * Image read options 03488 * @param msgid 03489 * An image identifer, obtained with iso_image_get_msg_id(), used to 03490 * associated messages issued by the filesystem implementation with an 03491 * existent image. If you are not using this filesystem in relation with 03492 * any image context, just use 0x1fffff as the value for this parameter. 03493 * @param fs 03494 * Will be filled with a pointer to the filesystem that can be used 03495 * to access image contents. 03496 * @param 03497 * 1 on success, < 0 on error 03498 * 03499 * @since 0.6.2 03500 */ 03501 int iso_image_filesystem_new(IsoDataSource *src, IsoReadOpts *opts, int msgid, 03502 IsoImageFilesystem **fs); 03503 03504 /** 03505 * Get the volset identifier for an existent image. The returned string belong 03506 * to the IsoImageFilesystem and shouldn't be free() nor modified. 03507 * 03508 * @since 0.6.2 03509 */ 03510 const char *iso_image_fs_get_volset_id(IsoImageFilesystem *fs); 03511 03512 /** 03513 * Get the volume identifier for an existent image. The returned string belong 03514 * to the IsoImageFilesystem and shouldn't be free() nor modified. 03515 * 03516 * @since 0.6.2 03517 */ 03518 const char *iso_image_fs_get_volume_id(IsoImageFilesystem *fs); 03519 03520 /** 03521 * Get the publisher identifier for an existent image. The returned string 03522 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03523 * 03524 * @since 0.6.2 03525 */ 03526 const char *iso_image_fs_get_publisher_id(IsoImageFilesystem *fs); 03527 03528 /** 03529 * Get the data preparer identifier for an existent image. The returned string 03530 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03531 * 03532 * @since 0.6.2 03533 */ 03534 const char *iso_image_fs_get_data_preparer_id(IsoImageFilesystem *fs); 03535 03536 /** 03537 * Get the system identifier for an existent image. The returned string belong 03538 * to the IsoImageFilesystem and shouldn't be free() nor modified. 03539 * 03540 * @since 0.6.2 03541 */ 03542 const char *iso_image_fs_get_system_id(IsoImageFilesystem *fs); 03543 03544 /** 03545 * Get the application identifier for an existent image. The returned string 03546 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03547 * 03548 * @since 0.6.2 03549 */ 03550 const char *iso_image_fs_get_application_id(IsoImageFilesystem *fs); 03551 03552 /** 03553 * Get the copyright file identifier for an existent image. The returned string 03554 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03555 * 03556 * @since 0.6.2 03557 */ 03558 const char *iso_image_fs_get_copyright_file_id(IsoImageFilesystem *fs); 03559 03560 /** 03561 * Get the abstract file identifier for an existent image. The returned string 03562 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03563 * 03564 * @since 0.6.2 03565 */ 03566 const char *iso_image_fs_get_abstract_file_id(IsoImageFilesystem *fs); 03567 03568 /** 03569 * Get the biblio file identifier for an existent image. The returned string 03570 * belong to the IsoImageFilesystem and shouldn't be free() nor modified. 03571 * 03572 * @since 0.6.2 03573 */ 03574 const char *iso_image_fs_get_biblio_file_id(IsoImageFilesystem *fs); 03575 03576 /** 03577 * Increment reference count of an IsoStream. 03578 * 03579 * @since 0.6.4 03580 */ 03581 void iso_stream_ref(IsoStream *stream); 03582 03583 /** 03584 * Decrement reference count of an IsoStream, and eventually free it if 03585 * refcount reach 0. 03586 * 03587 * @since 0.6.4 03588 */ 03589 void iso_stream_unref(IsoStream *stream); 03590 03591 /** 03592 * Opens the given stream. Remember to close the Stream before writing the 03593 * image. 03594 * 03595 * @return 03596 * 1 on success, 2 file greater than expected, 3 file smaller than 03597 * expected, < 0 on error 03598 * 03599 * @since 0.6.4 03600 */ 03601 int iso_stream_open(IsoStream *stream); 03602 03603 /** 03604 * Close a previously openned IsoStream. 03605 * 03606 * @return 03607 * 1 on success, < 0 on error 03608 * 03609 * @since 0.6.4 03610 */ 03611 int iso_stream_close(IsoStream *stream); 03612 03613 /** 03614 * Get the size of a given stream. This function should always return the same 03615 * size, even if the underlying source size changes. 03616 * 03617 * @return 03618 * IsoStream size in bytes 03619 * 03620 * @since 0.6.4 03621 */ 03622 off_t iso_stream_get_size(IsoStream *stream); 03623 03624 /** 03625 * Attempts to read up to count bytes from the given stream into 03626 * the buffer starting at buf. 03627 * 03628 * The stream must be open() before calling this, and close() when no 03629 * more needed. 03630 * 03631 * @return 03632 * number of bytes read, 0 if EOF, < 0 on error 03633 * 03634 * @since 0.6.4 03635 */ 03636 int iso_stream_read(IsoStream *stream, void *buf, size_t count); 03637 03638 /** 03639 * Whether the given IsoStream can be read several times, with the same 03640 * results. 03641 * For example, a regular file is repeatable, you can read it as many 03642 * times as you want. However, a pipe isn't. 03643 * 03644 * This function doesn't take into account if the file has been modified 03645 * between the two reads. 03646 * 03647 * @return 03648 * 1 if stream is repeatable, 0 if not, < 0 on error 03649 * 03650 * @since 0.6.4 03651 */ 03652 int iso_stream_is_repeatable(IsoStream *stream); 03653 03654 /** 03655 * Get an unique identifier for a given IsoStream. 03656 * 03657 * @since 0.6.4 03658 */ 03659 void iso_stream_get_id(IsoStream *stream, unsigned int *fs_id, dev_t *dev_id, 03660 ino_t *ino_id); 03661 03662 /************ Error codes and return values for libisofs ********************/ 03663 03664 /** successfully execution */ 03665 #define ISO_SUCCESS 1 03666 03667 /** 03668 * special return value, it could be or not an error depending on the 03669 * context. 03670 */ 03671 #define ISO_NONE 0 03672 03673 /** Operation canceled (FAILURE,HIGH, -1) */ 03674 #define ISO_CANCELED 0xE830FFFF 03675 03676 /** Unknown or unexpected fatal error (FATAL,HIGH, -2) */ 03677 #define ISO_FATAL_ERROR 0xF030FFFE 03678 03679 /** Unknown or unexpected error (FAILURE,HIGH, -3) */ 03680 #define ISO_ERROR 0xE830FFFD 03681 03682 /** Internal programming error. Please report this bug (FATAL,HIGH, -4) */ 03683 #define ISO_ASSERT_FAILURE 0xF030FFFC 03684 03685 /** 03686 * NULL pointer as value for an arg. that doesn't allow NULL (FAILURE,HIGH, -5) 03687 */ 03688 #define ISO_NULL_POINTER 0xE830FFFB 03689 03690 /** Memory allocation error (FATAL,HIGH, -6) */ 03691 #define ISO_OUT_OF_MEM 0xF030FFFA 03692 03693 /** Interrupted by a signal (FATAL,HIGH, -7) */ 03694 #define ISO_INTERRUPTED 0xF030FFF9 03695 03696 /** Invalid parameter value (FAILURE,HIGH, -8) */ 03697 #define ISO_WRONG_ARG_VALUE 0xE830FFF8 03698 03699 /** Can't create a needed thread (FATAL,HIGH, -9) */ 03700 #define ISO_THREAD_ERROR 0xF030FFF7 03701 03702 /** Write error (FAILURE,HIGH, -10) */ 03703 #define ISO_WRITE_ERROR 0xE830FFF6 03704 03705 /** Buffer read error (FAILURE,HIGH, -11) */ 03706 #define ISO_BUF_READ_ERROR 0xE830FFF5 03707 03708 /** Trying to add to a dir a node already added to a dir (FAILURE,HIGH, -64) */ 03709 #define ISO_NODE_ALREADY_ADDED 0xE830FFC0 03710 03711 /** Node with same name already exists (FAILURE,HIGH, -65) */ 03712 #define ISO_NODE_NAME_NOT_UNIQUE 0xE830FFBF 03713 03714 /** Trying to remove a node that was not added to dir (FAILURE,HIGH, -65) */ 03715 #define ISO_NODE_NOT_ADDED_TO_DIR 0xE830FFBE 03716 03717 /** A requested node does not exist (FAILURE,HIGH, -66) */ 03718 #define ISO_NODE_DOESNT_EXIST 0xE830FFBD 03719 03720 /** 03721 * Try to set the boot image of an already bootable image (FAILURE,HIGH, -67) 03722 */ 03723 #define ISO_IMAGE_ALREADY_BOOTABLE 0xE830FFBC 03724 03725 /** Trying to use an invalid file as boot image (FAILURE,HIGH, -68) */ 03726 #define ISO_BOOT_IMAGE_NOT_VALID 0xE830FFBB 03727 03728 /** 03729 * Error on file operation (FAILURE,HIGH, -128) 03730 * (take a look at more specified error codes below) 03731 */ 03732 #define ISO_FILE_ERROR 0xE830FF80 03733 03734 /** Trying to open an already openned file (FAILURE,HIGH, -129) */ 03735 #define ISO_FILE_ALREADY_OPENED 0xE830FF7F 03736 03737 /* @deprecated use ISO_FILE_ALREADY_OPENED instead */ 03738 #define ISO_FILE_ALREADY_OPENNED 0xE830FF7F 03739 03740 /** Access to file is not allowed (FAILURE,HIGH, -130) */ 03741 #define ISO_FILE_ACCESS_DENIED 0xE830FF7E 03742 03743 /** Incorrect path to file (FAILURE,HIGH, -131) */ 03744 #define ISO_FILE_BAD_PATH 0xE830FF7D 03745 03746 /** The file does not exist in the filesystem (FAILURE,HIGH, -132) */ 03747 #define ISO_FILE_DOESNT_EXIST 0xE830FF7C 03748 03749 /** Trying to read or close a file not openned (FAILURE,HIGH, -133) */ 03750 #define ISO_FILE_NOT_OPENED 0xE830FF7B 03751 03752 /* @deprecated use ISO_FILE_NOT_OPENED instead */ 03753 #define ISO_FILE_NOT_OPENNED ISO_FILE_NOT_OPENED 03754 03755 /** Directory used where no dir is expected (FAILURE,HIGH, -134) */ 03756 #define ISO_FILE_IS_DIR 0xE830FF7A 03757 03758 /** Read error (FAILURE,HIGH, -135) */ 03759 #define ISO_FILE_READ_ERROR 0xE830FF79 03760 03761 /** Not dir used where a dir is expected (FAILURE,HIGH, -136) */ 03762 #define ISO_FILE_IS_NOT_DIR 0xE830FF78 03763 03764 /** Not symlink used where a symlink is expected (FAILURE,HIGH, -137) */ 03765 #define ISO_FILE_IS_NOT_SYMLINK 0xE830FF77 03766 03767 /** Can't seek to specified location (FAILURE,HIGH, -138) */ 03768 #define ISO_FILE_SEEK_ERROR 0xE830FF76 03769 03770 /** File not supported in ECMA-119 tree and thus ignored (HINT,MEDIUM, -139) */ 03771 #define ISO_FILE_IGNORED 0xC020FF75 03772 03773 /* A file is bigger than supported by used standard (HINT,MEDIUM, -140) */ 03774 #define ISO_FILE_TOO_BIG 0xC020FF74 03775 03776 /* File read error during image creation (MISHAP,HIGH, -141) */ 03777 #define ISO_FILE_CANT_WRITE 0xE430FF73 03778 03779 /* Can't convert filename to requested charset (HINT,MEDIUM, -142) */ 03780 #define ISO_FILENAME_WRONG_CHARSET 0xC020FF72 03781 03782 /* File can't be added to the tree (SORRY,HIGH, -143) */ 03783 #define ISO_FILE_CANT_ADD 0xE030FF71 03784 03785 /** 03786 * File path break specification constraints and will be ignored 03787 * (HINT,MEDIUM, -144) 03788 */ 03789 #define ISO_FILE_IMGPATH_WRONG 0xC020FF70 03790 03791 /** 03792 * Offset greater than file size (FAILURE,HIGH, -145) 03793 * @since 0.6.4 03794 */ 03795 #define ISO_FILE_OFFSET_TOO_BIG 0xE830FF6A 03796 03797 /** Charset conversion error (FAILURE,HIGH, -256) */ 03798 #define ISO_CHARSET_CONV_ERROR 0xE830FF00 03799 03800 /** 03801 * Too much files to mangle, i.e. we cannot guarantee unique file names 03802 * (FAILURE,HIGH, -257) 03803 */ 03804 #define ISO_MANGLE_TOO_MUCH_FILES 0xE830FEFF 03805 03806 /* image related errors */ 03807 03808 /** 03809 * Wrong or damaged Primary Volume Descriptor (FAILURE,HIGH, -320) 03810 * This could mean that the file is not a valid ISO image. 03811 */ 03812 #define ISO_WRONG_PVD 0xE830FEC0 03813 03814 /** Wrong or damaged RR entry (SORRY,HIGH, -321) */ 03815 #define ISO_WRONG_RR 0xE030FEBF 03816 03817 /** Unsupported RR feature (SORRY,HIGH, -322) */ 03818 #define ISO_UNSUPPORTED_RR 0xE030FEBE 03819 03820 /** Wrong or damaged ECMA-119 (FAILURE,HIGH, -323) */ 03821 #define ISO_WRONG_ECMA119 0xE830FEBD 03822 03823 /** Unsupported ECMA-119 feature (FAILURE,HIGH, -324) */ 03824 #define ISO_UNSUPPORTED_ECMA119 0xE830FEBC 03825 03826 /** Wrong or damaged El-Torito catalog (SORRY,HIGH, -325) */ 03827 #define ISO_WRONG_EL_TORITO 0xE030FEBB 03828 03829 /** Unsupported El-Torito feature (SORRY,HIGH, -326) */ 03830 #define ISO_UNSUPPORTED_EL_TORITO 0xE030FEBA 03831 03832 /** Can't patch an isolinux boot image (SORRY,HIGH, -327) */ 03833 #define ISO_ISOLINUX_CANT_PATCH 0xE030FEB9 03834 03835 /** Unsupported SUSP feature (SORRY,HIGH, -328) */ 03836 #define ISO_UNSUPPORTED_SUSP 0xE030FEB8 03837 03838 /** Error on a RR entry that can be ignored (WARNING,HIGH, -329) */ 03839 #define ISO_WRONG_RR_WARN 0xD030FEB7 03840 03841 /** Error on a RR entry that can be ignored (HINT,MEDIUM, -330) */ 03842 #define ISO_SUSP_UNHANDLED 0xC020FEB6 03843 03844 /** Multiple ER SUSP entries found (WARNING,HIGH, -331) */ 03845 #define ISO_SUSP_MULTIPLE_ER 0xD030FEB5 03846 03847 /** Unsupported volume descriptor found (HINT,MEDIUM, -332) */ 03848 #define ISO_UNSUPPORTED_VD 0xC020FEB4 03849 03850 /** El-Torito related warning (WARNING,HIGH, -333) */ 03851 #define ISO_EL_TORITO_WARN 0xD030FEB3 03852 03853 /** Image write cancelled (MISHAP,HIGH, -334) */ 03854 #define ISO_IMAGE_WRITE_CANCELED 0xE430FEB2 03855 03856 /** El-Torito image is hidden (WARNING,HIGH, -335) */ 03857 #define ISO_EL_TORITO_HIDDEN 0xD030FEB1 03858 03859 #endif /*LIBISO_LIBISOFS_H_*/