LIBISOBURN(3)

NAME
libisoburn - frontend library for libburn and libisofs, implementation of xorriso

SYNOPSIS
#include <stdint.h>
#if __WORDSIZE == 32
#  define _LARGEFILE_SOURCE 1
#  define _FILE_OFFSET_BITS 64
#endif
#include <libburn/libburn.h>
#include <libisofs/libisofs.h>
#include <libisoburn/libisoburn.h>
int main(int argc, char *argv[]) {
    char errmsg[1024];
    if (!isoburn_initialize(errmsg, 0)) {
        printf("Failure: %s., errmsg);
        return 1;
    }
    /*
     * Read, write, or modify your images.
     *
     * TODO: Code simple use-cases relevant for 'read' and 'modify'.
     */
    isoburn_finish();
    return 0;
}

DESCRIPTION
Libisoburn can be seen as a wrapper library of libisofs(3) and of libburn(3), simplifying their usage. This manual page does not intend to present the complete picture for an application programmer, but intends to give some select impressions of a simple use case, and where all further information can be collected from the documentation found in the three relevant header files.

The complete API is documented in '<libisoburn/libisoburn.h>'.

There is a high level API present in '<libisoburn/xorriso.h>', which implements xorriso(1). See 'xorriso/xorriso_main.c' in the source code of libisoburn.
Do not mix the use of both APIs.

A function catalogue, where the library functions are loosely grouped according to their inherent purpose, aims at making this manual page useful as a quick reference.

FUNCTION CATALOGUE
/*
 * Versioning
 */
void isoburn_version(int *major, int *minor, int *micro);
int isoburn_is_compatible(int major, int minor, int micro, int __unused);
int isoburn_libburn_req(int *major, int *minor, int *micro);
int isoburn_libisofs_req(int *major, int *minor, int *micro);
int isoburn_libjte_req(int *major, int *minor, int *micro);
/*
 * Initiate and finalize library runtime environment.
 */
int isoburn_initialize(char errmsg[1024], int __unused);
void isoburn_finish(void);
/*
 * Message handling for diagnosis.
 */
typedef messenger int (*msgs_submit)(void *handle, int error_code,
                                     char msg_text[], int os_errno,
                                     char severity[], int flag);
int isoburn_set_msgs_submit(messenger msgs_submit, void *submit_handle,
                            int submit_flag, int __unused);
int isoburn_drive_set_msgs_submit(struct burn_drive *d, messenger msgs_submit,
                                  void *submit_handle, int submit_flag,
                                  int __unused);
/*
 * Capabilities and status.
 */
enum burn_disc_status isoburn_disc_get_status(struct burn_drive *drive);
int isoburn_disc_erasable(struct burn_drive *d);
int isoburn_needs_emulation(struct burn_drive *d);
int isoburn_drive_wrote_well(struct burn_drive *d);
int isoburn_get_fifo_status(struct burn_drive *d, int *size, int *free_bytes,
                            char **status_text);
/*
 * Acquisition of images and of physical equipment.
 */
int isoburn_drive_scan_and_grab(struct burn_drive_info *drive_infos[],
                                char* adr, int load);
int isoburn_drive_aquire(struct burn_drive_info *drive_infos[],
                         char* adr, int flag);
int isoburn_drive_grab(struct burn_drive *drive, int load);
void isoburn_drive_release(struct burn_drive *drive, int eject);
int burn_drive_info_forget(struct burn_drive_info *drive_info, int force);
void burn_drive_info_free(struct burn_drive_info drive_infos[]);
/*
 * Image reading.
 */
IsoImage *isoburn_get_attached_image(struct burn_drive *d);
int isoburn_read_image(struct burn_drive *d,
                       struct isoburn_read_opts *read_opts,
                       IsoImage **image);
int isoburn_set_read_pacifier(struct burn_drive *drive,
                              int (*read_pacifier)(IsoImage*, IsoFileSource*),
                              void *app_handle);
int isoburn_attach_image(struct burn_drive *d, IsoImage *image);
int isoburn_get_img_partition_offset(struct burn_drive *drive,
                                     uint32_t *block_offset_2k);
/*
 * Image writing.
 */
int isoburn_sync_after_write(struct burn_drive *input_drive,
                             struct burn_drive *output_drive, int flag);
int isoburn_activate_session(struct burn_drive *d);
void isoburn_disc_erase(struct burn_drive *drive, int fast);
int isoburn_set_truncate(struct burn_drive *drive, int flag);
void isoburn_disc_write(struct burn_write_opts *o, struct burn_disc *disc);
off_t isoburn_disc_available_space(struct burn_drive *d,
                                   struct burn_write_opts *o);
int isoburn_disc_get_msc1(struct burn_drive *d, int *start_lba);
int isoburn_set_msc1(struct burn_drive *d, int adr_mode, char *adr_value,
                     int flag);
int isoburn_disc_track_lba_nwa(struct burn_drive *d, struct burn_write_opts *o,
                               int trackno, int *lba, int *nwa);
int isoburn_get_min_start_byte(struct burn_drive *d, off_t *start_byte,
                               int __unused);
/*
 * Preparation of actions.
 */
int isoburn_prepare_disc(struct burn_drive *drive, struct burn_disc **disc,
                         struct isoburn_imgen_opts *opts);
int isoburn_prepare_new_image(struct burn_drive *in_drive,
                              struct burn_disc **disc,
                              struct isoburn_imgen_opts *opts,
                              struct burn_drive *out_drive);
int isoburn_prepare_blind_grow(struct burn_drive *in_drive,
                               struct burn_disc **disc,
                               struct isoburn_imgen_opts *opts,
                               struct burn_drive *out_drive, int nwa);
int isoburn_cancel_prepared_write(struct burn_drive *input_drive,
                                  struct burn_drive *output_drive, int flag);
/*
 * Retrieval and manipulation of the table of contents (TOC).
 */
struct isoburn_toc_disc *isoburn_toc_drive_get_disc(struct burn_drive *d);
int isoburn_toc_disc_get_sectors(struct isoburn_toc_disc *disc);
void isoburn_toc_disc_free(struct isoburn_toc_disc *disc);
struct isoburn_toc_session **isoburn_toc_disc_get_sessions(
                                      struct isoburn_toc_disc *disc, int *num);
int isoburn_toc_session_get_sectors(struct isoburn_toc_session *s);
void isoburn_toc_session_get_leadout_entry(struct isoburn_toc_session *s,
                                       struct burn_toc_entry *entry);
struct isoburn_toc_track **isoburn_toc_session_get_tracks(
                                      struct isoburn_toc_session *s, int *num);
void isoburn_toc_track_get_entry(struct isoburn_toc_track *t,
                                 struct burn_toc_entry *entry);
int isoburn_toc_track_get_emul(struct isoburn_toc_track *t, int *start_lba,
                               int *image_blocks, char volid[33],
                               int __unused);
int isoburn_read_iso_head(struct burn_drive *d, int lba,
                          int *image_blocks, char *info, int flag);
int isoburn_get_mount_params(struct burn_drive *d,
                             int adr_mode, char *adr_value,
                             int *lba, int *track, int *session,
                             char volid[33], int flag);
/*
 * Capabilities when reading an image.
 */
int isoburn_ropt_new(struct isoburn_read_opts **o, int flag);
int isoburn_ropt_destroy(struct isoburn_read_opts **o, int flag);
int isoburn_ropt_set_extensions(struct isoburn_read_opts *o, int ext);
int isoburn_ropt_get_extensions(struct isoburn_read_opts *o, int *ext);
int isoburn_ropt_set_default_perms(struct isoburn_read_opts *o,
                                   uid_t uid, gid_t gid, mode_t mode);
int isoburn_ropt_get_default_perms(struct isoburn_read_opts *o,
                                   uid_t *uid, gid_t *gid, mode_t *mode);
int isoburn_ropt_set_default_dirperms(struct isoburn_read_opts *o,
                                      mode_t mode);
int isoburn_ropt_get_default_dirperms(struct isoburn_read_opts *o,
                                      mode_t *mode);
int isoburn_ropt_set_input_charset(struct isoburn_read_opts *o,
                                   char *input_charset);
int isoburn_ropt_get_input_charset(struct isoburn_read_opts *o,
                                   char **input_charset);
int isoburn_ropt_set_auto_incharset(struct isoburn_read_opts *o, int mode);
int isoburn_ropt_get_auto_incharset(struct isoburn_read_opts *o, int *mode);
int isoburn_ropt_set_displacement(struct isoburn_read_opts *o,
                               uint32_t displacement, int displacement_sign);
int isoburn_ropt_get_displacement(struct isoburn_read_opts *o,
                               uint32_t *displacement, int *displacement_sign);
int isoburn_ropt_get_size_what(struct isoburn_read_opts *o,
                               uint32_t *size, int *has_what);
/*
 * Capabilities when growing an image.
 */
int isoburn_igopt_new(struct isoburn_imgen_opts **o, int flag);
int isoburn_igopt_destroy(struct isoburn_imgen_opts **o, int flag);
int isoburn_igopt_set_level(struct isoburn_imgen_opts *o, int level);
int isoburn_igopt_get_level(struct isoburn_imgen_opts *o, int *level);
int isoburn_igopt_set_extensions(struct isoburn_imgen_opts *o, int ext);
int isoburn_igopt_get_extensions(struct isoburn_imgen_opts *o, int *ext);
int isoburn_igopt_set_relaxed(struct isoburn_imgen_opts *o, int relax);
int isoburn_igopt_get_relaxed(struct isoburn_imgen_opts *o, int *relax);
int isoburn_igopt_set_untranslated_name_len(struct isoburn_imgen_opts *o,
                                            int len);
int isoburn_igopt_get_untranslated_name_len(struct isoburn_imgen_opts *o,
                                            int *len);
int isoburn_igopt_set_sort_files(struct isoburn_imgen_opts *o, int value);
int isoburn_igopt_get_sort_files(struct isoburn_imgen_opts *o, int *value);
int isoburn_igopt_set_over_mode(struct isoburn_imgen_opts *o,
                               int replace_dir_mode, int replace_file_mode,
                               mode_t dir_mode, mode_t file_mode);
int isoburn_igopt_get_over_mode(struct isoburn_imgen_opts *o,
                               int *replace_dir_mode, int *replace_file_mode,
                               mode_t *dir_mode, mode_t *file_mode);
int isoburn_igopt_set_over_ugid(struct isoburn_imgen_opts *o,
                               int replace_uid, int replace_gid,
                               uid_t uid, gid_t gid);
int isoburn_igopt_get_over_ugid(struct isoburn_imgen_opts *o,
                               int *replace_uid, int *replace_gid,
                               uid_t *uid, gid_t *gid);
int isoburn_igopt_set_out_charset(struct isoburn_imgen_opts *o,
                                 char *output_charset);
int isoburn_igopt_get_out_charset(struct isoburn_imgen_opts *o,
                                 char **output_charset);
int isoburn_igopt_set_fifo_size(struct isoburn_imgen_opts *o, int fifo_size);
int isoburn_igopt_get_fifo_size(struct isoburn_imgen_opts *o, int *fifo_size);
int isoburn_igopt_get_effective_lba(struct isoburn_imgen_opts *o, int *lba);
int isoburn_igopt_get_data_start(struct isoburn_imgen_opts *o, int *lba);
int isoburn_igopt_set_scdbackup_tag(struct isoburn_imgen_opts *o, char *name,
                                    char *timestamp, char *tag_written);
int isoburn_igopt_get_scdbackup_tag(struct isoburn_imgen_opts *o,
                                    char name[81], char timestamp[19],
int isoburn_igopt_set_system_area(struct isoburn_imgen_opts *o,
                                  char data[32768], int options);
int isoburn_igopt_get_system_area(struct isoburn_imgen_opts *o,
                                  char data[32768], int *options);
int isoburn_igopt_set_part_offset(struct isoburn_imgen_opts  *opts,
                                  uint32_t block_offset_2k,
                                  int secs_512_per_head, int heads_per_cyl);
int isoburn_igopt_get_part_offset(struct isoburn_imgen_opts *opts,
                                  uint32_t *block_offset_2k,
                                  int *secs_512_per_head, int *heads_per_cyl);
int isoburn_igopt_set_pvd_times(struct isoburn_imgen_opts *opts,
                        time_t creation_time, time_t modification_time,
                        time_t expiration_time, time_t effective_time,
                        char *uuid);
int isoburn_igopt_get_pvd_times(struct isoburn_imgen_opts *opts,
                      time_t *creation_time, time_t *modification_time,
                      time_t *expiration_time, time_t *effective_time,
                      char uuid[17]);
int isoburn_igopt_attach_jte(struct isoburn_imgen_opts *opts,
                             void *libjte_handle);
int isoburn_igopt_detach_jte(struct isoburn_imgen_opts *opts,
                             void **libjte_handle);
int isoburn_igopt_set_tail_blocks(struct isoburn_imgen_opts *opts,
                                  uint32_t num_blocks);
int isoburn_igopt_get_tail_blocks(struct isoburn_imgen_opts *opts,
                                  uint32_t *num_blocks);
int isoburn_igopt_set_partition_img(struct isoburn_imgen_opts *opts,
                                  int partition_number, uint8_t partition_type,
                                  char *image_path);
int isoburn_igopt_get_partition_img(struct isoburn_imgen_opts *opts,
                                    int num_entries,
                                    uint8_t partition_types[],
                                    char *image_paths[]);
int isoburn_igopt_set_disc_label(struct isoburn_imgen_opts *opts, char *label);
int isoburn_igopt_get_disc_label(struct isoburn_imgen_opts *opts,
                                 char **label);

SEE ALSO
xorriso(1), xorrisofs(1).

The complete function reference is present as inline comments in

    /usr/include/libisoburn/libisoburn.h

COPYRIGHT
This text was compiled by Mats Erik Andersson from the Doxygen encoded information contained in libisoburn.h, in order that the Debian package contain a useful and accessible account of the API expressed by this library. The text may be used by others under the sole provisio of being licensed identically to the upstream source `libburnia' itself.