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-usable 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 overwritable media or disk files which carry valid ISO
90       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       Overwritable 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  overwritable  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       Overwritable media are considered blank if they are new or if they have
144       been marked as blank by xorriso.  Action -blank "as_needed" can be used
145       to do this  marking  on  overwritable  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 overwritable media
149       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       Overwritable  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 usable for reading an ISO image.
220       With any type of drive object, the data are considered to be  organized
221       in  blocks  of  2 KiB. Access happens in terms of Logical Block Address
222       (LBA) which gives the number of a particular data block.
223
224       MMC compliant (i.e. optical) drives on GNU/Linux usually get  addressed
225       by the path of their block device or of their generic character device.
226       E.g.
227         -dev /dev/sr0
228         -dev /dev/hdc
229         -dev /dev/sg2
230       By default xorriso will try to map the given address  to  /dev/hd*  and
231       /dev/sr*.   The  command -scsi_dev_family can redirect the mapping from
232       sr to scd or sg.  The latter  does  not  suffer  from  the  concurrency
233       problems  which plague /dev/sr of Linux kernels since version 3. But it
234       does not yield the same addresses which are  used  by  mount(8)  or  by
235       open(2) for read(2).
236       On FreeBSD the device files have names like
237         -dev /dev/cd0
238       On NetBSD:
239         -dev /dev/rcd0d
240       On OpenSolaris:
241         -dev /dev/rdsk/c4t0d0s2
242       Get a list of accessible drives by command
243         -device_links
244       It  might  be  necessary  to  do  this as superuser in order to see all
245       drives and to then allow rw-access for the intended users.  Consider to
246       bundle the authorized users in a group like old "floppy".
247
248       Filesystem  objects  of  nearly  any  type  can  be addressed by prefix
249       "stdio:" and their path in the filesystem. E.g.:
250         -dev stdio:/dev/sdc
251       The default setting of -drive_class allows the user  to  address  files
252       outside the /dev tree without that prefix. E.g.:
253         -dev /tmp/pseudo_drive
254       If  path leads to a regular file or to a block device then the emulated
255       drive is random access readable and can  be  used  for  the  method  of
256       growing  if  it already contains a valid ISO 9660 image. Any other file
257       type is not readable via "stdio:" and can only be used  as  target  for
258       the  method  of  modifying  or  blind  growing.   Non-existing paths in
259       existing directories are handled as empty regular files.
260
261       A very special kind of pseudo drive are open file descriptors. They are
262       depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open).
263       Addresses  "-"  or  "stdio:/dev/fd/1"  depict  standard  output,  which
264       normally is the output channel for result texts.  To  prevent  a  fatal
265       intermingling  of  ISO  image  and  text messages, all result texts get
266       redirected to stderr if -*dev "-" or  "stdio:/dev/fd/1"  is  among  the
267       start arguments of the program.
268       Standard  output  is  currently  suitable  for creating one session per
269       program run without dialog. Use in other situations is discouraged  and
270       several restrictions apply:
271       It  is not allowed to use standard output as pseudo drive if it was not
272       among the start arguments. Do not try to fool  this  ban  via  backdoor
273       addresses to stdout.
274       If stdout is used as drive, then -use_readline is permanently disabled.
275       Use of backdoors can cause severe memory and/or tty corruption.
276
277       Be aware that especially the superuser can write  into  any  accessible
278       file  or  device by using its path with the "stdio:" prefix. By default
279       any address in the /dev tree without prefix "stdio:" will work only  if
280       it leads to a MMC drive.
281       One may use command -ban_stdio_write to surely prevent this risk and to
282       restrict drive usage to MMC drives.
283       One may prepend "mmc:" to a  path  to  surely  disallow  any  automatic
284       "stdio:".
285       By  command  -drive_class  one  may  ban  certain paths or allow access
286       without prefix "stdio:" to other paths.
287
288   Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
289       Rock Ridge is the name of a set of additional information which enhance
290       an  ISO  9660  filesystem  so  that  it can represent a POSIX compliant
291       filesystem with ownership,  access  permissions,  symbolic  links,  and
292       other attributes.
293       This is what xorriso uses for a decent representation of the disk files
294       within the ISO  image.  xorriso  produces  Rock  Ridge  information  by
295       default. It is strongly discouraged to disable this feature.
296
297       xorriso  is  not  named  "porriso"  because  POSIX  only  guarantees 14
298       characters of filename  length.  It  is  the  X/Open  System  Interface
299       standard  XSI  which demands a file name length of up to 255 characters
300       and paths of up to 1024 characters. Rock Ridge fulfills this demand.
301
302       An El Torito boot record points the BIOS bootstrapping facility to  one
303       or  more  boot images, which are binary program files stored in the ISO
304       image.  The content of the boot image files is not in the scope  of  El
305       Torito.
306       Most  bootable  GNU/Linux  CDs  are equipped with ISOLINUX or GRUB boot
307       images.  xorriso is able to create or  maintain  an  El  Torito  object
308       which   makes   such   an  image  bootable.  For  details  see  command
309       -boot_image.
310       It is possible to make ISO images bootable  from  USB  stick  or  other
311       hard-disk-like  media.  Several  options  install  a  MBR  (Master Boot
312       Record), It may get adjusted according to the  needs  of  the  intended
313       boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX.  A
314       MBR contains boot code and  a  partition  table.   The  new  MBR  of  a
315       follow-up session can get in effect only on overwritable media.
316       MBR is read by PC-BIOS when booting from USB stick or hard disk, and by
317       PowerPC CHRP or PReP when booting.  An MBR  partition  with  type  0xee
318       indicates the presence of GPT.
319       Emulation  -as mkisofs supports the example options out of the ISOLINUX
320       wiki, the options used in GRUB script grub-mkrescue, and the example in
321       the FreeBSD AvgLiveCD wiki.
322       A GPT (GUID Partition Table) marks partitions in a more modern way.  It
323       is read by EFI when booting from USB stick or hard  disk,  and  may  be
324       used for finding and mounting a HFS+ partition inside the ISO image.
325       An  APM  (Apple Partition Map) marks the HFS+ partition.  It is read by
326       Macs for booting and for mounting.
327       MBR, GPT and APM are combinable. APM occupies the first 8 bytes of  MBR
328       boot code. All three do not hamper El Torito booting from CDROM.
329       There  is  support  for further facilities: MIPS Big Endian (SGI), MIPS
330       Little  Endian  (DEC),  SUN  SPARC,  HP-PA.   Those  are  mutually  not
331       combinable and also not combinable with MBR, GPT, or APM.
332
333       ACL  are  an  advanced  way  of  controlling access permissions to file
334       objects. Neither ISO 9660 nor Rock Ridge specify a way to record  ACLs.
335       So  libisofs  has introduced a standard conformant extension named AAIP
336       for that purpose.  It uses this extension if enabled by command -acl.
337       AAIP enhanced images are supposed to be  mountable  normally,  but  one
338       cannot  expect  that  the  mounted filesystem will show and respect the
339       ACLs.  For now, only xorriso is able to retrieve those  ACLs.   It  can
340       bring  them  into effect when files get restored to an ACL enabled file
341       system or it can print them in a format suitable for tool setfacl.
342       Files with ACL show as group permissions the setting of entry  "mask::"
343       if  that  entry  exists.  Nevertheless the non-listed group members get
344       handled according to entry "group::". When removing ACL  from  a  file,
345       xorriso brings "group::" into effect.
346       Recording and restoring of ACLs from and to local files works currently
347       only on GNU/Linux and FreeBSD.
348
349       xattr (aka EA, or extattr) are pairs of name and  value  which  can  be
350       attached  to  file  objects. AAIP is able to represent them and xorriso
351       can record and restore them.
352       But be aware that pairs with  names  of  non-user  namespaces  are  not
353       necessarily  portable  between  operating  systems and not even between
354       filesystems.  Only those which begin with  "user.",  like  "user.x"  or
355       "user.whatever",  can  unconditionally be expected to be appropriate on
356       other  machines  and  disks.   Processing  of  other  xattr  may   need
357       administrator privileges.
358       Name  has to be a 0 terminated string.  Value may be any array of bytes
359       which does not exceed the size of 4095 bytes.  xattr processing happens
360       only if it is enabled by command -xattr.
361       As with ACL, currently only xorriso is able to retrieve xattr from AAIP
362       enhanced images, to restore them to xattr capable file systems,  or  to
363       print them.
364       Recording  and  restoring  of  xattr  from  and  to  local  files works
365       currently only on GNU/Linux  and  FreeBSD,  where  they  are  known  as
366       extattr.
367
368   Command processing:
369       Commands  are either actions which happen immediately or settings which
370       influence following actions. So their sequence does matter, unless they
371       are given as program arguments and command -x is among them.
372       Commands  consist of a command word, followed by zero or more parameter
373       words. If the list of parameter words is of variable length  (indicated
374       by  "[...]"  or  "[***]") then it must be terminated by either the list
375       delimiter, occur at the end of the argument list, or occur at  the  end
376       of an input line.
377
378       At  program  start  the list delimiter is the string "--".  This may be
379       changed with the -list_delimiter command in  order  to  allow  "--"  as
380       parameter  in  a variable length list.  However, it is advised to reset
381       the delimiter to "--" immediately afterwards.
382       For brevity the list delimiter is  referred  as  "--"  throughout  this
383       text.
384       The  list  delimiter  is  silently  ignored  if  it  appears  after the
385       parameters of a command with a fixed list  length.  It  is  handled  as
386       normal text if it appears among the parameters of such a command.
387
388       Pattern  expansion  converts  a  list  of  pattern words into a list of
389       existing file addresses.  Unmatched pattern words will appear unaltered
390       in that result list.
391       Pattern  matching  supports  the  usual  shell parser wildcards '*' '?'
392       '[xyz]' and respects '/' as the  path  separator,  which  may  only  be
393       matched literally.
394       Pattern  expansion  is a property of some particular commands and not a
395       general feature. It  is  controlled  by  commands  -iso_rr_pattern  and
396       -disk_pattern.   Commands which use pattern expansion all have variable
397       parameter lists which are specified in this text by "[***]" rather than
398       "[...]".
399       Some other commands perform pattern matching unconditionally.
400
401       Command and parameter words are either read from the program arguments,
402       where one argument is one word, or from quoted input lines where  words
403       are recognized similar to the quotation rules of a shell parser.
404       xorriso  is  not a shell, although it might appear so at first glimpse.
405       Be aware that the interaction of quotation marks  and  pattern  symbols
406       like  "*" differs from the usual shell parsers. In xorriso, a quotation
407       mark does not make a pattern symbol literal.
408
409       Quoted input converts whitespace-separated text into words.  The double
410       quotation mark " and the single quotation mark ' can be used to enclose
411       whitespace and make it part of words (e.g. of file  names).  Each  mark
412       type  can  enclose  the marks of the other type. A trailing backslash \
413       outside quotations or an open quotation cause the next input line to be
414       appended.
415       Quoted  input accepts any 8-bit character except NUL (0) as the content
416       of the quotes.  Nevertheless it can  be  cumbersome  for  the  user  to
417       produce  those  characters directly. Therefore quoted input and program
418       arguments offer optional Backslash Interpretation which  can  represent
419       all 8-bit characters except NUL (0) via backslash codes as in $'...' of
420       bash.
421       This is not enabled by default. See command -backslash_codes.
422
423       When the program starts then it first looks  for  argument  -no_rc.  If
424       this is not present then it looks for its startup files and reads their
425       content  as  command  input  lines.  Then  it  interprets  the  program
426       arguments  as commands and parameters. Finally it enters dialog mode if
427       command -dialog "on" has been executed by this point.
428
429       The program ends either by command -end,  or  by  the  end  of  program
430       arguments  if  dialog  mode has not been enabled at that point, or by a
431       problem event which triggers the threshold of command -abort_on.
432
433   Dialog, Readline, Result pager:
434       Dialog mode prompts for a quoted input line, parses it into words,  and
435       performs  them as commands with their parameters. It provides assisting
436       services to make dialog more comfortable.
437
438       Readline is an enhancement for the input line. You may already know  it
439       from  the bash shell. Whether it is available in xorriso depends on the
440       availability of package readline-dev at the time when xorriso was built
441       from its sourcecode.
442       Readline  lets  the  user  move the cursor over the text in the line by
443       help of the Left and the Right arrow keys.  Text may be inserted at the
444       cursor position. The Delete key removes the character under the cursor.
445       Up and Down arrow keys navigate through the history of  previous  input
446       lines.
447       See man readline for more info about libreadline.
448
449       Command  -page  activates  a  built-in  result  text pager which may be
450       convenient in dialog mode. After an action has output the given  number
451       of terminal lines, the pager prompts the user for a line of input.
452       An empty line lets xorriso resume work until the next page is output.
453       The single character "@" disables paging for the current action.
454       "@@@", "x", "q", "X", or "Q" request that the current action aborts and
455       suppress further result output.
456       Any other line input will  be  interpreted  as  new  dialog  line.  The
457       current  action  is  requested  to abort. Afterwards, the input line is
458       executed.
459
460       Some actions apply paging to their info output, too.
461       The request to abort may or may not be obeyed by  the  current  action.
462       All actions try to abort as soon as possible.
463

OPTIONS

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

EXAMPLES

4930   Overview of examples:
4931       As superuser learn about available drives
4932       Blank medium and compose a new ISO image as batch run
4933       A dialog session doing about the same
4934       Manipulate an existing ISO image on the same medium
4935       Copy modified ISO image from one medium to another
4936       Bring a prepared ISOLINUX tree onto medium and make it bootable
4937       Change existing file name tree from ISO-8859-1 to UTF-8
4938       Operate on storage facilities other than optical drives
4939       Burn an existing ISO image file to medium
4940       Perform multi-session runs as of cdrtools traditions
4941       Let xorriso work underneath growisofs
4942       Adjust thresholds for verbosity, exit value and program abort
4943       Examples of input timestrings
4944       Incremental backup of a few directory trees
4945       Restore directory trees from a particular ISO session to disk
4946       Try to retrieve blocks from a damaged medium
4947
4948   As superuser learn about available drives
4949       On  Linux,  FreeBSD  or NetBSD consider to give rw-permissions to those
4950       users or groups which shall be able to use the drives with xorriso.  On
4951       Solaris  use  pfexec.  Consider  to  restrict  privileges of xorriso to
4952       "base,sys_devices" and to give r-permission to user or group.
4953       $ xorriso -device_links
4954       1  -dev '/dev/cdrom1' rwrw-- :  'TSSTcorp' 'DVD-ROM SH-D162C
4955       1  -dev '/dev/cdrw'   rwrw-- :  'TSSTcorp' 'CDDVDW SH-S223B'
4956       2  -dev '/dev/cdrw3'  rwrw-- :  'HL-DT-ST' 'BDDVDRW_GGC-H20L'
4957
4958   Blank medium and compose a new ISO image as batch run
4959       Acquire drive /dev/sr2, make medium ready for writing a new image, fill
4960       the image with the files from hard disk directories /home/me/sounds and
4961       /home/me/pictures.
4962       Because no -dialog "on" is given, the program will then end by  writing
4963       the session to the medium.
4964       $ xorriso -outdev /dev/sr2 \
4965        -blank as_needed \
4966        -map /home/me/sounds /sounds \
4967        -map /home/me/pictures /pictures
4968
4969       The ISO image may be shaped in a more elaborate way like the following:
4970       Omit some unwanted stuff by removing it from the image directory  tree.
4971       Reintroduce some wanted stuff.
4972       $ cd /home/me
4973       $ xorriso -outdev /dev/sr2 \
4974        -blank as_needed \
4975        -map /home/me/sounds /sounds \
4976        -map /home/me/pictures /pictures \
4977        -rm_r \
4978          /sounds/indecent \
4979          '/pictures/*private*' \
4980          /pictures/confidential \
4981          -- \
4982        -cd / \
4983        -add pictures/confidential/work* --
4984       Note  that  '/pictures/*private*'  is  a pattern for iso_rr_paths while
4985       pictures/confidential/work* gets expanded by the shell  with  addresses
4986       from  the  hard  disk.  Commands -add and -map have different parameter
4987       rules but finally the same effect: they put files into the image.
4988
4989   A dialog session doing about the same
4990       Some settings are already given as start argument. The other activities
4991       are  done  as  dialog  input.  The  pager  gets  set  to 20 lines of 80
4992       characters.
4993       The drive is acquired by command -dev rather than -outdev in  order  to
4994       see  the  message  about  its  current  content. By command -blank this
4995       content is made ready for being overwritten and the loaded ISO image is
4996       made empty.
4997       In  order  to  be  able  to  eject  the medium, the session needs to be
4998       committed explicitly.
4999       $ xorriso -dialog on -page 20 80 -disk_pattern on
5000       enter option and arguments :
5001       -dev /dev/sr2
5002       enter option and arguments :
5003       -blank as_needed
5004       enter option and arguments :
5005       -map /home/me/sounds /sounds -map /home/me/pictures /pictures
5006       enter option and arguments :
5007       -rm_r /sounds/indecent /pictures/*private* /pictures/confidential
5008       enter option and arguments :
5009       -cdx /home/me/pictures -cd /pictures
5010       enter option and arguments :
5011       -add confidential/office confidential/factory
5012       enter option and arguments :
5013       -du /
5014       enter option and arguments :
5015       -commit_eject all -end
5016
5017   Manipulate an existing ISO image on the same medium
5018       Load image from drive.  Remove (i.e. hide) directory  /sounds  and  its
5019       subordinates.      Rename     directory    /pictures/confidential    to
5020       /pictures/restricted.    Change   access   permissions   of   directory
5021       /pictures/restricted.   Add  new  directory  trees /sounds and /movies.
5022       Burn to the same medium, check whether the  tree  can  be  loaded,  and
5023       eject.
5024       $ xorriso -dev /dev/sr2 \
5025        -rm_r /sounds -- \
5026        -mv \
5027          /pictures/confidential \
5028          /pictures/restricted \
5029          -- \
5030        -chmod go-rwx /pictures/restricted -- \
5031        -map /home/me/prepared_for_dvd/sounds_dummy /sounds \
5032        -map /home/me/prepared_for_dvd/movies /movies \
5033        -commit -eject all
5034
5035   Copy modified ISO image from one medium to another
5036       Load  image  from  input  drive.  Do  the  same manipulations as in the
5037       previous example. Acquire output drive and blank it. Burn the  modified
5038       image as first and only session to the output drive.
5039       $ xorriso -indev /dev/sr2 \
5040        -rm_r /sounds -- \
5041        ...
5042        -outdev /dev/sr0 -blank as_needed \
5043        -commit -eject all
5044
5045   Bring a prepared ISOLINUX tree onto medium and make it bootable
5046       The  user  has  already created a suitable file tree on disk and copied
5047       the ISOLINUX files into subdirectory ./boot/isolinux of that tree.  Now
5048       xorriso can burn an El Torito bootable medium:
5049       $ xorriso -outdev /dev/sr0 -blank as_needed \
5050          -map /home/me/ISOLINUX_prepared_tree / \
5051          -boot_image isolinux dir=/boot/isolinux
5052
5053   Change existing file name tree from ISO-8859-1 to UTF-8
5054       This  example  assumes  that  the  existing  ISO image was written with
5055       character set ISO-8859-1 but that the readers expected UTF-8. Now a new
5056       session gets added with converted file names.  Command -changes_pending
5057       "yes" enables writing despite the lack of any manipulation command.
5058       In order to avoid any weaknesses  of  the  local  character  set,  this
5059       command  pretends  that  it  uses  already  the final target set UTF-8.
5060       Therefore strange file names may appear in messages, which will be made
5061       terminal-safe by command -backslash_codes.
5062       $ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
5063          -out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
5064          -changes_pending yes -commit -eject all
5065
5066   Operate on storage facilities other than optical drives
5067       Full  read-write  operation  is  possible  with regular files and block
5068       devices:
5069       $ xorriso -dev /tmp/regular_file ...
5070       Paths underneath /dev normally need prefix "stdio:"
5071       $ xorriso -dev stdio:/dev/sdb ...
5072       If /dev/sdb is to be used frequently and /dev/sda is the  system  disk,
5073       then  consider  to place the following lines in a xorriso Startup File.
5074       They allow you to use /dev/sdb without prefix and protect disk /dev/sda
5075       from xorriso:
5076         -drive_class banned   /dev/sda*
5077         -drive_class harmless /dev/sdb
5078       Other writeable file types are supported write-only:
5079       $ xorriso -outdev /tmp/named_pipe ...
5080       Among the write-only drives is standard output:
5081       $ xorriso -outdev - \
5082        ...
5083        | gzip >image.iso.gz
5084
5085   Burn an existing ISO image file to medium
5086       Actually this works with any kind of data, not only ISO images:
5087       $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso
5088
5089   Perform multi-session runs as of cdrtools traditions
5090       Between  both processes there can be performed arbitrary transportation
5091       or filtering.
5092       The first session is written like this:
5093       $ xorriso -as mkisofs prepared_for_iso/tree1 | \
5094        xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
5095       Follow-up sessions are written like this (the run of dd is only to give
5096       demons a chance to spoil it):
5097       $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
5098       $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
5099       $ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \
5100        xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
5101       Always eject the drive tray between sessions.
5102       The  run  of  xorriso -as mkisofs will read old sessions via the CD-ROM
5103       driver of /dev/sr0. This driver might  not  be  aware  of  the  changed
5104       content  as  long  as  the medium is not loaded again. In this case the
5105       previous session would not be properly assessed by xorriso and the  new
5106       session would contain only the newly added files.
5107       Some  systems  have not enough patience with automatic tray loading and
5108       some demons may interfere with a first CD-ROM driver read attempt  from
5109       a freshly loaded medium.
5110       When  loading  the  tray  manually, wait 10 seconds after the drive has
5111       stopped blinking.
5112       A safe automatic way seems to be a separate run of xorriso for  loading
5113       the  tray  with  proper waiting, and a subsequent run of dd which shall
5114       offer itself to any problems caused by  demons  assessing  the  changed
5115       drive  status.   If  this  does  not  help,  insert a run of "sleep 10"
5116       between xorriso and dd.
5117       This example works for multi-session media only.   Add  cdrskin  option
5118       --grow_overwriteable_iso  to  all  -as cdrecord runs in order to enable
5119       multi-session emulation on overwritable media.
5120
5121   Let xorriso work underneath growisofs
5122       growisofs expects an ISO formatter program which understands options -C
5123       and -M. If xorriso gets started by name "xorrisofs" then it is suitable
5124       for that.
5125       $ export MKISOFS="xorrisofs"
5126       $ growisofs -Z /dev/dvd /some/files
5127       $ growisofs -M /dev/dvd /more/files
5128       If no "xorrisofs" is available on your system, then you  will  have  to
5129       create  a link pointing to the xorriso binary and tell growisofs to use
5130       it.  E.g. by:
5131       $ ln -s $(which xorriso) "$HOME/xorrisofs"
5132       $ export MKISOFS="$HOME/xorrisofs"
5133       One may quit mkisofs emulation by argument "--" and  make  use  of  all
5134       xorriso  commands. growisofs dislikes options which start with "-o" but
5135       -outdev must be set to "-".  So use "outdev" instead:
5136       $ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files
5137       $ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files
5138       growisofs has excellent burn capabilities with DVD and BD.  It does not
5139       emulate session history on overwritable media, though.
5140
5141   Adjust thresholds for verbosity, exit value and program abort
5142       Be quite verbose, exit 32 if severity "FAILURE" was encountered, do not
5143       abort prematurely but forcibly go on until the end of commands.
5144       $ xorriso ... \
5145        -report_about UPDATE \
5146        -return_with FAILURE 32 \
5147        -abort_on NEVER \
5148        ...
5149
5150   Examples of input timestrings
5151       As printed by program date: 'Thu Nov 8 14:51:13 CET 2007'
5152       The same without ignored parts: 'Nov 8 14:51:13 2007'
5153       The same as expected by date: 110814512007.13
5154       Four weeks in the future: +4w
5155       The current time: +0
5156       Three hours ago: -3h
5157       Seconds since Jan 1 1970: =1194531416
5158
5159   Incremental backup of a few directory trees
5160       This changes the directory trees /projects and  /personal_mail  in  the
5161       ISO  image so that they become exact copies of their disk counterparts.
5162       ISO file objects get created, deleted or get their attributes  adjusted
5163       accordingly.
5164       ACL, xattr, hard links and MD5 checksums will be recorded.  Accelerated
5165       comparison is enabled at the expense of potentially larger backup size.
5166       Only  media  with  the  expected volume ID or blank media are accepted.
5167       Files with names matching *.o or *.swp get excluded explicitly.
5168       When done with writing the new session gets  checked  by  its  recorded
5169       MD5.
5170       $ xorriso \
5171        -abort_on FATAL \
5172        -for_backup -disk_dev_ino on \
5173        -assert_volid 'PROJECTS_MAIL_*' FATAL \
5174        -dev /dev/sr0 \
5175        -volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
5176        -not_leaf '*.o' -not_leaf '*.swp' \
5177        -update_r /home/thomas/projects /projects \
5178        -update_r /home/thomas/personal_mail /personal_mail \
5179        -commit -toc -check_md5 FAILURE -- -eject all
5180       To  be used several times on the same medium, whenever an update of the
5181       two disk trees to the medium is desired. Begin with a blank medium  and
5182       update it until the run fails gracefully due to lack of remaining space
5183       on the old one.
5184       This makes sense  if  the  full  backup  leaves  substantial  remaining
5185       capacity on media and if the expected changes are much smaller than the
5186       full backup.  To apply zisofs compression to those data files which get
5187       newly   copied   from  the  local  filesystem,  insert  these  commands
5188       immediately before -commit :
5189        -hardlinks perform_update \
5190        -find / -type f -pending_data -exec set_filter --zisofs -- \
5191       Commands -disk_dev_ino and -for_backup  depend  on  stable  device  and
5192       inode numbers on disk. Without them, an update run may use -md5 "on" to
5193       match recorded MD5 sums against the current file content on hard  disk.
5194       This  is  usually  much  faster  than  the  default which compares both
5195       contents directly.
5196       With mount option -o "sbsector=" on  GNU/Linux  or  -s  on  FreeBSD  or
5197       NetBSD  it  is possible to access the session trees which represent the
5198       older backup versions. With CD media, GNU/Linux mount  accepts  session
5199       numbers directly by its option "session=".
5200       Multi-session  media and most overwritable media written by xorriso can
5201       tell the sbsectors of their sessions by  xorriso  command  -toc.   Used
5202       after  -commit  the following command prints the matching mount command
5203       for the newly written session (here for mount point /mnt):
5204        -mount_cmd "indev" "auto" "auto" /mnt
5205       Commands -mount_cmd and -mount are  also  able  to  produce  the  mount
5206       commands for older sessions in the table-of-content. E.g. as superuser:
5207        # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
5208
5209       Above  example  produces  a result similar to  -root / -old-root / with
5210       mkisofs.   For  getting  the  session  trees  accumulated  in  the  new
5211       sessions,  let  all  -update commands use a common parent directory and
5212       clone it after updating is done:
5213        -update_r /home/thomas/projects /current/projects \
5214        -update_r /home/thomas/personal_mail /current/personal_mail \
5215        -clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \
5216       The cloned tree will have a name like /2011_02_12_155700.
5217
5218       Sessions on multi-session media are separated by several MB  of  unused
5219       blocks.   So  with  small  sessions  the  payload  capacity  can become
5220       substantially lower than the overall media capacity. If  the  remaining
5221       space  on  a  medium  does  not  suffice for the next gap, the drive is
5222       supposed to close the medium automatically.
5223
5224       Better do not use your youngest backup for -update_r.   Have  at  least
5225       two  media  which  you  use  alternatingly.  So  only older backups get
5226       endangered by the new write  operation,  while  the  newest  backup  is
5227       stored safely on a different medium.
5228       Always  have  a blank medium ready to perform a full backup in case the
5229       update attempt fails  due  to  insufficient  remaining  capacity.  This
5230       failure will not spoil the old medium, of course.
5231
5232   Restore directory trees from a particular ISO session to disk
5233       This  is  an  alternative  to mounting the medium and using normal file
5234       operations.
5235       First check which backup sessions are on the medium:
5236       $ xorriso -outdev /dev/sr0 -toc
5237       Then enable restoring of ACL, xattr and hard links.  Load  the  desired
5238       session   and   copy   the   file  trees  to  disk.   Avoid  to  create
5239       /home/thomas/restored without rwx-permission.
5240       $ xorriso -for_backup \
5241        -load volid 'PROJECTS_MAIL_2008_06_19*' \
5242        -indev /dev/sr0 \
5243        -osirrox on:auto_chmod_on \
5244        -chmod u+rwx / -- \
5245        -extract /projects /home/thomas/restored/projects \
5246        -extract /personal_mail /home/thomas/restored/personal_mail \
5247        -rollback_end
5248       The final command -rollback_end prevents an  error  message  about  the
5249       altered image being discarded.
5250
5251   Try to retrieve blocks from a damaged medium
5252       $ xorriso -abort_on NEVER -indev /dev/sr0 \
5253        -check_media time_limit=1800 report=blocks_files \
5254        data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --
5255       This  can  be  repeated several times, if necessary with -eject or with
5256       other   -indev   drives.   See   the    human    readable    part    of
5257       "$HOME"/dvd_copy.map    for    addresses   which   can   be   used   on
5258       "$HOME"/dvd_copy with mount option -o sbsector= or -s.
5259

FILES

5261   Program alias names:
5262       Normal installation of xorriso creates three links or copies  which  by
5263       their program name pre-select certain settings:
5264       xorrisofs starts xorriso with -as mkisofs emulation.
5265       xorrecord starts xorriso with -as cdrecord emulation.
5266       osirrox  starts  with  -osirrox  "on:o_excl_off"  which  allows further
5267       commands to copy files from ISO image to  disk  and  to  apply  command
5268       -mount to one or more of the existing ISO sessions.
5269
5270   Startup files:
5271       If  not  -no_rc is given as the first argument then xorriso attempts on
5272       startup to read and execute lines from the following files:
5273          /etc/default/xorriso
5274          /etc/opt/xorriso/rc
5275          /etc/xorriso/xorriso.conf
5276          $HOME/.xorrisorc
5277       The files are read in the sequence given above, but  none  of  them  is
5278       required   to   exist.  The  line  format  is  described  with  command
5279       -options_from_file.
5280       If  mkisofs  emulation  was  enabled  by  program   name   "xorrisofs",
5281       "mkisofs",    "genisoimage",    or    "genisofs",    then    afterwards
5282       -read_mkisofsrc is performed, which reads .mkisofsrc files. See there.
5283
5284   Runtime control files:
5285       The default setting of -check_media abort_file= is:
5286          /var/opt/xorriso/do_abort_check_media
5287
5288

ENVIRONMENT

5290       The following environment variables influence the program behavior:
5291       HOME is used to find startup files of xorriso and mkisofs.
5292       SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org.   It
5293       is supposed to be either undefined or to contain a decimal number which
5294       tells the seconds since january 1st 1970. If it contains a number, then
5295       it  is  used  as  time value to set the default of -volume date "uuid",
5296       sets  -boot_image   "any"   "gpt_disk_guid="   to   "volume_date_uuid",
5297       -volume_date  "all_file_dates"  to  "set_to_mtime", and -iso_nowtime to
5298       "=$SOURCE_DATE_EPOCH".
5299       Startup  files  and  program  options  can  override  the   effect   of
5300       SOURCE_DATE_EPOCH.
5301
5302

SEE ALSO

5304       For the mkisofs emulation of xorriso
5305              xorrisofs(1)
5306
5307       For the cdrecord emulation of xorriso
5308              xorrecord(1)
5309
5310       For mounting xorriso generated ISO 9660 images (-t iso9660)
5311              mount(8)
5312
5313       Libreadline, a comfortable input line facility
5314              readline(3)
5315
5316       Other programs which produce ISO 9660 images
5317              mkisofs(8), genisoimage(1)
5318
5319       Other programs which burn sessions to optical media
5320              growisofs(1), cdrecord(1), wodim(1), cdrskin(1)
5321
5322       ACL and xattr
5323              getfacl(1), setfacl(1), getfattr(1), setfattr(1)
5324
5325       MD5 checksums
5326              md5sum(1)
5327
5328       On FreeBSD the commands for xattr and MD5 differ
5329              getextattr(8), setextattr(8), md5(1)
5330

BUGS

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

AUTHOR

5341       Thomas Schmitt <scdbackup@gmx.net>
5342       for libburnia-project.org
5343
5345       Copyright (c) 2007 - 2021 Thomas Schmitt
5346       Permission  is granted to distribute this text freely. It shall only be
5347       modified in sync with the technical properties of xorriso.  If you make
5348       use  of the license to derive modified versions of xorriso then you are
5349       entitled to modify this text under that same license.
5350

CREDITS

5352       xorriso is in part  based  on  work  by  Vreixo  Formoso  who  provides
5353       libisofs  together  with Mario Danic who also leads the libburnia team.
5354       Vladimir Serbinenko contributed the HFS+ filesystem  code  and  related
5355       knowledge.   Thanks  to Andy Polyakov who invented emulated growing, to
5356       Derek Foreman and Ben Jansens who once founded libburn.
5357       Compliments towards Joerg Schilling whose cdrtools served  me  for  ten
5358       years.
5359
5360
5361
5362                          Version 1.5.4, Jan 30, 2021               XORRISO(1)
Impressum