xorriso  1.5.4.pl02
About: GNU xorriso creates, loads, manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions. It is suitable for incremental data backup and for production of bootable ISO 9660 images. GNU xorriso is a statical compilation of the libraries libburn, libisofs, libisoburn, and libjte.
  Fossies Dox: xorriso-1.5.4.pl02.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

options.c File Reference
#include "libburn.h"
#include "options.h"
#include "drive.h"
#include "transport.h"
#include "init.h"
#include "write.h"
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include "libdax_msgs.h"
Include dependency graph for options.c:

Go to the source code of this file.


struct burn_write_optsburn_write_opts_new (struct burn_drive *drive)
void burn_write_opts_free (struct burn_write_opts *opts)
int burn_write_opts_clone (struct burn_write_opts *from, struct burn_write_opts **to, int flag)
struct burn_read_optsburn_read_opts_new (struct burn_drive *drive)
void burn_read_opts_free (struct burn_read_opts *opts)
int burn_write_opts_set_write_type (struct burn_write_opts *opts, enum burn_write_types write_type, int block_type)
void burn_write_opts_set_toc_entries (struct burn_write_opts *opts, int count, struct burn_toc_entry *toc_entries)
void burn_write_opts_set_format (struct burn_write_opts *opts, int format)
int burn_write_opts_set_simulate (struct burn_write_opts *opts, int sim)
int burn_write_opts_set_underrun_proof (struct burn_write_opts *opts, int underrun_proof)
void burn_write_opts_set_perform_opc (struct burn_write_opts *opts, int opc)
void burn_write_opts_set_has_mediacatalog (struct burn_write_opts *opts, int has_mediacatalog)
void burn_write_opts_set_mediacatalog (struct burn_write_opts *opts, unsigned char mediacatalog[13])
void burn_write_opts_set_multi (struct burn_write_opts *opts, int multi)
void burn_write_opts_set_fail21h_sev (struct burn_write_opts *opts, char *severity)
int burn_write_opts_set_leadin_text (struct burn_write_opts *opts, unsigned char *text_packs, int num_packs, int flag)
void burn_write_opts_set_start_byte (struct burn_write_opts *opts, off_t value)
enum burn_write_types burn_write_opts_auto_write_type (struct burn_write_opts *opts, struct burn_disc *disc, char reasons[4096], int flag)
void burn_write_opts_set_fillup (struct burn_write_opts *opts, int fill_up_media)
void burn_write_opts_set_force (struct burn_write_opts *opts, int use_force)
void burn_write_opts_set_stream_recording (struct burn_write_opts *opts, int value)
void burn_write_opts_set_dvd_obs (struct burn_write_opts *opts, int obs)
void burn_write_opts_set_obs_pad (struct burn_write_opts *opts, int pad)
void burn_write_opts_set_stdio_fsync (struct burn_write_opts *opts, int rhythm)
struct burn_driveburn_write_opts_get_drive (struct burn_write_opts *opts)
void burn_read_opts_set_raw (struct burn_read_opts *opts, int raw)
void burn_read_opts_set_c2errors (struct burn_read_opts *opts, int c2errors)
void burn_read_opts_read_subcodes_audio (struct burn_read_opts *opts, int subcodes_audio)
void burn_read_opts_read_subcodes_data (struct burn_read_opts *opts, int subcodes_data)
void burn_read_opts_set_hardware_error_recovery (struct burn_read_opts *opts, int hardware_error_recovery)
void burn_read_opts_report_recovered_errors (struct burn_read_opts *opts, int report_recovered_errors)
void burn_read_opts_transfer_damaged_blocks (struct burn_read_opts *opts, int transfer_damaged_blocks)
void burn_read_opts_set_hardware_error_retries (struct burn_read_opts *opts, unsigned char hardware_error_retries)


struct libdax_msgs * libdax_messenger

Function Documentation

◆ burn_read_opts_free()

void burn_read_opts_free ( struct burn_read_opts opts)

Frees a read_opts struct created with burn_read_opts_new

optswrite_opts to free

Definition at line 132 of file options.c.

References burn_read_opts::refcount.

◆ burn_read_opts_new()

struct burn_read_opts* burn_read_opts_new ( struct burn_drive drive)

Creates a read_opts struct for reading from the specified drive must be freed with burn_read_opts_free

driveThe drive to read from
The read_opts

Definition at line 112 of file options.c.

References burn_read_opts::c2errors, burn_read_opts::dap_bit, burn_read_opts::drive, burn_read_opts::hardware_error_recovery, burn_read_opts::hardware_error_retries, burn_read_opts::raw, burn_read_opts::refcount, burn_read_opts::report_recovered_errors, burn_read_opts::subcodes_audio, burn_read_opts::subcodes_data, and burn_read_opts::transfer_damaged_blocks.

◆ burn_read_opts_read_subcodes_audio()

void burn_read_opts_read_subcodes_audio ( struct burn_read_opts opts,
int  subcodes_audio 

Sets whether to read subcodes from audio tracks or not

optsThe read opts to change
subcodes_audioIf non-zero, read subcodes from audio tracks on the disc.

Definition at line 569 of file options.c.

References burn_read_opts::subcodes_audio.

◆ burn_read_opts_read_subcodes_data()

void burn_read_opts_read_subcodes_data ( struct burn_read_opts opts,
int  subcodes_data 

Sets whether to read subcodes from data tracks or not

optsThe read opts to change
subcodes_dataIf non-zero, read subcodes from data tracks on the disc.

Definition at line 575 of file options.c.

References burn_read_opts::subcodes_data.

◆ burn_read_opts_report_recovered_errors()

void burn_read_opts_report_recovered_errors ( struct burn_read_opts opts,
int  report_recovered_errors 

Sets whether to report recovered errors or not

optsThe read opts to change
report_recovered_errorsIf non-zero, recovered errors will be reported.

Definition at line 587 of file options.c.

References burn_read_opts::report_recovered_errors.

◆ burn_read_opts_set_c2errors()

void burn_read_opts_set_c2errors ( struct burn_read_opts opts,
int  c2errors 

Sets whether to report c2 errors or not

optsThe read opts to change
c2errorsIf non-zero, report c2 errors.

Definition at line 564 of file options.c.

References burn_read_opts::c2errors.

◆ burn_read_opts_set_hardware_error_recovery()

void burn_read_opts_set_hardware_error_recovery ( struct burn_read_opts opts,
int  hardware_error_recovery 

Sets whether to recover errors if possible

optsThe read opts to change
hardware_error_recoveryIf non-zero, attempt to recover errors if possible.

Definition at line 581 of file options.c.

References burn_read_opts::hardware_error_recovery.

◆ burn_read_opts_set_hardware_error_retries()

void burn_read_opts_set_hardware_error_retries ( struct burn_read_opts opts,
unsigned char  hardware_error_retries 

Sets the number of retries to attempt when trying to correct an error

optsThe read opts to change
hardware_error_retriesThe number of retries to attempt when correcting an error.

Definition at line 599 of file options.c.

References burn_read_opts::hardware_error_retries.

◆ burn_read_opts_set_raw()

void burn_read_opts_set_raw ( struct burn_read_opts opts,
int  raw_mode 

Sets whether to read in raw mode or not

optsThe read opts to change
raw_modeIf non-zero, reading will be done in raw mode, so that everything in the data tracks on the disc is read, including headers.

Definition at line 559 of file options.c.

References burn_read_opts::raw.

◆ burn_read_opts_transfer_damaged_blocks()

void burn_read_opts_transfer_damaged_blocks ( struct burn_read_opts opts,
int  transfer_damaged_blocks 

Sets whether blocks with unrecoverable errors should be read or not

optsThe read opts to change
transfer_damaged_blocksIf non-zero, blocks with unrecoverable errors will still be read.

Definition at line 593 of file options.c.

References burn_read_opts::transfer_damaged_blocks.

◆ burn_write_opts_auto_write_type()

enum burn_write_types burn_write_opts_auto_write_type ( struct burn_write_opts opts,
struct burn_disc disc,
char  reasons[4096],
int  flag 
flagBitfield for control purposes: bit0= do not choose type but check the one that is already set bit1= do not issue error messages via burn_msgs queue

Definition at line 302 of file options.c.

References burn_write_opts::start_byte.

Referenced by burn_precheck_write(), isoburn_disc_write(), and Xorriso_burn_track().

◆ burn_write_opts_clone()

int burn_write_opts_clone ( struct burn_write_opts from,
struct burn_write_opts **  to,
int  flag 

◆ burn_write_opts_free()

◆ burn_write_opts_get_drive()

struct burn_drive* burn_write_opts_get_drive ( struct burn_write_opts opts)

Inquires the drive associated with a burn_write_opts object.

optsobject to inquire
pointer to drive

Definition at line 553 of file options.c.

References burn_write_opts::drive.

Referenced by isoburn_disc_write().

◆ burn_write_opts_new()

◆ burn_write_opts_set_dvd_obs()

void burn_write_opts_set_dvd_obs ( struct burn_write_opts opts,
int  obs 

Overrides the write chunk size for DVD and BD media which is normally determined according to media type and setting of stream recording. A chunk size of 64 KB may improve throughput with bus systems which show latency problems.

optsThe write opts to change
obsNumber of bytes which shall be sent by a single write command. 0 means automatic size, 32768 and 65336 are the only other accepted sizes for now.

Definition at line 523 of file options.c.

References burn_write_opts::dvd_obs_override.

Referenced by Xorriso_make_write_options().

◆ burn_write_opts_set_fail21h_sev()

void burn_write_opts_set_fail21h_sev ( struct burn_write_opts opts,
char *  severity 

Set the severity to be used with write error messages which are potentially caused by not using write type BURN_WRITE_SAO on fast blanked DVD-RW.

Normally the call burn_write_opts_auto_write_type() can prevent such errors by looking for MMC feature 21h "Incremental Streaming Writable" which anounnces the capability for BURN_WRITE_TAO and multi session. Regrettable many drives announce feature 21h even if they only can do BURN_WRITE_SAO. This mistake becomes obvious by an early write error.

If you plan to call burn_drive_was_feat21_failure() and to repeat the burn attempt with BURN_WRITE_SAO, then set the severity of the error message low enough, so that the application does not see reason to abort.

optsThe option object to be manipulated
severitySeverity as with burn_msgs_set_severities(). "ALL" or empty text means the default severity that is attributed to other kinds of write errors.

Definition at line 228 of file options.c.

References burn_write_opts::feat21h_fail_sev, and libdax_msgs__text_to_sev().

Referenced by Xorriso_make_write_options().

◆ burn_write_opts_set_fillup()

void burn_write_opts_set_fillup ( struct burn_write_opts opts,
int  fill_up_media 

Caution: still immature and likely to change. Problems arose with sequential DVD-RW on one drive.

Controls whether the whole available space of the media shall be filled up by the last track of the last session.

optsThe write opts to change
fill_up_mediaIf 1 : fill up by last track, if 0 = do not fill up

Definition at line 500 of file options.c.

References burn_write_opts::fill_up_media.

◆ burn_write_opts_set_force()

void burn_write_opts_set_force ( struct burn_write_opts opts,
int  use_force 

Eventually makes libburn ignore the failure of some conformance checks:

  • the check whether CD write+block type is supported by the drive
  • the check whether the media profile supports simulated burning
    optsThe write opts to change
    use_force1=ignore above checks, 0=refuse work on failed check

Definition at line 508 of file options.c.

References burn_write_opts::force_is_set.

◆ burn_write_opts_set_format()

void burn_write_opts_set_format ( struct burn_write_opts opts,
int  format 

Sets the session format for a disc

optsThe write opts to change
formatThe session format to set

Definition at line 179 of file options.c.

References burn_write_opts::format.

◆ burn_write_opts_set_has_mediacatalog()

void burn_write_opts_set_has_mediacatalog ( struct burn_write_opts opts,
int  has_mediacatalog 

This call activates the Media Catalog Number for writing. The digits of that number have to be set by call burn_write_opts_set_mediacatalog().

optsThe write opts to change
has_mediacatalog1= activate writing of catalog to Q sub-channel 0= deactivate it

Definition at line 206 of file options.c.

References burn_write_opts::has_mediacatalog.

◆ burn_write_opts_set_leadin_text()

int burn_write_opts_set_leadin_text ( struct burn_write_opts opts,
unsigned char *  text_packs,
int  num_packs,
int  flag 

Submit an array of CD-TEXT packs which shall be written to the Lead-in of a SAO write run on CD.

optsThe option object to be manipulated
text_packsArray of bytes which form CD-TEXT packs of 18 bytes each. For a description of the format of the array, see file doc/cdtext.txt. No header of 4 bytes must be prepended which would tell the number of pack bytes + 2. This parameter may be NULL if the currently attached array of packs shall be removed.
num_packsThe number of 18 byte packs in text_packs. This parameter may be 0 if the currently attached array of packs shall be removed.
flagBitfield for control purposes. bit0= do not verify checksums bit1= repair mismatching checksums bit2= repair checksums if they are 00 00 with each pack
1 on success, <= 0 on failure

Definition at line 246 of file options.c.

References BURN_ALLOC_MEM, burn_cdtext_crc_mismatches(), BURN_FREE_MEM, burn_write_opts::drive, burn_drive::global_index, Libburn_leadin_cdtext_packs_maX, libdax_messenger, LIBDAX_MSGS_PRIO_HIGH, LIBDAX_MSGS_SEV_FAILURE, LIBDAX_MSGS_SEV_WARNING, libdax_msgs_submit(), burn_write_opts::no_text_pack_crc_check, burn_write_opts::num_text_packs, and burn_write_opts::text_packs.

◆ burn_write_opts_set_mediacatalog()

void burn_write_opts_set_mediacatalog ( struct burn_write_opts opts,
unsigned char  mediacatalog[13] 

The Q sub-channel of a CD may contain a Media Catalog Number of 13 decimal digits. This call sets the string of digits, but does not yet activate it for writing.

optsThe write opts to change
mediacatalogThe 13 decimal digits as ASCII bytes. I.e. '0' = 0x30.

Definition at line 212 of file options.c.

References burn_write_opts::mediacatalog.

◆ burn_write_opts_set_multi()

void burn_write_opts_set_multi ( struct burn_write_opts opts,
int  multi 

Sets the multi flag which eventually marks the emerging session as not being the last one and thus creating a BURN_DISC_APPENDABLE media. Note: DVD-R[W] in write mode BURN_WRITE_SAO are not capable of this. DVD-R DL are not capable of this at all. libburn will refuse to write if burn_write_opts_set_multi() is enabled under such conditions.

optsThe option object to be manipulated
multi1=media will be appendable, 0=media will be closed (default)

Definition at line 220 of file options.c.

References burn_write_opts::multi.

Referenced by isoburn_disc_write(), Xorriso_burn_track(), and Xorriso_make_write_options().

◆ burn_write_opts_set_obs_pad()

void burn_write_opts_set_obs_pad ( struct burn_write_opts opts,
int  pad 

Overrides the automatic decision whether to pad up the last write chunk to its full size. This applies to DVD, BD and stdio: pseudo-drives. Note: This override may get enabled fixely already at compile time by defining macro Libburn_dvd_always_obs_paD .

optsThe write opts to change
pad1 means to pad up in any case, 0 means automatic decision.

Definition at line 532 of file options.c.

References burn_write_opts::obs_pad.

◆ burn_write_opts_set_perform_opc()

void burn_write_opts_set_perform_opc ( struct burn_write_opts opts,
int  opc 

Sets whether to use opc or not with the write_opts struct

optsThe write opts to change
opcIf non-zero, optical power calibration will be performed at start of burn

Definition at line 201 of file options.c.

References burn_write_opts::perform_opc.

◆ burn_write_opts_set_simulate()

int burn_write_opts_set_simulate ( struct burn_write_opts opts,
int  sim 

Sets the simulate value for the write_opts struct . This corresponds to the Test Write bit in MMC mode page 05h. Several media types do not support this. See struct burn_multi_caps.might_simulate for actual availability of this feature. If the media is suitable, the drive will perform burn_disc_write() as a simulation instead of effective write operations. This means that the media content and burn_disc_get_status() stay unchanged. Note: With stdio-drives, the target file gets eventually created, opened, lseeked, and closed, but not written. So there are effects on it. Note: Up to version 1.4.6 the call burn_random_access_write() after burn_disc_write() did not simulate because it does not get any burn_write_opts and the drive did not memorize the simulation state. This has changed now. burn_random_access_write() will not write after a simulated burn run. Use burn_drive_reset_simulate(drive, 0) if you really want to end simulation before you call burn_disc_write() with new write options.

optsThe write opts to change
simNon-zero enables simulation, 0 enables real writing
Returns 1 on success and 0 on failure.

Definition at line 184 of file options.c.

References burn_write_opts::simulate.

Referenced by Xorriso_make_write_options().

◆ burn_write_opts_set_start_byte()

void burn_write_opts_set_start_byte ( struct burn_write_opts opts,
off_t  value 

Sets a start address for writing to media and write modes which are able to choose this address at all (for now: DVD+RW, DVD-RAM, formatted DVD-RW). now). The address is given in bytes. If it is not -1 then a write run will fail if choice of start address is not supported or if the block alignment of the address is not suitable for media and write mode. Alignment to 32 kB blocks is supposed to be safe with DVD media. Call burn_disc_get_multi_caps() can obtain the necessary media info. See resulting struct burn_multi_caps elements .start_adr , .start_alignment , .start_range_low , .start_range_high .

optsThe write opts to change
valueThe address in bytes (-1 = start at default address)

Definition at line 302 of file options.c.

Referenced by isoburn_disc_available_space(), isoburn_disc_write(), and Xorriso_burn_track().

◆ burn_write_opts_set_stdio_fsync()

void burn_write_opts_set_stdio_fsync ( struct burn_write_opts opts,
int  rhythm 

Sets the rhythm by which stdio pseudo drives force their output data to be consumed by the receiving storage device. This forcing keeps the memory from being clogged with lots of pending data for slow devices.

optsThe write opts to change
rhythmNumber of 2KB output blocks after which fsync(2) is performed. -1 means no fsync() 0 means default 1 means fsync() only at end,
1.3.8 (noop before 1.3.8) elsewise the value must be >= 32. Default is currently 8192 = 16 MB.

Definition at line 539 of file options.c.

References Libburn_stdio_fsync_limiT, and burn_write_opts::stdio_fsync_size.

Referenced by Xorriso_make_write_options().

◆ burn_write_opts_set_stream_recording()

void burn_write_opts_set_stream_recording ( struct burn_write_opts opts,
int  value 

Eventually makes use of the more modern write command AAh WRITE12 and sets the Streaming bit. With DVD-RAM and BD this can override the traditional slowdown to half nominal speed. But if it speeds up writing then it also disables error management and correction. Weigh your priorities. This affects the write operations of burn_disc_write() and subsequent calls of burn_random_access_write().

optsThe write opts to change
value0=use 2Ah WRITE10, 1=use AAh WRITE12 with Streaming bit
0.6.4: >=16 use WRITE12 but not before the LBA given by value

Definition at line 515 of file options.c.

References burn_write_opts::do_stream_recording.

Referenced by Xorriso_make_write_options(), and Xorriso_write_session().

◆ burn_write_opts_set_toc_entries()

void burn_write_opts_set_toc_entries ( struct burn_write_opts opts,
int  count,
struct burn_toc_entry toc_entries 

Supplies toc entries for writing - not normally required for cd mastering

optsThe write opts to change
countThe number of entries

Definition at line 170 of file options.c.

References burn_write_opts::toc_entries, and burn_write_opts::toc_entry.

◆ burn_write_opts_set_underrun_proof()

int burn_write_opts_set_underrun_proof ( struct burn_write_opts opts,
int  underrun_proof 

Controls buffer underrun prevention. This is only needed with CD media and possibly with old DVD-R drives. All other media types are not vulnerable to burn failure due to buffer underrun.

optsThe write opts to change
underrun_proofif non-zero, buffer underrun protection is enabled
Returns 1 if the drive announces to be capable of underrun prevention, Returns 0 if not.

Definition at line 190 of file options.c.

References burn_write_opts::drive, burn_drive::mdata, scsi_mode_data::p2a_valid, burn_write_opts::underrun_proof, and scsi_mode_data::underrun_proof.

Referenced by Xorriso_make_write_options().

◆ burn_write_opts_set_write_type()

int burn_write_opts_set_write_type ( struct burn_write_opts opts,
enum burn_write_types  write_type,
int  block_type 

Sets the write type for the write_opts struct. Note: write_type BURN_WRITE_SAO is currently not capable of writing a mix of data and audio tracks. You must use BURN_WRITE_TAO for such sessions.

optsThe write opts to change
write_typeThe write type to use
block_typeThe block type to use
Returns 1 on success and 0 on failure.

Definition at line 138 of file options.c.

References burn_write_opts::block_type, burn_drive::block_types, BURN_BLOCK_SAO, BURN_WRITE_SAO, burn_write_opts::drive, libdax_messenger, LIBDAX_MSGS_PRIO_HIGH, LIBDAX_MSGS_SEV_SORRY, libdax_msgs_submit(), sector_get_outmode(), spc_block_type(), and burn_write_opts::write_type.

Referenced by burn_drive_send_default_page_05(), isoburn_disc_write(), and Xorriso_burn_track().

Variable Documentation

◆ libdax_messenger

struct libdax_msgs* libdax_messenger