00001 /* -*- indent-tabs-mode: t; tab-width: 8; c-basic-offset: 8; -*- */ 00002 /* vim: set noet ts=8 sts=8 sw=8 : */ 00003 00004 /** 00005 * Create an ISO-9660 data volume with Rock Ridge and Joliet extensions. 00006 * Usage is easy: 00007 * - Create a new volume. 00008 * - Add files and directories. 00009 * - Write the volume to a file or create a burn source for use with Libburn. 00010 */ 00011 00012 #ifndef LIBISO_LIBISOFS_H 00013 #define LIBISO_LIBISOFS_H 00014 00015 #include <sys/types.h> 00016 00017 /* #include <libburn.h> */ 00018 struct burn_source; 00019 00020 /** 00021 * Data volume. 00022 * @see volume.h for details. 00023 */ 00024 struct iso_volume; 00025 00026 /** 00027 * A set of data volumes. 00028 * @see volume.h for details. 00029 */ 00030 struct iso_volset; 00031 00032 /** 00033 * A node in the filesystem tree. 00034 * \see tree.h 00035 */ 00036 struct iso_tree_node; 00037 00038 /** 00039 * El-Torito boot image 00040 * \see eltorito.h 00041 */ 00042 struct el_torito_boot_image; 00043 00044 /** 00045 * A directory in the filesystem tree. 00046 * The first member of this is an iso_tree_node. 00047 * \see tree.h 00048 */ 00049 struct iso_tree_node_dir; 00050 00051 /** 00052 * Extensions addition to ECMA-119 (ISO-9660) image. Usage of at least 00053 * one of these flags is highly recommended if the disc will be used on a 00054 * modern OS. 00055 */ 00056 enum ecma119_extension_flag { 00057 /** 00058 * Add the standard Rock Ridge extensions. This adds POSIX filesystem 00059 * features to the ECMA-119 image. Thus, usage of this flag is highly 00060 * recommended for images used on GNU/Linux systems. With the usage 00061 * of RR extension, the resulting image will have long filenames (up to 00062 * 255 characters), deeper directory structure, POSIX permissions and 00063 * owner info on files and directories, support for symbolic links or 00064 * special files... All that attributes can be modified/setted with the 00065 * appropiate function. 00066 */ 00067 ECMA119_ROCKRIDGE = (1<<0), 00068 /** 00069 * Add the non-standard Joliet extension to the image. This extension is 00070 * heavily used in Microsoft Windows systems, so if you plan to use your 00071 * disc on such a system you should add this extension. Usage of Joliet 00072 * supplies longer filesystem length (up to 64 unicode characters), and 00073 * deeper directory structure. 00074 */ 00075 ECMA119_JOLIET = (1<<1) 00076 }; 00077 00078 /** 00079 * Flag used to hide a file in the RR/ISO or Joliet tree. 00080 * 00081 * \see iso_tree_node_set_hidden 00082 */ 00083 enum hide_node_flag { 00084 LIBISO_HIDE_ON_RR = 1 << 0, 00085 LIBISO_HIDE_ON_JOLIET = 1 << 1 00086 }; 00087 00088 /** 00089 * El-Torito bootable image type. 00090 */ 00091 enum eltorito_boot_media_type { 00092 ELTORITO_FLOPPY_EMUL, 00093 ELTORITO_HARD_DISC_EMUL, 00094 ELTORITO_NO_EMUL 00095 }; 00096 00097 enum ecma119_relaxed_constraints_flag { 00098 ECMA119_OMIT_VERSION_NUMBERS = (1<<0), 00099 /* 37 char filenames involves no version number */ 00100 ECMA119_37_CHAR_FILENAMES = (1<<1) | (1<<0), 00101 ECMA119_NO_DIR_REALOCATION = (1<<2), 00102 ECMA119_RELAXED_FILENAMES = (1<<3) 00103 }; 00104 00105 /** 00106 * Holds the options for the image generation. 00107 */ 00108 struct ecma119_source_opts { 00109 int volnum; /**< The volume in the set which you want to write (usually 0) */ 00110 int level; /**< ISO level to write at. */ 00111 int flags; /**< Which extensions to support. */ 00112 int relaxed_constraints; /**< see ecma119_relaxed_constraints_flag */ 00113 unsigned int no_cache_inodes:1; 00114 /**< If use inode caching or not. Set it to 1 to prevent 00115 * inode caching. 00116 * Usage of inode caching allows detection of hard-links, 00117 * which contents are only written once to disc this way. 00118 * Don't use inode caching in systems with non unique inodes 00119 * per device. 00120 */ 00121 unsigned int sort_files:1; 00122 /**< If files should be sorted based on their weight. */ 00123 unsigned int default_mode:1; 00124 /**< 00125 * The default values for files and directory permissions, 00126 * gid and uid. This option can be overwritten when set 00127 * one of the following. 00128 * 0 to use useful values, 1 to use node modes (this are 00129 * the same as filesystem ones if not changed after added 00130 * to tree). 00131 */ 00132 unsigned int replace_dir_mode:1; 00133 /**< 00134 * When 1, permissions for all dirs will be replaced by the 00135 * specified in dir_mode field. 00136 */ 00137 unsigned int replace_file_mode:1; 00138 /**< 00139 * When 1, permissions for all files will be replaced by the 00140 * specified in file_mode field. 00141 */ 00142 unsigned int replace_uid:1; 00143 /**< 00144 * When 1, uid of all nodes (both files and dirs) will be 00145 * replaced by the specified in uid field. 00146 */ 00147 unsigned int replace_gid:1; 00148 /**< 00149 * When 1, gid of all nodes (both files and dirs) will be 00150 * replaced by the specified in gid field. 00151 */ 00152 mode_t dir_mode; /**< Mode to use on dirs when replace_dir_mode is set. */ 00153 mode_t file_mode; /**< Mode to use on files when replace_file_mode is set. */ 00154 gid_t gid; /**< gid to use when replace_gid is set. */ 00155 uid_t uid; /**< uid to use when replace_uid is set. */ 00156 char *input_charset; /**< NULL to use default charset */ 00157 char *ouput_charset; /**< NULL to use default charset */ 00158 }; 00159 00160 /** 00161 * This will hold the error code for some functions, if them fail. 00162 */ 00163 int libisofs_errno; 00164 00165 /* an unexpected internal error */ 00166 #define INTERNAL_ERROR -1 00167 /* file don't exists, or can't be stat'ed */ 00168 #define NO_FILE 1 00169 /* user haven't read access to file */ 00170 #define NO_READ_ACCESS 2 00171 /* unexpected file type, eg., passing a dir instead of a regular file */ 00172 #define UNEXPECTED_FILE_TYPE 3 00173 /* invalid boot image size */ 00174 #define ELTORITO_WRONG_IMAGE_SIZE 4 00175 00176 /** 00177 * Controls the bahavior of iso_tree_radd_dir function 00178 */ 00179 struct iso_tree_radd_dir_behavior { 00180 char** excludes; /**< List of paths (file or directory) to be ignored. */ 00181 //int follow_sym_link; 00182 int stop_on_error; /**< Stop when an error was found?. */ 00183 int error; /**< set to 1 on error */ 00184 //int notify_errors; 00185 //char** errors; 00186 }; 00187 00188 /** 00189 * Create a new volume. 00190 * The parameters can be set to NULL if you wish to set them later. 00191 */ 00192 struct iso_volume *iso_volume_new(const char *volume_id, 00193 const char *publisher_id, 00194 const char *data_preparer_id); 00195 00196 struct iso_volume *iso_volume_new_with_root(const char *volume_id, 00197 const char *publisher_id, 00198 const char *data_preparer_id, 00199 struct iso_tree_node_dir *root); 00200 00201 /** 00202 * Free a volume. 00203 */ 00204 void iso_volume_free(struct iso_volume *volume); 00205 00206 /** 00207 * Free a set of data volumes. 00208 */ 00209 void iso_volset_free(struct iso_volset *volume); 00210 00211 /** 00212 * Get the root directory for a volume. 00213 */ 00214 struct iso_tree_node_dir *iso_volume_get_root(const struct iso_volume *volume); 00215 00216 /** 00217 * Fill in the volume identifier for a volume. 00218 */ 00219 void iso_volume_set_volume_id(struct iso_volume *volume, 00220 const char *volume_id); 00221 00222 /** 00223 * Fill in the publisher for a volume. 00224 */ 00225 void iso_volume_set_publisher_id(struct iso_volume *volume, 00226 const char *publisher_id); 00227 00228 /** 00229 * Fill in the data preparer for a volume. 00230 */ 00231 void iso_volume_set_data_preparer_id(struct iso_volume *volume, 00232 const char *data_preparer_id); 00233 00234 /** 00235 * Fill in the system id for a volume. Up to 32 characters. 00236 */ 00237 void iso_volume_set_system_id(struct iso_volume *volume, 00238 const char *system_id); 00239 00240 /** 00241 * Fill in the application id for a volume. Up to 128 chars. 00242 */ 00243 void iso_volume_set_application_id(struct iso_volume *volume, 00244 const char *application_id); 00245 00246 /** 00247 * Fill copyright information for the volume. Usually this refers 00248 * to a file on disc. Up to 37 characters. 00249 */ 00250 void iso_volume_set_copyright_file_id(struct iso_volume *volume, 00251 const char *copyright_file_id); 00252 00253 /** 00254 * Fill abstract information for the volume. Usually this refers 00255 * to a file on disc. Up to 37 characters. 00256 */ 00257 void iso_volume_set_abstract_file_id(struct iso_volume *volume, 00258 const char *abstract_file_id); 00259 00260 /** 00261 * Fill biblio information for the volume. Usually this refers 00262 * to a file on disc. Up to 37 characters. 00263 */ 00264 void iso_volume_set_biblio_file_id(struct iso_volume *volume, 00265 const char *biblio_file_id); 00266 00267 /** 00268 * Create a bootable volume by adding a El-Torito boot image. 00269 * 00270 * \param volume The volume to make bootable. 00271 * \param image The tree node with the file to use as default boot image. 00272 * \param type The boot media type. This can be one of 3 types: 00273 * - Floppy emulation: Boot image files must be exactly 00274 * 1200 kB, 1440 kB or 2880 kB. 00275 * - Hard disc emulation: The image must begin with a master 00276 * boot record with a single image. 00277 * - No emulation. You should specify load segment and load size 00278 * of image. 00279 * \param dir The directory node where the boot catalog will be located 00280 * in image. Usually both boot catalog and boot image will be 00281 * located in the same dir, maybe /boot. 00282 * \param name The name of the boot catalog. 00283 * 00284 * \return The default El-Torito bootable image. If specified image file 00285 * seems to be not correct, this returns NULL and libisofs_errno 00286 * is set propertly. 00287 * 00288 * \pre \p volume is a volume without any boot catalog yet 00289 * \pre \p image is a file tree node already inserted in the volume tree. 00290 * \pre \p dir is a directory node already inserted in the volume tree. 00291 * \pre \p name There isn't any dir child with the same name. 00292 * 00293 */ 00294 struct el_torito_boot_image * 00295 iso_volume_create_boot_catalog(struct iso_volume *volume, 00296 struct iso_tree_node *image, 00297 enum eltorito_boot_media_type type, 00298 struct iso_tree_node_dir *dir, 00299 char *name); 00300 00301 /** 00302 * Sets the load segment for the initial boot image. This is only for 00303 * no emulation boot images, and is a NOP for other image types. 00304 */ 00305 void 00306 el_torito_set_load_seg(struct el_torito_boot_image *bootimg, int segment); 00307 00308 /** 00309 * Sets the number of sectors (512b) to be load at load segment during 00310 * the initial boot procedure. This is only for 00311 * no emulation boot images, and is a NOP for other image types. 00312 */ 00313 void 00314 el_torito_set_load_size(struct el_torito_boot_image *bootimg, int sectors); 00315 00316 /** 00317 * Marks the specified boot image as not bootable 00318 */ 00319 void 00320 el_torito_set_no_bootable(struct el_torito_boot_image *bootimg); 00321 00322 /** 00323 * Specifies that this image needs to be patched. This involves the writting 00324 * of a 56 bytes boot information table at offset 8 of the boot image file. 00325 * Be aware that libisofs will modify original boot image file, so do a backup 00326 * if needed. 00327 * This is needed for isolinux boot images. 00328 */ 00329 void 00330 el_torito_set_write_boot_info(struct el_torito_boot_image *bootimg); 00331 00332 /** 00333 * Locate a node by its path on disc. 00334 * 00335 * \param volume The volume to search in. 00336 * \param path The path, in the image, of the file. 00337 * 00338 * \return The node found or NULL. 00339 * 00340 * TODO we need a way to allow developers know which kind of node is. 00341 * Think about this when designing the read api 00342 */ 00343 struct iso_tree_node *iso_tree_volume_path_to_node(struct iso_volume *volume, const char *path); 00344 00345 /** 00346 * Add a file or a directory (recursively) to a volume by specifying its path on the volume. 00347 * 00348 * \param volume The volume to add the file to. 00349 * \param disc_path The path on the disc at which to add the disc. 00350 * \param path The path, on the local filesystem, of the file. 00351 * 00352 * \return The node for the file or NULL if the parent doesn't exists on the disc. 00353 */ 00354 //struct iso_tree_node *iso_tree_volume_add_path(struct iso_volume *volume, 00355 // const char *disc_path, 00356 // const char *path); 00357 00358 /** 00359 * Creates a new, empty directory on the volume. 00360 * 00361 * \param volume The volume to add the directory to. 00362 * \param disc_path The path on the volume at which to add the directory. 00363 * 00364 * \return A pointer to the newly created directory. 00365 */ 00366 //struct iso_tree_node *iso_tree_volume_add_new_dir(struct iso_volume *volume, 00367 // const char *disc_path); 00368 00369 /** 00370 * Create a new Volume Set consisting of only one volume. 00371 * @param volume The first and only volume for the volset to contain. 00372 * @param volset_id The Volume Set ID. 00373 * @return A new iso_volset. 00374 */ 00375 struct iso_volset *iso_volset_new(struct iso_volume *volume, 00376 const char *volset_id); 00377 00378 00379 /** 00380 * Creates a new root dir for a filesystem tree 00381 */ 00382 struct iso_tree_node_dir *iso_tree_new_root(); 00383 00384 /** 00385 * Add a file to a directory. 00386 * 00387 * \param path The path, on the local filesystem, of the file. 00388 * 00389 * \pre \p parent is non-NULL. 00390 * \pre \p path is non-NULL. 00391 * \return An iso_tree_node_file whose path is \p path and whose parent is 00392 * \p parent. 00393 * On error, returns NULL and libisofs_errno is set appropriately: 00394 * NO_FILE if path doesn't point to a valid file. 00395 * NO_READ_ACCESS if user haven't read access on file 00396 * UNEXPECTED_FILE_TYPE if path doesn't point to a regular file 00397 */ 00398 struct iso_tree_node *iso_tree_add_file(struct iso_tree_node_dir *parent, 00399 const char *path); 00400 00401 /** 00402 * Add a symbolic link to a directory. 00403 * 00404 * \param name The name of the symbolic link 00405 * \param dest The distination of the link, i.e., the file this link points 00406 * to 00407 * 00408 * \pre \p parent, name and dest are non-NULL. 00409 * 00410 * \return An iso_tree_node_symlink 00411 */ 00412 struct iso_tree_node *iso_tree_add_symlink(struct iso_tree_node_dir *parent, 00413 const char *name, const char *dest); 00414 00415 /** 00416 * Add a new, empty directory to the tree. 00417 * 00418 * \pre \p parent is non-NULL. 00419 * \pre \p name is unique among the children and files belonging to \p parent. 00420 * Also, it doesn't contain '/' characters. 00421 * 00422 * \post \p parent contains a child directory whose name is \p name and whose 00423 * POSIX attributes are the same as \p parent's. 00424 * \return a pointer to the newly created directory. 00425 */ 00426 struct iso_tree_node_dir *iso_tree_add_dir(struct iso_tree_node_dir *parent, 00427 const char *name); 00428 00429 /* TODO iso_tree_new_special */ 00430 00431 /** 00432 * Add a file to a directory. 00433 * 00434 * \param path The path, on the local filesystem, of the file. 00435 * 00436 * \pre \p parent is non-NULL. 00437 * \pre \p path is non-NULL and is a valid path to a file or directory on the local 00438 * filesystem. 00439 * \return An iso_tree_node whose path is \p path and whose parent is \p parent. 00440 * On error, returns NULL and libisofs_errno is set appropriately: 00441 * NO_FILE if path doesn't point to a valid file. 00442 * NO_READ_ACCESS if user haven't read access on file 00443 * UNEXPECTED_FILE_TYPE if path refers to non supported file type 00444 * (at the momment, only dirs, symlinks and regular 00445 * files are supported). 00446 */ 00447 struct iso_tree_node *iso_tree_add_node(struct iso_tree_node_dir *parent, 00448 const char *path); 00449 00450 /** 00451 * Recursively add an existing directory to the tree. 00452 * Warning: when using this, you'll lose pointers to files or subdirectories. 00453 * If you want to have pointers to all files and directories, 00454 * use iso_tree_add_file, iso_tree_add_node and iso_tree_add_dir. 00455 * 00456 * \param path The path, on the local filesystem, of the directory to add. 00457 * 00458 * \pre \p parent is non-NULL. 00459 * \pre \p path is non-NULL and is a valid path to a directory on the local 00460 * filesystem. 00461 */ 00462 void iso_tree_radd_dir(struct iso_tree_node_dir *parent, const char *path, 00463 struct iso_tree_radd_dir_behavior *behavior); 00464 00465 /** 00466 * Set the name of a tree node (using the current locale). 00467 */ 00468 void iso_tree_node_set_name(struct iso_tree_node *node, const char *name); 00469 00470 /** 00471 * Set if the node will be hidden in RR/ISO tree, Joliet tree or both. 00472 * 00473 * If the file is setted as hidden in one tree, it won't be included there, so 00474 * it won't be visible in a OS accessing CD using that tree. For example, 00475 * GNU/Linux systems access to Rock Ridge / ISO9960 tree in order to see 00476 * what is recorded on CD, while MS Windows make use of the Joliet tree. If a 00477 * file is hidden only in Joliet, it won't be visible in Windows systems, 00478 * while still visible in Linux. 00479 * 00480 * If a file is hidden in both trees, it won't be written to image. 00481 * 00482 * \param node The node that is to be hidden. 00483 * \param hide_attrs hide_node_flag's to set the trees in which file 00484 * will be hidden. 00485 */ 00486 void iso_tree_node_set_hidden(struct iso_tree_node *node, int hide_attrs); 00487 00488 /** 00489 * Set the group id for the node. This attribute is only useful when 00490 * Rock Ridge extensions are enabled. 00491 */ 00492 void iso_tree_node_set_gid(struct iso_tree_node *node, gid_t gid); 00493 00494 /** 00495 * Set the user id for the node. This attribute is only useful when 00496 * Rock Ridge extensions are enabled. 00497 */ 00498 void iso_tree_node_set_uid(struct iso_tree_node *node, uid_t uid); 00499 00500 /** 00501 * Set the permissions for the node. This attribute is only useful when 00502 * Rock Ridge extensions are enabled. 00503 * 00504 * \param mode bitmask with the permissions of the node, as specified 00505 * in 'man 2 stat'. The file type bitfields will be ignored, 00506 * only file permissions will be modified. 00507 */ 00508 void iso_tree_node_set_permissions(struct iso_tree_node *node, mode_t mode); 00509 00510 /** 00511 * Sets the order in which a node will be written on image. High weihted files 00512 * will be written first, so in a disc them will be written near the center. 00513 * 00514 * \param node The node which weight will be changed. If it's a dir, this 00515 * function will change the weight of all its children. For nodes 00516 * other that dirs or regular files, this function has no effect. 00517 * \param w The weight as a integer number, the greater this value is, the 00518 * closer from the begining of image the file will be written. 00519 */ 00520 void iso_tree_node_set_sort_weight(struct iso_tree_node *node, int w); 00521 00522 /** 00523 * Recursively print a directory to stdout. 00524 * \param spaces The initial number of spaces on the left. Set to 0 if you 00525 * supply a root directory. 00526 */ 00527 void iso_tree_print(const struct iso_tree_node *root, int spaces); 00528 00529 /** Create a burn_source which can be used as a data source for a track 00530 * 00531 * The volume set used to create the libburn_source can _not_ be modified 00532 * until the libburn_source is freed. 00533 * 00534 * \param volumeset The volume set from which you want to write 00535 * \param opts The options for image generation 00536 * 00537 * \pre \p volumeset is non-NULL 00538 * \pre \p volnum is less than \p volset->volset_size. 00539 * \return A burn_source to be used for the data source for a track 00540 */ 00541 struct burn_source* iso_source_new_ecma119(struct iso_volset *volumeset, 00542 struct ecma119_source_opts *opts); 00543 00544 #endif /* LIBISO_LIBISOFS_H */