From dcb13954bda28964ab1a6810627d9a4f8bca632f Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Wed, 14 Oct 2020 22:59:35 +0200 Subject: [PATCH] New -zisofs parameters version_2=, block_size_v2=, max_bpt=, max_bpt_f= --- xorriso/base_obj.c | 5 + xorriso/filters.c | 103 +- xorriso/iso_tree.c | 19 +- xorriso/lib_mgt.c | 13 +- xorriso/opts_d_h.c | 2 + xorriso/opts_p_z.c | 81 +- xorriso/xorriso.1 | 54 +- xorriso/xorriso.info | 6029 +---------------------------------- xorriso/xorriso.texi | 54 +- xorriso/xorriso_private.h | 13 +- xorriso/xorriso_timestamp.h | 2 +- 11 files changed, 349 insertions(+), 6026 deletions(-) diff --git a/xorriso/base_obj.c b/xorriso/base_obj.c index d09ecb9c..810ab3e5 100644 --- a/xorriso/base_obj.c +++ b/xorriso/base_obj.c @@ -195,6 +195,11 @@ int Xorriso_new(struct XorrisO ** xorriso,char *progname, int flag) m->zlib_level_default= m->zlib_level= 6; m->zisofs_block_size= m->zisofs_block_size_default= (1 << 15); m->zisofs_by_magic= 0; + m->zisofs_v2_enabled= 0; + m->zisofs_max_total_blocks= m->zisofs_max_total_blocks_default= 0x2000000; + m->zisofs_max_file_blocks= m->zisofs_max_file_blocks_default= 0x2000000; + m->zisofs_block_size= m->zisofs_block_size_default= (1 << 15); + m->zisofs_v2_block_size= m->zisofs_v2_block_size_default= (1 << 17); m->do_overwrite= 2; m->do_reassure= 0; m->drive_blacklist= NULL; diff --git a/xorriso/filters.c b/xorriso/filters.c index 703b7688..85b583e0 100644 --- a/xorriso/filters.c +++ b/xorriso/filters.c @@ -1,7 +1,7 @@ /* xorriso - creates, loads, manipulates and burns ISO 9660 filesystem images. - Copyright 2007-2014 Thomas Schmitt, + Copyright 2007-2020 Thomas Schmitt, Provided under GPL version 2 or later. @@ -659,10 +659,12 @@ int Xorriso_status_extf(struct XorrisO *xorriso, char *filter, FILE *fp, int Xorriso_set_zisofs_params(struct XorrisO *xorriso, int flag) { - int ret; + int ret, i; struct iso_zisofs_ctrl ctrl; - ctrl.version= 0; + memset(&ctrl, 0, sizeof(ctrl)); + ctrl.version= 1; + ctrl.compression_level= xorriso->zlib_level; if(xorriso->zisofs_block_size == (1 << 16)) ctrl.block_size_log2= 16; @@ -670,6 +672,15 @@ int Xorriso_set_zisofs_params(struct XorrisO *xorriso, int flag) ctrl.block_size_log2= 17; else ctrl.block_size_log2= 15; + + ctrl.v2_enabled= xorriso->zisofs_v2_enabled; + ctrl.max_total_blocks= xorriso->zisofs_max_total_blocks; + ctrl.max_file_blocks= xorriso->zisofs_max_file_blocks; + ctrl.v2_block_size_log2= 17; + for(i= 15; i <= 17; i++) + if(xorriso->zisofs_v2_block_size == (1 << i)) + ctrl.v2_block_size_log2= i; + ret= iso_zisofs_set_params(&ctrl, 0); Xorriso_process_msg_queues(xorriso,0); if(ret < 0) { @@ -681,21 +692,48 @@ int Xorriso_set_zisofs_params(struct XorrisO *xorriso, int flag) } +uint64_t Xorriso_zisofs_current_blocks(struct XorrisO *xorriso, int flag) +{ + int ret; + struct iso_zisofs_ctrl ctrl; + + memset(&ctrl, 0, sizeof(ctrl)); + ctrl.version= 1; + ret = iso_zisofs_get_params(&ctrl, 0); + if(ret != 1) + return(0); + return(ctrl.current_total_blocks); +} + + int Xorriso_status_zisofs(struct XorrisO *xorriso, char *filter, FILE *fp, int flag) /* - bit0= do only report non-default settings - bit1= do only report to fp + bit0= only report non-default settings + bit1= only report to fp */ { off_t ziso_count= 0, osiz_count= 0; off_t gzip_count= 0, gunzip_count= 0; + uint64_t used_blocks; + int always= 0; iso_zisofs_get_refcounts(&ziso_count, &osiz_count, 0); iso_gzip_get_refcounts(&gzip_count, &gunzip_count, 0); + if(!(flag & 1)) { + always= 1; + } else if(filter != NULL) { + if(filter[0] != 0) + always= 1; + } + +#ifdef NIX if((flag & 1) && xorriso->zlib_level == xorriso->zlib_level_default && xorriso->zisofs_block_size == xorriso->zisofs_block_size_default && - xorriso->zisofs_by_magic == 0 && + xorriso->zisofs_by_magic == 0 && xorriso->zisofs_v2_enabled == 0 && + xorriso->zisofs_max_file_blocks == + xorriso->zisofs_max_file_blocks_default && + xorriso->zisofs_v2_block_size == xorriso->zisofs_v2_block_size_default && ziso_count == 0 && osiz_count == 0 && gzip_count == 0 && gunzip_count == 0) { if(filter == NULL) @@ -703,15 +741,52 @@ int Xorriso_status_zisofs(struct XorrisO *xorriso, char *filter, FILE *fp, if(filter[0] == 0) return 2; } - sprintf(xorriso->result_line, - "-zisofs level=%d:block_size=%dk:by_magic=%s:ziso_used=%.f:osiz_used=%.f", - xorriso->zlib_level, xorriso->zisofs_block_size / 1024, - xorriso->zisofs_by_magic ? "on" : "off", - (double) ziso_count, (double) osiz_count); - sprintf(xorriso->result_line + strlen(xorriso->result_line), - ":gzip_used=%.f:gunzip_used=%.f\n", +#endif + + if(always || !( + xorriso->zlib_level == xorriso->zlib_level_default && + xorriso->zisofs_block_size == xorriso->zisofs_block_size_default && + xorriso->zisofs_by_magic == 0)) { + sprintf(xorriso->result_line, + "-zisofs level=%d:block_size=%dk:by_magic=%s\n", + xorriso->zlib_level, xorriso->zisofs_block_size / 1024, + xorriso->zisofs_by_magic ? "on" : "off"); + Xorriso_status_result(xorriso, filter, fp, flag & 2); + } + if(always || !( + xorriso->zisofs_v2_enabled == 0 && + xorriso->zisofs_v2_block_size == xorriso->zisofs_v2_block_size_default)){ + sprintf(xorriso->result_line, + "-zisofs version_2=%s:block_size_v2=%dk\n", + xorriso->zisofs_v2_enabled ? xorriso->zisofs_v2_enabled == 1 ? + "as_needed" : "on" : "off", + xorriso->zisofs_v2_block_size / 1024); + Xorriso_status_result(xorriso, filter, fp, flag & 2); + } + + used_blocks= Xorriso_zisofs_current_blocks(xorriso, 0); + if(always || !( + xorriso->zisofs_max_total_blocks == + xorriso->zisofs_max_total_blocks_default && + xorriso->zisofs_max_file_blocks == + xorriso->zisofs_max_file_blocks_default && + used_blocks == 0)) { + sprintf(xorriso->result_line, + "-zisofs max_bpt=%.f:bpt_used=%.f:max_bpt_f=%.f\n", + (double) xorriso->zisofs_max_total_blocks * 8.0, + (double) used_blocks * 8.0, + (double) xorriso->zisofs_max_file_blocks * 8.0); + Xorriso_status_result(xorriso, filter, fp, flag & 2); + } + if(always || !( + ziso_count == 0 && osiz_count == 0 && + gzip_count == 0 && gunzip_count == 0)) { + sprintf(xorriso->result_line, + "-zisofs ziso_used=%.f:osiz_used=%.f:gzip_used=%.f:gunzip_used=%.f\n", + (double) ziso_count, (double) osiz_count, (double) gzip_count, (double) gunzip_count); - Xorriso_status_result(xorriso, filter, fp, flag&2); + Xorriso_status_result(xorriso, filter, fp, flag & 2); + } return(1); } diff --git a/xorriso/iso_tree.c b/xorriso/iso_tree.c index fac9656d..f6b132c6 100644 --- a/xorriso/iso_tree.c +++ b/xorriso/iso_tree.c @@ -1296,7 +1296,8 @@ ex: int Xorriso_stream_type(struct XorrisO *xorriso, IsoNode *node, IsoStream *stream, char type_text[], int flag) { - int ret, lba; + int ret, lba, stream_type, block_size_log2; + uint8_t zisofs_algo[2], algo_num; char text[5]; strncpy(text, stream->class->type, 4); @@ -1307,10 +1308,16 @@ int Xorriso_stream_type(struct XorrisO *xorriso, IsoNode *node, strcpy(type_text, "image"); else strcpy(type_text, "disk"); - } else if(strcmp(text, "ziso") == 0) { - strcpy(type_text, "--zisofs"); - } else if(strcmp(text, "osiz") == 0) { - strcpy(type_text, "--zisofs-decode"); + } else if(strcmp(text, "ziso") == 0 || strcmp(text, "osiz") == 0) { + if(strcmp(text, "ziso") == 0) + strcpy(type_text, "--zisofs"); + else + strcpy(type_text, "--zisofs-decode"); + ret= iso_stream_get_zisofs_par(stream, &stream_type, zisofs_algo, &algo_num, + &block_size_log2, 0); + if(ret == 1) + sprintf(type_text + strlen(type_text), ":%c%c:%d", + zisofs_algo[0], zisofs_algo[1], 1 << block_size_log2); } else if(strcmp(text, "gzip") == 0) { strcpy(type_text, "--gzip"); } else if(strcmp(text, "pizg") == 0) { @@ -2392,7 +2399,7 @@ int Xorriso_show_stream(struct XorrisO *xorriso, void *in_node, IsoFile *file; IsoStream *stream= NULL, *input_stream; IsoExternalFilterCommand *cmd; - char type_text[16], *source_path= NULL; + char type_text[80], *source_path= NULL; unsigned int fs_id; dev_t dev_id; ino_t ino_id; diff --git a/xorriso/lib_mgt.c b/xorriso/lib_mgt.c index 586d3ea6..3d9b1cfe 100644 --- a/xorriso/lib_mgt.c +++ b/xorriso/lib_mgt.c @@ -1,7 +1,7 @@ /* xorriso - creates, loads, manipulates and burns ISO 9660 filesystem images. - Copyright 2007-2019 Thomas Schmitt, + Copyright 2007-2020 Thomas Schmitt, Provided under GPL version 2 or later. @@ -120,7 +120,7 @@ int Xorriso_startup_libraries(struct XorrisO *xorriso, int flag) { int ret, major, minor, micro; char *queue_sev, *print_sev, reason[1024]; - struct iso_zisofs_ctrl zisofs_ctrl= {0, 6, 15}; + struct iso_zisofs_ctrl zisofs_ctrl; /* First an ugly compile time check for header version compatibility. @@ -213,12 +213,21 @@ LIBISOBURN_MISCONFIGURATION_ = 0; if(ret <= 0) return(ret); + memset(&zisofs_ctrl, 0, sizeof(zisofs_ctrl)); + zisofs_ctrl.version = 1; ret = iso_zisofs_get_params(&zisofs_ctrl, 0); if (ret == 1) { xorriso->zisofs_block_size= xorriso->zisofs_block_size_default= (1 << zisofs_ctrl.block_size_log2); xorriso->zlib_level= xorriso->zlib_level_default= zisofs_ctrl.compression_level; + xorriso->zisofs_v2_enabled= zisofs_ctrl.v2_enabled; + xorriso->zisofs_max_total_blocks= + xorriso->zisofs_max_total_blocks_default= zisofs_ctrl.max_total_blocks; + xorriso->zisofs_max_file_blocks= + xorriso->zisofs_max_file_blocks_default= zisofs_ctrl.max_file_blocks; + xorriso->zisofs_v2_block_size= xorriso->zisofs_v2_block_size_default= + 1 << zisofs_ctrl.v2_block_size_log2; } iso_node_xinfo_make_clonable(Xorriso__mark_update_xinfo, diff --git a/xorriso/opts_d_h.c b/xorriso/opts_d_h.c index cbb32d1c..75a6634f 100644 --- a/xorriso/opts_d_h.c +++ b/xorriso/opts_d_h.c @@ -2186,6 +2186,8 @@ int Xorriso_option_help(struct XorrisO *xorriso, int flag) " -zisofs option[:options]", " Set global zisofs parameters:", " level=0|...|9 , block_size=32k|64k|128k , by_magic=on|off", +" version_2=off|as_needed|on , block_size_v2=32k|...|1024k", +" max_bpt=1k...128g , max_bpt_f=1k...128g", "", "Write-to-media commands:", " -rollback Discard the manipulated ISO image and reload it.", diff --git a/xorriso/opts_p_z.c b/xorriso/opts_p_z.c index a4ba1aac..cf9e3738 100644 --- a/xorriso/opts_p_z.c +++ b/xorriso/opts_p_z.c @@ -2245,15 +2245,34 @@ int Xorriso_option_xattr(struct XorrisO *xorriso, char *mode, int flag) } +static int parse_zisofs_param(char *cpt, int key_l, int l, double *num) +{ + char text[16]; + + *num= 0.0; + if(l <= key_l || l >= key_l + 16) + return(0); + strncpy(text, cpt + key_l, l - key_l); + text[l - key_l]= 0; + *num= Scanf_io_size(text, 0); + return(1); +} + /* Option -zisofs */ int Xorriso_option_zisofs(struct XorrisO *xorriso, char *mode, int flag) { - int was_level, was_blocksize, ret, l; + int was_level, was_blocksize, was_v2_enabled, was_blocksize_v2; + uint64_t was_max_total_blocks, was_max_file_blocks; + int ret, l, i; double num; char *cpt, *npt, text[16]; was_level= xorriso->zlib_level; was_blocksize= xorriso->zisofs_block_size; + was_v2_enabled= xorriso->zisofs_v2_enabled; + was_max_total_blocks= xorriso->zisofs_max_total_blocks; + was_max_file_blocks= xorriso->zisofs_max_file_blocks; + was_blocksize_v2= xorriso->zisofs_v2_block_size; npt= cpt= mode; for(cpt= mode; npt!=NULL; cpt= npt+1) { npt= strchr(cpt,':'); @@ -2277,7 +2296,8 @@ int Xorriso_option_zisofs(struct XorrisO *xorriso, char *mode, int flag) } else if(strncmp(cpt, "ziso_used=", 10) == 0 || strncmp(cpt, "osiz_used=", 10) == 0 || strncmp(cpt, "gzip_used=", 10) == 0 || - strncmp(cpt, "gunzip_used=", 12) == 0) { + strncmp(cpt, "gunzip_used=", 12) == 0 || + strncmp(cpt, "bpt_used=", 9) == 0) { /* (ignored info from -status) */; } else if(strncmp(cpt, "block_size=", 11)==0) { @@ -2294,16 +2314,67 @@ int Xorriso_option_zisofs(struct XorrisO *xorriso, char *mode, int flag) } xorriso->zisofs_block_size= num; - } else if(strncmp(cpt, "by_magic=", 8)==0) { + } else if(strncmp(cpt, "by_magic=", 9)==0) { if(strncmp(cpt + 9, "on", l - 9) == 0) xorriso->zisofs_by_magic= 1; else xorriso->zisofs_by_magic= 0; + } else if(strncmp(cpt, "version_2=", 10) == 0) { + if(strncmp(cpt + 10, "off", l - 10) == 0) { + xorriso->zisofs_v2_enabled= 0; + } else if(strncmp(cpt + 10, "as_needed", l - 11) == 0) { + xorriso->zisofs_v2_enabled= 1; + } else if(strncmp(cpt + 10, "on", l - 11) == 0) { + xorriso->zisofs_v2_enabled= 2; + } else { + sprintf(xorriso->info_text, + "-zisofs: Unrecognized version_2 mode (allowed: on, off, as_needed)"); + goto sorry_ex; + } + + } else if(strncmp(cpt, "max_bpt=", 8) == 0) { + parse_zisofs_param(cpt, 8, l, &num); + if(num < 1024.0 || num > 128.0 * 1024.0 * 1024.0 * 1024.0) { + sprintf(xorriso->info_text, + "-zisofs: Unsupported block pointer pool size (allowed: 1k to 128g)"); + goto sorry_ex; + } + xorriso->zisofs_max_total_blocks= num / 8.0; + if(xorriso->zisofs_max_total_blocks < xorriso->zisofs_max_file_blocks) + xorriso->zisofs_max_file_blocks= xorriso->zisofs_max_total_blocks; + + } else if(strncmp(cpt, "max_bpt_f=", 10) == 0) { + parse_zisofs_param(cpt, 10, l, &num); + if(num < 1024.0 || num > 128.0 * 1024.0 * 1024.0 * 1024.0) { + sprintf(xorriso->info_text, + "-zisofs: Unsupported block pointer list size (allowed: 1k to 128g)"); + goto sorry_ex; + } + xorriso->zisofs_max_file_blocks= num / 8.0; + if(xorriso->zisofs_max_file_blocks > xorriso->zisofs_max_total_blocks) + xorriso->zisofs_max_total_blocks= xorriso->zisofs_max_file_blocks; + + } else if(strncmp(cpt, "block_size_v2=", 14) == 0) { + parse_zisofs_param(cpt, 14, l, &num); + for(i= 15 ; i <= 20; i++) + if(num == (1 << i)) + break; + if(i > 20) { + sprintf(xorriso->info_text, + "-zisofs: Unsupported block size (allowed 32k, 64k, 128k, ... 1024k)"); + goto sorry_ex; + } + xorriso->zisofs_v2_block_size= num; + } else if(strncmp(cpt, "default", l)==0) { xorriso->zlib_level= xorriso->zlib_level_default; xorriso->zisofs_block_size= xorriso->zisofs_block_size_default; xorriso->zisofs_by_magic= 0; + xorriso->zisofs_v2_enabled= 0; + xorriso->zisofs_max_total_blocks= xorriso->zisofs_max_total_blocks_default; + xorriso->zisofs_max_file_blocks= xorriso->zisofs_max_file_blocks_default; + xorriso->zisofs_v2_block_size= xorriso->zisofs_v2_block_size_default; } else { unknown_mode:; @@ -2315,6 +2386,10 @@ sorry_ex: Xorriso_msgs_submit(xorriso, 0, xorriso->info_text, 0, "FAILURE", 0); xorriso->zlib_level= was_level; xorriso->zisofs_block_size= was_blocksize; + xorriso->zisofs_v2_enabled= was_v2_enabled; + xorriso->zisofs_max_total_blocks= was_max_total_blocks; + xorriso->zisofs_max_file_blocks= was_max_file_blocks; + xorriso->zisofs_v2_block_size= was_blocksize_v2; return(0); } } diff --git a/xorriso/xorriso.1 b/xorriso/xorriso.1 index a6f24b44..a79b0604 100644 --- a/xorriso/xorriso.1 +++ b/xorriso/xorriso.1 @@ -9,7 +9,7 @@ .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) -.TH XORRISO 1 "Version 1.5.3, Sep 30, 2020" +.TH XORRISO 1 "Version 1.5.3, Oct 14, 2020" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: @@ -3092,21 +3092,59 @@ User id to be used for all files when the new ISO tree gets written to media. \fB\-gid\fR gid Group id to be used for all files when the new ISO tree gets written to media. .TP -\fB\-zisofs\fR option[:options] +\fB\-zisofs\fR parameter[:parameters] Set global parameters for zisofs compression. This data format is recognized and transparently uncompressed by some Linux kernels. It is to be applied via command \-set_filter with built\-in filter "\-\-zisofs". +.br +Note: This command is only permitted while no \-\-zisofs filters are applied to +any files. +.br Parameters are: .br "level="[0\-9] zlib compression: 0=none, 1=fast,..., 9=slow .br - "block_size="32k|64k|128k size of compression blocks + "block_size="32k|64k|128k sets the size of version 1 compression blocks. .br "by_magic=on" enables an expensive test at image generation time which checks files from disk whether they already are zisofs compressed, e.g. by program mkzftree. .br - "default" same as "level=6:block_size=32k:by_magic=off" + "version_2="off|as_needed|on enables the use of experimental version zisofs2 +which can encode files of size 4 GiB or larger. The Linux kernel (as of 5.9) +does not yet know this format and will complain like +.br + isofs: Unknown ZF compression algorithm: PZ +.br +The files will then appear in their compressed form with zisofs2 header, +block pointer list, and compressed data. +.br +zisofs2 is recognized by xorriso in files from loaded images and gets equipped +with \-\-zisofs\-decode filters, unless restrictions on the number of +block pointers prevent this. +.br +Mode "off" restricts compression to files smaller than 4 GiB uncompressed size. +Mode "as_needed" uses zisofs2 for larger files. Mode "on" uses zisofs2 for all +zisofs compressed files. +.br + "block_size_v2="32k|64k|128k|256k|512k|1m sets the size of compression blocks +for zisofs2. +.br + "max_bpt="1k|...|128g sets the limit for the overall allocated block pointer +memory. Block pointers occupy virtual memory while a file gets uncompressed +and while a file, which shall be compressed, waits for ISO filesystem creation. +.br +One pointer occupies 8 bytes of memory and governs block_size or block_size_v2 +uncompressed bytes. +I.e. with block size 128k, 1m of block pointer memory suffices for 16g of +uncompressed file size. +.br + "max_bpt_f="1k|...|128g sets the limit for the memory size of the block +pointer list of a single file. max_bpt_f is never larger than max_bpt. +If either is set to violate this rule, the other gets set to the same value. +.br + "default" same as "level=6:block_size=32k:by_magic=off: +version_2=off:block_size_v2=128k:max_bpt=256m:max_bpt_f=256m". .TP \fB\-speed\fR code|number[k|m|c|d|b] Set the burn speed. Default is "max" (or "0") = maximum speed as announced @@ -4624,6 +4662,14 @@ Frequently used types are: cout:'disk_path offset count' for \-cut_out files. .br extf:'filter_name' for external filters. +.br + \-\-zisofs:algorithm:block_size for zisofs compression filters. +.br + \-\-zisofs\-decode:algorithm:block_size for zisofs uncompression filters. +.br + \-\-gzip for internal gzip compression filters. +.br + \-\-gunzip for internal gzip uncompression filters. .br Example: .br diff --git a/xorriso/xorriso.info b/xorriso/xorriso.info index fafaf3f8..9b72c6cc 100644 --- a/xorriso/xorriso.info +++ b/xorriso/xorriso.info @@ -13,5961 +13,12 @@ START-INFO-DIR-ENTRY END-INFO-DIR-ENTRY  -File: xorriso.info, Node: Top, Next: Overview, Up: (dir) - -GNU xorriso 1.5.3 -***************** - -xorriso - creates, loads, manipulates and writes ISO 9660 filesystem -images with Rock Ridge extensions. -* Menu: - -* Overview:: Overview -* Model:: Session model -* Media:: Media types and states -* Methods:: Creating, Growing, Modifying, Blind Growing -* Drives:: Libburn drives -* Extras:: Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr -* Processing:: Command processing -* Dialog:: Dialog, Readline, Result pager -* Commands:: Reference of commands -* Examples:: Examples -* Files:: Files -* Environ:: Environment -* Seealso:: See also -* Bugreport:: Reporting bugs -* Legal:: Author, Copyright, Credits -* CommandIdx:: Alphabetic Command List -* ConceptIdx:: Alphabetic List of Concepts and Objects - - -File: xorriso.info, Node: Overview, Next: Model, Prev: Top, Up: Top - -1 Overview -********** - -'xorriso' is a program which copies file objects from POSIX compliant -filesystems into Rock Ridge enhanced ISO 9660 filesystems and performs -session-wise manipulation of such filesystems. It can load the -management information of existing ISO images and it writes the session -results to optical media or to filesystem objects. -Vice versa 'xorriso' is able to copy file objects out of ISO 9660 -filesystems. - - A special property of 'xorriso' is that it needs neither an external -ISO 9660 formatter program nor an external burn program for CD, DVD or -BD but rather incorporates the libraries of libburnia-project.org . - -1.1 Features -============ - - -Operates on an existing ISO image or creates a new one. -Copies files from disk filesystem into the ISO image. -Copies files from ISO image to disk filesystem (see osirrox). -Renames or deletes file objects in the ISO image. -Changes file properties in the ISO image. -Updates ISO subtrees incrementally to match given disk subtrees. -Writes result either as completely new image or as add-on session to -optical media or filesystem objects. -Can activate ISOLINUX and GRUB boot images via El Torito and MBR. -Can perform multi-session tasks as emulation of mkisofs and cdrecord. -Can record and restore hard links and ACL. -Content may get zisofs compressed or filtered by external processes. -Can issue commands to mount older sessions on GNU/Linux or FreeBSD. -Can check media for damages and copy readable blocks to disk. -Can attach MD5 checksums to each data file and the whole session. -Scans for optical drives, blanks re-usable optical media. -Reads its instructions from command line arguments, dialog, and files. -Provides navigation commands for interactive ISO image manipulation. -Adjustable thresholds for abort, exit value, and problem reporting. - - Note that 'xorriso' does not write audio CDs and that it does not -produce UDF filesystems which are specified for official video DVD or -BD. - - -File: xorriso.info, Node: Model, Next: Media, Prev: Overview, Up: Top - -2 Session model -*************** - -Unlike other filesystems, *ISO 9660* (aka *ECMA-119*) is not intended -for read-write operation but rather for being generated in a single -sweep and being written to media as a *session*. -The data content of the session is called filesystem *image*. - - The written image in its session can then be mounted by the operating -system for being used read-only. GNU/Linux is able to mount ISO images -from block devices, which may represent optical media, other media or -via a loop device even from regular disk files. FreeBSD mounts ISO -images from devices that represent arbitrary media or from regular disk -files. - - This session usage model has been extended on CD media by the concept -of *multi-session* , which adds information to the CD and gives the -mount programs of the operating systems the addresses of the entry -points of each session. The mount programs recognize block devices -which represent CD media and will by default mount the image in the last -session. -This session usually contains an updated directory tree for the whole -medium which governs the data contents in all recorded sessions. So in -the view of the mount program all sessions of a particular medium -together form a single filesystem image. -Adding a session to an existing ISO image is in this text referred as -*growing*. -The multi-session model of the MMC standard does not apply to all media -types. But program growisofs by Andy Polyakov showed how to extend this -functionality to overwritable media or disk files which carry valid ISO -9660 filesystems. - - 'xorriso' provides growing as well as an own method named *modifying* -which produces a completely new ISO image from the old one and the -modifications. See paragraph Creating, Growing, Modifying, Blind -Growing below. - - 'xorriso' adopts the concept of multi-session by loading an image -directory tree if present, by offering to manipulate it by several -actions, and by writing the new image to the target medium. The first -session of a 'xorriso' run begins by the definition of the input drive -with the ISO image or by the definition of an output drive. The session -ends by command -commit which triggers writing. A -commit is done -automatically when the program ends regularly. - - After -commit a new session begins with the freshly written one as -input. A new input drive can only be chosen as long as the loaded ISO -image was not altered. Pending alteration can be revoked by command --rollback. - - Writing a session to the target is supposed to be very expensive in -terms of time and of consumed space on appendable or write-once media. -Therefore all intended manipulations of a particular ISO image should be -done in a single session. But in principle it is possible to store -intermediate states and to continue with image manipulations. - - -File: xorriso.info, Node: Media, Next: Methods, Prev: Model, Up: Top - -3 Media types and states -************************ - -There are two families of media in the MMC standard: -*Multi-session media* are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and -unformatted DVD-RW. These media provide a table of content which -describes their existing sessions. See command *-toc*. -Similar to multi-session media are DVD-R DL and minimally blanked -DVD-RW. They record only a single session of which the size must be -known in advance. 'xorriso' will write onto them only if command -close -is set to "on". -*Overwritable media* are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW. -They offer random write access but do not provide information about -their session history. If they contain one or more ISO 9660 sessions -and if the first session was written by 'xorriso', then a table of -content can be emulated. Else only a single overall session will be -visible. -DVD-RW media can be formatted by -format "full". They can be made -unformatted by -blank "deformat". -Regular files and block devices are handled as overwritable media. -Pipes and other writeable file types are handled as blank multi-session -media. - - These media can assume several states in which they offer different -capabilities. - - *Blank* media can be written from scratch. They contain no ISO image -suitable for 'xorriso'. -Blank is the state of newly purchased optical media. With used CD-RW -and DVD-RW it can be achieved by action -blank "as_needed". -Overwritable media are considered blank if they are new or if they have -been marked as blank by 'xorriso'. Action -blank "as_needed" can be -used to do this marking on overwritable media, or to apply mandatory -formatting to new media if necessary. - - *Appendable* media accept further sessions. Either they are MMC -multi-session media in appendable state, or they are overwritable media -which contain an ISO image suitable for 'xorriso'. -Appendable is the state after writing a session with command -close off. - - - *Closed* media cannot be written. They may contain an ISO image -suitable for 'xorriso'. -Closed is the state of DVD-ROM media and of multi-session media which -were written with command -close on. If the drive is read-only hardware -then it will probably show any media as closed CD-ROM or DVD-ROM. -Overwritable media assume this state in such read-only drives or if they -contain unrecognizable data in the first 32 data blocks. -Read-only drives may or may not show session histories of multi-session -media. Often only the first and the last session are visible. -Sometimes not even that. Command -rom_toc_scan might or might not help -in such cases. - - -File: xorriso.info, Node: Methods, Next: Drives, Prev: Media, Up: Top - -4 Creating, Growing, Modifying, Blind Growing: -********************************************** - - -A new empty ISO image gets *created* if there is no input drive with a -valid ISO 9660 image when the first time an output drive is defined. -This is achieved by command -dev on blank media or by command -outdev on -media in any state. -The new empty image can be populated with directories and files. Before -it can be written, the medium in the output drive must get into blank -state if it was not blank already. - - If there is a input drive with a valid ISO image, then this image -gets loaded as foundation for manipulations and extension. The -constellation of input and output drive determines which write method -will be used. They have quite different capabilities and constraints. - - The method of *growing* adds new data to the existing data on the -medium. These data comprise of new file content and they override the -existing ISO 9660 + Rock Ridge directory tree. It is possible to hide -files from previous sessions but they still exist on the medium and with -many types of optical media it is quite easy to recover them by mounting -older sessions. -Growing is achieved by command -dev. - - The write method of *modifying* produces compact filesystem images -with no outdated files or directory trees. Modifying can write its -images to target media which are completely unsuitable for multi-session -operations. E.g. DVD-RW which were treated with -blank -deformat_quickest, DVD-R DL, named pipes, character devices, sockets. -On the other hand modified sessions cannot be written to appendable -media but to blank media only. -So for this method one needs either two optical drives or has to work -with filesystem objects as source and/or target medium. -Modifying takes place if input drive and output drive are not the same -and if command -grow_blindly is set to its default "off". This is -achieved by commands -indev and -outdev. - - If command -grow_blindly is set to a non-negative number and if --indev and -outdev are both set to different drives, then *blind -growing* is performed. It produces an add-on session which is ready for -being written to the given block address. This is the usage model of -mkisofs -M $indev -C $msc1,$msc2 -o $outdev -which gives much room for wrong parameter combinations and should thus -only be employed if a strict distinction between ISO formatter 'xorriso' -and the burn program is desired. -C $msc1,$msc2 is equivalent to: --load sbsector $msc1 -grow_blindly $msc2 - - -File: xorriso.info, Node: Drives, Next: Extras, Prev: Methods, Up: Top - -5 Libburn drives -**************** - -Input drive, i.e. source of an existing or empty ISO image, can be any -random access readable libburn drive: optical media with readable data, -blank optical media, regular files, block devices. -Output drive, i.e. target for writing, can be any libburn drive. Some -drive types do not support the method of growing but only the methods of -modifying and blind growing. They all are suitable for newly created -images. - - All drive file objects have to offer rw-permission to the user of -'xorriso'. Even those which will not be usable for reading an ISO -image. -With any type of drive object, the data are considered to be organized -in blocks of 2 KiB. Access happens in terms of Logical Block Address -(*LBA*) which gives the number of a particular data block. - - MMC compliant (i.e. optical) drives on GNU/Linux usually get -addressed by the path of their block device or of their generic -character device. E.g. --dev /dev/sr0 --dev /dev/hdc --dev /dev/sg2 -By default xorriso will try to map the given address to /dev/hd* and -/dev/sr*. The command -scsi_dev_family can redirect the mapping from sr -to scd or sg. The latter does not suffer from the concurrency problems -which plague /dev/sr of Linux kernels since version 3. But it does not -yield the same addresses which are used by mount(8) or by open(2) for -read(2). -On FreeBSD the device files have names like --dev /dev/cd0 -On NetBSD: --dev /dev/rcd0d -On OpenSolaris: --dev /dev/rdsk/c4t0d0s2 -Get a list of accessible drives by command --device_links -It might be necessary to do this as *superuser* in order to see all -drives and to then allow rw-access for the intended users. Consider to -bundle the authorized users in a group like old "floppy". - - Filesystem objects of nearly any type can be addressed by prefix -"stdio:" and their path in the filesystem. E.g.: --dev stdio:/dev/sdc -The default setting of -drive_class allows the user to address files -outside the /dev tree without that prefix. E.g.: --dev /tmp/pseudo_drive -If path leads to a regular file or to a block device then the emulated -drive is random access readable and can be used for the method of -growing if it already contains a valid ISO 9660 image. Any other file -type is not readable via "stdio:" and can only be used as target for the -method of modifying or blind growing. Non-existing paths in existing -directories are handled as empty regular files. - - A very special kind of pseudo drive are open file descriptors. They -are depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open). - -Addresses "-" or "stdio:/dev/fd/1" depict standard output, which -normally is the output channel for result texts. To prevent a fatal -intermingling of ISO image and text messages, all result texts get -redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is among the -start arguments of the program. -Standard output is currently suitable for creating one session per -program run without dialog. Use in other situations is discouraged and -several restrictions apply: -It is not allowed to use standard output as pseudo drive if it was not -among the start arguments. Do not try to fool this ban via backdoor -addresses to stdout. -If stdout is used as drive, then -use_readline is permanently disabled. -Use of backdoors can cause severe memory and/or tty corruption. - - Be aware that especially the superuser can write into any accessible -file or device by using its path with the "stdio:" prefix. By default -any address in the /dev tree without prefix "stdio:" will work only if -it leads to a MMC drive. -One may use command *-ban_stdio_write* to surely prevent this risk and -to restrict drive usage to MMC drives. -One may prepend "mmc:" to a path to surely disallow any automatic -"stdio:". By command -drive_class one may ban certain paths or allow -access without prefix "stdio:" to other paths. - - -File: xorriso.info, Node: Extras, Next: Processing, Prev: Drives, Up: Top - -6 Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr -************************************************** - -*Rock Ridge* is the name of a set of additional information which -enhance an ISO 9660 filesystem so that it can represent a POSIX -compliant filesystem with ownership, access permissions, symbolic links, -and other attributes. -This is what 'xorriso' uses for a decent representation of the disk -files within the ISO image. 'xorriso' produces Rock Ridge information -by default. It is strongly discouraged to disable this feature. - - 'xorriso' is not named "porriso" because POSIX only guarantees 14 -characters of filename length. It is the X/Open System Interface -standard XSI which demands a file name length of up to 255 characters -and paths of up to 1024 characters. Rock Ridge fulfills this demand. - - An *El Torito* boot record points the BIOS bootstrapping facility to -one or more boot images, which are binary program files stored in the -ISO image. The content of the boot image files is not in the scope of -El Torito. -Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot -images. 'xorriso' is able to create or maintain an El Torito object -which makes such an image bootable. For details see command --boot_image. -It is possible to make ISO images bootable from USB stick or other -hard-disk-like media. Several options install a *MBR* (Master Boot -Record), It may get adjusted according to the needs of the intended boot -firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX. A MBR -contains boot code and a partition table. The new MBR of a follow-up -session can get in effect only on overwritable media. -MBR is read by PC-BIOS when booting from USB stick or hard disk, and by -PowerPC CHRP or PReP when booting. An MBR partition with type 0xee -indicates the presence of GPT. -Emulation -as mkisofs supports the example options out of the ISOLINUX -wiki, the options used in GRUB script grub-mkrescue, and the example in -the FreeBSD AvgLiveCD wiki. -A *GPT* (GUID Partition Table) marks partitions in a more modern way. -It is read by EFI when booting from USB stick or hard disk, and may be -used for finding and mounting a HFS+ partition inside the ISO image. -An *APM* (Apple Partition Map) marks the HFS+ partition. It is read by -Macs for booting and for mounting. -MBR, GPT and APM are combinable. APM occupies the first 8 bytes of MBR -boot code. All three do not hamper El Torito booting from CDROM. -There is support for further facilities: MIPS Big Endian (SGI), MIPS -Little Endian (DEC), SUN SPARC, HP-PA. Those are mutually not combinable -and also not combinable with MBR, GPT, or APM. - - *ACL* are an advanced way of controlling access permissions to file -objects. Neither ISO 9660 nor Rock Ridge specify a way to record ACLs. -So libisofs has introduced a standard conformant extension named AAIP -for that purpose. It uses this extension if enabled by command *-acl*. -AAIP enhanced images are supposed to be mountable normally, but one -cannot expect that the mounted filesystem will show and respect the -ACLs. For now, only 'xorriso' is able to retrieve those ACLs. It can -bring them into effect when files get restored to an ACL enabled file -system or it can print them in a format suitable for tool setfacl. -Files with ACL show as group permissions the setting of entry "mask::" -if that entry exists. Nevertheless the non-listed group members get -handled according to entry "group::". When removing ACL from a file, -'xorriso' brings "group::" into effect. -Recording and restoring of ACLs from and to local files works currently -only on GNU/Linux and FreeBSD. - - *xattr* (aka EA, or extattr) are pairs of name and value which can be -attached to file objects. AAIP is able to represent them and 'xorriso' -can record and restore them. -But be aware that pairs with names of non-user namespaces are not -necessarily portable between operating systems and not even between -filesystems. Only those which begin with "user.", like "user.x" or -"user.whatever", can unconditionally be expected to be appropriate on -other machines and disks. Processing of other xattr may need -administrator privileges. -Name has to be a 0 terminated string. Value may be any array of bytes -which does not exceed the size of 4095 bytes. xattr processing happens -only if it is enabled by command *-xattr*. -As with ACL, currently only 'xorriso' is able to retrieve xattr from -AAIP enhanced images, to restore them to xattr capable file systems, or -to print them. -Recording and restoring of xattr from and to local files works currently -only on GNU/Linux and FreeBSD, where they are known as extattr. - - -File: xorriso.info, Node: Processing, Next: Dialog, Prev: Extras, Up: Top - -7 Command processing -******************** - -Commands are either actions which happen immediately or settings which -influence following actions. So their sequence does matter, unless they -are given as program arguments and command *-x* is among them. -Commands consist of a command word, followed by zero or more parameter -words. If the list of parameter words is of variable length (indicated -by "[...]" or "[***]") then it must be terminated by either the *list -delimiter*, occur at the end of the argument list, or occur at the end -of an input line. - - At program start the list delimiter is the string "--". This may be -changed with the -list_delimiter command in order to allow "--" as -parameter in a variable length list. However, it is advised to reset -the delimiter to "--" immediately afterwards. -For brevity the list delimiter is referred as "--" throughout this text. - -The list delimiter is silently ignored if it appears after the -parameters of a command with a fixed list length. It is handled as -normal text if it appears among the parameters of such a command. - - *Pattern expansion* converts a list of pattern words into a list of -existing file addresses. Unmatched pattern words will appear unaltered -in that result list. -Pattern matching supports the usual shell parser wildcards '*' '?' -'[xyz]' and respects '/' as the path separator, which may only be -matched literally. -Pattern expansion is a property of some particular commands and not a -general feature. It is controlled by commands -iso_rr_pattern and --disk_pattern. Commands which use pattern expansion all have variable -parameter lists which are specified in this text by "[***]" rather than -"[...]". -Some other commands perform pattern matching unconditionally. - - Command and parameter words are either read from the program -arguments, where one argument is one word, or from quoted input lines -where words are recognized similar to the quotation rules of a shell -parser. -'xorriso' is not a shell, although it might appear so at first glimpse. -Be aware that the interaction of quotation marks and pattern symbols -like "*" differs from the usual shell parsers. In 'xorriso', a -quotation mark does not make a pattern symbol literal. - - *Quoted input* converts whitespace-separated text into words. The -double quotation mark " and the single quotation mark ' can be used to -enclose whitespace and make it part of words (e.g. of file names). -Each mark type can enclose the marks of the other type. A trailing -backslash \ outside quotations or an open quotation cause the next input -line to be appended. -Quoted input accepts any 8-bit character except NUL (0) as the content -of the quotes. Nevertheless it can be cumbersome for the user to -produce those characters directly. Therefore quoted input and program -arguments offer optional *Backslash Interpretation* which can represent -all 8-bit characters except NUL (0) via backslash codes as in $'...' of -bash. -This is not enabled by default. See command -backslash_codes. - - When the program starts then it first looks for argument -no_rc. If -this is not present then it looks for its startup files and reads their -content as command input lines. Then it interprets the program -arguments as commands and parameters. Finally it enters dialog mode if -command -dialog "on" has been executed by this point. - - The program ends either by command -end, or by the end of program -arguments if dialog mode has not been enabled at that point, or by a -problem event which triggers the threshold of command -abort_on. - - -File: xorriso.info, Node: Dialog, Next: Commands, Prev: Processing, Up: Top - -8 Dialog, Readline, Result pager -******************************** - -Dialog mode prompts for a quoted input line, parses it into words, and -performs them as commands with their parameters. It provides assisting -services to make dialog more comfortable. - - Readline is an enhancement for the input line. You may already know -it from the bash shell. Whether it is available in 'xorriso' depends on -the availability of package readline-dev at the time when 'xorriso' was -built from its sourcecode. -Readline lets the user move the cursor over the text in the line by help -of the Left and the Right arrow keys. Text may be inserted at the -cursor position. The Delete key removes the character under the cursor. -Up and Down arrow keys navigate through the history of previous input -lines. -See info readline for more info about libreadline. - - Command -page activates a built-in result text pager which may be -convenient in dialog mode. After an action has output the given number -of terminal lines, the pager prompts the user for a line of input. -An empty line lets 'xorriso' resume work until the next page is output. -The single character "@" disables paging for the current action. -"@@@", "x", "q", "X", or "Q" request that the current action aborts and -suppress further result output. -Any other line input will be interpreted as new dialog line. The -current action is requested to abort. Afterwards, the input line is -executed. - - Some actions apply paging to their info output, too. -The request to abort may or may not be obeyed by the current action. -All actions try to abort as soon as possible. - - -File: xorriso.info, Node: Commands, Next: Examples, Prev: Dialog, Up: Top - -9 Commands -********** - -All command words are shown with a leading dash although this dash is -not mandatory for the command to be recognized. Nevertheless within -command -as the dashes of the emulated commands are mandatory. -Normally any number of leading dashes is ignored with command words and -inner dashes are interpreted as underscores. -* Menu: - -* ArgSort:: Execution order of program arguments -* AqDrive:: Acquiring source and target drive -* Loading:: Influencing the behavior of image loading -* Insert:: Inserting files into ISO image -* SetInsert:: Settings for file insertion -* Manip:: File manipulations -* CmdFind:: Tree traversal command -find -* Filter:: Filters for data file content -* Writing:: Writing the result, drive control -* SetWrite:: Settings for result writing -* Bootable:: Bootable ISO images -* Jigdo:: Jigdo Template Extraction -* Charset:: Character sets -* Exception:: Exception processing -* DialogCtl:: Dialog mode control -* Inquiry:: Drive and media related inquiry actions -* Navigate:: Navigation in ISO image and disk filesystem -* Verify:: Evaluation of readability and recovery -* Restore:: osirrox ISO-to-disk restore commands -* Emulation:: Command compatibility emulations (cdrtools) -* Scripting:: Scripting, dialog and program control features -* Frontend:: Support for frontend programs via stdin and stdout - - -File: xorriso.info, Node: ArgSort, Next: AqDrive, Prev: Commands, Up: Commands - -9.1 Execution order of program arguments -======================================== - -By default the program arguments of a xorriso run are interpreted as a -sequence of commands which get performed exactly in the given order. -This requires the user to write commands for desired settings before the -commands which shall be influenced by those settings. -Many other programs support program arguments in an arbitrary ordering -and perform settings and actions in a sequence at their own discretion. -xorriso provides an option to enable such a behavior at the cost of loss -of expressivity. - --x - Enable automatic sorting of program arguments into a sequence that - (most likely) is sensible. This command may be given at any - position among the commands which are handed over as program - arguments. - Note: It works only if it is given as program argument and with a - single dash (i.e. "-x"). It will not work in startup files, nor - with -options_from_file, nor in dialog mode, nor as "x" and finally - not as "--x". It affects only the commands given as program - arguments. --list_arg_sorting - List all xorriso commands in the order which applies if command -x - is in effect. - This list may also be helpful without -x for a user who ponders - over the sequence in which to put commands. Deviations from the - listed sorting order may well make sense, though. - - -File: xorriso.info, Node: AqDrive, Next: Loading, Prev: ArgSort, Up: Commands - -9.2 Acquiring source and target drive -===================================== - -The effect of acquiring a drive may depend on several commands in the -next paragraph "Influencing the behavior of image loading". If desired, -their enabling commands have to be performed before the commands which -acquire the drive. - --dev address - Set input and output drive to the same address and load an ISO - image if it is present. If there is no ISO image then create a - blank one. Set the image expansion method to growing. - This is only allowed as long as no changes are pending in the - currently loaded ISO image. If changes are pending, then one has - to perform -commit or -rollback first. - Special address string "-" means standard output, to which several - restrictions apply. See above paragraph "Libburn drives". - An empty address string "" gives up the current device without - acquiring a new one. --indev address - Set input drive and load an ISO image if present. If the new input - drive differs from -outdev then switch from growing to modifying or - to blind growing. It depends on the setting of -grow_blindly which - of both gets activated. The same rules and restrictions apply as - with -dev. --outdev address - Set output drive and if it differs from the input drive then switch - from growing to modifying or to blind growing. Unlike -dev and - -indev this action does not load a new ISO image. So it can be - performed even if there are pending changes. - -outdev can be performed without previous -dev or -indev. In that - case an empty ISO image with no changes pending is created. It can - either be populated by help of -map, -add et.al. or it can be - discarded silently if -dev or -indev are performed afterwards. - Special address string "-" means standard output, to which several - restrictions apply. See above paragraph "Libburn drives". - An empty address string "" gives up the current output drive - without acquiring a new one. No writing is possible without an - output drive. --drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern - Add a drive path pattern to one of the safety lists or make those - lists empty. There are three lists defined which get tested in the - following sequence: - If a drive address path matches the "harmless" list then the drive - will be accepted. If it is not a MMC device then the prefix - "stdio:" will be prepended automatically. This list is empty by - default. - Else if the path matches the "banned" list then the drive will not - be accepted by 'xorriso' but rather lead to a FAILURE event. This - list is empty by default. - Else if the path matches the "caution" list and if it is not a MMC - device, then its address must have the prefix "stdio:" or it will - be rejected. This list has by default one entry: "/dev". - If a drive path matches no list then it is considered "harmless". - By default these are all paths which do not begin with directory - "/dev". - A path matches a list if one of its parent paths or itself matches - a list entry. Address prefix "stdio:" or "mmc:" will be ignored - when testing for matches. - By pseudo-class "clear_list" and pseudo-patterns "banned", - "caution", "harmless", or "all", the lists may be made empty. - E.g.: -drive_class clear_list banned - One will normally define the -drive_class lists in one of the - 'xorriso' Startup Files. - Note: This is not a security feature but rather a bumper for the - superuser to prevent inadverted mishaps. For reliably blocking - access to a device file you have to deny its rw-permissions in the - filesystem. --drive_access "exclusive"|"shared":"unrestricted"|"readonly" - Control whether device file locking mechanisms shall be used when - acquiring a drive, and whether status or content of the medium in - the drive may be altered. Useful and most harmless are the setting - "shared:readonly" and the default setting "exclusive:unrestricted". - - "exclusive" enables tests and locks when acquiring the drive. It - depends on the operating system which locking mechanisms get - applied, if any. On GNU/Linux it is open(O_EXCL). On FreeBSD it is - flock(LOCK_EX). - "shared" disables the use of these mechanisms to become able to - acquire drives which are mounted, or opened by some process, or - guarded by /dev/pktcdvd*. - "unrestricted" enables all technically appropriate operations on an - acquired drive. "shared:unrestricted" risks to get own burn runs - spoiled by other processes or to vice versa spoil activities of - such processes. So use "exclusive:unrestricted" unless you know - for sure that "shared" is safe. - "readonly" disables operations which might surprise a co-user of - the drive. For -outdev these are formatting, blanking, writing, - ejecting. For -indev this is ejecting. Be aware that even reading - and drive status inquiries can disturb an ongoing burn run on - CD-R[W] and DVD-R[W]. --scsi_dev_family "default"|"sr"|"scd"|"sg" - GNU/Linux specific: - By default, xorriso tries to map Linux drive addresses to /dev/sr* - before they get opened for operating the drive. This coordinates - well with other use cases of optical drives, like mount(8). But - since year 2010 all /dev/sr* share a global lock which allows only - one drive to process an SCSI command while all others have to wait - for its completion. This yields awful throughput if more than one - drive is writing or reading simultaneously. The global lock is not - applied to device files /dev/sg* and also not if the xorriso drive - address is prepended by "stdio:". - So for simultaneous burn runs on modern GNU/Linux it is advisable - to perform -scsi_dev_family "sg" before any -dev, -indev, or - -outdev. The drive addresses may then well be given as /dev/sr* - but will nevertheless get used as the matching /dev/sg*. - If you decide so, consider to put the command into a global startup - file like /etc/opt/xorriso/rc. --grow_blindly "off"|predicted_nwa - If predicted_nwa is a non-negative number then perform blind - growing rather than modifying if -indev and -outdev are set to - different drives. "off" or "-1" switch to modifying, which is the - default. - predicted_nwa is the block address where the add-on session of - blind growing will finally end up. It is the responsibility of the - user to ensure this final position and the presence of the older - sessions. Else the overall ISO image will not be mountable or will - produce read errors when accessing file content. 'xorriso' will - write the session to the address as obtained from examining -outdev - and not necessarily to predicted_nwa. - During a run of blind growing, the input drive is given up before - output begins. The output drive is given up when writing is done. - - -File: xorriso.info, Node: Loading, Next: Insert, Prev: AqDrive, Up: Commands - -9.3 Influencing the behavior of image loading -============================================= - -The following commands should normally be performed before loading an -image by acquiring an input drive. In rare cases it is desirable to -activate them only after image loading. - --read_speed code|number[k|m|c|d|b] - Set the speed for reading. Default is "none", which avoids to send - a speed setting command to the drive before reading begins. - Further special speed codes are: - "max" (or "0") selects maximum speed as announced by the drive. - "min" (or "-1") selects minimum speed as announced by the drive. - Speed can be given in media dependent numbers or as a desired - throughput per second in MMC compliant kB (= 1000) or MB (= 1000 - kB). Media x-speed factor can be set explicitly by "c" for CD, "d" - for DVD, "b" for BD, "x" is optional. - Example speeds: - 706k = 706kB/s = 4c = 4xCD - 5540k = 5540kB/s = 4d = 4xDVD - If there is no hint about the speed unit attached, then the medium - in the -indev will decide. Default unit is CD = 176.4k. - Depending on the drive, the reported read speeds can be deceivingly - low or high. Therefore "min" cannot become higher than 1x speed of - the involved medium type. Read speed "max" cannot become lower - than 52xCD, 24xDVD, or 20xBD, depending on the medium type. - MMC drives usually activate their own idea of speed and take the - speed value given by the burn program only as hint for their own - decision. Friendly drives adjust their constant angular velocity - so that the desired speed is reached at the outer rim of the - medium. But often there is only the choice between very slow and - very loud. - Sometimes no speed setting is obeyed at all, but speed is adjusted - to the demand frequency of the reading program. So xorriso offers - to set an additional software enforced limit by prefix - "soft_force:". The program will take care not to read faster than - the soft_force speed. This may be combined with setting the drive - speed to a higher value. Setting "soft_force:0" disables this - feature. - "soft_force:" tries to correct in subsequent waiting periods lost - or surplus time of up to 0.25 seconds. This smoothens the overall - data stream but also enables short times of higher speed to - compensate short times of low speed. Prefix "soft_corr:" sets this - hindsight span by giving a number of microseconds. Not more than 1 - billion = 1000 seconds. Very short times can cause speed - deviations, because systematic inaccuracies of the waiting function - cannot be compensated. - Examples (combinable): - -read_speed 6xBD - -read_speed soft_force:4xBD -read_speed soft_corr:100000 --load entity id - Load a particular (possibly outdated) ISO session from -dev or - -indev. Usually all available sessions are shown with command - -toc. - entity depicts the kind of addressing. id depicts the particular - address. The following entities are defined: - "auto" with any id addresses the last session in -toc. This is the - default. - "session" with id being a number as of a line "ISO session", column - "Idx". - "track" with id being a number as of a line "ISO track", column - "Idx". - "lba" or "sbsector" with a number as of a line "ISO ...", column - "sbsector". - "volid" with a search pattern for a text as of a line "ISO ...", - column "Volume Id". - Addressing a non-existing entity or one which does not represent an - ISO image will either abandon -indev or at least lead to a blank - image. - If an input drive is set at the moment when -load is executed, then - the addressed ISO image is loaded immediately. Else, the setting - will be pending until the next -dev or -indev. After the image has - been loaded once, the setting is valid for -rollback until next - -dev or -indev, where it will be reset to "auto". --displacement [-]lba - Compensate a displacement of the image versus the start address for - which the image was prepared. This affects only loading of ISO - images and reading of their files. The multi-session method of - growing is not allowed as long as -displacement is non-zero. I.e. - -indev and -outdev must be different. The displacement gets reset - to 0 before the drive gets re-acquired after writing. - Examples: - If a track of a CD starts at block 123456 and gets copied to a disk - file where it begins at block 0, then this copy can be loaded with - -displacement -123456 - If an ISO image was written onto a partition with offset of 640000 - blocks of 512 bytes, then it can be loaded from the base device by - -load sbsector 160000 -displacement 160000 - (If the partition start address is not divisible by 4, then you - will have to employ a loop device instead.) - In both cases, the ISO sessions should be self contained, i.e. not - add-on sessions to an ISO image outside their track or partition. --read_fs "any"|"norock"|"nojoliet"|"ecma119" - Specify which kind of filesystem tree to load if present. If the - wish cannot be fulfilled, then ECMA-119 names are loaded and - converted according to -ecma119_map. - "any" first tries to read Rock Ridge. If not present, Joliet is - tried. - "norock" does not try Rock Ridge. - "nojoliet" does not try Joliet. - "ecma119" tries neither Rock Ridge nor Joliet. --assert_volid pattern severity - Refuse to load ISO images with volume IDs which do not match the - given search pattern. When refusing an image, give up the input - drive and issue an event of the given severity (like FAILURE, see - -abort_on). An empty search pattern accepts any image. - This command does not hamper the creation of an empty image from - blank input media and does not discard an already loaded image. --in_charset character_set_name - Set the character set from which to convert file names when loading - an image. See paragraph "Character sets" for more explanations. - When loading the written image after -commit the setting of - -out_charset will be copied to -in_charset. --auto_charset "on"|"off" - Enable or disable recording and interpretation of the output - character set name in an xattr attribute of the image root - directory. If enabled and if a recorded character set name is - found, then this name will be used as name of the input character - set when reading an image. - Note that the default output charset is the local character set of - the terminal where 'xorriso' runs. Before attributing this local - character set to the produced ISO image, check whether the terminal - properly displays all intended filenames, especially exotic - national characters. --hardlinks mode[:mode...] - Enable or disable loading and recording of hardlink relations. - In default mode "off", iso_rr files lose their inode numbers at - image load time. Each iso_rr file object which has no inode number - at image generation time will get a new unique inode number if - -compliance is set to new_rr. - Mode "on" preserves inode numbers from the loaded image if such - numbers were recorded. When committing a session it searches for - families of iso_rr files which stem from the same disk file, have - identical content filtering and have identical properties. The - family members all get the same inode number. Whether these - numbers are respected at mount time depends on the operating - system. - Command -lsl displays hardlink counts if "lsl_count" is enabled. - This can slow down the command substantially after changes to the - ISO image have been made. Therefore the default is "no_lsl_count". - - Commands -update and -update_r track splits and fusions of hard - links in filesystems which have stable device and inode numbers. - This can cause automatic last minute changes before the session - gets written. Command -hardlinks "perform_update" may be used to - do these changes earlier, e.g. if you need to apply filters to all - updated files. - Mode "without_update" avoids hardlink processing during update - commands. Use this if your filesystem situation does not allow - -disk_dev_ino "on". - 'xorriso' commands which extract files from an ISO image try to - hardlink files with identical inode number. The normal scope of - this operation is from image load to image load. One may give up - the accumulated hard link addresses by -hardlinks - "discard_extract". - A large number of hardlink families may exhaust -temp_mem_limit if - not -osirrox "sort_lba_on" and -hardlinks "cheap_sorted_extract" - are both in effect. This restricts hard linking to other files - restored by the same single extract command. -hardlinks - "normal_extract" re-enables wide and expensive hardlink - accumulation. --acl "on"|"off" - Enable or disable processing of ACLs. If enabled, then 'xorriso' - will obtain ACLs from disk file objects, store ACLs in the ISO - image using the libisofs specific AAIP format, load AAIP data from - ISO images, test ACL during file comparison, and restore ACLs to - disk files when extracting them from ISO images. See also commands - -getfacl, -setfacl. --xattr "on"|"user"|"any"|"off" - Enable or disable processing of xattr attributes. If enabled, then - 'xorriso' will handle xattr similar to ACL. See also commands - -getfattr, -setfattr and above paragraph about xattr. - Modes "on" and "user" read and write only attributes from namespace - "user". - Mode "any" processes attributes of all namespaces. This might need - administrator privileges, even if the owner of the disk file tries - to read or write the attributes. - Note that xattr from namespace "isofs." are never read from disk - or restored to disk. Further it is not possible to set them via - xorriso xattr manipulation commands. --md5 "on"|"all"|"off"|"load_check_off" - Enable or disable processing of MD5 checksums for the overall - session and for each single data file. If enabled then images with - checksum tags get loaded only if the tags of superblock and - directory tree match properly. The MD5 checksums of data files and - whole session get loaded from the image if there are any. - With commands -compare and -update the recorded MD5 of a file will - be used to avoid content reading from the image. Only the disk - file content will be read and compared with that MD5. This can - save much time if -disk_dev_ino "on" is not suitable. - Commands which copy whole data files from ISO to hard disk will - verify the copied data stream by the recorded MD5, if -osirrox - "check_md5_on" is set. - At image generation time they are computed for each file which gets - its data written into the new session. The checksums of files - which have their data in older sessions get copied into the new - session. Superblock, tree and whole session get a checksum tag - each. - Mode "all" will additionally check during image generation whether - the checksum of a data file changed between the time when its - reading began and the time when it ended. This implies reading - every file twice. - Mode "load_check_off" together with "on" or "all" will load - recorded MD5 sums but not test the recorded checksum tags of - superblock and directory tree. This is necessary if growisofs was - used as burn program, because it does not overwrite the superblock - checksum tag of the first session. Therefore load_check_off is in - effect when 'xorriso' -as mkisofs option -M is performed. - The test can be re-enabled by mode "load_check_on". - Checksums can be exploited via commands -check_md5, -check_md5_r, - via find actions get_md5, check_md5, and via -check_media. --for_backup - Enable all extra features which help to produce or to restore - backups with highest fidelity of file properties. Currently this - is a shortcut for: - -hardlinks on -acl on -xattr any -md5 on - If you restore a backup with xattr from non-user namespaces, then - make sure that the target operating system and filesystem know what - these attributes mean. Possibly you will need administrator - privileges to record or restore such attributes. At recording - time, xorriso will try to tolerate missing privileges and just - record what is readable. But at restore time, missing privileges - will cause failure events. - Command -xattr "user" after command -for_backup excludes non-user - attributes from being recorded or restored. --ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase" - Choose the conversion of file names from the loaded session if - neither a Rock Ridge name nor a Joliet name was read from the - session. - Mode "stripped" is the default. It shows the names as found in the - ISO but removes trailing ";1" or ".;1" if present. - Mode "unmapped" shows names as found without removing characters. - Mode "lowercase" is like "stripped" but also maps uppercase letters - to lowercase letters. This is compatible to default GNU/Linux - mount behavior. - Mode "uppercase" is like "stripped" but maps lowercase letters to - uppercase, if any occur despite the prescriptions of ECMA-119. --iso_nowtime "dynamic"|timestring - Choose whether to use the current time ("dynamic") or a fixed time - point for timestamps of ISO 9660 nodes without a disk source file - and as default for superblock timestamps. - If a timestring is given, then it is used for such timestamps. For - the formats of timestrings see command *-alter_date*. --disk_dev_ino "on"|"ino_only"|"off" - Enable or disable processing of recorded file identification - numbers (dev_t and ino_t). If enabled they are stored as xattr and - can substantially accelerate file comparison. The root node gets a - global start timestamp. If during comparison a file with younger - timestamps is found in the ISO image, then it is suspected to have - inconsistent content. - If device numbers and inode numbers of the disk filesystems are - persistent and if no irregular alterations of timestamps or system - clock happen, then potential content changes can be detected - without reading that content. File content change is assumed if - any of mtime, ctime, device number or inode number have changed. - Mode "ino_only" replaces the precondition that device numbers are - stable by the precondition that mount points in the compared tree - always lead to the same filesystems. Use this if mode "on" always - sees all files changed. - The speed advantage appears only if the loaded session was produced - with -disk_dev_ino "on" too. - Note that -disk_dev_ino "off" is totally in effect only if - -hardlinks is "off", too. --file_name_limit [+]number - Set the maximum permissible length for file names in the range of - 64 to 255. Path components which are longer than the given number - will get truncated and have their last 33 bytes overwritten by a - colon ':' and the hex representation of the MD5 of the first 4095 - bytes of the whole oversized name. Potential incomplete UTF-8 - characters will get their leading bytes replaced by '_'. - iso_rr_paths with the long components will still be able to access - the file paths with truncated components. - If -file_name_limit is executed while an ISO tree is present, the - file names in the ISO tree get checked for existing truncated file - names of the current limit and for name collisions between newly - truncated files and existing files. In both cases, the setting - will be refused with a SORRY event. - One may lift this ban by prepending the character "+" to the - argument of -file_name_limit. Truncated filenames may then get - truncated again, invalidating their MD5 part. Colliding truncated - names are made unique, consuming at least 9 more bytes of the - remaining name part. - If writing of xattr is enabled, then the length will be stored in - "isofs.nt" of the root directory. If reading of xattr is enabled - and "isofs.nt" is found, then the found length will get into effect - if it is smaller than the current setting of -file_name_limit. - File name patterns will only work if they match the truncated name. - This might change in future. - Files with truncated names get deleted and re-added unconditionally - during -update and -update_r. This might change in future. - Linux kernels up to at least 4.1 misrepresent names of length 254 - and 255. If you expect such names in or under disk_paths and plan - to mount the ISO by such Linux kernels, consider to set - -file_name_limit 253. Else just avoid names longer than 253 - characters. --rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"] - Read-only drives do not tell the actual media type but show any - media as ROM (e.g. as DVD-ROM). The session history of MMC - multi-session media might be truncated to first and last session or - even be completely false. (The emulated history of overwritable - media is not affected by this.) - To have in case of failure a chance of getting the session history - and especially the address of the last session, there is a scan for - ISO 9660 filesystem headers which might help but also might yield - worse results than the drive's table of content. At its end it can - cause read attempts to invalid addresses and thus ugly drive - behavior. Setting "on" enables that scan for alleged read-only - media. - Some operating systems are not able to mount the most recent - session of multi-session DVD or BD. If on such a system 'xorriso' - has no own MMC capabilities then it may still find that session - from a scanned table of content. Setting "force" handles any media - like a ROM medium with setting "on". - On the other hand the emulation of session history on overwritable - media can hamper reading of partly damaged media. Setting - "off:emul_off" disables the elsewise trustworthy table-of-content - scan for those media. - The table-of-content scan on overwritable media normally searches - only up to the end of the session that is pointed to by the - superblock at block 0. Setting "on:emul_wide" lets the scan - continue up to the end of the medium. This may be useful after - copying a medium with -check_media patch_lba0=on when not the last - session was loaded. --calm_drive "in"|"out"|"all"|"revoke"|"on"|"off" - Reduce drive noise until it is actually used again. Some drives - stay alert for substantial time after they have been used for - reading. This reduces the startup time for the next drive - operation but can be loud and waste energy if no i/o with the drive - is expected to happen soon. - Modes "in", "out", "all" immediately calm down -indev, -outdev, or - both, respectively. Mode "revoke" immediately alerts both. Mode - "on" causes -calm_drive to be performed automatically after each - -dev, -indev, and -outdev. Mode "off" disables this. --ban_stdio_write - Allow for writing only the usage of MMC optical drives. Disallow - to write the result into files of nearly arbitrary type. Once set, - this command cannot be revoked. --early_stdio_test "on"|"appendable_wo"|"off" - If enabled by "on" then regular files and block devices get tested - for effective access permissions. This implies to try opening - those files for writing, which otherwise will happen only later and - only if actual writing is desired. - The test result is used for classifying the pseudo drives as - overwritable, read-only, write-only, or uselessly empty. This may - lead to earlier detection of severe problems, and may avoid some - less severe error events. - Mode "appendable_wo" is like "on" with the additional property that - non-empty write-only files are regarded as appendable rather than - blank. --data_cache_size number_of_tiles blocks_per_tile - Set the size and granularity of the data cache which is used when - ISO images are loaded and when file content is read from ISO - images. The cache consists of several tiles, which each consists - of several blocks. A larger cache reduces the need for tiles being - read multiple times. Larger tiles might additionally improve the - data throughput from the drive, but can be wasteful if the data are - scattered over the medium. - Larger cache sizes help best with image loading from MMC drives. - They are an inferior alternative to -osirrox option "sort_lba_on". - blocks_per_tile must be a power of 2. E.g. 16, 32, or 64. The - overall cache size must not exceed 1 GiB. The default values can be - restored by parameter "default" instead of one or both of the - numbers. Currently the default is 32 tiles of 32 blocks = 2 MiB. - - -File: xorriso.info, Node: Insert, Next: SetInsert, Prev: Loading, Up: Commands - -9.4 Inserting files into ISO image -================================== - -The following commands expect file addresses of two kinds: *disk_path* -is a path to an object in the local filesystem tree. *iso_rr_path* is -the Rock Ridge name of a file object in the ISO image. If no Rock Ridge -information is recorded in the loaded ISO image, then you will see ISO -9660 names which are of limited length and character set. If no Rock -Ridge information shall be stored in an emerging ISO image, then their -names will get mapped to such restricted ISO 9660 (aka ECMA-119) names. - - Note that in the ISO image you are as powerful as the superuser. -Access permissions of the existing files in the image do not apply to -your write operations. They are intended to be in effect with the -read-only mounted image. - - If the iso_rr_path of a newly inserted file leads to an existing file -object in the ISO image, then the following collision handling happens: -If both objects are directories then they get merged by recursively -inserting the subobjects from filesystem into ISO image. If other file -types collide then the setting of command *-overwrite* decides. -Renaming of files has similar collision handling, but directories can -only be replaced, not merged. Note that if the target directory exists, -then -mv inserts the source objects into this directory rather than -attempting to replace it. Command -move, on the other hand, would -attempt to replace it. - - The commands in this section alter the ISO image and not the local -filesystem. - --disk_pattern "on"|"ls"|"off" - Set the pattern expansion mode for the disk_path parameters of - several commands which support this feature. - Setting "off" disables this feature for all commands which are - marked in this man page by "disk_path [***]" or "disk_pattern - [***]". - Setting "on" enables it for all those commands. - Setting "ls" enables it only for those which are marked by - "disk_pattern [***]". - Default is "ls". --add pathspec [...] | disk_path [***] - Insert the given files or directory trees from filesystem into the - ISO image. - If -pathspecs is set to "on" or "as_mkisofs" then pattern expansion - is always disabled and character '=' has a special meaning. It - separates the ISO image path from the disk path: - iso_rr_path=disk_path - Character '=' in the iso_rr_path must be escaped by '\' (i.e. as - "\="). - With -pathspecs "on", the character '\' must not be escaped. The - character '=' in the disk_path must not be escaped. - With -pathspecs "as_mkisofs", all characters '\' must be escaped in - both, iso_rr_path and disk_path. The character '=' may or may not - be escaped in the disk_path. - If iso_rr_path does not begin with '/' then -cd is prepended. If - disk_path does not begin with '/' then -cdx is prepended. - If no '=' is given then the word is used as both, iso_rr_path and - disk path. If in this case the word does not begin with '/' then - -cdx is prepended to the disk_path and -cd is prepended to the - iso_rr_path. - If -pathspecs is set to "off" then -disk_pattern expansion applies, - if enabled. The resulting words are used as both, iso_rr_path and - disk path. Relative path words get prepended the setting of -cdx - to disk_path and the setting of -cd to iso_rr_path. --add_plainly mode - If set to mode "unknown" then any command word that does not begin - with "-" and is not recognized as known command will be subject to - a virtual -add command. I.e. it will be used as pathspec or as - disk_path and added to the image. If enabled, -disk_pattern - expansion applies to disk_paths. - Mode "dashed" is similar to "unknown" but also adds unrecognized - command words even if they begin with "-". - Mode "any" announces that all further words are to be added as - pathspecs or disk_paths. This does not work in dialog mode. - Mode "none" is the default. It prevents any words from being - understood as files to add, if they are not parameters to - appropriate commands. --path_list disk_path - Like -add but read the parameter words from file disk_path or - standard input if disk_path is "-". The list must contain exactly - one pathspec or disk_path pattern per line. --quoted_path_list disk_path - Like -path_list but with quoted input reading rules. Lines get - split into parameter words for -add. Whitespace outside quotes is - discarded. --map disk_path iso_rr_path - Insert file object disk_path into the ISO image as iso_rr_path. If - disk_path is a directory then its whole sub tree is inserted into - the ISO image. --map_single disk_path iso_rr_path - Like -map, but if disk_path is a directory then its sub tree is not - inserted. --map_l disk_prefix iso_rr_prefix disk_path [***] - Perform -map with each of the disk_path parameters. iso_rr_path - will be composed from disk_path by replacing disk_prefix by - iso_rr_prefix. --update disk_path iso_rr_path - Compare file object disk_path with file object iso_rr_path. If - they do not match, then perform the necessary image manipulations - to make iso_rr_path a matching copy of disk_path. By default this - comparison will imply lengthy content reading before a decision is - made. Commands -disk_dev_ino or -md5 may accelerate comparison if - they were already in effect when the loaded session was recorded. - If disk_path is a directory and iso_rr_path does not exist yet, - then the whole subtree will be inserted. Else only directory - attributes will be updated. --update_r disk_path iso_rr_path - Like -update but working recursively. I.e. all file objects below - both addresses get compared whether they have counterparts below - the other address and whether both counterparts match. If there is - a mismatch then the necessary update manipulation is done. - Note that the comparison result may depend on command -follow. Its - setting should always be the same as with the first adding of - disk_path as iso_rr_path. - If iso_rr_path does not exist yet, then it gets added. If - disk_path does not exist, then iso_rr_path gets deleted. --update_l disk_prefix iso_rr_prefix disk_path [***] - Perform -update_r with each of the disk_path parameters. - iso_rr_path will be composed from disk_path by replacing - disk_prefix by iso_rr_prefix. --update_li iso_rr_prefix disk_prefix iso_rr_path [***] - Perform -update_r with each of the iso_rr_path parameters. - disk_path will be composed from iso_rr_path by replacing - iso_rr_prefix by disk_prefix. --update_lxi disk_prefix iso_rr_prefix disk_path [***] - Perform -update_r with each of the disk_path parameters and with - iso_rr_paths in the ISO filesystem which are derived from the - disk_path parameters after exchanging disk_prefix by iso_rr_prefix. - So, other than -update_l, this detects missing matches of disk_path - and deletes the corresponding iso_rr_path. - Note that relative disk_paths and disk_path patterns are - interpreted as sub paths of the current disk working directory - -cdx. The corresponding iso_rr_paths are derived by exchanging - disk_prefix by iso_rr_prefix before pattern expansion happens. The - current -cdi directory has no influence. --cut_out disk_path byte_offset byte_count iso_rr_path - Map a byte interval of a regular disk file into a regular file in - the ISO image. This may be necessary if the disk file is larger - than a single medium, or if it exceeds the traditional limit of 2 - GiB - 1 for old operating systems, or the limit of 4 GiB - 1 for - newer ones. Only the newest Linux kernels seem to read properly - files >= 4 GiB - 1. - A clumsy remedy for this limit is to backup file pieces and to - concatenate them at restore time. A well tested chopping size is - 2047m. It is permissible to request a higher byte_count than - available. The resulting file will be truncated to the correct - size of a final piece. To request a byte_offset higher than - available yields no file in the ISO image but a SORRY event. E.g: - -cut_out /my/disk/file 0 2047m \ - /file/part_1_of_3_at_0_with_2047m_of_5753194821 \ - -cut_out /my/disk/file 2047m 2047m \ - /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \ - -cut_out /my/disk/file 4094m 2047m \ - /file/part_3_of_3_at_4094m_with_2047m_of_5753194821 - While command -split_size is set larger than 0, and if all pieces - of a file reside in the same ISO directory with no other files, and - if the names look like above, then their ISO directory will be - recognized and handled like a regular file. This affects commands - -compare*, -update*, and overwrite situations. See command - -split_size for details. --cpr disk_path [***] iso_rr_path - Insert the given files or directory trees from filesystem into the - ISO image. - The rules for generating the ISO addresses are similar as with - shell command cp -r. Nevertheless, directories of the iso_rr_path - are created if necessary. Especially a not yet existing - iso_rr_path will be handled as directory if multiple disk_paths are - present. The leafnames of the multiple disk_paths will be grafted - under that directory as would be done with an existing directory. - If a single disk_path is present then a non-existing iso_rr_path - will get the same type as the disk_path. - If a disk_path does not begin with '/' then -cdx is prepended. If - the iso_rr_path does not begin with '/' then -cd is prepended. --mkdir iso_rr_path [...] - Create empty directories if they do not exist yet. Existence as - directory generates a WARNING event, existence as other file causes - a FAILURE event. --lns target_text iso_rr_path - Create a symbolic link with address iso_rr_path which points to - target_text. iso_rr_path may not exist yet. - Hint: Command -clone produces the ISO equivalent of a hard link. --clone iso_rr_path_original iso_rr_path_copy - Create a copy of the ISO file object iso_rr_path_original with the - new address iso_rr_path_copy. If the original is a directory then - copy all files and directories underneath. If iso_rr_path_original - is a boot catalog file, then it gets not copied but is silently - ignored. - The copied ISO file objects have the same attributes. Copied data - files refer to the same content source as their originals. The - copies may then be manipulated independendly of their originals. - This command will refuse execution if the address iso_rr_path_copy - already exists in the ISO tree. --cp_clone iso_rr_path_original [***] iso_rr_path_dest - Create copies of one or more ISO file objects as with command - -clone. In case of collision merge directories with existing ones, - but do not overwrite existing ISO file objects. - The rules for generating the copy addresses are the same as with - command -cpr (see above) or shell command cp -r. Other than with - -cpr, relative iso_rr_path_original will get prepended the -cd path - and not the -cdx path. Consider to -mkdir iso_rr_path_dest before - -cp_clone so the copy address does not depend on the number of - iso_rr_path_original parameters. - - -File: xorriso.info, Node: SetInsert, Next: Manip, Prev: Insert, Up: Commands - -9.5 Settings for file insertion -=============================== - --file_size_limit value [value [...]] -- - Set the maximum permissible size for a single data file. The - values get summed up for the actual limit. If the only value is - "off" then the file size is not limited by 'xorriso'. Default is a - limit of 100 extents, 4g -2k each: - -file_size_limit 400g -200k -- - When mounting ISO 9660 filesystems, old operating systems can - handle only files up to 2g -1 --. Newer ones are good up to 4g -1 - --. You need quite a new Linux kernel to read correctly the final - bytes of a file >= 4g if its size is not aligned to 2048 byte - blocks. - 'xorriso''s own data read capabilities are not affected by - operating system size limits. Such limits apply to mounting only. - Nevertheless, the target filesystem of an -extract must be able to - take the file size. --not_mgt code[:code[...]] - Control the behavior of the exclusion lists. - Exclusion processing happens before disk_paths get mapped to the - ISO image and before disk files get compared with image files. The - absolute disk path of the source is matched against the -not_paths - list. The leafname of the disk path is matched against the - patterns in the -not_leaf list. If a match is detected then the - disk path will not be regarded as an existing file and not be added - to the ISO image. - Several codes are defined. The _on/_off settings persist until - they are revoked by their_off/_on counterparts. - "erase" empties the lists which were accumulated by -not_paths and - -not_leaf. - "reset" is like "erase" but also re-installs default behavior. - "off" disables exclusion processing temporarily without - invalidating the lists and settings. - "on" re-enables exclusion processing. - "param_off" applies exclusion processing only to paths below - disk_path parameter of commands. I.e. explicitly given disk_paths - are exempted from exclusion processing. - "param_on" applies exclusion processing to command parameters as - well as to files below such parameters. - "subtree_off" with "param_on" excludes parameter paths only if they - match a -not_paths item exactly. - "subtree_on" additionally excludes parameter paths which lead to a - file address below any -not_paths item. - "ignore_off" treats excluded disk files as if they were missing. - I.e. they get reported with -compare and deleted from the image - with -update. - "ignore_on" keeps excluded files out of -compare or -update - activities. --not_paths disk_path [***] - Add the given paths to the list of excluded absolute disk paths. - If a given path is relative, then the current -cdx is prepended to - form an absolute path. Pattern matching, if enabled, happens at - definition time and not when exclusion checks are made. - (Do not forget to end the list of disk_paths by "--") --not_leaf pattern - Add a single shell parser style pattern to the list of exclusions - for disk leafnames. These patterns are evaluated when the - exclusion checks are made. --not_list disk_path - Read lines from disk_path and use each of them either as -not_paths - parameter, if they contain a / character, or as -not_leaf pattern. --quoted_not_list disk_path - Like -not_list but with quoted input reading rules. Each word is - handled as one parameter for -not_paths or -not_leaf. --follow occasion[:occasion[...]] - Enable or disable resolution of symbolic links and mountpoints - under disk_paths. This applies to actions -add, -du*x, -ls*x, - -findx, -concat, and to -disk_pattern expansion. - There are three kinds of follow decisison to be made: - *link* is the hop from a symbolic link to its target file object - for the purpose of reading. I.e. not for command -concat. If - enabled then symbolic links are handled as their target file - objects, else symbolic links are handled as themselves. - *mount* is the hop from one filesystem to another subordinate - filesystem. If enabled then mountpoint directories are handled as - any other directory, else mountpoints are handled as empty - directories if they are encountered in directory tree traversals. - *concat* is the hop from a symbolic link to its target file object - for the purpose of writing. I.e. for command -concat. This is a - security risk ! - Less general than above occasions: - *pattern* is mount and link hopping, but only during -disk_pattern - expansion. - *param* is link hopping for parameter words (after eventual pattern - expansion). If enabled then -ls*x will show the link targets - rather than the links themselves. -du*x, -findx, and -add will - process the link targets but not follow links in an eventual - directory tree below the targets (unless "link" is enabled). - Occasions can be combined in a colon separated list. All occasions - mentioned in the list will then lead to a positive follow decision. - - *off* prevents any positive follow decision. Use it if no other - occasion applies. - Shortcuts: - *default* is equivalent to "pattern:mount:limit=100". - *on* always decides positive. Equivalent to "link:mount:concat". - - Not an occasion but an optional setting is: - *limit=* which sets the maximum number of link hops. A - link hop consists of a sequence of symbolic links and a final - target of different type. Nevertheless those hops can loop. - Example: - $ ln -s .. uploop - Link hopping has a built-in loop detection which stops hopping at - the first repetition of a link target. Then the repeated link is - handled as itself and not as its target. Regrettably one can - construct link networks which cause exponential workload before - their loops get detected. The number given with "limit=" can curb - this workload at the risk of truncating an intentional sequence of - link hops. --pathspecs "on"|"off"|"as_mkisofs" - Control parameter interpretation with 'xorriso' actions -add and - -path_list. - Mode "as_mkisofs" enables pathspecs of the form - *iso_rr_path=disk_path* - like with program mkisofs -graft-points. - All characters '\' must be escaped in both, iso_rr_path and - disk_path. The character '=' must be escaped in the iso_rr_path - and may or may not be escaped in the disk_path. This mode - temporarily disables -disk_pattern expansion for command -add. - Mode "on" does nearly the same. But '=' must only be escaped in - the iso_rr_path and '\' must not be escaped at all. This has the - disadvantage that one cannot express an iso_rr_path which ends by - '\'. - Mode "off" disables pathspecs of the form target=source and - re-enables -disk_pattern expansion. --overwrite "on"|"nondir"|"off" - Allow or disallow overwriting of existing files in the ISO image by - files with the same name. - With setting "off", name collisions with at least one non-directory - file cause FAILURE events. Collisions of two directories lead to - merging of their file lists. - With setting "nondir", only directories are protected by such - events, other existing file types get treated with -rm before the - new file gets added. Setting "on" enables automatic -rm_r. I.e. - a non-directory can replace an existing directory and all its - subordinates. - If restoring of files is enabled, then the overwrite rule applies - to the target file objects on disk as well, but "on" is downgraded - to "nondir". --split_size number["k"|"m"] - Set the threshold for automatic splitting of regular files. Such - splitting maps a large disk file onto a ISO directory with several - part files in it. This is necessary if the size of the disk file - exceeds -file_size_limit. Older operating systems can handle files - in mounted ISO 9660 filesystems only if they are smaller than 2 GiB - or in other cases 4 GiB. - Default is 0 which will exclude files larger than -file_size_limit - by a FAILURE event. A well tested -split_size is 2047m. Sizes - above -file_size_limit are not permissible. - While command -split_size is set larger than 0 such a directory - with split file pieces will be recognized and handled like a - regular file by commands -compare* , -update*, and in overwrite - situations. There are -osirrox parameters "concat_split_on" and - "concat_split_off" which control the handling when files get - restored to disk. - In order to be recognizable, the names of the part files have to - describe the splitting by 5 numbers: - part_number,total_parts,byte_offset,byte_count,disk_file_size - which are embedded in the following text form: - part_#_of_#_at_#_with_#_of_# - Scaling characters like "m" or "k" are taken into respect. All - digits are interpreted as decimal, even if leading zeros are - present. - E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 - No other files are allowed in the directory. All parts have to be - present and their numbers have to be plausible. E.g. byte_count - must be valid as -cut_out parameter and their contents may not - overlap. - - -File: xorriso.info, Node: Manip, Next: CmdFind, Prev: SetInsert, Up: Commands - -9.6 File manipulations -====================== - -The following commands manipulate files in the ISO image, regardless -whether they stem from the loaded image or were newly inserted. - --iso_rr_pattern "on"|"ls"|"off" - Set the pattern expansion mode for the iso_rr_path parameters of - several commands which support this feature. - Setting "off" disables pattern expansion for all commands which are - marked in this man page by "iso_rr_path [***]" or "iso_rr_pattern - [***]". - Setting "on" enables it for all those commands. - Setting "ls" enables it only for those which are marked by - "iso_rr_pattern [***]". - Default is "on". --rm iso_rr_path [***] - Delete the given files from the ISO image. - Note: This does not free any space on the -indev medium, even if - the deletion is committed to that same medium. - The image size will shrink if the image is written to a different - medium in modification mode. --rm_r iso_rr_path [***] - Delete the given files or directory trees from the ISO image. See - also the note with command -rm. --rmdir iso_rr_path [***] - Delete empty directories. --move iso_rr_path iso_rr_path - Rename the file given by the first (origin) iso_rr_path to the - second (destination) iso_rr_path. Deviate from rules of shell - command mv by not moving the origin file underneath an existing - destination directory. The origin file will rather replace such a - directory, if this is allowed by command -overwrite. --mv iso_rr_path [***] iso_rr_path - Rename the given file objects in the ISO tree to the last parameter - in the list. Use the same rules as with shell command mv. - If pattern expansion is enabled and if the last parameter contains - wildcard characters then it must match exactly one existing file - address, or else the command fails with a FAILURE event. --chown uid iso_rr_path [***] - Set ownership of file objects in the ISO image. uid may either be - a decimal number or the name of a user known to the operating - system. --chown_r uid iso_rr_path [***] - Like -chown but affecting all files below eventual directories. --chgrp gid iso_rr_path [***] - Set group attribute of file objects in the ISO image. gid may - either be a decimal number or the name of a group known to the - operating system. --chgrp_r gid iso_rr_path [***] - Like -chgrp but affecting all files below eventual directories. --chmod mode iso_rr_path [***] - Equivalent to shell command chmod in the ISO image. mode is either - an octal number beginning with "0" or a comma separated list of - statements of the form [ugoa]*[+-=][rwxst]* . - Like: go-rwx,u+rwx . - *Personalities*: u=user, g=group, o=others, a=all - *Operators*: + adds given permissions, - revokes given permissions, - = revokes all old permissions and then adds the given ones. - *Permissions*: r=read, w=write, x=execute|inspect, s=setuid|setgid, - t=sticky bit - For octal numbers see man 2 stat. --chmod_r mode iso_rr_path [***] - Like -chmod but affecting all files below eventual directories. --setfacl acl_text iso_rr_path [***] - Attach the given ACL to the given iso_rr_paths. If the files - already have ACLs, then those get deleted before the new ones get - into effect. If acl_text is empty, or contains the text "clear" or - the text "--remove-all", then the existing ACLs will be removed and - no new ones will be attached. Any other content of acl_text will - be interpreted as a list of ACL entries. It may be in the long - multi-line format as put out by -getfacl but may also be - abbreviated as follows: - ACL entries are separated by comma or newline. If an entry is - empty text or begins with "#" then it will be ignored. A valid - entry has to begin by a letter out of {ugom} for "user", "group", - "other", "mask". It has to contain two colons ":". A non-empty - text between those ":" gives a user id or group id. After the - second ":" there may be letters out of {rwx- #}. The first three - give read, write, or execute permission. Letters "-", " " and TAB - are ignored. "#" causes the rest of the entry to be ignored. - Letter "X" or any other letters are not supported. Examples: - g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw - group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw- - A valid entry may be prefixed by "d", some following characters and - ":". This indicates that the entry goes to the "default" ACL - rather than to the "access" ACL. Example: - u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx --setfacl_r acl_text iso_rr_path [***] - Like -setfacl but affecting all files below eventual directories. --setfacl_list disk_path - Read the output of -getfacl_r or shell command getfacl -R and apply - it to the iso_rr_paths as given in lines beginning with "# file:". - This will change ownership, group and ACL of the given files. If - disk_path is "-" then lines are read from standard input. Line "@" - ends the list, "@@@" aborts without changing the pending - iso_rr_path. - Since -getfacl and getfacl -R strip leading "/" from file paths, - the setting of -cd does always matter. --setfattr [-]name value iso_rr_path [***] - Attach the given xattr pair of name and value to the given - iso_rr_paths. If the given name is prefixed by "-", then the pair - with that name gets removed from the xattr list. If name is - "--remove-all" then all user namespace xattr of the given - iso_rr_paths get deleted. In case of deletion, value must be an - empty text. - Which names are permissible depends on the setting of command - -xattr. "on" or "user" restricts them to namespace "user". I.e. - a name has to look like "user.x" or "user.whatever". - -xattr setting "any" enables names from all namespaces except - "isofs". - Values and names undergo the normal input processing of 'xorriso'. - See also command -backslash_codes. Other than with command - -setfattr_list, the byte value 0 cannot be expressed via -setfattr. --setfattr_r [-]name value iso_rr_path [***] - Like -setfattr but affecting all files below eventual directories. --setfattr_list disk_path - Read the output format of -getfattr_r or shell command getfattr -Rd - and apply it to the iso_rr_paths as given in lines beginning with - "# file:". All previously existing xattr of the acceptable - namespaces will be deleted before the new xattr get attached. The - set of acceptable names depends on the setting of command -xattr. - If disk_path is "-" then lines are read from standard input. - Since -getfattr and getfattr -Rd strip leading "/" from file paths, - the setting of -cd does always matter. - Empty input lines and lines which begin by "#" will be ignored - (except "# file:"). Line "@" ends the list, "@@@" aborts without - changing the pending iso_rr_path. Other input lines must have the - form - name="value" - The separator "=" is not allowed in names. Value may contain any - kind of bytes. It must be in quotes. Trailing whitespace after - the end quote will be ignored. Non-printables bytes and quotes - must be represented as \XYZ by their octal 8-bit code XYZ. Use code - \000 for 0-bytes. --alter_date type timestring iso_rr_path [***] - Alter the date entries of files in the ISO image. type may be one - of the following: - "a" sets access time, updates ctime. - "m" sets modification time, updates ctime. - "b" sets access time and modification time, updates ctime. - "a-c", "m-c", and "b-c" set the times without updating ctime. - "c" sets the ctime. - timestring may be in the following formats (see also section - EXAMPLES): - As expected by program date: MMDDhhmm[[CC]YY][.ss]] - As produced by program date: - [Day] MMM DD hh:mm:ss [TZON] YYYY - Relative times counted from current clock time: - +|-Number["s"|"h"|"d"|"w"|"m"|"y"] - where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d, - "y"=365.25d plus 1d added to multiplication result. - Absolute seconds counted from Jan 1 1970: - =Number - 'xorriso''s own timestamps: - YYYY.MM.DD[.hh[mm[ss]]] - scdbackup timestamps: - YYMMDD[.hhmm[ss]] - where "A0" is year 2000, "B0" is 2010, etc. - ECMA-119 volume timestamps: - YYYYMMDDhhmmsscc - These are normally given as GMT. The suffix "LOC" causes local - timezone conversion. E.g. 2013010720574700, 2013010720574700LOC. - The last two digits cc (centiseconds) will be ignored, but must be - present in order to make the format recognizable. - Example: - -alter_date m-c 2013.11.27.103951 /file1 /file2 - - This command does not persistently apply to the boot catalog, which - gets fresh timestamps at -commit time. Command -volume_date "uuid" - can set this time value. --alter_date_r type timestring iso_rr_path [***] - Like -alter_date but affecting all files below eventual - directories. --hide hide_state iso_rr_path [***] - Prevent the names of the given files from showing up in the - directory trees of ISO 9660 and/or Joliet and/or HFS+ when the - image gets written. The data content of such hidden files will be - included in the resulting image, even if they do not show up in any - directory. But you will need own means to find nameless data in - the image. - Warning: Data which are hidden from the ISO 9660 tree will not be - copied by the write method of modifying. - Possible values of hide_state are: "iso_rr" for hiding from ISO - 9660 tree, "joliet" for Joliet tree, "hfsplus" for HFS+, "on" for - them all. "off" means visibility in all directory trees. - These values may be combined. E.g.: joliet:hfsplus - This command does not apply to the boot catalog. Rather use: - -boot_image "any" "cat_hidden=on" - - -File: xorriso.info, Node: CmdFind, Next: Filter, Prev: Manip, Up: Commands - -9.7 Tree traversal command -find -================================ - --find iso_rr_path [test [op] [test ...]] [-exec action [params]] -- - A restricted substitute for shell command find in the ISO image. - It performs an action on matching file objects at or below - iso_rr_path. - If not used as last command in the line then the parameter list - needs to get terminated by "--". - Tests are optional. If they are omitted then action is applied to - all file objects. If tests are given then they form together an - expression. The action is applied only if the expression matches - the file object. Default expression operator between tests is - -and, i.e. the expression matches only if all its tests match. - Available tests are: - - -name pattern : - Matches if pattern matches the file leaf name. If the pattern - does not contain any of the characters "*?[", then it will be - truncated according to -file_name_limit and thus match the - truncated name in the ISO filesystem. - -wholename pattern : - Matches if pattern matches the file path as it would be - printed by action "echo". Character '/' can be matched by - wildcards. If pattern pieces between '/' do not contain any - of the characters "*?[", they will be truncated according to - -file_name_limit. - -disk_name pattern : - Like -name but testing the leaf name of the file source on - disk. Can match only data files which do not stem from the - loaded image, or for directories above such data files. With - directories the result can change between -find runs if their - content stems from multiple sources. - -disk_path disk_path : - Matches if the given disk_path is equal to the path of the - file source on disk. The same restrictions apply as with - -disk_name. - -type type_letter : - Matches files of the given type: "block", "char", "dir", - "pipe", "file", "link", "socket", "eltorito", and "Xotic" - which matches what is not matched by the other types. - Only the first letter is interpreted. E.g.: -find / -type d - -maxdepth number : - Matches only files which are at most at the given depth level - relative to the iso_rr_path where -find starts. That path - itself is at depth 0, its directory children are at 1, their - directory children at 2, and so on. - -mindepth number : - Matches only files which are at least at the given depth - level. - -damaged : - Matches files which use data blocks marked as damaged by a - previous run of -check_media. The damage info vanishes when a - new ISO image gets loaded. - Note that a MD5 session mismatch marks all files of the - session as damaged. If finer distinction is desired, perform - -md5 off before -check_media. - -pending_data : - Matches files which get their content from outside the loaded - ISO image. - -lba_range start_lba block_count : - Matches files which use data blocks within the range of - start_lba and start_lba+block_count-1. - -has_acl : - Matches files which have a non-trivial ACL. - -has_xattr : - Matches files which have xattr name-value pairs from user - namespace. - -has_aaip : - Matches files which have ACL or any xattr. - -has_any_xattr : - Matches files which have any xattr other than ACL. - -has_md5 : - Matches data files which have MD5 checksums. - -has_hfs_crtp creator type : - Matches files which have the given HFS+ creator and type - attached. These are codes of 4 characters which get stored if - -hfsplus is enabled. Use a single dash '-' as wildcard that - matches any such code. E.g:. - -has_hfs_crtp YYDN TEXT - -has_hfs_crtp - - - -has_hfs_bless blessing : - Matches files which bear the given HFS+ blessing. It may be - one of : "ppc_bootdir", "intel_bootfile", "show_folder", - "os9_folder", "osx_folder", "any". See also action - set_hfs_bless. - -has_filter : - Matches files which are filtered by -set_filter. - -hidden hide_state : - Matches files which are hidden in "iso_rr" tree, in "joliet" - tree, in "hfsplus" tree, in all trees ("on"), or not hidden in - any tree ("off"). - Those which are hidden in some tree match -not -hidden "off". - -bad_outname namespace : - Matches files with names which change when converted forth and - back between the local character set and one of the namespaces - "rockridge", "joliet", "ecma119", "hfsplus". - All applicable -compliance rules are taken into respect. Rule - "omit_version" is always enabled, because else namespaces - "joliet" and "ecma119" would cause changes with every - non-directory name. Consider to also enable rules - "no_force_dots" and "no_j_force_dots". - The namespaces use different character sets and apply further - restrictions to name length, permissible characters, and - mandatory name components. "rockridge" uses the character set - defined by -out_charset, "joliet" uses UCS-2BE, "ecma119" uses - ASCII, "hfsplus" uses UTF-16BE. - -name_limit_blocker length : - Matches file names which would prevent command - -file_name_limit with the given length. The command itself - reports only the first problem file. - -prune : - If this test is reached and the tested file is a directory - then -find will not dive into that directory. This test - itself does always match. - -use_pattern "on"|"off" : - This pseudo test controls the interpretation of wildcards with - tests -name, -wholename, and -disk_name. Default is "on". If - interpretation is disabled by "off", then the parameters of - -name, -wholename, and -disk_name have to match literally - rather than as search pattern. This test itself does always - match. - -or_use_pattern "on"|"off" : - Like -use_pattern, but automatically appending the test by -or - rather than by -and. Further the test itself does never - match. So a subsequent test -or will cause its other operand - to be performed. - -decision "yes"|"no" : - If this test is reached then the evaluation ends immediately - and action is performed if the decision is "yes" or "true". - See operator -if. - -true and -false : - Always match or match not, respectively. Evaluation goes on. - -sort_lba : - Always match. This causes -find to perform its action in a - sequence sorted by the ISO image block addresses of the files. - It may improve throughput with actions which read data from - optical drives. Action will always get the absolute path as - parameter. - Available operators are: - -not : - Matches if the next test or sub expression does not match. - Several tests do this specifically: - -undamaged, -lba_range with negative start_lba, -has_no_acl, - -has_no_xattr, -has_no_aaip, -has_no_filter . - -and : - Matches if both neighboring tests or expressions match. - -or : - Matches if at least one of both neighboring tests or - expressions matches. - -sub ... -subend or ( ... ) : - Enclose a sub expression which gets evaluated first before it - is processed by neighboring operators. Normal precedence is: - -not, -or , -and. - -if ... -then ... -elseif ... -then ... -else ... -endif : - Enclose one or more sub expressions. If the -if expression - matches, then the -then expression is evaluated as the result - of the whole expression up to -endif. Else the next -elseif - expression is evaluated and if it matches, its -then - expression. Finally in case of no match, the -else expression - is evaluated. There may be more than one -elseif. Neither - -else nor -elseif are mandatory. If -else is missing and - would be hit, then the result is a non-match. - -if-expressions are the main use case for above test - -decision. - - Default action is *echo*, i.e. to print the address of the found - file. Other actions are certain 'xorriso' commands which get - performed on the found files. These commands may have specific - parameters. See also their particular descriptions. - - chown and chown_r - change the ownership and get the user id as parameter. E.g.: - -exec chown thomas -- - chgrp and chgrp_r - change the group attribute and get the group id as parameter. - E.g.: -exec chgrp_r staff -- - chmod and chmod_r - change access permissions and get a mode string as parameter. - E.g.: -exec chmod a-w,a+r -- - alter_date and alter_date_r - change the timestamps. They get a type character and a - timestring as parameters. - E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" -- - set_to_mtime - sets the ctime and atime to the value found in mtime. - lsdl - prints file information like shell command ls -dl. - compare - performs command -compare with the found file address as - iso_rr_path and the corresponding file address below its - parameter disk_path_start. For this the iso_rr_path of the - -find command gets replaced by the disk_path_start. - E.g.: -find /thomas -exec compare /home/thomas -- - update - performs command -update with the found file address as - iso_rr_path. The corresponding file address is determined - like with above action "compare". - update_merge - is like update but does not delete the found file if it is - missing on disk. It may be run several times and records with - all visited files whether their counterpart on disk has - already been seen by one of the update_merge runs. Finally, a - -find run with action "rm_merge" may remove all files that saw - no counterpart on disk. - Up to the next "rm_merge" or "clear_merge" all newly inserted - files will get marked as having a disk counterpart. - rm - removes the found iso_rr_path from the image if it is not a - directory with files in it. I.e. this "rm" includes "rmdir". - - rm_r - removes the found iso_rr_path from the image, including whole - directory trees. - rm_merge - removes the found iso_rr_path if it was visited by one or more - previous actions "update_merge" and saw no counterpart on disk - in any of them. The marking from the update actions is - removed in any case. - clear_merge - removes an eventual marking from action "update_merge". - report_damage - classifies files whether they hit a data block that is marked - as damaged. The result is printed together with the address - of the first damaged byte, the maximum span of damages, file - size, and the path of the file. - report_lba - prints files which are associated to image data blocks. It - tells the logical block address, the block number, the byte - size, and the path of each file. There may be reported more - than one line per file if the file has more than one section. - In this case each line has a different extent number in column - "xt". - report_sections - like report_lba but telling the byte sizes of the particular - sections rather than the overall byte size of the file. - getfacl - prints access permissions in ACL text form to the result - channel. - setfacl - attaches ACLs after removing existing ones. The new ACL is - given in text form as defined with command -setfacl. - E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw -- - getfattr - prints xattr name-value pairs to the result channel. The - choice of namespaces depends on the setting of command -xattr: - "on" or "user" restricts it to the namespace "user", "any" - only omits namespace "isofs". - get_any_xattr - prints xattr name-value pairs from any namespace except ACL to - the result channel. This is mostly for debugging of namespace - "isofs". - list_extattr mode - prints a script to the result channel, which would use FreeBSD - command setextattr to set the file's xattr name-value pairs of - user namespace. Parameter mode controls the form of the - output of names and values. Default mode "e" prints harmless - characters in shell quotation marks, but represents texts with - octal 001 to 037 and 0177 to 0377 by an embedded echo -e - command. Mode "q" prints any characters in shell quotation - marks. This might not be terminal-safe but should work in - script files. Mode "r" uses no quotation marks. Not safe. - Mode "b" prints backslash encoding. Not suitable for shell - parsing. - E.g. -exec list_extattr e - - Command -backslash_codes does not affect the output. - get_md5 - prints the MD5 sum, if recorded, together with file path. - check_md5 - compares the MD5 sum, if recorded, with the file content and - reports if mismatch. - E.g.: -find / -not -pending_data -exec check_md5 FAILURE -- - make_md5 - equips a data file with an MD5 sum of its content. Useful to - upgrade the files in the loaded image to full MD5 coverage by - the next commit with -md5 "on". - E.g.: -find / -type f -not -has_md5 -exec make_md5 -- - setfattr - sets or deletes xattr name value pairs. - E.g.: -find / -has_xattr -exec setfattr --remove-all " -- - set_hfs_crtp - adds, changes, or removes HFS+ creator and type attributes. - E.g.: -exec set_hfs_crtp YYDN TEXT - E.g.: -find /my/dir -prune -exec set_hfs_crtp -delete - - get_hfs_crtp - prints the HFS+ creator and type attributes together with the - iso_rr_path, if the file has such attributes at all. - E.g.: -exec get_hfs_crtp - set_hfs_bless - applies or removes HFS+ blessings. They are roles which can - be attributed to up to four directories and a data file: - "ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", - "osx_folder". - They may be abbreviated as "p", "i", "s", "9", and "x". - Each such role can be attributed to at most one file object. - "intel_bootfile" is the one that would apply to a data file. - All others apply to directories. The -find run will end as - soon as the first blessing is issued. The previous bearer of - the blessing will lose it then. No file object can bear more - than one blessing. - E.g.: -find /my/blessed/directory -exec set_hfs_bless p - Further there is blessing "none" or "n" which revokes any - blessing from the found files. This -find run will not stop - when the first match is reached. - E.g.: -find / -has_hfs_bless any -exec set_hfs_bless none - get_hfs_bless - prints the HFS+ blessing role and the iso_rr_path, if the file - is blessed at all. - E.g.: -exec get_hfs_bless - set_filter - applies or removes filters. - E.g.: -exec set_filter --zisofs -- - mkisofs_r - applies the rules of mkisofs -r to the file object: - user id and group id become 0, all r-permissions get granted, - all w denied. If there is any x-permission, then all three x - get granted. s- and t-bits get removed. - sort_weight - attributes a LBA weight number to regular files. - The number may range from -2147483648 to 2147483647. The - higher it is, the lower will be the block address of the file - data in the emerging ISO image. Currently the boot catalog - has a hardcoded weight of 1 billion. Normally it should - occupy the block with the lowest possible address. - Data files which are loaded by -indev or -dev get a weight - between 1 and 2 exp 28 = 268,435,456, depending on their block - address. This shall keep them roughly in the same order if - the write method of modifying is applied. - Data files which are added by other commands get an initial - weight of 0. Boot image files have a default weight of 2. - E.g.: -exec sort_weight 3 -- - show_stream - shows the content stream chain of a data file. - show_stream_id - is like show_stream, but also prints between stream type and - first ":" in square brackets libisofs id numbers: - [fs_id,dev_id,ino_id]. - hide - brings the file into one of the hide states "on", "iso_rr", - "joliet", "hfsplus", "off". They may be combined. E.g.: - joliet:hfsplus - E.g.: - -find / -disk_name *_secret -exec hide on - print_outname - prints in the first line the filename as registered by the - program model, and in the second line the filename after - conversion forth and back between local character set and one - of the namespaces "rockridge", "joliet", "ecma119", or - "hfsplus". The third output line is "-" . - The name conversion does not take into respect the possibility - of name collisions in the target namespace. Such collisions - are most likely in "joliet" and "ecma119", where they get - resolved by automatic file name changes. - E.g.: - -find / -bad_outname joliet -exec print_outname joliet - estimate_size - prints a lower and an upper estimation of the number of blocks - which the found files together will occupy in the emerging ISO - image. This does not account for the superblock, for the - directories in the -find path, or for image padding. - find - performs another run of -find on the matching file address. - It accepts the same params as -find, except iso_rr_path. - E.g.: - -find / -name '???' -type d -exec find -name '[abc]*' -exec - chmod a-w,a+r -- - - -File: xorriso.info, Node: Filter, Next: Writing, Prev: CmdFind, Up: Commands - -9.8 Filters for data file content -================================= - -*Filters* may be installed between data files in the ISO image and their -content source outside the image. They may also be used vice versa -between data content in the image and target files on disk. - - Built-in filters are "--zisofs" and "--zisofs-decode". The former is -to be applied via -set_filter, the latter is automatically applied if -zisofs compressed content is detected with a file when loading the ISO -image. -Another built-in filter pair is "--gzip" and "--gunzip" with suffix -".gz". They behave about like external gzip and gunzip but avoid -forking a process for each single file. So they are much faster if -there are many small files. - --external_filter name option[:option] program_path [arguments] -- - Register a content filter by associating a name with a program - path, program arguments, and some behavioral options. Once - registered it can be applied to multiple data files in the ISO - image, regardless whether their content resides in the loaded ISO - image or in the local filesystem. External filter processes may - produce synthetic file content by reading the original content from - stdin and writing to stdout whatever they want. They must deliver - the same output on the same input in repeated runs. - Options are: - "default" means that no other option is intended. - "suffix=..." sets a file name suffix. If it is not empty then it - will be appended to the file name or removed from it. - "remove_suffix" will remove a file name suffix rather than - appending it. - "if_nonempty" will leave 0-sized files unfiltered. - "if_reduction" will try filtering and revoke it if the content size - does not shrink. - "if_block_reduction" will revoke if the number of 2 kB blocks does - not shrink. - "used=..." is ignored. Command -status shows it with the number - of files which currently have the filter applied. - Examples: - -external_filter bzip2 suffix=.bz2:if_block_reduction \ - /usr/bin/bzip2 -- - -external_filter bunzip2 suffix=.bz2:remove_suffix \ - /usr/bin/bunzip2 -- --unregister_filter name - Remove an -external_filter registration. This is only possible if - the filter is not applied to any file in the ISO image. --close_filter_list - Irrevocably ban commands -concat "pipe", -external_filter, and - -unregister_filter, but not -set_filter. Use this to prevent - external filtering in general or when all intended filters are - registered and -concat mode "pipe" shall be disallowed. External - filters may also be banned totally at compile time of 'xorriso'. - By default they are banned if 'xorriso' runs under setuid - permission. --set_filter name iso_rr_path [***] - Apply an -external_filter or a built-in filter to the given data - files in the ISO image. If the filter suffix is not empty , then - it will be applied to the file name. Renaming only happens if the - filter really gets attached and is not revoked by its options. By - default files which already bear the suffix will not get filtered. - The others will get the suffix appended to their names. If the - filter has option "remove_suffix", then the filter will only be - applied if the suffix is present and can be removed. Name oversize - or collision caused by suffix change will prevent filtering. - With most filter types this command will immediately run the filter - once for each file in order to determine the output size. Content - reading operations like -extract , -compare and image generation - will perform further filter runs and deliver filtered content. - At image generation time the filter output must still be the same - as the output from the first run. Filtering for image generation - does not happen with files from the loaded ISO image if the write - method of growing is in effect (i.e -indev and -outdev are - identical). - The reserved filter name "--remove-all-filters" revokes filtering. - This will revoke suffix renamings as well. Use - "--remove-all-filters+" to prevent any suffix renaming. - Attaching or detaching filters will not alter the state of - -changes_pending. If the filter manipulations shall be the only - changes in a write run, then explicitly execute -changes_pending - "yes". --set_filter_r name iso_rr_path [***] - Like -set_filter but affecting all data files below eventual - directories. - - -File: xorriso.info, Node: Writing, Next: SetWrite, Prev: Filter, Up: Commands - -9.9 Writing the result, drive control -===================================== - -(see also paragraph about settings below) - --rollback - Discard the manipulated ISO image and reload it from -indev. (Use - -rollback_end if immediate program end is desired.) --changes_pending "no"|"yes"|"mkisofs_printed"|"show_status" - Write runs are performed only if a change of the image has been - made since the image was loaded or created blank. Vice versa the - program will start a write run for pending changes when it ends - normally (i.e. not by abort and not by command -rollback_end). - The command -changes_pending can be used to override the - automatically determined state. This is mainly useful for setting - state "yes" despite no real changes were made. The sequence - -changes_pending "no" -end is equivalent to the command - -rollback_end. State "mkisofs_printed" is caused by emulation - command -as mkisofs if option -print-size is present. - The pseudo-state "show_status" can be used to print the current - state to result channel. - Image loading or manipulations which happen after this command will - again update automatically the change status of the image. --commit - Perform the write operation. Afterwards, if -outdev is readable, - make it the new -dev and load the image from there. Switch to - growing mode. (A subsequent -outdev will activate modification - mode or blind growing.) -commit is performed automatically at end - of program if there are uncommitted manipulations pending. - So, to perform a final write operation with no new -dev and no new - loading of image, rather execute command -end. If you want to go - on without image loading, execute -commit_eject "none". To eject - after write without image loading, use -commit_eject "all". - To suppress a final write, execute -rollback_end. - - Writing can last quite a while. It is not unnormal with several - types of media that there is no progress visible for the first few - minutes or that the drive gnaws on the medium for a few minutes - after all data have been transmitted. 'xorriso' and the drives are - in a client-server relationship. The drives have much freedom - about what to do with the media. Some combinations of drives and - media simply do not work, despite the promises by their vendors. - If writing fails then try other media or another drive. The reason - for such failure is hardly ever in the code of the various burn - programs but you may well try some of those listed below under SEE - ALSO. --eject "in"|"out"|"all" - Eject the medium in -indev, -outdev, or both drives, respectively. - Note: It is not possible yet to effectively eject disk files. --commit_eject "in"|"out"|"all"|"none" - Combined -commit and -eject. When writing has finished do not make - -outdev the new -dev, and load no ISO image. Rather eject -indev - and/or -outdev. Give up any non-ejected drive. --blank mode - Make media ready for writing from scratch (if not -dummy is - activated). - This affects only the -outdev not the -indev. If both drives are - the same and if the ISO image was altered then this command leads - to a FAILURE event. Defined modes are: as_needed, fast, all, - deformat, deformat_quickest - "as_needed" cares for used CD-RW, DVD-RW and for used overwritable - media by applying -blank "fast". It applies -format "full" to yet - unformatted DVD-RAM and BD-RE. Other media in blank state are - gracefully ignored. Media which cannot be made ready for writing - from scratch cause a FAILURE event. - "fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates - overwritable ISO images. "all" might work more thoroughly and need - more time. - "deformat" converts overwritable DVD-RW into unformatted ones. - "deformat_quickest" is a faster way to deformat or blank DVD-RW but - produces media which are only suitable for a single session. Some - drives announce this state by not offering feature 21h, but some - drives offer it anyway. If feature 21h is missing, then 'xorriso' - will refuse to write on DVD-RW if not command -close is set to - "on". - The progress reports issued by some drives while blanking are quite - unrealistic. Do not conclude success or failure from the reported - percentages. Blanking was successful if no SORRY event or worse - occurred. - Mode may be prepended by "force:" in order to override the - evaluation of the medium state by libburn. E.g. "force:fast". - Blanking will nevertheless only succeed if the drive is willing to - do it. --format mode - Convert unformatted DVD-RW into overwritable ones, "de-ice" DVD+RW, - format newly purchased BD-RE or BD-R, re-format DVD-RAM or BD-RE. - Defined modes are: - as_needed, full, fast, by_index_, fast_by_index_, - by_size_, fast_by_size_, without_spare - "as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or - blank unformatted BD-R. Other media are left untouched. - "full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank - unformatted BD-R. - "fast" does the same as "full" but tries to be quicker. - "by_index_" selects a format out of the descriptor list issued by - command -list_formats. The index number from that list is to be - appended to the mode word. E.g: "by_index_3". - "fast_by_index_" does the same as "by_index_" but tries to be - quicker. - "by_size_" selects a format out of the descriptor list which - provides at least the given size. That size is to be appended to - the mode word. E.g: "by_size_4100m". This applies to media with - Defect Management. On BD-RE it will not choose format 0x31, which - offers no Defect Management. - "fast_by_size_" does the same as "by_size_" but tries to be - quicker. - "without_spare" selects the largest format out of the descriptor - list which provides no Spare Area for Defect Management. On BD-RE - this will be format 0x31. - The formatting action has no effect on media if -dummy is - activated. - Formatting is normally needed only once during the lifetime of a - medium, if ever. But it is a reason for re-formatting if: - DVD-RW was deformatted by -blank, - DVD+RW has read failures (re-format before next write), - DVD-RAM or BD-RE shall change their amount of defect reserve. - BD-R may be written unformatted or may be formatted before first - use. Formatting activates Defect Management which tries to catch - and repair bad spots on media during the write process at the - expense of half speed even with flawless media. - The progress reports issued by some drives while formatting are - quite unrealistic. Do not conclude success or failure from the - reported percentages. Formatting was successful if no SORRY event - or worse occurred. Be patient with apparently frozen progress. --list_formats - Put out a list of format descriptors as reported by the output - drive for the current medium. The list gives the index number - after "Format idx", a MMC format code, the announced size in blocks - (like "2236704s") and the same size in MiB. - MMC format codes are manifold. Most important are: "00h" general - formatting, "01h" increases reserve space for DVD-RAM, "26h" for - DVD+RW, "30h" for BD-RE with reserve space, "31h" for BD-RE without - reserve space, "32h" for BD-R. - Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserve - space. --list_speeds - Put out a list of speed values as reported by the drives with the - loaded media. The list tells read speeds of the input drive and of - the output drive. Further it tells write speeds of the output - drive. - The list of write speeds does not necessarily mean that the medium - is writable or that these speeds are actually achievable. - Especially the lists reported with empty drive or with ROM media - obviously advertise speeds for other media. - It is not mandatory to use speed values out of the listed range. - The drive is supposed to choose a safe speed that is as near to the - desired speed as possible. - At the end of the list, "Write speed L" and "Write speed H" are the - best guesses for lower and upper write speed limit. "Write speed - l" and "Write speed h" may appear only with CD and eventually - override the list of other speed offers. - Only if the drive reports contradicting speed information there - will appear "Write speed 0", which tells the outcome of speed - selection by command -speed 0, if it deviates from "Write speed H". - - "Read speed L" and "Read speed H" tell the minimum and maximum read - speeds, as reported by the drive. They would be chosen by - -read_speed "min" or "max" if they undercut or surpass the built-in - limits. These are "1x", "52xCD", "24xDVD", "20xBD". --list_profiles "in"|"out"|"all" - Put out a list of media types supported by -indev, -outdev, or - both, respectively. The currently recognized type is marked by - text "(current)". --truncate_overwritable entity id adjust - On overwritable medium copy the volume descriptors of an existing - session to the overall descriptors at LBA 0 ff. This makes all - sessions *inaccessible* which are younger than the activated one. - A reason to do this would be read errors in the younger sessions - and the wish to re-write or skip them. - This operation is only allowed if no changes to the loaded - filesystem are pending. If an -indev is acquired then it is - released before the write operation begins and re-acquired only in - case of success. - The parameters "entity" and "id" have the same meaning as with - command -load. They choose the existing ISO session which shall - become the youngest accessible session. Available entity names are - "session", "track", "lba", "sbsector", "volid". "auto" makes few - sense. id is a number or search text as appropriate for the given - entity. - Parameter "adjust" controls the claimed size of the activated - session. Text "new" means the size of the newly activated session - as it was before this command. I.e. the space of the then - inaccessible younger sessions will be re-used when appending more - sessions. - "old" means the size up to the end of the previously youngest - session. I.e. "old" will not free the space of the then - inaccessible younger sessions for re-use. - A number preceded by "+" gives the number of bytes to be added to - "new". A number without "+" gives the overall number of bytes. In - any case the result may not be smaller than "new". Numbers may - have a unit suffix: "d"=512, "k"=1024, "s"=2048, "m"=1024k, - "g"=1024m. - Examples: - Activate session 4 and enable overwriting of the blocks of younger - sessions: - -truncate_overwritable session 4 new - Activate session 4 and claim the blocks of younger sessions as - useless part of session 4: - -truncate_overwritable session 4 old - Let session 4 claim additional 500 MiB as useless data: - -truncate_overwritable session 4 +500m --close_damaged "as_needed"|"force" - Try to close the upcoming track and session if the drive reported - the medium as damaged. This may apply to CD-R, CD-RW, DVD-R, - DVD-RW, DVD+R, DVD+R DL, or BD-R media. It is indicated by warning - messages when the drive gets acquired, and by a remark "but next - track is damaged" with the line "Media status :" of command -toc. - The setting of command -close determines whether the medium stays - appendable. - Mode "as_needed" gracefully refuses on media which are not reported - as damaged. Mode "force" attempts the close operation even with - media which appear undamaged. - No image changes are allowed to be pending before this command is - performed. After closing was attempted, both drives are given up. - - -File: xorriso.info, Node: SetWrite, Next: Bootable, Prev: Writing, Up: Commands - -9.10 Settings for result writing -================================ - -Rock Ridge info will be generated by default. ACLs will be written -according to the setting of command -acl. - --joliet "on"|"off" - If enabled by "on", generate Joliet tree additional to ISO 9660 + - Rock Ridge tree. - --hfsplus "on"|"off" - If enabled by "on", generate a HFS+ filesystem inside the ISO 9660 - image and mark it by Apple Partition Map (APM) entries in the - System Area, the first 32 KiB of the image. - This may collide with data submitted by -boot_image system_area=. - The first 8 bytes of the System Area get overwritten by { 0x45, - 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff } which can be executed as - x86 machine code without negative effects. So if an MBR gets - combined with this feature, then its first 8 bytes should contain - no essential commands. - The next blocks of 2 KiB in the System Area will be occupied by APM - entries. The first one covers the part of the ISO image before the - HFS+ filesystem metadata. The second one marks the range from HFS+ - metadata to the end of file content data. If more ISO image data - follow, then a third partition entry gets produced. Other features - of xorriso might cause the need for more APM entries. - The HFS+ filesystem is not suitable for add-on sessions produced by - the multi-session method of growing. An existing ISO image may - nevertheless be the base for a new image produced by the method of - modifying. If -hfsplus is enabled when -indev or -dev gets - executed, then AAIP attributes get loaded from the input image and - checked for information about HFS creator, filetype, or blessing. - If found, then they get enabled as settings for the next image - production. Therefore it is advisable to perform -hfsplus "on" - before -indev or -dev. - Information about HFS creator, type, and blessings gets stored by - xorriso if -hfsplus is enabled at -commit time. It is stored as - copy outside the HFS+ partition, but rather along with the Rock - Ridge information. xorriso does not read any information from the - HFS+ meta data. - Be aware that HFS+ is case-insensitive although it can record file - names with upper-case and lower-case letters. Therefore, file - names from the iso_rr name tree may collide in the HFS+ name tree. - In this case they get changed by adding underscore characters and - counting numbers. In case of very long names, it might be - necessary to map them to "MANGLED_...". - WARNING: - The HFS+ implementation in libisofs has a limit of 125,829,120 - bytes for the size of the overall directory tree. This suffices - for about 300,000 files of normal name length. If the limit gets - exceeded, a FAILURE event will be issued and the ISO production - will not happen. - --rockridge "on"|"off" - Mode "off" disables production of Rock Ridge information for the - ISO 9660 file objects. The multi-session capabilities of xorriso - depend much on the naming fidelity of Rock Ridge. So it is - strongly discouraged to deviate from default setting "on". --compliance rule[:rule...] - Adjust the compliance to specifications of ISO 9660/ECMA-119 and - its contemporary extensions. In some cases it is worth to deviate - a bit in order to circumvent bugs of the intended reader system or - to get unofficial extra features. - There are several adjustable rules which have a keyword each. If - they are mentioned with this command then their rule gets added to - the relaxation list. This list can be erased by rules "strict" or - "clear". It can be reset to its start setting by "default". All - of the following relaxation rules can be revoked individually by - appending "_off". Like "deep_paths_off". - Rule keywords are: - "iso_9660_level="number chooses level 1 with ECMA-119 names of the - form 8.3 and -file_size_limit <= 4g - 1, or level 2 with ECMA-119 - names up to length 32 and the same -file_size_limit, or level 3 - with ECMA-119 names up to length 32 and -file_size_limit >= 400g - -200k. If necessary -file_size_limit gets adjusted. - "allow_dir_id_ext" allows ECMA-119 names of directories to have a - name extension as with other file types. It does not force dots - and it omits the version number, though. This is a bad tradition - of mkisofs which violates ECMA-119. Especially ISO level 1 only - allows 8 characters in a directory name and not 8.3. - "omit_version" does not add versions (";1") to ECMA-119 and Joliet - file names. - "only_iso_version" does not add versions (";1") to Joliet file - names. - "deep_paths" allows ECMA-119 file paths deeper than 8 levels. - "long_paths" allows ECMA-119 file paths longer than 255 characters. - - "long_names" allows up to 37 characters with ECMA-119 file names. - "no_force_dots" does not add a dot to ECMA-119 file names which - have none. - "no_j_force_dots" does not add a dot to Joliet file names which - have none. - "lowercase" allows lowercase characters in ECMA-119 file names. - "7bit_ascii" allows nearly all 7-bit characters in ECMA-119 file - names. Not allowed are 0x0 and '/'. If not "lowercase" is - enabled, then lowercase letters get converted to uppercase. - "full_ascii" allows all 8-bit characters except 0x0 and '/' in - ECMA-119 file names. - "untranslated_names" might be dangerous for inadverted reader - programs which rely on the restriction to at most 37 characters in - ECMA-119 file names. This rule allows ECMA-119 file names up to 96 - characters with no character conversion. If a file name has more - characters, then image production will fail deliberately. - "untranslated_name_len="number enables untranslated_names with a - smaller limit for the length of file names. 0 disables this - feature, -1 chooses maximum length limit, numbers larger than 0 - give the desired length limit. - "joliet_long_names" allows Joliet leaf names up to 103 characters - rather than 64. - "joliet_long_paths" allows Joliet paths longer than 240 characters. - - "joliet_utf16" encodes Joliet names in UTF-16BE rather than UCS-2. - The difference is with characters which are not present in UCS-2 - and get encoded in UTF-16 by 2 words of 16 bit each. Both words - then stem from a reserved subset of UCS-2. - "always_gmt" stores timestamps in GMT representation with timezone - 0. - "rec_mtime" records with non-RockRidge directory entries the disk - file's mtime and not the creation time of the image. This applies - to the ECMA-119 tree (plain ISO 9660), to Joliet, and to ISO - 9660:1999. "rec_time" is default. If disabled, it gets - automatically re-enabled by -as mkisofs emulation when a pathspec - is encountered. - "new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux but - not for older FreeBSD or for Solaris). This implies - "aaip_susp_1_10_off" which may be changed by subsequent - "aaip_susp_1_10". - Default is "old_rr" which uses Rock Ridge version 1.10. This - implies also "aaip_susp_1_10" which may be changed by subsequent - "aaip_susp_1_10_off". - "aaip_susp_1_10" allows AAIP to be written as unofficial extension - of RRIP rather than as official extension under SUSP-1.12. - "no_emul_toc" saves 64 kB with the first session on overwritable - media but makes the image incapable of displaying its session - history. - "iso_9660_1999" causes the production of an additional directory - tree compliant to ISO 9660:1999. It can record long filenames for - readers which do not understand Rock Ridge. - "old_empty" uses the old way of of giving block addresses in the - range of [0,31] to files with no own data content. The new way is - to have a dedicated block to which all such files will point. - Default setting is - "clear:only_iso_version:deep_paths:long_paths:no_j_force_dots: - always_gmt:old_rr". - Note: The term "ECMA-119 name" means the plain ISO 9660 names and - attributes which get visible if the reader ignores Rock Ridge. --rr_reloc_dir name - Specify the name of the relocation directory in which deep - directory subtrees shall be placed if -compliance is set to - "deep_paths_off" or "long_paths_off". A deep directory is one that - has a chain of 8 parent directories (including root) above itself, - or one that contains a file with an ECMA-119 path of more than 255 - characters. - The overall directory tree will appear originally deep when - interpreted as Rock Ridge tree. It will appear as re-arranged if - only ECMA-119 information is considered. - The default relocation directory is the root directory. By giving - a non-empty name with -rr_reloc_dir, a directory in the root - directory may get this role. If that directory does not already - exist at -commit time, then it will get created and marked for Rock - Ridge as relocation artefact. At least on GNU/Linux it will not be - displayed in mounted Rock Ridge images. - The name must not contain a '/' character and must not be longer - than 255 bytes. --volid text - Specify the volume ID, which most operating systems will consider - to be the volume name of the image or medium. - 'xorriso' accepts any text up to 32 characters, but according to - rarely obeyed specs stricter rules apply: - ECMA-119 demands ASCII characters out of [A-Z0-9_]. Like: - "IMAGE_23" - Joliet allows 16 UCS-2 characters. Like: - "Windows name" - Be aware that the volume id might get used automatically as the - name of the mount point when the medium is inserted into a playful - computer system. - If an ISO image gets loaded while the volume ID is set to default - "ISOIMAGE" or to "", then the volume ID of the loaded image will - become the effective volume id for the next write run. But as soon - as command -volid is performed afterwards, this pending ID is - overridden by the new setting. - Consider this when setting -volid "ISOIMAGE" before executing -dev, - -indev, or -rollback. If you insist in -volid "ISOIMAGE", set it - again after those commands. --volset_id text - Set the volume set ID string to be written with the next -commit. - Permissible are up to 128 characters. This setting gets overridden - by image loading. --publisher text - Set the publisher ID string to be written with the next -commit. - This may identify the person or organisation who specified what - shall be recorded. Permissible are up to 128 characters. This - setting gets overridden by image loading. --application_id text - Set the application ID string to be written with the next -commit. - This may identify the specification of how the data are recorded. - Permissible are up to 128 characters. This setting gets overridden - by image loading. - The special text "@xorriso@" gets converted to the ID string of - 'xorriso' which is normally written as -preparer_id. It is a wrong - tradition to write the program ID as -application_id. --system_id text - Set the system ID string to be written with the next -commit. This - may identify the system which can recognize and act upon the - content of the System Area in image blocks 0 to 15. Permissible - are up to 32 characters. This setting gets overridden by image - loading. --volume_date type timestring - Set one of the four overall timestamps for subsequent image - writing. Available types are: - "c" time when the volume was created. - "m" time when volume was last modified. - "x" time when the information in the volume expires. - "f" time since when the volume is effectively valid. - "all_file_dates" sets mtime, atime, and ctime of all files and - directories to the given time. If the timestring is - "set_to_mtime", then the atime and ctime of each file and directory - get set to the value found in their mtime. - These actions stay delayed until actual ISO production begins. Up - to then they can be revoked by "all_file_dates" with empty - timestring or timestring "default". - The timestamps of the El Torito boot catalog file get refreshed - when the ISO is produced. They can be influenced by "uuid". - "uuid" sets a timestring that overrides "c" and "m" times literally - and sets the time of the El Torito boot catalog. It must consist - of 16 decimal digits which form YYYYMMDDhhmmsscc, with YYYY between - 1970 and 2999. Time zone is GMT. It is supposed to match this GRUB - line: - search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc - E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds). - Timestrings for the other types may be given as with command - -alter_date. Some of them are prone to timezone computations. The - timestrings "default" or "overridden" cause default settings: "c" - and "m" will show the current time of image creation. "x" and "f" - will be marked as insignificant. "uuid" will be deactivated. - At -commit time, some timestamps get set to the maximum value of - effectively written volume creation and modification time: El - Torito boot catalog, HFS+ superblock, ECMA-119 file modification - time if -compliance "no_rec_mtime". The isohybrid MBR id is - computed from "uuid" if given, else from the effective volume - modification date. --copyright_file text - Set the copyright file name to be written with the next -commit. - This should be the ISO 9660 path of a file in the image which - contains a copyright statement. Permissible are up to 37 - characters. This setting gets overridden by image loading. --abstract_file text - Set the abstract file name to be written with the next -commit. - This should be the ISO 9660 path of a file in the image which - contains an abstract statement about the image content. - Permissible are up to 37 characters. This setting gets overridden - by image loading. --biblio_file text - Set the biblio file name to be written with the next -commit. This - should be the ISO 9660 path of a file in the image which contains - bibliographic records. Permissible are up to 37 characters. This - setting gets overridden by image loading. --preparer_id text - Set the preparer ID string to be written with the next -commit. - This may identify the person or other entity which controls the - preparation of the data which shall be recorded. Normally this - should be the ID of 'xorriso' and not of the person or program - which operates 'xorriso'. Please avoid to change it. Permissible - are up to 128 characters. - The special text "@xorriso@" gets converted to the ID string of - 'xorriso' which is default at program startup. - Unlike other ID strings, this setting is not influenced by image - loading. --application_use character|0xXY|disk_path - Specify the content of the Application Use field which can take at - most 512 bytes. - If the parameter of this command is empty, then the field is filled - with 512 0-bytes. If it is a single character, then it gets - repeated 512 times. If it begins by "0x" followed by two hex - digits [0-9a-fA-F], then the digits are read as byte value which - gets repeated 512 times. - Any other parameter text is used as disk_path to open a data file - and to read up to 512 bytes from it. If the file is smaller than - 512 bytes, then the remaining bytes in the field get set to binary - 0. - This setting is not influenced by image loading. --out_charset character_set_name - Set the character set to which file names get converted when - writing an image. See paragraph "Character sets" for more - explanations. When loading the written image after -commit the - setting of -out_charset will be copied to -in_charset. --uid uid - User id to be used for all files when the new ISO tree gets written - to media. --gid gid - Group id to be used for all files when the new ISO tree gets - written to media. --zisofs option[:options] - Set global parameters for zisofs compression. This data format is - recognized and transparently uncompressed by some Linux kernels. - It is to be applied via command -set_filter with built-in filter - "--zisofs". Parameters are: - "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow - "block_size="32k|64k|128k size of compression blocks - "by_magic=on" enables an expensive test at image generation time - which checks files from disk whether they already are zisofs - compressed, e.g. by program mkzftree. - "default" same as "level=6:block_size=32k:by_magic=off" --speed code|number[k|m|c|d|b] - Set the burn speed. Default is "max" (or "0") = maximum speed as - announced by the drive. Further special speed codes are: - "min" (or "-1") selects minimum speed as announced by the drive. - "none" avoids to send a speed setting command to the drive before - burning begins. - Speed can be given in media dependent numbers or as a desired - throughput per second in MMC compliant kB (= 1000) or MB (= 1000 - kB). Media x-speed factor can be set explicitly by "c" for CD, "d" - for DVD, "b" for BD, "x" is optional. - Example speeds: - 706k = 706kB/s = 4c = 4xCD - 5540k = 5540kB/s = 4d = 4xDVD - If there is no hint about the speed unit attached, then the medium - in the -outdev will decide. Default unit is CD = 176.4k. - MMC drives usually activate their own idea of speed and take the - speed value given by the burn program only as upper limit for their - own decision. --stream_recording "on"|"off"|"full"|"data"|number - Setting "on" tries to circumvent the management of defects on - DVD-RAM, BD-RE, or BD-R. Defect management keeps partly damaged - media usable. But it reduces write speed to half nominal speed - even if the medium is in perfect shape. For the case of flawless - media, one may use -stream_recording "on" to get full speed. - "full" tries full speed with all write operations, whereas "on" - does this only above byte address 32s. One may give a number of at - least 16s in order to set an own address limit. - "data" causes full speed to start when superblock and directory - entries are written and writing of file content blocks begins. --dvd_obs "default"|"32k"|"64k" - GNU/Linux specific: Set the number of bytes to be transmitted with - each write operation to DVD or BD media. A number of 64 KB may - improve throughput with bus systems which show latency problems. - The default depends on media type, on command -stream_recording , - and on compile time options. --modesty_on_drive parameter[:parameters] - Control whether the drive buffer shall be kept from getting - completely filled. Parameter "on" (or "1") keeps the program from - trying to write to the burner drive while its buffer is in danger - to be filled over a given limit. If this limit is exceeded then - the program will wait until the filling reaches a given low - percentage value. - This can ease the load on operating system and drive controller and - thus help with achieving better input bandwidth if disk and burner - are not on independent controllers (like hda and hdb). It may also - help with throughput problems of simultaneous burns on different - burners with Linux kernels like 3.16, if one has reason not to fix - the problem by -scsi_dev_family "sg". On the other hand it - increases the risk of buffer underflow and thus reduced write - speed. - Some burners are not suitable because they report buffer fill with - granularity too coarse in size or time, or expect their buffer to - be filled to the top before they go to full speed. - Parameters "off" or "0" disable this feature. - The threshold for beginning to wait is given by parameter - "max_percent=". Parameter "min_percent=" defines the threshold for - resuming transmission. Percentages are permissible in the range of - 25 to 100. Numbers in this range without a prepended name are - interpreted as "on:min_percent=". - E.g.: -modesty_on_drive 75 - The optimal values depend on the buffer behavior of the drive. - Parameter "timeout_sec=" defines after which time of unsuccessful - waiting the modesty shall be disabled because it does not work. - Parameter "min_usec=" defines the initial sleeping period in - microseconds. If the drive buffer appears to be too full for - sending more data, the program will wait the given time and inquire - the buffer fill state again. If repeated inquiry shows not enough - free space, the sleep time will slowly be increased to what - parameter "max_usec=" defines. - Parameters, which are not mentioned with a -modesty_on_drive - command, stay unchanged. Default is: - -modesty_on_drive off:min_percent=90:max_percent=95: - timeout_sec=120:min_usec=5000:max_usec=25000 --use_immed_bit "on"|"off"|"default" - Control whether several long lasting SCSI commands shall be - executed with the Immed bit, which makes the commands end early - while the drive operation is still going on. xorriso then inquires - progress indication until the drive reports to be ready again. If - this feature is turned off, then blanking and formatting will show - no progress indication. - It may depend on the operating system whether -use_immed_bit is set - to "off" by default. Command -status will tell by appending "/on" - or "/off" if a drive has already been acquired and -use_immed_bit - is currently set to "default". Command -use_immed_bit tolerates - and ignores such appended text. --stdio_sync "on"|"off"|"end"|number - Set the number of bytes after which to force output to stdio: - pseudo drives. This forcing keeps the memory from being clogged - with lots of pending data for slow devices. Default "on" is the - same as "16m". Forced output can be disabled by "off", or be - delayed by "end" until all data are produced. If a number is - chosen, then it must be at least 64k. --dummy "on"|"off" - If "on" then simulate burning or refuse with FAILURE event if no - simulation is possible, do neither blank nor format. --fs number["k"|"m"] - Set the size of the fifo buffer which smoothens the data stream - from ISO image generation to media burning. Default is 4 MiB, - minimum 64 kiB, maximum 1 GiB. The number may be followed by letter - "k" or "m" which means unit is kiB (= 1024) or MiB (= 1024 kiB). --close "on"|"off"|"as_needed" - If -close is set to "on" then mark the written medium as not - appendable any more. This will have no effect on overwritable - media types. Setting "on" is the contrary of cdrecord option - -multi, and is one aspect of growisofs option -dvd-compat. - If set to "off" then keep the medium writable for an appended - session. - If set to "as_needed" then use "on" only if "off" is predicted to - fail with the given medium and its state. - Not all drives correctly recognize fast-blanked DVD-RW which need - "on". If there is well founded suspicion that a burn run failed - due to -close "off", then -close "as_needed" causes a re-try with - "on". - Note that emulation command -as "cdrecord" temporarily overrides - the current setting of -close by its own default -close "on" if its - option -multi is missing. --write_type "auto"|"tao"|"sao/dao" - Set the write type for the next burn run. "auto" will select SAO - with blank CD media, DAO with blank DVD-R[W] if -close is "on", and - elsewise CD TAO or the equivalent write type of the particular - DVD/BD media. Choosing TAO or SAO/DAO explicitly might cause the - burn run to fail if the desired write type is not possible with the - given media state. --padding number["k"|"m"]|"included"|"appended" - Append the given number of extra bytes to the image stream. This - is a traditional remedy for a traditional bug in block device read - drivers. Needed only for CD recordings in TAO mode. Since one can - hardly predict on what media an image might end up, 'xorriso' adds - the traditional 300k of padding by default to all images. - For images which will never get to a CD it is safe to use -padding - 0 . - Normally padding is not written as part of the ISO image but - appended after the image end. This is -padding mode "appended". - Emulation command -as "mkisofs" and command -jigdo cause padding to - be written as part of the image. The same effect is achieved by - -padding mode "included". - - -File: xorriso.info, Node: Bootable, Next: Jigdo, Prev: SetWrite, Up: Commands - -9.11 Bootable ISO images -======================== - -Contrary to published specifications many BIOSes will load an El Torito -record from the first session on media and not from the last one, which -gets mounted by default. This makes no problems with overwritable -media, because they appear to inadverted readers as one single session. -But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that -the whole bootable system has to reside already in the first session and -that the last session still has to bear all files which the booted -system expects after mounting the ISO image. -If a boot image from ISOLINUX or GRUB is known to be present on media -then it is advised to patch it when a follow-up session gets written. -But one should not rely on the capability to influence the bootability -of the existing sessions, unless one can assume overwritable media. -Normally the boot images are data files inside the ISO filesystem. By -special path "-interval:appended_partition_NNN:all::" it is possible to -refer to an appended partition. The number NNN gives the partition -number as used with the corresponding command -append_partition. E.g.: --append_partition 2 0xef /tmp/efi.img --boot_image any efi_path=-interval:appended_partition_2:all:: -There are booting mechanisms which do not use an El Torito record but -rather start at the first bytes of the image: PC-BIOS MBR or EFI GPT for -hard-disk-like devices, APM partition entries for Macs which expect HFS+ -boot images, MIPS Volume Header for old SGI computers, DEC Boot Block -for old MIPS DECstation, SUN Disk Label for SPARC machines, HP-PA boot -sector for HP PA-RISC machines, DEC Alpha SRM boot sector for old DEC -Alpha machines. - - Several of the following commands expect disk paths as input but also -accept description strings for the libisofs interval reader, which is -able to cut out data from disk files or -indev and to zeroize parts of -the content: command -append_partition, boot specs system_area=, -grub2_mbr=, prep_boot_part=, efi_boot_part=. -The description string consists of the following components, separated -by colon ':' -"--interval:"Flags":"Interval":"Zeroizers":"Source -The component "--interval" states that this is not a plain disk path but -rather an interval reader description string. -The component Flags modifies the further interpretation: -"local_fs" demands to read from a file depicted by the path in Source. -"imported_iso" demands to read from the -indev. This works only if --outdev is not the same as -indev. The Source component is ignored. -"appended_partition_NNN" with a decimal number NNN works only for --boot_image bootspecs which announce El Torito boot image paths: -bin_path=, efi_path=. The number gives the partition number as used -with the corresponding command -append_partition. -The component Interval consists of two byte address numbers separated by -a "-" character. E.g. "0-429" means to read bytes 0 to 429. -The component Zeroizers consists of zero or more comma separated -strings. They define which part of the read data to zeroize. Byte -number 0 means the byte read from the Interval start address. Each -string may be one of: -"zero_mbrpt" demands to zeroize the MBR partition table if bytes 510 and -511 bear the MBR signature 0x55 0xaa. -"zero_gpt" demands to check for a GPT header in bytes 512 to 1023, to -zeroize it and its partition table blocks. -"zero_apm" demands to check for an APM block 0 and to zeroize its -partition table blocks. -Start_byte"-"End_byte demands to zeroize the read-in bytes beginning -with number Start_byte and ending after End_byte. -The component Source is the file path with flag "local_fs", and ignored -with flag "imported_iso". -Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning -multiplication by {1024, 1024k, 1024m, 1024g, 2048, 512}. A scaled -value end number depicts the last byte of the scaled range. -E.g. "0d-0d" is "0-511". -Examples: -"local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso" -"imported_iso:45056d-47103d::" - --boot_image "any"|"isolinux"|"grub" - - "discard"|"keep"|"patch"|"replay"|"show_status"| bootspec|"next" - - Define the equipment of the emerging filesystem with boot entry - points. - With systems which boot via BIOS or EFI this is a set of El Torito - boot images, possibly MBR boot code, and possibly partition tables - of type MBR, GPT, or APM. Such file sets get produced by boot - loader systems like ISOLINUX or GRUB. - - Each -boot_image command has two parameters: type and setting. - More than one -boot_image command may be used to define the - handling of one or more boot images. Sequence matters. - Types *isolinux* and *grub* care for known peculiarities. Type - *any* makes no assumptions about the origin of the boot images. - - When loading an ISO filesystem, system area and El Torito boot - images get loaded, too. The default behavior is not to write - loaded El Torito boot images and to write the loaded system area - content without alterations. - *discard* gives up the El Torito boot catalog and its boot images. - regardless whether loaded from an ISO filesystem or defined by - commands. Any BIOS or EFI related boot options get revoked. - Nevertheless, loaded system area data stay valid. If desired, they - have to be erased by - -boot_image any system_area=/dev/zero - *keep* keeps or copies El Torito boot images unaltered and writes a - new catalog. - *patch* applies patching to existing El Torito boot images if they - seem to bear a boot info table. - A boot info table needs to be patched when the boot image gets - newly introduced into the ISO image or if an existing image gets - relocated. This is automatically done if type "isolinux" or "grub" - is given, but not with "any". - If patching is enabled, then boot images from previous sessions - will be checked whether they seem to bear a boot info table. If - not, then they stay unpatched. This check is not infallible. So - if you do know that the images need no patching, use "any" "keep". - "grub" "patch" will not patch EFI images (platform_id=0xef). - *replay* is a more modern version of "patch", which not only cares - for existing El Torito boot equipment but also for the recognizable - boot provisions in the System Area. It discards any existing - -boot_image setting and executes the commands proposed by command - -report_el_torito "cmd". - This action will only succeed if the file objects mentioned in the - output of command -report_el_torito "cmd" are still available. Do - not remove or rename boot image files after -indev. - Drop unknown El Torito: -boot_image "any" "discard" - Maintain recognizable stuff: -boot_image "any" "replay" - El Torito only for GRUB: -boot_image "grub" "patch" - El Torito only for ISOLINUX: -boot_image "isolinux" "patch" - *show_status* will print what is known about the loaded boot images - and their designated fate. - - A *bootspec* is a word of the form name=value. It is used to - describe the parameters of a boot feature. The names "dir", - "bin_path", "efi_path" lead to El Torito bootable images. Name - "system_area" activates a given file as MBR or other disk header. - On all media types this is possible within the first session. In - further sessions an existing boot image can get replaced by a new - one, but depending on the media type this may have few effect at - boot time. See above. - El Torito boot images have to be added to the ISO image by normal - means (image loading, -map, -add, ...). In case of ISOLINUX the - files should reside either in ISO image directory /isolinux or in - /boot/isolinux . In that case it suffices to use as bootspec the - text "*dir=/isolinux*" or "dir=/boot/isolinux". E.g.: - -boot_image isolinux dir=/boot/isolinux - which bundles these individual settings: - -boot_image isolinux bin_path=/boot/isolinux/isolinux.bin - -boot_image isolinux cat_path=/boot/isolinux/boot.cat - -boot_image isolinux load_size=2048 - -boot_image any boot_info_table=on - An El Torito boot catalog file gets inserted into the ISO image - with address *cat_path=* with the first -boot_image "any" "next" or - at -commit time. It is subject to normal -overwrite and -reassure - processing if there is already a file with the same name. The - catalog lists the boot images and is read by the boot facility to - choose one of the boot images. But it is not necessary that it - appears in the directory tree at all. One may hide it in all trees - by *cat_hidden=on*. Other possible values are "iso_rr", "joliet", - "hfsplus", and the default "off". The timestamps of the boot - catalog file are refreshed at commit time. Command -volume_date - "uuid" can be used to set their value. - *bin_path=* depicts an El Torito boot image file, a binary program - which is to be started by the hardware boot facility (e.g. the - BIOS) at boot time. - *efi_path=* depicts an El Torito boot image file that is ready for - EFI booting. This is normally a FAT filesystem image not larger - than 65535 blocks of 512 bytes (= 32 MiB - 512). Its load_size is - determined automatically, no boot info table gets written, no boot - medium gets emulated, platform_id is 0xef. - *emul_type=* can be one of "no_emulation", "hard_disk", "diskette". - It controls the boot medium emulation code of a boot image. The - default "no_emulation" is suitable for ISOLINUX, GRUB, FreeBSD - cdboot. - *load_size=* is a value which depends on the boot image. Default - is 2048 which matches the expectations of most boot images. The - special value "full" means the full size of the boot image file - rounded up to a multiple of 2048 bytes. Maximum is 33,552,384 - bytes. - *boot_info_table=on* causes address patching to bytes 8 to 63 of - the boot image which is given by "any" "bin_path=". - "boot_info_table=off" disables this patching. - *grub2_boot_info=on* causes address patching to byte 2548 of the - boot image which is given by "any" "bin_path=". The address is - written as 64 bit little-endian number. It is the 2KB block - address of the boot image content, multiplied by 4, and then - incremented by 5. "grub2_boot_info=off" disables this patching. - *platform_id=* defines by a hexadecimal or decimal number the - Platform ID of the boot image. "0x00" is 80x86 PC-BIOS, "0x01" is - PowerPC, "0x02" is Mac, "0xef" is EFI (decimal "239"). - *id_string=*text|56_hexdigits defines the ID string of the boot - catalog section where the boot image will be listed. If the value - consists of 56 characters [0-9A-Fa-f] then it is converted into 28 - bytes, else the first 28 characters become the ID string. The ID - string of the first boot image becomes the overall catalog ID. It - is limited to 24 characters. Other id_strings become section IDs. - *sel_crit=*hexdigits defines the Selection Criteria of the boot - image. Up to 20 bytes get read from the given characters - [0-9A-Fa-f]. They get attributed to the boot image entry in the - catalog. - *next* ends the definition of a boot image and starts a new one. - Any following -bootimage bootspecs will affect the new image. The - first "next" discards loaded boot images and their catalog. - *system_area=*disk_path copies at most 32768 bytes from the given - disk file to the very start of the ISO image. This System Area is - reserved for system dependent boot software, e.g. an MBR which can - be used to boot from USB stick or hard disk. - Other than an El Torito boot image, the file disk_path needs not to - be added to the ISO image. - *-boot_image isolinux system_area=* implies "partition_table=on". - In this case, the disk path should lead to one of the SYSLINUX - files isohdp[fp]x*.bin or to a file which was derived from one of - those files. E.g. to the first 512 bytes from an ISOLINUX - isohybrid ISO image. - In this case, El Torito boot images (dir=, bin_path=, efi_path=) - may be augmented by *isolinux partition_entry=gpt_basdat* or - *isolinux partition_entry=gpt_hfsplus*, and by *isolinux - partition_entry=apm_hfsplus*. The boot image will then be - mentioned in an invalid GPT as Basic Data or GPT HFS+ partition, - and in a valid APM as HFS+ partition. The first three GPT - partitions will also be marked by MBR partitions. The MBR - partition of type 0xEF is what actually is used by EFI firmware for - booting from USB stick. - In multi-session situations the existing System Area is preserved - by default. In in this case, the special disk_path "." prevents - reading of a disk file but nevertheless causes adjustments in the - loaded system area data. Such adjustments may get ordered by - -boot_image commands. - *-boot_image any gpt_disk_guid=*value controls whether an emerging - GPT shall get a randomly generated disk GUID or whether the GUID is - supplied by the user. Value "random" is default. Value - "volume_date_uuid" produces a low quality GUID from the value set - by -volume_date "uuid". - A string of 32 hex digits, or a RFC 4122 compliant GUID string may - be used to set the disk GUID directly. UEFI prescribes the first - three components of a RFC 4122 GUID string to be byte-swapped in - the binary representation: - E.g. gpt_disk_guid=2303cd2a-73c7-424a-a298-25632da7f446 equals - gpt_disk_guid=2acd0323c7734a42a29825632da7f446 - The partition GUIDs get generated by minimally varying the disk - GUID. - *-boot_image any part_like_isohybrid=on* enables -boot_image - isolinux partition_entry= even if no -boot_image isolinux - system_area= is given. No MBR partition of type 0xee emerges, even - if GPT gets produced. Gaps between GPT and APM partitions will not - be filled by more partitions. Appended partitions get mentioned in - APM if other APM partitions emerge. - *-boot_image any iso_mbr_part_type=*number sets the partition type - of the MBR partition which represents the ISO or at least protects - it. - Number may be 0x00 to 0xff. The text "default" re-enables the - default types of the various occasions to create an ISO MBR - partition. This is without effect if no such partition emerges by - other settings or if the partition type is prescribed mandatorily - like 0xee for GPT protective MBR or 0x96 for CHRP. - If instead a type_guid is given by a 32-digit hex string like - a2a0d0ebe5b9334487c068b6b72699c7 or by a structured text like - EBD0A0A2-B9E5-4433-87C0-68B6B72699C7, then it will be used as - partition type if the ISO filesystem appears as partition in GPT. - In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped to - 0xef. Any other GUID will be mapped to 0x83. - *grub2_mbr=*disk_path works like "any" system_area= with additional - patching for modern GRUB MBRs. The content start address of the - first boot image is converted to a count of 512 byte blocks, and an - offset of 4 is added. The result is written as 64 bit - little-endian number to byte address 0x1b0. - This feature can be revoked either by grub2_mbr= with empty disk - path, or by submitting a disk_path via system_area=. - *partition_table=on* causes a simple partition table to be written - into bytes 446 to 511 of the System Area. - With type "isolinux" it shows a partition that begins at byte 0 and - it causes the LBA of the first boot image to be written into the - MBR. For the first session this works only if also "system_area=" - and "bin_path=" or "dir=" is given. - With types "any" and "grub" it shows a single partition which - starts at byte 512 and ends where the ISO image ends. This works - with or without system_area= or boot image. - Bootspecs chrp_boot_part=, prep_boot_part=, and efi_boot_part= - overwrite this entry in the MBR partition table. - If types "isolinux" or "grub" are set to "patch", then - "partition_table=on" is activated without new boot image. In this - case the existing System Area gets checked whether it bears - addresses and sizes as if it had been processed by - "partition_table=on". If so, then those parameters get updated - when the new System Area is written. - Special "system_area=/dev/zero" causes 32k of NUL-bytes. Use this - to discard an MBR which was loaded with the ISO image. - *appended_part_as=gpt* marks partitions from -append_partition in - GPT rather than in MBR. In this case the MBR shows a single - partition of type 0xee which covers the whole output data. - *appended_part_as=mbr* is the default. Appended partitions get - marked in GPT only if GPT is produced because of other settings. - If given explicitly, this clears setting "gpt" and "apm". - Nevertheless "apm" may be added to "mbr". - *appended_part_as=apm* marks partitions from -append_partition in - APM additionally to "mbr" or "gpt". - By default, appended partitions get marked in APM only if APM is - produced because of other options together with - part_like_isohybrid="on". - *chrp_boot_part=on* causes a single partition in MBR which covers - the whole ISO image and has type 0x96. This is not compatible with - any other feature that produces MBR partition entries. It makes - GPT unrecognizable. - *prep_boot_part=*disk_path inserts the content of a data file into - the image and marks it by an MBR partition of type 0x41. The parts - of the ISO image before and after this partition will be covered by - further MBR partitions. The data file is supposed to contain ELF - executable code. - *efi_boot_part=*disk_path inserts the content of a data file into - the image and marks it by a GPT partition. If not - chrp_boot_part=on, then the first partition in MBR will have type - 0xee to announce the presence of GPT. The data file is supposed to - contain a FAT filesystem. - Instead of a disk_path, the word --efi-boot-image may be given. It - exposes in GPT the content of the first El Torito EFI boot image as - EFI system partition. EFI boot images are introduced by bootspec - efi_path=. The affected EFI boot image cannot show up in HFS+ - because it is stored outside the HFS+ partition. - *partition_offset=*2kb_block_adr causes a partition table with a - single partition that begins at the given block address. This is - counted in 2048 byte blocks, not in 512 byte blocks. If the block - address is non-zero then it must be at least 16. A non-zero - partition offset causes two superblocks to be generated and two - sets of directory trees. The image is then mountable from its - absolute start as well as from the partition start. - The offset value of an ISO image gets preserved when a new session - is added. So the value defined here is only in effect if a new ISO - image gets written. - *partition_hd_cyl=*number gives the number of heads per cylinder - for the partition table. 0 chooses a default value. Maximum is - 255. - *partition_sec_hd=*number gives the number of sectors per head for - the partition table. 0 chooses a default value. Maximum is 63. - The product partition_sec_hd * partition_hd_cyl * 512 is the - cylinder size. It should be divisible by 2048 in order to make - exact alignment possible. With appended partitions and - "appended_part_as=gpt" there is no limit for the number of - cylinders. Else there may be at most 1024 of them. If the - cylinder size is too small to stay below the limit, then - appropriate values of partition_hd_cyl are chosen with - partition_sec_hd 32 or 63. If the image is larger than - 8,422,686,720 bytes, then the cylinder size constraints cannot be - fulfilled for MBR. - *partition_cyl_align=*mode controls image size alignment to an - integer number of cylinders. It is prescribed by isohybrid specs - and it seems to please program fdisk. Cylinder size must be - divisible by 2048. Images larger than 8,323,596,288 bytes cannot - be aligned in MBR partition table. - Mode "auto" is default. Alignment by padding happens only with - "isolinux" "partition_table=on". - Mode "on" causes alignment by padding with "partition_table=on" for - any type. Mode "all" is like "on" but also pads up partitions from - -append_partition to an aligned size. - Mode "off" disables alignment for any type. - *mbr_force_bootable=*mode enforces an MBR partition with - "bootable/active" flag if options like partition_table= or - grub2_mbr= indicate production of a bootable MBR. These options - normally cause the flag to be set if there is an MBR partition of - type other than 0xee or 0xef. If no such partition exists, then no - bootflag is set, unless mbr_force_bootable="on" forces creation of - a dummy partition of type 0x00 which covers only the first block of - the ISO image. - If no bootable MBR is indicated and a partition gets created by - -append_partition, then mbr_force_bootable="on" causes a bootflag - like it would do with a bootable MBR. - *mips_path=*iso_rr_path declares a data file in the image to be a - MIPS Big Endian boot file and causes production of a MIPS Big - Endian Volume Header. This is mutually exclusive with production - of other boot blocks like MBR. It will overwrite the first 512 - bytes of any data provided by system_area=. Up to 15 boot files - can be declared by mips_path=. - *mipsel_path=*iso_rr_path declares a data file in the image to be - the MIPS Little Endian boot file. This is mutually exclusive with - other boot blocks. It will overwrite the first 512 bytes of any - data provided by system_area=. Only a single boot file can be - declared by mipsel_path=. - *sparc_label=*text causes the production of a SUN Disk Label with - the given text as ASCII label. Partitions 2 to 8 may be occupied - by appended images. Partition 1 will always be the ISO image. See - command -append_partition. The first 512 bytes of any data - provided by system_area= will be overwritten. - *grub2_sparc_core=*iso_rr_path causes the content address and size - of the given file to be written after the SUN Disk Label. Both - numbers are counted in bytes. The address is written as 64 bit - big-endian number to byte 0x228. The size is written as 32 bit - big-endian number to byte 0x230. - *hppa_cmdline=*text sets the PALO command line for HP-PA. Up to - 1023 characters are permitted by default. With hppa_hdrversion=4 - the limit is 127. - Note that the first five hppa_ bootspecs are mandatory, if any of - the hppa_ bootspecs is used. Only hppa_hdrversion= is allowed to - be missing. - *hppa_bootloader=*iso_rr_path designates the given path as HP-PA - bootloader file. - *hppa_kernel_32=*iso_rr_path designates the given path as HP-PA 32 - bit kernel file. - *hppa_kernel_64=*iso_rr_path designates the given path as HP-PA 64 - bit kernel file. - *hppa_ramdisk=*iso_rr_path designates the given path as HP-PA RAM - disk file. - *hppa_hdrversion=*number chooses between PALO header version 5 - (default) and version 4. For the appropriate value see in PALO - source code: PALOHDRVERSION. - *alpha_boot=*iso_rr_path declares a data file in the image to be - the DEC Alpha SRM Secondary Bootstrap Loader and causes production - of a boot sector which points to it. This is mutually exclusive - with production of other boot blocks like MBR. - *mips_discard*, *sparc_discard*, *hppa_discard*, *alpha_discard* - revoke any boot file declarations made for mips/mipsel, sparc, - hppa, or alpha, respectively. This removes the ban on production - of other boot blocks. - *hfsplus_serial=*hexstring sets a string of 16 digits "0" to "9" - and letters "a" to "f", which will be used as unique serial number - of an emerging HFS+ filesystem. - *hfsplus_block_size=*number sets the allocation block size to be - used when producing HFS+ filesystems. Permissible are 512, 2048, - or 0. The latter lets the program decide. - *apm_block_size=*number sets the block size to be used when - describing partitions by an Apple Partition Map. Permissible are - 512, 2048, or 0. The latter lets the program decide. - Note that size 512 is not compatible with production of GPT, and - that size 2048 will not be mountable -t hfsplus at least by older - Linux kernels. - - --append_partition partition_number type_code disk_path - Cause a prepared filesystem image to be appended to the ISO image - and to be described by a partition table entry in a boot block at - the start of the emerging ISO image. The partition entry will bear - the size of the submitted file rounded up to the next multiple of - 2048 bytes or to the next multiple of the cylinder size. - Beware of subsequent multi-session runs. The appended partition - will get overwritten. - Partitions may be appended with boot block type MBR and with SUN - Disk Label. - With MBR: - partition_number may be 1 to 4. Number 1 will put the whole ISO - image into the unclaimed space before partition 1. So together - with most 'xorriso' MBR features, number 2 would be the most - natural choice. - The type_code may be "FAT12", "FAT16", "Linux", or a hexadecimal - number between 0x00 and 0xff. Not all those numbers will yield - usable results. For a list of MBR partition type codes search the - Internet for "Partition Types" or run fdisk command "L". - type_code may also be a type GUID as plain hex string like - a2a0d0ebe5b9334487c068b6b72699c7 or as structured text like - EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the - partition is mentioned in GPT. In MBR, - C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped to 0xef. Any - other GUID will be mapped to 0x83. - If some other command causes the production of GPT, then the - appended partitions will be mentioned there too. - The disk_path must provide the necessary data bytes at commit time. - An empty disk_path disables this feature for the given partition - number. - With SUN Disk Label (selected by -boot_image any sparc_label=): - partition_number may be 2 to 8. Number 1 will always be the ISO - image. Partition start addresses are aligned to 320 KiB. The - type_code does not matter. Submit 0x0. - Partition image name "." causes the partition to become a copy of - the next lower valid one. - - -File: xorriso.info, Node: Jigdo, Next: Charset, Prev: Bootable, Up: Commands - -9.12 Jigdo Template Extraction -============================== - -From man genisoimage: "Jigdo is a tool to help in the distribution of -large files like CD and DVD images; see http://atterer.net/jigdo/ for -more details. Debian CDs and DVD ISO images are published on the web in -jigdo format to allow end users to download them more efficiently." -'xorriso' can produce a .jigdo and a .template file together with a -single-session ISO image. The .jigdo file contains checksums and -symbolic file addresses. The .template file contains the compressed ISO -image with reference tags instead of the content bytes of the listed -files. -Input for this process are the normal arguments for a 'xorriso' session -on a blank -outdev, and a checksum file which lists those data files -which may be listed in the .jigdo file and externally referenced in the -.template file. Each designated file is represented in the checksum -file by a single text line: -Checksum as hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 -blanks, symbolic file address -The kind of checksum is chosen by -jigdo "checksum_algorithm" with -values "md5" (32 hex digits) or "sha256" (64 hex digits). It will also -be used for the file address lines in the .jigdo file. The default is -"md5". -The file address in a checksum file line has to bear the same basename -as the disk_path of the file which it shall match. The directory path -of the file address is decisive for To=From mapping, not for file -recognition. After To=From mapping, the file address gets written into -the .jigdo file. Jigdo restore tools will convert these addresses into -really reachable data source addresses from which they can read. -If the list of jigdo parameters is not empty, then 'xorriso' will refuse -to write to non-blank targets, it will disable multi-session emulation, -and padding will be counted as part of the ISO image. - --jigdo parameter_name value - Clear Jigdo Template Extraction parameter list or add a parameter - to that list. The alias names are the corresponding genisoimage - options. They are accepted as parameter names as well. Especially - they are recognized by the -as mkisofs emulation command. - Parameter *clear* with any value empties the whole list. No .jigdo - and .template file will be produced. - *checksum_algorithm* chooses the checksum algorithm which shall be - used for the data file entries in the .jigdo file and is expected - in the checksum file. Permissible are "md5" or "sha256". Default - is "md5". - Alias: -jigdo-checksum-algorithm - *template_path* sets the disk_path for the .template file with the - holed and compressed ISO image copy. - Alias: -jigdo-template - *jigdo_path* sets the disk_path for the .jigdo file with the - checksums and download addresses for filling the holes in - .template. - Alias: -jigdo-jigdo - *checksum_path* sets the disk_path where to find the checksum file - with symbolic file addresses and checksums according to - *checksum_algorithm*. - Alias: md5_path - Alias: -checksum-list - Alias: -md5-list - *min_size* sets the minimum size for a data file to be listed in - the .jigdo file and being a hole in the .template file. - Alias: -jigdo-min-file-size - *exclude* adds a regular expression pattern which will get compared - with the absolute disk_path of any data file. A match causes the - file to stay in .template in any case. - Alias: -jigdo-exclude - *demand_checksum* adds a regular expression pattern which will get - compared with the absolute disk_path of any data file that was not - found in the checksum list file as of "checksum_path". A match - causes a MISHAP event. - Alias: demand_md5 - Alias: -jigdo-force-checksum - Alias: -jigdo-force-md5 - *mapping* adds a string pair of the form To=From to the parameter - list. If a data file gets listed in the .jigdo file, then it is - referred by the file address from its line in the checksum file. - This file address gets checked whether it begins with the From - string. If so, then this string will be replaced by the To string - and a ':' character, before it goes into the .jigdo file. The From - string should end by a '/' character. - Alias: -jigdo-map - *compression* chooses one of "bzip2" or "gzip" for the compression - of the template file. The jigdo file is put out uncompressed. - Alias: -jigdo-template-compress - *checksum_iso* chooses one or more of "md5", "sha1", "sha256", - "sha512" for the auxiliary "# Image Hex" checksums in the jigdo - file. The value may e.g. look like "md5,sha1,sha512". Value - "all" chooses all available algorithms. Note that MD5 stays always - enabled. - Alias: -checksum_algorithm_iso - *checksum_template* is like checksum_iso but for "# Template Hex". - Alias: -checksum_algorithm_template - - -File: xorriso.info, Node: Charset, Next: Exception, Prev: Jigdo, Up: Commands - -9.13 Character sets -=================== - -File names are strings of non-zero bytes with 8 bit each. Unfortunately -the same byte string may appear as different peculiar national -characters on differently nationalized terminals. The meanings of byte -codes are defined in *character sets* which have names. Shell command -iconv -l lists them. -The file names on hard disk are assumed to be encoded by the *local -character set* which is also used for the communication with the user. -Byte codes 32 to 126 of the local character set must match the US-ASCII -characters of the same code. ISO-8859 and UTF-8 fulfill this demand. -By default, 'xorriso' uses the character set as told by shell command -"locale" with argument "charmap". This may be influenced by environment -variables LC_ALL, LC_CTYPE, or LANG and should match the expectations of -the terminal. In some situations it may be necessary to set it by -command -local_charset. -Local character sets should not matter as long as only english -alphanumeric characters are used for file names or as long as all -writers and readers of the media use the same local character set. -Outside these constraints it may be necessary to let 'xorriso' convert -byte codes from and to other character sets. -The Rock Ridge file names in ISO filesystems are assumed to be encoded -by the *input character set*. The Rock Ridge file names which get -written with ISO filesystems will be encoded by the *output character -set*. -The sets can be defined independently by commands -in_charset and --out_charset. Normally one will have both identical, if ever. Other -than the local character set, these two character sets may deviate from -US-ASCII. -The output character sets for Joliet and HFS+ are not influenced by -these commands. Joliet uses output character set UCS-2 or UTF-16. HFS+ -uses UTF-16. -The default output charset is the local character set of the terminal -where 'xorriso' runs. So by default no conversion happens between local -filesystem names and emerging Rock Ridge names in the image. The -situation stays ambiguous and the reader has to riddle what character -set was used. -By command -auto_charset it is possible to attribute the output charset -name to the image. This makes the situation unambiguous. But if your -terminal character set does not match the character set of the local -file names, then this attribute can become plainly wrong and cause -problems at read time. To prevent this it is necessary to check whether -the terminal properly displays all intended filenames. Check especially -the exotic national characters. -To enforce recording of a particular character set name without any -conversion at image generation time, set -charset and -local_charset to -the desired name, and enable -backslash_codes to avoid evil character -display on your terminal. - --charset character_set_name - Set the character set from which to convert file names when loading - an image and to which to convert when writing an image. --local_charset character_set_name - Override the system assumption of the local character set name. If - this appears necessary, one should consider to set -backslash_codes - to "on" in order to avoid dangerous binary codes being sent to the - terminal. - - -File: xorriso.info, Node: Exception, Next: DialogCtl, Prev: Charset, Up: Commands - -9.14 Exception processing -========================= - -Since the tasks of 'xorriso' are manifold and prone to external -influence, there may arise the need for 'xorriso' to report and handle -problem events. -Those events get classified when they are detected by one of the -software modules and forwarded to reporting and evaluation modules which -decide about reactions. Event classes are sorted by severity: -"NEVER" The upper end of the severity spectrum. -"ABORT" The program is being aborted and on its way to end. -"FATAL" The main purpose of the run failed or an important resource -failed unexpectedly. -"FAILURE" An important part of the job could not be performed. -"MISHAP" A FAILURE which can be tolerated during ISO image generation. -"SORRY" A less important part of the job could not be performed. -"WARNING" A situation is suspicious of being not intended by the user. -"HINT" A proposal to the user how to achieve better results. -"NOTE" A harmless information about noteworthy circumstances. -"UPDATE" A pacifier message during long running operations. -"DEBUG" A message which would only interest the program developers. -"ALL" The lower end of the severity spectrum. - --abort_on severity - Set the severity threshold for events to abort the program. - Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY" - It may become necessary to abort the program anyway, despite the - setting by this command. Expect not many "ABORT" events to be - ignorable. - A special property of this command is that it works preemptive if - given as program start argument. I.e. the first -abort_on setting - among the start arguments is in effect already when the first - operations of 'xorriso' begin. Only "-abort_on" with dash "-" is - recognized that way. --return_with severity exit_value - Set the threshold and exit_value to be returned at program end if - no abort has happened. This is to allow 'xorriso' to go on after - problems but to get a failure indicating exit value from the - program, nevertheless. Useful is a value lower than the -abort_on - threshold, down to "WARNING". - exit_value may be either 0 (indicating success to the starter of - the program) or a number between 32 and 63. Some other exit_values - are used by 'xorriso' if it decides to abort the program run: - 1=abort due to external signal - 2=no program arguments given - 3=creation of 'xorriso' main object failed - 4=failure to start libburnia-project.org libraries - 5=program abort during argument processing - 6=program abort during dialog processing --report_about severity - Set the threshold for events to be reported. - Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", - "ALL" - Regardless what is set by -report_about, messages get always - reported if they reach the severity threshold of -abort_on . - Event messages are sent to the info channel "I" which is usually - stderr but may be influenced by command -pkt_output. Info messages - which belong to no event get attributed severity "NOTE". - A special property of this command is that the first -report_about - setting among the start arguments is in effect already when the - first operations of 'xorriso' begin. Only "-report_about" with - dash "-" is recognized that way. --signal_handling mode - Control the installation of a signal handler which shall react on - external signals (e.g. from program "kill" or from keys Ctrl+C) or - on signals caused by severe program errors. - Mode "on" is the default. It uses the signal handler of libburn - which produces ugly messages but puts much effort in releasing - optical drives before 'xorriso' ends. - Mode "off" as first -signal_handling among the start arguments - prevents all own signal precautions of 'xorriso'. Inherited signal - handler settings stay as they are. - It works like "sig_dfl" if given after other signal handling was - already established at program start. - Mode "sig_dfl" uses the system provided default handling of - signals, which is normally a sudden abort of the program. To - prevent stuck drives, the libburn handler is used during burning, - blanking, and formatting on MMC drives. - Mode "sig_ign" tries to ignore as many signal types as possible. - This imposes the risk that 'xorriso' refuses to end until - externally kill -9 if performed. kill -9 then imposes the risk - that the drive is left in unusable state and needs poweroff to be - reset. So during burning, blanking, and formatting wait for at - least their normal run time before killing externally. - A special property of this command is that the first - -signal_handling setting among the start arguments is in effect - already when the first operations of 'xorriso' begin. Only - "-signal_handling" with dash "-" is recognized that way. --error_behavior occasion behavior - Control the program behavior at problem event occasions. For now - this applies to occasions "image_loading" which is given while an - image tree is read from the input device, and to "file_extraction" - which is given with osirrox commands like -extract. - With "image_loading" there are three behaviors available: - "best_effort" goes on with reading after events with severity below - FAILURE if the threshold of command -abort_on allows this. - "failure" aborts image tree reading on first event of at least - SORRY. It issues an own FAILURE event. This is the default. - "fatal" acts like "failure" but issues the own event as FATAL. - With occasion "file_extraction" there are three behaviors: - "keep" maintains incompletely extracted files on disk. This is the - default. - "delete" removes files which encountered errors during content - extraction. - "best_effort" starts a revovery attempt by means of -extract_cut if - the file content stems from the loaded ISO image and is not - filtered. - - -File: xorriso.info, Node: DialogCtl, Next: Inquiry, Prev: Exception, Up: Commands - -9.15 Dialog mode control -======================== - --dialog "on"|"off"|"single_line" - Enable or disable to enter dialog mode after all program arguments - are processed. In dialog mode input lines get prompted via - readline or from stdin. - If no -abort_on severity was set when dialog starts, then "NEVER" - is set to avoid abort in most cases of wrong input or other - problems. Before dialog begins, the default is "FAILURE" which - e.g. aborts on unknown commands. - Mode "on" supports input of newline characters within quotation - marks and line continuation by trailing backslash outside quotation - marks. Mode "single_line" does not. --page length width - Describe terminal to the text pager. See also above, paragraph - Result pager. - If parameter length is nonzero then the user gets prompted after - that number of terminal lines. Zero length disables paging. - Parameter width is the number of characters per terminal line. It - is used to compute the number of terminal lines which get occupied - by an output line. A usual terminal width is 80. --use_readline "on"|"off" - If "on" then use readline for dialog. Else use plain stdin. - See also above, paragraph Dialog, Readline, Result pager. --reassure "on"|"tree"|"off" - If "on" then ask the user for "y" or "n": - before deleting or overwriting any file in the ISO image, - before overwriting any disk file during restore operations, - before rolling back pending image changes, - before committing image changes to media, - before changing the input drive, - before blanking or formatting media, - before ending the program. - With setting "tree" the reassuring prompt will appear for an - eventual directory only once and not for each file in its whole - subtree. - Setting "off" silently kills any kind of image file object and - performs above irrevocable actions. - To really produce user prompts, command -dialog needs to be set to - "on". Note that the prompt does not appear in situations where - file removal is forbidden by command -overwrite. -reassure only - imposes an additional curb for removing existing file objects. - Be aware that file objects get deleted from the ISO image - immediately after confirmation. They are gone even if the running - command gets aborted and its desired effect gets revoked. In case - of severe mess-up, consider to use -rollback to revoke the whole - session. - - -File: xorriso.info, Node: Inquiry, Next: Navigate, Prev: DialogCtl, Up: Commands - -9.16 Drive and media related inquiry actions -============================================ - --devices - Show list of available MMC drives with the addresses of their - libburn standard device files. - This is only possible when no ISO image changes are pending. After - this command was executed, there is no drive current and no image - loaded. - In order to be visible, a device has to offer rw-permissions with - its libburn standard device file. Thus it might be only the - *superuser* who is able to see all drives. - Drives which are occupied by other processes get not shown. --device_links - Like -devices, but presenting the drives with addresses of symbolic - links which point to the actual device files. - Modern GNU/Linux systems may shuffle drive addresses from boot to - boot. The udev daemon is supposed to create links which always - point to the same drive, regardless of its system address. The - command -device_links shows the addresses of such links if they - begin by "/dev/dvd" or "/dev/cd". Precedence is: "dvdrw", "cdrw", - "dvd", "cdrom", "cd". --toc - - Show media specific tables of content. This is the session history - of the medium, not the ISO image directory tree. - In case of overwritable media holding a valid ISO image, it may - happen that only a single session gets shown. But if the first - session on the overwritable media was written by 'xorriso' then a - complete session history can be emulated. - A drive which is incapable of writing may show any media as CD-ROM - or DVD-ROM with only one or two sessions on it. The last of these - sessions is supposed to be the most recent real session then. - Some read-only drives and media show no usable session history at - all. Command -rom_toc_scan might help. - If input device and output device are both acquired and not the - same, then both tables-of-content get shown. --toc_of "in"|"out"|"all"[":short"] - Like command -toc but explicitly choosing which drive's - table-of-content to show. "in" shows -indev or -dev, "out" shows - -outdev or -dev, "all" shows the same as -toc. - If ":short" is appended to the drive choosing word, then only a - short summary of drive state and medium content is printed. - As further difference to -toc, this command does not emit FAILURE - events if the desired drive is not acquired. --mount_cmd drive entity id path - Emit an appropriate command line for mounting the ISO session - indicated by drive, entity and id. The result will be different on - GNU/Linux and on FreeBSD or NetBSD. - drive can be "indev" or "outdev" to indicate already acquired - drives, or it can be the path of a not yet acquired drive. Prefix - "stdio:" for non-MMC drives is not mandatory. - For entity and id, see also command -load. They must be either - "sbsector" with the superblock sector address as id, or "track" - with a track number as id, or "session" with a session number, or - "volid" with a search pattern for the volume id, or "auto" with - which any text as id mounts the first track of the last session. - path will be used as mount point and must already exist as a - directory on disk. - The command gets printed to the result channel. See command -mount - for direct execution of this command. --mount_opts option[:option...] - Set options which influence -mount and -mount_cmd. Currently there - is only option "exclusive" which is default and its counterpart - "shared". The latter causes 'xorriso' not to give up the affected - drive with command -mount. On GNU/Linux it adds mount option - "loop" which may enable mounting of several sessions of the same - block device at the same time. One should not write to a mounted - optical medium, of course. Take care to umount all sessions before - ejecting. --session_string drive entity id format - Print to the result channel a text which gets composed according to - format and the parameters of the addressed session. - Formats "linux:"path or "freebsd:"path produce the output of - -mount_cmd for the given operating systems. - In other texts 'xorriso' will substitute the following parameter - names. An optional prefix "string:" will be removed. - "%device%" will be substituted by the mountable device path of the - drive address. - "%sbsector%" will be substituted by the session start sector. - "%track%", "%session%", "%volid%" will be substituted by track - number, session number, or volume id of the depicted session. --print_size - Print the foreseeable consumption of 2048 byte blocks by next - -commit. This can last a while as a -commit gets prepared and only - in last moment is revoked by this command. The result depends on - several settings and also on the kind of output device. If no - -jigdo options are set and not command -as "mkisofs" was used, then - -padding (300 kB by default) is not counted as part of the image - size. - If an El Torito boot image file is already depicted, then command - -print_size automatically executes -boot_image "any" "next". This - means that the properties of that boot image cannot be edited by - subsequent commands. --tell_media_space - Print available space on the output medium and the free space after - subtracting already foreseeable consumption by next -commit. - Note that the title of the prediction "After commit :" is - misleading. It is rather the space that may still be filled in - this session without making the next -commit fail from medium - overflow. - The free space after the next -commit might be smaller by several - MB. This depends on medium type, number of recorded sessions, and - drive habits. --pvd_info - Print various ID strings and timestamps which can be found in - loaded ISO images. Some of the IDs may be changed by commands like - -volid or -publisher. For these IDs -pvd_info reports what would - be written with the next -commit. The timestamps get not - automatically propagated from loaded image to newly written image. - The ones for new images may be set by command -volume_date. See - there for the meaning of the particular timestamps. --report_el_torito mode - - With mode *plain* print a report about the information found in the - El Torito boot catalog of the loaded ISO image. - With mode *help* print a text which explains the meaning of the - lines put out by "plain". - Mode *cmd* tries to print the *xorriso* commands which are - necessary to produce the found boot equipment: disk identifiers, El - Torito boot images, and System Area. Disk identifiers are strings - which the booting operating system might use to find the ISO - filesystem from where it comes. Currently known is the use of - volume id and modification date. - The intended use case is modification of the filesystem by having - -indev and -outdev pointing to different images or drives. The - result might be insufficient, if the found equipment cannot be - produced by xorriso. Various SORRY events may arise in this case, - but it is not guaranteed that xorriso recognizes all its - insufficiencies. - Mode *as_mkisofs* tries to print the *xorriso -as mkisofs* options, - which are necessary to produce the found equipment. The intended - use case is to use the mounted filesystem as input tree together - with the printed options. --report_system_area mode - With mode *plain* print a report about the information found in the - System Area of the loaded ISO image. The report consists of zero - to many lines with a header text, a colon, and information text. - With mode *help* print a text which explains the meaning of the - lines put out by "plain". You probably will have to look for more - documentation which explains the technical details of the mentioned - boot facilities. - Modes *cmd* and *as_mkisofs* work like with command - -report_el_torito. See above. - With mode *gpt_disk_guid* print the GPT disk GUID of the loaded ISO - in RFC 4122 text format to result channel. It is not considered an - error if no GPT is present. In this case nothing is printed to - result channel. - With mode *gpt_crc_of:*disk_path read up to 32 KiB from the disk - file with the path given after the colon. Compute the GPT - compliant CRC number and print it to the result channel. The - number is shown like "0x690fd979". The special disk_path "-" - causes reading from standard input. - With mode *make_guid* print a pseudo-random GUID in RFC 4122 text - format to result channel. - - -File: xorriso.info, Node: Navigate, Next: Verify, Prev: Inquiry, Up: Commands - -9.17 Navigation in ISO image and disk filesystem -================================================ - --cd iso_rr_path - Change the current working directory in the ISO image. This is - prepended to iso_rr_paths which do not begin with '/'. - It is possible to set the working directory to a path which does - not exist yet in the ISO image. The necessary parent directories - will be created when the first file object is inserted into that - virtual directory. Use -mkdir if you want to enforce the existence - of the directory already at first insertion. --cdx disk_path - Change the current working directory in the local filesystem. To - be prepended to disk_paths which do not begin with '/'. --pwd - - Tell the current working directory in the ISO image. --pwdx - - Tell the current working directory in the local filesystem. --ls iso_rr_pattern [***] - List files in the ISO image which match shell patterns (i.e. with - wildcards '*' '?' '[a-z]'). If a pattern does not begin with '/' - then it is compared with addresses relative to -cd. - Directories are listed by their content rather than as single file - item. - Pattern expansion may be disabled by command -iso_rr_pattern. --lsd iso_rr_pattern [***] - Like -ls but listing directories as themselves and not by their - content. This resembles shell command ls -d. --lsl iso_rr_pattern [***] - Like -ls but also list some of the file attributes. The output - format resembles shell command ls -ln. - File type 'e' indicates the El Torito boot catalog. - If the file has non-trivial ACL, then a '+' is appended to the - permission info. If the file is hidden, then 'I' for "iso_rr", 'J' - for "joliet", 'A' for "hfsplus", 'H' for multiple hiding gets - appended. Together with ACL it is 'i', 'j', 'a', 'h'. --lsdl iso_rr_pattern [***] - Like -lsd but also list some of the file attributes. The output - format resembles shell command ls -dln. --lsx disk_pattern [***] - List files in the local filesystem which match shell patterns. - Patterns which do not begin with '/' are used relative to -cdx. - Directories are listed by their content rather than as single file - item. - Pattern expansion may be disabled by command -disk_pattern. --lsdx disk_pattern [***] - Like -lsx but listing directories as themselves and not by their - content. This resembles shell command ls -d. --lslx disk_pattern [***] - Like -lsx but also listing some of the file attributes. Output - format resembles shell command ls -ln. --lsdlx disk_pattern [***] - Like -lsdx but also listing some of the file attributes. Output - format resembles shell command ls -dln. --getfacl iso_rr_pattern [***] - Print the access permissions of the given files in the ISO image - using the format of shell command getfacl. If a file has no ACL - then it gets fabricated from the -chmod settings. A file may have - a real ACL if it was introduced into the ISO image while command - -acl was set to "on". --getfacl_r iso_rr_pattern [***] - Like -gefacl but listing recursively the whole file trees - underneath eventual directories. --getfattr iso_rr_pattern [***] - Print the xattr of the given files in the ISO image. If a file has - no such xattr then noting is printed for it. The choice of - namespaces depends on the setting of command -xattr: "on" or "user" - restricts it to namespace "user", "any" only omits namespace - "isofs". --getfattr_r iso_rr_pattern [***] - Like -gefattr but listing recursively the whole file trees - underneath of directories. --du iso_rr_pattern [***] - Recursively list size of directories and files in the ISO image - which match one of the patterns. similar to shell command du -k. --dus iso_rr_pattern [***] - List size of directories and files in the ISO image which match one - of the patterns. Similar to shell command du -sk. --dux disk_pattern [***] - Recursively list size of directories and files in the local - filesystem which match one of the patterns. Similar to shell - command du -k. --dusx disk_pattern [***] - List size of directories and files in the local filesystem which - match one of the patterns. Similar to shell command du -sk. --findx disk_path [-name pattern] [-type t] [-exec action [params]] -- - Like -find but operating on local filesystem and not on the ISO - image. This is subject to the settings of -follow. - -findx accepts the same -type parameters as -find. Additionally it - recognizes type "mountpoint" (or "m") which matches subdirectories - which reside on a different device than their parent. It never - matches the disk_path given as start address for -findx. - -findx accepts the -exec actions as does -find. But except the - following few actions it will always perform action "echo". - - in_iso - reports the path if its counterpart exists in the ISO image. - For this the disk_path of the -findx command gets replaced by - the iso_rr_path given as parameter. - E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd -- - not_in_iso - reports the path if its counterpart does not exist in the ISO - image. The report format is the same as with command - -compare. - add_missing iso_rr_path_start - adds the counterpart if it does not yet exist in the ISO image - and marks it for "rm_merge" as non-removable. - E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd -- - is_full_in_iso - reports if the counterpart in the ISO image contains files. - To be used with -type "m" to report mount points. - empty_iso_dir - deletes all files from the counterpart in the ISO image. To - be used with -type "m" to truncate mount points. - estimate_size - prints a lower and an upper estimation of the number of blocks - which the found files together will occupy in the emerging ISO - image. This does not account for the superblock, for the - directories in the -findx path, or for image padding. - list_extattr mode - prints a script to the result channel, which would use FreeBSD - command setextattr to set the file's xattr name-value pairs of - user namespace. See -find for a description of parameter - mode. - E.g. -exec list_extattr e - --compare disk_path iso_rr_path - Compare attributes and eventual data file content of a fileobject - in the local filesystem with a file object in the ISO image. The - iso_rr_path may well point to an image file object which is not yet - committed, i.e. of which the data content still resides in the - local filesystem. Such data content is prone to externally caused - changes. - If iso_rr_path is empty then disk_path is used as path in the ISO - image too. - Differing attributes are reported in detail, differing content is - summarized. Both to the result channel. In case of no differences - no result lines are emitted. --compare_r disk_path iso_rr_path - Like -compare but working recursively. I.e. all file objects - below both addresses get compared whether they have counterparts - below the other address and whether both counterparts match. --compare_l disk_prefix iso_rr_prefix disk_path [***] - Perform -compare_r with each of the disk_path parameters. - iso_rr_path will be composed from disk_path by replacing - disk_prefix by iso_rr_prefix. --show_stream iso_rr_path [***] - Display the content stream chain of data files in the ISO image. - The chain consists of the iso_rr_name and one or more streams, - separated by " < " marks. A stream description consists of one or - more texts, separated by ":" characters. The first text tells the - stream type, the following ones, if ever, describe its individual - properties. Frequently used types are: - disk:'disk_path' for local filesystem objects. - image:'iso_rr_path' for ISO image file objects. - cout:'disk_path offset count' for -cut_out files. - extf:'filter_name' for external filters. - Example: - '/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x' --show_stream_r iso_rr_path [***] - Like -show_stream but working recursively. - - -File: xorriso.info, Node: Verify, Next: Restore, Prev: Navigate, Up: Commands - -9.18 Evaluation of readability and recovery -=========================================== - -It is not uncommon that optical media produce read errors. The reasons -may be various and get obscured by error correction which is performed -by the drives and based on extra data on the media. If a drive returns -data then one can quite trust that they are valid. But at some degree -of read problems the correction will fail and the drive is supposed to -indicate error. -'xorriso' can scan a medium for readable data blocks, classify them -according to their read speed, save them to a file, and keep track of -successfully saved blocks for further tries on the same medium. -By command -md5 checksums may get recorded with data files and whole -sessions. These checksums are reachable only via indev and a loaded -image. They work independently of the media type and can detect -transmission errors. - --check_media [option [option ...]] -- - Try to read data blocks from the indev drive, optionally copy them - to a disk file, and finally report about the encountered quality. - Several options may be used to modify the default behavior. - The parameters given with this command override the default - settings which may have been changed by command - -check_media_defaults. See there for a description of available - options. - The result list tells intervals of 2 KiB blocks with start address, - number of blocks and quality. Qualities which begin with "+" are - supposed to be valid readable data. Qualities with "-" are - unreadable or corrupted data. "0" indicates qualities which are - not covered by the check run or are regularly allowed to be - unreadable (e.g. gaps between tracks). - Alternatively it is possible to report damaged files rather than - blocks. - If -md5 is "on" then the default mode what=tracks looks out for - libisofs checksum tags for the ISO session data and checks them - against the checksums computed from the data stream. --check_media_defaults [option [option ...]] -- - Preset options for runs of -check_media, -extract_cut and - best_effort file extraction. Options given with -check_media will - override the preset options. -extract_cut will override some - options automatically. - An option consists of a keyword, a "=" character, and a value. - Options may override each other. So their sequence matters. - The default setting at program start is: - use=indev what=tracks min_lba=-1 max_lba=-1 retry=default - time_limit=28800 item_limit=100000 data_to=" event=ALL - abort_file=/var/opt/xorriso/do_abort_check_media - sector_map=" map_with_volid=off patch_lba0=off report=blocks - bad_limit=invalid slow_limit=1.0 chunk_size=0s async_chunks=0 - Option "reset=now" restores these startup defaults. - Non-default options are: - - report="files" - lists the files which use damaged blocks (not with - use=outdev). The format is like with find -exec - report_damage. Note that a MD5 session mismatch marks all - files of the session as damaged. If finer distinction is - desired, perform -md5 off before -check_media. - report="blocks_files" - first lists damaged blocks and then affected files. - use="outdev" - reads from the output drive instead of the input drive. This - avoids loading the ISO image tree from media. - use="sector_map" - does not read any media but loads the file given by option - sector_map= and processes this virtual outcome. - what="disc" - scans the payload range of a medium without respecting track - gaps. - what="image" - similar to "disc", but restricts scanning to the range of the - ISO 9660 image, if present. - min_lba=limit - omits all blocks with addresses lower than limit. - max_lba=limit - switches to what=disc and omits all blocks above limit. - chunk_size=size - sets the number of bytes to be read in one low-level read - operation. This gets rounded down to full blocks of 2048 - bytes. 0 means automatic size. - retry="on" - forces read retries with minimal senseful chunk size when the - normal read chunk produces a read error. This size is 1s with - CD and stdio files, 16s with DVD (1 ECC Block), and 32s with - BD (1 Cluster). By default, retries are only enabled with CD - media. "retry=off" forbits retries for all media types. - abort_file=disk_path - gives the path of the file which may abort a scan run. Abort - happens if the file exists and its mtime is not older than the - start time of the run. Use shell command "touch" to trigger - this. Other than an aborted program run, this will report the - tested and untested blocks and go on with running 'xorriso'. - time_limit=seconds - gives the number of seconds after which the scan shall be - aborted. This is useful for unattended scanning of media - which may else overwork the drive in its effort to squeeze out - some readable blocks. Abort may be delayed by the drive - gnawing on the last single read operation. Value -1 means - unlimited time. - item_limit=number - gives the number of report list items after which to abort. - Value -1 means unlimited item number. - data_to=disk_path - copies the valid blocks to the given file, which must support - random access writing, unless disk_path is "-" which means - standard output. - In the latter case, patch_lba0= settings other than "off" - yield failure. Further the usual result messages of - -check_media get redirected to the info channel. But beware - of result messages from other commands. Beware of -*dev "-" - which redirect standard output to standard error. Keep the - run simple: - xorriso -indev /dev/sr0 -check_media data_to=- - | md5sum - xorriso -outdev /dev/sr0 -check_media data_to=- use=outdev \ - what=disc min_lba=0 max_lba=999999 - | sha256sum - event=severity - sets the given severity for a problem event which shall be - issued at the end of a check run if data blocks were - unreadable or failed to match recorded MD5 checksums. - Severity "ALL" disables this event. - sector_map=disk_path - tries to read the file given by disk_path as sector bitmap and - to store such a map file after the scan run. The bitmap tells - which blocks have been read successfully in previous runs. It - is the persistent memory for several scans on the same medium, - even with intermediate eject, in order to collect readable - blocks whenever the drive is lucky enough to produce them. - The stored file contains a human readable TOC of tracks and - their start block addresses, followed by binary bitmap data. - By default, untested blocks are not considered bad, but rather - as intentionally unread. If you expect time_limit= or - item_limit= to abort the run, then consider to use - bad_limit="untested". - map_with_volid="on" - examines tracks whether they are ISO images and prints their - volume IDs into the human readable TOC of sector_map=. - patch_lba0="on" - transfers within the data_to= file a copy of the currently - loaded session head to the start of that file and patches it - to be valid at that position. This makes the loaded session - the last valid session of the image file when it gets mounted - or loaded as stdio: drive. New sessions will be appended - after this last session and will overwrite any sessions which - have followed it. - patch_lba0="force" - performs patch_lba0="on" even if 'xorriso' believes that the - copied data are not valid. - patch_lba0= may also bear a number. If it is 32 or higher it - is taken as start address of the session to be copied. In - this case it is not necessary to have an -indev and a loaded - image. ":force" may be appended after the number. - bad_limit=threshold - sets the highest quality which shall be considered as damage. - Choose one of "good", "md5_match", "slow", "partial", "valid", - "untested", "md5_mismatch", "invalid", "tao_end", "off_track", - "unreadable". - "valid" and "invalid" are qualities imported from a sector_map - file. "tao_end" and "off_track" are intentionally not - readable, but not bad either. "partial" are blocks retrieved - from a partially readable chunk. They are supposed to be ok - but stem from a suspicious neighborhood. - "md5_match" and "md5_mismatch" regions overlap with regions of - other quality. The former is a strong confirmation for - quality, the latter only tells that one or more blocks of the - region must be wrong. - By default bad_limit is set higher than md5_mismatch, so that - mismatches are classified as quality class "0" rather than - "-". This means that the sectors of a MD5 mismatch range are - recorded in the sector_map as successfully read, if the drive - handed them out at all. Set "bad_limit=md5_mismatch" to let - the sector_map record the whole mismatching range as yet not - retrieved. - slow_limit=threshold - sets the time threshold for a single read chunk to be - considered slow. This may be a fractional number like 0.1 or - 1.5. - async_chunks=number - enables asynchronous MD5 processing if number is 2 or larger. - In this case the given number of read chunks is allocated as - fifo buffer. On very fast MMC drives try: chunk_size=64s - async_chunks=16. --check_md5 severity iso_rr_path [***] - Compare the data content of the given files in the loaded image - with their recorded MD5 checksums, if there are any. In case of - any mismatch an event of the given severity is issued. It may then - be handled by appropriate settings of commands -abort_on or - -return_with which both can cause non-zero exit values of the - program run. Severity ALL suppresses that event. - This command reports match and mismatch of data files to the result - channel. Non-data files cause NOTE events. There will also be - UPDATE events from data reading. - If no iso_rr_path is given then the whole loaded session is - compared with its MD5 sum. Be aware that this covers only one - session and not the whole image if there are older sessions. --check_md5_r severity iso_rr_path [***] - Like -check_md5 but checking all data files underneath the given - paths. Only mismatching data files will be reported. - - -File: xorriso.info, Node: Restore, Next: Emulation, Prev: Verify, Up: Commands - -9.19 osirrox ISO-to-disk restore commands -========================================= - -Normally 'xorriso' only writes to disk files which were given as stdio: -pseudo-drives or as log files. But its alter ego osirrox is able to -extract file objects from ISO images and to create, overwrite, or delete -file objects on disk. -Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply. If disk -file objects already exist then the settings of -overwrite and -reassure -apply. But -overwrite "on" only triggers the behavior of -overwrite -"nondir". I.e. directories cannot be deleted. -Access permissions of files in the ISO image do not restrict restoring. -The directory permissions on disk have to allow rwx. - --osirrox setting[:option:...] - Setting *off* disables disk filesystem manipulations. This is the - default unless the program was started with leafname *osirrox*. - Elsewise the capability to restore files can be enabled explicitly - by -osirrox *on*. It can be irrevocably disabled by -osirrox - *banned*. - The setting *blocked* is like *off*. But it can only be revoked by - setting *unblock*, which elsewise is like *on*. This can be used - to curb command scripts which might use *on* undesiredly. - To enable restoring of special files by *device_files* is - potentially dangerous. The meaning of the number st_rdev (see man - 2 stat) depends much on the operating system. Best is to restore - device files only to the same system from where they were copied. - If not enabled, device files in the ISO image are ignored during - restore operations. - Due to a bug of previous versions, device files from previous - sessions might have been altered to major=0, minor=1. So this - combination does not get restored. - Option *concat_split_on* is default. It enables restoring of split - file directories as data files if the directory contains a complete - collection of -cut_out part files. With option *concat_split_off* - such directories are handled like any other ISO image directory. - Option *auto_chmod_off* is default. If *auto_chmod_on* is set then - access restrictions for disk directories get circumvented if those - directories are owned by the effective user who runs 'xorriso'. - This happens by temporarily granting rwx permission to the owner. - Option *sort_lba_on* may improve read performance with optical - drives. It can restore large numbers of hard links without - exhausting -temp_mem_limit. It does not preserve directory mtime - and it needs -osirrox option auto_chmod_on in order to extract - directories which offer no write permission. Default is - *sort_lba_off*. - Option *o_excl_on* is the default unless the program was started - with leafname "osirrox". On GNU/Linux it tries to avoid using - drives which are mounted or in use by other libburn programs. - Option *o_excl_off* on GNU/Linux enables access to such drives by - the equivalent of -drive_access "shared:readonly". I.e. drives - which get acquired while *o_excl_off* will refuse to get blanked, - formatted, written, or ejected. But be aware that even harmless - inquiries can spoil ongoing burns of CD-R[W] and DVD-R[W]. - Option *strict_acl_off* is default. It tolerates on FreeBSD the - presence of directory "default" ACLs in the ISO image. With - *strict_acl_on* these GNU/Linux ACLs cause on FreeBSD a FAILURE - event during restore with -acl "on". - Option *check_md5_off* disables MD5 checking during copy to disk. - The default option *check_md5_on* enables it if -md5 is "on". If a - data file with recorded MD5 is copied as a whole to the disk - filesystem, then the MD5 of the copied content gets computed and - compared with the recorded MD5. A mismatch causes an error message - of severity SORRY. Option *check_md5_force* causes an error message - if -md5 is "on" but no MD5 is recorded for the data file. --extract iso_rr_path disk_path - Copy the file objects at and underneath iso_rr_path to their - corresponding addresses at and underneath disk_path. This is the - inverse of -map or -update_r. - If iso_rr_path is a directory and disk_path is an existing - directory then both trees will be merged. Directory attributes get - extracted only if the disk directory is newly created by the copy - operation. Disk files get removed only if they are to be replaced - by file objects from the ISO image. - As many attributes as possible are copied together with restored - file objects. --extract_single iso_rr_path disk_path - Like -extract, but if iso_rr_path is a directory then its sub tree - gets not restored. --extract_l iso_rr_prefix disk_prefix iso_rr_path [***] - Perform -extract with each of the iso_rr_path parameters. - disk_path will be composed from iso_rr_path by replacing - iso_rr_prefix by disk_prefix. --extract_cut iso_rr_path byte_offset byte_count disk_path - Copy a byte interval from a data file out of an ISO image into a - newly created disk file. The main purpose for this is to offer a - way of handling large files if they are not supported by mount -t - iso9660 or if the target disk filesystem cannot store large files. - If the data bytes of iso_rr_path are stored in the loaded ISO - image, and no filter is applied, and byte_offset is a multiple of - 2048, then a special run of -check_media is performed. It may be - quicker and more rugged than the general reading method. --cpx iso_rr_path [***] disk_path - Copy single leaf file objects from the ISO image to the address - given by disk_path. If more then one iso_rr_path is given then - disk_path must be a directory or non-existent. In the latter case - it gets created and the extracted files get installed in it with - the same leafnames. - Missing directory components in disk_path will get created, if - possible. - Directories are allowed as iso_rr_path only with -osirrox - "concat_split_on" and only if they actually represent a complete - collection of -cut_out split file parts. --cpax iso_rr_path [***] disk_path - Like -cpx but restoring mtime, atime as in ISO image and trying to - set ownership and group as in ISO image. --cp_rx iso_rr_path [***] disk_path - Like -cpx but also extracting whole directory trees from the ISO - image. - The resulting disk paths are determined as with shell command cp -r - : If disk_path is an existing directory then the trees will be - inserted or merged underneath this directory and will keep their - leaf names. The ISO directory "/" has no leaf name and thus gets - mapped directly to disk_path. --cp_rax iso_rr_path [***] disk_path - Like -cp_rx but restoring mtime, atime as in ISO image and trying - to set ownership and group as in ISO image. --paste_in iso_rr_path disk_path byte_offset byte_count - Read the content of a ISO data file and write it into a data file - on disk beginning at the byte_offset. Write at most byte_count - bytes. This is the inverse of command -cut_out. --concat mode [target | lim prog [args [...]] lim] iso_rr_path [***] - Copy the data content of one or more data files of the ISO image - into a disk file object, into a file descriptor, or start a program - and copy the data into its standard input. The latter is subject - to the security restrictions for external filters. - Modes *overwrite* and *append* write into the target which is given - by the second parameter. This may be the path to a disk file - object, or "-" which means standard output, or a text of the form - /dev/fd/number, where number is an open file descriptor (e.g. - standard error is /dev/fd/2). An existing target file is not - removed before writing begins. If it is not able to take content - data, then this command fails. Mode overwrite truncates regular - data files to 0 size before writing into them. Example: - - -concat append /home/me/accumulated_text /my/iso/text - - - Mode *pipe* expects as second parameter a delimiter word which - shall mark the end of the program argument list. The third - argument is the disk_path to the program. It must contain at least - one '/'. $PATH is not applied. Further parameters up to the - announced delimiter word are used as arguments with the program - start. Example: - - -iso_rr_pattern on \ - -concat pipe + /usr/bin/wc + "/my/iso/files*" - - - The further parameters in all modes are the iso_rr_paths of data - files. Their content gets concatenated in the copy. --mount drive entity id path - Produce the same line as -mount_cmd and then execute it as external - program run after giving up the depicted drive. See also - -mount_opts. This demands -osirrox to be enabled and normally will - succeed only for the superuser. For safety reasons the mount - program is only executed if it is reachable as /bin/mount or - /sbin/mount. - - -File: xorriso.info, Node: Emulation, Next: Scripting, Prev: Restore, Up: Commands - -9.20 Command compatibility emulations (cdrtools) -================================================ - -Writing of ISO 9660 on CD is traditionally done by program mkisofs as -ISO 9660 image producer and cdrecord as burn program. 'xorriso' does -not strive for their comprehensive emulation. Nevertheless it is ready -to perform some of its core tasks under control of commands which in -said programs trigger comparable actions. - --as personality option [options] -- - - Perform the variable length option list as sparse emulation of the - program depicted by the personality word. - - Personality "*mkisofs*" accepts the options listed with: - -as mkisofs -help -- - Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mode, - -file-mode, -path-list, -m, -exclude-list, -f, -print-size, -pad, - -no-pad, -V, -v, -version, -graft-points, -z, -no-emul-boot, -b, - -c, -boot-info-table, -boot-load-size, -input-charset, -G, - -output-charset, -U, -hide, -hide-joliet, -hide-list, - -hide-joliet-list, file paths and pathspecs. A lot of options are - not supported and lead to failure of the mkisofs emulation. Some - are ignored, but better do not rely on this tolerance. - The supported options are documented in detail in xorrisofs.info - and in man xorrisofs. The description here is focused on the - effect of mkisofs emulation in the context of a 'xorriso' run. - Other than with the "cdrecord" personality there is no automatic - -commit at the end of a "mkisofs" option list. Verbosity settings - -v (= "UPDATE") and -quiet (= "SORRY") persist. The output file - persists until things happen like -commit, -rollback, -dev, or end - of 'xorriso'. - Options which affect all file objects in the ISO image, like -r or - -dir-mode, will be applied only to files which are present in the - ISO image when the command -as ends. If you use several -as - mkisofs commands in the same run, then consider to put such options - into the last -as command. - If files are added to the image, then -pacifier gets set to - "mkisofs" and -stdio_sync is defaulted to "off" if no such setting - was made yet. - -graft-points is equivalent to -pathspecs on. Note that pathspecs - without "=" are interpreted differently than with 'xorriso' command - -add. Directories get merged with the root directory of the ISO - image, other filetypes get mapped into that root directory. - If pathspecs are given and if no output file was chosen before or - during the "mkisofs" option list, then standard output (-outdev - "-") will get into effect. If -o points to a regular file, then it - will be truncated to 0 bytes when finally writing begins. This - truncation does not happen if the drive is chosen by 'xorriso' - commands before -as mkisofs or after its list delimiter. - Directories and symbolic links are no valid -o targets. - Writing to stdout is possible only if -as "mkisofs" was among the - start arguments or if other start arguments pointed the output - drive to standard output. - -print-size inhibits automatic image production at program end. - This ban is lifted only if the pending image changes get discarded. - - Padding is counted as part of the ISO image if not option -emul-toc - is given. - If no -iso-level is given, then level 1 is chosen when the first - file or directory is added to the image. At the same occasion - directory names get allowed to violate the standard by -compliance - option allow_dir_id_ext. This may be avoided by option - -disallow_dir_id_ext. - Option -root is supported. Option -old-root is implemented by - 'xorriso' commands -mkdir, -cp_clone, -find update_merge, and -find - rm_merge. -root and -old-root set command -disk_dev_ino to - "ino_only" and -md5 to "on", by default. -disk_dev_ino can be set - to "off" by --old-root-no-ino or to "on" by --old-root-devno . - -md5 can be set to "off" by --old-root-no-md5 . - Not original mkisofs options are --quoted_path_list , --hardlinks , - --acl , --xattr , --md5 , --stdio_sync . They work like the - 'xorriso' commands with the same name and hardcoded parameter "on", - e.g. -acl "on". Explicit parameters are expected by --stdio_sync - and --scdbackup_tag. - The capability to preserve multi-session history on overwritable - media gets disabled by default. It can be enabled by using - --emul-toc with the first session. See -compliance no_emul_toc. - --sort-weight gets as parameters a number and an iso_rr_path. The - number becomes the LBA sorting weight of regular file iso_rr_path - or of all regular files underneath directory iso_rr_path. (See - -find -exec sort_weight). - Adopted from grub-mkisofs are --protective-msdos-label (see - -boot_image grub partition_table=on) and - --modification-date=YYYYMMDDhhmmsscc (see -volume_date uuid). For - EFI bootable GRUB boot images use --efi-boot. It performs - -boot_image grub efi_path= surrounded by two -boot_image "any" - "next". Alternative option -e from Fedora genisoimage sets - bin_path and platform_id for EFI, but performs no "next". - For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE, - where FILE is one of the Syslinux files mbr/isohdp[fp]x*.bin . Use - this instead of -G to apply the effect of -boot_image isolinux - partition_table=on. - --boot-catalog-hide is -boot_image any cat_hidden=on. - -mips-boot is the same as -boot_image any mips_path= . - -mipsel-boot leads to mipsel_path= . - -partition_offset number is -boot_image any - partition_offset=number. - Command -append_partition is supported. - -untranslated_name_len number is -compliance - untranslated_name_len=number. - --old-empty is -compliance old_empty. - The options of genisoimage Jigdo Template Extraction are recognized - and performed via 'xorriso' command -jigdo. See the "Alias:" names - there for the meaning of the genisoimage options. - - Personalities "*xorrisofs*", "*genisoimage*", and "*genisofs*" are - aliases for "mkisofs". - If 'xorriso' is started with one of the leafnames "xorrisofs", - "genisofs", "mkisofs", or "genisoimage", then it performs - -read_mkisofsrc and prepends -as "genisofs" to the program - arguments. I.e. all arguments will be interpreted mkisofs style - until "--" is encountered. From then on, arguments are interpreted - as 'xorriso' commands. - --no_rc as first argument of such a program start prevents - interpretation of startup files. See section FILES below. - - Personality "*cdrecord*" accepts the options listed with: - -as cdrecord -help -- - Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsize=, - tsize=, -isosize, -multi, -msinfo, --grow_overwriteable_iso, - write_start_address=, track source file path or "-" for standard - input as track source. - It ignores most other options of cdrecord and cdrskin but refuses - on -audio, -scanbus, and on blanking modes unknown to 'xorriso'. - The scope is only a single data track per session to be written to - blank, overwritable, or appendable media. The medium gets closed - if closing is applicable and not option -multi is present. - If an input drive was acquired, then it is given up. This is only - allowed if no image changes are pending. - dev= must be given as 'xorriso' device address. Addresses like - 0,0,0 or ATA:1,1,0 are not supported. - If a track source is given, then an automatic -commit happens at - the end of the "cdrecord" option list. - --grow_overwriteable_iso enables emulation of multi-session on - overwritable media. To enable emulation of a TOC, the first - session needs -C 0,32 with -as mkisofs (but no -M) and - --grow_overwriteable_iso write_start_address=32s with -as cdrecord. - - A much more elaborate libburn based cdrecord emulator is the - program cdrskin. - Personalites "*xorrecord*", "*wodim*", and "*cdrskin*" are aliases - for "cdrecord". - If 'xorriso' is started with one of the leafnames "xorrecord", - "cdrskin", "cdrecord", or "wodim", then it automatically prepends - -as "cdrskin" to the program arguments. I.e. all arguments will - be interpreted cdrecord style until "--" is encountered. From then - on, arguments are interpreted as 'xorriso' commands. - --no_rc as first argument of such a program start prevents - interpretation of 'xorriso' startup files. See section FILES - below. --read_mkisofsrc - Try one by one to open for reading: ./.mkisofsrc , $MKISOFSRC , - $HOME/.mkisofsrc , $(dirname $0)/.mkisofsrc - On success interpret the file content as of man mkisofs - CONFIGURATION, and end this command. Do not try further files. - The last address is used only if start argument 0 has a non-trivial - dirname. - The reader currently interprets the following NAME=VALUE pairs: - APPI (-application_id) , PUBL (-publisher) , SYSI (-system_id) , - VOLI (-volid) , VOLS (-volset_id) - Any other lines will be silently ignored. --pacifier behavior_code - Control behavior of UPDATE pacifiers during write operations. The - following behavior codes are defined: - "xorriso" is the default format: - Writing: sector XXXXX of YYYYYY [fifo active, nn% fill] - "cdrecord" looks like: - X of Y MB written (fifo nn%) [buf mmm%] - "mkisofs" - nn% done, estimate finish Tue Jul 15 20:13:28 2008 - The frequency of the messages can be adjusted by - "interval=number" - where number gives the seconds between two messages. Permissible - settings are 0.1 to 60.0. --scdbackup_tag list_path record_name - Set the parameter "name" for a scdbackup checksum record. It will - be appended in an scdbackup checksum tag to the -md5 session tag if - the image starts at LBA 0. This is the case if it gets written as - first session onto a sequential medium, or piped into a program, - named pipe or character device. - If list_path is not empty then the record will also be appended to - the data file given by this path. - Program scdbackup_verify will recognize and verify tag and file - record. - An empty record_name disables this feature. - - -File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Commands - -9.21 Scripting, dialog and program control features -=================================================== - --no_rc - - Only if used as first program argument this command prevents - reading and interpretation of startup files. See section FILES - below. --options_from_file fileaddress - Read quoted input from fileaddress and execute it like dialog - lines. Empty lines and lines which begin by # are ignored. - Normally one line should hold one 'xorriso' command and all its - parameters. Nevertheless lines may be concatenated by a trailing - backslash. - See also section "Command processing", paragraph "Quoted input". --help - - Print helptext. --version - Print program name and version, component versions, license. --list_extras code - Tell whether certain extra features were enabled at compile time. - Code "all" lists all features and a headline. Other codes pick a - single feature. Code "codes" lists them. They share names with - related commands (see also there): - "acl" tells whether xorriso has an adapter for local filesystems - ACLs. - "xattr" tells whether xorriso has an adapter for local filesystems - EA. - "jigdo" tells whether production of Jigdo files is possible. - "zisofs" tells whether zisofs and built-in gzip filters are - enabled. - "external_filter" tells whether external filter processes are - allowed and whether they are allowed if real user id and effective - user id differ. - "dvd_obs" tells whether 64 kB output to DVD media is default. - "use_readline" tells whether readline may be enabled in dialog - mode. --history textline - Copy textline into libreadline history. --status mode|filter - Print the current settings of 'xorriso'. Modes: - short... print only important or altered settings - long ... print all settings including defaults - long_history like long plus history lines - Filters begin with '-' and are compared literally against the - output lines of -status:long_history. A line is put out only if - its start matches the filter text. No wildcards. --status_history_max number - Set maximum number of history lines to be reported with -status - "long_history". --list_delimiter word - Set the list delimiter to be used instead of "--". It has to be a - single word, must not be empty, not longer than 80 characters, and - must not contain quotation marks. - For brevity the list delimiter is referred as "--" throughout this - text. --sh_style_result "on"|"off" - Make the result output of some filesystem inspection commands look - more like the output of equivalent shell commands. The most - important effect is to prevent the wrapping of file addresses into - quotation marks with commands -pwd -pwdx -ls -lsd -lsl -lsdl -lsx - -lsdx -lslx -lsdlx -du -dus -dux -dusx -findx -find - This will make ambiguous the representation of file names which - contain newline characters. On the other hand it should facilitate - integration of xorriso into shell scripts which already use the - corresponding shell commands. --backslash_codes "on"|"off"|mode[:mode] - Enable or disable the interpretation of symbolic representations of - special characters with quoted input, or with program arguments, or - with program text output. If enabled the following translations - apply: - \a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014) - \n=linefeed(012) \r=carriage_return(015) \t=tab(011) - \v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code - \x[0-9a-f][0-9a-f]=hex_code \cC=control-C - Translations can occur with quoted input in 3 modes: - "in_double_quotes" translates only inside " quotation. - "in_quotes" translates inside " and ' quotation. - "with_quoted_input" translates inside and outside quotes. - With the start program arguments there is mode: - "with_program_arguments" translates program arguments. - - Mode "encode_output" encodes output characters. It combines - "encode_results" with "encode_infos". Inside single or double - quotation marks encoding applies to 8-bit characters octal 001 to - 037 , 177 to 377 and to backslash(134). Outside quotation marks - some harmless ASCII control characters stay unencoded: bell(007), - backspace(010), tab(011), linefeed(012), formfeed(014), - carriage_return(015). - Mode "off" is default and disables any translation. Mode "on" is - "with_quoted_input:with_program_arguments:encode_output". --temp_mem_limit number["k"|"m"] - Set the maximum size of temporary memory to be used for image - dependent buffering. Currently this applies to pattern expansion, - LBA sorting, restoring of hard links. - Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 - GiB. --print text - Print a text line to the result channel which is by default stdout. --print_info text - Print a text line to the info channel which is by default stderr. --print_mark text - Print a text line to the mark channel which is by default directed - to both, result and info channel. An empty text will cause no - output at all. --prompt text - Show text at beginning of output line and wait for the user to hit - the Enter key or to send a line via stdin. --sleep seconds - Wait for the given number of seconds before performing the next - command. Expect coarse granularity no better than 1/100 seconds. --errfile_log mode path|channel - - If problem events are related to input files from the filesystem, - then their disk_paths can be logged to a file or to output channels - R or I. - Mode can either be "plain" or "marked". The latter causes marker - lines which give the time of log start, burn session start, burn - session end, log end or program end. In mode "plain", only the - file paths are logged. - If path is "-" or "-R" then the log is directed to the result - channel. Path "-I" directs it to the info message channel. Any - text that does not begin with "-" is used as path for a file to - append the log lines. - Problematic files can be recorded multiple times during one program - run. If the program run aborts then the list might not be complete - because some input files might not have been processed at all. - The errfile paths are transported as messages of very low severity - "ERRFILE". This transport becomes visible with -report_about "ALL". --session_log path - If path is not empty it gives the address of a plain text file - where a log record gets appended after each session. This log can - be used to determine the start_lba of a session for mount options - -o sbsector= (on GNU/Linux) or -s (on FreeBSD) from date or volume - ID. - Record format is: timestamp start_lba size volume-id - The first three items are single words, the rest of the line is the - volume ID. --scsi_log "on"|"off" - Mode "on" enables very verbose logging of SCSI commands and drive - replies. Logging messages get printed to stderr, not to any of the - 'xorriso' output channels. - A special property of this command is that the first -scsi_log - setting among the start arguments is in effect already when the - first operations of 'xorriso' begin. Only "-scsi_log" with dash - "-" is recognized that way. --end - - End program after writing pending changes. --rollback_end - Discard pending changes. End program immediately. -# any text - Only in dialog or file execution mode, and only as first - non-whitespace in line: Do not execute the line but store it in - readline history. - - -File: xorriso.info, Node: Frontend, Next: ExDevices, Prev: Scripting, Up: Commands - -9.22 Support for frontend programs via stdin and stdout -======================================================= - --pkt_output "on"|"off" - Consolidate text output on stdout and classify each line by a - channel indicator: - 'R:' for result lines, - 'I:' for notes and error messages, - 'M:' for -mark texts. - Next is a decimal number of which only bit 0 has a meaning for now. - 0 means no newline at end of payload, 1 means that the newline - character at the end of the output line belongs to the payload. - After another colon and a blank follows the payload text. - Example: - I:1: enter option and parameters : --logfile channel fileaddress - Copy output of a channel to the given file. Channel may be one of: - "." for all channels, "I" for info messages, "R" for result lines, - "M" for -mark texts. --mark text - If text is not empty it will get put out on "M" channel each time - 'xorriso' is ready for the next dialog line or before 'xorriso' - performs a command that was entered to the pager prompt. --msg_op opcode parameter_text - This command shall facilitate extraction of particular information - from the message output of other commands. It gives access to the - C API function Xorriso_parse_line() and to the message sieve that - is provided by the C API. Please refer to their descriptions in - file xorriso.h. Further it helps to interpret the severity codes - of info messages. - Intended users are frontend programs which operate xorriso in - dialog mode. - The result output of this command is not caught by the message - sieve. - The following opcodes are defined: - *start_sieve* - Install the message sieve as of Xorriso_sieve_big() and start - watching program messages. The parameter_text has no meaning. - *show_sieve* - Show a list of filter rule names. The parameter_text has no - meaning. The list begins by a line with the return value of - Xorriso_sieve_get_result() with flag bit3. If this value is larger - than 0, then the next line tells the number of names. The - following lines show one name each. - *read_sieve* - Use the parameter_text as name of a filter rule and inquire its - next recorded result. See Xorriso_sieve_big() for a list of names - and reply strings. - The recorded strings are put out on result channel. They get - wrapped into lines which tell their structure. The first line - tells the return value of Xorriso_sieve_get_result(). The next - line tells the number of strings. Each string begins by a line - that tells the number of lines of the string. Then follow these - lines. They are to be concatenated with a newline character - between each of them. Finally the number of still available - recorded results of the given name is put out. - *clear_sieve* - Dispose all recorded strings and continue watching program - messages. The parameter_text has no meaning. - *end_sieve* - Dispose the sieve with its filter rules and stop watching program - messages. The parameter_text has no meaning. - *parse* - Read a text from dialog input and submit it to - Xorriso_parse_line(). The parameter_text word shall consist of - several words separated by blanks. It will be necessary to use - both kinds of quotation marks. - E.g. "'ISO session :' " 0 0 1" - The five parameter words are: prefix, separators, max_words, flag, - number_of_input_lines. The former four are handed over to - Xorriso_parse_line(). The number of input lines minus one tells - xorriso how many newline characters are part of the input text. - The announced number of text lines will be read from dialog input, - concatenated with a newline character between each of them, and - submitted to Xorriso_parse_line() as parameter line. Note that - newlines outside of quotation marks are interpreted as separators - if the separators parameter is empty. - The parsed strings are put out on result channel. They get wrapped - into lines which tell their structure. The first line tells the - return value of Xorriso_parse_line(). The next line tells the - number of strings. Each string begins by a line that tells the - number of lines of the string. Then follow these lines. They are - to be concatenated with a newline character between each of them. - If -backslash_codes "encode_output" is enabled, then the strings - undergo encoding as if they were enclosed in quotes. Escpecially - each string will be put out as a single result line. - *parse_bulk* - Like "parse", but with the fifth parameter word being - number_of_input_texts rather than number_of_input_lines. Each - input text has to be preceded by a line that tells - number_of_input_lines as with "parse". Then come the announced - number of text lines. - All input texts will be read before printing of result lines - begins. This consumes memory in xorriso. So the - number_of_input_texts should not be extremely high. On the other - hand, large transactions of command, input texts, and results are - desirable if connection latency is an issue. - *parse_silently* - Like "parse" but not issuing a prompting message. Confusing to - humans. - *parse_bulk_silently* - Like "parse_bulk" but not issuing a prompting message. Confusing - to humans. - *compare_sev* - The parameter_text should contain two comma separated severity - texts as issued by this program. Like "SORRY,UPDATE". See also - paragraph "Exception processing". - These two severity texts get compared and a number gets printed to - the result channel. This number is 0 if both severities are equal. - It is -1 if the first severity is lower than the second one. It is - 1 is the first severity is higher than the second one. - Above example "SORRY,UPDATE" will yield 1. - *list_sev* - Print to the result channel a blank separated list of all severity - names. Sorted from low to high severity. --named_pipe_loop mode[:mode] disk_path_stdin disk_path_stdout disk_path_stderr - Temporarily replace standard input, standard output and standard - error by named pipes. Enter dialog mode without readline. - Defined modes are: - "cleanup" removes the submitted pipe files when the loop ends. - "keep" does not delete them. This is the default. - "buffered" reads all lines from the input pipe until EOF before it - opens the output pipes and processes the input lines. - "direct" opens the output pipes after the first input line was - read. Each line is executed directly after it is read. This is - the default. - The other three parameters must either be disk paths to existing - named pipes, or be "-" to leave the according standard i/o channel - unreplaced. - xorriso will open the stdin pipe, read and execute dialog lines - from it until the sender closes the pipe. The output pipes get - opened depending on mode "buffered" or "direct". After all lines - are executed, xorriso will close its side of the pipes and enter a - new cycle of opening, reading and executing. - If an input line consists only of the word "end_named_pipe_loop" - then -named_pipe_loop will end and further xorriso commands may be - executed from other sources. --launch_frontend program [arguments ...] -- - Start the program that is given as first parameter. Submit the - other parameters as program arguments. Enable xorriso dialog mode. - - Two nameless pipe objects are created. xorriso standard input gets - connected to the standard output of the started program. xorriso - standard output and standard error get connected to the standard - input of that program. - xorriso will abort when the started program ends or if it cannot be - started at all. In both cases it will return a non-zero exit - value. The exit value will be zero if the frontend sends -end or - -rollback_end before ending itself. - This command may be totaly banned at compile time. It is banned by - default if xorriso runs under setuid permissions. - The program name will not be searched in the $PATH directories. To - make this clear, it must contain at least one /-character. Best is - an absolute path. - Example: - xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio - - The frontend program should first send via its standard output: - -mark 0 -pkt_output on -msg_op start_sieve - -reassure off - It should be ready to decode -pkt_output and to react on -mark - messages. Best is to increment the -mark number after each sent - command sequence and then to wait for the new number to show up in - a mark message: - ...some...commands... -mark - Further are advised: - -report_about UPDATE -abort_on NEVER - -iso_rr_pattern off -disk_pattern off - A check of the xorriso version should be done, in order to make - sure that all desired features are present. - Command -launch_frontend will only work once per xorriso run. If - no command parameters are submitted or if program is an empty text, - then no program will be started but nevertheless -launch_frontend - will be irrevocably disabled. --prog text - Use text as name of this program in subsequent messages --prog_help text - Use text as name of this program and perform -help. - - -File: xorriso.info, Node: Examples, Next: Files, Prev: Commands, Up: Top - -10 Examples -*********** - -* Menu: - -* ExDevices:: As superuser learn about available drives -* ExCreate:: Blank medium and compose a new ISO image as batch run -* ExDialog:: A dialog session doing about the same -* ExGrowing:: Manipulate an existing ISO image on the same medium -* ExModifying:: Copy modified ISO image from one medium to another -* ExBootable:: Bring a prepared ISOLINUX tree onto medium and make it bootable -* ExCharset:: Change existing file name tree from ISO-8859-1 to UTF-8 -* ExPseudo:: Operate on storage facilities other than optical drives -* ExCdrecord:: Burn an existing ISO image file to medium -* ExMkisofs:: Perform multi-session runs as of cdrtools traditions -* ExGrowisofs:: Let 'xorriso' work underneath growisofs -* ExException:: Adjust thresholds for verbosity, exit value and program abort -* ExTime:: Examples of input timestrings -* ExIncBackup:: Incremental backup of a few directory trees -* ExRestore:: Restore directory trees from a particular ISO session to disk -* ExRecovery:: Try to retrieve blocks from a damaged medium - - -File: xorriso.info, Node: ExDevices, Next: ExCreate, Prev: Frontend, Up: Examples - -10.1 As superuser learn about available drives -============================================== - -On Linux, FreeBSD or NetBSD consider to give rw-permissions to those -users or groups which shall be able to use the drives with 'xorriso'. -On Solaris use pfexec. Consider to restrict privileges of 'xorriso' to -"base,sys_devices" and to give r-permission to user or group. - - $ xorriso -device_links -1 -dev '/dev/cdrom1' rwrw-- : 'TSSTcorp' 'DVD-ROM SH-D162C -1 -dev '/dev/cdrw' rwrw-- : 'TSSTcorp' 'CDDVDW SH-S223B' -2 -dev '/dev/cdrw3' rwrw-- : 'HL-DT-ST' 'BDDVDRW_GGC-H20L' - - -File: xorriso.info, Node: ExCreate, Next: ExDialog, Prev: ExDevices, Up: Examples - -10.2 Blank medium and compose a new ISO image as batch run -========================================================== - -Acquire drive /dev/sr2, make medium ready for writing a new image, fill -the image with the files from hard disk directories /home/me/sounds and -/home/me/pictures. -Because no -dialog "on" is given, the program will then end by writing -the session to the medium. - - $ xorriso -outdev /dev/sr2 \ --blank as_needed \ --map /home/me/sounds /sounds \ --map /home/me/pictures /pictures - - - The ISO image may be shaped in a more elaborate way like the -following: Omit some unwanted stuff by removing it from the image -directory tree. Reintroduce some wanted stuff. - - $ cd /home/me -$ xorriso -outdev /dev/sr2 \ --blank as_needed \ --map /home/me/sounds /sounds \ --map /home/me/pictures /pictures \ --rm_r \ -/sounds/indecent \ -'/pictures/*private*' \ -/pictures/confidential \ --- \ --cd / \ --add pictures/confidential/work* -- - - Note that '/pictures/*private*' is a pattern for iso_rr_paths while -pictures/confidential/work* gets expanded by the shell with addresses -from the hard disk. Commands -add and -map have different parameter -rules but finally the same effect: they put files into the image. - - -File: xorriso.info, Node: ExDialog, Next: ExGrowing, Prev: ExCreate, Up: Examples - -10.3 A dialog session doing about the same as the previous example -================================================================== - -Some settings are already given as start argument. The other activities -are done as dialog input. The pager gets set to 20 lines of 80 -characters. -The drive is acquired by command -dev rather than -outdev in order to -see the message about its current content. By command -blank this -content is made ready for being overwritten and the loaded ISO image is -made empty. -In order to be able to eject the medium, the session needs to be -committed explicitly. - - $ xorriso -dialog on -page 20 80 -disk_pattern on - - enter option and arguments : --dev /dev/sr2 - - enter option and arguments : --blank as_needed - - enter option and arguments : --map /home/me/sounds /sounds -map /home/me/pictures /pictures - - enter option and arguments : --rm_r /sounds/indecent /pictures/*private* /pictures/confidential - - enter option and arguments : --cdx /home/me/pictures -cd /pictures - - enter option and arguments : --add confidential/office confidential/factory - - enter option and arguments : --du / - - enter option and arguments : --commit_eject all -end - - -File: xorriso.info, Node: ExGrowing, Next: ExModifying, Prev: ExDialog, Up: Examples - -10.4 Manipulate an existing ISO image on the same medium -======================================================== - -Load image from drive. Remove (i.e. hide) directory /sounds and its -subordinates. Rename directory /pictures/confidential to -/pictures/restricted. Change access permissions of directory -/pictures/restricted. Add new directory trees /sounds and /movies. -Burn to the same medium, check whether the tree can be loaded, and -eject. - - $ xorriso -dev /dev/sr2 \ --rm_r /sounds -- \ --mv \ -/pictures/confidential \ -/pictures/restricted \ --- \ --chmod go-rwx /pictures/restricted -- \ --map /home/me/prepared_for_dvd/sounds_dummy /sounds \ --map /home/me/prepared_for_dvd/movies /movies \ --commit -eject all - - -File: xorriso.info, Node: ExModifying, Next: ExBootable, Prev: ExGrowing, Up: Examples - -10.5 Copy modified ISO image from one medium to another -======================================================= - -Load image from input drive. Do the same manipulations as in the -previous example. Acquire output drive and blank it. Burn the modified -image as first and only session to the output drive. - - $ xorriso -indev /dev/sr2 \ --rm_r /sounds -- \ -... --outdev /dev/sr0 -blank as_needed \ --commit -eject all - - -File: xorriso.info, Node: ExBootable, Next: ExCharset, Prev: ExModifying, Up: Examples - -10.6 Bring a prepared ISOLINUX tree onto medium and make it bootable -==================================================================== - -The user has already created a suitable file tree on disk and copied the -ISOLINUX files into subdirectory ./boot/isolinux of that tree. Now -'xorriso' can burn an El Torito bootable medium: - - $ xorriso -outdev /dev/sr0 -blank as_needed \ --map /home/me/ISOLINUX_prepared_tree / \ --boot_image isolinux dir=/boot/isolinux - - -File: xorriso.info, Node: ExCharset, Next: ExPseudo, Prev: ExBootable, Up: Examples - -10.7 Change existing file name tree from ISO-8859-1 to UTF-8 -============================================================ - -This example assumes that the existing ISO image was written with -character set ISO-8859-1 but that the readers expected UTF-8. Now a new -session gets added with converted file names. Command -changes_pending -"yes" enables writing despite the lack of any manipulation command. -In order to avoid any weaknesses of the local character set, this -command pretends that it uses already the final target set UTF-8. -Therefore strange file names may appear in messages, which will be made -terminal-safe by command -backslash_codes. - - $ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \ --out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \ --changes_pending yes -commit -eject all - - -File: xorriso.info, Node: ExPseudo, Next: ExCdrecord, Prev: ExCharset, Up: Examples - -10.8 Operate on storage facilities other than optical drives -============================================================ - -Full read-write operation is possible with regular files and block -devices: - - $ xorriso -dev /tmp/regular_file ... - - Paths underneath /dev normally need prefix "stdio:" - - $ xorriso -dev stdio:/dev/sdb ... - - If /dev/sdb is to be used frequently and /dev/sda is the system disk, -then consider to place the following lines in a 'xorriso' Startup File. -They allow you to use /dev/sdb without prefix and protect disk /dev/sda -from 'xorriso': - - -drive_class banned /dev/sda* --drive_class harmless /dev/sdb - - Other writeable file types are supported write-only: - - $ xorriso -outdev /tmp/named_pipe ... - - Among the write-only drives is standard output: - - $ xorriso -outdev - \ -... -| gzip >image.iso.gz - - -File: xorriso.info, Node: ExCdrecord, Next: ExMkisofs, Prev: ExPseudo, Up: Examples - -10.9 Burn an existing ISO image file to medium -============================================== - -Actually this works with any kind of data, not only ISO images: - - $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso - - -File: xorriso.info, Node: ExMkisofs, Next: ExGrowisofs, Prev: ExCdrecord, Up: Examples - -10.10 Perform multi-session runs as of cdrtools traditions -========================================================== - -Between both processes there can be performed arbitrary transportation -or filtering. -The first session is written like this: - - $ xorriso -as mkisofs prepared_for_iso/tree1 | \ -xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject - - - Follow-up sessions are written like this (the run of dd is only to -give demons a chance to spoil it): - - $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) -$ dd if=/dev/sr0 count=1 >/dev/null 2>&1 -$ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \ -xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject - - - Always eject the drive tray between sessions. -The run of xorriso -as mkisofs will read old sessions via the CD-ROM -driver of /dev/sr0. This driver might not be aware of the changed -content as long as the medium is not loaded again. In this case the -previous session would not be properly assessed by xorriso and the new -session would contain only the newly added files. -Some systems have not enough patience with automatic tray loading and -some demons may interfere with a first CD-ROM driver read attempt from a -freshly loaded medium. -When loading the tray manually, wait 10 seconds after the drive has -stopped blinking. -A safe automatic way seems to be a separate run of xorriso for loading -the tray with proper waiting, and a subsequent run of dd which shall -offer itself to any problems caused by demons assessing the changed -drive status. If this does not help, insert a run of "sleep 10" between -xorriso and dd. - - This example works for multi-session media only. Add cdrskin option ---grow_overwriteable_iso to all -as cdrecord runs in order to enable -multi-session emulation on overwritable media. - - -File: xorriso.info, Node: ExGrowisofs, Next: ExException, Prev: ExMkisofs, Up: Examples - -10.11 Let 'xorriso' work underneath growisofs -============================================= - -growisofs expects an ISO formatter program which understands options -C -and -M. If 'xorriso' gets started by name "xorrisofs" then it is -suitable for that. - - $ export MKISOFS="xorrisofs" -$ growisofs -Z /dev/dvd /some/files -$ growisofs -M /dev/dvd /more/files - - If no "xorrisofs" is available on your system, then you will have to -create a link pointing to the 'xorriso' binary and tell growisofs to use -it. E.g. by: - - $ ln -s $(which xorriso) "$HOME/xorrisofs" -$ export MKISOFS="$HOME/xorrisofs" - - One may quit mkisofs emulation by argument "--" and make use of all -'xorriso' commands. growisofs dislikes options which start with "-o" -but -outdev must be set to "-". So use "outdev" instead: - - $ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files -$ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files - - growisofs has excellent burn capabilities with DVD and BD. It does -not emulate session history on overwritable media, though. - - -File: xorriso.info, Node: ExException, Next: ExTime, Prev: ExGrowisofs, Up: Examples - -10.12 Adjust thresholds for verbosity, exit value and program abort -=================================================================== - -Be quite verbose, exit 32 if severity "FAILURE" was encountered, do not -abort prematurely but forcibly go on until the end of commands. - - $ xorriso ... \ --report_about UPDATE \ --return_with FAILURE 32 \ --abort_on NEVER \ -... - - -File: xorriso.info, Node: ExTime, Next: ExIncBackup, Prev: ExException, Up: Examples - -10.13 Examples of input timestrings -=================================== - -As printed by program date: -'Thu Nov 8 14:51:13 CET 2007' - - The same without ignored parts: -'Nov 8 14:51:13 2007' - - The same as expected by date: -110814512007.13 - - Four weeks in the future: -+4w - - The current time: -+0 - - Three hours ago: --3h - - Seconds since Jan 1 1970: -=1194531416 - - -File: xorriso.info, Node: ExIncBackup, Next: ExRestore, Prev: ExTime, Up: Examples - -10.14 Incremental backup of a few directory trees -================================================= - -This changes the directory trees /projects and /personal_mail in the ISO -image so that they become exact copies of their disk counterparts. ISO -file objects get created, deleted or get their attributes adjusted -accordingly. -ACL, xattr, hard links and MD5 checksums will be recorded. Accelerated -comparison is enabled at the expense of potentially larger backup size. -Only media with the expected volume ID or blank media are accepted. -Files with names matching *.o or *.swp get excluded explicitly. -When done with writing the new session gets checked by its recorded MD5. - - - $ xorriso \ --abort_on FATAL \ --for_backup -disk_dev_ino on \ --assert_volid 'PROJECTS_MAIL_*' FATAL \ --dev /dev/sr0 \ --volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \ --not_leaf '*.o' -not_leaf '*.swp' \ --update_r /home/thomas/projects /projects \ --update_r /home/thomas/personal_mail /personal_mail \ --commit -toc -check_md5 FAILURE -- -eject all - - To be used several times on the same medium, whenever an update of -the two disk trees to the medium is desired. Begin with a blank medium -and update it until the run fails gracefully due to lack of remaining -space on the old one. -This makes sense if the full backup leaves substantial remaining -capacity on media and if the expected changes are much smaller than the -full backup. To apply zisofs compression to those data files which get -newly copied from the local filesystem, insert these commands -immediately before -commit : - - -hardlinks perform_update \ --find / -type f -pending_data -exec set_filter --zisofs -- \ - - Commands -disk_dev_ino and -for_backup depend on stable device and -inode numbers on disk. Without them, an update run may use -md5 "on" to -match recorded MD5 sums against the current file content on hard disk. -This is usually much faster than the default which compares both -contents directly. -With *mount* option *-o "sbsector="* on GNU/Linux or *-s* on FreeBSD or -NetBSD it is possible to access the session trees which represent the -older backup versions. With CD media, GNU/Linux mount accepts session -numbers directly by its option "session=". -Multi-session media and most overwritable media written by 'xorriso' can -tell the sbsectors of their sessions by 'xorriso' command -toc. Used -after -commit the following command prints the matching mount command -for the newly written session (here for mount point /mnt): - - -mount_cmd "indev" "auto" "auto" /mnt - - Commands -mount_cmd and -mount are also able to produce the mount -commands for older sessions in the table-of-content. E.g. as -superuser: - - # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt - - Above example produces a result similar to -root / -old-root / with -mkisofs. For getting the session trees accumulated in the new sessions, -let all -update commands use a common parent directory and clone it -after updating is done: --update_r /home/thomas/projects /current/projects \ --update_r /home/thomas/personal_mail /current/personal_mail \ --clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \ -The cloned tree will have a name like /2011_02_12_155700. - - Sessions on multi-session media are separated by several MB of unused -blocks. So with small sessions the payload capacity can become -substantially lower than the overall media capacity. If the remaining -space on a medium does not suffice for the next gap, the drive is -supposed to close the medium automatically. - - *Better do not use your youngest backup for -update_r*. Have at -least two media which you use alternatingly. So only older backups get -endangered by the new write operation, while the newest backup is stored -safely on a different medium. -Always have a blank medium ready to perform a full backup in case the -update attempt fails due to insufficient remaining capacity. This -failure will not spoil the old medium, of course. - - -File: xorriso.info, Node: ExRestore, Next: ExRecovery, Prev: ExIncBackup, Up: Examples - -10.15 Restore directory trees from a particular ISO session to disk -=================================================================== - -This is an alternative to mounting the medium and using normal file -operations. -First check which backup sessions are on the medium: - - $ xorriso -outdev /dev/sr0 -toc - - Then enable restoring of ACL, xattr and hard links. Load the desired -session and copy the file trees to disk. Avoid to create -/home/thomas/restored without rwx-permission. - - $ xorriso -for_backup \ --load volid 'PROJECTS_MAIL_2008_06_19*' \ --indev /dev/sr0 \ --osirrox on:auto_chmod_on \ --chmod u+rwx / -- \ --extract /projects /home/thomas/restored/projects \ --extract /personal_mail /home/thomas/restored/personal_mail \ --rollback_end - - The final command -rollback_end prevents an error message about the -altered image being discarded. - - -File: xorriso.info, Node: ExRecovery, Prev: ExRestore, Up: Examples - -10.16 Try to retrieve blocks from a damaged medium -================================================== - - - -$ xorriso -abort_on NEVER -indev /dev/sr0 \ --check_media time_limit=1800 report=blocks_files \ -data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map -- - - This can be repeated several times, if necessary with -eject or with -other -indev drives. See the human readable part of -"$HOME"/dvd_copy.map for addresses which can be used on "$HOME"/dvd_copy -with mount option -o sbsector= or -s. - - -File: xorriso.info, Node: Files, Next: Environ, Prev: Examples, Up: Top - -11 Files -******** - - -11.1 Program Alias Names -======================== - -Normal installation of 'xorriso' creates three links or copies which by -their program name pre-select certain settings: - - *xorrisofs* starts 'xorriso' with -as mkisofs emulation. -*xorrecord* starts 'xorriso' with -as cdrecord emulation. -*osirrox* starts with -osirrox "on:o_excl_off" which allows further -commands to copy files from ISO image to disk and to apply command --mount to one or more of the existing ISO sessions. - -11.2 Startup Files -================== - - -If not -no_rc is given as the first argument then 'xorriso' attempts on -startup to read and execute lines from the following files: - - /etc/default/xorriso -/etc/opt/xorriso/rc -/etc/xorriso/xorriso.conf -$HOME/.xorrisorc - - The files are read in the sequence given above, but none of them is -required to exist. The line format is described with command --options_from_file. -If mkisofs emulation was enabled by program name "xorrisofs", "mkisofs", -"genisoimage", or "genisofs", then afterwards -read_mkisofsrc is -performed, which reads .mkisofsrc files. See there. - -11.3 Runtime control files -========================== - - -The default setting of -check_media abort_file= is: - - /var/opt/xorriso/do_abort_check_media - - -File: xorriso.info, Node: Environ, Next: Seealso, Prev: Files, Up: Top - -12 Environ -********** - -The following environment variables influence the program behavior: -HOME is used to find startup files of xorriso and mkisofs. -SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. It -is supposed to be either undefined or to contain a decimal number which -tells the seconds since january 1st 1970. If it contains a number, then -it is used as time value to set the default of -volume date "uuid", sets --boot_image "any" "gpt_disk_guid=" to "volume_date_uuid", -volume_date -"all_file_dates" to "set_to_mtime", and -iso_nowtime to -"=$SOURCE_DATE_EPOCH". -Startup files and program options can override the effect of -SOURCE_DATE_EPOCH. - - -File: xorriso.info, Node: Seealso, Next: Bugreport, Prev: Environ, Up: Top - -13 See also -*********** - -For the mkisofs emulation of 'xorriso' - xorrisofs(1) -For the cdrecord emulation of 'xorriso' - xorrecord(1) -For mounting 'xorriso' generated ISO 9660 images (-t iso9660) - mount(8) -Libreadline, a comfortable input line facility - readline(3) -Other programs which produce ISO 9660 images - mkisofs(8), genisoimage(1) -Other programs which burn sessions to optical media - growisofs(1), cdrecord(1), wodim(1), cdrskin(1) -ACL and xattr - getfacl(1), setfacl(1), getfattr(1), setfattr(1) -MD5 checksums - md5sum(1) -On FreeBSD some commands differ: - getextattr(8), setextattr(8), md5(1) - - -File: xorriso.info, Node: Bugreport, Next: Legal, Prev: Seealso, Up: Top - -14 Reporting bugs -***************** - -To report bugs, request help, or suggest enhancements for 'xorriso', -please send electronic mail to the public list . -If more privacy is desired, mail to . - - Please describe what you expect 'xorriso' to do, the program -arguments or dialog commands by which you tried to achieve it, the -messages of 'xorriso', and the undesirable outcome of your program run. - - Expect to get asked more questions before solutions can be proposed. - - -File: xorriso.info, Node: Legal, Next: CommandIdx, Prev: Bugreport, Up: Top - -15 Author, Copyright, Credits -***************************** - -15.1 Author -=========== - -Thomas Schmitt -for libburnia-project.org - -15.2 Copyright -============== - -Copyright (c) 2007 - 2020 Thomas Schmitt -Permission is granted to distribute this text freely. It shall only be -modified in sync with the technical properties of 'xorriso'. If you -make use of the license to derive modified versions of 'xorriso' then -you are entitled to modify this text under that same license. - -15.3 Credits -============ - -'xorriso' is in part based on work by Vreixo Formoso who provides -libisofs together with Mario Danic who also leads the libburnia team. -Vladimir Serbinenko contributed the HFS+ filesystem code and related -knowledge. Thanks to Andy Polyakov who invented emulated growing, to -Derek Foreman and Ben Jansens who once founded libburn. -Compliments towards Joerg Schilling whose cdrtools served me for ten -years. - - -File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top - -16 Alphabetic Command List -************************** - -[index] -* Menu: - -* # starts a comment line: Scripting. (line 156) -* -abort_on controls abort on error: Exception. (line 27) -* -abstract_file sets abstract file name: SetWrite. (line 250) -* -acl controls handling of ACLs: Loading. (line 165) -* -add inserts one or more paths: Insert. (line 44) -* -add_plainly inserts one or more paths: Insert. (line 68) -* -alter_date sets timestamps in ISO image: Manip. (line 139) -* -alter_date_r sets timestamps in ISO image: Manip. (line 174) -* -append_partition adds arbitrary file after image end: Bootable. - (line 423) -* -application_id sets application id: SetWrite. (line 197) -* -application_use sets application use field: SetWrite. (line 272) -* -as emulates mkisofs or cdrecord: Emulation. (line 13) -* -assert_volid rejects undesired images: Loading. (line 105) -* -auto_charset learns character set from image: Loading. (line 117) -* -backslash_codes enables backslash conversion: Scripting. (line 71) -* -ban_stdio_write demands real drive: Loading. (line 337) -* -biblio_file sets biblio file name: SetWrite. (line 256) -* -blank erases media: Writing. (line 57) -* -boot_image controls bootability: Bootable. (line 75) -* -calm_drive reduces drive activity: Loading. (line 327) -* -cd sets working directory in ISO: Navigate. (line 7) -* -cdx sets working directory on disk: Navigate. (line 15) -* -changes_pending overrides change status: Writing. (line 12) -* -charset sets input/output character set: Charset. (line 54) -* -check_md5 verifies file checksum: Verify. (line 184) -* -check_md5_r verifies file tree checksums: Verify. (line 198) -* -check_media reads media block by block: Verify. (line 21) -* -check_media_defaults sets -check_media options: Verify. (line 40) -* -chgrp sets group in ISO image: Manip. (line 49) -* -chgrp_r sets group in ISO image: Manip. (line 53) -* -chmod sets permissions in ISO image: Manip. (line 55) -* -chmod_r sets permissions in ISO image: Manip. (line 66) -* -chown sets ownership in ISO image: Manip. (line 43) -* -chown_r sets ownership in ISO image: Manip. (line 47) -* -clone copies ISO directory tree: Insert. (line 185) -* -close controls media closing: SetWrite. (line 407) -* -close_damaged closes damaged track and session: Writing. (line 205) -* -close_filter_list bans filter registration: Filter. (line 50) -* -commit writes pending ISO image: Writing. (line 27) -* -commit_eject writes and ejects: Writing. (line 53) -* -compare reports ISO/disk differences: Navigate. (line 131) -* -compare_l reports ISO/disk differences: Navigate. (line 147) -* -compare_r reports ISO/disk differences: Navigate. (line 143) -* -compliance controls standard compliance: SetWrite. (line 62) -* -concat copies ISO file content: Restore. (line 125) -* -copyright_file sets copyright file name: SetWrite. (line 245) -* -cpax copies files to disk: Restore. (line 107) -* -cpr inserts like with cp -r: Insert. (line 164) -* -cpx copies files to disk: Restore. (line 96) -* -cp_clone copies ISO directory tree: Insert. (line 196) -* -cp_rx copies file trees to disk: Restore. (line 110) -* -cp_rx copies file trees to disk <1>: Restore. (line 118) -* -cut_out inserts piece of data file: Insert. (line 139) -* -data_cache_size adjusts read cache size: Loading. (line 353) -* -dev acquires one drive for input and output: AqDrive. (line 12) -* -devices gets list of drives: Inquiry. (line 7) -* -device_links gets list of drives: Inquiry. (line 17) -* -dialog enables dialog mode: DialogCtl. (line 7) -* -disk_dev_ino fast incremental backup: Loading. (line 247) -* -disk_pattern controls pattern expansion: Insert. (line 34) -* -displacement compensate altered image start address: Loading. - (line 78) -* -drive_access control device file locking: AqDrive. (line 72) -* -drive_class controls drive accessability: AqDrive. (line 43) -* -du show directory size in ISO image: Navigate. (line 78) -* -dummy controls write simulation: SetWrite. (line 399) -* -dus show directory size in ISO image: Navigate. (line 81) -* -dusx show directory size on disk: Navigate. (line 88) -* -dux show directory size on disk: Navigate. (line 84) -* -dvd_obs set write block size: SetWrite. (line 336) -* -early_stdio_test classifies stdio drives: Loading. (line 341) -* -ecma119_map names w/o Rock Ridge, Joliet: Loading. (line 229) -* -eject ejects drive tray: Writing. (line 50) -* -end writes pending session and ends program: Scripting. (line 151) -* -errfile_log logs problematic disk files: Scripting. (line 116) -* -error_behavior controls error workarounds: Exception. (line 92) -* -external_filter registers data filter: Filter. (line 20) -* -external_filter unregisters data filter: Filter. (line 47) -* -extract copies file tree to disk: Restore. (line 69) -* -extract_cut copies file piece to disk: Restore. (line 87) -* -extract_l copies files to disk: Restore. (line 83) -* -extract_single copies file to disk: Restore. (line 80) -* -file_name_limit curbs length of file names: Loading. (line 267) -* -file_size_limit limits data file size: SetInsert. (line 7) -* -find traverses and alters ISO tree: CmdFind. (line 7) -* -findx traverses disk tree: Navigate. (line 91) -* -follow softlinks and mount points: SetInsert. (line 69) -* -format formats media: Writing. (line 87) -* -for_backup -acl,-xattr,-hardlinks,-md5: Loading. (line 215) -* -fs sets size of fifo: SetWrite. (line 402) -* -getfacl shows ACL in ISO image: Navigate. (line 60) -* -getfacl_r shows ACL in ISO image: Navigate. (line 66) -* -getfattr shows xattr in ISO image: Navigate. (line 69) -* -getfattr_r shows xattr in ISO image: Navigate. (line 75) -* -gid sets global ownership: SetWrite. (line 293) -* -grow_blindly overrides next writeable address: AqDrive. (line 112) -* -hardlinks controls handling of hard links: Loading. (line 128) -* -help prints help text: Scripting. (line 19) -* -hfsplus enables production of HFS+ partition: SetWrite. (line 14) -* -hide excludes file names from directory trees: Manip. (line 177) -* -history brings text into readline history: Scripting. (line 42) -* -indev acquires a drive for input: AqDrive. (line 23) -* -in_charset sets input character set: Loading. (line 112) -* -iso_nowtime fixed "now" time for ISO 9660 objects: Loading. - (line 241) -* -iso_rr_pattern controls pattern expansion: Manip. (line 10) -* -jigdo clears JTE or or adds parameter to JTE: Jigdo. (line 37) -* -joliet enables production of Joliet tree: SetWrite. (line 10) -* -launch_frontend starts frontend program at pipes: Frontend. - (line 141) -* -list_arg_sorting prints sorting order of -x: ArgSort. (line 26) -* -list_delimiter replaces '--': Scripting. (line 55) -* -list_extras lists compile time extra features: Scripting. (line 24) -* -list_formats lists available formats: Writing. (line 128) -* -list_profiles lists supported media: Writing. (line 163) -* -list_speeds lists available write speeds: Writing. (line 139) -* -lns creates ISO symbolic link: Insert. (line 181) -* -load addresses a particular session as input: Loading. (line 54) -* -local_charset sets terminal character set: Charset. (line 57) -* -logfile logs output channels to file: Frontend. (line 19) -* -ls lists files in ISO image: Navigate. (line 24) -* -lsd lists files in ISO image: Navigate. (line 31) -* -lsdl lists files in ISO image: Navigate. (line 42) -* -lsdlx lists files on disk: Navigate. (line 57) -* -lsdx lists files on disk: Navigate. (line 51) -* -lsl lists files in ISO image: Navigate. (line 34) -* -lslx lists files on disk: Navigate. (line 54) -* -lsx lists files on disk: Navigate. (line 45) -* -map inserts path: Insert. (line 89) -* -map_l inserts paths from disk file: Insert. (line 96) -* -map_single inserts path: Insert. (line 93) -* -mark sets synchronizing message: Frontend. (line 23) -* -md5 controls handling of MD5 sums: Loading. (line 184) -* -mkdir creates ISO directory: Insert. (line 177) -* -modesty_on_drive keep drive buffer hungry: SetWrite. (line 342) -* -mount issues mount command for ISO session: Restore. (line 153) -* -mount_cmd composes mount command line: Inquiry. (line 49) -* -mount_cmd controls mount command: Inquiry. (line 65) -* -msg_op perform operations on program messages: Frontend. (line 27) -* -mv renames files in ISO image: Manip. (line 37) -* -mv renames single file in ISO image: Manip. (line 31) -* -named_pipe_loop enters EOF resistant dialog: Frontend. (line 119) -* -not_leaf sets exclusion pattern: SetInsert. (line 59) -* -not_list sets exclusions from disk file: SetInsert. (line 63) -* -not_mgt controls file exclusion: SetInsert. (line 22) -* -not_paths sets absolute exclusion paths: SetInsert. (line 53) -* -no_rc disables startup files: Scripting. (line 7) -* -options_from_file reads commands from file: Scripting. (line 12) -* -osirrox enables ISO-to-disk copying: Restore. (line 18) -* -outdev acquires a drive for output: AqDrive. (line 29) -* -out_charset sets output character set: SetWrite. (line 285) -* -overwrite enables overwriting in ISO: SetInsert. (line 131) -* -pacifier controls pacifier text form: Emulation. (line 166) -* -padding sets amount or mode of image padding: SetWrite. (line 430) -* -page set terminal geometry: DialogCtl. (line 18) -* -paste_in copies file into disk file: Restore. (line 121) -* -pathspecs sets meaning of = with -add: SetInsert. (line 115) -* -path_list inserts paths from disk file: Insert. (line 81) -* -pkt_output consolidates text output: Frontend. (line 7) -* -preparer_id sets preparer id: SetWrite. (line 261) -* -print prints result text line: Scripting. (line 102) -* -print_info prints message text line: Scripting. (line 104) -* -print_mark prints synchronizing text line: Scripting. (line 106) -* -print_size predicts image size: Inquiry. (line 86) -* -prog sets program name: Frontend. (line 176) -* -prog_help prints help text: Frontend. (line 178) -* -prompt prompts for enter key: Scripting. (line 110) -* -publisher sets publisher id: SetWrite. (line 192) -* -pvd_info shows image id strings: Inquiry. (line 108) -* -pwd tells working directory in ISO: Navigate. (line 19) -* -pwdx tells working directory on disk: Navigate. (line 21) -* -quoted_not_list sets exclusions: SetInsert. (line 66) -* -quoted_path_list inserts paths from disk file: Insert. (line 85) -* -read_fs filesystem type for image loading: Loading. (line 96) -* -read_mkisofsrc searches and reads .mkisofsrc file: Emulation. - (line 155) -* -read_speed set read speed: Loading. (line 11) -* -reassure enables confirmation question: DialogCtl. (line 29) -* -report_about controls verbosity: Exception. (line 53) -* -report_el_torito shows Boot Catalog: Inquiry. (line 116) -* -report_system_area shows MBR, GPT, and alike: Inquiry. (line 138) -* -return_with controls exit value: Exception. (line 38) -* -rm deletes files from ISO image: Manip. (line 20) -* -rmdir deletes ISO directory: Manip. (line 29) -* -rm_r deletes trees from ISO image: Manip. (line 26) -* -rockridge disables production of Rock Ridge info: SetWrite. - (line 57) -* -rollback discards pending changes: Writing. (line 9) -* -rollback_end ends program without writing: Scripting. (line 154) -* -rom_toc_scan searches for sessions: Loading. (line 299) -* -rr_reloc_dir sets name of relocation directory: SetWrite. (line 150) -* -scdbackup_tag enables scdbackup checksum tag: Emulation. (line 179) -* -scsi_dev_family choose Linux device file type: AqDrive. (line 95) -* -scsi_log reports SCSI commands: Scripting. (line 143) -* -session_log logs written sessions: Scripting. (line 134) -* -session_string composes session info line: Inquiry. (line 74) -* -setfacl sets ACL in ISO image: Manip. (line 68) -* -setfacl_list sets ACL in ISO image: Manip. (line 94) -* -setfacl_r sets ACL in ISO image: Manip. (line 92) -* -setfattr sets xattr in ISO image: Manip. (line 103) -* -setfattr_list sets xattr in ISO image: Manip. (line 120) -* -setfattr_r sets xattr in ISO image: Manip. (line 118) -* -set_filter applies filter to file: Filter. (line 58) -* -set_filter_r applies filter to file tree: Filter. (line 84) -* -show_stream shows data source and filters: Navigate. (line 151) -* -show_stream_r shows data source and filters: Navigate. (line 164) -* -sh_style_result makes results look more like shell: Scripting. - (line 61) -* -signal_handling controls handling of system signals: Exception. - (line 66) -* -sleep waits for a given time span: Scripting. (line 113) -* -speed set write speed: SetWrite. (line 307) -* -split_size enables large file splitting: SetInsert. (line 145) -* -status shows current settings: Scripting. (line 44) -* -status_history_max curbs -status history: Scripting. (line 52) -* -stdio_sync controls stdio buffer: SetWrite. (line 392) -* -stream_recording controls defect management: SetWrite. (line 325) -* -system_id sets system id: SetWrite. (line 205) -* -tell_media_space reports free space: Inquiry. (line 98) -* -temp_mem_limit curbs memory consumption: Scripting. (line 96) -* -toc shows list of sessions: Inquiry. (line 27) -* -toc_of shows list of sessions: Inquiry. (line 41) -* -truncate_overwritable activates older session: Writing. (line 167) -* -uid sets global ownership: SetWrite. (line 290) -* -update inserts path if different: Insert. (line 100) -* -update_l inserts paths if different: Insert. (line 120) -* -update_l inserts paths if different <1>: Insert. (line 128) -* -update_li inserts paths if different: Insert. (line 124) -* -update_r inserts paths if different: Insert. (line 110) -* -use_immed_bit controls use of Immed bit: SetWrite. (line 380) -* -use_readline enables readline for dialog: DialogCtl. (line 26) -* -version prints help text: Scripting. (line 22) -* -volid sets volume id: SetWrite. (line 168) -* -volset_id sets volume set id: SetWrite. (line 188) -* -volume_date sets volume timestamp: SetWrite. (line 211) -* -write_type chooses TAO or SAO/DAO: SetWrite. (line 423) -* -x enables automatic execution order of arguments: ArgSort. (line 16) -* -xattr controls handling of xattr (EA): Loading. (line 172) -* -zisofs controls zisofs production: SetWrite. (line 296) - - -File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top - -17 Alphabetic List of Concepts and Objects -****************************************** - -[index] -* Menu: - -* ACL, control handling, -acl: Loading. (line 165) -* ACL, set in ISO image, -setfacl: Manip. (line 68) -* ACL, set in ISO image, -setfacl_list: Manip. (line 94) -* ACL, set in ISO image, -setfacl_r: Manip. (line 92) -* ACL, show in ISO image, -getfacl: Navigate. (line 60) -* ACL, show in ISO image, -getfacl_r: Navigate. (line 66) -* ACL, _definition: Extras. (line 50) -* APM block size: Bootable. (line 414) -* APM, _definition: Extras. (line 42) -* Appendable media, _definition: Media. (line 38) -* Appended Filesystem Image, -append_partition: Bootable. (line 423) -* Appended partition, in APM: Bootable. (line 291) -* Appended partition, in MBR or GPT: Bootable. (line 284) -* Automatic execution order, of arguments, -x: ArgSort. (line 16) -* Backslash Interpretation, _definition: Processing. (line 53) -* Backup, enable fast incremental, -disk_dev_ino: Loading. (line 247) -* Backup, enable features, -for_backup: Loading. (line 215) -* Backup, scdbackup checksum tag, -scdbackup: Emulation. (line 179) -* Blank media, _definition: Media. (line 29) -* Blank, format, Immed bit, -use_immed_bit: SetWrite. (line 380) -* Blind growing, _definition: Methods. (line 41) -* Bootability, control, -boot_image: Bootable. (line 75) -* Bugs, reporting: Bugreport. (line 6) -* cdrecord, Emulation: Emulation. (line 120) -* Character Set, for input, -in_charset: Loading. (line 112) -* Character Set, for input/output, -charset: Charset. (line 54) -* Character Set, for output, -out_charset: SetWrite. (line 285) -* Character set, learn from image, -auto_charset: Loading. (line 117) -* Character Set, of terminal, -local_charset: Charset. (line 57) -* Character Set, _definition: Charset. (line 6) -* CHRP partition, _definition: Bootable. (line 296) -* Closed media, _definition: Media. (line 44) -* Comment, #: Scripting. (line 156) -* Control, signal handling, -signal_handling: Exception. (line 66) -* Create, new ISO image, _definition: Methods. (line 7) -* Cylinder alignment, _definition: Bootable. (line 340) -* Cylinder size, _definition: Bootable. (line 325) -* Damaged track and session, close, -close_damaged: Writing. (line 205) -* DEC Alpha SRM boot sector, production: Bootable. (line 400) -* Delete, from ISO image, -rm: Manip. (line 20) -* Delete, from ISO image, -rm_r: Manip. (line 26) -* Delete, ISO directory, -rmdir: Manip. (line 29) -* Device file locking, -drive_access: AqDrive. (line 72) -* Dialog, bring text into history, -history: Scripting. (line 42) -* Dialog, confirmation question, -reassure: DialogCtl. (line 29) -* Dialog, enable dialog mode, -dialog: DialogCtl. (line 7) -* Dialog, EOF resistant, -named_pipe_loop: Frontend. (line 119) -* Dialog, line editing, -use_readline: DialogCtl. (line 26) -* Dialog, terminal geometry, -page: DialogCtl. (line 18) -* Directories, copy, -cp_clone: Insert. (line 196) -* Directory, copy, -clone: Insert. (line 185) -* Directory, create, -mkdir: Insert. (line 177) -* Directory, delete, -rmdir: Manip. (line 29) -* disk_path, _definition: Insert. (line 6) -* Drive, accessability, -drive_class: AqDrive. (line 43) -* Drive, classify stdio, -early_stdio_test: Loading. (line 341) -* Drive, demand real MMC, -ban_stdio_write: Loading. (line 337) -* Drive, eject tray, -eject: Writing. (line 50) -* Drive, for input and output, -dev: AqDrive. (line 12) -* Drive, for input, -indev: AqDrive. (line 23) -* Drive, for output, -outdev: AqDrive. (line 29) -* Drive, get drive list, -devices: Inquiry. (line 7) -* Drive, get drive list, -device_links: Inquiry. (line 17) -* Drive, list supported media, -list_profiles: Writing. (line 163) -* Drive, reduce activity, -calm_drive: Loading. (line 327) -* Drive, report SCSI commands, -scsi_log: Scripting. (line 143) -* Drive, write and eject, -commit_eject: Writing. (line 53) -* Drive, _definition: Drives. (line 6) -* EA, _definition: Extras. (line 66) -* ECMA-119, _definition: Model. (line 6) -* EFI system partition, _definition: Bootable. (line 305) -* El Torito, _definition: Extras. (line 19) -* Emulation, -as: Emulation. (line 13) -* Emulation, .mkisofsrc, -read_mkisofsrc: Emulation. (line 155) -* Emulation, cdrecord, -as: Emulation. (line 120) -* Emulation, mkisofs, -as: Emulation. (line 17) -* Emulation, pacifier form, -pacifier: Emulation. (line 166) -* Examples: Examples. (line 6) -* extattr, _definition: Extras. (line 66) -* File content, copy, -concat: Restore. (line 125) -* File names, curb length, -file_name_limit: Loading. (line 267) -* File names, if neither Rock Ridge nor Joliet: Loading. (line 229) -* Filter, apply to file tree, -set_filter_r: Filter. (line 84) -* Filter, apply to file, -set_filter: Filter. (line 58) -* Filter, ban registration, -close_filter_list: Filter. (line 50) -* Filter, register, -external_filter: Filter. (line 20) -* Filter, show chain, -show_stream: Navigate. (line 151) -* Filter, show chains of tree, -show_stream_r: Navigate. (line 164) -* Filter, unregister, -unregister_filter: Filter. (line 47) -* Filter, zisofs parameters, -zisofs: SetWrite. (line 296) -* Filter, _definition: Filter. (line 6) -* Frontend program, start at pipes, -launch_frontend: Frontend. - (line 141) -* GPT, control GUID, -boot_image gpt_disk_guid=: Bootable. (line 225) -* GPT, _definition: Extras. (line 39) -* Group, global in ISO image, -gid: SetWrite. (line 293) -* Group, in ISO image, -chgrp: Manip. (line 49) -* Group, in ISO image, -chgrp_r: Manip. (line 53) -* Growing, _definition: Methods. (line 20) -* Hard links, control handling, -hardlinks: Loading. (line 128) -* HFS+ allocation block size: Bootable. (line 411) -* HFS+ serial number: Bootable. (line 408) -* hidden, set in ISO image, -hide: Manip. (line 177) -* HP-PA boot sector, production: Bootable. (line 383) -* Image reading, cache size, -data_cache_size: Loading. (line 353) -* Image, demand volume ID, -assert_volid: Loading. (line 105) -* Image, discard pending changes, -rollback: Writing. (line 9) -* Image, filesystem to load, -read_fs: Loading. (line 96) -* Image, override change status, -changes_pending: Writing. (line 12) -* Image, set abstract file name, -abstract_file: SetWrite. (line 250) -* Image, set application id, -application_id: SetWrite. (line 197) -* Image, set application iuse field, -application_use: SetWrite. - (line 272) -* Image, set biblio file name, -biblio_file: SetWrite. (line 256) -* Image, set copyright file name, -copyright_file: SetWrite. (line 245) -* Image, set preparer id, -preparer_id: SetWrite. (line 261) -* Image, set publisher id, -publisher: SetWrite. (line 192) -* Image, set system id, -system_id: SetWrite. (line 205) -* Image, set volume id, -volid: SetWrite. (line 168) -* Image, set volume set id, -volset_id: SetWrite. (line 188) -* Image, set volume timestamp, -volume_date: SetWrite. (line 211) -* Image, show Boot Catalog: Inquiry. (line 116) -* Image, show id strings, -pvd_info: Inquiry. (line 108) -* Image, show MBR, GPT, and alike, -pvd_info: Inquiry. (line 138) -* Image, _definition: Model. (line 9) -* Input Character Set, _definition: Charset. (line 25) -* Insert, enable overwriting, -overwrite: SetInsert. (line 131) -* Insert, file exclusion absolute, -not_paths: SetInsert. (line 53) -* Insert, file exclusion from file, -not_list: SetInsert. (line 63) -* Insert, file exclusion pattern, -not_leaf: SetInsert. (line 59) -* Insert, file exclusion, -not_mgt: SetInsert. (line 22) -* Insert, file exclusion, -quoted_not_list: SetInsert. (line 66) -* Insert, if different, -update: Insert. (line 100) -* Insert, if different, -update_l: Insert. (line 120) -* Insert, if different, -update_li: Insert. (line 124) -* Insert, if different, -update_lxi: Insert. (line 128) -* Insert, if different, -update_r: Insert. (line 110) -* Insert, large file splitting, -split_size: SetInsert. (line 145) -* Insert, limit data file size, -file_size_limit: SetInsert. (line 7) -* Insert, links or mount points, -follow: SetInsert. (line 69) -* Insert, meaning of = with -add, -pathspecs: SetInsert. (line 115) -* Insert, non-dashed arguments, -add_plainly: Insert. (line 68) -* Insert, path, -map: Insert. (line 89) -* Insert, path, -map_single: Insert. (line 93) -* Insert, paths from disk file, -map_l: Insert. (line 96) -* Insert, paths from disk file, -path_list: Insert. (line 81) -* Insert, paths from disk file, -quoted_path_list: Insert. (line 85) -* Insert, paths, -cpr: Insert. (line 164) -* Insert, pathspecs, -add: Insert. (line 44) -* Insert, piece of data file, -cut_out: Insert. (line 139) -* Interval reader for system area and partitions: Bootable. (line 32) -* ISO 9660, _definition: Model. (line 6) -* iso_rr_path, _definition: Insert. (line 7) -* Jigdo Template Extraction, -jigdo: Jigdo. (line 37) -* Jigdo Template Extraction, _definition: Jigdo. (line 6) -* LBA, _definition: Drives. (line 17) -* libisofs, fixed "now" time: Loading. (line 241) -* Linux device type, -scsi_dev_family: AqDrive. (line 95) -* List delimiter, _definition: Processing. (line 9) -* Local Character Set, _definition: Charset. (line 11) -* MBR bootable/active flag, enforce: Bootable. (line 351) -* MBR, set, -boot_image system_area=: Bootable. (line 200) -* MBR, _definition: Extras. (line 27) -* MD5, control handling, -md5: Loading. (line 184) -* Media, erase, -blank: Writing. (line 57) -* Media, format, -format: Writing. (line 87) -* Media, list formats, -list_formats: Writing. (line 128) -* Media, list write speeds, -list_speeds: Writing. (line 139) -* MIPS boot file, activation: Bootable. (line 362) -* mkisofs, Emulation: Emulation. (line 17) -* Modifying, _definition: Methods. (line 28) -* Multi-session media, _definition: Media. (line 7) -* Multi-session, _definition: Model. (line 18) -* Navigate, directory size in ISO image, -du: Navigate. (line 78) -* Navigate, directory size in ISO image, -dus: Navigate. (line 81) -* Navigate, directory size in on disk, -dusx: Navigate. (line 88) -* Navigate, directory size in on disk, -dux: Navigate. (line 84) -* Navigate, list disk files, -lsdlx: Navigate. (line 57) -* Navigate, list disk files, -lsdx: Navigate. (line 51) -* Navigate, list disk files, -lslx: Navigate. (line 54) -* Navigate, list disk files, -lsx: Navigate. (line 45) -* Navigate, list ISO files, -ls: Navigate. (line 24) -* Navigate, list ISO files, -lsd: Navigate. (line 31) -* Navigate, list ISO files, -lsdl: Navigate. (line 42) -* Navigate, list ISO files, -lsl: Navigate. (line 34) -* Navigate, set disk working directory, -cdx: Navigate. (line 15) -* Navigate, set ISO working directory, -cd: Navigate. (line 7) -* Navigate, tell disk working directory, -pwdx: Navigate. (line 21) -* Navigate, tell ISO working directory, -pwd: Navigate. (line 19) -* Next writeable address, -grow_blindly: AqDrive. (line 112) -* Older session, activate, -truncate_overwritable: Writing. (line 167) -* Output Character Set, _definition: Charset. (line 26) -* Overwritable media, _definition: Media. (line 14) -* Ownership, global in ISO image, -uid: SetWrite. (line 290) -* Ownership, in ISO image, -chown: Manip. (line 43) -* Ownership, in ISO image, -chown_r: Manip. (line 47) -* Partition offset, _definition: Bootable. (line 315) -* Partition table, _definition: Bootable. (line 265) -* Pathspec, _definition: SetInsert. (line 117) -* Pattern expansion, for disk paths, -disk_pattern: Insert. (line 34) -* Pattern expansion, for ISO paths, -iso_rr_pattern: Manip. (line 10) -* Pattern expansion, _definition: Processing. (line 25) -* Permissions, in ISO image, -chmod: Manip. (line 55) -* Permissions, in ISO image, -chmod_r: Manip. (line 66) -* PReP partition, _definition: Bootable. (line 300) -* Problems, reporting: Bugreport. (line 6) -* Process, consolidate text output, -pkt_output: Frontend. (line 7) -* Process, control abort on error, -abort_on: Exception. (line 27) -* Process, control exit value, -return_with: Exception. (line 38) -* Process, control verbosity, -report_about: Exception. (line 53) -* Process, disable startup files, -no_rc: Scripting. (line 7) -* Process, end program and write, -end: Scripting. (line 151) -* Process, end program, no writing, -rollback_end: Scripting. (line 154) -* Process, error workarounds, -error_behavior: Exception. (line 92) -* Process, log output channels to file, -logfile: Frontend. (line 19) -* Process, read command file, -options_from_file: Scripting. (line 12) -* Process, set synchronizing message, -mark: Frontend. (line 23) -* Program messages, perform operations, -msg_op: Frontend. (line 27) -* Program, backslash conversion, -backslash_codes: Scripting. (line 71) -* Program, curb memory, -temp_mem_limit: Scripting. (line 96) -* Program, end and write, -end: Scripting. (line 151) -* Program, end without writing, -rollback_end: Scripting. (line 154) -* Program, list extra features, -list_extras: Scripting. (line 24) -* Program, print help text, -help: Scripting. (line 19) -* Program, print help text, -prog_help: Frontend. (line 178) -* Program, print message text line, -print_info: Scripting. (line 104) -* Program, print result text line, -print: Scripting. (line 102) -* Program, print synchronizing text line, -print_mark: Scripting. - (line 106) -* Program, print version, -version: Scripting. (line 22) -* Program, prompt for enter key, -prompt: Scripting. (line 110) -* Program, replace --, -list_delimiter: Scripting. (line 55) -* Program, set name, -prog: Frontend. (line 176) -* Program, show current settings, -status: Scripting. (line 44) -* Program, status history, -status_history_max: Scripting. (line 52) -* Program, wait a time span, -sleep: Scripting. (line 113) -* Quoted input, _definition: Processing. (line 47) -* Read, set speed, -read_speed: Loading. (line 11) -* Recovery, retrieve blocks, -check_media: Verify. (line 21) -* Relocation directory, set name, -rr_reloc_dir: SetWrite. (line 150) -* Rename, in ISO image, -move: Manip. (line 31) -* Rename, in ISO image, -mv: Manip. (line 37) -* Restore, copy file into disk file, -paste_in: Restore. (line 121) -* Restore, copy file piece to disk, -extract_cut: Restore. (line 87) -* Restore, copy file to disk, -extract_single: Restore. (line 80) -* Restore, copy file tree to disk, -extract: Restore. (line 69) -* Restore, copy file trees to disk, -cp_rx: Restore. (line 110) -* Restore, copy file trees to disk, -cp_rx <1>: Restore. (line 118) -* Restore, copy files to disk, -cpax: Restore. (line 107) -* Restore, copy files to disk, -cpx: Restore. (line 96) -* Restore, copy files to disk, -extract_l: Restore. (line 83) -* Restore, enable ISO-to-disk, -osirrox: Restore. (line 18) -* Result layout, more shell-like, -sh_style_result: Scripting. - (line 61) -* Rock Ridge, _definition: Extras. (line 6) -* Session, altered start address, -displacement: Loading. (line 78) -* Session, info string, -session_string: Inquiry. (line 74) -* Session, issue mount command, -mount: Restore. (line 153) -* Session, log when written, -session_log: Scripting. (line 134) -* Session, mount command line, -mount_cmd: Inquiry. (line 49) -* Session, mount parameters, -mount_opts: Inquiry. (line 65) -* Session, select as input, -load: Loading. (line 54) -* Session, _definition: Model. (line 6) -* Sorting order, for -x, -list_arg_sorting: ArgSort. (line 26) -* SUN Disk Label, production: Bootable. (line 373) -* SUN SPARC boot images, activation: Bootable. (line 452) -* Symbolic link, create, -lns: Insert. (line 181) -* System area, _definition: Bootable. (line 200) -* Table-of-content, search sessions, -rom_toc_scan: Loading. (line 299) -* Table-of-content, show, -toc: Inquiry. (line 27) -* Timestamps, set in ISO image, -alter_date: Manip. (line 139) -* Timestamps, set in ISO image, -alter_date_r: Manip. (line 174) -* Tree, disk, traverse, -findx: Navigate. (line 91) -* Tree, ISO, traverse and alter, -find: CmdFind. (line 7) -* UTF-16, for Joliet paths, -compliance: SetWrite. (line 114) -* Verify, check blocks, -check_media: Verify. (line 21) -* Verify, compare ISO and disk file, -compare: Navigate. (line 131) -* Verify, compare ISO and disk tree, -compare_r: Navigate. (line 143) -* Verify, compare ISO and disk, -compare_l: Navigate. (line 147) -* Verify, file checksum, -check_md5: Verify. (line 184) -* Verify, file tree checksums, -check_md5_r: Verify. (line 198) -* Verify, preset -check_media, -check_media_defaults: Verify. (line 40) -* Write, block size, -dvd_obs: SetWrite. (line 336) -* Write, bootability, -boot_image: Bootable. (line 75) -* Write, buffer syncing, -stdio_sync: SetWrite. (line 392) -* Write, close media, -close: SetWrite. (line 407) -* Write, compliance to specs, -compliance: SetWrite. (line 62) -* Write, defect management, -stream_recording: SetWrite. (line 325) -* Write, disable Rock Ridge, -rockridge: SetWrite. (line 57) -* Write, drive buffer, -modesty_on_drive: SetWrite. (line 342) -* Write, enable HFS+, -hfsplus: SetWrite. (line 14) -* Write, enable Joliet, -joliet: SetWrite. (line 10) -* Write, fifo size, -fs: SetWrite. (line 402) -* Write, free space, -tell_media_space: Inquiry. (line 98) -* Write, log problematic disk files, -errfile_log: Scripting. (line 116) -* Write, log written sessions, -session_log: Scripting. (line 134) -* Write, padding image, -padding: SetWrite. (line 430) -* Write, pending ISO image, -commit: Writing. (line 27) -* Write, predict image size, -print_size: Inquiry. (line 86) -* Write, set speed, -speed: SetWrite. (line 307) -* Write, simulation, -dummy: SetWrite. (line 399) -* Write, TAO or SAO/DAO, -write_type: SetWrite. (line 423) -* xattr, control handling, -xattr: Loading. (line 172) -* xattr, set in ISO image, -setfattr: Manip. (line 103) -* xattr, set in ISO image, -setfattr_list: Manip. (line 120) -* xattr, set in ISO image, -setfattr_r: Manip. (line 118) -* xattr, show in ISO image, -getfattr: Navigate. (line 69) -* xattr, show in ISO image, -getfattr_r: Navigate. (line 75) -* xattr, _definition: Extras. (line 66) - - +Indirect: +xorriso.info-1: 415 +xorriso.info-2: 301310  Tag Table: +(Indirect) Node: Top415 Node: Overview1405 Node: Model3441 @@ -5988,41 +39,41 @@ Node: CmdFind88338 Node: Filter107267 Node: Writing111889 Node: SetWrite124144 -Node: Bootable149221 -Node: Jigdo176306 -Node: Charset181309 -Node: Exception184638 -Node: DialogCtl190767 -Node: Inquiry193369 -Node: Navigate202251 -Node: Verify210708 -Node: Restore221857 -Node: Emulation231023 -Node: Scripting241479 -Node: Frontend249262 -Node: Examples258888 -Node: ExDevices260066 -Node: ExCreate260727 -Node: ExDialog262027 -Node: ExGrowing263298 -Node: ExModifying264107 -Node: ExBootable264617 -Node: ExCharset265172 -Node: ExPseudo266068 -Node: ExCdrecord266995 -Node: ExMkisofs267315 -Node: ExGrowisofs269212 -Node: ExException270365 -Node: ExTime270823 -Node: ExIncBackup271281 -Node: ExRestore275307 -Node: ExRecovery276253 -Node: Files276825 -Node: Environ278159 -Node: Seealso278907 -Node: Bugreport279624 -Node: Legal280215 -Node: CommandIdx281227 -Node: ConceptIdx298843 +Node: Bootable151023 +Node: Jigdo178108 +Node: Charset183111 +Node: Exception186440 +Node: DialogCtl192569 +Node: Inquiry195171 +Node: Navigate204053 +Node: Verify212760 +Node: Restore223909 +Node: Emulation233075 +Node: Scripting243531 +Node: Frontend251314 +Node: Examples260940 +Node: ExDevices262118 +Node: ExCreate262779 +Node: ExDialog264079 +Node: ExGrowing265350 +Node: ExModifying266159 +Node: ExBootable266669 +Node: ExCharset267224 +Node: ExPseudo268120 +Node: ExCdrecord269047 +Node: ExMkisofs269367 +Node: ExGrowisofs271264 +Node: ExException272417 +Node: ExTime272875 +Node: ExIncBackup273333 +Node: ExRestore277359 +Node: ExRecovery278305 +Node: Files278877 +Node: Environ280211 +Node: Seealso280959 +Node: Bugreport281676 +Node: Legal282267 +Node: CommandIdx283279 +Node: ConceptIdx301310  End Tag Table diff --git a/xorriso/xorriso.texi b/xorriso/xorriso.texi index dde70de5..5441e787 100644 --- a/xorriso/xorriso.texi +++ b/xorriso/xorriso.texi @@ -50,7 +50,7 @@ @c man .\" First parameter, NAME, should be all caps @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection @c man .\" other parameters are allowed: see man(7), man(1) -@c man .TH XORRISO 1 "Version 1.5.3, Sep 30, 2020" +@c man .TH XORRISO 1 "Version 1.5.3, Oct 14, 2020" @c man .\" Please adjust this date whenever revising the manpage. @c man .\" @c man .\" Some roff macros, for reference: @@ -3603,23 +3603,61 @@ User id to be used for all files when the new ISO tree gets written to media. @cindex Group, global in ISO image, -gid Group id to be used for all files when the new ISO tree gets written to media. @c man .TP -@item -zisofs option[:options] +@item -zisofs parameter[:parameters] @kindex -zisofs controls zisofs production @cindex Filter, zisofs parameters, -zisofs Set global parameters for zisofs compression. This data format is recognized and transparently uncompressed by some Linux kernels. It is to be applied via command -set_filter with built-in filter "@minus{}@minus{}zisofs". +@* +Note: This command is only permitted while no --zisofs filters are applied to +any files. +@* Parameters are: @* "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow @* - "block_size="32k|64k|128k size of compression blocks + "block_size="32k|64k|128k sets the size of version 1 compression blocks. @* "by_magic=on" enables an expensive test at image generation time which checks files from disk whether they already are zisofs compressed, e.g. by program mkzftree. @* - "default" same as "level=6:block_size=32k:by_magic=off" + "version_2="off|as_needed|on enables the use of experimental version zisofs2 +which can encode files of size 4 GiB or larger. The Linux kernel (as of 5.9) +does not yet know this format and will complain like +@* + isofs: Unknown ZF compression algorithm: PZ +@* +The files will then appear in their compressed form with zisofs2 header, +block pointer list, and compressed data. +@* +zisofs2 is recognized by xorriso in files from loaded images and gets equipped +with --zisofs-decode filters, unless restrictions on the number of +block pointers prevent this. +@* +Mode "off" restricts compression to files smaller than 4 GiB uncompressed size. +Mode "as_needed" uses zisofs2 for larger files. Mode "on" uses zisofs2 for all +zisofs compressed files. +@* + "block_size_v2="32k|64k|128k|256k|512k|1m sets the size of compression blocks +for zisofs2. +@* + "max_bpt="1k|...|128g sets the limit for the overall allocated block pointer +memory. Block pointers occupy virtual memory while a file gets uncompressed +and while a file, which shall be compressed, waits for ISO filesystem creation. +@* +One pointer occupies 8 bytes of memory and governs block_size or block_size_v2 +uncompressed bytes. +I.e. with block size 128k, 1m of block pointer memory suffices for 16g of +uncompressed file size. +@* + "max_bpt_f="1k|...|128g sets the limit for the memory size of the block +pointer list of a single file. max_bpt_f is never larger than max_bpt. +If either is set to violate this rule, the other gets set to the same value. +@* + "default" same as "level=6:block_size=32k:by_magic=off: +version_2=off:block_size_v2=128k:max_bpt=256m:max_bpt_f=256m". @c man .TP @item -speed code|number[k|m|c|d|b] @kindex -speed set write speed @@ -5333,6 +5371,14 @@ Frequently used types are: cout:'disk_path offset count' for -cut_out files. @* extf:'filter_name' for external filters. +@* + --zisofs:algorithm:block_size for zisofs compression filters. +@* + --zisofs-decode:algorithm:block_size for zisofs uncompression filters. +@* + --gzip for internal gzip compression filters. +@* + --gunzip for internal gzip uncompression filters. @* Example: @* diff --git a/xorriso/xorriso_private.h b/xorriso/xorriso_private.h index 64819e9f..8ea13d40 100644 --- a/xorriso/xorriso_private.h +++ b/xorriso/xorriso_private.h @@ -2,7 +2,7 @@ /* Command line oriented batch and dialog tool which creates, loads, manipulates and burns ISO 9660 filesystem images. - Copyright 2007-2019 Thomas Schmitt, + Copyright 2007-2020 Thomas Schmitt, Provided under GPL version 2 or later. @@ -212,8 +212,8 @@ struct XorrisO { /* the global context of xorriso */ mode_t global_dir_mode; mode_t global_file_mode; - int do_tao; /* 1= Use TAO resp. Incremental - -1= Use SAO resp. DAO + int do_tao; /* 1= Use TAO or Incremental + -1= Use SAO or DAO 0= let libburn choose */ struct Xorriso_lsT *filters; @@ -224,6 +224,13 @@ struct XorrisO { /* the global context of xorriso */ int zisofs_block_size; int zisofs_block_size_default; int zisofs_by_magic; + int zisofs_v2_enabled; /* 0=no, 1=as_needed, 2=force */ + uint64_t zisofs_max_total_blocks; + uint64_t zisofs_max_total_blocks_default; + uint64_t zisofs_max_file_blocks; + uint64_t zisofs_max_file_blocks_default; + int zisofs_v2_block_size; + int zisofs_v2_block_size_default; int do_overwrite; /* 0=off, 1=on, 2=nondir */ int do_reassure; /* 0=off, 1=on, 2=tree */ diff --git a/xorriso/xorriso_timestamp.h b/xorriso/xorriso_timestamp.h index eb827d66..71b86072 100644 --- a/xorriso/xorriso_timestamp.h +++ b/xorriso/xorriso_timestamp.h @@ -1 +1 @@ -#define Xorriso_timestamP "2020.10.14.182119" +#define Xorriso_timestamP "2020.10.14.205904"