libisoburn/xorriso/xorrisofs.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename xorrisofs.info
@settitle GNU xorrisofs 1.5.3
@c %**end of header
@c
@c man-ignore-lines begin
@dircategory Archiving
@direntry
* Xorrisofs: (xorrisofs).           Emulates ISO 9660 program mkisofs
@end direntry
@c man-ignore-lines end
@c
@c Notes about embedded man page:
@c This texinfo code contains the necessary info to produce a man page
@c which resembles much the version of xorriso.1 from which this code
@c was originally derived in march 2010.
@c One can produce the man page by applying the following rules:
@c   The first line gets discarded.
@c   Line start "@c man " will become "", the remainder is put out unaltered.
@c   Lines "@*" will be converted to ".br"
@c   "@c man-ignore-lines N"  will discard N following lines.
@c   "@c man-ignore-lines begin" discards all following lines
@c   up to "@c man-ignore-lines end".
@c   Line blocks of "@menu" "@end menu" will be discarded.
@c   "@item word words" becomes "\fBword\fR words".
@c   @b{...}, @command{...}, @dfn{...}, @emph{...}, @strong{...}
@c     get mapped to \fB...\fR .
@c   @abbr{...}, @code{...}, @file{...}, @i{...}, @option{...}, @r{...},
@c     @ref{...}, @samp{...},@var{...}, get mapped to ... .
@c   @ref{...}, @xref{...} get mapped to empty text.
@c   @email{...} gets mapped to <...> .
@c   Mapped {...} content is subject to the rules except {...} mapping.
@c   @minus{} will become "-".
@c   @@ , @{, @} will get stripped of their first @.
@c   Other lines which begin by "@" will be discarded.
@c   In lines not stemming from "@c man", "\" becomes "\\"
@c   "-" which are not preceded by an uneven number of "\" will get
@c     prepended one "\".
@c
@c
@c man .\"                                      Hey, EMACS: -*- nroff -*-
@c man .\"
@c man .\" IMPORTANT NOTE:
@c man .\"
@c man .\"        The original of this file is kept in xorriso/xorrisofs.texi
@c man .\"        This here was generated by program xorriso/make_xorriso_1
@c man .\"
@c man .\"
@c man .\" First parameter, NAME, should be all caps
@c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
@c man .\" other parameters are allowed: see man(7), man(1)
@c man .TH XORRISOFS 1 "Version 1.5.3, Sep 11, 2020"
@c man .\" Please adjust this date whenever revising the manpage.
@c man .\"
@c man .\" Some roff macros, for reference:
@c man .\" .nh        disable hyphenation
@c man .\" .hy        enable hyphenation
@c man .\" .ad l      left justify
@c man .\" .ad b      justify to both left and right margins
@c man .\" .nf        disable filling
@c man .\" .fi        enable filling
@c man .\" .br        insert line break
@c man .\" .sp <n>    insert n+1 empty lines
@c man .\" for manpage-specific macros, see man(7)
@c man .nh
@c man-ignore-lines begin
@copying
xorrisofs -  Emulation of ISO 9660 program mkisofs by program xorriso

Copyright @copyright{} 2011 - 2019 Thomas Schmitt

@quotation
Permission is granted to distribute this text freely.
@end quotation
@end copying
@c man-ignore-lines end
@titlepage
@title Manual of GNU xorriso personality xorrisofs 1.5.3
@author Thomas Schmitt
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top xorrisofs 1.5.3
@c man-ignore-lines 1

@c man .SH NAME
xorrisofs -  Emulation of ISO 9660 program mkisofs by program xorriso
@end ifnottex
@menu
* Overview::            Overview
* Standards::           ISO 9660, Rock Ridge, Joliet
* Insert::              Inserting files into the ISO image
* Xorriso::             Relation to program xorriso
* Options::             Options
* Examples::            Examples
* Files::               Files
* Environ::             Environment
* Seealso::             See also
* Bugreport::           Reporting bugs
* Legal::               Author, Copyright, Credits
* CommandIdx::          Alphabetic Command List
* ConceptIdx::          Alphabetic List of Concepts and Objects
@end menu
@node Overview, Standards, Top, Top
@chapter Overview
@c man .SH SYNOPSIS
@c man .B xorrisofs
@c man [ options ] [-o filename ] pathspec [pathspecs ...]
@c man .br
@c man .SH DESCRIPTION
@c man .PP
@command{xorrisofs}
produces Rock Ridge enhanced ISO 9660 filesystems and add-on sessions to
such filesystems. Optionally it can produce Joliet directory trees too.
@*
@sp 1
@c man .PP
@command{xorrisofs} understands options of program mkisofs from cdrtools by
Joerg Schilling.
Its implementation is part of program xorriso which shares no source
code with cdrtools.
@c man .SS
@node Standards, Insert, Overview, Top
@chapter ISO 9660, Rock Ridge, Joliet, HFS+
@c man \fBISO 9660, Rock Ridge, Joliet, HFS+:\fR
@c man .br
@cindex ISO 9660, _definition
@cindex ECMA-119, _definition
@strong{ISO 9660}
(aka @strong{ECMA-119}) is a read-only filesystem that is mainly used for
optical media CD, DVD, BD, but may also reside on other storage devices like
disk files, USB sticks or disk partitions. It is widely readable by many
operating systems and by boot facilities of personal computers.
@*
ISO 9660 describes directories and data files by
very restricted filenames with no distinction of upper case and lower case. 
Its metadata do not comply to fundamental POSIX specifications.
@*
@cindex Rock Ridge, _definition
@strong{Rock Ridge}
is the name of a set of additional information which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
Rock Ridge allows filenames of up to 255 bytes and paths of up to
1024 bytes.
@*
xorrisofs produces Rock Ridge information by default. It is strongly
discouraged to disable this feature.
@*
@cindex Joliet, _definition
@strong{Joliet} 
is the name of an additional directory tree which provides
filenames up to 64 characters encoded as UTF-16.
A Joliet tree is mainly interesting for reading the ISO image by
operating systems of Microsoft Corporation.
Production of this directory tree may be enabled by option -J.
@*
@cindex ISO 9660:1999, _definition
@strong{ISO 9660:1999}
is the name of an additional directory tree which provides longer
filenames. It allows single file names to have up to 207 characters.
It might be of use with some older computer system boot
facilities which read neither Rock Ridge nor Joliet but
need longer filenames nevertheless.
Production of this directory tree may be enabled by option -iso-level 4.
@*
@cindex HFS+, _definition
@strong{HFS+}
is the name of a filesystem which is normally used for writing and reading
on hard disks and similar devices. It is possible to embed a HFS+ partition
into the emerging ISO 9660 image and to mark it by Apple Partition Map
entries. This interferes with options which copy data into the first 32 KiB
of the ISO image, like -G or -isohybrid-mbr. See option -hfsplus.
@*
The main purpose for having an embedded HFS+ partition is booting of
certain models of Apple computers.
@c man .SS
@sp 1
@c man .B Inserting files into the ISO image:
@node Insert, Xorriso, Standards, Top
@chapter Inserting files into the ISO image
@c man .PP
@command{xorrisofs} deals with two kinds of file addresses:
@*
@cindex disk_path, _definition
@strong{disk_path}
is a path to an object in the local filesystem tree.
@*
@cindex iso_rr_path, _definition
@strong{iso_rr_path}
is the Rock Ridge address of a file object in the ISO image. 
If no Rock Ridge information shall be stored in an emerging ISO, then the
names will get mapped to ISO 9660 names of limited length and character set.
@cindex pathspec, _definition
@*
@sp 1
@c man .PP
A program argument is handled as a @strong{pathspec}, if it is not
recognized as original mkisofs option or additional @command{xorrisofs} option.
A pathspec depicts an input file object by a disk_path. 
If option -graft-points is not present, then the behavior depends on the
file type of disk_path. Directories get merged with the /-directory of the
ISO image. Files of other types get copied into the /-directory. 
@*
If -graft-points is present then each pathspec gets split at the first
occurrence of the =-character.
The part before the = is taken as @strong{target}, i.e. the iso_rr_path for
the file object in the ISO image. The part after the first = is taken
as @strong{source}, i.e. the disk_path of the input object.
@*
It is possible to make =-characters part of the iso_rr_path by preceding
them with a \-character. The same must be done for \-characters which
shall be part of the iso_rr_path.
@*
@sp 1
@c man .PP
If the source part of the pathspec leads to a directory, then all files
underneath this directory get inserted into the image, too.
It is possible to exclude particular files from being inserted
by help of option -m.
@*
In case that target already exists, the following rules apply:
Directories and other files may overwrite existing non-directories.
Directories get merged with existing directories.
Non-directories may not overwrite existing directories.
@c man .SS
@node Xorriso, Options, Insert, Top
@chapter Relation to program xorriso
@c man \fBRelation to program xorriso:\fR
@c man .br
@cindex xorriso, mkisofs emulation
@command{xorrisofs} is actually a command mode of program @strong{xorriso},
which gets entered either by xorriso command "-as mkisofs" or by
starting the program by one of the names "xorrisofs", "mkisofs",
"genisoimage", or "genisofs".
@*
This command mode can be left by argument "@minus{}@minus{}" which leads
to generic xorriso command mode. See @strong{man xorriso} for its description.
@*
@sp 1
@c man .PP
xorriso performs image reading and writing by help of libburn, which is
mainly intended for optical drives, but also operates on all POSIX
file types except directories.
@*
The program messages call any image file a "drive". File types which are not
supported for reading are reported as "blank". The reported free media
space may be quite fictional.
@*
Nevertheless @command{xorrisofs} does not operate directly on optical drives,
but rather forces libburn to regard them as general device files.
So for writing of sequential optical media (CD, DVD-R, DVD+R, BD-R)
one will have to use a burn program. E.g the cdrecord emulation of xorriso.
See EXAMPLES.
@c man .SS
@node Options, Examples, Xorriso, Top
@chapter Options
@cindex xorriso, options
@c man .br
@c man .SH OPTIONS
@c man .br
@menu
* Loading::             Image loading
* SetInsert::           Settings for file insertion
* SetProduct::          Settings for image production
* SetCompl::            Settings for standards compliance
* SetExtras::           Settings for standards extensions
* SetHide::             Settings for file hiding
* ImageId::             ISO image ID strings
* Bootable::            El Torito Bootable ISO images
* SystemArea::          System Area, MBR, GPT, APM, other boot blocks
* Charset::             Character sets
* Jigdo::               Jigdo Template Extraction
* Miscellaneous::       Miscellaneous options
@end menu
@c man .PP
@c man .TP
@c man .B Image loading:
@node Loading, SetInsert, Options, Options
@section Influencing the behavior of image loading
@c man .PP
The following options control loading of an existing ISO image for the purpose
of preparing a suitable add-on session.
If they are missing then a new image is composed from scratch.
@table @asis
@sp 1
@c man .TP
@item -M disk_path
@kindex -M   set path for loading existing ISO image
@cindex Session, select path, -M, -prev-session, -dev
Set the path from which to load the existing ISO image directory tree
on which to base the upcoming directory tree as add-on session.
The path must lead to a random-access readable file object.
On GNU/Linux: regular data files or block device files.
@*
A special kind of pseudo disk_path has the form "/dev/fd/"number.
It depicts the open file descriptor with the given number, regardless whether
the operating system supports this feature by file nodes in /dev/fd or not.
E.g. /dev/fd/3 is file descriptor 3 which was opened by the program that
later started xorriso.
@c man .TP
@item -prev-session disk_path
@kindex -prev-session   set path for loading existing ISO image
Alias of -M.
@c man .TP
@item -dev disk_path
@kindex -dev   set path for loading existing ISO image
Alias of -M.
@c man .TP
@item -C last_session_start,next_writeable_address
@kindex -C   set load address and write address offset
@cindex Session, set load and write address, -C, -cdrecord-params
Set the 2 KiB block address last_session_start from where to read the
ISO image out of the file given by option -M.
@*
Separated by a comma, set the next_writeable_address to which the
add-on session will finally be written. Decisive is actually the block
address which the intended readers will have to use as superblock address
on the intended medium.
@*
Both values can be inquired from optical media by help of burn programs
and cdrecord option -msinfo. xorriso itself can obtain it in its
cdrecord emulation.
@*
  values=$(xorriso -as cdrecord dev=/dev/... -msinfo)
@*
  echo $values
@*
@sp 1
Option -C may be used without option -M to create an ISO image from
scratch and prepare it for being finally written to a block address
other than 0. Parameter last_session_start must then be set to 0.
@c man .TP
@item -cdrecord-params last_session_start,next_writeable_address
@kindex -cdrecord-params   set load address and write address offset
Alias of -C.
@end table
@c man .TP
@c man .B Settings for file insertion:
@node SetInsert, SetProduct, Loading, Options
@section Settings for file insertion
@table @asis
@sp 1
@c man .TP
@item -path-list disk_path
@kindex -path-list   read pathspecs from disk file
@cindex pathspec, read list of, -path-list
Read pathspecs line-by-line from disk_file and insert the depicted file
objects into the ISO image. If disk_path is "-" then read the pathspecs
from standard input.
@c man .TP
@item @minus{}@minus{}quoted_path_list disk_path
@kindex @minus{}@minus{}quoted_path_list   read pathspecs from disk file
@cindex pathspec, read list of, @minus{}@minus{}quoted_path_list
Like option -path-list but reading quoted words rather than plain lines.
Whitespace outside of quotes will be discarded. On the other hand it is
possible to represent pathspecs which contain newline characters.
@*
The double quotation mark " and the single quotation mark ' can be used to
enclose whitespace and make it part of pathspecs. Each mark
type can enclose the marks of the other type. A trailing backslash \ outside
quotations or an open quotation cause the next input line to be appended.
@c man .TP
@item -f
@kindex -f   follow symbolic links on disk
@cindex Links, follow on disk, -f, -follow-links
@*
Resolve symbolic links on disk rather than storing them as symbolic
links in the ISO image.
@c man .TP
@item -follow-links
@kindex -follow-links   follow symbolic links on disk
Alias of -f.
@c man .TP
@item -graft-points
@kindex -graft-points   enable target=source pathspecs
@cindex pathspec, enable target=source, -graft-points
Enable interpretation of input file pathspecs as combination of iso_rr_path
and disk_path, separated by a =-character.
@c man .TP
@item -m disk_pattern
@kindex -m   exclude disk files from inserting
@cindex Disk files, exclude, -m, -exclude, -x, -old-exclude
Exclude files from being inserted into the image. Silently ignored are
those files of which the disk_path matches the given shell parser pattern.
If no /-character is part of the pattern, then it gets matched against
the leaf name of the disk file.
@*
It is possible to give more than one -m option.
@c man .TP
@item -exclude
@kindex -exclude   exclude disk files from inserting
Alias of -m.
@c man .TP
@item -x
@kindex -x   exclude disk files from inserting
@*
Alias of -m.
@c man .TP
@item -old-exclude
@kindex -old-exclude   exclude disk files from inserting
Alias of -m.
@c man .TP
@item -exclude-list disk_path
@kindex -exclude-list   exclude disk files from inserting
@cindex Disk files, exclude, -hide-list
Perform -m using each line out of file disk_path as argument disk_pattern.
@c man .TP
@item -z
@kindex -z   enable recognition of zisofs files
@cindex zisofs file, enable recognition, -z, -transparent-compression
@*
Enable recognition and proper processing of zisofs compressed files
as produced by program mkzftree. These files will get equipped with the
necessary meta data so that a Linux kernel will recognize them and
deliver their content in uncompressed form.
@c man .TP
@item -transparent-compression
@kindex -transparent-compression   enable recognition of zisofs files
Alias of -z.
@c man .TP
@item -root iso_rr_path
@kindex -root   redirect ISO root directory
@cindex ISO root directory, redirect, -root
Insert all files under the given iso_rr_path. If option -graft-points is given,
then iso_rr_path is prepended to each target part of a pathspec.
@*
The default for -root is "/".
@c man .TP
@item -old-root iso_rr_path
@kindex -old-root   enable incremental insertion
@cindex Incremental insertion, enable, -old-root
Enable incremental insertion of files into the loaded image.
The effective target and source addresses of given pathspecs get compared
whether the target already exists in the ISO image and is still identical
to the source on disk. Metadata in the ISO image will get adjusted, if they
differ from those on disk.
New files and files with changed content will get newly added.
Target files which do not exist in any of the according pathspec sources
will get removed from the ISO directory tree.
@*
If the effective setting of -root differs from the iso_rr_path given
with -old-root, then the files underneath the -old-root directory get cloned
underneath the -root directory. Cloning happens before file comparison.
@c man .TP
@item @minus{}@minus{}old-root-no-ino
@kindex @minus{}@minus{}old-root-no-ino   disable disk ino with -old-root
@cindex Incremental insertion, disable disk ino, @minus{}@minus{}old-root-no-ino
Disable recording and use of disk inode numbers.
If no disk inode numbers are recorded, then option -old-root will have
to read disk file content and compare it with the MD5 checksum that is
recorded in the ISO image.
@*
With recorded disk inode numbers and with credible ctime and mtime,
it is possible to detect potential changes in the content without actually
reading it.
A loophole remains if multiple different filesystems may get mounted
at the same directory, like it is habit with /mnt.
In this case one has to use option @minus{}@minus{}old-root-devno
or disable the inode number shortcut by @minus{}@minus{}old-root-no-ino.
@c man .TP
@item @minus{}@minus{}old-root-devno
@kindex @minus{}@minus{}old-root-devno   enable disk idevno with -old-root
@cindex Incremental insertion, enable disk devno, @minus{}@minus{}old-root-devno
Enable comparison of recorded device numbers together with recorded
inode numbers. This works only with good old stable device numbers which
get out of fashion, regrettably. If the hard disk has a different
device number after each reboot, then this comparison will see all
files as changed and thus prevent any incremental size saving.
@c man .TP
@item @minus{}@minus{}old-root-no-md5
@kindex @minus{}@minus{}old-root-no-md5   disable MD5 with -old-root
@cindex Incremental insertion, disable MD5, @minus{}@minus{}old-root-no-md5
Disable recording and use of MD5 checksums for data file content.
If neither checksums and nor disk inode numbers are recorded, then
option -old-root will have to read ISO image file content when comparing
it with disk file content.
@end table
@c man .TP
@c man .B Settings for image production:
@node SetProduct, SetCompl, SetInsert, Options
@section Settings for image production
@table @asis
@sp 1
@c man .TP
@item -o disk_path
@kindex -o   set output file address
@cindex Output file, set address, -o, -output
Set the output file address for the emerging ISO image.
If the address exists as regular file, it will be truncated to length 0
when image production begins. It may not already exist as directory.
If it does not exist yet then its parent directory must exist and
a regular file will get created.
@*
A special kind of pseudo disk_path has the form "/dev/fd/"number.
It depicts the open file descriptor with the given number, regardless whether
the operating system supports this feature by file nodes in /dev/fd or not.
E.g. /dev/fd/4 is file descriptor 4 which was opened by the program that
later started xorriso.
@*
Default is standard output (/dev/fd/1) which may also be set by disk_path "-".
@c man .TP
@item -output disk_path
@kindex -output   set output file address
Alias of -o.
@c man .TP
@item @minus{}@minus{}stdio_sync "on"|"off"|"end"|number
@kindex @minus{}@minus{}stdio_sync   control forced output to disk files
@cindex Forced output, control, @minus{}@minus{}stdio_sync
Set the number of bytes after which to force output to disk
in order to keep the memory from being clogged with lots of
pending data for slow devices. "on" is the same as "16m".
Forced output can be disabled by "off", or be delayed by "end" until all 
data are produced. If a number is chosen, then it must be at least 64k.
@*
The default with xorriso mkisofs emulation is @minus{}@minus{}stdio_sync "off".
@*
xorriso uses an inner fifo buffer with default size 4 MiB. So forcing
the operating system i/o cache to disk does not necessarily block the
simultaneous production of more image content.
@c man .TP
@item @minus{}@minus{}emul-toc
@kindex @minus{}@minus{}emul-toc   enable table-of-content emulation
@cindex Table-of-content, emulation, @minus{}@minus{}emul-toc
Write a second superblock with the first session into random-access
files. If further sessions get appended and the first superblock gets updated,
then the second superblock will not be overwritten. So it is still possible to
mount the first session and to find the start blocks of the further sessions.
@*
The price is 64 KiB extra space consumption. If -partition_offset is non-zero,
then it is 128 KiB plus twice the partition setup.
@c man .TP
@item @minus{}@minus{}no-emul-toc
@kindex @minus{}@minus{}no-emul-toc   no table-of-content emulation
@cindex Table-of-content, emulation off, @minus{}@minus{}no-emul-toc
Do not write a second superblock with the first session into random-access
files.
@*
This is the default.
@c man .TP
@item @minus{}@minus{}sort-weight weight_number iso_rr_path
@kindex @minus{}@minus{}sort-weight   set block address sorting weight
@cindex Block address, set sorting weight, @minus{}@minus{}sort-weight
Attribute a LBA weight number to regular files. If iso_rr_path leads
to a directory then all regular files underneath will get the weight_number.
@*
The weight_number may range from -2147483648 to 2147483647.
The higher it is, the lower will be the block address of the file data
in the emerging ISO image.
Currently the El Torito boot catalog has a hardcoded weight of 1 billion.
Normally it should occupy the block with the lowest possible address.
Data files get added or loaded with initial weight 0. Boot image files
have a default weight of 2.
@c man .TP
@item @minus{}@minus{}sort-weight-list disk_path
@kindex @minus{}@minus{}sort-weight-list   set block address sorting weight
@cindex Block address, set sorting weight, @minus{}@minus{}sort-weight-list
Read pairs of weight number and iso_rr_path from a file of the
local filesystem. Apply each pair like with @minus{}@minus{}sort-weight.
@*
Only the last @minus{}@minus{}sort-weight-list or
@minus{}@minus{}sort-weight-patterns of a xorrisofs run gets into effect. 
@*
The weight number is read from the start of the line.
The iso_rr_path part of an input line begins immediately after the first blank
or tab character of the line.
@*
Notes for the case that this feature is used within a sequence of generic
xorriso commands (not an issue with a pure mkisofs emulation run):
@*
The addressed files must already be in the ISO image model when you execute
@*
  -as mkisofs @minus{}@minus{}sort-weight-list disk_path @minus{}@minus{}
@*
Several such commands may be used to apply more than one weight file.
@*
Data files which are loaded by -indev or -dev get a weight between 1 and
2 exp 28 = 268,435,456, depending on their block address. This shall keep
them roughly in the same order if the write method of modifying is applied.
@c man .TP
@item @minus{}@minus{}sort-weight-patterns disk_path
@kindex @minus{}@minus{}sort-weight-patterns   set block address sorting weight
@cindex Block address, set sorting weight, @minus{}@minus{}sort-weight-patterns
Like @minus{}@minus{}sort-weight-list , but expanding the iso_rr_paths as
shell parser patterns and applying @minus{}@minus{}sort-weight to each
matching file.
@c man .TP
@item -uid number|name
@kindex -uid   ownership for all files
@cindex Ownership, for all files, -uid
Use the given number or locally existing user name as owner id of all files
and directories in the emerging filesystem.
Empty name or name "-" revoke this feature.
@c man .TP
@item -gid number|name
@kindex -gid   group assignment for all files
@cindex Group, for all files, -gid
Use the given number or locally existing group name as group id of all files
and directories in the emerging filesystem.
Empty name or name "-" revoke this feature.
@c man .TP
@item -dir-mode mode
@kindex -dir-mode   permissions for all directories
@cindex Permissions, for all directories, -dir-mode
Set the access permissions for all directories in the image to the given
mode which is either an octal number beginning with "0" or a comma separated
list of statements of the form [ugoa]*[+-=][rwxst]* . E.g. ug=rx,a-rwx
@c man .TP
@item -file-mode mode
@kindex -file-mode   permissions for all data files
@cindex Permissions, for all data files, -file-mode
Like -dir-mode but for all regular data files in the image.
@c man .TP
@item -pad
@kindex -pad   add 300 KiB of zeros to ISO tree
@cindex Padding, 300 KiB, -pad
@*
Add 300 KiB to the end of the produced ISO image. This circumvents possible
read errors from ISO images which have been written to CD media in TAO mode.
The additional bytes are claimed as part of the ISO image if not --emul-toc
is given.
@*
Option -pad is the default.
@c man .TP
@item -no-pad
@kindex -no-pad   do not add zeros to ISO tree
@cindex Padding, disable, -no-pad
Disable padding of 300 KiB to the end of the produced ISO image.
This is safe if the image is not meant to be written on CD or if it
gets written to CD as only track in write mode SAO.
@c man .TP
@item @minus{}@minus{}old-empty
@kindex @minus{}@minus{}old-empty   old block addresses for empty files
@cindex Padding, disable, @minus{}@minus{}old-empty
Use the old way of of giving block addresses in the range
of [0,31] to files with no own data content. The new way is to have
a dedicated block to which all such files will point.
@end table
@c man .TP
@c man .B Settings for standards compliance:
@node SetCompl, SetExtras, SetProduct, Options
@section Settings for standards compliance
@table @asis
@sp 1
@kindex -iso-level   define ISO 9660 limitations
@cindex ISO level, specify, -iso-level
@c man .TP
@item -iso-level number
@kindex -iso-level   define ISO 9660 limitations
@cindex ISO level, specify, -iso-level
Specify the ISO 9660 version which defines the limitations of file naming
and data file size. The naming restrictions do not apply to the
Rock Ridge names but only to the low-level ISO 9660 names.
There are three conformance levels:
@*
Level 1 allows ISO names of the form 8.3 and file size up to 4 GiB - 1.
@*
Level 2 allows ISO names with up to 32 characters
and file size up to 4 GiB - 1.
@*
Level 3  allows ISO names with up to 32 characters
and file size of up to 400 GiB - 200 KiB. (This size limitation is
set by the xorriso implementation and not by ISO 9660 which would
allow nearly 8 TiB.)
@*
Pseudo-level 4 enables production of an additional ISO 9660:1999
directory tree.
@c man .TP
@item -disallow_dir_id_ext
@kindex -disallow_dir_id_ext   enforce ISO level 1 directory names
@cindex ISO level 1, enforce directory names, -disallow_dir_id_ext
Do not follow a bad habit of mkisofs which allows dots in the ISO names
of directories. On the other hand, some bootable GNU/Linux images depend on
this bad habit.
@c man .TP
@item -U
@kindex -U   very relaxed filename rules
@cindex ISO file names, very relaxed rules, -U, -untranslated-filenames
@*
This option allows ISO file names without dot and up to 37 characters,
ISO file paths longer than 255 characters, and all ASCII characters in file
names. Further it omits the semicolon and the version numbers at the end
of ISO names.
@*
This all violates ISO 9660 specs.
@c man .TP
@item -untranslated-filenames
@kindex -untranslated-filenames   very relaxed filename rules
Alias of -U.
@c man .TP
@item -untranslated_name_len number
@kindex -untranslated_name_len   untranslated file names 
@cindex ISO file names, untranslated, -untranslated_name_len
Allow ISO file names up to the given number of characters
without any character conversion. The maximum number is 96.
If a file name has more characters, then image production will
fail deliberately.
@*
This violates ISO 9660 specs.
@c man .TP
@item -allow-lowercase
@kindex -allow-lowercase   lowercase in ISO file names
@cindex ISO file names, allow lowercase, -allow-lowercase
Allow lowercase character in ISO file names.
@*
This violates ISO 9660 specs.
@c man .TP
@item -relaxed-filenames
@kindex -relaxed-filenames   7-bit special characters in ISO file names
@cindex ISO file names, 7-bit special characters, -relaxed-filenames
Allow nearly all 7-bit characters in ISO file names.
Not allowed are 0x0 and '/'. If not option -allow-lowercase is given,
then lowercase letters get converted to uppercase.
@*
This violates ISO 9660 specs.
@c man .TP
@item -d
@kindex -d   omit trailing dot in ISO file names
@cindex ISO file names, omit trailing dot, -d, -omit-period
@*
Do not add trailing dot to ISO file names without dot.
@*
This violates ISO 9660 specs.
@c man .TP
@item -omit-period
@kindex -omit-period   omit trailing dot in ISO file names
Alias of -d.
@c man .TP
@item -l
@kindex -l   allow 31 characters in ISO file names
@cindex ISO file names, allow 31 characters, -l, -full-iso9660-filenames
@*
Allow up to 31 characters in ISO file names.
@c man .TP
@item -full-iso9660-filenames
@kindex -full-iso9660-filenames   allow 31 characters in ISO file names
Alias of -l.
@c man .TP
@item -max-iso9660-filenames
@kindex -max-iso9660-filenames   allow 37 characters in ISO file names
@cindex ISO file names, allow 37 characters, -max-iso9660-filenames
Allow up to 37 characters in ISO file names.
@*
This violates ISO 9660 specs.
@c man .TP
@item -N
@kindex -N   omit version number in ISO file names
@cindex ISO file names, omit version number, -N, -omit-version-number
@*
Omit the semicolon and the version numbers at the end of ISO names.
@*
This violates ISO 9660 specs.
@c man .TP
@item -omit-version-number
@kindex -omit-version-number   omit version number in ISO file names
Alias of -N.
@end table
@c man .TP
@c man .B Settings for standards extensions:
@node SetExtras, SetHide, SetCompl, Options
@section Settings for standards extensions
@table @asis
@sp 1
@c man .TP
@item -R
@kindex -R   Rock Ridge (is enabled by default)
@cindex Rock Ridge, (enabled by default), -R, -rock
@*
With mkisofs this option enables Rock Ridge extensions. @command{xorrisofs}
produces them by default. It is strongly discouraged to disable them
by option @minus{}@minus{}norock.
@c man .TP
@item -rock
@kindex -rock   Rock Ridge (is enabled by default)
@*
Alias of -R.
@c man .TP
@item -r
@kindex -r   Rock Ridge with altered owner and permission
@cindex Rock Ridge, altered owner and permission, -r, -rational-rock
@*
Enable Rock Ridge and set user and group id of all files in the ISO image to 0.
Grant r-permissions to all. Deny all w-permissions.
If any x-permission is set, grant x-permission to all.
Remove s-bit and t-bit.
@*
These attribute changes stay delayed until mkisofs emulation ends. Within the
same -as mkisofs emulation command they can be revoked by a subsequent
option @minus{}@minus{}norock. For compatibility reasons, option -R does not
revoke the changes ordered by -r.
@c man .TP
@item -rational-rock
@kindex -rational-rock   Rock Ridge with altered owner and permission
Alias of -r.
@c man .TP
@item @minus{}@minus{}norock
@kindex @minus{}@minus{}norock   disable Rock Ridge production
@cindex Rock Ridge, disable production, @minus{}@minus{}norock
@*
This option disables the production of Rock Ridge extensions for the
ISO 9660 file objects. The multi-session capabilities of @command{xorrisofs}
depend much on the naming fidelity of Rock Ridge. So it is strongly
discouraged to disable it by this option, except for the special use case
to revoke the effect of -r by:
 @minus{}@minus{}norock -R
@c man .TP
@item @minus{}@minus{}set_all_file_dates timestring
@kindex @minus{}@minus{}set_all_file_dates  set all file timestamps 
@cindex File timestamps, set all, @minus{}@minus{}set_all_file_dates
Set mtime, atime, and ctime of all files and directories to the given time.
@*
Valid timestring formats are: 'Nov 8 14:51:13 CET 2007', 110814512007.13,
2007110814511300. See also @minus{}@minus{}modification-date= and man xorriso,
Examples of input timestrings.
@*
If the timestring is "set_to_mtime", then the
atime and ctime of each file and directory get set to the value found in their
mtime.
@*
These actions stay delayed until actual ISO production begins.
Up to then they can be revoked by @minus{}@minus{}set_all_file_dates
with empty timestring or timestring "default".
@*
The timestamps of the El Torito boot catalog file get refreshed when the ISO
is produced. They can be influenced by @minus{}@minus{}modification-date=.
@c man .TP
@item -file_name_limit number
@kindex -file_name_limit   curbs length of file names
@cindex File names, curb length, -file_name_limit
Set the maximum permissible length for file names in the range of 64 to 255.
Path components which are longer than the given number will get truncated
and have their last 33 bytes overwritten by a colon ':' and the
hex representation of the MD5 of the first 4095 bytes of the whole
oversized name. Potential incomplete UTF-8 characters will get their
leading bytes replaced by '_'.
@*
Linux kernels up to at least 4.1 misrepresent names of length 254 and 255.
If you expect such names in or under disk_paths and plan to mount the ISO
by such Linux kernels, consider to set -file_name_limit 253.
@c man .TP
@item -D
@kindex -D   allow deep directory hierarchies
@cindex Deep directories, allow, -D, -disable-deep-relocation
The standard ECMA-119 demands that no path in the image shall have more
than 8 name components or 255 characters. Therefore it would be necessary
to move deeper directory trees to a higher directory. Rock Ridge offers an
opportunity to let these relocated directories appear at their original
deep position, but this feature might not be implemented properly by
operating systems which mount the image.
@*
Option -D disables this deep directory relocation, and thus violates
ISO 9660 specs.
@*
xorrisofs has -D set by default. If given explicitly then it overrides
the options -rr_reloc_dir and -hide-rr-moved.
@c man .TP
@item -disable-deep-relocation
@kindex -disable-deep-relocation   allow deep directory hierarchies
Alias of -D.
@c man .TP
@item -rr_reloc_dir name
@kindex -rr_reloc_dir   set deep directory relocation target
@cindex Deep directories, relocation target, -rr_reloc_dir
Enable the relocation of deep directories and thus avoid ECMA-119 file paths
of more than 8 name components or 255 characters. Directories which lead to
such file paths will get moved to a directory in the root directory of the
image. Its name gets set by this option.
It is permissible to use the root directory itself.
@*
The overall directory tree will appear originally deep when interpreted as
Rock Ridge tree. It will appear as re-arranged if only ECMA-119 information
is considered.
@*
If the given relocation target directory does not already exist when image
production begins, then it will get created and marked for Rock Ridge as
relocation artefact. At least on GNU/Linux it will not be displayed in
mounted Rock Ridge images.
@*
The name must not contain a '/' character after its first character and it
must not be longer than 255 bytes.
@*
This option has no effect if option -D is present.
@c man .TP
@item -hide-rr-moved
@kindex -hide-rr-moved   set deep directory relocation target
@cindex Deep directories, relocation target, -hide-rr-moved
Alias of -rr_reloc_dir "/.rr_moved"
@c man .TP
@item @minus{}@minus{}for_backup
@kindex @minus{}@minus{}for_backup   Enable backup fidelity
@cindex Backup, enable fidelity, @minus{}@minus{}for_backup
Enable all options which improve backup fidelity:
@*
@minus{}@minus{}acl, @minus{}@minus{}xattr-any, @minus{}@minus{}md5,
@minus{}@minus{}hardlinks. 
@*
If you later restore a backup with xattr from non-user namespaces, then make
sure that the target operating system and filesystem know what these attributes
mean. Possibly you will need administrator privileges to record or restore
such attributes. At recording time, xorriso will try to tolerate missing
privileges and just record what is readable.
@*
Option -xattr after option -for_backup excludes non-user attributes
from being recorded.
@c man .TP
@item @minus{}@minus{}acl
@kindex @minus{}@minus{}acl   Recording of ACLs
@cindex ACL, record and load, @minus{}@minus{}acl
@*
Enable recording and loading of ACLs from GNU/Linux or FreeBSD
(see man getfacl, man acl).  
They will not be in effect with mounted ISO images. But xorriso can
restore them on the same systems when extracting files from the ISO image.
@c man .TP
@item @minus{}@minus{}xattr
@kindex @minus{}@minus{}xattr   Recording of user xattr
@cindex xattr, record and load, @minus{}@minus{}xattr
@*
Enable recording and loading of GNU/Linux or FreeBSD extended attributes in
user namespace (see man getfattr and man attr,
man getextattr and man 9 extattr, respectively).
They will not be in effect with mounted ISO images. But xorriso can
restore them on the same systems when extracting files from the ISO image.
@c man .TP
@item @minus{}@minus{}xattr-any
@kindex @minus{}@minus{}xattr   Recording of any xattr
@cindex xattr, record and load, @minus{}@minus{}xattr-any
@*
Enable recording and loading of GNU/Linux or FreeBSD extended attributes in
all namespaces. This might need administrator privileges, even if the owner
of the disk file tries to read the attributes.
@c man .TP
@item @minus{}@minus{}md5
@kindex @minus{}@minus{}md5   Recording of MD5 checksums
@cindex MD5, record and load, @minus{}@minus{}md5
@*
Enable recording of MD5 checksums for the overall ISO image and for each
single data file in the image. xorriso can check the content of an ISO
image with these sums and raise alert on mismatch.
See man xorriso, options -check_media, check_md5_r.
xorriso can print recorded MD5 checksums. E.g. by:
@*
 -find / -exec get_md5
@c man .TP
@item @minus{}@minus{}hardlinks
@kindex @minus{}@minus{}hardlinks   Recording of hardlink relations
@cindex Links, record and load hard links, @minus{}@minus{}hardlinks
Enable loading and recording of hardlink relations.
Search for families of iso_rr files which stem from the same disk file,
have identical content filtering and have identical properties.
The members of each family get the same inode number in the ISO image.
@*
Whether these numbers are respected at mount time depends on the operating
system. xorriso can create hardlink families when extracting files from
the ISO image.
@c man .TP
@item @minus{}@minus{}scdbackup_tag disk_path record_name
@kindex @minus{}@minus{}scdbackup_tag   Recording of MD5 checksum
@cindex scdbackup, record checksum tag, @minus{}@minus{}scdbackup_tag
Append a scdbackup checksum record to the image. This works only if the
parameter next_writeable_address of option -C is 0 and --md5 is enabled.
If disk_path is not an empty string, then append a scdbackup checksum record
to the end of this file. record_name is a word that gets part of tag
and record.
@*
Program scdbackup_verify will recognize and verify tag and file record.
@*
An empty record_name disables this feature.
@c man .TP
@item -J
@kindex -J   enable production of Joliet directory tree
@cindex Joliet, enable, -J, -joliet
@*
Enable the production of an additional Joliet directory tree along
with the ISO 9660 Rock Ridge tree.
@c man .TP
@item -joliet
@kindex -joliet   enable production of Joliet directory tree
Alias of -J.
@c man .TP
@item -joliet-long
@kindex -joliet-long   allow longer Joliet names
@cindex Joliet, allows longer names, -joliet-long
Allow 103 characters in Joliet file names rather than 64 as is prescribed
by the specification. Allow Joliet paths longer than the prescribed limit of
240 characters.
@*
Oversized names get truncated. Without this option, oversized paths get
excluded from the Joliet tree.
@c man .TP
@item -joliet-utf16
@kindex -joliet-utf16   use UTF-16 with Joliet names
@cindex UTF-16, for Joliet paths, -joliet-utf16
Encode Joliet file names in UTF-16BE rather than UCS-2.
The difference is with characters which are not present
in UCS-2 and get encoded in UTF-16 by 2 words of 16 bit each.
Both words then stem from a reserved subset of UCS-2.
@c man .TP
@item -hfsplus
@kindex -hfsplus   enable production of HFS+ partition
@cindex HFS+, enables production
Enable the production of an additional HFS+ filesystem inside the ISO 9660
image and mark it by Apple Partition Map (APM) entries in the System Area,
the first 32 KiB of the image.
@*
This may collide with options like -G or -isohybrid-mbr which submit user data
for inclusion in the same address range.
The first 8 bytes of the System Area get overwritten by
@{ 0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff @}
which can be executed as x86 machine code without negative effects.
So if an MBR gets combined with this feature, then its first 8 bytes
should contain no essential commands.
@*
The next blocks of 2 KiB in the System Area will be occupied by APM entries.
The first one covers the part of the ISO image before the HFS+ filesystem
metadata. The second one marks the range from HFS+ metadata to the end
of file content data. If more ISO image data follow, then a third partition
entry gets produced. Other features of xorriso might cause the need for
more APM entries.
@*
Be aware that HFS+ is case-insensitive although it can record file names
with upper-case and lower-case letters. Therefore, file names from the iso_rr
name tree may collide in the HFS+ name tree. In this case they get changed
by adding underscore characters and counting numbers. In case of very long
names, it might be necessary to map them to "MANGLED_...".