1XORRISO(1)                  General Commands Manual                 XORRISO(1)
2
3
4

NAME

6       xorriso  -  creates,  loads, manipulates and writes ISO 9660 filesystem
7       images with Rock Ridge extensions.
8

SYNOPSIS

10       xorriso [settings|actions]
11

DESCRIPTION

13       xorriso is a program which copies file  objects  from  POSIX  compliant
14       filesystems  into Rock Ridge enhanced ISO 9660 filesystems and performs
15       session-wise  manipulation  of  such  filesystems.  It  can  load   the
16       management information of existing ISO images and it writes the session
17       results to optical media or to filesystem objects.
18       Vice versa xorriso is able  to  copy  file  objects  out  of  ISO  9660
19       filesystems.
20
21       A  special property of xorriso is that it needs neither an external ISO
22       9660 formatter program nor an external burn program for CD, DVD  or  BD
23       but rather incorporates the libraries of libburnia-project.org .
24
25   Overview of features:
26       Operates on an existing ISO image or creates a new one.
27       Copies files from disk filesystem into the ISO image.
28       Copies files from ISO image to disk filesystem (see osirrox).
29       Renames or deletes file objects in the ISO image.
30       Changes file properties in the ISO image.
31       Updates ISO subtrees incrementally to match given disk subtrees.
32       Writes  result  either  as completely new image or as add-on session to
33       optical media or filesystem objects.
34       Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
35       Can perform multi-session tasks as emulation of mkisofs and cdrecord.
36       Can record and restore hard links and ACL.
37       Content may get zisofs compressed or filtered by external processes.
38       Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
39       Can check media for damages and copy readable blocks to disk.
40       Can attach MD5 checksums to each data file and the whole session.
41       Scans for optical drives, blanks re-useable optical media.
42       Reads its instructions from command line arguments, dialog, and files.
43       Provides navigation commands for interactive ISO image manipulation.
44       Adjustable thresholds for abort, exit value, and problem reporting.
45
46       Note that xorriso does not write audio CDs and that it does not produce
47       UDF filesystems which are specified for official video DVD or BD.
48
49   General information paragraphs:
50       Session model
51       Media types and states
52       Creating, Growing, Modifying, Blind Growing
53       Libburn drives
54       Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
55       Command processing
56       Dialog, Readline, Result pager
57
58       Maybe you first want to have a look at section EXAMPLES near the end of
59       this text before reading the  next  few  hundred  lines  of  background
60       information.
61
62   Session model:
63       Unlike  other  filesystems, ISO 9660 (aka ECMA-119) is not intended for
64       read-write operation but rather for being generated in a  single  sweep
65       and being written to media as a session.
66       The data content of the session is called filesystem image.
67
68       The  written  image in its session can then be mounted by the operating
69       system for being used read-only. GNU/Linux is able to mount ISO  images
70       from  block  devices, which may represent optical media, other media or
71       via a loop device even from regular  disk  files.  FreeBSD  mounts  ISO
72       images from devices that represent arbitrary media or from regular disk
73       files.
74
75       This session usage model has been extended on CD media by  the  concept
76       of multi-session , which adds information to the CD and gives the mount
77       programs of the operating systems the addresses of the entry points  of
78       each   session.  The  mount  programs  recognize  block  devices  which
79       represent CD media and will by default mount  the  image  in  the  last
80       session.
81       This  session  usually contains an updated directory tree for the whole
82       medium which governs the data contents in all recorded sessions.  So in
83       the  view  of  the  mount  program  all sessions of a particular medium
84       together form a single filesystem image.
85       Adding a session to an existing ISO image is in this text  referred  as
86       growing.
87       The multi-session model of the MMC standard does not apply to all media
88       types. But program growisofs by Andy Polyakov showed how to extend this
89       functionality  to  overwriteable  media or disk files which carry valid
90       ISO 9660 filesystems.
91
92       xorriso provides growing as well as an own method named modifying which
93       produces  a  completely  new  ISO  image  from  the  old  one  and  the
94       modifications.   See  paragraph  Creating,  Growing,  Modifying,  Blind
95       Growing below.
96
97       xorriso  adopts  the  concept  of  multi-session  by  loading  an image
98       directory tree if present, by offering  to  manipulate  it  by  several
99       actions, and by writing the new image to the target medium.
100       The  first  session  of  a  xorriso run begins by the definition of the
101       input drive with the ISO image or by the definition of an output drive.
102       The  session  ends by command -commit which triggers writing. A -commit
103       is done automatically when the program ends regularly.
104
105       After -commit a new session begins with  the  freshly  written  one  as
106       input.   A new input drive can only be chosen as long as the loaded ISO
107       image was not altered. Pending alteration can  be  revoked  by  command
108       -rollback.
109
110       Writing  a  session  to  the target is supposed to be very expensive in
111       terms of time and of consumed space on appendable or write-once  media.
112       Therefore  all  intended manipulations of a particular ISO image should
113       be done in a single session. But in principle it is possible  to  store
114       intermediate states and to continue with image manipulations.
115
116   Media types and states:
117       There are two families of media in the MMC standard:
118       Multi-session  media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and
119       unformatted DVD-RW. These  media  provide  a  table  of  content  which
120       describes their existing sessions. See command -toc.
121       Similar  to  multi-session  media  are  DVD-R  DL and minimally blanked
122       DVD-RW.  They record only a single session of which the  size  must  be
123       known  in advance.  xorriso will write onto them only if command -close
124       is set to "on".
125       Overwriteable media are DVD-RAM, DVD+RW, BD-RE, and  formatted  DVD-RW.
126       They  offer  random  write  access but do not provide information about
127       their session history. If they contain one or more  ISO  9660  sessions
128       and  if  the  first  session  was  written  by xorriso, then a table of
129       content can be emulated. Else only a single  overall  session  will  be
130       visible.
131       DVD-RW  media  can  be  formatted  by -format "full".  They can be made
132       unformatted by -blank "deformat".
133       Regular files and block devices are  handled  as  overwriteable  media.
134       Pipes and other writeable file types are handled as blank multi-session
135       media.
136
137       These media can assume several states in  which  they  offer  different
138       capabilities.
139       Blank  media  can  be  written  from scratch. They contain no ISO image
140       suitable for xorriso.
141       Blank is the state of newly purchased optical media.  With  used  CD-RW
142       and   DVD-RW   it   can  be  achieved  by  action  -blank  "as_needed".
143       Overwriteable media are considered blank if they are  new  or  if  they
144       have been marked as blank by xorriso.  Action -blank "as_needed" can be
145       used to do this marking on overwriteable media, or to  apply  mandatory
146       formatting to new media if necessary.
147       Appendable   media   accept  further  sessions.  Either  they  are  MMC
148       multi-session media in appendable  state,  or  they  are  overwriteable
149       media which contain an ISO image suitable for xorriso.
150       Appendable  is  the  state  after writing a session with command -close
151       off.
152       Closed media cannot be written. They may contain an ISO image  suitable
153       for xorriso.
154       Closed  is  the state of DVD-ROM media and of multi-session media which
155       were written with command -close on. If the drive is read-only hardware
156       then it will probably show any media as closed CD-ROM or DVD-ROM.
157       Overwriteable  media  assume  this state in such read-only drives or if
158       they contain unrecognizable data in the first 32 data blocks.
159       Read-only drives may or may not show session histories of multi-session
160       media. Often only the first and the last session are visible. Sometimes
161       not even that. Command -rom_toc_scan might or might not  help  in  such
162       cases.
163
164   Creating, Growing, Modifying, Blind Growing:
165       A  new  empty  ISO image gets created if there is no input drive with a
166       valid ISO 9660 image when the first time an output  drive  is  defined.
167       This  is  achieved by command -dev on blank media or by command -outdev
168       on media in any state.
169       The new empty image  can  be  populated  with  directories  and  files.
170       Before  it can be written, the medium in the output drive must get into
171       blank state if it was not blank already.
172
173       If there is a input drive with a valid ISO image, then this image  gets
174       loaded as foundation for manipulations and extension. The constellation
175       of input and output drive determines which write method will  be  used.
176       They have quite different capabilities and constraints.
177
178       The method of growing adds new data to the existing data on the medium.
179       These data comprise of new file content and they override the  existing
180       ISO 9660 + Rock Ridge directory tree. It is possible to hide files from
181       previous sessions but they still exist on  the  medium  and  with  many
182       types  of  optical  media  it is quite easy to recover them by mounting
183       older sessions.
184       Growing is achieved by command -dev.
185
186       The write method of modifying produces compact filesystem  images  with
187       no outdated files or directory trees. Modifying can write its images to
188       target  media  which  are  completely  unsuitable   for   multi-session
189       operations.    E.g.    DVD-RW    which   were   treated   with   -blank
190       deformat_quickest, DVD-R DL, named pipes, character  devices,  sockets.
191       On  the  other  hand  modified sessions cannot be written to appendable
192       media but to blank media only.
193       So for this method one needs either two optical drives or has  to  work
194       with filesystem objects as source and/or target medium.
195       Modifying  takes place if input drive and output drive are not the same
196       and if command -grow_blindly is set to  its  default  "off".   This  is
197       achieved by commands -indev and -outdev.
198
199       If  command -grow_blindly is set to a non-negative number and if -indev
200       and -outdev are both set to different drives,  then  blind  growing  is
201       performed.  It  produces  an  add-on  session  which is ready for being
202       written to the given block address. This is the usage model of
203        mkisofs -M $indev -C $msc1,$msc2 -o $outdev
204       which gives much room for wrong parameter combinations and should  thus
205       only  be employed if a strict distinction between ISO formatter xorriso
206       and the burn program is desired. -C $msc1,$msc2 is equivalent to:
207        -load sbsector $msc1 -grow_blindly $msc2
208
209   Libburn drives:
210       Input drive, i.e. source of an existing or empty ISO image, can be  any
211       random access readable libburn drive: optical media with readable data,
212       blank optical media, regular files, block devices.
213       Output drive, i.e. target for writing, can be any libburn drive.   Some
214       drive  types  do not support the method of growing but only the methods
215       of modifying and blind growing. They all are suitable for newly created
216       images.
217
218       All  drive  file  objects  have  to  offer rw-permission to the user of
219       xorriso.  Even those which will not  be  useable  for  reading  an  ISO
220       image.
221       With  any type of drive object, the data are considered to be organized
222       in blocks of 2 KiB. Access happens in terms of  Logical  Block  Address
223       (LBA) which gives the number of a particular data block.
224
225       MMC  compliant (i.e. optical) drives on GNU/Linux usually get addressed
226       by the path of their block device or of their generic character device.
227       E.g.
228         -dev /dev/sr0
229         -dev /dev/hdc
230         -dev /dev/sg2
231       By  default  xorriso  will try to map the given address to /dev/hd* and
232       /dev/sr*.  The command -scsi_dev_family can redirect the  mapping  from
233       sr  to  scd  or  sg.   The  latter does not suffer from the concurrency
234       problems which plague /dev/sr of Linux kernels since version 3. But  it
235       does  not  yield  the  same  addresses which are used by mount(8) or by
236       open(2) for read(2).
237       On FreeBSD the device files have names like
238         -dev /dev/cd0
239       On NetBSD:
240         -dev /dev/rcd0d
241       On OpenSolaris:
242         -dev /dev/rdsk/c4t0d0s2
243       Get a list of accessible drives by command
244         -device_links
245       It might be necessary to do this as  superuser  in  order  to  see  all
246       drives and to then allow rw-access for the intended users.  Consider to
247       bundle the authorized users in a group like old "floppy".
248
249       Filesystem objects of nearly  any  type  can  be  addressed  by  prefix
250       "stdio:" and their path in the filesystem. E.g.:
251         -dev stdio:/dev/sdc
252       The  default  setting  of -drive_class allows the user to address files
253       outside the /dev tree without that prefix. E.g.:
254         -dev /tmp/pseudo_drive
255       If path leads to a regular file or to a block device then the  emulated
256       drive  is  random  access  readable  and  can be used for the method of
257       growing if it already contains a valid ISO 9660 image. Any  other  file
258       type  is  not  readable via "stdio:" and can only be used as target for
259       the method of  modifying  or  blind  growing.   Non-existing  paths  in
260       existing directories are handled as empty regular files.
261
262       A very special kind of pseudo drive are open file descriptors. They are
263       depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open).
264       Addresses  "-"  or  "stdio:/dev/fd/1"  depict  standard  output,  which
265       normally  is  the  output channel for result texts.  To prevent a fatal
266       intermingling of ISO image and text  messages,  all  result  texts  get
267       redirected  to  stderr  if  -*dev "-" or "stdio:/dev/fd/1" is among the
268       start arguments of the program.
269       Standard output is currently suitable  for  creating  one  session  per
270       program  run without dialog. Use in other situations is discouraged and
271       several restrictions apply:
272       It is not allowed to use standard output as pseudo drive if it was  not
273       among  the  start  arguments.  Do not try to fool this ban via backdoor
274       addresses to stdout.
275       If stdout is used as drive, then -use_readline is permanently disabled.
276       Use of backdoors can cause severe memory and/or tty corruption.
277
278       Be  aware  that  especially the superuser can write into any accessible
279       file or device by using its path with the "stdio:" prefix.  By  default
280       any  address in the /dev tree without prefix "stdio:" will work only if
281       it leads to a MMC drive.
282       One may use command -ban_stdio_write to surely prevent this risk and to
283       restrict drive usage to MMC drives.
284       One  may  prepend  "mmc:"  to  a  path to surely disallow any automatic
285       "stdio:".
286       By command -drive_class one may  ban  certain  paths  or  allow  access
287       without prefix "stdio:" to other paths.
288
289   Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
290       Rock Ridge is the name of a set of additional information which enhance
291       an ISO 9660 filesystem so that  it  can  represent  a  POSIX  compliant
292       filesystem  with  ownership,  access  permissions,  symbolic links, and
293       other attributes.
294       This is what xorriso uses for a decent representation of the disk files
295       within  the  ISO  image.  xorriso  produces  Rock  Ridge information by
296       default. It is strongly discouraged to disable this feature.
297
298       xorriso is  not  named  "porriso"  because  POSIX  only  guarantees  14
299       characters  of  filename  length.  It  is  the  X/Open System Interface
300       standard XSI which demands a file name length of up to  255  characters
301       and paths of up to 1024 characters. Rock Ridge fulfills this demand.
302
303       An  El Torito boot record points the BIOS bootstrapping facility to one
304       or more boot images, which are binary program files stored in  the  ISO
305       image.   The  content of the boot image files is not in the scope of El
306       Torito.
307       Most bootable GNU/Linux CDs are equipped with  ISOLINUX  or  GRUB  boot
308       images.   xorriso  is  able  to  create or maintain an El Torito object
309       which  makes  such  an  image  bootable.  For   details   see   command
310       -boot_image.
311       It  is  possible  to  make  ISO images bootable from USB stick or other
312       hard-disk-like media.  Several  options  install  a  MBR  (Master  Boot
313       Record),  It  may  get  adjusted according to the needs of the intended
314       boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX.  A
315       MBR  contains  boot  code  and  a  partition  table.   The new MBR of a
316       follow-up session can get in effect only on overwriteable media.
317       MBR is read by PC-BIOS when booting from USB stick or hard disk, and by
318       PowerPC  CHRP  or  PReP  when booting.  An MBR partition with type 0xee
319       indicates the presence of GPT.
320       Emulation -as mkisofs supports the example options out of the  ISOLINUX
321       wiki, the options used in GRUB script grub-mkrescue, and the example in
322       the FreeBSD AvgLiveCD wiki.
323       A GPT (GUID Partition Table) marks partitions in a more modern way.  It
324       is  read  by  EFI  when booting from USB stick or hard disk, and may be
325       used for finding and mounting a HFS+ partition inside the ISO image.
326       An APM (Apple Partition Map) marks the HFS+ partition.  It is  read  by
327       Macs for booting and for mounting.
328       MBR,  GPT and APM are combinable. APM occupies the first 8 bytes of MBR
329       boot code. All three do not hamper El Torito booting from CDROM.
330       There is support for further facilities: MIPS Big  Endian  (SGI),  MIPS
331       Little  Endian  (DEC),  SUN  SPARC,  HP-PA.   Those  are  mutually  not
332       combinable and also not combinable with MBR, GPT, or APM.
333
334       ACL are an advanced way  of  controlling  access  permissions  to  file
335       objects.  Neither ISO 9660 nor Rock Ridge specify a way to record ACLs.
336       So libisofs has introduced a standard conformant extension  named  AAIP
337       for that purpose.  It uses this extension if enabled by command -acl.
338       AAIP  enhanced  images  are  supposed to be mountable normally, but one
339       cannot expect that the mounted filesystem will  show  and  respect  the
340       ACLs.   For  now,  only xorriso is able to retrieve those ACLs.  It can
341       bring them into effect when files get restored to an ACL  enabled  file
342       system or it can print them in a format suitable for tool setfacl.
343       Files  with ACL show as group permissions the setting of entry "mask::"
344       if that entry exists. Nevertheless the  non-listed  group  members  get
345       handled  according  to  entry "group::". When removing ACL from a file,
346       xorriso brings "group::" into effect.
347       Recording and restoring of ACLs from and to local files works currently
348       only on GNU/Linux and FreeBSD.
349
350       xattr  (aka  EA,  or  extattr) are pairs of name and value which can be
351       attached to file objects. AAIP is able to represent  them  and  xorriso
352       can record and restore them.
353       But  be  aware  that  pairs  with  names of non-user namespaces are not
354       necessarily portable between operating systems  and  not  even  between
355       filesystems.   Only  those  which  begin with "user.", like "user.x" or
356       "user.whatever", can unconditionally be expected to be  appropriate  on
357       other   machines  and  disks.   Processing  of  other  xattr  may  need
358       administrator privileges.
359       Name has to be a 0 terminated string.  Value may be any array of  bytes
360       which does not exceed the size of 4095 bytes.  xattr processing happens
361       only if it is enabled by command -xattr.
362       As with ACL, currently only xorriso is able to retrieve xattr from AAIP
363       enhanced  images,  to restore them to xattr capable file systems, or to
364       print them.
365       Recording and  restoring  of  xattr  from  and  to  local  files  works
366       currently  only  on  GNU/Linux  and  FreeBSD,  where  they are known as
367       extattr.
368
369   Command processing:
370       Commands are either actions which happen immediately or settings  which
371       influence following actions. So their sequence does matter, unless they
372       are given as program arguments and command -x is among them.
373       Commands consist of a command word, followed by zero or more  parameter
374       words.  If the list of parameter words is of variable length (indicated
375       by "[...]" or "[***]") then it must be terminated by  either  the  list
376       delimiter,  occur  at the end of the argument list, or occur at the end
377       of an input line.
378
379       At program start the list delimiter is the string "--".   This  may  be
380       changed  with  the  -list_delimiter  command  in order to allow "--" as
381       parameter in a variable length list.  However, it is advised  to  reset
382       the delimiter to "--" immediately afterwards.
383       For  brevity  the  list  delimiter  is referred as "--" throughout this
384       text.
385       The list  delimiter  is  silently  ignored  if  it  appears  after  the
386       parameters  of  a  command  with  a fixed list length. It is handled as
387       normal text if it appears among the parameters of such a command.
388
389       Pattern expansion converts a list of  pattern  words  into  a  list  of
390       existing file addresses.  Unmatched pattern words will appear unaltered
391       in that result list.
392       Pattern matching supports the usual  shell  parser  wildcards  '*'  '?'
393       '[xyz]'  and  respects  '/'  as  the  path separator, which may only be
394       matched literally.
395       Pattern expansion is a property of some particular commands and  not  a
396       general  feature.  It  is  controlled  by  commands -iso_rr_pattern and
397       -disk_pattern.  Commands which use pattern expansion all have  variable
398       parameter lists which are specified in this text by "[***]" rather than
399       "[...]".
400       Some other commands perform pattern matching unconditionally.
401
402       Command and parameter words are either read from the program arguments,
403       where  one argument is one word, or from quoted input lines where words
404       are recognized similar to the quotation rules of a shell parser.
405       xorriso is not a shell, although it might appear so at  first  glimpse.
406       Be  aware  that  the interaction of quotation marks and pattern symbols
407       like "*" differs from the usual shell parsers. In xorriso, a  quotation
408       mark does not make a pattern symbol literal.
409
410       Quoted input converts whitespace-separated text into words.  The double
411       quotation mark " and the single quotation mark ' can be used to enclose
412       whitespace  and  make  it part of words (e.g. of file names). Each mark
413       type can enclose the marks of the other type. A  trailing  backslash  \
414       outside quotations or an open quotation cause the next input line to be
415       appended.
416       Quoted input accepts any 8-bit character except NUL (0) as the  content
417       of  the  quotes.   Nevertheless  it  can  be cumbersome for the user to
418       produce those characters directly. Therefore quoted input  and  program
419       arguments  offer  optional Backslash Interpretation which can represent
420       all 8-bit characters except NUL (0) via backslash codes as in $'...' of
421       bash.
422       This is not enabled by default. See command -backslash_codes.
423
424       When  the  program  starts  then it first looks for argument -no_rc. If
425       this is not present then it looks for its startup files and reads their
426       content  as  command  input  lines.  Then  it  interprets  the  program
427       arguments as commands and parameters. Finally it enters dialog mode  if
428       command -dialog "on" has been executed by this point.
429
430       The  program  ends  either  by  command  -end, or by the end of program
431       arguments if dialog mode has not been enabled at that point,  or  by  a
432       problem event which triggers the threshold of command -abort_on.
433
434   Dialog, Readline, Result pager:
435       Dialog  mode prompts for a quoted input line, parses it into words, and
436       performs them as commands with their parameters. It provides  assisting
437       services to make dialog more comfortable.
438
439       Readline  is an enhancement for the input line. You may already know it
440       from the bash shell. Whether it is available in xorriso depends on  the
441       availability of package readline-dev at the time when xorriso was built
442       from its sourcecode.
443       Readline lets the user move the cursor over the text  in  the  line  by
444       help of the Left and the Right arrow keys.  Text may be inserted at the
445       cursor position. The Delete key removes the character under the cursor.
446       Up  and  Down arrow keys navigate through the history of previous input
447       lines.
448       See man readline for more info about libreadline.
449
450       Command -page activates a built-in  result  text  pager  which  may  be
451       convenient  in dialog mode. After an action has output the given number
452       of terminal lines, the pager prompts the user for a line of input.
453       An empty line lets xorriso resume work until the next page is output.
454       The single character "@" disables paging for the current action.
455       "@@@", "x", "q", "X", or "Q" request that the current action aborts and
456       suppress further result output.
457       Any  other  line  input  will  be  interpreted  as new dialog line. The
458       current action is requested to abort. Afterwards,  the  input  line  is
459       executed.
460
461       Some actions apply paging to their info output, too.
462       The  request  to  abort may or may not be obeyed by the current action.
463       All actions try to abort as soon as possible.
464

OPTIONS

466       All command words are shown with a leading dash although this  dash  is
467       not  mandatory  for  the  command to be recognized. Nevertheless within
468       command -as the dashes of the emulated commands are mandatory.
469       Normally any number of leading dashes is ignored with command words and
470       inner dashes are interpreted as underscores.
471
472       Execution order of program arguments:
473
474       By  default the program arguments of a xorriso run are interpreted as a
475       sequence of commands which get performed exactly in  the  given  order.
476       This  requires  the  user to write commands for desired settings before
477       the commands which shall be influenced by those settings.
478       Many other programs support program arguments in an arbitrary  ordering
479       and perform settings and actions in a sequence at their own discretion.
480       xorriso provides an option to enable such a behavior  at  the  cost  of
481       loss of expressivity.
482
483       -x     Enable  automatic  sorting  of program arguments into a sequence
484              that (most likely) is sensible.  This command may  be  given  at
485              any position among the commands which are handed over as program
486              arguments.
487              Note: It works only if it is given as program argument and  with
488              a  single  dash  (i.e. "-x"). It will not work in startup files,
489              nor with -options_from_file, nor in dialog mode, nor as "x"  and
490              finally  not  as  "--x".   It affects only the commands given as
491              program arguments.
492
493       -list_arg_sorting
494              List all xorriso commands in the order which applies if  command
495              -x is in effect.
496              This  list may also be helpful without -x for a user who ponders
497              over the sequence in which to put commands. Deviations from  the
498              listed sorting order may well make sense, though.
499
500       Acquiring source and target drive:
501
502       The  effect  of acquiring a drive may depend on several commands in the
503       next  paragraph  "Influencing  the  behavior  of  image  loading".   If
504       desired,  their  enabling  commands  have  to  be  performed before the
505       commands which acquire the drive.
506
507       -dev address
508              Set input and output drive to the same address and load  an  ISO
509              image  if it is present.  If there is no ISO image then create a
510              blank one.  Set the image expansion method to growing.
511              This is only allowed as long as no changes are  pending  in  the
512              currently loaded ISO image. If changes are pending, then one has
513              to perform -commit or -rollback first.
514              Special address string  "-"  means  standard  output,  to  which
515              several   restrictions   apply.  See  above  paragraph  "Libburn
516              drives".
517              An empty address string "" gives up the current  device  without
518              acquiring a new one.
519
520       -indev address
521              Set  input  drive  and load an ISO image if present.  If the new
522              input drive differs from -outdev then  switch  from  growing  to
523              modifying  or  to  blind  growing.  It depends on the setting of
524              -grow_blindly which of both gets activated.  The same rules  and
525              restrictions apply as with -dev.
526
527       -outdev address
528              Set  output  drive  and  if it differs from the input drive then
529              switch from growing to modifying or  to  blind  growing.  Unlike
530              -dev and -indev this action does not load a new ISO image. So it
531              can be performed even if there are pending changes.
532              -outdev can be performed without previous  -dev  or  -indev.  In
533              that case an empty ISO image with no changes pending is created.
534              It can either be populated by help of -map, -add  et.al.  or  it
535              can  be  discarded  silently  if  -dev  or  -indev are performed
536              afterwards.
537              Special address string  "-"  means  standard  output,  to  which
538              several   restrictions   apply.  See  above  paragraph  "Libburn
539              drives".
540              An empty address string "" gives up  the  current  output  drive
541              without  acquiring  a new one. No writing is possible without an
542              output drive.
543
544       -drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern
545              Add a drive path pattern to one of  the  safety  lists  or  make
546              those  lists  empty.   There  are  three lists defined which get
547              tested in the following sequence:
548              If a drive address path matches the  "harmless"  list  then  the
549              drive  will  be  accepted.  If  it  is not a MMC device then the
550              prefix "stdio:" will be prepended automatically.  This  list  is
551              empty by default.
552              Else  if  the path matches the "banned" list then the drive will
553              not be accepted by xorriso but rather lead to a  FAILURE  event.
554              This list is empty by default.
555              Else  if  the path matches the "caution" list and if it is not a
556              MMC device, then its address must have the prefix "stdio:" or it
557              will be rejected.  This list has by default one entry: "/dev".
558              If   a  drive  path  matches  no  list  then  it  is  considered
559              "harmless". By default these are all paths which  do  not  begin
560              with directory "/dev".
561              A  path  matches  a  list  if  one of its parent paths or itself
562              matches a list entry. Address prefix "stdio:" or "mmc:" will  be
563              ignored when testing for matches.
564              By   pseudo-class  "clear_list"  and  pseudo-patterns  "banned",
565              "caution", "harmless", or "all", the lists may be made empty.
566              E.g.: -drive_class clear_list banned
567              One will normally define the -drive_class lists in  one  of  the
568              xorriso Startup Files.
569              Note: This is not a security feature but rather a bumper for the
570              superuser to prevent inadverted mishaps. For  reliably  blocking
571              access  to  a device file you have to deny its rw-permissions in
572              the filesystem.
573
574       -drive_access "exclusive"|"shared":"unrestricted"|"readonly"
575              Control whether device file locking  mechanisms  shall  be  used
576              when  acquiring  a  drive,  and whether status or content of the
577              medium in the drive may be altered. Useful and most harmless are
578              the   setting   "shared:readonly"   and   the   default  setting
579              "exclusive:unrestricted".
580              "exclusive" enables tests and locks when acquiring the drive. It
581              depends  on  the  operating  system which locking mechanisms get
582              applied, if any. On GNU/Linux it is open(O_EXCL). On FreeBSD  it
583              is flock(LOCK_EX).
584              "shared"  disables the use of these mechanisms to become able to
585              acquire drives which are mounted, or opened by some process,  or
586              guarded by /dev/pktcdvd*.
587              "unrestricted" enables all technically appropriate operations on
588              an acquired drive. "shared:unrestricted" risks to get  own  burn
589              runs   spoiled  by  other  processes  or  to  vice  versa  spoil
590              activities of such processes.  So  use  "exclusive:unrestricted"
591              unless you know for sure that "shared" is safe.
592              "readonly" disables operations which might surprise a co-user of
593              the drive.  For -outdev these are formatting, blanking, writing,
594              ejecting.  For  -indev  this  is  ejecting.  Be  aware that even
595              reading and drive status inquiries can disturb an  ongoing  burn
596              run on CD-R[W] and DVD-R[W].
597
598       -scsi_dev_family "default"|"sr"|"scd"|"sg"
599              GNU/Linux specific:
600              By  default,  xorriso  tries  to  map  Linux  drive addresses to
601              /dev/sr* before they get opened for operating  the  drive.  This
602              coordinates  well  with  other use cases of optical drives, like
603              mount(8). But since year 2010 all /dev/sr* share a  global  lock
604              which allows only one drive to process an SCSI command while all
605              others have to wait  for  its  completion.   This  yields  awful
606              throughput  if  more  than  one  drive  is  writing  or  reading
607              simultaneously.  The global lock is not applied to device  files
608              /dev/sg*  and also not if the xorriso drive address is prepended
609              by "stdio:".
610              So  for  simultaneous  burn  runs  on  modern  GNU/Linux  it  is
611              advisable  to  perform  -scsi_dev_family  "sg"  before any -dev,
612              -indev, or -outdev. The drive addresses may then well  be  given
613              as  /dev/sr*  but  will  nevertheless  get  used as the matching
614              /dev/sg*.
615              If you decide so, consider to put  the  command  into  a  global
616              startup file like /etc/opt/xorriso/rc.
617
618       -grow_blindly "off"|predicted_nwa
619              If  predicted_nwa  is  a  non-negative number then perform blind
620              growing rather than modifying if -indev and -outdev are  set  to
621              different  drives.   "off" or "-1" switch to modifying, which is
622              the default.
623              predicted_nwa is the block address where the add-on  session  of
624              blind  growing  will finally end up. It is the responsibility of
625              the user to ensure this final position and the presence  of  the
626              older sessions. Else the overall ISO image will not be mountable
627              or will produce read errors when accessing file content. xorriso
628              will write the session to the address as obtained from examining
629              -outdev and not necessarily to predicted_nwa.
630              During a run of blind growing,  the  input  drive  is  given  up
631              before  output begins. The output drive is given up when writing
632              is done.
633
634       Influencing the behavior of image loading:
635
636       The following commands should normally be performed before  loading  an
637       image  by  acquiring  an  input drive. In rare cases it is desirable to
638       activate them only after image loading.
639
640       -read_speed code|number[k|m|c|d|b]
641              Set the speed for reading. Default is "none",  which  avoids  to
642              send a speed setting command to the drive before reading begins.
643              Further special speed codes are:
644              "max" (or "0") selects maximum speed as announced by the drive.
645              "min" (or "-1") selects minimum speed as announced by the drive.
646              Speed  can  be  given in media dependent numbers or as a desired
647              throughput per second in MMC compliant kB (= 1000) or MB (= 1000
648              kB).  Media  x-speed factor can be set explicitly by "c" for CD,
649              "d" for DVD, "b" for BD, "x" is optional.
650              Example speeds:
651               706k = 706kB/s = 4c = 4xCD
652               5540k = 5540kB/s = 4d = 4xDVD
653              If there is no hint about the  speed  unit  attached,  then  the
654              medium in the -indev will decide. Default unit is CD = 176.4k.
655              Depending  on  the  drive,  the  reported  read  speeds  can  be
656              deceivingly low or high. Therefore "min"  cannot  become  higher
657              than  1x  speed  of  the  involved medium type. Read speed "max"
658              cannot become lower than 52xCD, 24xDVD, or 20xBD,  depending  on
659              the medium type.
660              MMC drives usually activate their own idea of speed and take the
661              speed value given by the burn program only as hint for their own
662              decision.
663
664       -load entity id
665              Load  a  particular (possibly outdated) ISO session from -dev or
666              -indev.  Usually all available sessions are shown  with  command
667              -toc.
668              entity depicts the kind of addressing. id depicts the particular
669              address. The following entities are defined:
670              "auto" with any id addresses the last session in -toc.  This  is
671              the default.
672              "session"  with  id  being  a number as of a line "ISO session",
673              column "Idx".
674              "track" with id being a number as of a line "ISO track",  column
675              "Idx".
676              "lba" or "sbsector" with a number as of a line "ISO ...", column
677              "sbsector".
678              "volid" with a search pattern for a text as of a line "ISO ...",
679              column "Volume Id".
680              Addressing a non-existing entity or one which does not represent
681              an ISO image will either abandon -indev or at least  lead  to  a
682              blank image.
683              If  an  input drive is set at the moment when -load is executed,
684              then the addressed ISO image is loaded  immediately.  Else,  the
685              setting will be pending until the next -dev or -indev. After the
686              image has been loaded once, the setting is valid  for  -rollback
687              until next -dev or -indev, where it will be reset to "auto".
688
689       -displacement [-]lba
690              Compensate  a displacement of the image versus the start address
691              for which the image was prepared. This affects only  loading  of
692              ISO  images and reading of their files. The multi-session method
693              of growing is not allowed as long as -displacement is  non-zero.
694              I.e. -indev and -outdev must be different. The displacement gets
695              reset to 0 before the drive gets re-acquired after writing.
696              Examples:
697              If a track of a CD starts at block 123456 and gets copied  to  a
698              disk  file  where  it  begins  at block 0, then this copy can be
699              loaded with
700                -displacement -123456
701              If an ISO image was written onto  a  partition  with  offset  of
702              640000  blocks of 512 bytes, then it can be loaded from the base
703              device by
704                -load sbsector 160000 -displacement 160000
705              (If the partition start address is not divisible by 4, then  you
706              will have to employ a loop device instead.)
707              In  both  cases, the ISO sessions should be self contained, i.e.
708              not add-on sessions to an  ISO  image  outside  their  track  or
709              partition.
710
711       -read_fs "any"|"norock"|"nojoliet"|"ecma119"
712              Specify which kind of filesystem tree to load if present. If the
713              wish cannot be fulfilled, then ECMA-119  names  are  loaded  and
714              converted according to -ecma119_map.
715              "any"  first tries to read Rock Ridge. If not present, Joliet is
716              tried.
717              "norock" does not try Rock Ridge.
718              "nojoliet" does not try Joliet.
719              "ecma119" tries neither Rock Ridge nor Joliet.
720
721       -assert_volid pattern severity
722              Refuse to load ISO images with volume IDs which do not match the
723              given  search pattern. When refusing an image, give up the input
724              drive and issue an event of the given  severity  (like  FAILURE,
725              see -abort_on). An empty search pattern accepts any image.
726              This command does not hamper the creation of an empty image from
727              blank input media and does not discard an already loaded image.
728
729       -in_charset character_set_name
730              Set the character set from which  to  convert  file  names  when
731              loading  an  image.  See  paragraph  "Character  sets"  for more
732              explanations.  When loading the written image after -commit  the
733              setting of -out_charset will be copied to -in_charset.
734
735       -auto_charset "on"|"off"
736              Enable  or  disable  recording  and interpretation of the output
737              character set name in an  xattr  attribute  of  the  image  root
738              directory.  If  enabled  and if a recorded character set name is
739              found, then this  name  will  be  used  as  name  of  the  input
740              character set when reading an image.
741              Note  that the default output charset is the local character set
742              of the terminal where  xorriso  runs.  Before  attributing  this
743              local character set to the produced ISO image, check whether the
744              terminal properly displays all  intended  filenames,  especially
745              exotic national characters.
746
747       -hardlinks mode[:mode...]
748              Enable or disable loading and recording of hardlink relations.
749              In  default mode "off", iso_rr files lose their inode numbers at
750              image load time. Each iso_rr file  object  which  has  no  inode
751              number  at  image  generation  time  will get a new unique inode
752              number if -compliance is set to new_rr.
753              Mode "on" preserves inode numbers from the loaded image if  such
754              numbers  were  recorded.   When committing a session it searches
755              for families of iso_rr files which stem from the same disk file,
756              have  identical content filtering and have identical properties.
757              The family members all get the same inode number.  Whether these
758              numbers  are  respected  at  mount time depends on the operating
759              system.
760              Command -lsl displays hardlink counts if "lsl_count" is enabled.
761              This  can  slow  down the command substantially after changes to
762              the  ISO  image  have  been  made.  Therefore  the  default   is
763              "no_lsl_count".
764              Commands  -update and -update_r track splits and fusions of hard
765              links in filesystems which have stable device and inode numbers.
766              This  can cause automatic last minute changes before the session
767              gets written. Command -hardlinks "perform_update" may be used to
768              do  these  changes earlier, e.g. if you need to apply filters to
769              all updated files.
770              Mode "without_update" avoids hardlink processing  during  update
771              commands.   Use this if your filesystem situation does not allow
772              -disk_dev_ino "on".
773              xorriso commands which extract files from an ISO  image  try  to
774              hardlink  files with identical inode number. The normal scope of
775              this operation is from image load to image load. One may give up
776              the    accumulated    hard    link   addresses   by   -hardlinks
777              "discard_extract".
778              A large number of hardlink families may exhaust  -temp_mem_limit
779              if     not     -osirrox     "sort_lba_on"     and     -hardlinks
780              "cheap_sorted_extract" are both in effect. This  restricts  hard
781              linking  to  other  files  restored  by  the same single extract
782              command.  -hardlinks  "normal_extract"   re-enables   wide   and
783              expensive hardlink accumulation.
784
785       -acl "on"|"off"
786              Enable  or disable processing of ACLs.  If enabled, then xorriso
787              will obtain ACLs from disk file objects, store ACLs in  the  ISO
788              image  using  the  libisofs specific AAIP format, load AAIP data
789              from ISO images, test ACL during file  comparison,  and  restore
790              ACLs  to  disk  files when extracting them from ISO images.  See
791              also commands -getfacl, -setfacl.
792
793       -xattr "on"|"user"|"any"|"off"
794              Enable or disable processing of xattr attributes.   If  enabled,
795              then  xorriso  will  handle  xattr  similar  to  ACL.   See also
796              commands -getfattr, -setfattr and above paragraph about xattr.
797              Modes "on" and  "user"  read  and  write  only  attributes  from
798              namespace "user".
799              Mode  "any"  processes  attributes of all namespaces. This might
800              need administrator privileges, even if the  owner  of  the  disk
801              file tries to read or write the attributes.
802              Note that xattr from namespace "isofs." are never read from disk
803              or restored to disk. Further it is not possible to set them  via
804              xorriso xattr manipulation commands.
805
806       -md5 "on"|"all"|"off"|"load_check_off"
807              Enable  or  disable  processing of MD5 checksums for the overall
808              session and for each single data file. If  enabled  then  images
809              with checksum tags get loaded only if the tags of superblock and
810              directory tree match properly. The MD5 checksums of  data  files
811              and whole session get loaded from the image if there are any.
812              With  commands  -compare  and -update the recorded MD5 of a file
813              will be used to avoid content reading from the image.  Only  the
814              disk  file content will be read and compared with that MD5. This
815              can save much time if -disk_dev_ino "on" is not suitable.
816              At image generation time they are computed for each  file  which
817              gets  its  data  written  into the new session. The checksums of
818              files which have their data in older sessions  get  copied  into
819              the  new  session.  Superblock,  tree  and  whole  session get a
820              checksum tag each.
821              Mode "all"  will  additionally  check  during  image  generation
822              whether  the  checksum  of  a data file changed between the time
823              when its reading began and the time when it ended. This  implies
824              reading every file twice.
825              Mode  "load_check_off"  together  with  "on"  or "all" will load
826              recorded MD5 sums but not test the  recorded  checksum  tags  of
827              superblock  and  directory tree.  This is necessary if growisofs
828              was used as burn program, because  it  does  not  overwrite  the
829              superblock   checksum  tag  of  the  first  session.   Therefore
830              load_check_off is in effect when xorriso -as mkisofs  option  -M
831              is performed.
832              The test can be re-enabled by mode "load_check_on".
833              Checksums    can   be   exploited   via   commands   -check_md5,
834              -check_md5_r, via  find  actions  get_md5,  check_md5,  and  via
835              -check_media.
836
837       -for_backup
838              Enable  all  extra  features which help to produce or to restore
839              backups with highest fidelity of file properties. Currently this
840              is a shortcut for:
841              -hardlinks on -acl on -xattr any -md5 on
842              If  you  restore  a  backup with xattr from non-user namespaces,
843              then make sure that the target operating system  and  filesystem
844              know   what  these  attributes  mean.  Possibly  you  will  need
845              administrator privileges to record or restore  such  attributes.
846              At   recording  time,  xorriso  will  try  to  tolerate  missing
847              privileges and just record what is  readable.   But  at  restore
848              time, missing privileges will cause failure events.
849              Command   -xattr   "user"  after  command  -for_backup  excludes
850              non-user attributes from being recorded or restored.
851
852       -ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase"
853              Choose the conversion of file names from the loaded  session  if
854              neither  a  Rock  Ridge name nor a Joliet name was read from the
855              session.
856              Mode "stripped" is the default. It shows the names as  found  in
857              the ISO but removes trailing ";1" or ".;1" if present.
858              Mode   "unmapped"   shows   names   as  found  without  removing
859              characters.
860              Mode "lowercase" is like  "stripped"  but  also  maps  uppercase
861              letters  to  lowercase  letters.  This  is compatible to default
862              GNU/Linux mount behavior.
863              Mode "uppercase" is like "stripped" but maps  lowercase  letters
864              to   uppercase,  if  any  occur  despite  the  prescriptions  of
865              ECMA-119.
866
867       -iso_nowtime "dynamic"|timestring
868              Choose whether to use the current time ("dynamic")  or  a  fixed
869              time  point  for  timestamps  of  ISO  9660 nodes without a disk
870              source file and as default for superblock timestamps.
871              If a timestring is given, then it is used for  such  timestamps.
872              For the formats of timestrings see command -alter_date.
873
874       -disk_dev_ino "on"|"ino_only"|"off"
875              Enable  or  disable  processing  of recorded file identification
876              numbers (dev_t and ino_t). If enabled they are stored  as  xattr
877              and  can substantially accelerate file comparison. The root node
878              gets a global start timestamp. If during comparison a file  with
879              younger  timestamps  is  found  in  the  ISO  image,  then it is
880              suspected to have inconsistent content.
881              If device numbers and inode numbers of the disk filesystems  are
882              persistent  and  if  no  irregular  alterations of timestamps or
883              system clock happen,  then  potential  content  changes  can  be
884              detected  without  reading that content.  File content change is
885              assumed if any of mtime, ctime, device number  or  inode  number
886              have changed.
887              Mode  "ino_only"  replaces  the precondition that device numbers
888              are stable by the precondition that mount points in the compared
889              tree  always lead to the same filesystems. Use this if mode "on"
890              always sees all files changed.
891              The speed advantage appears  only  if  the  loaded  session  was
892              produced with -disk_dev_ino "on" too.
893              Note  that  -disk_dev_ino  "off"  is  totally  in effect only if
894              -hardlinks is "off", too.
895
896       -file_name_limit [+]number
897              Set the maximum permissible length for file names in  the  range
898              of  64  to 255.  Path components which are longer than the given
899              number  will  get  truncated  and  have  their  last  33   bytes
900              overwritten by a colon ':' and the hex representation of the MD5
901              of the first 4095 bytes of the whole oversized  name.  Potential
902              incomplete   UTF-8  characters  will  get  their  leading  bytes
903              replaced by '_'.
904              iso_rr_paths with the long components  will  still  be  able  to
905              access the file paths with truncated components.
906              If  -file_name_limit  is  executed while an ISO tree is present,
907              the file  names  in  the  ISO  tree  get  checked  for  existing
908              truncated   file  names  of  the  current  limit  and  for  name
909              collisions between newly truncated files and existing files.  In
910              both cases, the setting will be refused with a SORRY event.
911              One  may  lift  this  ban by prepending the character "+" to the
912              argument of -file_name_limit. Truncated filenames may  then  get
913              truncated   again,   invalidating   their  MD5  part.  Colliding
914              truncated names are made unique, consuming at least 9 more bytes
915              of the remaining name part.
916              If  writing  of xattr is enabled, then the length will be stored
917              in "isofs.nt" of the root directory.  If  reading  of  xattr  is
918              enabled  and "isofs.nt" is found, then the found length will get
919              into effect if  it  is  smaller  than  the  current  setting  of
920              -file_name_limit.
921              File  name  patterns  will only work if they match the truncated
922              name.  This might change in future.
923              Files  with   truncated   names   get   deleted   and   re-added
924              unconditionally  during -update and -update_r. This might change
925              in future.
926              Linux kernels up to at least 4.1 misrepresent  names  of  length
927              254  and  255.   If you expect such names in or under disk_paths
928              and plan to mount the ISO by such Linux kernels, consider to set
929              -file_name_limit  253.   Else  just  avoid names longer than 253
930              characters.
931
932       -rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"]
933              Read-only drives do not tell the actual media type but show  any
934              media  as  ROM  (e.g.  as  DVD-ROM).  The session history of MMC
935              multi-session media might be truncated to first and last session
936              or   even   be  completely  false.   (The  emulated  history  of
937              overwriteable media is not affected by this.)
938              To have in case of failure  a  chance  of  getting  the  session
939              history and especially the address of the last session, there is
940              a scan for ISO 9660 filesystem headers which might help but also
941              might  yield worse results than the drive's table of content. At
942              its end it can cause read attempts to invalid addresses and thus
943              ugly drive behavior.  Setting "on" enables that scan for alleged
944              read-only media.
945              Some operating systems are not able to  mount  the  most  recent
946              session  of multi-session DVD or BD. If on such a system xorriso
947              has no own MMC capabilities then it may still find that  session
948              from  a  scanned  table  of content. Setting "force" handles any
949              media like a ROM medium with setting "on".
950              On  the  other  hand  the  emulation  of  session   history   on
951              overwriteable  media can hamper reading of partly damaged media.
952              Setting  "off:emul_off"  disables   the   elsewise   trustworthy
953              table-of-content scan for those media.
954              The   table-of-content  scan  on  overwriteable  media  normally
955              searches only up to the end of the session that is pointed to by
956              the superblock at block 0.  Setting "on:emul_wide" lets the scan
957              continue up to the end of the medium.  This may be useful  after
958              copying  a  medium  with -check_media patch_lba0=on when not the
959              last session was loaded.
960
961       -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
962              Reduce drive noise until it is actually used again. Some  drives
963              stay  alert  for  substantial time after they have been used for
964              reading. This reduces  the  startup  time  for  the  next  drive
965              operation  but  can  be loud and waste energy if no i/o with the
966              drive is expected to happen soon.
967              Modes "in", "out", "all" immediately calm down -indev,  -outdev,
968              or  both,  respectively.  Mode "revoke" immediately alerts both.
969              Mode "on" causes -calm_drive to be performed automatically after
970              each -dev, -indev, and -outdev. Mode "off" disables this.
971
972       -ban_stdio_write
973              Allow for writing only the usage of MMC optical drives. Disallow
974              to write the result into files of nearly arbitrary  type.   Once
975              set, this command cannot be revoked.
976
977       -early_stdio_test "on"|"appendable_wo"|"off"
978              If  enabled  by  "on"  then  regular files and block devices get
979              tested for effective access permissions.  This  implies  to  try
980              opening  those  files  for  writing, which otherwise will happen
981              only later and only if actual writing is desired.
982              The test result is used for classifying  the  pseudo  drives  as
983              overwriteable,  read-only,  write-only, or uselessly empty. This
984              may lead to earlier detection of severe problems, and may  avoid
985              some less severe error events.
986              Mode  "appendable_wo"  is like "on" with the additional property
987              that non-empty  write-only  files  are  regarded  as  appendable
988              rather than blank.
989
990       -data_cache_size number_of_tiles blocks_per_tile
991              Set  the  size  and  granularity of the data cache which is used
992              when ISO images are loaded and when file content  is  read  from
993              ISO  images.  The  cache  consists  of several tiles, which each
994              consists of several blocks. A larger cache reduces the need  for
995              tiles being read multiple times. Larger tiles might additionally
996              improve the data throughput from the drive, but can be  wasteful
997              if the data are scattered over the medium.
998              Larger cache sizes help best with image loading from MMC drives.
999              They  are   an   inferior   alternative   to   -osirrox   option
1000              "sort_lba_on".
1001              blocks_per_tile  must  be  a power of 2. E.g. 16, 32, or 64. The
1002              overall cache size must not exceed 1 GiB.   The  default  values
1003              can be restored by parameter "default" instead of one or both of
1004              the numbers.  Currently the default is 32 tiles of 32 blocks = 2
1005              MiB.
1006
1007       Inserting files into ISO image:
1008
1009       The following commands expect file addresses of two kinds:
1010       disk_path is a path to an object in the local filesystem tree.
1011       iso_rr_path  is  the Rock Ridge name of a file object in the ISO image.
1012       If no Rock Ridge information is recorded in the loaded ISO image,  then
1013       you  will  see ISO 9660 names which are of limited length and character
1014       set.  If no Rock Ridge information shall be stored in an  emerging  ISO
1015       image,  then  their  names  will get mapped to such restricted ISO 9660
1016       (aka ECMA-119) names.
1017
1018       Note that in the ISO image you are as powerful as the superuser. Access
1019       permissions  of  the  existing  files in the image do not apply to your
1020       write operations. They are intended to be in effect with the  read-only
1021       mounted image.
1022
1023       If  the  iso_rr_path of a newly inserted file leads to an existing file
1024       object in the ISO image, then the following collision handling happens:
1025       If both objects are directories then they  get  merged  by  recursively
1026       inserting the subobjects from filesystem into ISO image.  If other file
1027       types collide then the setting of command -overwrite decides.
1028       Renaming of files has similar collision handling, but  directories  can
1029       only be replaced, not merged. Note that if the target directory exists,
1030       then -mv inserts the source objects into  this  directory  rather  than
1031       attempting  to  replace  it.  Command  -move,  on the other hand, would
1032       attempt to replace it.
1033
1034       The commands in this section alter the ISO  image  and  not  the  local
1035       filesystem.
1036
1037       -disk_pattern "on"|"ls"|"off"
1038              Set  the  pattern expansion mode for the disk_path parameters of
1039              several commands which support this feature.
1040              Setting "off" disables this feature for all commands  which  are
1041              marked  in  this  man page by "disk_path [***]" or "disk_pattern
1042              [***]".
1043              Setting "on" enables it for all those commands.
1044              Setting "ls" enables it only  for  those  which  are  marked  by
1045              "disk_pattern [***]".
1046              Default is "ls".
1047
1048       -add pathspec [...] | disk_path [***]
1049              Insert  the  given files or directory trees from filesystem into
1050              the ISO image.
1051              If -pathspecs is  set  to  "on"  or  "as_mkisofs"  then  pattern
1052              expansion  is  always  disabled  and character '=' has a special
1053              meaning. It separates the ISO image path from the disk path:
1054              iso_rr_path=disk_path
1055              Character '=' in the iso_rr_path must be escaped by '\' (i.e. as
1056              "\=").
1057              With -pathspecs "on", the character '\' must not be escaped. The
1058              character '=' in the disk_path must not be escaped.
1059              With -pathspecs "as_mkisofs", all characters '\' must be escaped
1060              in both, iso_rr_path and disk_path. The character '=' may or may
1061              not be escaped in the disk_path.
1062              If iso_rr_path does not begin with '/' then  -cd  is  prepended.
1063              If disk_path does not begin with '/' then -cdx is prepended.
1064              If  no  '='  is given then the word is used as both, iso_rr_path
1065              and disk path.  If in this case the word does not begin with '/'
1066              then  -cdx is prepended to the disk_path and -cd is prepended to
1067              the iso_rr_path.
1068              If -pathspecs is  set  to  "off"  then  -disk_pattern  expansion
1069              applies,  if  enabled.   The  resulting  words are used as both,
1070              iso_rr_path and disk path. Relative path words get prepended the
1071              setting  of  -cdx  to  disk_path  and  the  setting  of  -cd  to
1072              iso_rr_path.
1073
1074       -add_plainly mode
1075              If set to mode "unknown" then any command  word  that  does  not
1076              begin  with  "-"  and is not recognized as known command will be
1077              subject to a virtual -add command.  I.e.  it  will  be  used  as
1078              pathspec  or  as  disk_path and added to the image.  If enabled,
1079              -disk_pattern expansion applies to disk_paths.
1080              Mode "dashed" is similar to "unknown" but also adds unrecognized
1081              command words even if they begin with "-".
1082              Mode  "any"  announces that all further words are to be added as
1083              pathspecs or disk_paths. This does not work in dialog mode.
1084              Mode "none" is the default. It prevents  any  words  from  being
1085              understood  as  files  to  add,  if  they  are not parameters to
1086              appropriate commands.
1087
1088       -path_list disk_path
1089              Like -add but read the parameter words from  file  disk_path  or
1090              standard  input  if  disk_path  is  "-".   The list must contain
1091              exactly one pathspec or disk_path pattern per line.
1092
1093       -quoted_path_list disk_path
1094              Like -path_list but with quoted input reading rules.  Lines  get
1095              split  into  parameter words for -add. Whitespace outside quotes
1096              is discarded.
1097
1098       -map disk_path iso_rr_path
1099              Insert file object disk_path into the ISO image as  iso_rr_path.
1100              If  disk_path is a directory then its whole sub tree is inserted
1101              into the ISO image.
1102
1103       -map_single disk_path iso_rr_path
1104              Like -map, but if disk_path is a directory then its sub tree  is
1105              not inserted.
1106
1107       -map_l disk_prefix iso_rr_prefix disk_path [***]
1108              Perform  -map with each of the disk_path parameters. iso_rr_path
1109              will be composed from  disk_path  by  replacing  disk_prefix  by
1110              iso_rr_prefix.
1111
1112       -update disk_path iso_rr_path
1113              Compare  file  object disk_path with file object iso_rr_path. If
1114              they  do  not  match,   then   perform   the   necessary   image
1115              manipulations  to make iso_rr_path a matching copy of disk_path.
1116              By default this comparison will imply  lengthy  content  reading
1117              before  a  decision  is made. Commands -disk_dev_ino or -md5 may
1118              accelerate comparison if they were already in  effect  when  the
1119              loaded session was recorded.
1120              If  disk_path is a directory and iso_rr_path does not exist yet,
1121              then the whole subtree will be  inserted.  Else  only  directory
1122              attributes will be updated.
1123
1124       -update_r disk_path iso_rr_path
1125              Like  -update  but  working  recursively.  I.e. all file objects
1126              below both addresses get compared whether they have counterparts
1127              below  the other address and whether both counterparts match. If
1128              there is a mismatch then the necessary  update  manipulation  is
1129              done.
1130              Note  that  the comparison result may depend on command -follow.
1131              Its setting should always be the same as with the  first  adding
1132              of disk_path as iso_rr_path.
1133              If  iso_rr_path  does  not  exist  yet,  then  it gets added. If
1134              disk_path does not exist, then iso_rr_path gets deleted.
1135
1136       -update_l disk_prefix iso_rr_prefix disk_path [***]
1137              Perform  -update_r  with  each  of  the  disk_path   parameters.
1138              iso_rr_path   will  be  composed  from  disk_path  by  replacing
1139              disk_prefix by iso_rr_prefix.
1140
1141       -update_li iso_rr_prefix disk_prefix iso_rr_path [***]
1142              Perform -update_r  with  each  of  the  iso_rr_path  parameters.
1143              disk_path   will  be  composed  from  iso_rr_path  by  replacing
1144              iso_rr_prefix by disk_prefix.
1145
1146       -update_lxi disk_prefix iso_rr_prefix disk_path [***]
1147              Perform -update_r with each of the disk_path parameters and with
1148              iso_rr_paths  in  the  ISO filesystem which are derived from the
1149              disk_path   parameters   after   exchanging    disk_prefix    by
1150              iso_rr_prefix.  So,  other  than -update_l, this detects missing
1151              matches of disk_path and deletes the corresponding iso_rr_path.
1152              Note  that  relative  disk_paths  and  disk_path  patterns   are
1153              interpreted  as  sub paths of the current disk working directory
1154              -cdx. The corresponding iso_rr_paths are derived  by  exchanging
1155              disk_prefix  by  iso_rr_prefix before pattern expansion happens.
1156              The current -cdi directory has no influence.
1157
1158       -cut_out disk_path byte_offset byte_count iso_rr_path
1159              Map a byte interval of a regular disk file into a  regular  file
1160              in  the  ISO  image.   This may be necessary if the disk file is
1161              larger than a single medium, or if it  exceeds  the  traditional
1162              limit  of 2 GiB - 1 for old operating systems, or the limit of 4
1163              GiB - 1 for newer ones. Only the newest Linux  kernels  seem  to
1164              read properly files >= 4 GiB - 1.
1165              A  clumsy  remedy for this limit is to backup file pieces and to
1166              concatenate them at restore time. A well tested chopping size is
1167              2047m.   It  is  permissible to request a higher byte_count than
1168              available. The resulting file will be truncated to  the  correct
1169              size  of  a  final  piece.  To request a byte_offset higher than
1170              available yields no file in the ISO image  but  a  SORRY  event.
1171              E.g:
1172               -cut_out /my/disk/file 0 2047m \
1173               /file/part_1_of_3_at_0_with_2047m_of_5753194821 \
1174               -cut_out /my/disk/file 2047m 2047m \
1175               /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
1176               -cut_out /my/disk/file 4094m 2047m \
1177               /file/part_3_of_3_at_4094m_with_2047m_of_5753194821
1178              While  command  -split_size  is  set  larger  than 0, and if all
1179              pieces of a file reside in the same ISO directory with no  other
1180              files,  and  if  the  names  look  like  above,  then  their ISO
1181              directory will be recognized and handled like  a  regular  file.
1182              This   affects   commands  -compare*,  -update*,  and  overwrite
1183              situations.  See command -split_size for details.
1184
1185       -cpr disk_path [***] iso_rr_path
1186              Insert the given files or directory trees from  filesystem  into
1187              the ISO image.
1188              The  rules  for generating the ISO addresses are similar as with
1189              shell  command  cp  -r.   Nevertheless,   directories   of   the
1190              iso_rr_path  are  created  if  necessary.  Especially  a not yet
1191              existing iso_rr_path will be handled as  directory  if  multiple
1192              disk_paths   are   present.    The  leafnames  of  the  multiple
1193              disk_paths will be grafted under that directory as would be done
1194              with an existing directory.
1195              If a single disk_path is present then a non-existing iso_rr_path
1196              will get the same type as the disk_path.
1197              If a disk_path does not begin with '/' then -cdx  is  prepended.
1198              If  the  iso_rr_path  does  not  begin  with  '/'  then  -cd  is
1199              prepended.
1200
1201       -mkdir iso_rr_path [...]
1202              Create empty directories if they do not exist yet.  Existence as
1203              directory  generates  a  WARNING  event, existence as other file
1204              causes a FAILURE event.
1205
1206       -lns target_text iso_rr_path
1207              Create a symbolic link with address iso_rr_path which points  to
1208              target_text.  iso_rr_path may not exist yet.
1209              Hint: Command -clone produces the ISO equivalent of a hard link.
1210
1211       -clone iso_rr_path_original iso_rr_path_copy
1212              Create  a  copy of the ISO file object iso_rr_path_original with
1213              the new address iso_rr_path_copy. If the original is a directory
1214              then   copy   all   files   and   directories   underneath.   If
1215              iso_rr_path_original is a boot catalog file, then  it  gets  not
1216              copied but is silently ignored.
1217              The  copied  ISO  file  objects have the same attributes. Copied
1218              data files refer to the same content source as their  originals.
1219              The  copies  may  then  be  manipulated  independendly  of their
1220              originals.
1221              This   command   will   refuse   execution   if   the    address
1222              iso_rr_path_copy already exists in the ISO tree.
1223
1224       -cp_clone iso_rr_path_original [***] iso_rr_path_dest
1225              Create  copies  of  one or more ISO file objects as with command
1226              -clone.  In case of collision merge  directories  with  existing
1227              ones, but do not overwrite existing ISO file objects.
1228              The rules for generating the copy addresses are the same as with
1229              command -cpr (see above) or shell command cp -r. Other than with
1230              -cpr,  relative  iso_rr_path_original will get prepended the -cd
1231              path and not the -cdx path. Consider to -mkdir  iso_rr_path_dest
1232              before  -cp_clone  so  the  copy  address does not depend on the
1233              number of iso_rr_path_original parameters.
1234
1235       Settings for file insertion:
1236
1237       -file_size_limit value [value [...]] --
1238              Set the maximum permissible size for a  single  data  file.  The
1239              values  get summed up for the actual limit. If the only value is
1240              "off" then the file size is not limited by xorriso.  Default  is
1241              a limit of 100 extents, 4g -2k each:
1242               -file_size_limit 400g -200k --
1243              When  mounting  ISO  9660 filesystems, old operating systems can
1244              handle only files up to 2g -1 --. Newer ones are good up  to  4g
1245              -1  --.  You need quite a new Linux kernel to read correctly the
1246              final bytes of a file >= 4g if its size is not aligned  to  2048
1247              byte blocks.
1248              xorriso's  own  data  read  capabilities  are  not  affected  by
1249              operating system size limits.  Such  limits  apply  to  mounting
1250              only. Nevertheless, the target filesystem of an -extract must be
1251              able to take the file size.
1252
1253       -not_mgt code[:code[...]]
1254              Control the behavior of the exclusion lists.
1255              Exclusion processing happens before disk_paths get mapped to the
1256              ISO  image  and before disk files get compared with image files.
1257              The absolute disk path of the  source  is  matched  against  the
1258              -not_paths  list.   The  leafname  of  the  disk path is matched
1259              against the patterns in  the  -not_leaf  list.  If  a  match  is
1260              detected  then the disk path will not be regarded as an existing
1261              file and not be added to the ISO image.
1262              Several codes are defined.  The _on/_off settings persist  until
1263              they are revoked by their_off/_on counterparts.
1264              "erase"  empties  the lists which were accumulated by -not_paths
1265              and -not_leaf.
1266              "reset" is like "erase" but also re-installs default behavior.
1267              "off"  disables   exclusion   processing   temporarily   without
1268              invalidating the lists and settings.
1269              "on" re-enables exclusion processing.
1270              "param_off"  applies  exclusion  processing  only to paths below
1271              disk_path  parameter  of   commands.   I.e.   explicitly   given
1272              disk_paths are exempted from exclusion processing.
1273              "param_on" applies exclusion processing to command parameters as
1274              well as to files below such parameters.
1275              "subtree_off" with "param_on" excludes parameter paths  only  if
1276              they match a -not_paths item exactly.
1277              "subtree_on" additionally excludes parameter paths which lead to
1278              a file address below any -not_paths item.
1279              "ignore_off" treats excluded disk files as if they were missing.
1280              I.e.  they get reported with -compare and deleted from the image
1281              with -update.
1282              "ignore_on" keeps excluded files  out  of  -compare  or  -update
1283              activities.
1284
1285       -not_paths disk_path [***]
1286              Add the given paths to the list of excluded absolute disk paths.
1287              If a given path is relative, then the current -cdx is  prepended
1288              to form an absolute path.  Pattern matching, if enabled, happens
1289              at definition time and not when exclusion checks are made.
1290              (Do not forget to end the list of disk_paths by "--")
1291
1292       -not_leaf pattern
1293              Add  a  single  shell  parser  style  pattern  to  the  list  of
1294              exclusions for disk leafnames. These patterns are evaluated when
1295              the exclusion checks are made.
1296
1297       -not_list disk_path
1298              Read lines from  disk_path  and  use  each  of  them  either  as
1299              -not_paths  parameter,  if  they  contain  a  / character, or as
1300              -not_leaf pattern.
1301
1302       -quoted_not_list disk_path
1303              Like -not_list but with quoted input reading rules. Each word is
1304              handled as one parameter for -not_paths or -not_leaf.
1305
1306       -follow occasion[:occasion[...]]
1307              Enable  or  disable resolution of symbolic links and mountpoints
1308              under disk_paths. This applies to actions  -add,  -du*x,  -ls*x,
1309              -findx, -concat, and to -disk_pattern expansion.
1310              There are three kinds of follow decisison to be made:
1311              link  is  the hop from a symbolic link to its target file object
1312              for the purpose of reading. I.e. not for  command  -concat.   If
1313              enabled  then  symbolic  links  are handled as their target file
1314              objects, else symbolic links are handled as themselves.
1315              mount is the hop from  one  filesystem  to  another  subordinate
1316              filesystem.   If enabled then mountpoint directories are handled
1317              as any other directory, else mountpoints are  handled  as  empty
1318              directories   if   they   are   encountered  in  directory  tree
1319              traversals.
1320              concat is the hop from a symbolic link to its target file object
1321              for  the purpose of writing. I.e. for command -concat. This is a
1322              security risk !
1323              Less general than above occasions:
1324              pattern is mount and link hopping, but only during -disk_pattern
1325              expansion.
1326              param  is  link  hopping  for  parameter  words  (after eventual
1327              pattern expansion).  If enabled then -ls*x will  show  the  link
1328              targets  rather  than  the  links themselves. -du*x, -findx, and
1329              -add will process the link targets but not follow  links  in  an
1330              eventual  directory  tree  below  the  targets (unless "link" is
1331              enabled).
1332              Occasions can  be  combined  in  a  colon  separated  list.  All
1333              occasions  mentioned  in  the  list will then lead to a positive
1334              follow decision.
1335              off prevents any positive follow decision. Use it  if  no  other
1336              occasion applies.
1337              Shortcuts:
1338              default is equivalent to "pattern:mount:limit=100".
1339              on always decides positive. Equivalent to "link:mount:concat".
1340
1341              Not an occasion but an optional setting is:
1342              limit=<number>  which  sets  the maximum number of link hops.  A
1343              link hop consists of a sequence of symbolic links  and  a  final
1344              target  of  different  type.  Nevertheless  those hops can loop.
1345              Example:
1346                $ ln -s .. uploop
1347              Link hopping has a built-in loop detection which  stops  hopping
1348              at the first repetition of a link target. Then the repeated link
1349              is handled as itself and not as its target.  Regrettably one can
1350              construct  link networks which cause exponential workload before
1351              their loops get detected.  The number given  with  "limit="  can
1352              curb  this  workload  at  the  risk of truncating an intentional
1353              sequence of link hops.
1354
1355       -pathspecs "on"|"off"|"as_mkisofs"
1356              Control parameter interpretation with xorriso actions  -add  and
1357              -path_list.
1358              Mode "as_mkisofs" enables pathspecs of the form
1359              iso_rr_path=disk_path
1360              like with program mkisofs -graft-points.
1361              All  characters  '\'  must  be  escaped in both, iso_rr_path and
1362              disk_path.  The character '=' must be escaped in the iso_rr_path
1363              and  may  or  may  not  be  escaped in the disk_path.  This mode
1364              temporarily disables -disk_pattern expansion for command -add.
1365              Mode "on" does nearly the same. But '=' must only be escaped  in
1366              the iso_rr_path and '\' must not be escaped at all. This has the
1367              disadvantage that one cannot express an iso_rr_path  which  ends
1368              by '\'.
1369              Mode  "off"  disables  pathspecs  of  the form target=source and
1370              re-enables -disk_pattern expansion.
1371
1372       -overwrite "on"|"nondir"|"off"
1373              Allow or disallow overwriting of existing files in the ISO image
1374              by files with the same name.
1375              With   setting   "off",   name  collisions  with  at  least  one
1376              non-directory file  cause  FAILURE  events.  Collisions  of  two
1377              directories lead to merging of their file lists.
1378              With  setting  "nondir",  only directories are protected by such
1379              events, other existing file types get treated  with  -rm  before
1380              the  new file gets added.  Setting "on" enables automatic -rm_r.
1381              I.e. a non-directory can replace an existing directory  and  all
1382              its subordinates.
1383              If  restoring  of  files  is  enabled,  then  the overwrite rule
1384              applies to the target file objects on disk as well, but "on"  is
1385              downgraded to "nondir".
1386
1387       -split_size number["k"|"m"]
1388              Set the threshold for automatic splitting of regular files. Such
1389              splitting maps a large disk  file  onto  a  ISO  directory  with
1390              several  part files in it.  This is necessary if the size of the
1391              disk file exceeds -file_size_limit.  Older operating systems can
1392              handle  files  in  mounted ISO 9660 filesystems only if they are
1393              smaller than 2 GiB or in other cases 4 GiB.
1394              Default  is   0   which   will   exclude   files   larger   than
1395              -file_size_limit  by a FAILURE event.  A well tested -split_size
1396              is 2047m. Sizes above -file_size_limit are not permissible.
1397              While command -split_size is set larger than 0 such a  directory
1398              with  split  file  pieces  will be recognized and handled like a
1399              regular file by commands -compare* , -update*, and in  overwrite
1400              situations.  There are -osirrox parameters "concat_split_on" and
1401              "concat_split_off" which control the  handling  when  files  get
1402              restored to disk.
1403              In order to be recognizable, the names of the part files have to
1404              describe the splitting by 5 numbers:
1405               part_number,total_parts,byte_offset,byte_count,disk_file_size
1406              which are embedded in the following text form:
1407               part_#_of_#_at_#_with_#_of_#
1408              Scaling characters like "m" or "k" are taken into respect.   All
1409              digits  are  interpreted  as  decimal, even if leading zeros are
1410              present.
1411              E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
1412              No other files are allowed in the directory. All parts  have  to
1413              be  present  and  their  numbers  have  to  be  plausible.  E.g.
1414              byte_count  must  be  valid  as  -cut_out  parameter  and  their
1415              contents may not overlap.
1416
1417       File manipulations:
1418
1419       The  following  commands  manipulate files in the ISO image, regardless
1420       whether they stem from the loaded image or were newly inserted.
1421
1422       -iso_rr_pattern "on"|"ls"|"off"
1423              Set the pattern expansion mode for the iso_rr_path parameters of
1424              several commands which support this feature.
1425              Setting  "off" disables pattern expansion for all commands which
1426              are  marked  in  this  man  page  by  "iso_rr_path   [***]"   or
1427              "iso_rr_pattern [***]".
1428              Setting "on" enables it for all those commands.
1429              Setting  "ls"  enables  it  only  for  those which are marked by
1430              "iso_rr_pattern [***]".
1431              Default is "on".
1432
1433       -rm iso_rr_path [***]
1434              Delete the given files from the ISO image.
1435              Note: This does not free any space on the -indev medium, even if
1436              the deletion is committed to that same medium.
1437              The  image  size  will  shrink  if  the  image  is  written to a
1438              different medium in modification mode.
1439
1440       -rm_r iso_rr_path [***]
1441              Delete the given files or directory trees from  the  ISO  image.
1442              See also the note with command -rm.
1443
1444       -rmdir iso_rr_path [***]
1445              Delete empty directories.
1446
1447       -move iso_rr_path iso_rr_path
1448              Rename  the  file given by the first (origin) iso_rr_path to the
1449              second (destination) iso_rr_path.  Deviate from rules  of  shell
1450              command  mv by not moving the origin file underneath an existing
1451              destination directory. The origin file will rather replace  such
1452              a directory, if this is allowed by command -overwrite.
1453
1454       -mv iso_rr_path [***] iso_rr_path
1455              Rename  the  given  file  objects  in  the  ISO tree to the last
1456              parameter in the list. Use the same rules as with shell  command
1457              mv.
1458              If  pattern  expansion  is  enabled  and  if  the last parameter
1459              contains wildcard characters then  it  must  match  exactly  one
1460              existing  file address, or else the command fails with a FAILURE
1461              event.
1462
1463       -chown uid iso_rr_path [***]
1464              Set ownership of file objects in the ISO image. uid  may  either
1465              be a decimal number or the name of a user known to the operating
1466              system.
1467
1468       -chown_r uid iso_rr_path [***]
1469              Like -chown but affecting all files below eventual directories.
1470
1471       -chgrp gid iso_rr_path [***]
1472              Set group attribute of file objects in the ISO image.  gid   may
1473              either  be  a decimal number or the name of a group known to the
1474              operating system.
1475
1476       -chgrp_r gid iso_rr_path [***]
1477              Like -chgrp but affecting all files below eventual directories.
1478
1479       -chmod mode iso_rr_path [***]
1480              Equivalent to shell command chmod in the  ISO  image.   mode  is
1481              either  an  octal number beginning with "0" or a comma separated
1482              list of statements of the form [ugoa]*[+-=][rwxst]* .
1483              Like: go-rwx,u+rwx .
1484              Personalities: u=user, g=group, o=others, a=all
1485              Operators:  +  adds   given   permissions,   -   revokes   given
1486              permissions,  =  revokes  all  old permissions and then adds the
1487              given ones.
1488              Permissions:      r=read,      w=write,       x=execute|inspect,
1489              s=setuid|setgid, t=sticky bit
1490              For octal numbers see man 2 stat.
1491
1492       -chmod_r mode iso_rr_path [***]
1493              Like -chmod but affecting all files below eventual directories.
1494
1495       -setfacl acl_text iso_rr_path [***]
1496              Attach  the  given  ACL  to the given iso_rr_paths. If the files
1497              already have ACLs, then those get deleted before  the  new  ones
1498              get  into  effect.   If  acl_text is empty, or contains the text
1499              "clear" or the text "--remove-all", then the existing ACLs  will
1500              be  removed  and no new ones will be attached. Any other content
1501              of acl_text will be interpreted as a list of ACL entries. It may
1502              be  in the long multi-line format as put out by -getfacl but may
1503              also be abbreviated as follows:
1504              ACL entries are separated by comma or newline. If  an  entry  is
1505              empty  text  or begins with "#" then it will be ignored. A valid
1506              entry has to begin  by  a  letter  out  of  {ugom}  for  "user",
1507              "group",  "other",  "mask".  It has to contain two colons ":". A
1508              non-empty text between those ":" gives a user id  or  group  id.
1509              After  the second ":" there may be letters out of {rwx- #}.  The
1510              first three give read, write, or  execute  permission.   Letters
1511              "-",  "  " and TAB are ignored. "#" causes the rest of the entry
1512              to  be  ignored.  Letter  "X"  or  any  other  letters  are  not
1513              supported. Examples:
1514                g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
1515                group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-
1516              A  valid entry may be prefixed by "d", some following characters
1517              and ":".  This indicates that the entry goes  to  the  "default"
1518              ACL rather than to the "access" ACL. Example:
1519                u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
1520
1521       -setfacl_r acl_text iso_rr_path [***]
1522              Like   -setfacl   but   affecting   all   files  below  eventual
1523              directories.
1524
1525       -setfacl_list disk_path
1526              Read the output of -getfacl_r or shell command  getfacl  -R  and
1527              apply it to the iso_rr_paths as given in lines beginning with "#
1528              file:". This will change ownership, group and ACL of  the  given
1529              files.   If  disk_path  is "-" then lines are read from standard
1530              input. Line "@" ends the list, "@@@" aborts without changing the
1531              pending iso_rr_path.
1532              Since -getfacl and getfacl -R strip leading "/" from file paths,
1533              the setting of -cd does always matter.
1534
1535       -setfattr [-]name value iso_rr_path [***]
1536              Attach the given xattr pair of  name  and  value  to  the  given
1537              iso_rr_paths.   If  the  given name is prefixed by "-", then the
1538              pair with that name gets removed from the xattr list. If name is
1539              "--remove-all"  then  all  user  namespace  xattr  of  the given
1540              iso_rr_paths get deleted. In case of deletion, value must be  an
1541              empty text.
1542              Which  names  are  permissible depends on the setting of command
1543              -xattr.  "on" or "user" restricts them to namespace "user". I.e.
1544              a name has to look like "user.x" or "user.whatever".
1545              -xattr  setting  "any"  enables names from all namespaces except
1546              "isofs".
1547              Values and names undergo the normal input processing of xorriso.
1548              See  also  command  -backslash_codes.  Other  than  with command
1549              -setfattr_list,  the  byte  value  0  cannot  be  expressed  via
1550              -setfattr.
1551
1552       -setfattr_r [-]name value iso_rr_path [***]
1553              Like   -setfattr   but   affecting   all  files  below  eventual
1554              directories.
1555
1556       -setfattr_list disk_path
1557              Read the output format of -getfattr_r or shell command  getfattr
1558              -Rd and apply it to the iso_rr_paths as given in lines beginning
1559              with "# file:".  All previously existing xattr of the acceptable
1560              namespaces  will  be  deleted before the new xattr get attached.
1561              The set of acceptable names depends on the  setting  of  command
1562              -xattr.
1563              If disk_path is "-" then lines are read from standard input.
1564              Since  -getfattr  and  getfattr  -Rd strip leading "/" from file
1565              paths, the setting of -cd does always matter.
1566              Empty input lines and lines which begin by "#" will  be  ignored
1567              (except "# file:"). Line "@" ends the list, "@@@" aborts without
1568              changing the pending iso_rr_path. Other input  lines  must  have
1569              the form
1570                name="value"
1571              The  separator  "="  is not allowed in names.  Value may contain
1572              any kind of bytes. It must be  in  quotes.  Trailing  whitespace
1573              after  the  end  quote will be ignored. Non-printables bytes and
1574              quotes must be represented as \XYZ by  their  octal  8-bit  code
1575              XYZ.  Use code \000 for 0-bytes.
1576
1577       -alter_date type timestring iso_rr_path [***]
1578              Alter  the  date  entries of files in the ISO image. type may be
1579              one of the following:
1580              "a" sets access time, updates ctime.
1581              "m" sets modification time, updates ctime.
1582              "b" sets access time and modification time, updates ctime.
1583              "a-c", "m-c", and "b-c" set the times without updating ctime.
1584              "c" sets the ctime.
1585              timestring may be in the following  formats  (see  also  section
1586              EXAMPLES):
1587              As expected by program date:
1588               MMDDhhmm[[CC]YY][.ss]]
1589              As produced by program date:
1590               [Day] MMM DD hh:mm:ss [TZON] YYYY
1591              Relative times counted from current clock time:
1592               +|-Number["s"|"h"|"d"|"w"|"m"|"y"]
1593              where  "s"  means  seconds,  "h"  hours,  "d"  days,  "w" weeks,
1594              "m"=30d, "y"=365.25d plus 1d added to multiplication result.
1595              Absolute seconds counted from Jan 1 1970:
1596               =Number
1597              xorriso's own timestamps:
1598               YYYY.MM.DD[.hh[mm[ss]]]
1599              scdbackup timestamps:
1600               YYMMDD[.hhmm[ss]]
1601              where "A0" is year 2000, "B0" is 2010, etc.
1602              ECMA-119 volume timestamps:
1603               YYYYMMDDhhmmsscc
1604              These are normally given as GMT. The suffix "LOC"  causes  local
1605              timezone conversion. E.g. 2013010720574700, 2013010720574700LOC.
1606              The last two digits cc (centiseconds) will be ignored, but  must
1607              be present in order to make the format recognizable.
1608              Example:
1609                -alter_date m-c 2013.11.27.103951 /file1 /file2 --
1610              This  command  does  not persistently apply to the boot catalog,
1611              which  gets  fresh   timestamps   at   -commit   time.   Command
1612              -volume_date "uuid" can set this time value.
1613
1614       -alter_date_r type timestring iso_rr_path [***]
1615              Like   -alter_date   but  affecting  all  files  below  eventual
1616              directories.
1617
1618       -hide hide_state iso_rr_path [***]
1619              Prevent the names of the given files  from  showing  up  in  the
1620              directory  trees  of ISO 9660 and/or Joliet and/or HFS+ when the
1621              image gets written.  The data content of such hidden files  will
1622              be  included in the resulting image, even if they do not show up
1623              in any directory.  But you will need own means to find  nameless
1624              data in the image.
1625              Warning:  Data  which are hidden from the ISO 9660 tree will not
1626              be copied by the write method of modifying.
1627              Possible values of hide_state are: "iso_rr" for hiding from  ISO
1628              9660  tree,  "joliet"  for Joliet tree, "hfsplus" for HFS+, "on"
1629              for them all.  "off" means visibility in all directory trees.
1630              These values may be combined.  E.g.: joliet:hfsplus
1631              This command does not apply to the boot  catalog.   Rather  use:
1632              -boot_image "any" "cat_hidden=on"
1633
1634       Tree traversal command -find:
1635
1636       -find iso_rr_path [test [op] [test ...]] [-exec action [params]] --
1637              A restricted substitute for shell command find in the ISO image.
1638              It performs an action on  matching  file  objects  at  or  below
1639              iso_rr_path.
1640              If  not used as last command in the line then the parameter list
1641              needs to get terminated by "--".
1642              Tests are optional. If they are omitted then action  is  applied
1643              to  all file objects. If tests are given then they form together
1644              an expression.  The action is applied  only  if  the  expression
1645              matches  the  file  object.  Default expression operator between
1646              tests is -and, i.e. the expression matches only if all its tests
1647              match.
1648              Available tests are:
1649              -name  pattern  : Matches if pattern matches the file leaf name.
1650              If the pattern does not contain any  of  the  characters  "*?[",
1651              then it will be truncated according to -file_name_limit and thus
1652              match the truncated name in the ISO filesystem.
1653              -wholename pattern : Matches if pattern matches the file path as
1654              it  would  be  printed  by  action  "echo". Character '/' can be
1655              matched by wildcards. If  pattern  pieces  between  '/'  do  not
1656              contain  any  of  the  characters  "*?[", they will be truncated
1657              according to -file_name_limit.
1658              -disk_name pattern : Like -name but testing the leaf name of the
1659              file  source  on  disk.   Can match only data files which do not
1660              stem from the loaded image, or for directories above  such  data
1661              files. With directories the result can change between -find runs
1662              if their content stems from multiple sources.
1663              -disk_path disk_path : Matches if the given disk_path  is  equal
1664              to  the  path  of the file source on disk. The same restrictions
1665              apply as with -disk_name.
1666              -type type_letter : Matches files of the  given  type:  "block",
1667              "char", "dir", "pipe", "file", "link", "socket", "eltorito", and
1668              "Xotic" which matches what is not matched by the other types.
1669              Only the first letter is interpreted.  E.g.: -find / -type d
1670              -maxdepth number : Matches only files which are at most  at  the
1671              given  depth  level  relative  to  the  iso_rr_path  where -find
1672              starts. That path itself is at depth 0, its  directory  children
1673              are at 1, their directory children at 2, and so on.
1674              -mindepth  number : Matches only files which are at least at the
1675              given depth level.
1676              -damaged : Matches files which use data blocks marked as damaged
1677              by a previous run of -check_media. The damage info vanishes when
1678              a new ISO image gets loaded.
1679              Note that a MD5 session mismatch marks all files of the  session
1680              as  damaged.   If finer distinction is desired, perform -md5 off
1681              before -check_media.
1682              -pending_data : Matches  files  which  get  their  content  from
1683              outside the loaded ISO image.
1684              -lba_range  start_lba block_count : Matches files which use data
1685              blocks     within     the     range     of     start_lba     and
1686              start_lba+block_count-1.
1687              -has_acl : Matches files which have a non-trivial ACL.
1688              -has_xattr  :  Matches  files  which have xattr name-value pairs
1689              from user namespace.
1690              -has_aaip : Matches files which have ACL or any xattr.
1691              -has_any_xattr : Matches files which have any xattr  other  than
1692              ACL.
1693              -has_md5 : Matches data files which have MD5 checksums.
1694              -has_hfs_crtp  creator type : Matches files which have the given
1695              HFS+ creator and type attached.  These are codes of 4 characters
1696              which  get  stored if -hfsplus is enabled. Use a single dash '-'
1697              as wildcard that matches any such code.  E.g:.
1698               -has_hfs_crtp YYDN TEXT
1699               -has_hfs_crtp - -
1700              -has_hfs_bless blessing : Matches files  which  bear  the  given
1701              HFS+   blessing.   It   may   be   one   of   :   "ppc_bootdir",
1702              "intel_bootfile",  "show_folder",  "os9_folder",   "osx_folder",
1703              "any". See also action set_hfs_bless.
1704              -has_filter : Matches files which are filtered by -set_filter.
1705              -hidden  hide_state : Matches files which are hidden in "iso_rr"
1706              tree, in "joliet" tree, in "hfsplus" tree, in all trees  ("on"),
1707              or not hidden in any tree ("off").
1708              Those which are hidden in some tree match -not -hidden "off".
1709              -bad_outname  namespace  : Matches files with names which change
1710              when converted forth and back between the  local  character  set
1711              and  one  of  the  namespaces  "rockridge", "joliet", "ecma119",
1712              "hfsplus".
1713              All applicable -compliance rules are taken into  respect.   Rule
1714              "omit_version"   is  always  enabled,  because  else  namespaces
1715              "joliet"  and  "ecma119"  would   cause   changes   with   every
1716              non-directory    name.     Consider   to   also   enable   rules
1717              "no_force_dots" and "no_j_force_dots".
1718              The namespaces use different character sets  and  apply  further
1719              restrictions   to   name  length,  permissible  characters,  and
1720              mandatory name components.  "rockridge" uses the  character  set
1721              defined  by  -out_charset, "joliet" uses UCS-2BE, "ecma119" uses
1722              ASCII, "hfsplus" uses UTF-16BE.
1723              -name_limit_blocker length :  Matches  file  names  which  would
1724              prevent  command  -file_name_limit  with  the  given length. The
1725              command itself reports only the first problem file.
1726              -prune : If this test is  reached  and  the  tested  file  is  a
1727              directory  then  -find  will  not dive into that directory. This
1728              test itself does always match.
1729              -use_pattern  "on"|"off"  :  This  pseudo  test   controls   the
1730              interpretation  of  wildcards  with tests -name, -wholename, and
1731              -disk_name. Default is "on". If interpretation  is  disabled  by
1732              "off",  then the parameters of -name, -wholename, and -disk_name
1733              have to match literally rather than  as  search  pattern.   This
1734              test itself does always match.
1735              -or_use_pattern    "on"|"off"    :    Like   -use_pattern,   but
1736              automatically appending the test by -or  rather  than  by  -and.
1737              Further  the  test itself does never match. So a subsequent test
1738              -or will cause its other operand to be performed.
1739              -decision  "yes"|"no"  :  If  this  test  is  reached  then  the
1740              evaluation  ends  immediately  and  action  is  performed if the
1741              decision is "yes" or "true". See operator -if.
1742              -true and -false : Always  match  or  match  not,  respectively.
1743              Evaluation goes on.
1744              -sort_lba  :  Always  match.  This  causes  -find to perform its
1745              action in a sequence sorted by the ISO image block addresses  of
1746              the  files.  It  may  improve throughput with actions which read
1747              data from optical drives. Action will always  get  the  absolute
1748              path as parameter.
1749              Available operators are:
1750              -not  :  Matches  if  the  next  test or sub expression does not
1751              match.  Several tests do this specifically:
1752              -undamaged, -lba_range  with  negative  start_lba,  -has_no_acl,
1753              -has_no_xattr, -has_no_aaip, -has_no_filter .
1754              -and : Matches if both neighboring tests or expressions match.
1755              -or  :  Matches  if  at  least  one of both neighboring tests or
1756              expressions matches.
1757              -sub ... -subend or ( ... ) : Enclose  a  sub  expression  which
1758              gets  evaluated  first  before  it  is  processed by neighboring
1759              operators.  Normal precedence is: -not, -or , -and.
1760              -if ... -then ... -elseif ... -then  ...   -else  ...  -endif  :
1761              Enclose  one  or  more  sub  expressions.  If the -if expression
1762              matches, then the -then expression is evaluated as the result of
1763              the  whole  expression  up  to  -endif.  Else  the  next -elseif
1764              expression is evaluated and if it matches, its -then expression.
1765              Finally  in case of no match, the -else expression is evaluated.
1766              There may be more than one -elseif. Neither  -else  nor  -elseif
1767              are  mandatory.   If -else is missing and would be hit, then the
1768              result is a non-match.
1769              -if-expressions are the main use case for above test -decision.
1770
1771              Default action is echo, i.e. to print the address of  the  found
1772              file.  Other  actions  are  certain  xorriso  commands which get
1773              performed on the found files.  These commands may have  specific
1774              parameters. See also their particular descriptions.
1775              chown  and  chown_r  change the ownership and get the user id as
1776              parameter. E.g.: -exec chown thomas --
1777              chgrp and chgrp_r change the group attribute and get  the  group
1778              id as parameter. E.g.: -exec chgrp_r staff --
1779              chmod  and  chmod_r  change  access  permissions  and get a mode
1780              string as parameter.  E.g.: -exec chmod a-w,a+r --
1781              alter_date and alter_date_r change the timestamps.  They  get  a
1782              type character and a timestring as parameters.
1783              E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" --
1784              set_to_mtime  sets  the  ctime  and  atime to the value found in
1785              mtime.
1786              lsdl prints file information like shell command ls -dl.
1787              compare performs command -compare with the found file address as
1788              iso_rr_path   and  the  corresponding  file  address  below  its
1789              parameter disk_path_start. For this the iso_rr_path of the -find
1790              command gets replaced by the disk_path_start.
1791              E.g.: -find /thomas -exec compare /home/thomas --
1792              update  performs  command -update with the found file address as
1793              iso_rr_path. The corresponding file address is  determined  like
1794              with above action "compare".
1795              update_merge  is  like update but does not delete the found file
1796              if it is missing on disk.  It  may  be  run  several  times  and
1797              records with all visited files whether their counterpart on disk
1798              has already been seen by one of the update_merge runs.  Finally,
1799              a -find run with action "rm_merge" may remove all files that saw
1800              no counterpart on disk.
1801              Up to the next "rm_merge" or "clear_merge"  all  newly  inserted
1802              files will get marked as having a disk counterpart.
1803              rm  removes  the found iso_rr_path from the image if it is not a
1804              directory with files in it. I.e. this "rm" includes "rmdir".
1805              rm_r removes the found iso_rr_path  from  the  image,  including
1806              whole directory trees.
1807              rm_merge  removes the found iso_rr_path if it was visited by one
1808              or more previous actions "update_merge" and saw  no  counterpart
1809              on  disk  in any of them. The marking from the update actions is
1810              removed in any case.
1811              clear_merge   removes   an   eventual   marking   from    action
1812              "update_merge".
1813              report_damage  classifies  files  whether  they hit a data block
1814              that is marked as damaged. The result is printed  together  with
1815              the  address  of  the  first  damaged  byte, the maximum span of
1816              damages, file size, and the path of the file.
1817              report_lba prints files  which  are  associated  to  image  data
1818              blocks.   It  tells the logical block address, the block number,
1819              the byte size, and the path of each file. There may be  reported
1820              more  than  one  line  per  file  if  the file has more than one
1821              section.  In this case each line has a different  extent  number
1822              in column "xt".
1823              report_sections  like  report_lba  but telling the byte sizes of
1824              the particular sections rather than the overall byte size of the
1825              file.
1826              getfacl prints access permissions in ACL text form to the result
1827              channel.
1828              setfacl attaches ACLs after removing existing ones. The new  ACL
1829              is given in text form as defined with command -setfacl.
1830              E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
1831              getfattr  prints  xattr  name-value pairs to the result channel.
1832              The choice of namespaces  depends  on  the  setting  of  command
1833              -xattr:  "on"  or  "user"  restricts it to the namespace "user",
1834              "any" only omits namespace "isofs".
1835              get_any_xattr prints xattr name-value pairs from  any  namespace
1836              except  ACL  to the result channel. This is mostly for debugging
1837              of namespace "isofs".
1838              list_extattr mode prints a script to the result  channel,  which
1839              would  use  FreeBSD  command  setextattr to set the file's xattr
1840              name-value pairs of user namespace.  Parameter mode controls the
1841              form of the output of names and values.  Default mode "e" prints
1842              harmless characters in shell  quotation  marks,  but  represents
1843              texts with octal 001 to 037 and 0177 to 0377 by an embedded echo
1844              -e command.  Mode "q" prints any characters in  shell  quotation
1845              marks. This might not be terminal-safe but should work in script
1846              files.  Mode "r" uses no quotation marks. Not  safe.   Mode  "b"
1847              prints backslash encoding. Not suitable for shell parsing.
1848              E.g. -exec list_extattr e --
1849              Command -backslash_codes does not affect the output.
1850              get_md5  prints  the  MD5  sum,  if recorded, together with file
1851              path.
1852              check_md5 compares the MD5  sum,  if  recorded,  with  the  file
1853              content and reports if mismatch.
1854              E.g.: -find / -not -pending_data -exec check_md5 FAILURE --
1855              make_md5  equips  a  data  file  with an MD5 sum of its content.
1856              Useful to upgrade the files in the  loaded  image  to  full  MD5
1857              coverage by the next commit with -md5 "on".
1858              E.g.: -find / -type f -not -has_md5 -exec make_md5 --
1859              setfattr sets or deletes xattr name value pairs.
1860              E.g.: -find / -has_xattr -exec setfattr --remove-all '' --
1861              set_hfs_crtp  adds,  changes,  or  removes HFS+ creator and type
1862              attributes.
1863              E.g.: -exec set_hfs_crtp YYDN TEXT
1864              E.g.: -find /my/dir -prune -exec set_hfs_crtp --delete -
1865              get_hfs_crtp  prints  the  HFS+  creator  and  type   attributes
1866              together  with  the iso_rr_path, if the file has such attributes
1867              at all.
1868              E.g.: -exec get_hfs_crtp
1869              set_hfs_bless applies or removes HFS+ blessings. They are  roles
1870              which  can  be  attributed  to up to four directories and a data
1871              file:
1872              "ppc_bootdir",  "intel_bootfile",  "show_folder",  "os9_folder",
1873              "osx_folder".
1874              They may be abbreviated as "p", "i", "s", "9", and "x".
1875              Each  such  role  can  be attributed to at most one file object.
1876              "intel_bootfile" is the one that would apply to a data file. All
1877              others  apply to directories.  The -find run will end as soon as
1878              the first  blessing  is  issued.  The  previous  bearer  of  the
1879              blessing  will  lose it then.  No file object can bear more than
1880              one blessing.
1881              E.g.: -find /my/blessed/directory -exec set_hfs_bless p
1882              Further there is  blessing  "none"  or  "n"  which  revokes  any
1883              blessing from the found files. This -find run will not stop when
1884              the first match is reached.
1885              E.g.: -find / -has_hfs_bless any -exec set_hfs_bless none
1886              get_hfs_bless prints the HFS+ blessing role and the iso_rr_path,
1887              if the file is blessed at all.
1888              E.g.: -exec get_hfs_bless
1889              set_filter applies or removes filters.
1890              E.g.: -exec set_filter --zisofs --
1891              mkisofs_r applies the rules of mkisofs -r to the file object:
1892              user  id  and  group id become 0, all r-permissions get granted,
1893              all w denied.  If there is any x-permission, then  all  three  x
1894              get granted.  s- and t-bits get removed.
1895              sort_weight attributes a LBA weight number to regular files.
1896              The  number may range from -2147483648 to 2147483647. The higher
1897              it is, the lower will be the block address of the file  data  in
1898              the  emerging  ISO  image.   Currently  the  boot  catalog has a
1899              hardcoded weight of 1 billion.  Normally it  should  occupy  the
1900              block with the lowest possible address.
1901              Data  files  which  are  loaded  by  -indev or -dev get a weight
1902              between 1 and 2 exp 28 = 268,435,456, depending on  their  block
1903              address.  This  shall keep them roughly in the same order if the
1904              write method of modifying is applied.
1905              Data files which are added by  other  commands  get  an  initial
1906              weight of 0.  Boot image files have a default weight of 2.
1907              E.g.: -exec sort_weight 3 --
1908              show_stream shows the content stream chain of a data file.
1909              show_stream_id  is  like  show_stream,  but  also prints between
1910              stream type  and  first  ":"  in  square  brackets  libisofs  id
1911              numbers: [fs_id,dev_id,ino_id].
1912              hide brings the file into one of the hide states "on", "iso_rr",
1913              "joliet",  "hfsplus",  "off".  They  may  be   combined.   E.g.:
1914              joliet:hfsplus
1915              E.g.:
1916                -find / -disk_name *_secret -exec hide on
1917              print_outname   prints   in  the  first  line  the  filename  as
1918              registered by the program model, and  in  the  second  line  the
1919              filename after conversion forth and back between local character
1920              set and one of the namespaces "rockridge", "joliet",  "ecma119",
1921              or "hfsplus". The third output line is "--" .
1922              The  name  conversion does not take into respect the possibility
1923              of name collisions in the target namespace. Such collisions  are
1924              most  likely  in "joliet" and "ecma119", where they get resolved
1925              by automatic file name changes.
1926              E.g.:
1927                -find / -bad_outname joliet -exec print_outname joliet
1928              estimate_size prints a lower and  an  upper  estimation  of  the
1929              number  of  blocks which the found files together will occupy in
1930              the  emerging  ISO  image.   This  does  not  account  for   the
1931              superblock,  for the directories in the -find path, or for image
1932              padding.
1933              find performs another run of -find on the matching file address.
1934              It accepts the same params as -find, except iso_rr_path.
1935              E.g.:
1936                -find  /  -name  '???' -type d -exec find -name '[abc]*' -exec
1937              chmod a-w,a+r --
1938
1939       Filters for data file content:
1940
1941       Filters may be installed between data files in the ISO image and  their
1942       content  source  outside  the  image.  They may also be used vice versa
1943       between data content in the image and target files on disk.
1944       Built-in filters are "--zisofs" and "--zisofs-decode". The former is to
1945       be  applied  via  -set_filter,  the  latter is automatically applied if
1946       zisofs compressed content is detected with a file when loading the  ISO
1947       image.
1948       Another  built-in  filter  pair  is "--gzip" and "--gunzip" with suffix
1949       ".gz".  They behave about like  external  gzip  and  gunzip  but  avoid
1950       forking  a  process  for  each  single file. So they are much faster if
1951       there are many small files.
1952
1953       -external_filter name option[:option] program_path [arguments] --
1954              Register a content filter by associating a name with  a  program
1955              path,  program  arguments,  and  some  behavioral  options. Once
1956              registered it can be applied to multiple data files in  the  ISO
1957              image,  regardless  whether  their content resides in the loaded
1958              ISO image or in the local filesystem.  External filter processes
1959              may  produce  synthetic  file  content  by  reading the original
1960              content from stdin and writing to  stdout  whatever  they  want.
1961              They  must deliver the same output on the same input in repeated
1962              runs.
1963              Options are:
1964               "default" means that no other option is intended.
1965               "suffix=..." sets a file name suffix. If it is not  empty  then
1966              it will be appended to the file name or removed from it.
1967               "remove_suffix"  will  remove  a  file  name suffix rather than
1968              appending it.
1969               "if_nonempty" will leave 0-sized files unfiltered.
1970               "if_reduction" will try filtering and revoke it if the  content
1971              size does not shrink.
1972               "if_block_reduction"  will  revoke if the number of 2 kB blocks
1973              does not shrink.
1974               "used=..." is ignored. Command -status shows it with the number
1975              of files which currently have the filter applied.
1976              Examples:
1977               -external_filter bzip2 suffix=.bz2:if_block_reduction \
1978                                /usr/bin/bzip2 --
1979               -external_filter bunzip2 suffix=.bz2:remove_suffix \
1980                                /usr/bin/bunzip2 --
1981
1982       -unregister_filter name
1983              Remove  an  -external_filter registration. This is only possible
1984              if the filter is not applied to any file in the ISO image.
1985
1986       -close_filter_list
1987              Irrevocably ban commands -concat "pipe",  -external_filter,  and
1988              -unregister_filter,  but  not  -set_filter.  Use this to prevent
1989              external filtering in general or when all intended  filters  are
1990              registered   and   -concat  mode  "pipe"  shall  be  disallowed.
1991              External filters may also be banned totally at compile  time  of
1992              xorriso.   By  default  they  are  banned  if xorriso runs under
1993              setuid permission.
1994
1995       -set_filter name iso_rr_path [***]
1996              Apply an -external_filter or a built-in filter to the given data
1997              files  in  the  ISO  image.  If the filter suffix is not empty ,
1998              then it will be applied to the file name.  Renaming only happens
1999              if  the  filter  really  gets attached and is not revoked by its
2000              options.  By default files which already bear  the  suffix  will
2001              not  get  filtered.  The  others will get the suffix appended to
2002              their names.  If the filter has option "remove_suffix", then the
2003              filter  will only be applied if the suffix is present and can be
2004              removed.  Name oversize or collision  caused  by  suffix  change
2005              will prevent filtering.
2006              With  most  filter  types  this command will immediately run the
2007              filter once for each file in order to determine the output size.
2008              Content  reading  operations  like -extract , -compare and image
2009              generation will perform further filter runs and deliver filtered
2010              content.
2011              At  image  generation  time  the filter output must still be the
2012              same as the output from  the  first  run.  Filtering  for  image
2013              generation  does not happen with files from the loaded ISO image
2014              if the write method of growing is  in  effect  (i.e  -indev  and
2015              -outdev are identical).
2016              The   reserved   filter   name   "--remove-all-filters"  revokes
2017              filtering. This will  revoke  suffix  renamings  as  well.   Use
2018              "--remove-all-filters+" to prevent any suffix renaming.
2019              Attaching  or  detaching  filters  will  not  alter the state of
2020              -changes_pending.  If the filter manipulations shall be the only
2021              changes in a write run, then explicitly execute -changes_pending
2022              "yes".
2023
2024       -set_filter_r name iso_rr_path [***]
2025              Like -set_filter but affecting all  data  files  below  eventual
2026              directories.
2027
2028       Writing the result, drive control:
2029
2030       (see also paragraph about settings below)
2031
2032       -rollback
2033              Discard  the  manipulated  ISO  image and reload it from -indev.
2034              (Use -rollback_end if immediate program end is desired.)
2035
2036       -changes_pending "no"|"yes"|"mkisofs_printed"|"show_status"
2037              Write runs are performed only if a change of the image has  been
2038              made since the image was loaded or created blank. Vice versa the
2039              program will start a write run for pending changes when it  ends
2040              normally (i.e. not by abort and not by command -rollback_end).
2041              The  command  -changes_pending  can  be  used  to  override  the
2042              automatically  determined  state.  This  is  mainly  useful  for
2043              setting  state  "yes"  despite  no  real  changes were made. The
2044              sequence -changes_pending "no" -end is equivalent to the command
2045              -rollback_end.  State  "mkisofs_printed"  is caused by emulation
2046              command -as mkisofs if option -print-size is present.
2047              The pseudo-state "show_status" can be used to print the  current
2048              state to result channel.
2049              Image  loading  or manipulations which happen after this command
2050              will again update automatically the change status of the image.
2051
2052       -commit
2053              Perform the write operation. Afterwards, if -outdev is readable,
2054              make  it  the new -dev and load the image from there.  Switch to
2055              growing mode.  (A subsequent -outdev will activate  modification
2056              mode  or  blind growing.)  -commit is performed automatically at
2057              end of program if there are uncommitted manipulations pending.
2058              So, to perform a final write operation with no new -dev  and  no
2059              new  loading of image, rather execute command -end.  If you want
2060              to go on without image loading,  execute  -commit_eject  "none".
2061              To  eject  after  write without image loading, use -commit_eject
2062              "all".
2063              To suppress a final write, execute -rollback_end.
2064
2065              Writing can last quite a while. It is not unnormal with  several
2066              types  of  media that there is no progress visible for the first
2067              few minutes or that the drive gnaws on  the  medium  for  a  few
2068              minutes  after  all data have been transmitted.  xorriso and the
2069              drives are in a client-server  relationship.   The  drives  have
2070              much freedom about what to do with the media.  Some combinations
2071              of drives and media simply do not work, despite the promises  by
2072              their vendors.  If writing fails then try other media or another
2073              drive. The reason for such failure is hardly ever in the code of
2074              the  various  burn  programs  but you may well try some of those
2075              listed below under SEE ALSO.
2076
2077       -eject "in"|"out"|"all"
2078              Eject  the  medium  in  -indev,   -outdev,   or   both   drives,
2079              respectively.  Note: It is not possible yet to effectively eject
2080              disk files.
2081
2082       -commit_eject "in"|"out"|"all"|"none"
2083              Combined -commit and -eject. When writing has  finished  do  not
2084              make  -outdev  the new -dev, and load no ISO image. Rather eject
2085              -indev and/or -outdev. Give up any non-ejected drive.
2086
2087       -blank mode
2088              Make media ready for writing from  scratch  (if  not  -dummy  is
2089              activated).
2090              This  affects  only  the -outdev not the -indev.  If both drives
2091              are the same and if the ISO image was altered then this  command
2092              leads to a FAILURE event.  Defined modes are:
2093                as_needed, fast, all, deformat, deformat_quickest
2094              "as_needed"   cares   for   used  CD-RW,  DVD-RW  and  for  used
2095              overwriteable  media  by  applying  -blank  "fast".  It  applies
2096              -format  "full"  to   yet  unformatted  DVD-RAM and BD-RE. Other
2097              media in blank state are gracefully ignored.  Media which cannot
2098              be made ready for writing from scratch cause a FAILURE event.
2099              "fast"   makes   CD-RW  and  unformatted  DVD-RW  re-usable,  or
2100              invalidates overwriteable ISO  images.  "all"  might  work  more
2101              thoroughly and need more time.
2102              "deformat" converts overwriteable DVD-RW into unformatted ones.
2103              "deformat_quickest"  is a faster way to deformat or blank DVD-RW
2104              but produces media which are only suitable for a single session.
2105              Some drives announce this state by not offering feature 21h, but
2106              some drives offer it anyway.  If feature 21h  is  missing,  then
2107              xorriso  will refuse to write on DVD-RW if not command -close is
2108              set to "on".
2109              The progress reports issued by some drives  while  blanking  are
2110              quite  unrealistic.  Do not conclude success or failure from the
2111              reported percentages. Blanking was successful if no SORRY  event
2112              or worse occurred.
2113              Mode  may  be  prepended  by  "force:"  in order to override the
2114              evaluation of the medium state by  libburn.  E.g.  "force:fast".
2115              Blanking  will nevertheless only succeed if the drive is willing
2116              to do it.
2117
2118       -format mode
2119              Convert unformatted DVD-RW  into  overwriteable  ones,  "de-ice"
2120              DVD+RW,  format newly purchased BD-RE or BD-R, re-format DVD-RAM
2121              or BD-RE.
2122              Defined modes are:
2123                as_needed, full, fast, by_index_<num>, fast_by_index_<num>,
2124                by_size_<num>, fast_by_size_<num>, without_spare
2125              "as_needed" formats yet unformatted DVD-RW, DVD-RAM,  BD-RE,  or
2126              blank unformatted BD-R. Other media are left untouched.
2127              "full"  (re-)formats  DVD-RW,  DVD+RW,  DVD-RAM, BD-RE, or blank
2128              unformatted BD-R.
2129              "fast" does the same as "full" but tries to be quicker.
2130              "by_index_" selects a format out of the descriptor  list  issued
2131              by  command -list_formats. The index number from that list is to
2132              be appended to the mode word. E.g: "by_index_3".
2133              "fast_by_index_" does the same as "by_index_" but  tries  to  be
2134              quicker.
2135              "by_size_"  selects  a  format  out of the descriptor list which
2136              provides at least the given size. That size is to be appended to
2137              the mode word.  E.g: "by_size_4100m". This applies to media with
2138              Defect Management.  On BD-RE it will  not  choose  format  0x31,
2139              which offers no Defect Management.
2140              "fast_by_size_"  does  the  same  as  "by_size_" but tries to be
2141              quicker.
2142              "without_spare" selects the largest format out of the descriptor
2143              list  which  provides  no  Spare  Area for Defect Management. On
2144              BD-RE this will be format 0x31.
2145              The formatting action has  no  effect  on  media  if  -dummy  is
2146              activated.
2147              Formatting is normally needed only once during the lifetime of a
2148              medium, if ever. But it is a reason for re-formatting if:
2149               DVD-RW was deformatted by -blank,
2150               DVD+RW has read failures (re-format before next write),
2151               DVD-RAM or BD-RE shall change their amount of defect reserve.
2152              BD-R may be written unformatted or may be formatted before first
2153              use.   Formatting  activates  Defect  Management  which tries to
2154              catch and repair bad spots on media during the write process  at
2155              the expense of half speed even with flawless media.
2156              The  progress reports issued by some drives while formatting are
2157              quite unrealistic. Do not conclude success or failure  from  the
2158              reported  percentages.  Formatting  was  successful  if no SORRY
2159              event or worse  occurred.  Be  patient  with  apparently  frozen
2160              progress.
2161
2162       -list_formats
2163              Put  out  a list of format descriptors as reported by the output
2164              drive for the current medium. The list gives  the  index  number
2165              after  "Format  idx",  a  MMC format code, the announced size in
2166              blocks (like "2236704s") and the same size in MiB.
2167              MMC format codes are manifold. Most important are: "00h" general
2168              formatting, "01h" increases reserve space for DVD-RAM, "26h" for
2169              DVD+RW, "30h" for BD-RE with  reserve  space,  "31h"  for  BD-RE
2170              without reserve space, "32h" for BD-R.
2171              Smaller  format  size  with  DVD-RAM,  BD-RE, or BD-R means more
2172              reserve space.
2173
2174       -list_speeds
2175              Put out a list of speed values as reported by  the  drives  with
2176              the  loaded media. The list tells read speeds of the input drive
2177              and of the output drive. Further it tells write  speeds  of  the
2178              output drive.
2179              The  list  of  write  speeds  does not necessarily mean that the
2180              medium is writable or that these speeds are actually achievable.
2181              Especially the lists reported with empty drive or with ROM media
2182              obviously advertise speeds for other media.
2183              It is not mandatory to use speed values out of the listed range.
2184              The  drive is supposed to choose a safe speed that is as near to
2185              the desired speed as possible.
2186              At the end of the list, "Write speed L" and "Write speed H"  are
2187              the  best guesses for lower and upper write speed limit.  "Write
2188              speed l" and "Write  speed  h"  may  appear  only  with  CD  and
2189              eventually override the list of other speed offers.
2190              Only  if the drive reports contradicting speed information there
2191              will appear "Write speed 0", which tells the  outcome  of  speed
2192              selection  by command -speed 0, if it deviates from "Write speed
2193              H".
2194              "Read speed L" and "Read speed H" tell the minimum  and  maximum
2195              read  speeds,  as reported by the drive. They would be chosen by
2196              -read_speed "min" or "max"  if  they  undercut  or  surpass  the
2197              built-in limits. These are "1x", "52xCD", "24xDVD", "20xBD".
2198
2199       -close_damaged "as_needed"|"force"
2200              Try  to  close  the  upcoming  track  and  session  if the drive
2201              reported the medium as damaged. This may apply to  CD-R,  CD-RW,
2202              DVD-R,  DVD-RW,  DVD+R, DVD+R DL, or BD-R media. It is indicated
2203              by warning messages when the  drive  gets  acquired,  and  by  a
2204              remark  "but  next track is damaged" with the line "Media status
2205              :" of command -toc.
2206              The setting of command  -close  determines  whether  the  medium
2207              stays appendable.
2208              Mode  "as_needed"  gracefully  refuses  on  media  which are not
2209              reported as damaged. Mode "force" attempts the  close  operation
2210              even with media which appear undamaged.
2211              No  image  changes are allowed to be pending before this command
2212              is performed.  After closing  was  attempted,  both  drives  are
2213              given up.
2214
2215       -list_profiles "in"|"out"|"all"
2216              Put  out  a list of media types supported by -indev, -outdev, or
2217              both, respectively.  The currently recognized type is marked  by
2218              text "(current)".
2219
2220       Settings for result writing:
2221
2222       Rock  Ridge  info  will  be generated by default.  ACLs will be written
2223       according to the setting of command -acl.
2224
2225       -joliet "on"|"off"
2226              If enabled by "on", generate Joliet tree additional to ISO  9660
2227              + Rock Ridge tree.
2228
2229       -hfsplus "on"|"off"
2230              If  enabled  by  "on", generate a HFS+ filesystem inside the ISO
2231              9660 image and mark it by Apple Partition Map (APM)  entries  in
2232              the System Area, the first 32 KiB of the image.
2233              This   may   collide   with   data   submitted   by  -boot_image
2234              system_area=.   The  first  8  bytes  of  the  System  Area  get
2235              overwritten by { 0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff }
2236              which can be executed  as  x86  machine  code  without  negative
2237              effects.  So if an MBR gets combined with this feature, then its
2238              first 8 bytes should contain no essential commands.
2239              The next blocks of 2 KiB in the System Area will be occupied  by
2240              APM  entries.   The  first  one covers the part of the ISO image
2241              before the HFS+ filesystem metadata. The second  one  marks  the
2242              range  from  HFS+  metadata  to the end of file content data. If
2243              more ISO image data follow, then a third  partition  entry  gets
2244              produced.  Other  features  of  xorriso might cause the need for
2245              more APM entries.
2246              The HFS+ filesystem is not suitable for add-on sessions produced
2247              by  the  multi-session  method of growing. An existing ISO image
2248              may nevertheless be the base for a new  image  produced  by  the
2249              method of modifying.  If -hfsplus is enabled when -indev or -dev
2250              gets executed, then AAIP attributes get loaded  from  the  input
2251              image  and  checked for information about HFS creator, filetype,
2252              or blessing. If found, then they get enabled as settings for the
2253              next  image  production.   Therefore  it is advisable to perform
2254              -hfsplus "on" before -indev or -dev.
2255              Information about HFS creator, type, and blessings  gets  stored
2256              by  xorriso if -hfsplus is enabled at -commit time. It is stored
2257              as copy outside the HFS+ partition, but rather  along  with  the
2258              Rock  Ridge  information.  xorriso does not read any information
2259              from the HFS+ meta data.
2260              Be aware that HFS+ is case-insensitive although  it  can  record
2261              file  names  with  upper-case and lower-case letters. Therefore,
2262              file names from the iso_rr name tree may  collide  in  the  HFS+
2263              name  tree.  In  this case they get changed by adding underscore
2264              characters and counting numbers. In case of very long names,  it
2265              might be necessary to map them to "MANGLED_...".
2266
2267       -rockridge "on"|"off"
2268              Mode "off" disables production of Rock Ridge information for the
2269              ISO 9660 file objects. The multi-session capabilities of xorriso
2270              depend  much  on  the  naming  fidelity  of Rock Ridge. So it is
2271              strongly discouraged to deviate from default setting "on".
2272
2273       -compliance rule[:rule...]
2274              Adjust the compliance to specifications of ISO 9660/ECMA-119 and
2275              its  contemporary  extensions.  In  some  cases  it  is worth to
2276              deviate a bit in order to circumvent bugs of the intended reader
2277              system or to get unofficial extra features.
2278              There are several adjustable rules which have a keyword each. If
2279              they are mentioned with this command then their rule gets  added
2280              to  the  relaxation  list.  This  list  can  be  erased by rules
2281              "strict" or "clear". It can be reset to  its  start  setting  by
2282              "default".  All of the following relaxation rules can be revoked
2283              individually by appending "_off". Like "deep_paths_off".
2284              Rule keywords are:
2285              "iso_9660_level="number chooses level 1 with ECMA-119  names  of
2286              the  form  8.3  and  -file_size_limit <= 4g - 1, or level 2 with
2287              ECMA-119 names up to length 32 and the same -file_size_limit, or
2288              level 3 with ECMA-119 names up to length 32 and -file_size_limit
2289              >= 400g -200k. If necessary -file_size_limit gets adjusted.
2290              "allow_dir_id_ext" allows ECMA-119 names of directories to  have
2291              a  name  extension  as  with other file types. It does not force
2292              dots and it omits the version number,  though.  This  is  a  bad
2293              tradition  of  mkisofs  which violates ECMA-119.  Especially ISO
2294              level 1 only allows 8 characters in a  directory  name  and  not
2295              8.3.
2296              "omit_version"  does  not  add  versions  (";1") to ECMA-119 and
2297              Joliet file names.
2298              "only_iso_version" does not add versions (";1") to  Joliet  file
2299              names.
2300              "deep_paths" allows ECMA-119 file paths deeper than 8 levels.
2301              "long_paths"   allows   ECMA-119  file  paths  longer  than  255
2302              characters.
2303              "long_names" allows up  to  37  characters  with  ECMA-119  file
2304              names.
2305              "no_force_dots"  does not add a dot to ECMA-119 file names which
2306              have none.
2307              "no_j_force_dots" does not add a dot to Joliet file names  which
2308              have none.
2309              "lowercase" allows lowercase characters in ECMA-119 file names.
2310              "7bit_ascii" allows nearly all 7-bit characters in ECMA-119 file
2311              names.  Not allowed are 0x0  and  '/'.  If  not  "lowercase"  is
2312              enabled, then lowercase letters get converted to uppercase.
2313              "full_ascii"  allows  all 8-bit characters except 0x0 and '/' in
2314              ECMA-119 file names.
2315              "untranslated_names" might be dangerous  for  inadverted  reader
2316              programs  which rely on the restriction to at most 37 characters
2317              in ECMA-119 file names.  This rule allows ECMA-119 file names up
2318              to  96  characters  with no character conversion. If a file name
2319              has  more  characters,   then   image   production   will   fail
2320              deliberately.
2321              "untranslated_name_len="number enables untranslated_names with a
2322              smaller limit for the length of  file  names.  0  disables  this
2323              feature,  -1 chooses maximum length limit, numbers larger than 0
2324              give the desired length limit.
2325              "joliet_long_names"  allows  Joliet  leaf  names   up   to   103
2326              characters rather than 64.
2327              "joliet_long_paths"   allows   Joliet   paths  longer  than  240
2328              characters.
2329              "joliet_utf16" encodes Joliet  names  in  UTF-16BE  rather  than
2330              UCS-2.   The difference is with characters which are not present
2331              in UCS-2 and get encoded in UTF-16 by 2 words of  16  bit  each.
2332              Both words then stem from a reserved subset of UCS-2.
2333              "always_gmt"   stores  timestamps  in  GMT  representation  with
2334              timezone 0.
2335              "rec_mtime" records with  non-RockRidge  directory  entries  the
2336              disk  file's  mtime and not the creation time of the image. This
2337              applies to the ECMA-119 tree (plain ISO 9660), to Joliet, and to
2338              ISO  9660:1999.  "rec_time"  is  default.  If  disabled, it gets
2339              automatically  re-enabled  by  -as  mkisofs  emulation  when   a
2340              pathspec is encountered.
2341              "new_rr"  uses  Rock  Ridge version 1.12 (suitable for GNU/Linux
2342              but  not  for  older  FreeBSD  or  for  Solaris).  This  implies
2343              "aaip_susp_1_10_off"   which   may   be  changed  by  subsequent
2344              "aaip_susp_1_10".
2345              Default is "old_rr" which uses Rock  Ridge  version  1.10.  This
2346              implies also "aaip_susp_1_10" which may be changed by subsequent
2347              "aaip_susp_1_10_off".
2348              "aaip_susp_1_10"  allows  AAIP  to  be  written  as   unofficial
2349              extension  of  RRIP  rather  than  as  official  extension under
2350              SUSP-1.12.
2351              "no_emul_toc"  saves  64  kB   with   the   first   session   on
2352              overwriteable  media but makes the image incapable of displaying
2353              its session history.
2354              "iso_9660_1999" causes the production of an additional directory
2355              tree  compliant  to  ISO 9660:1999. It can record long filenames
2356              for readers which do not understand Rock Ridge.
2357              "old_empty" uses the old way of of giving block addresses in the
2358              range  of  [0,31] to files with no own data content. The new way
2359              is to have a dedicated block to which all such files will point.
2360              Default setting is
2361               "clear:only_iso_version:deep_paths:long_paths:no_j_force_dots:
2362               always_gmt:old_rr".
2363              Note: The term "ECMA-119 name" means the plain  ISO  9660  names
2364              and  attributes  which  get  visible  if the reader ignores Rock
2365              Ridge.
2366
2367       -rr_reloc_dir name
2368              Specify the name of  the  relocation  directory  in  which  deep
2369              directory  subtrees  shall  be  placed  if -compliance is set to
2370              "deep_paths_off" or "long_paths_off".  A deep directory  is  one
2371              that  has a chain of 8 parent directories (including root) above
2372              itself, or one that contains a file with  an  ECMA-119  path  of
2373              more than 255 characters.
2374              The  overall  directory  tree  will  appear originally deep when
2375              interpreted as Rock Ridge tree. It will appear as re-arranged if
2376              only ECMA-119 information is considered.
2377              The  default  relocation  directory  is  the  root directory. By
2378              giving a non-empty name with -rr_reloc_dir, a directory  in  the
2379              root  directory  may  get this role.  If that directory does not
2380              already exist at -commit time, then  it  will  get  created  and
2381              marked  for  Rock  Ridge  as  relocation  artefact.  At least on
2382              GNU/Linux it will not be displayed in mounted Rock Ridge images.
2383              The name must not contain a '/' character and must not be longer
2384              than 255 bytes.
2385
2386       -volid text
2387              Specify  the  volume  ID,  which  most  operating  systems  will
2388              consider to be the volume name of the image or medium.
2389              xorriso accepts any text up to 32 characters, but  according  to
2390              rarely obeyed specs stricter rules apply:
2391              ECMA-119 demands ASCII characters out of [A-Z0-9_]. Like:
2392                "IMAGE_23"
2393              Joliet allows 16 UCS-2 characters. Like:
2394                "Windows name"
2395              Be  aware that the volume id might get used automatically as the
2396              name of the mount point when  the  medium  is  inserted  into  a
2397              playful computer system.
2398              If  an  ISO  image  gets  loaded  while  the volume ID is set to
2399              default "ISOIMAGE" or to "", then the volume ID  of  the  loaded
2400              image  will  become  the  effective volume id for the next write
2401              run. But as soon as command -volid is performed afterwards, this
2402              pending ID is overridden by the new setting.
2403              Consider  this  when  setting -volid "ISOIMAGE" before executing
2404              -dev, -indev, or -rollback.  If you insist in -volid "ISOIMAGE",
2405              set it again after those commands.
2406
2407       -volset_id text
2408              Set  the  volume  set  ID  string  to  be  written with the next
2409              -commit.  Permissible are up to  128  characters.  This  setting
2410              gets overridden by image loading.
2411
2412       -publisher text
2413              Set the publisher ID string to be written with the next -commit.
2414              This may identify the person or organisation who specified  what
2415              shall  be  recorded.  Permissible are up to 128 characters. This
2416              setting gets overridden by image loading.
2417
2418       -application_id text
2419              Set the application ID  string  to  be  written  with  the  next
2420              -commit. This may identify the specification of how the data are
2421              recorded.  Permissible are up to 128  characters.  This  setting
2422              gets overridden by image loading.
2423              The  special text "@xorriso@" gets converted to the ID string of
2424              xorriso which is normally written as -preparer_id. It is a wrong
2425              tradition to write the program ID as -application_id.
2426
2427       -system_id text
2428              Set  the  system  ID string to be written with the next -commit.
2429              This may identify the system which can recognize  and  act  upon
2430              the  content  of  the  System  Area  in  image  blocks  0 to 15.
2431              Permissible  are  up  to  32  characters.  This   setting   gets
2432              overridden by image loading.
2433
2434       -volume_date type timestring
2435              Set  one  of  the  four  overall timestamps for subsequent image
2436              writing.  Available types are:
2437              "c"  time when the volume was created.
2438              "m"  time when volume was last modified.
2439              "x"  time when the information in the volume expires.
2440              "f"  time since when the volume is effectively valid.
2441              "all_file_dates"  sets mtime, atime, and ctime of all files  and
2442              directories   to   the   given   time.   If  the  timestring  is
2443              "set_to_mtime", then the  atime  and  ctime  of  each  file  and
2444              directory get set to the value found in their mtime.
2445              These  actions  stay delayed until actual ISO production begins.
2446              Up to then they can be revoked by  "all_file_dates"  with  empty
2447              timestring or timestring "default".
2448              The  timestamps of the El Torito boot catalog file get refreshed
2449              when the ISO is produced. They can be influenced by "uuid".
2450              "uuid"  sets a timestring  that  overrides  "c"  and  "m"  times
2451              literally  and  sets the time of the El Torito boot catalog.  It
2452              must consist of 16 decimal digits which  form  YYYYMMDDhhmmsscc,
2453              with  YYYY  between  1970  and  2999.  Time  zone is GMT.  It is
2454              supposed to match this GRUB line:
2455               search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc
2456              E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
2457              Timestrings for the other types may be  given  as  with  command
2458              -alter_date.   Some  of them are prone to timezone computations.
2459              The  timestrings  "default"  or   "overridden"   cause   default
2460              settings:  "c"  and  "m"  will  show  the  current time of image
2461              creation. "x" and "f" will be marked as  insignificant.   "uuid"
2462              will be deactivated.
2463              At -commit time, some timestamps get set to the maximum value of
2464              effectively written volume creation and  modification  time:  El
2465              Torito boot catalog, HFS+ superblock, ECMA-119 file modification
2466              time if -compliance "no_rec_mtime".  The  isohybrid  MBR  id  is
2467              computed  from  "uuid"  if given, else from the effective volume
2468              modification date.
2469
2470       -copyright_file text
2471              Set the copyright file name to be written with the next -commit.
2472              This  should  be  the ISO 9660 path of a file in the image which
2473              contains a  copyright  statement.   Permissible  are  up  to  37
2474              characters. This setting gets overridden by image loading.
2475
2476       -abstract_file text
2477              Set  the abstract file name to be written with the next -commit.
2478              This should be the ISO 9660 path of a file in  the  image  which
2479              contains   an   abstract  statement  about  the  image  content.
2480              Permissible  are  up  to  37  characters.  This   setting   gets
2481              overridden by image loading.
2482
2483       -biblio_file text
2484              Set  the  biblio  file name to be written with the next -commit.
2485              This should be the ISO 9660 path of a file in  the  image  which
2486              contains  bibliographic  records.   Permissible  are  up  to  37
2487              characters. This setting gets overridden by image loading.
2488
2489       -preparer_id
2490              Set the preparer ID string to be written with the next  -commit.
2491              This  may identify the person or other entity which controls the
2492              preparation of the data which shall be recorded.  Normally  this
2493              should  be  the  ID  of xorriso and not of the person or program
2494              which operates xorriso.  Please avoid to change it.  Permissible
2495              are up to 128 characters.
2496              The  special text "@xorriso@" gets converted to the ID string of
2497              xorriso which is default at program startup.
2498              Unlike other ID strings, this setting is not influenced by image
2499              loading.
2500
2501       -application_use character|0xXY|disk_path
2502              Specify  the content of the Application Use field which can take
2503              at most 512 bytes.
2504              If the parameter of this command is empty,  then  the  field  is
2505              filled  with  512  0-bytes. If it is a single character, then it
2506              gets repeated 512 times.  If it begins by "0x" followed  by  two
2507              hex  digits  [0-9a-fA-F], then the digits are read as byte value
2508              which gets repeated 512 times.
2509              Any other parameter text is used as disk_path  to  open  a  data
2510              file and to read up to 512 bytes from it. If the file is smaller
2511              than 512 bytes, then the remaining bytes in the field get set to
2512              binary 0.
2513              This setting is not influenced by image loading.
2514
2515       -out_charset character_set_name
2516              Set  the  character  set  to which file names get converted when
2517              writing an  image.  See  paragraph  "Character  sets"  for  more
2518              explanations.   When loading the written image after -commit the
2519              setting of -out_charset will be copied to -in_charset.
2520
2521       -uid uid
2522              User id to be used for all files when  the  new  ISO  tree  gets
2523              written to media.
2524
2525       -gid gid
2526              Group  id  to  be  used for all files when the new ISO tree gets
2527              written to media.
2528
2529       -zisofs option[:options]
2530              Set global parameters for zisofs compression. This  data  format
2531              is  recognized  and  transparently  uncompressed  by  some Linux
2532              kernels. It is  to  be  applied  via  command  -set_filter  with
2533              built-in filter "--zisofs".  Parameters are:
2534               "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow
2535               "block_size="32k|64k|128k size of compression blocks
2536               "by_magic=on"  enables  an  expensive  test at image generation
2537              time which checks files  from  disk  whether  they  already  are
2538              zisofs compressed, e.g. by program mkzftree.
2539               "default" same as "level=6:block_size=32k:by_magic=off"
2540
2541       -speed code|number[k|m|c|d|b]
2542              Set the burn speed. Default is "max" (or "0") = maximum speed as
2543              announced by the drive.  Further special speed codes are:
2544              "min" (or "-1") selects minimum speed as announced by the drive.
2545              "none" avoids to send a  speed  setting  command  to  the  drive
2546              before burning begins.
2547              Speed  can  be  given in media dependent numbers or as a desired
2548              throughput per second in MMC compliant kB (= 1000) or MB (= 1000
2549              kB).  Media  x-speed factor can be set explicitly by "c" for CD,
2550              "d" for DVD, "b" for BD, "x" is optional.
2551              Example speeds:
2552               706k = 706kB/s = 4c = 4xCD
2553               5540k = 5540kB/s = 4d = 4xDVD
2554              If there is no hint about the  speed  unit  attached,  then  the
2555              medium in the -outdev will decide. Default unit is CD = 176.4k.
2556              MMC drives usually activate their own idea of speed and take the
2557              speed value given by the burn program only as  upper  limit  for
2558              their own decision.
2559
2560       -stream_recording "on"|"off"|"full"|"data"|number
2561              Setting  "on"  tries  to circumvent the management of defects on
2562              DVD-RAM, BD-RE, or BD-R. Defect management keeps partly  damaged
2563              media  usable.  But it reduces write speed to half nominal speed
2564              even if the medium  is  in  perfect  shape.   For  the  case  of
2565              flawless  media,  one may use -stream_recording "on" to get full
2566              speed.
2567              "full" tries full speed with all write operations, whereas  "on"
2568              does  this only above byte address 32s. One may give a number of
2569              at least 16s in order to set an own address limit.
2570              "data" causes full speed to start when superblock and  directory
2571              entries are written and writing of file content blocks begins.
2572
2573       -dvd_obs "default"|"32k"|"64k"
2574              GNU/Linux  specific:  Set  the number of bytes to be transmitted
2575              with each write operation to DVD or BD media. A number of 64  KB
2576              may  improve  throughput  with  bus  systems  which show latency
2577              problems.  The  default  depends  on  media  type,  on   command
2578              -stream_recording , and on compile time options.
2579
2580       -modesty_on_drive parameter[:parameters]
2581              Control  whether  the  drive  buffer  shall be kept from getting
2582              completely filled.  Parameter "on" (or "1")  keeps  the  program
2583              from  trying to write to the burner drive while its buffer is in
2584              danger to be filled over  a  given  limit.   If  this  limit  is
2585              exceeded  then the program will wait until the filling reaches a
2586              given low percentage value.
2587              This can ease the load on operating system and drive  controller
2588              and  thus help with achieving better input bandwidth if disk and
2589              burner are not on independent controllers (like hda and hdb). It
2590              may  also help with throughput problems of simultaneous burns on
2591              different burners with Linux  kernels  like  3.16,  if  one  has
2592              reason  not to fix the problem by -scsi_dev_family "sg".  On the
2593              other hand it increases the risk of buffer  underflow  and  thus
2594              reduced write speed.
2595              Some  burners  are  not suitable because they report buffer fill
2596              with granularity too coarse in size or  time,  or  expect  their
2597              buffer to be filled to the top before they go to full speed.
2598              Parameters "off" or "0" disable this feature.
2599              The  threshold  for  beginning  to  wait  is  given by parameter
2600              "max_percent=".  Parameter "min_percent=" defines the  threshold
2601              for  resuming  transmission.  Percentages are permissible in the
2602              range of 25 to 100. Numbers in this range  without  a  prepended
2603              name are interpreted as "on:min_percent=".
2604              E.g.: -modesty_on_drive 75
2605              The optimal values depend on the buffer behavior of the drive.
2606              Parameter   "timeout_sec="   defines   after   which   time   of
2607              unsuccessful waiting the modesty shall be  disabled  because  it
2608              does not work.
2609              Parameter  "min_usec="  defines  the  initial sleeping period in
2610              microseconds.  If the drive buffer appears to be  too  full  for
2611              sending  more  data,  the  program  will wait the given time and
2612              inquire the buffer fill state again.  If repeated inquiry  shows
2613              not  enough  free space, the sleep time will slowly be increased
2614              to what parameter "max_usec=" defines.
2615              Parameters, which are not  mentioned  with  a  -modesty_on_drive
2616              command, stay unchanged.  Default is:
2617                -modesty_on_drive off:min_percent=90:max_percent=95:
2618                timeout_sec=120:min_usec=5000:max_usec=25000
2619
2620       -use_immed_bit "on"|"off"|"default"
2621              Control  whether  several  long  lasting  SCSI commands shall be
2622              executed with the Immed bit, which makes the commands end  early
2623              while  the  drive  operation  is  still  going  on. xorriso then
2624              inquires progress indication until the drive reports to be ready
2625              again.  If  this  feature  is  turned  off,  then  blanking  and
2626              formatting will show no progress indication.
2627              It may depend on the operating system whether -use_immed_bit  is
2628              set  to "off" by default. Command -status will tell by appending
2629              "/on" or "/off"  if  a  drive  has  already  been  acquired  and
2630              -use_immed_bit   is   currently   set   to  "default".   Command
2631              -use_immed_bit tolerates and ignores such appended text.
2632
2633       -stdio_sync "on"|"off"|"end"|number
2634              Set the number of bytes after which to force  output  to  stdio:
2635              pseudo drives.  This forcing keeps the memory from being clogged
2636              with lots of pending data for slow devices. Default "on" is  the
2637              same  as  "16m".   Forced output can be disabled by "off", or be
2638              delayed by "end" until all data are produced.  If  a  number  is
2639              chosen, then it must be at least 64k.
2640
2641       -dummy "on"|"off"
2642              If "on" then simulate burning or refuse with FAILURE event if no
2643              simulation is possible, do neither blank nor format.
2644
2645       -fs number["k"|"m"]
2646              Set the size of the fifo buffer which smoothens the data  stream
2647              from  ISO  image  generation to media burning. Default is 4 MiB,
2648              minimum 64 kiB, maximum 1 GiB.  The number may  be  followed  by
2649              letter  "k"  or  "m"  which means unit is kiB (= 1024) or MiB (=
2650              1024 kiB).
2651
2652       -close "on"|"off"|"as_needed"
2653              If -close is set to "on" then mark the  written  medium  as  not
2654              appendable  any  more.  This will have no effect on overwritable
2655              media types.  Setting "on" is the contrary  of  cdrecord  option
2656              -multi, and is one aspect of growisofs option -dvd-compat.
2657              If  set  to  "off" then keep the medium writable for an appended
2658              session.
2659              If set to "as_needed" then use "on" only if "off"  is  predicted
2660              to fail with the given medium and its state.
2661              Not  all  drives  correctly  recognize fast-blanked DVD-RW which
2662              need "on".  If there is well founded suspicion that a  burn  run
2663              failed  due  to  -close  "off", then -close "as_needed" causes a
2664              re-try with "on".
2665              Note that emulation command -as "cdrecord" temporarily overrides
2666              the  current setting of -close by its own default -close "on" if
2667              its option -multi is missing.
2668
2669       -write_type "auto"|"tao"|"sao/dao"
2670              Set the write type for the next burn run. "auto" will select SAO
2671              with  blank CD media, DAO with blank DVD-R[W] if -close is "on",
2672              and elsewise  CD  TAO  or  the  equivalent  write  type  of  the
2673              particular  DVD/BD  media.   Choosing  TAO or SAO/DAO explicitly
2674              might cause the burn run to fail if the desired  write  type  is
2675              not possible with the given media state.
2676
2677       -padding number["k"|"m"]|"included"|"appended"
2678              Append  the  given  number  of  extra bytes to the image stream.
2679              This is a traditional remedy for  a  traditional  bug  in  block
2680              device  read drivers. Needed only for CD recordings in TAO mode.
2681              Since one can hardly predict on what media an  image  might  end
2682              up,  xorriso  adds the traditional 300k of padding by default to
2683              all images.
2684              For images which will never get to  a  CD  it  is  safe  to  use
2685              -padding 0 .
2686              Normally  padding  is  not  written as part of the ISO image but
2687              appended after the image end. This is -padding mode "appended".
2688              Emulation command -as "mkisofs" and command -jigdo cause padding
2689              to be written as part of the image.  The same effect is achieved
2690              by -padding mode "included".
2691
2692       Bootable ISO images:
2693
2694       Contrary to published specifications many BIOSes will load an El Torito
2695       record from the first session on media and not from the last one, which
2696       gets mounted by default. This  makes  no  problems  with  overwriteable
2697       media, because they appear to inadverted readers as one single session.
2698       But  with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that
2699       the whole bootable system has to reside already in  the  first  session
2700       and  that the last session still has to bear all files which the booted
2701       system expects after mounting the ISO image.
2702       If a boot image from ISOLINUX or GRUB is known to be present  on  media
2703       then  it  is advised to patch it when a follow-up session gets written.
2704       But one should not rely on the capability to influence the  bootability
2705       of the existing sessions, unless one can assume overwriteable media.
2706       Normally  the  boot images are data files inside the ISO filesystem. By
2707       special path "--interval:appended_partition_NNN:all::" it  is  possible
2708       to  refer  to an appended partition. The number NNN gives the partition
2709       number as used with the corresponding command -append_partition.  E.g.:
2710         -append_partition 2 0xef /tmp/efi.img
2711         -boot_image any efi_path=--interval:appended_partition_2:all::
2712       There are booting mechanisms which do not use an El Torito  record  but
2713       rather  start  at  the first bytes of the image: PC-BIOS MBR or EFI GPT
2714       for hard-disk-like devices, APM partition entries for Macs which expect
2715       HFS+  boot  images,  MIPS Volume Header for old SGI computers, DEC Boot
2716       Block for old MIPS DECstation, SUN Disk Label for SPARC machines, HP-PA
2717       boot  sector for HP PA-RISC machines, DEC Alpha SRM boot sector for old
2718       DEC Alpha machines.
2719
2720       Several of the following commands expect disk paths as input  but  also
2721       accept  description  strings for the libisofs interval reader, which is
2722       able to cut out data from disk files or -indev and to zeroize parts  of
2723       the   content:  command  -append_partition,  boot  specs  system_area=,
2724       grub2_mbr=, prep_boot_part=, efi_boot_part=.
2725       The description string consists of the following components,  separated
2726       by colon ':'
2727         "--interval:"Flags":"Interval":"Zeroizers":"Source
2728       The  component  "--interval"  states that this is not a plain disk path
2729       but rather an interval reader description string.  The component  Flags
2730       modifies the further interpretation:
2731       "local_fs" demands to read from a file depicted by the path in Source.
2732       "imported_iso"  demands  to  read  from  the -indev. This works only if
2733       -outdev is not the same as -indev. The Source component is ignored.
2734       "appended_partition_NNN" with a  decimal  number  NNN  works  only  for
2735       -boot_image  bootspecs  which  announce  El  Torito  boot  image paths:
2736       bin_path=, efi_path=.  The number gives the partition  number  as  used
2737       with the corresponding command -append_partition.
2738       The  component  Interval consists of two byte address numbers separated
2739       by a "-" character. E.g. "0-429" means to read bytes 0 to 429.
2740       The component Zeroizers  consists  of  zero  or  more  comma  separated
2741       strings.   They  define  which  part  of the read data to zeroize. Byte
2742       number 0 means the byte read from the  Interval  start  address.   Each
2743       string may be one of:
2744       "zero_mbrpt"  demands  to  zeroize the MBR partition table if bytes 510
2745       and 511 bear the MBR signature 0x55 0xaa.
2746       "zero_gpt" demands to check for a GPT header in bytes 512 to  1023,  to
2747       zeroize it and its partition table blocks.
2748       "zero_apm"  demands  to  check  for  an  APM block 0 and to zeroize its
2749       partition table blocks.
2750       Start_byte"-"End_byte demands to zeroize the  read-in  bytes  beginning
2751       with number Start_byte and ending after End_byte.
2752       The component Source is the file path with flag "local_fs", and ignored
2753       with flag "imported_iso".
2754       Byte numbers may be scaled by a suffix  out  of  {k,m,g,t,s,d}  meaning
2755       multiplication  by  {1024,  1024k,  1024m,  1024g, 2048, 512}. A scaled
2756       value end number depicts the last byte of the scaled range.
2757       E.g. "0d-0d" is "0-511".
2758       Examples:
2759         "local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso"
2760         "imported_iso:45056d-47103d::"
2761
2762       -boot_image "any"|"isolinux"|"grub"
2763                   "discard"|"keep"|"patch"|"replay"|"show_status"|
2764                   bootspec|"next"
2765              Define the equipment of the emerging filesystem with boot  entry
2766              points.
2767              With  systems  which  boot  via  BIOS or EFI this is a set of El
2768              Torito  boot  images,  possibly  MBR  boot  code,  and  possibly
2769              partition  tables  of type MBR, GPT, or APM.  Such file sets get
2770              produced by boot loader systems like ISOLINUX or GRUB.
2771
2772              Each -boot_image command has two parameters: type  and  setting.
2773              More  than  one  -boot_image  command  may be used to define the
2774              handling of one or more boot images. Sequence matters.
2775              Types isolinux and grub care for known peculiarities.  Type  any
2776              makes no assumptions about the origin of the boot images.
2777
2778              When  loading  an ISO filesystem, system area and El Torito boot
2779              images get loaded, too. The default behavior  is  not  to  write
2780              loaded El Torito boot images and to write the loaded system area
2781              content without alterations.
2782              discard gives up the El Torito boot catalog and its boot images.
2783              regardless  whether  loaded from an ISO filesystem or defined by
2784              commands.  Any BIOS or EFI related  boot  options  get  revoked.
2785              Nevertheless,  loaded  system  area data stay valid. If desired,
2786              they have to be erased by
2787               -boot_image any system_area=/dev/zero
2788              keep keeps or copies El Torito boot images unaltered and  writes
2789              a new catalog.
2790              patch applies patching to existing El Torito boot images if they
2791              seem to bear a boot info table.
2792              A boot info table needs to be patched when the boot  image  gets
2793              newly introduced into the ISO image or if an existing image gets
2794              relocated.  This is automatically done  if  type  "isolinux"  or
2795              "grub" is given, but not with "any".
2796              If  patching is enabled, then boot images from previous sessions
2797              will be checked whether they seem to bear a boot info table.  If
2798              not,  then they stay unpatched. This check is not infallible. So
2799              if you do know that the  images  need  no  patching,  use  "any"
2800              "keep".     "grub"   "patch"   will   not   patch   EFI   images
2801              (platform_id=0xef).
2802              replay is a more modern version of "patch", which not only cares
2803              for   existing  El  Torito  boot  equipment  but  also  for  the
2804              recognizable boot provisions in the System Area. It discards any
2805              existing  -boot_image setting and executes the commands proposed
2806              by command -report_el_torito "cmd".
2807              This action will only succeed if the file objects  mentioned  in
2808              the   output   of  command  -report_el_torito  "cmd"  are  still
2809              available. Do not  remove  or  rename  boot  image  files  after
2810              -indev.
2811              Drop unknown El Torito:  -boot_image "any" "discard"
2812              Maintain recognizable stuff:  -boot_image "any" "replay"
2813              El Torito only for GRUB:  -boot_image "grub" "patch"
2814              El Torito only for ISOLINUX:  -boot_image "isolinux" "patch"
2815              show_status  will  print  what  is  known  about the loaded boot
2816              images and their designated fate.
2817
2818              A bootspec is a word of the  form  name=value.  It  is  used  to
2819              describe  the  parameters  of  a boot feature.  The names "dir",
2820              "bin_path", "efi_path" lead to El Torito bootable images.   Name
2821              "system_area"  activates  a  given  file  as  MBR  or other disk
2822              header.
2823              On all media types this is possible within the first session. In
2824              further  sessions  an  existing boot image can get replaced by a
2825              new one, but depending on the  media  type  this  may  have  few
2826              effect at boot time. See above.
2827              El  Torito  boot  images  have  to  be added to the ISO image by
2828              normal means (image  loading,  -map,  -add,  ...).  In  case  of
2829              ISOLINUX  the  files should reside either in ISO image directory
2830              /isolinux or in /boot/isolinux .  In that case  it  suffices  to
2831              use     as     bootspec     the    text    "dir=/isolinux"    or
2832              "dir=/boot/isolinux". E.g.:
2833               -boot_image isolinux dir=/boot/isolinux
2834              which bundles these individual settings:
2835               -boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
2836               -boot_image isolinux cat_path=/boot/isolinux/boot.cat
2837               -boot_image isolinux load_size=2048
2838               -boot_image any boot_info_table=on
2839              An El Torito boot catalog file gets inserted into the ISO  image
2840              with  address  cat_path= with the first -boot_image "any" "next"
2841              or at -commit time.  It is  subject  to  normal  -overwrite  and
2842              -reassure  processing  if  there is already a file with the same
2843              name.  The catalog lists the boot images and is read by the boot
2844              facility  to  choose  one  of  the  boot  images.  But it is not
2845              necessary that it appears in the directory tree at all. One  may
2846              hide  it  in  all trees by cat_hidden=on.  Other possible values
2847              are "iso_rr", "joliet", "hfsplus", and the default  "off".   The
2848              timestamps  of  the  boot  catalog  file are refreshed at commit
2849              time.  Command -volume_date "uuid" can  be  used  to  set  their
2850              value.
2851              bin_path= depicts an El Torito boot image file, a binary program
2852              which is to be started by the hardware boot facility  (e.g.  the
2853              BIOS) at boot time.
2854              efi_path= depicts an El Torito boot image file that is ready for
2855              EFI booting. This is normally a FAT filesystem image not  larger
2856              than  65535 blocks of 512 bytes (= 32 MiB - 512).  Its load_size
2857              is determined automatically, no boot info table gets written, no
2858              boot medium gets emulated, platform_id is 0xef.
2859              emul_type=   can   be   one   of   "no_emulation",  "hard_disk",
2860              "diskette".  It controls the boot medium  emulation  code  of  a
2861              boot   image.    The  default  "no_emulation"  is  suitable  for
2862              ISOLINUX, GRUB, FreeBSD cdboot.
2863              load_size= is a value which depends on the boot image.   Default
2864              is 2048 which matches the expectations of most boot images.  The
2865              special value "full" means the full size of the boot image  file
2866              rounded  up  to  a multiple of 2048 bytes. Maximum is 33,552,384
2867              bytes.
2868              boot_info_table=on causes address patching to bytes 8 to  63  of
2869              the   boot   image   which   is   given  by  "any"  "bin_path=".
2870              "boot_info_table=off" disables this patching.
2871              grub2_boot_info=on causes address patching to byte 2548  of  the
2872              boot  image which is given by "any" "bin_path=".  The address is
2873              written as 64 bit little-endian number.  It  is  the  2KB  block
2874              address  of  the  boot  image content, multiplied by 4, and then
2875              incremented by 5.  "grub2_boot_info=off" disables this patching.
2876              platform_id= defines by a  hexadecimal  or  decimal  number  the
2877              Platform  ID  of the boot image. "0x00" is 80x86 PC-BIOS, "0x01"
2878              is PowerPC, "0x02" is Mac, "0xef" is EFI (decimal "239").
2879              id_string=text|56_hexdigits defines the ID string  of  the  boot
2880              catalog  section  where  the  boot  image will be listed. If the
2881              value consists of 56 characters [0-9A-Fa-f] then it is converted
2882              into  28  bytes,  else  the  first  28  characters become the ID
2883              string.  The ID string of  the  first  boot  image  becomes  the
2884              overall  catalog  ID.   It  is  limited  to 24 characters. Other
2885              id_strings become section IDs.
2886              sel_crit=hexdigits defines the Selection Criteria  of  the  boot
2887              image.   Up  to  20  bytes  get  read  from the given characters
2888              [0-9A-Fa-f].  They get attributed to the boot image entry in the
2889              catalog.
2890              next  ends  the definition of a boot image and starts a new one.
2891              Any following -bootimage bootspecs will affect  the  new  image.
2892              The first "next" discards loaded boot images and their catalog.
2893              system_area=disk_path  copies at most 32768 bytes from the given
2894              disk file to the very start of the ISO image.  This System  Area
2895              is  reserved  for  system  dependent  boot software, e.g. an MBR
2896              which can be used to boot from USB stick or hard disk.
2897              Other than an El Torito boot image, the file disk_path needs not
2898              to be added to the ISO image.
2899              -boot_image  isolinux system_area= implies "partition_table=on".
2900              In this case, the disk path should lead to one of  the  SYSLINUX
2901              files  isohdp[fp]x*.bin  or to a file which was derived from one
2902              of those files.  E.g. to the first 512 bytes  from  an  ISOLINUX
2903              isohybrid ISO image.
2904              In this case, El Torito boot images (dir=, bin_path=, efi_path=)
2905              may  be  augmented  by  isolinux  partition_entry=gpt_basdat  or
2906              isolinux    partition_entry=gpt_hfsplus,    and    by   isolinux
2907              partition_entry=apm_hfsplus.   The  boot  image  will  then   be
2908              mentioned in GPT as Basic Data or GPT HFS+ partition, and in APM
2909              as HFS+ partition.  The first three GPT partitions will also  be
2910              marked by MBR partitions.
2911              In   multi-session   situations  the  existing  System  Area  is
2912              preserved by default.  In in this case,  the  special  disk_path
2913              "."  prevents  reading  of  a  disk file but nevertheless causes
2914              adjustments in the loaded system area data. Such adjustments may
2915              get ordered by -boot_image commands.
2916              -boot_image any gpt_disk_guid=value controls whether an emerging
2917              GPT shall get a randomly generated disk GUID or whether the GUID
2918              is  supplied  by  the  user.   Value  "random" is default. Value
2919              "volume_date_uuid" produces a low quality GUID  from  the  value
2920              set by -volume_date "uuid".
2921              A  string  of 32 hex digits, or a RFC 4122 compliant GUID string
2922              may be used to set the disk GUID directly. UEFI  prescribes  the
2923              first  three  components  of  a  RFC  4122  GUID  string  to  be
2924              byte-swapped in the binary representation:
2925              E.g.  gpt_disk_guid=2303cd2a-73c7-424a-a298-25632da7f446  equals
2926              gpt_disk_guid=2acd0323c7734a42a29825632da7f446
2927              The  partition GUIDs get generated by minimally varying the disk
2928              GUID.
2929              -boot_image  any  part_like_isohybrid=on   enables   -boot_image
2930              isolinux   partition_entry=  even  if  no  -boot_image  isolinux
2931              system_area= is given.  No MBR partition  of type 0xee  emerges,
2932              even  if GPT gets produced.  Gaps between GPT and APM partitions
2933              will not be filled by more partitions.  Appended partitions  get
2934              mentioned in APM if other APM partitions emerge.
2935              -boot_image any iso_mbr_part_type=number sets the partition type
2936              of the MBR partition  which  represents  the  ISO  or  at  least
2937              protects it.
2938              Number  may  be  0x00 to 0xff. The text "default" re-enables the
2939              default types of the various occasions  to  create  an  ISO  MBR
2940              partition.   This is without effect if no such partition emerges
2941              by other  settings  or  if  the  partition  type  is  prescribed
2942              mandatorily like 0xee for GPT protective MBR or 0x96 for CHRP.
2943              If  instead  a  type_guid is given by a 32-digit hex string like
2944              a2a0d0ebe5b9334487c068b6b72699c7 or by a  structured  text  like
2945              EBD0A0A2-B9E5-4433-87C0-68B6B72699C7,  then  it  will be used as
2946              partition type if the ISO filesystem  appears  as  partition  in
2947              GPT.    In  MBR,  C12A7328-F81F-11D2-BA4B-00A0C93EC93B  will  be
2948              mapped to 0xef.  Any other GUID will be mapped to 0x83.
2949              grub2_mbr=disk_path   works   like   "any"   system_area=   with
2950              additional  patching  for  modern  GRUB  MBRs. The content start
2951              address of the first boot image is converted to a count  of  512
2952              byte blocks, and an offset of 4 is added.  The result is written
2953              as 64 bit little-endian number to byte address 0x1b0.
2954              This feature can be revoked either by grub2_mbr= with empty disk
2955              path, or by submitting a disk_path via system_area=.
2956              partition_table=on causes a simple partition table to be written
2957              into bytes 446 to 511 of the System Area.
2958              With type "isolinux" it shows a partition that begins at byte  0
2959              and it causes the LBA of the first boot image to be written into
2960              the  MBR.  For  the  first  session  this  works  only  if  also
2961              "system_area=" and "bin_path=" or "dir=" is given.
2962              With  types  "any"  and "grub" it shows a single partition which
2963              starts at byte 512 and ends where  the  ISO  image  ends.   This
2964              works with or without system_area= or boot image.
2965              Bootspecs  chrp_boot_part=,  prep_boot_part=, and efi_boot_part=
2966              overwrite this entry in the MBR partition table.
2967              If  types  "isolinux"  or  "grub"  are  set  to  "patch",   then
2968              "partition_table=on"  is  activated  without new boot image.  In
2969              this case the existing System Area gets checked whether it bears
2970              addresses   and   sizes   as   if   it  had  been  processed  by
2971              "partition_table=on". If so, then those parameters  get  updated
2972              when the new System Area is written.
2973              Special  "system_area=/dev/zero"  causes  32k of NUL-bytes.  Use
2974              this to discard an MBR which was loaded with the ISO image.
2975              appended_part_as=gpt marks partitions from -append_partition  in
2976              GPT  rather  than  in  MBR.  In this case the MBR shows a single
2977              partition of type 0xee which covers the whole output data.
2978              appended_part_as=mbr is the  default.  Appended  partitions  get
2979              marked in GPT only if GPT is produced because of other settings.
2980              If given  explicitly,  this  clears  setting  "gpt"  and  "apm".
2981              Nevertheless "apm" may be added to "mbr".
2982              appended_part_as=apm  marks partitions from -append_partition in
2983              APM additionally to "mbr" or "gpt".
2984              By default, appended partitions get marked in APM only if APM is
2985              produced    because    of    other    options    together   with
2986              part_like_isohybrid="on".
2987              chrp_boot_part=on causes a single partition in MBR which  covers
2988              the  whole  ISO  image and has type 0x96. This is not compatible
2989              with any other feature that produces MBR partition  entries.  It
2990              makes GPT unrecognizable.
2991              prep_boot_part=disk_path inserts the content of a data file into
2992              the image and marks it by an MBR partition  of  type  0x41.  The
2993              parts  of  the ISO image before and after this partition will be
2994              covered by further MBR partitions.  The data file is supposed to
2995              contain ELF executable code.
2996              efi_boot_part=disk_path  inserts the content of a data file into
2997              the  image  and  marks  it  by   a   GPT   partition.   If   not
2998              chrp_boot_part=on,  then  the  first  partition in MBR will have
2999              type 0xee to announce the presence of GPT.   The  data  file  is
3000              supposed to contain a FAT filesystem.
3001              Instead  of a disk_path, the word --efi-boot-image may be given.
3002              It exposes in GPT the content of the first El  Torito  EFI  boot
3003              image as EFI system partition. EFI boot images are introduced by
3004              bootspec efi_path=.  The affected EFI boot image cannot show  up
3005              in HFS+ because it is stored outside the HFS+ partition.
3006              partition_offset=2kb_block_adr  causes  a partition table with a
3007              single partition that begins at the given block address. This is
3008              counted  in  2048  byte  blocks,  not in 512 byte blocks. If the
3009              block address is non-zero  then  it  must  be  at  least  16.  A
3010              non-zero partition offset causes two superblocks to be generated
3011              and two sets of directory trees. The  image  is  then  mountable
3012              from its absolute start as well as from the partition start.
3013              The  offset  value  of  an  ISO  image gets preserved when a new
3014              session is added.  So the value defined here is only  in  effect
3015              if a new ISO image gets written.
3016              partition_hd_cyl=number  gives  the number of heads per cylinder
3017              for the partition table. 0 chooses a default value.  Maximum  is
3018              255.
3019              partition_sec_hd=number gives the number of sectors per head for
3020              the partition table. 0 chooses a default value. Maximum is 63.
3021              The product partition_sec_hd * partition_hd_cyl  *  512  is  the
3022              cylinder  size.  It should be divisible by 2048 in order to make
3023              exact  alignment  possible.   With   appended   partitions   and
3024              "appended_part_as=gpt"  there  is  no  limit  for  the number of
3025              cylinders. Else there may be at  most  1024  of  them.   If  the
3026              cylinder  size  is  too  small  to  stay  below  the limit, then
3027              appropriate  values  of   partition_hd_cyl   are   chosen   with
3028              partition_sec_hd   32  or  63.  If  the  image  is  larger  than
3029              8,422,686,720 bytes, then the cylinder size  constraints  cannot
3030              be fulfilled for MBR.
3031              partition_cyl_align=mode  controls  image  size  alignment to an
3032              integer number of cylinders. It is prescribed by isohybrid specs
3033              and  it  seems  to  please  program fdisk. Cylinder size must be
3034              divisible by  2048.   Images  larger  than  8,323,596,288  bytes
3035              cannot be aligned in MBR partition table.
3036              Mode  "auto"  is default. Alignment by padding happens only with
3037              "isolinux" "partition_table=on".
3038              Mode "on" causes alignment by padding with  "partition_table=on"
3039              for  any  type.   Mode  "all"  is  like  "on"  but  also pads up
3040              partitions from -append_partition to an aligned size.
3041              Mode "off" disables alignment for any type.
3042              mbr_force_bootable=mode   enforces   an   MBR   partition   with
3043              "bootable/active"  flag  if  options  like  partition_table=  or
3044              grub2_mbr= indicate production of a bootable MBR.  These options
3045              normally  cause  the flag to be set if there is an MBR partition
3046              of type other than 0xee or 0xef.  If no such  partition  exists,
3047              then  no  bootflag is set, unless mbr_force_bootable="on" forces
3048              creation of a dummy partition of type 0x00 which covers only the
3049              first block of the ISO image.
3050              If  no bootable MBR is indicated and a partition gets created by
3051              -append_partition,   then   mbr_force_bootable="on"   causes   a
3052              bootflag like it would do with a bootable MBR.
3053              mips_path=iso_rr_path  declares a data file in the image to be a
3054              MIPS Big Endian boot file and causes production of  a  MIPS  Big
3055              Endian Volume Header. This is mutually exclusive with production
3056              of other boot blocks like MBR.  It will overwrite the first  512
3057              bytes of any data provided by system_area=.  Up to 15 boot files
3058              can be declared by mips_path=.
3059              mipsel_path=iso_rr_path declares a data file in the image to  be
3060              the  MIPS  Little  Endian  boot file. This is mutually exclusive
3061              with other boot blocks.  It will overwrite the first  512  bytes
3062              of  any  data provided by system_area=.  Only a single boot file
3063              can be declared by mipsel_path=.
3064              sparc_label=text causes the production of a SUN Disk Label  with
3065              the given text as ASCII label. Partitions 2 to 8 may be occupied
3066              by appended images.  Partition 1 will always be the  ISO  image.
3067              See  command -append_partition.  The first 512 bytes of any data
3068              provided by system_area= will be overwritten.
3069              grub2_sparc_core=iso_rr_path causes the content address and size
3070              of  the  given file to be written after the SUN Disk Label. Both
3071              numbers are counted in bytes. The address is written as  64  bit
3072              big-endian  number  to byte 0x228. The size is written as 32 bit
3073              big-endian number to byte 0x230.
3074              hppa_cmdline=text sets the PALO command line for  HP-PA.  Up  to
3075              1023 characters are permitted by default. With hppa_hdrversion=4
3076              the limit is 127.
3077              Note that the first five hppa_ bootspecs are mandatory,  if  any
3078              of the hppa_ bootspecs is used. Only hppa_hdrversion= is allowed
3079              to be missing.
3080              hppa_bootloader=iso_rr_path designates the given path  as  HP-PA
3081              bootloader file.
3082              hppa_kernel_32=iso_rr_path designates the given path as HP-PA 32
3083              bit kernel file.
3084              hppa_kernel_64=iso_rr_path designates the given path as HP-PA 64
3085              bit kernel file.
3086              hppa_ramdisk=iso_rr_path  designates the given path as HP-PA RAM
3087              disk file.
3088              hppa_hdrversion=number chooses between  PALO  header  version  5
3089              (default)  and version 4.  For the appropriate value see in PALO
3090              source code: PALOHDRVERSION.
3091              alpha_boot=iso_rr_path declares a data file in the image  to  be
3092              the   DEC  Alpha  SRM  Secondary  Bootstrap  Loader  and  causes
3093              production of a  boot  sector  which  points  to  it.   This  is
3094              mutually  exclusive  with  production  of other boot blocks like
3095              MBR.
3096              mips_discard, sparc_discard, hppa_discard, alpha_discard  revoke
3097              any boot file declarations made for mips/mipsel, sparc, hppa, or
3098              alpha, respectively.  This removes  the  ban  on  production  of
3099              other boot blocks.
3100              hfsplus_serial=hexstring  sets  a string of 16 digits "0" to "9"
3101              and letters "a" to "f", which will  be  used  as  unique  serial
3102              number of an emerging HFS+ filesystem.
3103              hfsplus_block_size=number  sets  the allocation block size to be
3104              used when producing HFS+ filesystems. Permissible are 512, 2048,
3105              or 0.  The latter lets the program decide.
3106              apm_block_size=number  sets  the  block  size  to  be  used when
3107              describing partitions by an Apple Partition Map. Permissible are
3108              512, 2048, or 0. The latter lets the program decide.
3109              Note that size 512 is not compatible with production of GPT, and
3110              that size 2048 will not be mountable  -t  hfsplus  at  least  by
3111              older Linux kernels.
3112
3113       -append_partition partition_number type_code disk_path
3114              Cause  a  prepared  filesystem  image  to be appended to the ISO
3115              image and to be described by a partition table entry in  a  boot
3116              block  at  the  start  of  the emerging ISO image. The partition
3117              entry will bear the size of the submitted file rounded up to the
3118              next  multiple  of  2048  bytes  or  to the next multiple of the
3119              cylinder size.
3120              Beware of subsequent multi-session runs. The appended  partition
3121              will get overwritten.
3122              Partitions may be appended with boot block type MBR and with SUN
3123              Disk Label.
3124              With MBR:
3125              partition_number may be 1 to 4. Number 1 will put the whole  ISO
3126              image  into  the unclaimed space before partition 1. So together
3127              with most xorriso MBR features,  number  2  would  be  the  most
3128              natural choice.
3129              The type_code may be "FAT12", "FAT16", "Linux", or a hexadecimal
3130              number between 0x00 and 0xff. Not all those numbers  will  yield
3131              usable  results.  For  a list of MBR partition type codes search
3132              the Internet for "Partition Types" or run fdisk command "L".
3133              type_code may also be a type  GUID  as  plain  hex  string  like
3134              a2a0d0ebe5b9334487c068b6b72699c7  or  as  structured  text  like
3135              EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will  be  used  if  the
3136              partition      is      mentioned     in     GPT.     In     MBR,
3137              C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped to 0xef. Any
3138              other GUID will be mapped to 0x83.
3139              If  some  other  command  causes the production of GPT, then the
3140              appended partitions will be mentioned there too.
3141              The disk_path must provide the necessary data  bytes  at  commit
3142              time.   An  empty  disk_path disables this feature for the given
3143              partition number.
3144              With SUN Disk Label (selected by -boot_image any sparc_label=):
3145              partition_number may be 2 to 8. Number 1 will always be the  ISO
3146              image.   Partition  start  addresses are aligned to 320 KiB. The
3147              type_code does not matter. Submit 0x0.
3148              Partition image name "." causes the partition to become  a  copy
3149              of the next lower valid one.
3150
3151       Jigdo Template Extraction:
3152
3153       From  man  genisoimage: "Jigdo is a tool to help in the distribution of
3154       large files like CD and DVD images; see  http://atterer.net/jigdo/  for
3155       more details. Debian CDs and DVD ISO images are published on the web in
3156       jigdo format to allow end users to download them more efficiently."
3157       xorriso can produce a .jigdo and  a  .template  file  together  with  a
3158       single-session  ISO  image.   The  .jigdo  file  contains checksums and
3159       symbolic file addresses.  The .template file  contains  the  compressed
3160       ISO  image  with  reference  tags  instead  of the content bytes of the
3161       listed files.
3162       Input for this process are the normal arguments for a  xorriso  session
3163       on  a blank -outdev, and a .md5 file which lists those data files which
3164       may be listed in the .jigdo  file  and  externally  referenced  in  the
3165       .template  file.   Each designated file is represented in the .md5 file
3166       by a single text line:
3167       MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks,  2
3168       blanks, symbolic file address
3169       The  file  address in an .md5 line has to bear the same basename as the
3170       disk_path of the file which it shall match. The directory path  of  the
3171       file address is decisive for To=From mapping, not for file recognition.
3172       After To=From mapping, the file address gets written  into  the  .jigdo
3173       file.  Jigdo  restore  tools  will  convert these addresses into really
3174       reachable data source addresses from which they can read.
3175       If the list of jigdo parameters is not empty, then xorriso will  refuse
3176       to write to non-blank targets, it will disable multi-session emulation,
3177       and padding will be counted as part of the ISO image.
3178
3179       -jigdo parameter_name value
3180              Clear  Jigdo  Template  Extraction  parameter  list  or  add   a
3181              parameter  to  that list.  The alias names are the corresponding
3182              genisoimage options. They are accepted  as  parameter  names  as
3183              well.   Especially  they  are  recognized  by  the  -as  mkisofs
3184              emulation command.
3185              Parameter clear with any  value  empties  the  whole  list.   No
3186              .jigdo and .template file will be produced.
3187              template_path sets the disk_path for the .template file with the
3188              holed and compressed ISO image copy.
3189              Alias: -jigdo-template
3190              jigdo_path sets the disk_path  for  the  .jigdo  file  with  the
3191              checksums  and  download  addresses  for  filling  the  holes in
3192              .template.
3193              Alias: -jigdo-jigdo
3194              md5_path sets the disk_path where to find the .md5 input file.
3195              Alias: -md5-list
3196              min_size sets the minimum size for a data file to be  listed  in
3197              the .jigdo file and being a hole in the .template file.
3198              Alias: -jigdo-min-file-size
3199              exclude  adds  a  regular  expression  pattern  which  will  get
3200              compared with the absolute disk_path of any data file.  A  match
3201              causes the file to stay in .template in any case.
3202              Alias: -jigdo-exclude
3203              demand_md5  adds  a  regular  expression  pattern which will get
3204              compared with the absolute disk_path of any data file  that  was
3205              not found in the .md5 list. A match causes a MISHAP event.
3206              Alias: -jigdo-force-md5
3207              mapping  adds a string pair of the form To=From to the parameter
3208              list.  If a data file gets listed in the .jigdo file, then it is
3209              referred  by  the  file  address from its line in the .md5 file.
3210              This file address gets checked whether it begins with  the  From
3211              string.  If  so,  then  this  string  will be replaced by the To
3212              string and a ':' character, before it goes into the .jigdo file.
3213              The From string should end by a '/' character.
3214              Alias: -jigdo-map
3215              compression chooses one of "bzip2" or "gzip" for the compression
3216              of the template file. The jigdo file is put out uncompressed.
3217              Alias: -jigdo-template-compress
3218              checksum_iso chooses one or more  of  "md5",  "sha1",  "sha256",
3219              "sha512"  for the auxiliary "# Image Hex" checksums in the jigdo
3220              file. The value may e.g.   look  like  "md5,sha1,sha512".  Value
3221              "all"  chooses  all  available  algorithms.  Note that MD5 stays
3222              always enabled.
3223              Alias: -checksum_algorithm_iso
3224              checksum_template is like checksum_iso but for "# Template Hex".
3225              Alias: -checksum_algorithm_template
3226
3227       Character sets:
3228
3229       File names are strings of non-zero bytes with 8 bit each. Unfortunately
3230       the  same  byte  string  may  appear  as  different  peculiar  national
3231       characters on differently nationalized terminals.  The meanings of byte
3232       codes  are  defined  in  character sets which have names. Shell command
3233       iconv -l lists them.
3234       The file names on hard disk are assumed to  be  encoded  by  the  local
3235       character  set  which is also used for the communication with the user.
3236       Byte codes 32 to 126 of the local character set must match the US-ASCII
3237       characters of the same code. ISO-8859 and UTF-8 fulfill this demand.
3238       By  default,  xorriso  uses  the character set as told by shell command
3239       "locale" with argument "charmap". This may be influenced by environment
3240       variables  LC_ALL,  LC_CTYPE, or LANG and should match the expectations
3241       of the terminal.  In some situations it may be necessary to set  it  by
3242       command -local_charset.
3243       Local  character  sets  should  not  matter  as  long  as  only english
3244       alphanumeric characters are used for file  names  or  as  long  as  all
3245       writers  and  readers  of  the  media use the same local character set.
3246       Outside these constraints it may be necessary to  let  xorriso  convert
3247       byte codes from and to other character sets.
3248       The  Rock Ridge file names in ISO filesystems are assumed to be encoded
3249       by the input character set.   The  Rock  Ridge  file  names  which  get
3250       written  with  ISO  filesystems will be encoded by the output character
3251       set.
3252       The sets can be  defined  independently  by  commands  -in_charset  and
3253       -out_charset.  Normally  one  will have both identical, if ever.  Other
3254       than the local character set, these two character sets may deviate from
3255       US-ASCII.
3256       The  output  character  sets  for Joliet and HFS+ are not influenced by
3257       these commands. Joliet uses output character set UCS-2 or UTF-16.  HFS+
3258       uses UTF-16.
3259       The  default  output charset is the local character set of the terminal
3260       where xorriso runs. So by default no conversion happens  between  local
3261       filesystem  names  and  emerging  Rock  Ridge  names  in the image. The
3262       situation stays ambiguous and the reader has to riddle  what  character
3263       set was used.
3264       By command -auto_charset it is possible to attribute the output charset
3265       name to the image. This makes the situation unambiguous.  But  if  your
3266       terminal  character  set  does not match the character set of the local
3267       file names, then this attribute can  become  plainly  wrong  and  cause
3268       problems  at  read  time.   To  prevent  this  it is necessary to check
3269       whether the terminal properly displays all  intended  filenames.  Check
3270       especially the exotic national characters.
3271       To  enforce  recording  of  a particular character set name without any
3272       conversion at image generation time, set -charset and -local_charset to
3273       the  desired  name, and enable -backslash_codes to avoid evil character
3274       display on your terminal.
3275
3276       -charset character_set_name
3277              Set the character set from which  to  convert  file  names  when
3278              loading an image and to which to convert when writing an image.
3279
3280       -local_charset character_set_name
3281              Override  the system assumption of the local character set name.
3282              If  this  appears  necessary,  one  should   consider   to   set
3283              -backslash_codes  to  "on"  in  order  to avoid dangerous binary
3284              codes being sent to the terminal.
3285
3286       Exception processing:
3287
3288       Since  the  tasks  of  xorriso  are  manifold  and  prone  to  external
3289       influence,  there  may  arise the need for xorriso to report and handle
3290       problem events.
3291       Those events get classified when  they  are  detected  by  one  of  the
3292       software  modules  and  forwarded  to  reporting and evaluation modules
3293       which decide about reactions. Event classes are sorted by severity:
3294       "NEVER" The upper end of the severity spectrum.
3295       "ABORT" The program is being aborted and on its way to end.
3296       "FATAL" The main purpose of the run failed  or  an  important  resource
3297       failed unexpectedly.
3298       "FAILURE" An important part of the job could not be performed.
3299       "MISHAP" A FAILURE which can be tolerated during ISO image generation.
3300       "SORRY" A less important part of the job could not be performed.
3301       "WARNING" A situation is suspicious of being not intended by the user.
3302       "HINT" A proposal to the user how to achieve better results.
3303       "NOTE" A harmless information about noteworthy circumstances.
3304       "UPDATE" A pacifier message during long running operations.
3305       "DEBUG" A message which would only interest the program developers.
3306       "ALL" The lower end of the severity spectrum.
3307
3308       -abort_on severity
3309              Set the severity threshold for events to abort the program.
3310              Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY"
3311              It may become necessary to abort the program anyway, despite the
3312              setting by this command. Expect not many "ABORT"  events  to  be
3313              ignorable.
3314              A  special  property of this command is that it works preemptive
3315              if given as program start argument.  I.e.  the  first  -abort_on
3316              setting  among the start arguments is in effect already when the
3317              first operations of xorriso begin. Only  "-abort_on"  with  dash
3318              "-" is recognized that way.
3319
3320       -return_with severity exit_value
3321              Set  the  threshold and exit_value to be returned at program end
3322              if no abort has happened. This is to  allow  xorriso  to  go  on
3323              after  problems  but to get a failure indicating exit value from
3324              the program, nevertheless.  Useful is a  value  lower  than  the
3325              -abort_on threshold, down to "WARNING".
3326              exit_value may be either 0 (indicating success to the starter of
3327              the  program)  or  a  number  between  32  and  63.  Some  other
3328              exit_values  are  used  by  xorriso  if  it decides to abort the
3329              program run:
3330              1=abort due to external signal
3331              2=no program arguments given
3332              3=creation of xorriso main object failed
3333              4=failure to start libburnia-project.org libraries
3334              5=program abort during argument processing
3335              6=program abort during dialog processing
3336
3337       -report_about severity
3338              Set the threshold for events to be reported.
3339              Useful:  "SORRY", "WARNING", "HINT", "NOTE", "UPDATE",  "DEBUG",
3340              "ALL"
3341              Regardless  what  is  set  by -report_about, messages get always
3342              reported if they reach the severity threshold of -abort_on .
3343              Event messages are sent to the info channel "I" which is usually
3344              stderr  but  may  be  influenced  by  command -pkt_output.  Info
3345              messages which  belong  to  no  event  get  attributed  severity
3346              "NOTE".
3347              A   special   property   of  this  command  is  that  the  first
3348              -report_about setting among the start  arguments  is  in  effect
3349              already  when  the  first  operations  of  xorriso  begin.  Only
3350              "-report_about" with dash "-" is recognized that way.
3351
3352       -signal_handling mode
3353              Control the installation of a signal handler which  shall  react
3354              on  external  signals  (e.g.  from  program  "kill" or from keys
3355              Ctrl+C) or on signals caused by severe program errors.
3356              Mode "on" is the default. It uses the signal handler of  libburn
3357              which  produces  ugly messages but puts much effort in releasing
3358              optical drives before xorriso ends.
3359              Mode "off" as first -signal_handling among the  start  arguments
3360              prevents all own signal precautions of xorriso. Inherited signal
3361              handler settings stay as they are.
3362              It works like "sig_dfl" if given after other signal handling was
3363              already established at program start.
3364              Mode  "sig_dfl"  uses  the  system  provided default handling of
3365              signals, which is normally a sudden abort  of  the  program.  To
3366              prevent  stuck  drives,  the  libburn  handler  is  used  during
3367              burning, blanking, and formatting on MMC drives.
3368              Mode "sig_ign" tries to ignore as many signal types as possible.
3369              This  imposes  the  risk  that  xorriso  refuses  to  end  until
3370              externally kill -9 if performed.  kill -9 then imposes the  risk
3371              that  the  drive is left in unusable state and needs poweroff to
3372              be reset. So during burning, blanking, and formatting  wait  for
3373              at least their normal run time before killing externally.
3374              A   special   property   of  this  command  is  that  the  first
3375              -signal_handling setting among the start arguments is in  effect
3376              already  when  the  first  operations  of  xorriso  begin.  Only
3377              "-signal_handling" with dash "-" is recognized that way.
3378
3379       -error_behavior occasion behavior
3380              Control the program behavior at problem  event  occasions.   For
3381              now  this  applies  to  occasions "image_loading" which is given
3382              while an image tree is  read  from  the  input  device,  and  to
3383              "file_extraction"  which  is  given  with  osirrox commands like
3384              -extract.
3385              With "image_loading" there are three behaviors available:
3386              "best_effort" goes on with reading after  events  with  severity
3387              below FAILURE if the threshold of command -abort_on allows this.
3388              "failure"  aborts  image tree reading on first event of at least
3389              SORRY.  It issues an own FAILURE event.  This is the default.
3390              "fatal" acts like "failure" but issues the own event as FATAL.
3391              With occasion "file_extraction" there are three behaviors:
3392              "keep" maintains incompletely extracted files on disk.  This  is
3393              the default.
3394              "delete"  removes  files which encountered errors during content
3395              extraction.
3396              "best_effort" starts a revovery attempt by means of -extract_cut
3397              if  the  file content stems from the loaded ISO image and is not
3398              filtered.
3399
3400       Dialog mode control:
3401
3402       -dialog "on"|"off"|"single_line"
3403              Enable or  disable  to  enter  dialog  mode  after  all  program
3404              arguments  are  processed.   In  dialog  mode  input  lines  get
3405              prompted via readline or from stdin.
3406              If no -abort_on  severity  was  set  when  dialog  starts,  then
3407              "NEVER"  is  set  to avoid abort in most cases of wrong input or
3408              other problems. Before dialog begins, the default  is  "FAILURE"
3409              which e.g. aborts on unknown commands.
3410              Mode  "on" supports input of newline characters within quotation
3411              marks  and  line  continuation  by  trailing  backslash  outside
3412              quotation marks.  Mode "single_line" does not.
3413
3414       -page length width
3415              Describe  terminal  to the text pager. See also above, paragraph
3416              Result pager.
3417              If parameter length is nonzero then the user gets prompted after
3418              that number of terminal lines. Zero length disables paging.
3419              Parameter  width  is the number of characters per terminal line.
3420              It is used to compute the number of  terminal  lines  which  get
3421              occupied by an output line.  A usual terminal width is 80.
3422
3423       -use_readline "on"|"off"
3424              If "on" then use readline for dialog. Else use plain stdin.
3425              See also above, paragraph Dialog, Readline, Result pager.
3426
3427       -reassure "on"|"tree"|"off"
3428              If "on" then ask the user for "y" or "n":
3429              before deleting or overwriting any file in the ISO image,
3430              before overwriting any disk file during restore operations,
3431              before rolling back pending image changes,
3432              before committing image changes to media,
3433              before changing the input drive,
3434              before blanking or formatting media,
3435              before ending the program.
3436              With  setting  "tree"  the  reassuring prompt will appear for an
3437              eventual directory only once and not for each file in its  whole
3438              subtree.
3439              Setting  "off"  silently kills any kind of image file object and
3440              performs above irrevocable actions.
3441              To really produce user prompts, command -dialog needs to be  set
3442              to  "on".   Note  that  the prompt does not appear in situations
3443              where file removal is forbidden by command -overwrite. -reassure
3444              only  imposes  an  additional  curb  for  removing existing file
3445              objects.
3446              Be aware that file  objects  get  deleted  from  the  ISO  image
3447              immediately  after  confirmation.  They  are  gone  even  if the
3448              running  command  gets  aborted  and  its  desired  effect  gets
3449              revoked. In case of severe mess-up, consider to use -rollback to
3450              revoke the whole session.
3451
3452       Drive and media related inquiry actions:
3453
3454       -devices
3455              Show list of available MMC drives with the  addresses  of  their
3456              libburn standard device files.
3457              This  is  only  possible  when no ISO image changes are pending.
3458              After this command was executed, there is no drive  current  and
3459              no image loaded.
3460              In  order  to  be  visible, a device has to offer rw-permissions
3461              with its libburn standard device file. Thus it might be only the
3462              superuser who is able to see all drives.
3463              Drives which are occupied by other processes get not shown.
3464
3465       -device_links
3466              Like  -devices,  but  presenting  the  drives  with addresses of
3467              symbolic links which point to the actual device files.
3468              Modern GNU/Linux systems may shuffle drive addresses  from  boot
3469              to  boot.   The  udev  daemon  is supposed to create links which
3470              always point  to  the  same  drive,  regardless  of  its  system
3471              address.   The command -device_links shows the addresses of such
3472              links if they begin by "/dev/dvd" or "/dev/cd".  Precedence  is:
3473              "dvdrw", "cdrw", "dvd", "cdrom", "cd".
3474
3475       -toc
3476              Show  media  specific  tables  of  content.  This is the session
3477              history of the medium, not the ISO image directory tree.
3478              In case of overwriteable media holding a valid ISO image, it may
3479              happen  that  only a single session gets shown. But if the first
3480              session on the overwriteable media was written by xorriso then a
3481              complete session history can be emulated.
3482              A  drive  which  is  incapable  of writing may show any media as
3483              CD-ROM or DVD-ROM with only one or two sessions on it. The  last
3484              of these sessions is supposed to be the most recent real session
3485              then.
3486              Some read-only drives and media show no usable  session  history
3487              at all.  Command -rom_toc_scan might help.
3488              If  input device and output device are both acquired and not the
3489              same, then both tables-of-content get shown.
3490
3491       -toc_of "in"|"out"|"all"[":short"]
3492              Like  command  -toc  but  explicitly  choosing   which   drive's
3493              table-of-content to show. "in" shows -indev or -dev, "out" shows
3494              -outdev or -dev, "all" shows the same as -toc.
3495              If ":short" is appended to the drive choosing word, then only  a
3496              short summary of drive state and medium content is printed.
3497              As  further  difference  to  -toc,  this  command  does not emit
3498              FAILURE events if the desired drive is not acquired.
3499
3500       -mount_cmd drive entity id path
3501              Emit an appropriate command line for mounting  the  ISO  session
3502              indicated by drive, entity and id.  The result will be different
3503              on GNU/Linux and on FreeBSD or NetBSD.
3504              drive can be "indev" or "outdev" to  indicate  already  acquired
3505              drives,  or  it  can  be  the  path of a not yet acquired drive.
3506              Prefix "stdio:" for non-MMC drives is not mandatory.
3507              For entity and id, see also command -load. They must  be  either
3508              "sbsector"  with the superblock sector address as id, or "track"
3509              with a track number as id, or "session" with a  session  number,
3510              or  "volid"  with  a search pattern for the volume id, or "auto"
3511              with which any text as id mounts the first  track  of  the  last
3512              session.
3513              path  will  be  used  as mount point and must already exist as a
3514              directory on disk.
3515              The command gets printed to  the  result  channel.  See  command
3516              -mount for direct execution of this command.
3517
3518       -mount_opts option[:option...]
3519              Set  options  which  influence  -mount and -mount_cmd. Currently
3520              there is only  option  "exclusive"  which  is  default  and  its
3521              counterpart  "shared".  The latter causes xorriso not to give up
3522              the affected drive with command -mount.  On  GNU/Linux  it  adds
3523              mount  option  "loop"  which  may  enable  mounting  of  several
3524              sessions of the same block device at the same time.  One  should
3525              not  write  to a mounted optical medium, of course. Take care to
3526              umount all sessions before ejecting.
3527
3528       -session_string drive entity id format
3529              Print to the result channel a text which gets composed according
3530              to format and the parameters of the addressed session.
3531              Formats  "linux:"path  or  "freebsd:"path  produce the output of
3532              -mount_cmd for the given operating systems.
3533              In other texts xorriso will substitute the  following  parameter
3534              names.  An optional prefix "string:" will be removed.
3535              "%device%"  will  be substituted by the mountable device path of
3536              the drive address.
3537              "%sbsector%" will be substituted by the session start sector.
3538              "%track%", "%session%", "%volid%" will be substituted  by  track
3539              number, session number, or volume id of the depicted session.
3540
3541       -print_size
3542              Print  the  foreseeable  consumption of 2048 byte blocks by next
3543              -commit. This can last a while as a -commit  gets  prepared  and
3544              only  in  last  moment  is  revoked by this command.  The result
3545              depends on several settings and  also  on  the  kind  of  output
3546              device.   If  no  -jidgo  options  are  set  and not command -as
3547              "mkisofs" was used, then -padding (300 kB  by  default)  is  not
3548              counted as part of the image size.
3549              If  an  El  Torito  boot  image  file  is already depicted, then
3550              command -print_size  automatically  executes  -boot_image  "any"
3551              "next".   This  means  that  the  properties  of that boot image
3552              cannot be edited by subsequent commands.
3553
3554       -tell_media_space
3555              Print available space on the output medium and  the  free  space
3556              after   subtracting  already  foreseeable  consumption  by  next
3557              -commit.
3558              Note that the title  of  the  prediction  "After  commit  :"  is
3559              misleading.   It is rather the space that may still be filled in
3560              this session without making the next -commit  fail  from  medium
3561              overflow.
3562              The  free  space  after  the  next  -commit  might be smaller by
3563              several MB.  This depends on medium  type,  number  of  recorded
3564              sessions, and drive habits.
3565
3566       -pvd_info
3567              Print  various  ID  strings and timestamps which can be found in
3568              loaded ISO images. Some of the IDs may be  changed  by  commands
3569              like -volid or -publisher.  For these IDs -pvd_info reports what
3570              would be written with the next -commit.  The timestamps get  not
3571              automatically  propagated  from  loaded  image  to newly written
3572              image.  The  ones  for  new  images  may  be  set   by   command
3573              -volume_date.   See  there  for  the  meaning  of the particular
3574              timestamps.
3575
3576       -report_el_torito mode
3577              With mode plain print a report about the  information  found  in
3578              the El Torito boot catalog of the loaded ISO image.
3579              With  mode  help  print a text which explains the meaning of the
3580              lines put out by "plain".
3581              Mode cmd tries to print the xorriso commands which are necessary
3582              to produce the found boot equipment: disk identifiers, El Torito
3583              boot images, and System Area. Disk identifiers are strings which
3584              the   booting  operating  system  might  use  to  find  the  ISO
3585              filesystem from where it comes. Currently known is  the  use  of
3586              volume id and modification date.
3587              The  intended  use  case  is  modification  of the filesystem by
3588              having -indev  and  -outdev  pointing  to  different  images  or
3589              drives.    The  result  might  be  insufficient,  if  the  found
3590              equipment cannot be produced by xorriso.  Various  SORRY  events
3591              may  arise  in  this case, but it is not guaranteed that xorriso
3592              recognizes all its insufficiencies.
3593              Mode as_mkisofs tries to print the xorriso -as mkisofs  options,
3594              which  are  necessary  to  produce  the  found  equipment.   The
3595              intended use case is to use the mounted filesystem as input tree
3596              together with the printed options.
3597
3598       -report_system_area mode
3599              With  mode  plain  print a report about the information found in
3600              the System Area of the loaded ISO image. The report consists  of
3601              zero  to many lines with a header text, a colon, and information
3602              text.
3603              With mode help print a text which explains the  meaning  of  the
3604              lines  put  out  by  "plain". You probably will have to look for
3605              more documentation which explains the technical details  of  the
3606              mentioned boot facilities.
3607              Modes    cmd    and    as_mkisofs   work   like   with   command
3608              -report_el_torito. See above.
3609              With mode gpt_disk_guid print the GPT disk GUID  of  the  loaded
3610              ISO  in  RFC  4122  text  format  to  result  channel. It is not
3611              considered an error if no GPT is present. In this  case  nothing
3612              is printed to result channel.
3613              With  mode  gpt_crc_of:disk_path read up to 32 KiB from the disk
3614              file with the path  given  after  the  colon.  Compute  the  GPT
3615              compliant  CRC  number  and  print it to the result channel. The
3616              number is shown like "0x690fd979".  The  special  disk_path  "-"
3617              causes reading from standard input.
3618              With  mode make_guid print a pseudo-random GUID in RFC 4122 text
3619              format to result channel.
3620
3621       Navigation in ISO image and disk filesystem:
3622
3623       -cd iso_rr_path
3624              Change the current working directory in the ISO image.  This  is
3625              prepended to iso_rr_paths which do not begin with '/'.
3626              It is possible to set the working directory to a path which does
3627              not exist yet in the ISO image. The necessary parent directories
3628              will be created when the first file object is inserted into that
3629              virtual directory.  Use  -mkdir  if  you  want  to  enforce  the
3630              existence of the directory already at first insertion.
3631
3632       -cdx disk_path
3633              Change  the  current  working directory in the local filesystem.
3634              To be prepended to disk_paths which do not begin with '/'.
3635
3636       -pwd
3637              Tell the current working directory in the ISO image.
3638
3639       -pwdx
3640              Tell the current working directory in the local filesystem.
3641
3642       -ls iso_rr_pattern [***]
3643              List files in the ISO image which  match  shell  patterns  (i.e.
3644              with  wildcards  '*'  '?' '[a-z]').  If a pattern does not begin
3645              with '/' then it is compared with addresses relative to -cd.
3646              Directories are listed by their content rather  than  as  single
3647              file item.
3648              Pattern expansion may be disabled by command -iso_rr_pattern.
3649
3650       -lsd iso_rr_pattern [***]
3651              Like  -ls but listing directories as themselves and not by their
3652              content.  This resembles shell command ls -d.
3653
3654       -lsl iso_rr_pattern [***]
3655              Like -ls but also list some of the file attributes.  The  output
3656              format resembles shell command ls -ln.
3657              File type 'e' indicates the El Torito boot catalog.
3658              If  the  file has non-trivial ACL, then a '+' is appended to the
3659              permission info.  If the file is hidden, then 'I' for  "iso_rr",
3660              'J'  for  "joliet",  'A'  for "hfsplus", 'H' for multiple hiding
3661              gets appended.  Together with ACL it is 'i', 'j', 'a', 'h'.
3662
3663       -lsdl iso_rr_pattern [***]
3664              Like -lsd but also list some of the file attributes.  The output
3665              format resembles shell command ls -dln.
3666
3667       -lsx disk_pattern [***]
3668              List  files  in the local filesystem which match shell patterns.
3669              Patterns which do not begin with '/' are used relative to -cdx.
3670              Directories are listed by their content rather  than  as  single
3671              file item.
3672              Pattern expansion may be disabled by command -disk_pattern.
3673
3674       -lsdx disk_pattern [***]
3675              Like -lsx but listing directories as themselves and not by their
3676              content.  This resembles shell command ls -d.
3677
3678       -lslx disk_pattern [***]
3679              Like -lsx but also listing some of the file attributes.   Output
3680              format resembles shell command ls -ln.
3681
3682       -lsdlx disk_pattern [***]
3683              Like -lsdx but also listing some of the file attributes.  Output
3684              format resembles shell command ls -dln.
3685
3686       -getfacl iso_rr_pattern [***]
3687              Print the access permissions of the given files in the ISO image
3688              using  the format of shell command getfacl. If a file has no ACL
3689              then it gets fabricated from the -chmod  settings.  A  file  may
3690              have  a  real  ACL if it was introduced into the ISO image while
3691              command -acl was set to "on".
3692
3693       -getfacl_r iso_rr_pattern [***]
3694              Like -gefacl  but  listing  recursively  the  whole  file  trees
3695              underneath eventual directories.
3696
3697       -getfattr iso_rr_pattern [***]
3698              Print  the xattr of the given files in the ISO image.  If a file
3699              has no such xattr then noting is printed for it.  The choice  of
3700              namespaces  depends  on  the  setting of command -xattr: "on" or
3701              "user" restricts  it  to  namespace  "user",  "any"  only  omits
3702              namespace "isofs".
3703
3704       -getfattr_r iso_rr_pattern [***]
3705              Like  -gefattr  but  listing  recursively  the  whole file trees
3706              underneath of directories.
3707
3708       -du iso_rr_pattern [***]
3709              Recursively list size of directories and files in the ISO  image
3710              which  match  one  of the patterns.  similar to shell command du
3711              -k.
3712
3713       -dus iso_rr_pattern [***]
3714              List size of directories and files in the ISO image which  match
3715              one of the patterns.  Similar to shell command du -sk.
3716
3717       -dux disk_pattern [***]
3718              Recursively  list  size  of  directories  and files in the local
3719              filesystem which match one of the  patterns.  Similar  to  shell
3720              command du -k.
3721
3722       -dusx disk_pattern [***]
3723              List size of directories and files in the local filesystem which
3724              match one of the patterns.  Similar to shell command du -sk.
3725
3726       -findx disk_path [-name pattern] [-type t] [-exec action [params]] --
3727              Like -find but operating on local filesystem and not on the  ISO
3728              image.  This is subject to the settings of -follow.
3729              -findx  accepts the same -type parameters as -find. Additionally
3730              it  recognizes  type  "mountpoint"  (or   "m")   which   matches
3731              subdirectories  which  reside  on  a different device than their
3732              parent. It never matches the disk_path given  as  start  address
3733              for -findx.
3734              -findx  accepts  the -exec actions as does -find. But except the
3735              following few actions it will always perform action "echo".
3736              in_iso reports the path if its counterpart  exists  in  the  ISO
3737              image.   For  this  the  disk_path  of  the  -findx command gets
3738              replaced by the iso_rr_path given as parameter.
3739              E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd --
3740              not_in_iso reports the path if its counterpart does not exist in
3741              the  ISO  image.  The  report format is the same as with command
3742              -compare.
3743              add_missing iso_rr_path_start adds the counterpart  if  it  does
3744              not  yet  exist  in the ISO image and marks it for "rm_merge" as
3745              non-removable.
3746              E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd --
3747              is_full_in_iso reports if  the  counterpart  in  the  ISO  image
3748              contains  files.  To  be  used  with  -type  "m" to report mount
3749              points.
3750              empty_iso_dir deletes all files from the counterpart in the  ISO
3751              image. To be used with -type "m" to truncate mount points.
3752              estimate_size  prints  a  lower  and  an upper estimation of the
3753              number of blocks which the found files together will  occupy  in
3754              the   emerging  ISO  image.   This  does  not  account  for  the
3755              superblock, for the directories in the -findx path, or for image
3756              padding.
3757              list_extattr  mode  prints a script to the result channel, which
3758              would use FreeBSD command setextattr to  set  the  file's  xattr
3759              name-value pairs of user namespace.  See -find for a description
3760              of parameter mode.
3761              E.g. -exec list_extattr e --
3762
3763       -compare disk_path iso_rr_path
3764              Compare  attributes  and  eventual  data  file  content   of   a
3765              fileobject in the local filesystem with a file object in the ISO
3766              image. The iso_rr_path may well point to an  image  file  object
3767              which is not yet committed, i.e. of which the data content still
3768              resides in the local filesystem. Such data content is  prone  to
3769              externally caused changes.
3770              If  iso_rr_path  is  empty then disk_path is used as path in the
3771              ISO image too.
3772              Differing attributes are reported in detail,  differing  content
3773              is  summarized.   Both  to  the  result  channel.  In case of no
3774              differences no result lines are emitted.
3775
3776       -compare_r disk_path iso_rr_path
3777              Like -compare but working recursively.  I.e.  all  file  objects
3778              below both addresses get compared whether they have counterparts
3779              below the other address and whether both counterparts match.
3780
3781       -compare_l disk_prefix iso_rr_prefix disk_path [***]
3782              Perform  -compare_r  with  each  of  the  disk_path  parameters.
3783              iso_rr_path   will  be  composed  from  disk_path  by  replacing
3784              disk_prefix by iso_rr_prefix.
3785
3786       -show_stream iso_rr_path [***]
3787              Display the content stream chain of data files in the ISO image.
3788              The  chain  consists of the iso_rr_name and one or more streams,
3789              separated by " < " marks.  A stream description consists of  one
3790              or  more  texts,  separated  by  ":" characters.  The first text
3791              tells the stream type, the following ones, if ever, describe its
3792              individual properties.  Frequently used types are:
3793               disk:'disk_path'  for local filesystem objects.
3794               image:'iso_rr_path'  for ISO image file objects.
3795               cout:'disk_path offset count'  for -cut_out files.
3796               extf:'filter_name' for external filters.
3797              Example:
3798               '/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'
3799
3800       -show_stream_r iso_rr_path [***]
3801              Like -show_stream but working recursively.
3802
3803       Evaluation of readability and recovery:
3804
3805       It  is not uncommon that optical media produce read errors. The reasons
3806       may be various and get obscured by error correction which is  performed
3807       by  the drives and based on extra data on the media. If a drive returns
3808       data then one can quite trust that they are valid. But at  some  degree
3809       of  read problems the correction will fail and the drive is supposed to
3810       indicate error.
3811       xorriso can scan a medium  for  readable  data  blocks,  classify  them
3812       according  to  their read speed, save them to a file, and keep track of
3813       successfully saved blocks for further tries on the same medium.
3814       By command -md5 checksums may get recorded with data  files  and  whole
3815       sessions.  These  checksums  are  reachable only via indev and a loaded
3816       image.  They work independently  of  the  media  type  and  can  detect
3817       transmission errors.
3818
3819       -check_media [option [option ...]] --
3820              Try  to  read  data blocks from the indev drive, optionally copy
3821              them to a disk file, and finally report  about  the  encountered
3822              quality.  Several  options  may  be  used  to modify the default
3823              behavior.
3824              The parameters given with  this  command  override  the  default
3825              settings    which    may    have   been   changed   by   command
3826              -check_media_defaults. See there for a description of  available
3827              options.
3828              The  result  list  tells  intervals  of  2 KiB blocks with start
3829              address, number of blocks and  quality.  Qualities  which  begin
3830              with  "+" are supposed to be valid readable data. Qualities with
3831              "-" are unreadable or corrupted data.  "0"  indicates  qualities
3832              which  are not covered by the check run or are regularly allowed
3833              to be unreadable (e.g. gaps between tracks).
3834              Alternatively it is possible to report damaged files rather than
3835              blocks.
3836              If  -md5 is "on" then the default mode what=tracks looks out for
3837              libisofs checksum tags for the ISO session data and checks  them
3838              against the checksums computed from the data stream.
3839
3840       -check_media_defaults [option [option ...]] --
3841              Preset  options  for  runs  of  -check_media,  -extract_cut  and
3842              best_effort file extraction.  Options  given  with  -check_media
3843              will  override  the  preset  options. -extract_cut will override
3844              some options automatically.
3845              An option consists of a keyword, a "=" character, and  a  value.
3846              Options may override each other. So their sequence matters.
3847              The default setting at program start is:
3848              use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
3849              time_limit=28800 item_limit=100000 data_to='' event=ALL
3850              abort_file=/var/opt/xorriso/do_abort_check_media
3851              sector_map='' map_with_volid=off patch_lba0=off report=blocks
3852              bad_limit=invalid slow_limit=1.0 chunk_size=0s async_chunks=0
3853              Option "reset=now" restores these startup defaults.
3854              Non-default options are:
3855              report="files"  lists  the  files  which use damaged blocks (not
3856              with  use=outdev).   The  format  is  like   with   find   -exec
3857              report_damage.  Note that a MD5 session mismatch marks all files
3858              of the session as damaged.  If  finer  distinction  is  desired,
3859              perform -md5 off before -check_media.
3860              report="blocks_files"   first  lists  damaged  blocks  and  then
3861              affected files.
3862              use="outdev" reads from the output drive instead  of  the  input
3863              drive. This avoids loading the ISO image tree from media.
3864              use="sector_map"  does  not  read  any  media but loads the file
3865              given by option sector_map= and processes this virtual outcome.
3866              what="disc"  scans  the  payload  range  of  a  medium   without
3867              respecting track gaps.
3868              what="image"  similar  to  "disc", but restricts scanning to the
3869              range of the ISO 9660 image, if present.
3870              min_lba=limit omits all blocks with addresses lower than limit.
3871              max_lba=limit switches to what=disc and omits all  blocks  above
3872              limit.
3873              chunk_size=size  sets  the  number  of  bytes  to be read in one
3874              low-level read operation.  This gets rounded down to full blocks
3875              of 2048 bytes. 0 means automatic size.
3876              retry="on"  forces read retries with minimal senseful chunk size
3877              when the normal read chunk produces a read error. This  size  is
3878              1s  with CD and stdio files, 16s with DVD (1 ECC Block), and 32s
3879              with BD (1 Cluster).  By default, retries are only enabled  with
3880              CD media. "retry=off" forbits retries for all media types.
3881              abort_file=disk_path  gives the path of the file which may abort
3882              a scan run. Abort happens if the file exists and  its  mtime  is
3883              not  older  than  the  start  time of the run. Use shell command
3884              "touch" to trigger this.  Other than  an  aborted  program  run,
3885              this  will  report the tested and untested blocks and go on with
3886              running xorriso.
3887              time_limit=seconds gives the number of seconds after  which  the
3888              scan shall be aborted. This is useful for unattended scanning of
3889              media which may else overwork the drive in its effort to squeeze
3890              out  some  readable  blocks.   Abort may be delayed by the drive
3891              gnawing on the last  single  read  operation.   Value  -1  means
3892              unlimited time.
3893              item_limit=number  gives  the  number of report list items after
3894              which to abort.  Value -1 means unlimited item number.
3895              data_to=disk_path copies the valid blocks to the given file.
3896              event=severity sets the given severity for a problem event which
3897              shall  be  issued  at the end of a check run if data blocks were
3898              unreadable or failed to match recorded MD5  checksums.  Severity
3899              "ALL" disables this event.
3900              sector_map=disk_path  tries  to read the file given by disk_path
3901              as sector bitmap and to store such a map  file  after  the  scan
3902              run.   The bitmap tells which blocks have been read successfully
3903              in previous runs.  It is the persistent memory for several scans
3904              on  the  same  medium, even with intermediate eject, in order to
3905              collect readable blocks whenever the drive is  lucky  enough  to
3906              produce  them.  The stored file contains a human readable TOC of
3907              tracks and their  start  block  addresses,  followed  by  binary
3908              bitmap data.
3909              By  default,  untested blocks are not considered bad, but rather
3910              as  intentionally  unread.  If   you   expect   time_limit=   or
3911              item_limit=   to   abort   the   run,   then   consider  to  use
3912              bad_limit="untested".
3913              map_with_volid="on" examines tracks whether they are ISO  images
3914              and  prints  their  volume  IDs  into  the human readable TOC of
3915              sector_map=.
3916              patch_lba0="on" transfers within the data_to= file a copy of the
3917              currently  loaded  session  head  to  the start of that file and
3918              patches it to be valid at that position.  This makes the  loaded
3919              session  the  last  valid session of the image file when it gets
3920              mounted or loaded as stdio: drive. New sessions will be appended
3921              after  this  last  session and will overwrite any sessions which
3922              have followed it.
3923              patch_lba0="force"  performs  patch_lba0="on"  even  if  xorriso
3924              believes that the copied data are not valid.
3925              patch_lba0=  may also bear a number. If it is 32 or higher it is
3926              taken as start address of the session to be copied. In this case
3927              it  is  not  necessary  to  have  an  -indev and a loaded image.
3928              ":force" may be appended after the number.
3929              bad_limit=threshold sets the  highest  quality  which  shall  be
3930              considered  as  damage.   Choose  one  of  "good",  "md5_match",
3931              "slow",   "partial",   "valid",   "untested",    "md5_mismatch",
3932              "invalid", "tao_end", "off_track", "unreadable".
3933              "valid"  and  "invalid" are qualities imported from a sector_map
3934              file.  "tao_end" and "off_track" are intentionally not readable,
3935              but  not  bad  either.   "partial"  are  blocks retrieved from a
3936              partially readable chunk. They are supposed to be  ok  but  stem
3937              from a suspicious neighborhood.
3938              "md5_match"  and  "md5_mismatch" regions overlap with regions of
3939              other quality.  The former is a strong confirmation for quality,
3940              the latter only tells that one or more blocks of the region must
3941              be wrong.
3942              By default bad_limit is set higher than  md5_mismatch,  so  that
3943              mismatches  are classified as quality class "0" rather than "-".
3944              This means that the sectors of a MD5 mismatch range are recorded
3945              in the sector_map as successfully read, if the drive handed them
3946              out at all. Set "bad_limit=md5_mismatch" to let  the  sector_map
3947              record the whole mismatching range as yet not retrieved.
3948              slow_limit=threshold  sets  the time threshold for a single read
3949              chunk to be considered slow. This may  be  a  fractional  number
3950              like 0.1 or 1.5.
3951              async_chunks=number   enables  asynchronous  MD5  processing  if
3952              number is 2 or larger.  In this case the given  number  of  read
3953              chunks  is  allocated  as  fifo buffer.  On very fast MMC drives
3954              try: chunk_size=64s async_chunks=16.
3955
3956       -check_md5 severity iso_rr_path [***]
3957              Compare the data content of the given files in the loaded  image
3958              with  their recorded MD5 checksums, if there are any. In case of
3959              any mismatch an event of the given severity is  issued.  It  may
3960              then be handled by appropriate settings of commands -abort_on or
3961              -return_with which both can cause non-zero exit  values  of  the
3962              program run. Severity ALL suppresses that event.
3963              This  command  reports  match  and mismatch of data files to the
3964              result channel.  Non-data files cause NOTE  events.  There  will
3965              also be UPDATE events from data reading.
3966              If  no  iso_rr_path  is  given  then the whole loaded session is
3967              compared with its MD5 sum. Be aware that this  covers  only  one
3968              session and not the whole image if there are older sessions.
3969
3970       -check_md5_r severity iso_rr_path [***]
3971              Like -check_md5 but checking all data files underneath the given
3972              paths.  Only mismatching data files will be reported.
3973
3974       osirrox ISO-to-disk restore commands:
3975
3976       Normally xorriso only writes to disk files which were given  as  stdio:
3977       pseudo-drives  or  as  log files.  But its alter ego osirrox is able to
3978       extract file objects from ISO  images  and  to  create,  overwrite,  or
3979       delete file objects on disk.
3980       Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply.  If disk
3981       file  objects  already  exist  then  the  settings  of  -overwrite  and
3982       -reassure  apply.  But  -overwrite  "on"  only triggers the behavior of
3983       -overwrite "nondir". I.e. directories cannot be deleted.
3984       Access permissions of files in the ISO image do not restrict restoring.
3985       The directory permissions on disk have to allow rwx.
3986
3987       -osirrox setting[:option:...]
3988              Setting  "off"  disables  disk filesystem manipulations. This is
3989              the  default  unless  the  program  was  started  with  leafname
3990              "osirrox".  Elsewise  the  capability  to  restore  files can be
3991              enabled explicitly by -osirrox  "on".   It  can  be  irrevocably
3992              disabled by -osirrox "banned".
3993              The  setting "blocked" is like "off". But it can only be revoked
3994              by setting "unblock", which elsewise is like "on". This  can  be
3995              used to curb command scripts which might use "on" undesiredly.
3996              To  enable  restoring  of  special  files  by  "device_files" is
3997              potentially dangerous.  The meaning of the number  st_rdev  (see
3998              man  2  stat)  depends  much on the operating system. Best is to
3999              restore device files only to the same  system  from  where  they
4000              were  copied.  If not enabled, device files in the ISO image are
4001              ignored during restore operations.
4002              Due to a bug of previous versions, device  files  from  previous
4003              sessions  might  have  been altered to major=0, minor=1. So this
4004              combination does not get restored.
4005              Option "concat_split_on" is default.  It  enables  restoring  of
4006              split file directories as data files if the directory contains a
4007              complete  collection  of  -cut_out  part  files.   With   option
4008              "concat_split_off"  such  directories are handled like any other
4009              ISO image directory.
4010              Option "auto_chmod_off" is default. If  "auto_chmod_on"  is  set
4011              then  access  restrictions for disk directories get circumvented
4012              if those directories are owned by the effective  user  who  runs
4013              xorriso.  This happens by temporarily granting rwx permission to
4014              the owner.
4015              Option "sort_lba_on" may improve read performance  with  optical
4016              drives.  It  can  restore  large  numbers  of hard links without
4017              exhausting -temp_mem_limit. It does not preserve directory mtime
4018              and  it  needs -osirrox option auto_chmod_on in order to extract
4019              directories  which  offer  no  write  permission.   Default   is
4020              "sort_lba_off".
4021              Option "o_excl_on" is the default unless the program was started
4022              with leafname "osirrox". On GNU/Linux it tries  to  avoid  using
4023              drives  which  are  mounted or in use by other libburn programs.
4024              Option "o_excl_off" on GNU/Linux enables access to  such  drives
4025              by  the  equivalent  of  -drive_access  "shared:readonly".  I.e.
4026              drives which get acquired while "o_excl_off" will refuse to  get
4027              blanked,  formatted, written, or ejected. But be aware that even
4028              harmless inquiries  can  spoil  ongoing  burns  of  CD-R[W]  and
4029              DVD-R[W].
4030              Option  "strict_acl_off" is default. It tolerates on FreeBSD the
4031              presence of directory "default" ACLs  in  the  ISO  image.  With
4032              "strict_acl_on"  these GNU/Linux ACLs cause on FreeBSD a FAILURE
4033              event during restore with -acl "on".
4034
4035       -extract iso_rr_path disk_path
4036              Copy the file objects at and  underneath  iso_rr_path  to  their
4037              corresponding  addresses  at  and underneath disk_path.  This is
4038              the inverse of -map or -update_r.
4039              If iso_rr_path is a  directory  and  disk_path  is  an  existing
4040              directory  then  both trees will be merged. Directory attributes
4041              get extracted only if the disk directory is newly created by the
4042              copy  operation.   Disk files get removed only if they are to be
4043              replaced by file objects from the ISO image.
4044              As many attributes as possible are copied together with restored
4045              file objects.
4046
4047       -extract_single iso_rr_path disk_path
4048              Like  -extract,  but  if iso_rr_path is a directory then its sub
4049              tree gets not restored.
4050
4051       -extract_l iso_rr_prefix disk_prefix iso_rr_path [***]
4052              Perform  -extract  with  each  of  the  iso_rr_path  parameters.
4053              disk_path   will  be  composed  from  iso_rr_path  by  replacing
4054              iso_rr_prefix by disk_prefix.
4055
4056       -extract_cut iso_rr_path byte_offset byte_count disk_path
4057              Copy a byte interval from a data file out of an ISO image into a
4058              newly  created disk file.  The main purpose for this is to offer
4059              a way of handling large files if they are not supported by mount
4060              -t  iso9660  or if the target disk filesystem cannot store large
4061              files.
4062              If the data bytes of iso_rr_path are stored in  the  loaded  ISO
4063              image,  and  no filter is applied, and byte_offset is a multiple
4064              of 2048, then a special run of -check_media is performed. It may
4065              be quicker and more rugged than the general reading method.
4066
4067       -cpx iso_rr_path [***] disk_path
4068              Copy  single leaf file objects from the ISO image to the address
4069              given by disk_path. If more then one iso_rr_path is  given  then
4070              disk_path  must  be  a  directory or non-existent. In the latter
4071              case it gets created and the extracted files get installed in it
4072              with the same leafnames.
4073              Missing  directory  components in disk_path will get created, if
4074              possible.
4075              Directories  are  allowed  as  iso_rr_path  only  with  -osirrox
4076              "concat_split_on" and only if they actually represent a complete
4077              collection of -cut_out split file parts.
4078
4079       -cpax iso_rr_path [***] disk_path
4080              Like -cpx but restoring mtime, atime as in ISO image and  trying
4081              to set ownership and group as in ISO image.
4082
4083       -cp_rx iso_rr_path [***] disk_path
4084              Like -cpx but also extracting whole directory trees from the ISO
4085              image.
4086              The resulting disk paths are determined as with shell command cp
4087              -r  :  If disk_path is an existing directory then the trees will
4088              be inserted or merged underneath this directory  and  will  keep
4089              their  leaf  names.  The  ISO directory "/" has no leaf name and
4090              thus gets mapped directly to disk_path.
4091
4092       -cp_rax iso_rr_path [***] disk_path
4093              Like -cp_rx but restoring mtime,  atime  as  in  ISO  image  and
4094              trying to set ownership and group as in ISO image.
4095
4096       -paste_in iso_rr_path disk_path byte_offset byte_count
4097              Read  the  content  of  a ISO data file and write it into a data
4098              file on  disk  beginning  at  the  byte_offset.  Write  at  most
4099              byte_count bytes.  This is the inverse of command -cut_out.
4100
4101       -concat mode [target | lim prog [args [...]] lim] iso_rr_path [***]
4102              Copy the data content of one or more data files of the ISO image
4103              into a disk file object, into a  file  descriptor,  or  start  a
4104              program  and  copy the data into its standard input.  The latter
4105              is subject to the security restrictions for external filters.
4106              Modes overwrite and append write into the target which is  given
4107              by  the  second  parameter.  This may be the path to a disk file
4108              object, or "-" which means standard output, or  a  text  of  the
4109              form  /dev/fd/number,  where  number  is an open file descriptor
4110              (e.g. standard error is /dev/fd/2).  An existing target file  is
4111              not  removed  before  writing  begins. If it is not able to take
4112              content data, then this command fails.  Mode overwrite truncates
4113              regular data files to 0 size before writing into them.  Example:
4114               -concat append /home/me/accumulated_text /my/iso/text --
4115
4116              Mode  pipe  expects  as  second parameter a delimiter word which
4117              shall mark the end of  the  program  argument  list.  The  third
4118              argument  is  the  disk_path  to the program. It must contain at
4119              least one '/'. $PATH is not applied.  Further parameters  up  to
4120              the  announced  delimiter  word  are  used as arguments with the
4121              program start. Example:
4122               -iso_rr_pattern on \
4123               -concat pipe + /usr/bin/wc + "/my/iso/files*" --
4124
4125              The further parameters in all modes are the iso_rr_paths of data
4126              files.  Their content gets concatenated in the copy.
4127
4128       -mount drive entity id path
4129              Produce  the  same  line  as  -mount_cmd  and then execute it as
4130              external program run after giving up  the  depicted  drive.  See
4131              also  -mount_opts.   This  demands  -osirrox  to  be enabled and
4132              normally will succeed only for the superuser. For safety reasons
4133              the  mount  program  is  only  executed  if  it  is reachable as
4134              /bin/mount or /sbin/mount.
4135
4136       Command compatibility emulations:
4137
4138       Writing of ISO 9660 on CD is traditionally done by program  mkisofs  as
4139       ISO 9660 image producer and cdrecord as burn program.  xorriso does not
4140       strive for their comprehensive emulation.  Nevertheless it is ready  to
4141       perform  some of its core tasks under control of commands which in said
4142       programs trigger comparable actions.
4143
4144       -as personality option [options] --
4145              Perform the variable length option list as sparse  emulation  of
4146              the program depicted by the personality word.
4147
4148              Personality "mkisofs" accepts the options listed with:
4149                -as mkisofs -help --
4150              Among  them:  -R  (always  on),  -r,  -J, -o, -M, -C, -dir-mode,
4151              -file-mode,  -path-list,  -m,  -exclude-list,  -f,  -print-size,
4152              -pad,    -no-pad,   -V,   -v,   -version,   -graft-points,   -z,
4153              -no-emul-boot,  -b,   -c,   -boot-info-table,   -boot-load-size,
4154              -input-charset,  -G,  -output-charset,  -U, -hide, -hide-joliet,
4155              -hide-list, -hide-joliet-list, file paths and pathspecs.  A  lot
4156              of  options are not supported and lead to failure of the mkisofs
4157              emulation. Some are ignored, but better  do  not  rely  on  this
4158              tolerance.
4159              The supported options are documented in detail in xorrisofs.info
4160              and in man xorrisofs. The description here  is  focused  on  the
4161              effect of mkisofs emulation in the context of a xorriso run.
4162              Other than with the "cdrecord" personality there is no automatic
4163              -commit at  the  end  of  a  "mkisofs"  option  list.  Verbosity
4164              settings  -v  (=  "UPDATE")  and -quiet (= "SORRY") persist. The
4165              output  file  persists  until  things   happen   like   -commit,
4166              -rollback, -dev, or end of xorriso.
4167              Options  which affect all file objects in the ISO image, like -r
4168              or -dir-mode, will be applied only to files which are present in
4169              the  ISO image when the command -as ends. If you use several -as
4170              mkisofs commands in the same run,  then  consider  to  put  such
4171              options into the last -as command.
4172              If  files  are  added  to  the image, then -pacifier gets set to
4173              "mkisofs" and -stdio_sync is  defaulted  to  "off"  if  no  such
4174              setting was made yet.
4175              -graft-points   is   equivalent  to  -pathspecs  on.  Note  that
4176              pathspecs without "="  are  interpreted  differently  than  with
4177              xorriso  command  -add.   Directories  get  merged with the root
4178              directory of the ISO image, other filetypes get mapped into that
4179              root directory.
4180              If  pathspecs  are given and if no output file was chosen before
4181              or during  the  "mkisofs"  option  list,  then  standard  output
4182              (-outdev  "-")  will get into effect.  If -o points to a regular
4183              file, then it will be truncated to 0 bytes when finally  writing
4184              begins.  This  truncation does not happen if the drive is chosen
4185              by xorriso  commands  before  -as  mkisofs  or  after  its  list
4186              delimiter.  Directories  and  symbolic  links  are  no  valid -o
4187              targets.
4188              Writing to stdout is possible only if -as  "mkisofs"  was  among
4189              the  start  arguments  or  if  other start arguments pointed the
4190              output drive to standard output.
4191              -print-size inhibits automatic image production at program  end.
4192              This  ban  is  lifted  only  if  the  pending  image changes get
4193              discarded.
4194              Padding is counted as part  of  the  ISO  image  if  not  option
4195              --emul-toc is given.
4196              If no -iso-level is given, then level 1 is chosen when the first
4197              file or directory is added to the image. At  the  same  occasion
4198              directory   names   get  allowed  to  violate  the  standard  by
4199              -compliance option allow_dir_id_ext.  This  may  be  avoided  by
4200              option -disallow_dir_id_ext.
4201              Option  -root  is  supported. Option -old-root is implemented by
4202              xorriso commands  -mkdir,  -cp_clone,  -find  update_merge,  and
4203              -find  rm_merge.   -root and -old-root set command -disk_dev_ino
4204              to "ino_only" and -md5 to "on", by default.   -disk_dev_ino  can
4205              be   set   to   "off"   by   --old-root-no-ino  or  to  "on"  by
4206              --old-root-devno   .    -md5   can   be   set   to   "off"    by
4207              --old-root-no-md5 .
4208              Not   original   mkisofs   options   are   --quoted_path_list  ,
4209              --hardlinks , --acl , --xattr , --md5  ,  --stdio_sync  .   They
4210              work  like the xorriso commands with the same name and hardcoded
4211              parameter  "on",  e.g.  -acl  "on".   Explicit  parameters   are
4212              expected by --stdio_sync and --scdbackup_tag.
4213              The    capability   to   preserve   multi-session   history   on
4214              overwriteable media gets disabled by default. It can be  enabled
4215              by  using  --emul-toc  with  the  first session. See -compliance
4216              no_emul_toc.
4217              --sort-weight gets as parameters a number  and  an  iso_rr_path.
4218              The  number  becomes  the  LBA  sorting  weight  of regular file
4219              iso_rr_path  or  of  all  regular  files  underneath   directory
4220              iso_rr_path.  (See -find -exec sort_weight).
4221              Adopted  from  grub-mkisofs  are  --protective-msdos-label  (see
4222              -boot_image         grub         partition_table=on)         and
4223              --modification-date=YYYYMMDDhhmmsscc  (see  -volume_date  uuid).
4224              For EFI bootable GRUB boot images use --efi-boot.   It  performs
4225              -boot_image  grub  efi_path= surrounded by two -boot_image "any"
4226              "next".  Alternative option  -e  from  Fedora  genisoimage  sets
4227              bin_path and platform_id for EFI, but performs no "next".
4228              For  MBR  bootable ISOLINUX images there is -isohybrid-mbr FILE,
4229              where FILE is one of the Syslinux files  mbr/isohdp[fp]x*.bin  .
4230              Use  this  instead  of  -G  to  apply  the effect of -boot_image
4231              isolinux partition_table=on.
4232              --boot-catalog-hide is -boot_image any cat_hidden=on.
4233              -mips-boot is the same as -boot_image any mips_path= .
4234              -mipsel-boot leads to mipsel_path= .
4235              -partition_offset      number      is      -boot_image       any
4236              partition_offset=number.
4237              Command -append_partition is supported.
4238              -untranslated_name_len        number        is       -compliance
4239              untranslated_name_len=number.
4240              --old-empty is -compliance old_empty.
4241              The  options  of  genisoimage  Jigdo  Template  Extraction   are
4242              recognized  and  performed  via  xorriso command -jigdo. See the
4243              "Alias:" names there for the meaning of the genisoimage options.
4244
4245              Personalities "xorrisofs",  "genisoimage",  and  "genisofs"  are
4246              aliases for "mkisofs".
4247              If  xorriso  is  started  with one of the leafnames "xorrisofs",
4248              "genisofs",  "mkisofs",  or  "genisoimage",  then  it   performs
4249              -read_mkisofsrc  and  prepends  -as  "genisofs"  to  the program
4250              arguments.  I.e. all arguments will be interpreted mkisofs style
4251              until   "--"  is  encountered.   From  then  on,  arguments  are
4252              interpreted as xorriso commands.
4253              --no_rc as first argument  of  such  a  program  start  prevents
4254              interpretation of startup files. See section FILES below.
4255
4256              Personality "cdrecord" accepts the options listed with:
4257                -as cdrecord -help --
4258              Among  them:  -v,  dev=,  speed=,  blank=,  fs=,  -eject, -atip,
4259              padsize=,      tsize=,      -isosize,      -multi,      -msinfo,
4260              --grow_overwriteable_iso,   write_start_address=,  track  source
4261              file path or "-" for standard input as track source.
4262              It ignores most  other  options  of  cdrecord  and  cdrskin  but
4263              refuses  on  -audio,  -scanbus, and on blanking modes unknown to
4264              xorriso.
4265              The scope is only a single data track per session to be  written
4266              to  blank,  overwriteable,  or appendable media. The medium gets
4267              closed if  closing  is  applicable  and  not  option  -multi  is
4268              present.
4269              If  an  input  drive was acquired, then it is given up.  This is
4270              only allowed if no image changes are pending.
4271              dev= must be given as xorriso  device  address.  Addresses  like
4272              0,0,0 or ATA:1,1,0 are not supported.
4273              If a track source is given, then an automatic -commit happens at
4274              the end of the "cdrecord" option list.
4275              --grow_overwriteable_iso enables emulation of  multi-session  on
4276              overwriteable  media.   To  enable emulation of a TOC, the first
4277              session  needs  -C  0,32  with  -as  mkisofs  (but  no  -M)  and
4278              --grow_overwriteable_iso    write_start_address=32s   with   -as
4279              cdrecord.
4280              A much more elaborate libburn based  cdrecord  emulator  is  the
4281              program cdrskin.
4282              Personalites "xorrecord", "wodim", and "cdrskin" are aliases for
4283              "cdrecord".
4284              If xorriso is started with one  of  the  leafnames  "xorrecord",
4285              "cdrskin",   "cdrecord",   or  "wodim",  then  it  automatically
4286              prepends -as  "cdrskin"  to  the  program  arguments.  I.e.  all
4287              arguments  will  be  interpreted  cdrecord  style  until "--" is
4288              encountered.  From then on, arguments are interpreted as xorriso
4289              commands.
4290              --no_rc  as  first  argument  of  such  a program start prevents
4291              interpretation of xorriso  startup  files.   See  section  FILES
4292              below.
4293
4294       -read_mkisofsrc
4295              Try one by one to open for reading:
4296               ./.mkisofsrc   ,  $MKISOFSRC  ,  $HOME/.mkisofsrc  ,  $(dirname
4297              $0)/.mkisofsrc
4298              On  success  interpret  the  file  content  as  of  man  mkisofs
4299              CONFIGURATION,  and  end this command. Do not try further files.
4300              The last address  is  used  only  if  start  argument  0  has  a
4301              non-trivial dirname.
4302              The  reader currently interprets the following NAME=VALUE pairs:
4303              APPI (-application_id) , PUBL (-publisher) , SYSI (-system_id) ,
4304              VOLI (-volid) , VOLS (-volset_id)
4305              Any other lines will be silently ignored.
4306
4307       -pacifier behavior_code
4308              Control  behavior  of  UPDATE pacifiers during write operations.
4309              The following behavior codes are defined:
4310              "xorriso" is the default format:
4311              Writing: sector XXXXX of YYYYYY  [fifo active, nn% fill]
4312              "cdrecord" looks like:
4313              X of Y MB written (fifo nn%) [buf mmm%]
4314              "mkisofs"
4315              nn% done, estimate finish Tue Jul 15 20:13:28 2008
4316              The frequency of the messages can be adjusted by
4317              "interval=number"
4318              where number gives the seconds between two messages. Permissible
4319              settings are 0.1 to 60.0.
4320
4321       -scdbackup_tag list_path record_name
4322              Set  the  parameter  "name" for a scdbackup checksum record.  It
4323              will be appended in  an  scdbackup  checksum  tag  to  the  -md5
4324              session tag if the image starts at LBA 0. This is the case if it
4325              gets written as first session onto a sequential medium, or piped
4326              into a program, named pipe or character device.
4327              If  list_path is not empty then the record will also be appended
4328              to the data file given by this path.
4329              Program scdbackup_verify will recognize and verify tag and  file
4330              record.
4331              An empty record_name disables this feature.
4332
4333       Scripting, dialog and program control features:
4334
4335       -no_rc
4336              Only  if  used  as  first program argument this command prevents
4337              reading and interpretation of startup files. See  section  FILES
4338              below.
4339
4340       -options_from_file fileaddress
4341              Read  quoted  input  from fileaddress and execute it like dialog
4342              lines.  Empty lines and lines which  begin  by  #  are  ignored.
4343              Normally  one  line  should hold one xorriso command and all its
4344              parameters.   Nevertheless  lines  may  be  concatenated  by   a
4345              trailing backslash.
4346              See also section "Command processing", paragraph "Quoted input".
4347
4348       -help
4349              Print helptext.
4350
4351       -version
4352              Print program name and version, component versions, license.
4353
4354       -list_extras code
4355              Tell  whether  certain  extra  features  were enabled at compile
4356              time.  Code "all" lists all  features  and  a  headline.   Other
4357              codes  pick  a  single  feature.   Code "codes" lists them. They
4358              share names with related commands (see also there):
4359              "acl" tells whether xorriso has an adapter for local filesystems
4360              ACLs.
4361              "xattr"   tells   whether  xorriso  has  an  adapter  for  local
4362              filesystems EA.
4363              "jigdo" tells whether production of Jigdo files is possible.
4364              "zisofs" tells whether zisofs  and  built-in  gzip  filters  are
4365              enabled.
4366              "external_filter"  tells  whether  external filter processes are
4367              allowed and whether  they  are  allowed  if  real  user  id  and
4368              effective user id differ.
4369              "dvd_obs" tells whether 64 kB output to DVD media is default.
4370              "use_readline"  tells  whether readline may be enabled in dialog
4371              mode.
4372
4373       -history textline
4374              Copy textline into libreadline history.
4375
4376       -status mode|filter
4377              Print the current settings of xorriso.  Modes:
4378                short... print only important or altered settings
4379                long ... print all settings including defaults
4380                long_history  like long plus history lines
4381              Filters begin with '-' and are compared  literally  against  the
4382              output  lines of -status:long_history. A line is put out only if
4383              its start matches the filter text. No wildcards.
4384
4385       -status_history_max number
4386              Set maximum number of history lines to be reported with  -status
4387              "long_history".
4388
4389       -list_delimiter word
4390              Set the list delimiter to be used instead of "--".  It has to be
4391              a single word, must not be empty, not longer than 80 characters,
4392              and must not contain quotation marks.
4393              For  brevity  the  list delimiter is referred as "--" throughout
4394              this text.
4395
4396       -sh_style_result "on"|"off"
4397              Make the result output of some  filesystem  inspection  commands
4398              look more like the output of equivalent shell commands. The most
4399              important effect is to prevent the wrapping  of  file  addresses
4400              into quotation marks with commands
4401                -pwd -pwdx -ls -lsd -lsl -lsdl -lsx -lsdx -lslx -lsdlx
4402                -du -dus -dux -dusx -findx -find
4403              This  will make ambiguous the representation of file names which
4404              contain  newline  characters.  On  the  other  hand  it   should
4405              facilitate  integration  of  xorriso  into  shell  scripts which
4406              already use the corresponding shell commands.
4407
4408       -backslash_codes "on"|"off"|mode[:mode]
4409              Enable or disable the interpretation of symbolic representations
4410              of  special  characters  with  quoted  input,  or  with  program
4411              arguments, or with program text output. If enabled the following
4412              translations apply:
4413               \a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014)
4414               \n=linefeed(012) \r=carriage_return(015) \t=tab(011)
4415               \v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code
4416               \x[0-9a-f][0-9a-f]=hex_code \cC=control-C
4417              Translations can occur with quoted input in 3 modes:
4418               "in_double_quotes" translates only inside " quotation.
4419               "in_quotes" translates inside " and ' quotation.
4420               "with_quoted_input" translates inside and outside quotes.
4421              With the start program arguments there is mode:
4422               "with_program_arguments" translates program arguments.
4423              Mode  "encode_output"  encodes  output  characters.  It combines
4424              "encode_results" with "encode_infos". Inside  single  or  double
4425              quotation  marks  encoding applies to 8-bit characters octal 001
4426              to 037 , 177 to 377 and to  backslash(134).   Outside  quotation
4427              marks  some  harmless  ASCII  control characters stay unencoded:
4428              bell(007),     backspace(010),     tab(011),      linefeed(012),
4429              formfeed(014), carriage_return(015).
4430              Mode  "off"  is default and disables any translation.  Mode "on"
4431              is "with_quoted_input:with_program_arguments:encode_output".
4432
4433       -temp_mem_limit number["k"|"m"]
4434              Set the maximum size of temporary memory to be  used  for  image
4435              dependent   buffering.   Currently   this   applies  to  pattern
4436              expansion, LBA sorting, restoring of hard links.
4437              Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1
4438              GiB.
4439
4440       -print  text
4441              Print  a  text  line  to  the result channel which is by default
4442              stdout.
4443
4444       -print_info  text
4445              Print a text line to  the  info  channel  which  is  by  default
4446              stderr.
4447
4448       -print_mark  text
4449              Print  a  text  line  to  the  mark  channel which is by default
4450              directed to both, result and info channel. An  empty  text  will
4451              cause no output at all.
4452
4453       -prompt text
4454              Show  text  at beginning of output line and wait for the user to
4455              hit the Enter key or to send a line via stdin.
4456
4457       -sleep seconds
4458              Wait for the given number of seconds before performing the  next
4459              command.    Expect  coarse  granularity  no  better  than  1/100
4460              seconds.
4461
4462       -errfile_log mode path|channel
4463              If  problem  events  are  related  to  input  files   from   the
4464              filesystem,  then their disk_paths can be logged to a file or to
4465              output channels R or I.
4466              Mode can either be "plain" or "marked". The latter causes marker
4467              lines which give the time of log start, burn session start, burn
4468              session end, log end or program end. In mode "plain",  only  the
4469              file paths are logged.
4470              If  path  is  "-" or "-R" then the log is directed to the result
4471              channel.  Path "-I" directs it to the info message channel.  Any
4472              text  that does not begin with "-" is used as path for a file to
4473              append the log lines.
4474              Problematic files can be  recorded  multiple  times  during  one
4475              program  run.  If the program run aborts then the list might not
4476              be complete  because  some  input  files  might  not  have  been
4477              processed at all.
4478              The  errfile  paths  are  transported  as  messages  of very low
4479              severity  "ERRFILE".   This  transport  becomes   visible   with
4480              -report_about "ALL".
4481
4482       -session_log path
4483              If  path  is not empty it gives the address of a plain text file
4484              where a log record gets appended after each  session.  This  log
4485              can  be  used  to determine the start_lba of a session for mount
4486              options -o sbsector= (on GNU/Linux) or -s (on FreeBSD) from date
4487              or volume ID.
4488              Record format is: timestamp start_lba size volume-id
4489              The  first three items are single words, the rest of the line is
4490              the volume ID.
4491
4492       -scsi_log "on"|"off"
4493              Mode "on" enables very verbose  logging  of  SCSI  commands  and
4494              drive  replies.   Logging messages get printed to stderr, not to
4495              any of the xorriso output channels.
4496              A special property of this command is that the  first  -scsi_log
4497              setting  among the start arguments is in effect already when the
4498              first operations of xorriso begin.  Only "-scsi_log"  with  dash
4499              "-" is recognized that way.
4500
4501       -end
4502              End program after writing pending changes.
4503
4504       -rollback_end
4505              Discard pending changes. End program immediately.
4506
4507       # any text
4508              Only  in  dialog  or  file  execution  mode,  and  only as first
4509              non-whitespace in line: Do not execute the line but store it  in
4510              readline history.
4511
4512       Support for frontend programs via stdin and stdout:
4513
4514       -pkt_output "on"|"off"
4515              Consolidate  text  output  on stdout and classify each line by a
4516              channel indicator:
4517               'R:' for result lines,
4518               'I:' for notes and error messages,
4519               'M:' for -mark texts.
4520              Next is a decimal number of which only bit 0 has a  meaning  for
4521              now.   0  means  no  newline at end of payload, 1 means that the
4522              newline character at the end of the output line belongs  to  the
4523              payload.  After  another  colon  and a blank follows the payload
4524              text.
4525              Example:
4526               I:1: enter option and parameters :
4527
4528       -logfile channel fileaddress
4529              Copy output of a channel to the given file. Channel may  be  one
4530              of:  "." for all channels, "I" for info messages, "R" for result
4531              lines, "M" for -mark texts.
4532
4533       -mark text
4534              If text is not empty it will get put out  on  "M"  channel  each
4535              time xorriso is ready for the next dialog line or before xorriso
4536              performs a command that was entered to the pager prompt.
4537
4538       -msg_op opcode parameter_text
4539              This  command  shall   facilitate   extraction   of   particular
4540              information  from the message output of other commands. It gives
4541              access to the C API function  Xorriso_parse_line()  and  to  the
4542              message  sieve  that  is provided by the C API.  Please refer to
4543              their descriptions in  file  xorriso.h.   Further  it  helps  to
4544              interpret the severity codes of info messages.
4545              Intended  users  are  frontend programs which operate xorriso in
4546              dialog mode.
4547              The result output of this command is not caught by  the  message
4548              sieve.
4549              The following opcodes are defined:
4550              start_sieve
4551              Install  the  message  sieve as of Xorriso_sieve_big() and start
4552              watching program messages. The parameter_text has no meaning.
4553              show_sieve
4554              Show a list of filter rule  names.  The  parameter_text  has  no
4555              meaning.   The  list  begins  by a line with the return value of
4556              Xorriso_sieve_get_result() with flag  bit3.  If  this  value  is
4557              larger than 0, then the next line tells the number of names. The
4558              following lines show one name each.
4559              read_sieve
4560              Use the parameter_text as name of a filter rule and inquire  its
4561              next  recorded  result.   See  Xorriso_sieve_big() for a list of
4562              names and reply strings.
4563              The recorded strings are put out on  result  channel.  They  get
4564              wrapped  into  lines which tell their structure.  The first line
4565              tells the return value of Xorriso_sieve_get_result().  The  next
4566              line  tells  the number of strings. Each string begins by a line
4567              that tells the number of lines of the string. Then follow  these
4568              lines.  They  are  to  be  concatenated with a newline character
4569              between each of them.  Finally the  number  of  still  available
4570              recorded results of the given name is put out.
4571              clear_sieve
4572              Dispose  all  recorded  strings  and  continue  watching program
4573              messages.  The parameter_text has no meaning.
4574              end_sieve
4575              Dispose the sieve  with  its  filter  rules  and  stop  watching
4576              program messages.  The parameter_text has no meaning.
4577              parse
4578              Read   a   text   from   dialog   input   and   submit   it   to
4579              Xorriso_parse_line().  The parameter_text word shall consist  of
4580              several  words separated by blanks.  It will be necessary to use
4581              both kinds of quotation marks.
4582              E.g. "'ISO session  :' '' 0 0 1"
4583              The five parameter words  are:  prefix,  separators,  max_words,
4584              flag, number_of_input_lines.  The former four are handed over to
4585              Xorriso_parse_line(). The number of input lines minus one  tells
4586              xorriso how many newline characters are part of the input text.
4587              The  announced  number  of  text  lines will be read from dialog
4588              input, concatenated with a newline  character  between  each  of
4589              them,  and  submitted to Xorriso_parse_line() as parameter line.
4590              Note that newlines outside of quotation marks are interpreted as
4591              separators if the separators parameter is empty.
4592              The  parsed  strings  are  put  out  on result channel. They get
4593              wrapped into lines which tell their structure.  The  first  line
4594              tells  the  return value of Xorriso_parse_line().  The next line
4595              tells the number of strings. Each string begins by a  line  that
4596              tells  the  number  of  lines  of  the string. Then follow these
4597              lines. They are to be  concatenated  with  a  newline  character
4598              between each of them.
4599              If -backslash_codes "encode_output" is enabled, then the strings
4600              undergo encoding as if they were enclosed in quotes. Escpecially
4601              each string will be put out as a single result line.
4602              parse_bulk
4603              Like   "parse",   but   with  the  fifth  parameter  word  being
4604              number_of_input_texts rather  than  number_of_input_lines.  Each
4605              input   text   has   to   be  preceded  by  a  line  that  tells
4606              number_of_input_lines as with "parse".  Then come the  announced
4607              number of text lines.
4608              All  input  texts  will  be read before printing of result lines
4609              begins.    This   consumes   memory   in   xorriso.    So    the
4610              number_of_input_texts should not be extremely high. On the other
4611              hand, large transactions of command, input  texts,  and  results
4612              are desirable if connection latency is an issue.
4613              parse_silently
4614              Like  "parse"  but not issuing a prompting message. Confusing to
4615              humans.
4616              parse_bulk_silently
4617              Like "parse_bulk" but not issuing a prompting message. Confusing
4618              to humans.
4619              compare_sev
4620              The  parameter_text  should contain two comma separated severity
4621              texts as issued by this program. Like "SORRY,UPDATE".  See  also
4622              paragraph "Exception processing".
4623              These  two severity texts get compared and a number gets printed
4624              to the result channel. This number is 0 if both  severities  are
4625              equal.   It is -1 if the first severity is lower than the second
4626              one.  It is 1 is the first severity is higher  than  the  second
4627              one.
4628              Above example "SORRY,UPDATE" will yield 1.
4629              list_sev
4630              Print  to  the  result  channel  a  blank  separated list of all
4631              severity names.  Sorted from low to high severity.
4632
4633       -named_pipe_loop    mode[:mode]    disk_path_stdin     disk_path_stdout
4634       disk_path_stderr
4635              Temporarily replace standard input, standard output and standard
4636              error by named pipes. Enter dialog mode without readline.
4637              Defined modes are:
4638              "cleanup" removes the submitted pipe files when the loop ends.
4639              "keep" does not delete them. This is the default.
4640              "buffered" reads all lines from the input pipe until EOF  before
4641              it opens the output pipes and processes the input lines.
4642              "direct"  opens  the output pipes after the first input line was
4643              read.  Each line is executed directly after it is read. This  is
4644              the default.
4645              The other three parameters must either be disk paths to existing
4646              named pipes, or be "-"  to  leave  the  according  standard  i/o
4647              channel unreplaced.
4648              xorriso  will open the stdin pipe, read and execute dialog lines
4649              from it until the sender closes the pipe. The output  pipes  get
4650              opened depending on mode "buffered" or "direct". After all lines
4651              are executed, xorriso will close its side of the pipes and enter
4652              a new cycle of opening, reading and executing.
4653              If an input line consists only of the word "end_named_pipe_loop"
4654              then -named_pipe_loop will end and further xorriso commands  may
4655              be executed from other sources.
4656
4657       -launch_frontend program [arguments ...] --
4658              Start  the  program that is given as first parameter. Submit the
4659              other parameters as program  arguments.  Enable  xorriso  dialog
4660              mode.
4661              Two  nameless  pipe  objects are created. xorriso standard input
4662              gets connected to the standard output of  the  started  program.
4663              xorriso  standard output and standard error get connected to the
4664              standard input of that program.
4665              xorriso will abort when the started program ends or if it cannot
4666              be  started at all. In both cases it will return a non-zero exit
4667              value.  The exit value will be zero if the frontend  sends  -end
4668              or -rollback_end before ending itself.
4669              This  command may be totaly banned at compile time. It is banned
4670              by default if xorriso runs under setuid permissions.
4671              The program name will not be searched in the $PATH  directories.
4672              To  make  this  clear, it must contain at least one /-character.
4673              Best is an absolute path.
4674              Example:
4675                xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio --
4676              The frontend program should first send via its standard output:
4677                -mark 0 -pkt_output on -msg_op start_sieve - -reassure off
4678              It should be ready to decode -pkt_output and to react  on  -mark
4679              messages.  Best is to increment the -mark number after each sent
4680              command sequence and then to wait for the new number to show  up
4681              in a mark message:
4682                ...some...commands... -mark <incremented_number>
4683              Further are advised:
4684                -report_about UPDATE -abort_on NEVER
4685                -iso_rr_pattern off -disk_pattern off
4686              A  check of the xorriso version should be done, in order to make
4687              sure that all desired features are present.
4688              Command -launch_frontend will only work once  per  xorriso  run.
4689              If no command parameters are submitted or if program is an empty
4690              text,  then  no  program  will  be  started   but   nevertheless
4691              -launch_frontend will be irrevocably disabled.
4692
4693       -prog text
4694              Use text as name of this program in subsequent messages
4695
4696       -prog_help text
4697              Use text as name of this program and perform -help.
4698

EXAMPLES

4700   Overview of examples:
4701       As superuser learn about available drives
4702       Blank medium and compose a new ISO image as batch run
4703       A dialog session doing about the same
4704       Manipulate an existing ISO image on the same medium
4705       Copy modified ISO image from one medium to another
4706       Bring a prepared ISOLINUX tree onto medium and make it bootable
4707       Change existing file name tree from ISO-8859-1 to UTF-8
4708       Operate on storage facilities other than optical drives
4709       Burn an existing ISO image file to medium
4710       Perform multi-session runs as of cdrtools traditions
4711       Let xorriso work underneath growisofs
4712       Adjust thresholds for verbosity, exit value and program abort
4713       Examples of input timestrings
4714       Incremental backup of a few directory trees
4715       Restore directory trees from a particular ISO session to disk
4716       Try to retrieve blocks from a damaged medium
4717
4718   As superuser learn about available drives
4719       On  Linux,  FreeBSD  or NetBSD consider to give rw-permissions to those
4720       users or groups which shall be able to use the drives with xorriso.  On
4721       Solaris  use  pfexec.  Consider  to  restrict  privileges of xorriso to
4722       "base,sys_devices" and to give r-permission to user or group.
4723       $ xorriso -device_links
4724       1  -dev '/dev/cdrom1' rwrw-- :  'TSSTcorp' 'DVD-ROM SH-D162C
4725       1  -dev '/dev/cdrw'   rwrw-- :  'TSSTcorp' 'CDDVDW SH-S223B'
4726       2  -dev '/dev/cdrw3'  rwrw-- :  'HL-DT-ST' 'BDDVDRW_GGC-H20L'
4727
4728   Blank medium and compose a new ISO image as batch run
4729       Acquire drive /dev/sr2, make medium ready for writing a new image, fill
4730       the image with the files from hard disk directories /home/me/sounds and
4731       /home/me/pictures.
4732       Because no -dialog "on" is given, the program will then end by  writing
4733       the session to the medium.
4734       $ xorriso -outdev /dev/sr2 \
4735        -blank as_needed \
4736        -map /home/me/sounds /sounds \
4737        -map /home/me/pictures /pictures
4738
4739       The ISO image may be shaped in a more elaborate way like the following:
4740       Omit some unwanted stuff by removing it from the image directory  tree.
4741       Reintroduce some wanted stuff.
4742       $ cd /home/me
4743       $ xorriso -outdev /dev/sr2 \
4744        -blank as_needed \
4745        -map /home/me/sounds /sounds \
4746        -map /home/me/pictures /pictures \
4747        -rm_r \
4748          /sounds/indecent \
4749          '/pictures/*private*' \
4750          /pictures/confidential \
4751          -- \
4752        -cd / \
4753        -add pictures/confidential/work* --
4754       Note  that  '/pictures/*private*'  is  a pattern for iso_rr_paths while
4755       pictures/confidential/work* gets expanded by the shell  with  addresses
4756       from  the  hard  disk.  Commands -add and -map have different parameter
4757       rules but finally the same effect: they put files into the image.
4758
4759   A dialog session doing about the same
4760       Some settings are already given as start argument. The other activities
4761       are  done  as  dialog  input.  The  pager  gets  set  to 20 lines of 80
4762       characters.
4763       The drive is acquired by command -dev rather than -outdev in  order  to
4764       see  the  message  about  its  current  content. By command -blank this
4765       content is made ready for being overwritten and the loaded ISO image is
4766       made empty.
4767       In  order  to  be  able  to  eject  the medium, the session needs to be
4768       committed explicitly.
4769       $ xorriso -dialog on -page 20 80 -disk_pattern on
4770       enter option and arguments :
4771       -dev /dev/sr2
4772       enter option and arguments :
4773       -blank as_needed
4774       enter option and arguments :
4775       -map /home/me/sounds /sounds -map /home/me/pictures /pictures
4776       enter option and arguments :
4777       -rm_r /sounds/indecent /pictures/*private* /pictures/confidential
4778       enter option and arguments :
4779       -cdx /home/me/pictures -cd /pictures
4780       enter option and arguments :
4781       -add confidential/office confidential/factory
4782       enter option and arguments :
4783       -du /
4784       enter option and arguments :
4785       -commit_eject all -end
4786
4787   Manipulate an existing ISO image on the same medium
4788       Load image from drive.  Remove (i.e. hide) directory  /sounds  and  its
4789       subordinates.      Rename     directory    /pictures/confidential    to
4790       /pictures/restricted.    Change   access   permissions   of   directory
4791       /pictures/restricted.   Add  new  directory  trees /sounds and /movies.
4792       Burn to the same medium, check whether the  tree  can  be  loaded,  and
4793       eject.
4794       $ xorriso -dev /dev/sr2 \
4795        -rm_r /sounds -- \
4796        -mv \
4797          /pictures/confidential \
4798          /pictures/restricted \
4799          -- \
4800        -chmod go-rwx /pictures/restricted -- \
4801        -map /home/me/prepared_for_dvd/sounds_dummy /sounds \
4802        -map /home/me/prepared_for_dvd/movies /movies \
4803        -commit -eject all
4804
4805   Copy modified ISO image from one medium to another
4806       Load  image  from  input  drive.  Do  the  same manipulations as in the
4807       previous example. Acquire output drive and blank it. Burn the  modified
4808       image as first and only session to the output drive.
4809       $ xorriso -indev /dev/sr2 \
4810        -rm_r /sounds -- \
4811        ...
4812        -outdev /dev/sr0 -blank as_needed \
4813        -commit -eject all
4814
4815   Bring a prepared ISOLINUX tree onto medium and make it bootable
4816       The  user  has  already created a suitable file tree on disk and copied
4817       the ISOLINUX files into subdirectory ./boot/isolinux of that tree.  Now
4818       xorriso can burn an El Torito bootable medium:
4819       $ xorriso -outdev /dev/sr0 -blank as_needed \
4820          -map /home/me/ISOLINUX_prepared_tree / \
4821          -boot_image isolinux dir=/boot/isolinux
4822
4823   Change existing file name tree from ISO-8859-1 to UTF-8
4824       This  example  assumes  that  the  existing  ISO image was written with
4825       character set ISO-8859-1 but that the readers expected UTF-8. Now a new
4826       session gets added with converted file names.  Command -changes_pending
4827       "yes" enables writing despite the lack of any manipulation command.
4828       In order to avoid any weaknesses  of  the  local  character  set,  this
4829       command  pretends  that  it  uses  already  the final target set UTF-8.
4830       Therefore strange file names may appear in messages, which will be made
4831       terminal-safe by command -backslash_codes.
4832       $ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
4833          -out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
4834          -changes_pending yes -commit -eject all
4835
4836   Operate on storage facilities other than optical drives
4837       Full  read-write  operation  is  possible  with regular files and block
4838       devices:
4839       $ xorriso -dev /tmp/regular_file ...
4840       Paths underneath /dev normally need prefix "stdio:"
4841       $ xorriso -dev stdio:/dev/sdb ...
4842       If /dev/sdb is to be used frequently and /dev/sda is the  system  disk,
4843       then  consider  to place the following lines in a xorriso Startup File.
4844       They allow you to use /dev/sdb without prefix and protect disk /dev/sda
4845       from xorriso:
4846         -drive_class banned   /dev/sda*
4847         -drive_class harmless /dev/sdb
4848       Other writeable file types are supported write-only:
4849       $ xorriso -outdev /tmp/named_pipe ...
4850       Among the write-only drives is standard output:
4851       $ xorriso -outdev - \
4852        ...
4853        | gzip >image.iso.gz
4854
4855   Burn an existing ISO image file to medium
4856       Actually this works with any kind of data, not only ISO images:
4857       $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso
4858
4859   Perform multi-session runs as of cdrtools traditions
4860       Between  both processes there can be performed arbitrary transportation
4861       or filtering.
4862       The first session is written like this:
4863       $ xorriso -as mkisofs prepared_for_iso/tree1 | \
4864        xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
4865       Follow-up sessions are written like this (the run of dd is only to give
4866       demons a chance to spoil it):
4867       $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
4868       $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
4869       $ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \
4870        xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
4871       Always eject the drive tray between sessions.
4872       The  run  of  xorriso -as mkisofs will read old sessions via the CD-ROM
4873       driver of /dev/sr0. This driver might  not  be  aware  of  the  changed
4874       content  as  long  as  the medium is not loaded again. In this case the
4875       previous session would not be properly assessed by xorriso and the  new
4876       session would contain only the newly added files.
4877       Some  systems  have not enough patience with automatic tray loading and
4878       some demons may interfere with a first CD-ROM driver read attempt  from
4879       a freshly loaded medium.
4880       When  loading  the  tray  manually, wait 10 seconds after the drive has
4881       stopped blinking.
4882       A safe automatic way seems to be a separate run of xorriso for  loading
4883       the  tray  with  proper waiting, and a subsequent run of dd which shall
4884       offer itself to any problems caused by  demons  assessing  the  changed
4885       drive  status.   If  this  does  not  help,  insert a run of "sleep 10"
4886       between xorriso and dd.
4887       This example works for multi-session media only.   Add  cdrskin  option
4888       --grow_overwriteable_iso  to  all  -as cdrecord runs in order to enable
4889       multi-session emulation on overwriteable media.
4890
4891   Let xorriso work underneath growisofs
4892       growisofs expects an ISO formatter program which understands options -C
4893       and -M. If xorriso gets started by name "xorrisofs" then it is suitable
4894       for that.
4895       $ export MKISOFS="xorrisofs"
4896       $ growisofs -Z /dev/dvd /some/files
4897       $ growisofs -M /dev/dvd /more/files
4898       If no "xorrisofs" is available on your system, then you  will  have  to
4899       create  a link pointing to the xorriso binary and tell growisofs to use
4900       it.  E.g. by:
4901       $ ln -s $(which xorriso) "$HOME/xorrisofs"
4902       $ export MKISOFS="$HOME/xorrisofs"
4903       One may quit mkisofs emulation by argument "--" and  make  use  of  all
4904       xorriso  commands. growisofs dislikes options which start with "-o" but
4905       -outdev must be set to "-".  So use "outdev" instead:
4906       $ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files
4907       $ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files
4908       growisofs has excellent burn capabilities with DVD and BD.  It does not
4909       emulate session history on overwriteable media, though.
4910
4911   Adjust thresholds for verbosity, exit value and program abort
4912       Be quite verbose, exit 32 if severity "FAILURE" was encountered, do not
4913       abort prematurely but forcibly go on until the end of commands.
4914       $ xorriso ... \
4915        -report_about UPDATE \
4916        -return_with FAILURE 32 \
4917        -abort_on NEVER \
4918        ...
4919
4920   Examples of input timestrings
4921       As printed by program date: 'Thu Nov 8 14:51:13 CET 2007'
4922       The same without ignored parts: 'Nov 8 14:51:13 2007'
4923       The same as expected by date: 110814512007.13
4924       Four weeks in the future: +4w
4925       The current time: +0
4926       Three hours ago: -3h
4927       Seconds since Jan 1 1970: =1194531416
4928
4929   Incremental backup of a few directory trees
4930       This changes the directory trees /projects and  /personal_mail  in  the
4931       ISO  image so that they become exact copies of their disk counterparts.
4932       ISO file objects get created, deleted or get their attributes  adjusted
4933       accordingly.
4934       ACL, xattr, hard links and MD5 checksums will be recorded.  Accelerated
4935       comparison is enabled at the expense of potentially larger backup size.
4936       Only  media  with  the  expected volume ID or blank media are accepted.
4937       Files with names matching *.o or *.swp get excluded explicitly.
4938       When done with writing the new session gets  checked  by  its  recorded
4939       MD5.
4940       $ xorriso \
4941        -abort_on FATAL \
4942        -for_backup -disk_dev_ino on \
4943        -assert_volid 'PROJECTS_MAIL_*' FATAL \
4944        -dev /dev/sr0 \
4945        -volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
4946        -not_leaf '*.o' -not_leaf '*.swp' \
4947        -update_r /home/thomas/projects /projects \
4948        -update_r /home/thomas/personal_mail /personal_mail \
4949        -commit -toc -check_md5 FAILURE -- -eject all
4950       To  be used several times on the same medium, whenever an update of the
4951       two disk trees to the medium is desired. Begin with a blank medium  and
4952       update it until the run fails gracefully due to lack of remaining space
4953       on the old one.
4954       This makes sense  if  the  full  backup  leaves  substantial  remaining
4955       capacity on media and if the expected changes are much smaller than the
4956       full backup.  To apply zisofs compression to those data files which get
4957       newly   copied   from  the  local  filesystem,  insert  these  commands
4958       immediately before -commit :
4959        -hardlinks perform_update \
4960        -find / -type f -pending_data -exec set_filter --zisofs -- \
4961       Commands -disk_dev_ino and -for_backup  depend  on  stable  device  and
4962       inode numbers on disk. Without them, an update run may use -md5 "on" to
4963       match recorded MD5 sums against the current file content on hard  disk.
4964       This  is  usually  much  faster  than  the  default which compares both
4965       contents directly.
4966       With mount option -o "sbsector=" on  GNU/Linux  or  -s  on  FreeBSD  or
4967       NetBSD  it  is possible to access the session trees which represent the
4968       older backup versions. With CD media, GNU/Linux mount  accepts  session
4969       numbers directly by its option "session=".
4970       Multi-session media and most overwriteable media written by xorriso can
4971       tell the sbsectors of their sessions by  xorriso  command  -toc.   Used
4972       after  -commit  the following command prints the matching mount command
4973       for the newly written session (here for mount point /mnt):
4974        -mount_cmd "indev" "auto" "auto" /mnt
4975       Commands -mount_cmd and -mount are  also  able  to  produce  the  mount
4976       commands for older sessions in the table-of-content. E.g. as superuser:
4977        # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
4978
4979       Above  example  produces  a result similar to  -root / -old-root / with
4980       mkisofs.   For  getting  the  session  trees  accumulated  in  the  new
4981       sessions,  let  all  -update commands use a common parent directory and
4982       clone it after updating is done:
4983        -update_r /home/thomas/projects /current/projects \
4984        -update_r /home/thomas/personal_mail /current/personal_mail \
4985        -clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \
4986       The cloned tree will have a name like /2011_02_12_155700.
4987
4988       Sessions on multi-session media are separated by several MB  of  unused
4989       blocks.   So  with  small  sessions  the  payload  capacity  can become
4990       substantially lower than the overall media capacity. If  the  remaining
4991       space  on  a  medium  does  not  suffice for the next gap, the drive is
4992       supposed to close the medium automatically.
4993
4994       Better do not use your youngest backup for -update_r.   Have  at  least
4995       two  media  which  you  use  alternatingly.  So  only older backups get
4996       endangered by the new write  operation,  while  the  newest  backup  is
4997       stored safely on a different medium.
4998       Always  have  a blank medium ready to perform a full backup in case the
4999       update attempt fails  due  to  insufficient  remaining  capacity.  This
5000       failure will not spoil the old medium, of course.
5001
5002   Restore directory trees from a particular ISO session to disk
5003       This  is  an  alternative  to mounting the medium and using normal file
5004       operations.
5005       First check which backup sessions are on the medium:
5006       $ xorriso -outdev /dev/sr0 -toc
5007       Then enable restoring of ACL, xattr and hard links.  Load  the  desired
5008       session   and   copy   the   file  trees  to  disk.   Avoid  to  create
5009       /home/thomas/restored without rwx-permission.
5010       $ xorriso -for_backup \
5011        -load volid 'PROJECTS_MAIL_2008_06_19*' \
5012        -indev /dev/sr0 \
5013        -osirrox on:auto_chmod_on \
5014        -chmod u+rwx / -- \
5015        -extract /projects /home/thomas/restored/projects \
5016        -extract /personal_mail /home/thomas/restored/personal_mail \
5017        -rollback_end
5018       The final command -rollback_end prevents an  error  message  about  the
5019       altered image being discarded.
5020
5021   Try to retrieve blocks from a damaged medium
5022       $ xorriso -abort_on NEVER -indev /dev/sr0 \
5023        -check_media time_limit=1800 report=blocks_files \
5024        data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --
5025       This  can  be  repeated several times, if necessary with -eject or with
5026       other   -indev   drives.   See   the    human    readable    part    of
5027       "$HOME"/dvd_copy.map    for    addresses   which   can   be   used   on
5028       "$HOME"/dvd_copy with mount option -o sbsector= or -s.
5029

FILES

5031   Program alias names:
5032       Normal installation of xorriso creates three links or copies  which  by
5033       their program name pre-select certain settings:
5034       xorrisofs starts xorriso with -as mkisofs emulation.
5035       xorrecord starts xorriso with -as cdrecord emulation.
5036       osirrox  starts  with  -osirrox  "on:o_excl_off"  which  allows further
5037       commands to copy files from ISO image to  disk  and  to  apply  command
5038       -mount to one or more of the existing ISO sessions.
5039
5040   Startup files:
5041       If  not  -no_rc is given as the first argument then xorriso attempts on
5042       startup to read and execute lines from the following files:
5043          /etc/default/xorriso
5044          /etc/opt/xorriso/rc
5045          /etc/xorriso/xorriso.conf
5046          $HOME/.xorrisorc
5047       The files are read in the sequence given above, but  none  of  them  is
5048       required   to   exist.  The  line  format  is  described  with  command
5049       -options_from_file.
5050       If  mkisofs  emulation  was  enabled  by  program   name   "xorrisofs",
5051       "mkisofs",    "genisoimage",    or    "genisofs",    then    afterwards
5052       -read_mkisofsrc is performed, which reads .mkisofsrc files. See there.
5053
5054   Runtime control files:
5055       The default setting of -check_media abort_file= is:
5056          /var/opt/xorriso/do_abort_check_media
5057
5058

ENVIRONMENT

5060       The following environment variables influence the program behavior:
5061       HOME is used to find startup files of xorriso and mkisofs.
5062       SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org.   It
5063       is supposed to be either undefined or to contain a decimal number which
5064       tells the seconds since january 1st 1970. If it contains a number, then
5065       it  is  used  as  time value to set the default of -volume date "uuid",
5066       sets  -boot_image   "any"   "gpt_disk_guid="   to   "volume_date_uuid",
5067       -volume_date  "all_file_dates"  to  "set_to_mtime", and -iso_nowtime to
5068       "=$SOURCE_DATE_EPOCH".
5069       Startup  files  and  program  options  can  override  the   effect   of
5070       SOURCE_DATE_EPOCH.
5071
5072

SEE ALSO

5074       For the mkisofs emulation of xorriso
5075              xorrisofs(1)
5076
5077       For the cdrecord emulation of xorriso
5078              xorrecord(1)
5079
5080       For mounting xorriso generated ISO 9660 images (-t iso9660)
5081              mount(8)
5082
5083       Libreadline, a comfortable input line facility
5084              readline(3)
5085
5086       Other programs which produce ISO 9660 images
5087              mkisofs(8), genisoimage(1)
5088
5089       Other programs which burn sessions to optical media
5090              growisofs(1), cdrecord(1), wodim(1), cdrskin(1)
5091
5092       ACL and xattr
5093              getfacl(1), setfacl(1), getfattr(1), setfattr(1)
5094
5095       MD5 checksums
5096              md5sum(1)
5097
5098       On FreeBSD the commands for xattr and MD5 differ
5099              getextattr(8), setextattr(8), md5(1)
5100

BUGS

5102       To  report  bugs,  request  help,  or suggest enhancements for xorriso,
5103       please send electronic mail to the public  list  <bug-xorriso@gnu.org>.
5104       If more privacy is desired, mail to <scdbackup@gmx.net>.
5105       Please describe what you expect xorriso to do, the program arguments or
5106       dialog commands by which you tried  to  achieve  it,  the  messages  of
5107       xorriso, and the undesirable outcome of your program run.
5108       Expect to get asked more questions before solutions can be proposed.
5109

AUTHOR

5111       Thomas Schmitt <scdbackup@gmx.net>
5112       for libburnia-project.org
5113
5115       Copyright (c) 2007 - 2019 Thomas Schmitt
5116       Permission  is granted to distribute this text freely. It shall only be
5117       modified in sync with the technical properties of xorriso.  If you make
5118       use  of the license to derive modified versions of xorriso then you are
5119       entitled to modify this text under that same license.
5120

CREDITS

5122       xorriso is in part  based  on  work  by  Vreixo  Formoso  who  provides
5123       libisofs  together  with Mario Danic who also leads the libburnia team.
5124       Vladimir Serbinenko contributed the HFS+ filesystem  code  and  related
5125       knowledge.   Thanks  to Andy Polyakov who invented emulated growing, to
5126       Derek Foreman and Ben Jansens who once founded libburn.
5127       Compliments towards Joerg Schilling whose cdrtools served  me  for  ten
5128       years.
5129
5130
5131
5132                          Version 1.5.2, Oct 26, 2019               XORRISO(1)
Impressum