You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

1158 lines
40 KiB

  1. /* -*- indent-tabs-mode: t; tab-width: 8; c-basic-offset: 8; -*- */
  2. /* vim: set noet ts=8 sts=8 sw=8 : */
  3. /**
  4. * Create an ISO-9660 data volume with Rock Ridge and Joliet extensions.
  5. * Usage is easy:
  6. * - Create a new volume.
  7. * - Add files and directories.
  8. * - Write the volume to a file or create a burn source for use with Libburn.
  9. */
  10. #ifndef LIBISO_LIBISOFS_H
  11. #define LIBISO_LIBISOFS_H
  12. #include <sys/types.h>
  13. #include <stdint.h>
  14. /* #include <libburn.h> */
  15. struct burn_source;
  16. /**
  17. * Data volume.
  18. * @see volume.h for details.
  19. */
  20. struct iso_volume;
  21. /**
  22. * A set of data volumes.
  23. * @see volume.h for details.
  24. */
  25. struct iso_volset;
  26. /**
  27. * A node in the filesystem tree.
  28. *
  29. * This is opaque struct that represent any kind of nodes. When needed,
  30. * you can get the type with iso_tree_node_get_type and cast it to the
  31. * appropiate subtype:
  32. *
  33. * iso_tree_node_dir
  34. * iso_tree_node_file
  35. * iso_tree_node_symlink
  36. *
  37. * \see tree.h
  38. */
  39. struct iso_tree_node;
  40. /**
  41. * The type of an iso_tree_node.
  42. * When an user gets an iso_tree_node from libisofs, (s)he can use
  43. * iso_tree_node_get_type to get the current type of the node, and then
  44. * cast to the appropriate subtype. For example:
  45. *
  46. * ...
  47. * struct iso_tree_node *node = iso_tree_iter_next(iter);
  48. * if ( iso_tree_node_get_type(node) == LIBISO_NODE_DIR ) {
  49. * struct iso_tree_node_dir *dir = (struct iso_tree_node_dir *)node;
  50. * ...
  51. * }
  52. *
  53. * Useful macros are provided.
  54. */
  55. enum iso_tree_node_type {
  56. LIBISO_NODE_DIR,
  57. LIBISO_NODE_FILE,
  58. LIBISO_NODE_SYMLINK,
  59. LIBISO_NODE_BOOT
  60. };
  61. #define LIBISO_ISDIR(n) (iso_tree_node_get_type(n) == LIBISO_NODE_DIR)
  62. #define LIBISO_ISREG(n) (iso_tree_node_get_type(n) == LIBISO_NODE_FILE)
  63. #define LIBISO_ISLNK(n) (iso_tree_node_get_type(n) == LIBISO_NODE_SYMLINK)
  64. /**
  65. * A directory in the filesystem tree.
  66. * The first member of this is an iso_tree_node.
  67. * \see tree.h
  68. */
  69. struct iso_tree_node_dir;
  70. /**
  71. * A node in the filesystem tree that represents a regular file
  72. */
  73. struct iso_tree_node_file;
  74. /**
  75. * A node in the filesystem tree that represents a symbolic link
  76. */
  77. struct iso_tree_node_symlink;
  78. /**
  79. * A node that represents an El-Torito file.
  80. */
  81. struct iso_tree_node_boot;
  82. /**
  83. * Information about El-Torito boot image.
  84. * \see eltorito.h
  85. */
  86. struct el_torito_boot_image;
  87. /** Iterator for dir children. */
  88. struct iso_tree_iter;
  89. /**
  90. * The procedence of the node.
  91. */
  92. enum tree_node_from {
  93. /** The node has been added by the user */
  94. LIBISO_NEW = 0,
  95. /**
  96. * The node comes from a previous image. That can be from a previous
  97. * session on disc, or from an ISO file we want to modify.
  98. */
  99. LIBISO_PREVIMG
  100. };
  101. /**
  102. * Extensions addition to ECMA-119 (ISO-9660) image. Usage of at least
  103. * one of these flags is highly recommended if the disc will be used on a
  104. * modern OS.
  105. */
  106. enum ecma119_extension_flag {
  107. /**
  108. * Add the standard Rock Ridge extensions. This adds POSIX filesystem
  109. * features to the ECMA-119 image. Thus, usage of this flag is highly
  110. * recommended for images used on GNU/Linux systems. With the usage
  111. * of RR extension, the resulting image will have long filenames (up to
  112. * 255 characters), deeper directory structure, POSIX permissions and
  113. * owner info on files and directories, support for symbolic links or
  114. * special files... All that attributes can be modified/setted with the
  115. * appropiate function.
  116. */
  117. ECMA119_ROCKRIDGE = (1<<0),
  118. /**
  119. * Add the non-standard Joliet extension to the image. This extension is
  120. * heavily used in Microsoft Windows systems, so if you plan to use your
  121. * disc on such a system you should add this extension. Usage of Joliet
  122. * supplies longer filesystem length (up to 64 unicode characters), and
  123. * deeper directory structure.
  124. */
  125. ECMA119_JOLIET = (1<<1)
  126. };
  127. /**
  128. * Flag used to hide a file in the RR/ISO or Joliet tree.
  129. *
  130. * \see iso_tree_node_set_hidden
  131. */
  132. enum hide_node_flag {
  133. LIBISO_HIDE_ON_RR = 1 << 0,
  134. LIBISO_HIDE_ON_JOLIET = 1 << 1
  135. };
  136. /**
  137. * El-Torito bootable image type.
  138. */
  139. enum eltorito_boot_media_type {
  140. ELTORITO_FLOPPY_EMUL,
  141. ELTORITO_HARD_DISC_EMUL,
  142. ELTORITO_NO_EMUL
  143. };
  144. /**
  145. * ISO-9660 (ECMA-119) has important restrictions in both file/dir names
  146. * and deep of the directory hierarchy. These are intented for compatibility
  147. * with old systems, and most modern operative system can safety deal with
  148. * ISO filesystems with relaxed constraints.
  149. * You can use some of these flags to generate that kind of filesystems with
  150. * libisofs. Of course, all these options will lead to an image not conforming
  151. * with ISO-9660 specification, so use them with caution.
  152. * Moreover, note that there are much better options to have an ISO-9660 image
  153. * compliant with modern systems, such as the Rock Ridge and Joliet extensions,
  154. * that add support for longer filenames, deeper directory hierarchy and even
  155. * file permissions (in case of RR), while keeping a standard ISO structure
  156. * suitable for old systems.
  157. * Thus, in most cases you don't want to use the relaxed constraints.
  158. */
  159. enum ecma119_relaxed_constraints_flag {
  160. ECMA119_OMIT_VERSION_NUMBERS = (1<<0),
  161. /**<
  162. * ISO-9660 requires a version number at the end of each file name.
  163. * That number is just ignored on most systems, so you can omit them
  164. * if you want.
  165. */
  166. ECMA119_37_CHAR_FILENAMES = (1<<1) | (1<<0),
  167. /**<
  168. * Allow ISO-9660 filenames to be up to 37 characters long. The extra
  169. * space is taken from the version number, so this option involves
  170. * no version number
  171. */
  172. ECMA119_NO_DIR_REALOCATION = (1<<2),
  173. /**<
  174. * In ISO-9660 images the depth of the directory hierarchy can't be
  175. * greater than 8 levels. In addition, a path to a file on disc can't
  176. * be more than 255 characteres. Use the ECMA119_NO_DIR_REALOCATION
  177. * to disable this restriction.
  178. */
  179. ECMA119_RELAXED_FILENAMES = (1<<3)
  180. /**<
  181. * Allow filenames with any character. Note that with this flag, the
  182. * filename provide by the user will be used without any modification
  183. * other that a truncate to max. length.
  184. */
  185. };
  186. /**
  187. * Holds the options for the image generation.
  188. */
  189. struct ecma119_source_opts {
  190. int volnum; /**< The volume in the set which you want to write (usually 0) */
  191. int level; /**< ISO level to write at. */
  192. int flags; /**< Which extensions to support. */
  193. int relaxed_constraints; /**< see ecma119_relaxed_constraints_flag */
  194. unsigned int copy_eltorito:1;
  195. /**<
  196. * In multisession discs, select whether to copy el-torito catalog
  197. * and boot image. Copy is needed for isolinux images, that need to
  198. * be patched. However, it can lead to problems when the image is
  199. * not present in the iso filesystem, because we can't figure out
  200. * its size. In those cases, we only copy 1 block of data.
  201. */
  202. unsigned int no_cache_inodes:1;
  203. /**< If use inode caching or not. Set it to 1 to prevent
  204. * inode caching.
  205. * Usage of inode caching allows detection of hard-links,
  206. * which contents are only written once to disc this way.
  207. * Don't use inode caching in systems with non unique inodes
  208. * per device.
  209. */
  210. unsigned int sort_files:1;
  211. /**< If files should be sorted based on their weight. */
  212. unsigned int default_mode:1;
  213. /**<
  214. * The default values for files and directory permissions,
  215. * gid and uid. This option can be overwritten when set
  216. * one of the following.
  217. * 0 to use useful values, 1 to use node modes (this are
  218. * the same as filesystem ones if not changed after added
  219. * to tree).
  220. */
  221. unsigned int replace_dir_mode:1;
  222. /**<
  223. * When 1, permissions for all dirs will be replaced by the
  224. * specified in dir_mode field.
  225. */
  226. unsigned int replace_file_mode:1;
  227. /**<
  228. * When 1, permissions for all files will be replaced by the
  229. * specified in file_mode field.
  230. */
  231. unsigned int replace_uid:1;
  232. /**<
  233. * When 1, uid of all nodes (both files and dirs) will be
  234. * replaced by the specified in uid field.
  235. */
  236. unsigned int replace_gid:1;
  237. /**<
  238. * When 1, gid of all nodes (both files and dirs) will be
  239. * replaced by the specified in gid field.
  240. */
  241. mode_t dir_mode; /**< Mode to use on dirs when replace_dir_mode is set. */
  242. mode_t file_mode; /**< Mode to use on files when replace_file_mode is set. */
  243. gid_t gid; /**< gid to use when replace_gid is set. */
  244. uid_t uid; /**< uid to use when replace_uid is set. */
  245. char *input_charset; /**< NULL to use default charset */
  246. char *ouput_charset; /**< NULL to use default charset */
  247. uint32_t ms_block;
  248. /**<
  249. * Start block for multisession. When this is greater than 0,
  250. * it's suppossed to be the lba of the next writable address
  251. * on disc; all block lba on image will take this into account,
  252. * and files from a previous session will not be written on
  253. * image. This behavior is only suitable for images to be
  254. * appended to a multisession disc.
  255. * When this is 0, no multisession image will be created. If
  256. * some files are taken from a previous image, its contents
  257. * will be written again to the new image. Use this with new
  258. * images or if you plan to modify an existin image.
  259. */
  260. struct data_source* src;
  261. /**<
  262. * When modifying a image, this is the source of the original
  263. * image, used to read file contents.
  264. * Otherwise it can be NULL.
  265. */
  266. uint8_t *overwrite;
  267. /**<
  268. * When not NULL, it should point to a buffer of at least
  269. * 64KiB, where libisofs will write the contents that should
  270. * be written at the beginning of a overwriteable media, to
  271. * grow the image.
  272. * You shoudl initialize the buffer either with 0s, or with
  273. * the contents of the first blocks of the image you're
  274. * growing. In most cases, 0 is good enought.
  275. */
  276. };
  277. /**
  278. * Options for image reading.
  279. * There are four kind of options:
  280. * - Related to multisession support.
  281. * In most cases, an image begins at LBA 0 of the data source. However,
  282. * in multisession discs, the later image begins in the last session on
  283. * disc. The block option can be used to specify the start of that last
  284. * session.
  285. * - Related to the tree that will be read.
  286. * As default, when Rock Ridge extensions are present in the image, that
  287. * will be used to get the tree. If RR extensions are not present, libisofs
  288. * will use the Joliet extensions if available. Finally, the plain ISO-9660
  289. * tree is used if neither RR nor Joliet extensions are available. With
  290. * norock, nojoliet, and preferjoliet options, you can change this
  291. * default behavior.
  292. * - Related to default POSIX attributes.
  293. * When Rock Ridege extensions are not used, libisofs can't figure out what
  294. * are the the permissions, uid or gid for the files. You should supply
  295. * default values for that.
  296. * - Return information for image.
  297. * Both size, hasRR and hasJoliet will be filled by libisofs with suitable values.
  298. * Also, error is set to non-0 if some error happens (error codes are
  299. * private now)
  300. */
  301. struct ecma119_read_opts {
  302. uint32_t block; /** Block where the image begins, usually 0, can be
  303. * different on a multisession disc.
  304. */
  305. unsigned int norock:1; /*< Do not read Rock Ridge extensions */
  306. unsigned int nojoliet:1; /*< Do not read Joliet extensions */
  307. unsigned int preferjoliet:1;
  308. /*< When both Joliet and RR extensions are present, the RR
  309. * tree is used. If you prefer using Joliet, set this to 1. */
  310. uid_t uid; /**< Default uid when no RR */
  311. gid_t gid; /**< Default uid when no RR */
  312. mode_t mode; /**< Default mode when no RR (only permissions) */
  313. //TODO differ file and dir mode
  314. //option to convert names to lower case?
  315. /* modified by the function */
  316. unsigned int hasRR:1; /*< It will be set to 1 if RR extensions are present,
  317. to 0 if not. */
  318. unsigned int hasJoliet:1; /*< It will be set to 1 if Joliet extensions are
  319. present, to 0 if not. */
  320. uint32_t size; /**< Will be filled with the size (in 2048 byte block) of
  321. * the image, as reported in the PVM. */
  322. int error;
  323. };
  324. /**
  325. * Data source used by libisofs for reading an existing image.
  326. * It contains suitable methods to read arbitrary block. Usually, the block
  327. * size is 2048 bytes.
  328. */
  329. struct data_source {
  330. /**
  331. * Reference count for the data source. Should be 1 when a new source
  332. * is created. Increment it to take a reference for yourself. Use
  333. * data_source_free to destroy your reference to it.
  334. */
  335. int refcount;
  336. /**
  337. * Read data from the source.
  338. * @param lba Block to be read.
  339. * @param buffer Buffer where the data will be written. Its size must
  340. * be at least 2048 bytes.
  341. * @return
  342. * 0 if ok, < 0 on error
  343. */
  344. int (*read_block)(struct data_source *src, int lba, unsigned char *buffer);
  345. /** Get the size (number of block) of the source's data */
  346. int (*get_size)(struct data_source *);
  347. /** Clean up the source specific data */
  348. void (*free_data)(struct data_source *);
  349. /** Source specific data */
  350. void *data;
  351. };
  352. /**
  353. * This will hold the error code for some functions, if them fail.
  354. */
  355. int libisofs_errno;
  356. /* an unexpected internal error */
  357. #define INTERNAL_ERROR -1
  358. /* file don't exists, or can't be stat'ed */
  359. #define NO_FILE 1
  360. /* user haven't read access to file */
  361. #define NO_READ_ACCESS 2
  362. /* unexpected file type, eg., passing a dir instead of a regular file */
  363. #define UNEXPECTED_FILE_TYPE 3
  364. /* invalid boot image size */
  365. #define ELTORITO_WRONG_IMAGE_SIZE 4
  366. /* invalid image */
  367. #define ELTORITO_WRONG_IMAGE 5
  368. /**
  369. * Controls the bahavior of iso_tree_radd_dir function
  370. */
  371. struct iso_tree_radd_dir_behavior {
  372. char** excludes; /**< List of paths (file or directory) to be ignored. */
  373. //int follow_sym_link;
  374. int stop_on_error; /**< Stop when an error was found?. */
  375. int error; /**< set to 1 on error */
  376. //int notify_errors;
  377. //char** errors;
  378. };
  379. /**
  380. * Initialize libisofs. You must call this before any usage of the library.
  381. * @return 1 on success, 0 on error
  382. */
  383. int iso_init();
  384. /**
  385. * Finalize libisofs.
  386. */
  387. void iso_finish();
  388. /**
  389. * Create a new volume.
  390. * The parameters can be set to NULL if you wish to set them later.
  391. */
  392. struct iso_volume *iso_volume_new(const char *volume_id,
  393. const char *publisher_id,
  394. const char *data_preparer_id);
  395. struct iso_volume *iso_volume_new_with_root(const char *volume_id,
  396. const char *publisher_id,
  397. const char *data_preparer_id,
  398. struct iso_tree_node_dir *root);
  399. /**
  400. * Free a volume.
  401. */
  402. void iso_volume_free(struct iso_volume *volume);
  403. void iso_volset_ref(struct iso_volset *volset);
  404. /**
  405. * Free a set of data volumes.
  406. */
  407. void iso_volset_free(struct iso_volset *volume);
  408. /**
  409. * Get a volume from a volume set.
  410. */
  411. struct iso_volume *iso_volset_get_volume(struct iso_volset *volset, int volnum);
  412. /**
  413. * Get the root directory for a volume.
  414. */
  415. struct iso_tree_node_dir *iso_volume_get_root(const struct iso_volume *volume);
  416. /**
  417. * Fill in the volume identifier for a volume.
  418. */
  419. void iso_volume_set_volume_id(struct iso_volume *volume,
  420. const char *volume_id);
  421. /**
  422. * Get the volume identifier.
  423. * The returned string is owned by libisofs and should not be freed nor
  424. * changed.
  425. */
  426. const char *iso_volume_get_volume_id(struct iso_volume *volume);
  427. /**
  428. * Fill in the publisher for a volume.
  429. */
  430. void iso_volume_set_publisher_id(struct iso_volume *volume,
  431. const char *publisher_id);
  432. /**
  433. * Get the publisher of a volume.
  434. * The returned string is owned by libisofs and should not be freed nor
  435. * changed.
  436. */
  437. const char *iso_volume_get_publisher_id(struct iso_volume *volume);
  438. /**
  439. * Fill in the data preparer for a volume.
  440. */
  441. void iso_volume_set_data_preparer_id(struct iso_volume *volume,
  442. const char *data_preparer_id);
  443. /**
  444. * Get the data preparer of a volume.
  445. * The returned string is owned by libisofs and should not be freed nor
  446. * changed.
  447. */
  448. const char *iso_volume_get_data_preparer_id(struct iso_volume *volume);
  449. /**
  450. * Fill in the system id for a volume. Up to 32 characters.
  451. */
  452. void iso_volume_set_system_id(struct iso_volume *volume,
  453. const char *system_id);
  454. /**
  455. * Get the system id of a volume.
  456. * The returned string is owned by libisofs and should not be freed nor
  457. * changed.
  458. */
  459. const char *iso_volume_get_system_id(struct iso_volume *volume);
  460. /**
  461. * Fill in the application id for a volume. Up to 128 chars.
  462. */
  463. void iso_volume_set_application_id(struct iso_volume *volume,
  464. const char *application_id);
  465. /**
  466. * Get the application id of a volume.
  467. * The returned string is owned by libisofs and should not be freed nor
  468. * changed.
  469. */
  470. const char *iso_volume_get_application_id(struct iso_volume *volume);
  471. /**
  472. * Fill copyright information for the volume. Usually this refers
  473. * to a file on disc. Up to 37 characters.
  474. */
  475. void iso_volume_set_copyright_file_id(struct iso_volume *volume,
  476. const char *copyright_file_id);
  477. /**
  478. * Get the copyright information of a volume.
  479. * The returned string is owned by libisofs and should not be freed nor
  480. * changed.
  481. */
  482. const char *iso_volume_get_copyright_file_id(struct iso_volume *volume);
  483. /**
  484. * Fill abstract information for the volume. Usually this refers
  485. * to a file on disc. Up to 37 characters.
  486. */
  487. void iso_volume_set_abstract_file_id(struct iso_volume *volume,
  488. const char *abstract_file_id);
  489. /**
  490. * Get the abstract information of a volume.
  491. * The returned string is owned by libisofs and should not be freed nor
  492. * changed.
  493. */
  494. const char *iso_volume_get_abstract_file_id(struct iso_volume *volume);
  495. /**
  496. * Fill biblio information for the volume. Usually this refers
  497. * to a file on disc. Up to 37 characters.
  498. */
  499. void iso_volume_set_biblio_file_id(struct iso_volume *volume,
  500. const char *biblio_file_id);
  501. /**
  502. * Get the biblio information of a volume.
  503. * The returned string is owned by libisofs and should not be freed nor
  504. * changed.
  505. */
  506. const char *iso_volume_get_biblio_file_id(struct iso_volume *volume);
  507. /**
  508. * Create a bootable volume by adding a El-Torito boot image.
  509. *
  510. * This also add a catalog tree node to the image filesystem tree. The tree
  511. * node for the image will be replaced with a iso_tree_node_boot node, that
  512. * acts as a placeholder for the real image.
  513. *
  514. * \param volume The volume to make bootable.
  515. * \param image The tree node with the file to use as default boot image.
  516. * \param type The boot media type. This can be one of 3 types:
  517. * - Floppy emulation: Boot image files must be exactly
  518. * 1200 kB, 1440 kB or 2880 kB.
  519. * - Hard disc emulation: The image must begin with a master
  520. * boot record with a single image.
  521. * - No emulation. You should specify load segment and load size
  522. * of image.
  523. * \param dir The directory node where the boot catalog will be located
  524. * in image. Usually both boot catalog and boot image will be
  525. * located in the same dir, maybe /boot.
  526. * \param name The name of the boot catalog.
  527. *
  528. * \return The default El-Torito bootable image. If specified image file
  529. * seems to be not correct, this returns NULL and libisofs_errno
  530. * is set propertly.
  531. *
  532. * \pre \p volume is a volume without any boot catalog yet
  533. * \pre \p image is a file tree node already inserted in the volume tree.
  534. * \pre \p image is a file tree node that refers to a newly added file, not
  535. * one from a previous session. FIXME allow prev session files too
  536. * \pre \p dir is a directory node already inserted in the volume tree.
  537. * \pre \p name There isn't any dir child with the same name.
  538. *
  539. */
  540. struct el_torito_boot_image*
  541. iso_volume_set_boot_image(struct iso_volume *volume,
  542. struct iso_tree_node *image,
  543. enum eltorito_boot_media_type type,
  544. struct iso_tree_node_dir *dir,
  545. char *name);
  546. struct el_torito_boot_image*
  547. iso_volume_set_boot_image_hidden(struct iso_volume *volume,
  548. const char* path,
  549. enum eltorito_boot_media_type type);
  550. /**
  551. * Get El-Torito boot image of the volume, if any.
  552. *
  553. * This can be useful, for example, to check if a volume read from a previous
  554. * session or an existing image is bootable. It can also be useful to get
  555. * the image and catalog tree nodes. An application would want those, for
  556. * example, to prevent the user removing it.
  557. *
  558. * Both tree nodes are owned by libisofs and should not be freed. You can check
  559. * if the node is already on the tree by getting its parent (note that when
  560. * reading El-Torito info from a previous image, the nodes might not be on
  561. * the tree even if you haven't removed them). Remember that you'll need to
  562. * get a new ref (with iso_tree_node_ref()) before inserting them again to the
  563. * tree, and probably you will also need to set the name or permissions.
  564. *
  565. * \param imgnode When not NULL, it will be filled with the image tree node, if
  566. * any.
  567. * \param catnode When not NULL, it will be filled with the catalog tree node,
  568. * if any.
  569. *
  570. * \return The default El-Torito bootable image, or NULL is the volume is not
  571. * bootable.
  572. */
  573. struct el_torito_boot_image*
  574. iso_volume_get_boot_image(struct iso_volume *volume,
  575. struct iso_tree_node **imgnode,
  576. struct iso_tree_node **catnode);
  577. /**
  578. * Removes the El-Torito bootable image. Both the catalog and image tree nodes
  579. * are also removed from the image filesystem tree, if there.
  580. * If the volume is not bootable (don't have el-torito image) this function is
  581. * a nop.
  582. */
  583. void
  584. iso_volume_remove_boot_image(struct iso_volume *volume);
  585. /**
  586. * Sets the load segment for the initial boot image. This is only for
  587. * no emulation boot images, and is a NOP for other image types.
  588. */
  589. void
  590. el_torito_set_load_seg(struct el_torito_boot_image *bootimg, int segment);
  591. /**
  592. * Sets the number of sectors (512b) to be load at load segment during
  593. * the initial boot procedure. This is only for
  594. * no emulation boot images, and is a NOP for other image types.
  595. */
  596. void
  597. el_torito_set_load_size(struct el_torito_boot_image *bootimg, int sectors);
  598. /**
  599. * Marks the specified boot image as not bootable
  600. */
  601. void
  602. el_torito_set_no_bootable(struct el_torito_boot_image *bootimg);
  603. /**
  604. * Specifies that this image needs to be patched. This involves the writting
  605. * of a 56 bytes boot information table at offset 8 of the boot image file.
  606. * The original boot image file won't be modified.
  607. * This is needed for isolinux boot images.
  608. */
  609. void
  610. el_torito_patch_isolinux_image(struct el_torito_boot_image *bootimg);
  611. /**
  612. * Locate a node by its path on disc.
  613. *
  614. * \param volume The volume to search in.
  615. * \param path The path, in the image, of the file.
  616. *
  617. * \return The node found or NULL.
  618. */
  619. struct iso_tree_node *iso_tree_volume_path_to_node(struct iso_volume *volume, const char *path);
  620. /**
  621. * TODO I don't like this kind of functions here. I think it should be
  622. * in genisofs
  623. * Add a file or a directory (recursively) to a volume by specifying its path on the volume.
  624. *
  625. * \param volume The volume to add the file to.
  626. * \param disc_path The path on the disc at which to add the disc.
  627. * \param path The path, on the local filesystem, of the file.
  628. *
  629. * \return The node for the file or NULL if the parent doesn't exists on the disc.
  630. */
  631. //struct iso_tree_node *iso_tree_volume_add_path(struct iso_volume *volume,
  632. // const char *disc_path,
  633. // const char *path);
  634. /**
  635. * TODO I don't like this kind of functions here. I think it should be
  636. * in genisofs
  637. * Creates a new, empty directory on the volume.
  638. *
  639. * \param volume The volume to add the directory to.
  640. * \param disc_path The path on the volume at which to add the directory.
  641. *
  642. * \return A pointer to the newly created directory.
  643. */
  644. //struct iso_tree_node *iso_tree_volume_add_new_dir(struct iso_volume *volume,
  645. // const char *disc_path);
  646. /**
  647. * Create a new Volume Set consisting of only one volume.
  648. * @param volume The first and only volume for the volset to contain.
  649. * @param volset_id The Volume Set ID.
  650. * @return A new iso_volset.
  651. */
  652. struct iso_volset *iso_volset_new(struct iso_volume *volume,
  653. const char *volset_id);
  654. /**
  655. * Creates a new root dir for a filesystem tree
  656. */
  657. struct iso_tree_node_dir *iso_tree_new_root();
  658. /**
  659. * Add a file to a directory.
  660. *
  661. * \param path The path, on the local filesystem, of the file.
  662. *
  663. * \pre \p parent is non-NULL.
  664. * \pre \p path is non-NULL.
  665. * \return An iso_tree_node_file whose path is \p path and whose parent is
  666. * \p parent.
  667. * On error, returns NULL and libisofs_errno is set appropriately:
  668. * NO_FILE if path doesn't point to a valid file.
  669. * NO_READ_ACCESS if user haven't read access on file
  670. * UNEXPECTED_FILE_TYPE if path doesn't point to a regular file
  671. */
  672. struct iso_tree_node *iso_tree_add_file(struct iso_tree_node_dir *parent,
  673. const char *path);
  674. /**
  675. * Add a symbolic link to a directory.
  676. *
  677. * \param name The name of the symbolic link
  678. * \param dest The distination of the link, i.e., the file this link points
  679. * to
  680. *
  681. * \pre \p parent, name and dest are non-NULL.
  682. *
  683. * \return An iso_tree_node_symlink
  684. */
  685. struct iso_tree_node *iso_tree_add_symlink(struct iso_tree_node_dir *parent,
  686. const char *name, const char *dest);
  687. /**
  688. * Add a new, empty directory to the tree.
  689. *
  690. * \pre \p parent is non-NULL.
  691. * \pre \p name is unique among the children and files belonging to \p parent.
  692. * Also, it doesn't contain '/' characters.
  693. *
  694. * \post \p parent contains a child directory whose name is \p name and whose
  695. * POSIX attributes are the same as \p parent's.
  696. * \return a pointer to the newly created directory.
  697. */
  698. struct iso_tree_node_dir *iso_tree_add_dir(struct iso_tree_node_dir *parent,
  699. const char *name);
  700. /* TODO iso_tree_new_special */
  701. /**
  702. * Add a file to a directory.
  703. *
  704. * \param path The path, on the local filesystem, of the file.
  705. *
  706. * \pre \p parent is non-NULL.
  707. * \pre \p path is non-NULL and is a valid path to a file or directory on the local
  708. * filesystem.
  709. * \return An iso_tree_node whose path is \p path and whose parent is \p parent.
  710. * On error, returns NULL and libisofs_errno is set appropriately:
  711. * NO_FILE if path doesn't point to a valid file.
  712. * NO_READ_ACCESS if user haven't read access on file
  713. * UNEXPECTED_FILE_TYPE if path refers to non supported file type
  714. * (at the momment, only dirs, symlinks and regular
  715. * files are supported).
  716. */
  717. struct iso_tree_node *iso_tree_add_node(struct iso_tree_node_dir *parent,
  718. const char *path);
  719. /**
  720. * TODO I don't like this kind of functions here. I think it should be
  721. * in genisofs
  722. *
  723. * Recursively add an existing directory to the tree.
  724. * Warning: when using this, you'll lose pointers to files or subdirectories.
  725. * If you want to have pointers to all files and directories,
  726. * use iso_tree_add_file, iso_tree_add_node and iso_tree_add_dir.
  727. *
  728. * \param path The path, on the local filesystem, of the directory to add.
  729. *
  730. * \pre \p parent is non-NULL.
  731. * \pre \p path is non-NULL and is a valid path to a directory on the local
  732. * filesystem.
  733. */
  734. void iso_tree_radd_dir(struct iso_tree_node_dir *parent, const char *path,
  735. struct iso_tree_radd_dir_behavior *behavior);
  736. /**
  737. * Get the type of an iso_tree_node
  738. */
  739. enum iso_tree_node_type iso_tree_node_get_type(struct iso_tree_node *node);
  740. /**
  741. * Set the name of a tree node (using the current locale).
  742. */
  743. void iso_tree_node_set_name(struct iso_tree_node *node, const char *name);
  744. /**
  745. * Get the name of a tree node (using the current locale).
  746. * The returned string belongs to the node and should not be modified nor
  747. * freed. Use strdup if you really need your own copy.
  748. */
  749. const char *iso_tree_node_get_name(struct iso_tree_node *node);
  750. /**
  751. * Set if the node will be hidden in RR/ISO tree, Joliet tree or both.
  752. *
  753. * If the file is setted as hidden in one tree, it won't be included there, so
  754. * it won't be visible in a OS accessing CD using that tree. For example,
  755. * GNU/Linux systems access to Rock Ridge / ISO9960 tree in order to see
  756. * what is recorded on CD, while MS Windows make use of the Joliet tree. If a
  757. * file is hidden only in Joliet, it won't be visible in Windows systems,
  758. * while still visible in Linux.
  759. *
  760. * If a file is hidden in both trees, it won't be written to image.
  761. *
  762. * \param node The node that is to be hidden.
  763. * \param hide_attrs hide_node_flag's to set the trees in which file
  764. * will be hidden.
  765. */
  766. void iso_tree_node_set_hidden(struct iso_tree_node *node, int hide_attrs);
  767. /**
  768. * Check if a node will be hidden in RR/ISO tree, Joliet tree or both.
  769. *
  770. * @return
  771. * 0 if the node won't be hidden, otherwise you can AND the return value
  772. * with hide_node_flag's to get in what trees the node will be hidden.
  773. */
  774. int iso_tree_node_is_hidden(struct iso_tree_node *node);
  775. /**
  776. * Set the group id for the node. This attribute is only useful when
  777. * Rock Ridge extensions are enabled.
  778. */
  779. void iso_tree_node_set_gid(struct iso_tree_node *node, gid_t gid);
  780. /**
  781. * Get the group id of the node.
  782. */
  783. gid_t iso_tree_node_get_gid(struct iso_tree_node *node);
  784. /**
  785. * Set the user id for the node. This attribute is only useful when
  786. * Rock Ridge extensions are enabled.
  787. */
  788. void iso_tree_node_set_uid(struct iso_tree_node *node, uid_t uid);
  789. /**
  790. * Get the user id of the node.
  791. */
  792. uid_t iso_tree_node_get_uid(struct iso_tree_node *node);
  793. /**
  794. * Set the permissions for the node. This attribute is only useful when
  795. * Rock Ridge extensions are enabled.
  796. *
  797. * \param mode bitmask with the permissions of the node, as specified
  798. * in 'man 2 stat'. The file type bitfields will be ignored,
  799. * only file permissions will be modified.
  800. */
  801. void iso_tree_node_set_permissions(struct iso_tree_node *node, mode_t mode);
  802. /** Get the permissions for the node */
  803. mode_t iso_tree_node_get_permissions(struct iso_tree_node *node);
  804. /** Get the size of the node, in bytes */
  805. off_t iso_tree_node_get_size(struct iso_tree_node *node);
  806. /** Set the time of last modification of the file */
  807. void iso_tree_node_set_mtime(struct iso_tree_node *node, time_t time);
  808. /** Get the time of last modification of the file */
  809. time_t iso_tree_node_get_mtime(struct iso_tree_node *node);
  810. /** Set the time of last access to the file */
  811. void iso_tree_node_set_atime(struct iso_tree_node *node, time_t time);
  812. /** Get the time of last access to the file */
  813. time_t iso_tree_node_get_atime(struct iso_tree_node *node);
  814. /** Set the time of last status change of the file */
  815. void iso_tree_node_set_ctime(struct iso_tree_node *node, time_t time);
  816. /** Get the time of last status change of the file */
  817. time_t iso_tree_node_get_ctime(struct iso_tree_node *node);
  818. /**
  819. * Sets the order in which a node will be written on image. High weihted files
  820. * will be written first, so in a disc them will be written near the center.
  821. *
  822. * \param node The node which weight will be changed. If it's a dir, this
  823. * function will change the weight of all its children. For nodes
  824. * other that dirs or regular files, this function has no effect.
  825. * \param w The weight as a integer number, the greater this value is, the
  826. * closer from the begining of image the file will be written.
  827. */
  828. void iso_tree_node_set_sort_weight(struct iso_tree_node *node, int w);
  829. /**
  830. * Sets the destination of a symbolic link
  831. */
  832. void iso_tree_node_symlink_set_dest(struct iso_tree_node_symlink *node, const char *dest);
  833. /**
  834. * Get the destination of a symbolic link.
  835. * The returned string is owned by libisofs and should not be freed nor modified.
  836. */
  837. const char *iso_tree_node_symlink_get_dest(struct iso_tree_node_symlink *node);
  838. /**
  839. * Get an iterator for the children of the given dir.
  840. * You can iterate over the children with iso_tree_iter_next. When finished,
  841. * you should free the iterator with iso_tree_iter_free.
  842. * You musn't delete a child of the same dir, using iso_tree_node_take() or
  843. * iso_tree_node_remove(), while you're using the iterator. You can use
  844. * iso_tree_node_take_iter() or iso_tree_node_remove_iter() instead.
  845. *
  846. * The usage of an iterator is:
  847. *
  848. * struct iso_tree_iter *iter;
  849. * struct iso_tree_node *node;
  850. * iter = iso_tree_node_children(dir);
  851. * while ( (node = iso_tree_iter_next(iter)) != NULL ) {
  852. * // do something with the child
  853. * }
  854. * iso_tree_iter_free(iter);
  855. *
  856. * An iterator is intended to be used in a single iteration over the
  857. * children of a dir. Thus, it should be treated as a temporary object,
  858. * and free as soon as possible.
  859. */
  860. struct iso_tree_iter *iso_tree_node_children(struct iso_tree_node_dir *dir);
  861. /**
  862. * Get the next child.
  863. * Take care that the node is owned by libisofs, and will be freed whit the
  864. * tree it belongs. If you want your own ref to it, call iso_tree_node_ref()
  865. * on it.
  866. * This returns NULL if no more children are available.
  867. */
  868. struct iso_tree_node *iso_tree_iter_next(struct iso_tree_iter *iter);
  869. /**
  870. * Check if there're more children.
  871. * @return
  872. * 1 if next call to iso_tree_iter_next() will return != NULL,
  873. * 0 otherwise
  874. */
  875. int iso_tree_iter_has_next(struct iso_tree_iter *iter);
  876. /** Free an iteration */
  877. void iso_tree_iter_free(struct iso_tree_iter *iter);
  878. /**
  879. * Removes a child from a directory.
  880. * The child is not freed, so you will become the owner of the node. Later
  881. * you can add the node to another dir (calling iso_tree_add_child), or free
  882. * it if you don't need it (with iso_tree_free).
  883. *
  884. * @return 0 on success, -1 if the node doesn't belong to the dir.
  885. */
  886. int iso_tree_node_take(struct iso_tree_node_dir *dir,
  887. struct iso_tree_node *node);
  888. /**
  889. * Removes a child from a directory and free (unref) it.
  890. * If you want to keep the child alive, you need to iso_tree_node_ref() it
  891. * before this call, but in that case iso_tree_node_take() is a better
  892. * alternative.
  893. *
  894. * @return 0 on success, -1 if the node doesn't belong to the dir (in this
  895. * last case the node is not freed).
  896. */
  897. int iso_tree_node_remove(struct iso_tree_node_dir *dir,
  898. struct iso_tree_node *node);
  899. /**
  900. * Removes a child from a directory during an iteration, without freeing it.
  901. * It's like iso_tree_node_take(), but to be used during a directory
  902. * iteration.
  903. * The node removed will be the last returned by the iteration.
  904. *
  905. * The behavior on two call to this function without calling iso_tree_iter_next
  906. * between then is undefined, and should never occur. (TODO protect against this?)
  907. *
  908. * @return 0 on success, < 0 on an invalid usage, i.e., if the user call this
  909. * before an inicial iso_tree_iter_next() or if last
  910. * iso_tree_iter_next() has returned NULL.
  911. */
  912. int iso_tree_node_take_iter(struct iso_tree_iter *iter);
  913. /**
  914. * Removes a child from a directory during an iteration and free it.
  915. * It's like iso_tree_node_remove(), but to be used during a directory
  916. * iteration.
  917. * The node removed will be the last returned by the iteration.
  918. *
  919. * The behavior on two call to this function without calling iso_tree_iter_next
  920. * between then is undefined, and should never occur. (TODO protect against this?)
  921. *
  922. * @return 0 on success, < 0 on an invalid usage, i.e., if the user call this
  923. * before an inicial iso_tree_iter_next() or if last
  924. * iso_tree_iter_next() has returned NULL.
  925. */
  926. int iso_tree_node_remove_iter(struct iso_tree_iter *iter);
  927. /*
  928. * Get the parent of the given iso tree node.
  929. * This returns NULL if the node is the root of the tree, or is a node
  930. * that doesn't pertain to any tree (it was removed/take)
  931. */
  932. struct iso_tree_node_dir *iso_tree_node_get_parent(struct iso_tree_node *node);
  933. /**
  934. * Adds a child to a directory.
  935. * The child will be freed when the parent is freed, so you must be the
  936. * owner of the child (maybe calling iso_tree_node_ref) before calling this.
  937. *
  938. * \pre parent has no child with the same name as \p child
  939. */
  940. void iso_tree_add_child(struct iso_tree_node_dir *parent,
  941. struct iso_tree_node *child);
  942. /**
  943. * Increments the reference counting of the given node.
  944. * If you call this, you must remember call iso_tree_free when the
  945. * node is no more needed.
  946. */
  947. void iso_tree_node_ref(struct iso_tree_node *node);
  948. /**
  949. * Recursively free a directory.
  950. *
  951. * \param root The root of the directory heirarchy to free.
  952. *
  953. * \pre \p root is non-NULL.
  954. */
  955. void iso_tree_free(struct iso_tree_node *root);
  956. /**
  957. * Recursively print a directory to stdout.
  958. * \param spaces The initial number of spaces on the left. Set to 0 if you
  959. * supply a root directory.
  960. */
  961. void iso_tree_print(const struct iso_tree_node *root, int spaces);
  962. /** Create a burn_source which can be used as a data source for a track
  963. *
  964. * The volume set used to create the libburn_source can _not_ be modified
  965. * until the libburn_source is freed.
  966. *
  967. * \param volumeset The volume set from which you want to write
  968. * \param opts The options for image generation
  969. *
  970. * \pre \p volumeset is non-NULL
  971. * \pre \p volnum is less than \p volset->volset_size.
  972. * \return A burn_source to be used for the data source for a track
  973. */
  974. struct burn_source* iso_source_new_ecma119(struct iso_volset *volumeset,
  975. struct ecma119_source_opts *opts);
  976. /**
  977. * Creates a new data source from the given file.
  978. *
  979. * Returns NULL on error
  980. */
  981. struct data_source *data_source_from_file(const char *path);
  982. /** Free a given data source (decrease its refcount and maybe free it) */
  983. void data_source_free(struct data_source*);
  984. /**
  985. * Read an existing ISO image.
  986. *
  987. * TODO documentar
  988. */
  989. struct iso_volset *iso_volset_read(struct data_source *src,
  990. struct ecma119_read_opts *opts);
  991. /**
  992. * Control queueing and stderr printing of messages from libisofs.
  993. * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
  994. * "NOTE", "UPDATE", "DEBUG", "ALL".
  995. *
  996. * @param queue_severity Gives the minimum limit for messages to be queued.
  997. * Default: "NEVER". If you queue messages then you
  998. * must consume them by iso_msgs_obtain().
  999. * @param print_severity Does the same for messages to be printed directly
  1000. * to stderr.
  1001. * @param print_id A text prefix to be printed before the message.
  1002. * @return >0 for success, <=0 for error
  1003. */
  1004. int iso_msgs_set_severities(char *queue_severity,
  1005. char *print_severity, char *print_id);
  1006. #define ISO_MSGS_MESSAGE_LEN 4096
  1007. /**
  1008. * Obtain the oldest pending libisofs message from the queue which has at
  1009. * least the given minimum_severity. This message and any older message of
  1010. * lower severity will get discarded from the queue and is then lost forever.
  1011. *
  1012. * Severity may be one of "NEVER", "FATAL", "SORRY", "WARNING", "HINT",
  1013. * "NOTE", "UPDATE", "DEBUG", "ALL". To call with minimum_severity "NEVER"
  1014. * will discard the whole queue.
  1015. *
  1016. * @param error_code Will become a unique error code as listed in messages.h
  1017. * @param msg_text Must provide at least ISO_MSGS_MESSAGE_LEN bytes.
  1018. * @param os_errno Will become the eventual errno related to the message
  1019. * @param severity Will become the severity related to the message and
  1020. * should provide at least 80 bytes.
  1021. * @return 1 if a matching item was found, 0 if not, <0 for severe errors
  1022. */
  1023. int iso_msgs_obtain(char *minimum_severity,
  1024. int *error_code, char msg_text[], int *os_errno,
  1025. char severity[]);
  1026. /** Return the messenger object handle used by libisofs. This handle
  1027. may be used by related libraries to replace their own compatible
  1028. messenger objects and thus to direct their messages to the libisofs
  1029. message queue. See also: libburn, API function burn_set_messenger().
  1030. @return the handle. Do only use with compatible
  1031. */
  1032. void *iso_get_messenger(void);
  1033. #endif /* LIBISO_LIBISOFS_H */