libburnia/libisoburn
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Adjusted line lengths to less than 80 chars in source of xorriso manual

Browse Source
This commit is contained in:
Thomas Schmitt 2011-05-16 19:20:07 +00:00
parent 889b92d359
commit be0b15a8e7
3 changed files with 315 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
xorriso/xorriso.1
View File

@ -39,9 +39,11 @@ session\-wise manipulation of such filesystems. It can load the management
information of existing ISO images and it writes the session results to
optical media or to filesystem objects.
.br
Vice versa \fBxorriso\fR is able to copy file objects out of ISO 9660 filesystems.
Vice versa \fBxorriso\fR is able to copy file objects out of ISO 9660
filesystems.
.PP
A special property of \fBxorriso\fR is that it needs neither an external ISO 9660
A special property of \fBxorriso\fR is that it needs neither an external
ISO 9660
formatter program nor an external burn program for CD, DVD or BD but rather
incorporates the libraries of libburnia\-project.org .
.SS
@ -142,11 +144,12 @@ filesystems.
one and the modifications.
See paragraph Creating, Growing, Modifying, Blind Growing below.
.PP
\fBxorriso\fR adopts the concept of multi\-session by loading an eventual image
directory tree, allowing to manipulate it by several actions, and to write
the new image to the target media.
\fBxorriso\fR adopts the concept of multi\-session by loading an eventual
image directory tree, allowing to manipulate it by several actions, and to
write the new image to the target media.
.br
The first session of a \fBxorriso\fR run begins by the definition of the input
The first session of a \fBxorriso\fR run begins by the definition of
the input
drive with the eventual ISO image or by the definition of an output drive.
The session ends by command \-commit which triggers writing. A \-commit is
done automatically when the program ends regularly.
@ -264,8 +267,8 @@ to the given block address. This is the usage model of
mkisofs \-M $indev \-C $msc1,$msc2 \-o $outdev
.br
which gives much room for wrong parameter combinations and should thus only be
employed if a strict distinction between ISO formatter \fBxorriso\fR and the burn
program is desired. \-C $msc1,$msc2 is equivalent to:
employed if a strict distinction between ISO formatter \fBxorriso\fR
and the burn program is desired. \-C $msc1,$msc2 is equivalent to:
.br
\-load sbsector $msc1 \-grow_blindly $msc2
.SS
@ -279,7 +282,8 @@ Output drive, i.e. target for writing, can be any libburn drive.
Some drive types do not support the method of growing but only the methods
of modifying and blind growing. They all are suitable for newly created images.
.br
All drive file objects have to offer rw\-permission to the user of \fBxorriso\fR.
All drive file objects have to offer rw\-permission to the user of
\fBxorriso\fR.
Even those which will not be useable for reading an ISO image.
.PP
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by
@ -366,11 +370,12 @@ 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.
.br
This is what \fBxorriso\fR uses for a decent representation of the disk files
within the ISO image. Rock Ridge information is produced with any \fBxorriso\fR
image.
This is what \fBxorriso\fR uses for a decent representation of the disk
files within the ISO image. Rock Ridge information is produced with any
\fBxorriso\fR image.
.PP
\fBxorriso\fR is not named "porriso" because POSIX only guarantees 14 characters
\fBxorriso\fR is not named "porriso" because POSIX only guarantees
14 characters
of filename length. It is the X/Open System Interface standard XSI which
demands a file name length of up to 255 characters and paths of up to 1024
characters. Rock Ridge fulfills this demand.
@ -381,8 +386,8 @@ images, which are binary program files stored in the ISO image.
The content of the boot image files is not in the scope of El Torito.
.br
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images.
\fBxorriso\fR is able to create or maintain an El Torito object which makes such
an image bootable. For details see option \-boot_image.
\fBxorriso\fR is able to create or maintain an El Torito object which
makes such an image bootable. For details see option \-boot_image.
.br
It is possible to make ISO images bootable from USB stick or other
hard\-disk\-like media by \-boot_image argument system_area= . This installs
@ -409,27 +414,29 @@ It uses this extension if enabled by option
.br
AAIP enhanced images are supposed to be mountable normally, but one cannot
expect that the mounted filesystem will show and respect the eventual ACLs.
For now, only \fBxorriso\fR is able to retrieve those ACLs. It can bring them into
For now, only \fBxorriso\fR is able to retrieve those ACLs.
It can bring them into
effect when files get restored to an ACL enabled file system or it can
print them in a format suitable for tool setfacl.
.br
Files with ACL show as group permissions the setting of entry "mask::" if
that entry exists. Nevertheless the non\-listed group members get handled
according to entry "group::". \fBxorriso\fR brings "group::" into effect before
eventually removing the ACL from a file.
according to entry "group::". \fBxorriso\fR brings "group::" into effect
before eventually removing the ACL from a file.
.PP
\fBxattr\fR (aka EA)
are pairs of name and value which can be attached to file objects. AAIP is
able to represent them and \fBxorriso\fR allows to record and restore pairs which
able to represent them and \fBxorriso\fR allows to record and restore
pairs which
have names out of the user namespace. I.e. those which begin with "user.",
like "user.x" or "user.whatever". Name has to be a 0 terminated string.
Value may be any array of bytes which does not exceed the size of 4095 bytes.
xattr processing happens only if it is enabled by option
\fB\-xattr\fR.
.br
As with ACL, currently only \fBxorriso\fR is able to retrieve xattr from AAIP
enhanced images, to restore them to xattr capable file systems, or to print
them.
As with ACL, currently only \fBxorriso\fR is able to retrieve xattr
from AAIP enhanced images, to restore them to xattr capable file systems,
or to print them.
.SS
.B Command processing:
.br
@ -475,8 +482,8 @@ similar to the quotation rules of a shell parser.
.br
\fBxorriso\fR is not a shell, although it might appear so on first glimpse.
Be aware that the interaction of quotation marks and pattern symbols like "*"
differs from the usual shell parsers. In \fBxorriso\fR, a quotation mark does not
make a pattern symbol literal.
differs from the usual shell parsers. In \fBxorriso\fR, a quotation mark
does not make a pattern symbol literal.
.PP
\fBQuoted input\fR
converts whitespace separated text pieces into words.
@ -511,8 +518,10 @@ them as commands with their parameters. It provides assisting services
to make dialog more comfortable.
.PP
Readline is an enhancement for the input line. You may know it already from
the bash shell. Whether it is available in \fBxorriso\fR depends on the availability
of package readline\-dev at the time when \fBxorriso\fR was built from its sourcecode.
the bash shell. Whether it is available in \fBxorriso\fR depends on the
availability
of package readline\-dev at the time when \fBxorriso\fR was built from
its sourcecode.
.br
It allows to move the cursor over the text in the line by help of the
Leftward and the Rightward arrow key.
@ -670,8 +679,8 @@ accepted. If it is not a MMC device then the prefix "stdio:" will be prepended
automatically. This list is empty by default.
.br
Else if the path matches the "banned" list then the drive will not be
accepted by \fBxorriso\fR but rather lead to a FAILURE event. This list is empty by
default.
accepted by \fBxorriso\fR but rather lead to a FAILURE event.
This list is empty by default.
.br
Else if the path matches the "caution" list and if it is not a MMC device,
then its address must have the prefix "stdio:" or it will be rejected.
@ -719,7 +728,8 @@ an eventual recorded character set name gets used as input character set
when reading an image.
.br
Note that the default output charset is the local character set of the
terminal where \fBxorriso\fR runs. Before attributing this local character set
terminal where \fBxorriso\fR runs. Before attributing this local
character set
to the produced ISO image, check whether the terminal properly displays
all intended filenames, especially exotic national characters.
.TP
@ -746,7 +756,8 @@ e.g. if you need to apply filters to all updated files.
Mode "without_update" avoids hardlink processing during update commands.
Use this if your filesystem situation does not allow \-disk_dev_ino "on".
.br
\fBxorriso\fR commands which extract files from an ISO image try to hardlink files
\fBxorriso\fR commands which extract files from an ISO image try to
hardlink files
with identical inode number. The normal scope of this operation is from
image load to image load. One may give up the accumulated hard link addresses
by \-hardlinks "discard_extract".
@ -796,8 +807,8 @@ Mode "load_check_off" together with "on" or "all" will load recorded MD5 sums
but not test the recorded checksum tags of superblock and directory tree.
This is necessary if growisofs was used as burn program, because it does
not overwrite the superblock checksum tag of the first session.
Therefore load_check_off is in effect when \fBxorriso\fR \-as mkisofs option \-M
is performed.
Therefore load_check_off is in effect when \fBxorriso\fR \-as mkisofs
option \-M is performed.
.br
The test can be re\-enabled by mode "load_check_on".
.br
@ -1103,7 +1114,8 @@ arguments.
\fB\-file_size_limit\fR value [value [...]] --
Set the maximum permissible size for a single data file. The values get
summed up for the actual limit. If the only value is "off" then the file
size is not limited by \fBxorriso\fR. Default is a limit of 100 extents, 4g \-2k each:
size is not limited by \fBxorriso\fR.
Default is a limit of 100 extents, 4g \-2k each:
.br
\-file_size_limit 400g \-200k \-\-
.br
@ -1234,7 +1246,8 @@ The number given with "limit=" can curb this workload at the risk of truncating
an intentional sequence of link hops.
.TP
\fB\-pathspecs\fR "on"|"off"
Control parameter interpretation with \fBxorriso\fR actions \-add and \-path_list.
Control parameter interpretation with \fBxorriso\fR
actions \-add and \-path_list.
.br
"on" enables pathspecs of the form
\fBtarget=source\fR
@ -1636,7 +1649,8 @@ If \-else is missing and would be hit, then the result is a non\-match.
Default action is \fBecho\fR,
i.e. to print the address of the found file. Other actions are certain
\fBxorriso\fR commands which get performed on the found files. These commands
\fBxorriso\fR commands which get performed on the found files.
These commands
may have specific parameters. See also their particular descriptions.
.br
\fBchown\fR and \fBchown_r\fR
@ -1862,7 +1876,8 @@ is not applied to any file in the ISO image.
Irrevocably ban commands \-external_filter and \-unregister_filter,
but not \-set_filter. Use this to prevent external filtering in general or
when all intended filters are registered.
External filters may also be banned totally at compile time of \fBxorriso\fR.
External filters may also be banned totally at compile time of
\fBxorriso\fR.
By default they are banned if \fBxorriso\fR runs under setuid permission.
.TP
\fB\-set_filter\fR name iso_rr_path [***]
@ -2175,7 +2190,8 @@ identify the specification of how the data are recorded.
Permissible are up to 128 characters. This setting gets overridden by
image loading.
.br
The special text "@xorriso@" gets converted to the id string of \fBxorriso\fR
The special text "@xorriso@" gets converted to the id string of
\fBxorriso\fR
which is normally written as \-preparer_id. It is a wrong tradition to write
the program id as \-application_id.
.TP
@ -2237,12 +2253,12 @@ image loading.
\fB\-preparer_id\fR
Set the preparer id string to be written with the next \-commit. This may
identify the person or other entity which controls the preparation of the data
which shall be recorded. Normally this should be the id of \fBxorriso\fR and not
of the person or program which operates \fBxorriso\fR. Please avoid to change it.
Permissible are up to 128 characters.
which shall be recorded. Normally this should be the id of \fBxorriso\fR
and not of the person or program which operates \fBxorriso\fR.
Please avoid to change it. Permissible are up to 128 characters.
.br
The special text "@xorriso@" gets converted to the id string of \fBxorriso\fR
which is default at program startup.
The special text "@xorriso@" gets converted to the id string of
\fBxorriso\fR which is default at program startup.
.br
Unlike other id strings, this setting is not influenced by image loading.
.TP
@ -2344,7 +2360,8 @@ Append the given number of extra bytes to the image stream.
This is a traditional remedy for a traditional bug in block
device read drivers. Needed only for CD recordings in TAO mode.
Since one can hardly predict on what media an image might end up,
\fBxorriso\fR adds the traditional 300k of padding by default to all images.
\fBxorriso\fR adds the traditional 300k of padding by default to
all images.
.br
For images which will never get to a CD it is safe to use \-padding 0 .
.br
@ -2613,8 +2630,8 @@ Partitions may be appended with boot block type MBR and with SUN Disk Label.
With MBR:
.br
partition_number may be 1 to 4. Number 1 will put the whole ISO image into
the unclaimed space before partition 1. So together with most \fBxorriso\fR MBR
features, number 2 would be the most natural choice.
the unclaimed space before partition 1. So together with most \fBxorriso\fR
MBR features, number 2 would be the most natural choice.
.br
The type_code may be "FAT12", "FAT16", "Linux",
or a hexadecimal number between 0x00 and 0xff. Not all those numbers will
@ -2662,7 +2679,8 @@ After eventual To=From mapping, the file address gets written into the .jigdo
file. Jigdo restore tools will convert these addresses into really
reachable data source addresses from which they can read.
.br
If the list of jigdo parameters is not empty, then \fBxorriso\fR will refuse to
If the list of jigdo parameters is not empty, then \fBxorriso\fR will
refuse to
write to non\-blank targets, it will disable multi\-session emulation, and
eventual padding will be counted as part of the ISO image.
.br
@ -2743,8 +2761,8 @@ names. Shell command iconv \-l lists them.
Character sets should not matter as long as only english alphanumeric
characters are used for file names or as long as all writers and readers
of the media use the same character set.
Outside these constraints it may be necessary to let \fBxorriso\fR convert byte
codes.
Outside these constraints it may be necessary to let \fBxorriso\fR
convert byte codes.
.br
There is an input conversion from input character set to the local character
set which applies when an ISO image gets loaded. A conversion from local
@ -2753,13 +2771,15 @@ image tree gets written. The sets can be defined independently by options
\-in_charset and \-out_charset. Normally one will have both identical, if ever.
.br
If conversions are desired then \fBxorriso\fR needs to know the name of the
local character set. \fBxorriso\fR can inquire the same info as shell command
local character set. \fBxorriso\fR can inquire the same info as
shell command
"locale" with argument "charmap". This may be influenced by environment
variables LC_ALL, LC_CTYPE, or LANG and should match the expectations of
the terminal.
.br
The default output charset is the local character set of the terminal where
\fBxorriso\fR runs. So by default no conversion happens between local filesystem
\fBxorriso\fR runs. So by default no conversion happens between local
filesystem
names and emerging names in the image. The situation stays ambigous and the
reader has to riddle what character set was used.
.br
@ -2786,7 +2806,8 @@ If this appears necessary, one should consider to set \-backslash_codes to
.TP
.B Exception processing:
.PP
Since the tasks of \fBxorriso\fR are manifold and prone to external influence, there
Since the tasks of \fBxorriso\fR are manifold and prone to external
influence, there
may arise the need for \fBxorriso\fR to report and handle problem events.
.br
Those events get classified when they are detected by one of the software
@ -2829,18 +2850,18 @@ be ignorable.
.br
A special property of this option is that it works preemptive if given as
program start argument. I.e. the first \-abort_on setting among the
start arguments is in effect already when the first operations of \fBxorriso\fR
begin. Only "\-abort_on" with dash "\-" is recognized that way.
start arguments is in effect already when the first operations of
\fBxorriso\fR begin. Only "\-abort_on" with dash "\-" is recognized that way.
.TP
\fB\-return_with\fR severity exit_value
Set the threshold and exit_value to be returned at program end if no abort
has happened. This is to allow \fBxorriso\fR to go on after problems but to get
a failure indicating exit value from the program, nevertheless.
has happened. This is to allow \fBxorriso\fR to go on after problems
but to get a failure indicating exit value from the program, nevertheless.
Useful is a value lower than the \-abort_on threshold, down to "WARNING".
.br
exit_value may be either 0 (indicating success to the starter of the program)
or a number between 32 and 63. Some other exit_values are used by \fBxorriso\fR if
it decides to abort the program run:
or a number between 32 and 63. Some other exit_values are used by
\fBxorriso\fR if it decides to abort the program run:
.br
1=abort due to external signal
.br
@ -2868,7 +2889,8 @@ Info messages which belong to no event get attributed severity "NOTE".
.br
A special property of this option is that the first \-report_about setting
among the start arguments is in effect already when the first operations
of \fBxorriso\fR begin. Only "\-report_about" with dash "\-" is recognized that way.
of \fBxorriso\fR begin. Only "\-report_about" with dash "\-" is
recognized that way.
.TP
\fB\-signal_handling\fR mode
Control the installation of a signal handler which shall react on external
@ -2880,8 +2902,8 @@ ugly messages but puts much effort in releasing eventually used optical drives
before \fBxorriso\fR ends.
.br
Mode "off" as first \-signal_handling among the start arguments prevents all
own signal precautions of \fBxorriso\fR. Eventually inherited signal handler settings
stay as they are.
own signal precautions of \fBxorriso\fR. Eventually inherited signal
handler settings stay as they are.
.br
It works like "sig_dfl" if given after other signal handling was already
established at program start.
@ -2891,14 +2913,16 @@ normally a sudden abort of the program. To prevent stuck drives, the
libburn handler is used during burning, blanking, and formatting on MMC drives.
.br
Mode "sig_ign" tries to ignore as many signal types as possible. This imposes
the risk that \fBxorriso\fR refuses to end until externally kill \-9 if performed.
the risk that \fBxorriso\fR refuses to end until externally kill \-9
if performed.
kill \-9 then imposes the risk that the drive is left in unusable state and
needs poweroff to be reset. So during burning, blanking, and formatting
wait for at least their normal run time before killing externally.
.br
A special property of this option is that the first \-signal_handling setting
among the start arguments is in effect already when the first operations
of \fBxorriso\fR begin. Only "\-signal_handling" with dash "\-" is recognized that way.
of \fBxorriso\fR begin. Only "\-signal_handling" with dash "\-" is
recognized that way.
.TP
\fB\-error_behavior\fR occasion behavior
Control the program behavior at problem event occasions.
@ -3289,7 +3313,8 @@ and based on extra data on the media. If a drive returns data then one can
quite trust that they are valid. But at some degree of read problems the
correction will fail and the drive is supposed to indicate error.
.br
\fBxorriso\fR can scan the media for readable data blocks, classify them according
\fBxorriso\fR can scan the media for readable data blocks, classify them
according
to their read speed, save them to a file, and keep track of successfuly saved
blocks for further tries on the same media.
.br
@ -3500,8 +3525,8 @@ handled like any other ISO image directory.
.br
Option "auto_chmod_off" is default. If "auto_chmod_on" is set then access
restrictions for disk directories get circumvented if those directories
are owned by the effective user who runs \fBxorriso\fR. This happens by temporarily
granting rwx permission to the owner.
are owned by the effective user who runs \fBxorriso\fR. This happens
by temporarily granting rwx permission to the owner.
.br
Option "sort_lba_on" may improve read performance with optical drives. It
allows to restore large numbers of hard links without exhausting
@ -3626,11 +3651,13 @@ of mkisofs emulation in the context of a \fBxorriso\fR run.
Other than with the "cdrecord" personality there is no automatic \-commit at
the end of a "mkisofs" option list. Verbosity settings \-v (= "UPDATE") and
\-quiet (= "SORRY") persist. The output file, eventually chosen with \-o,
persists until things happen like \-commit, \-rollback, \-dev, or end of \fBxorriso\fR.
persists until things happen like \-commit, \-rollback, \-dev, or end of
\fBxorriso\fR.
\-pacifier gets set to "mkisofs" if files are added to the image.
.br
\-graft\-points is equivalent to \-pathspecs on. Note that pathspecs without "="
are interpreted differently than with \fBxorriso\fR option \-add. Directories get
are interpreted differently than with \fBxorriso\fR option \-add.
Directories get
merged with the root directory of the ISO image, other filetypes get mapped
into that root directory.
.br
@ -3638,8 +3665,8 @@ If pathspecs are given and if no output file was chosen before or during the
"mkisofs" option list, then standard output (\-outdev "\-") will get into effect.
If \-o points to a regular file, then it will be truncated to 0 bytes
when finally writing begins. This truncation does not happen if the drive
is chosen by \fBxorriso\fR options before \-as mkisofs or after its list delimiter.
Directories and symbolic links are no valid \-o targets.
is chosen by \fBxorriso\fR options before \-as mkisofs or after its
list delimiter. Directories and symbolic links are no valid \-o targets.
.br
Writing to stdout is possible only if \-as "mkisofs" was among the start
arguments or if other start arguments pointed the output drive to
@ -3712,14 +3739,15 @@ Option \-append_partition is supported.
\-\-old\-empty is \-compliance old_empty.
.br
The options of genisoimage Jigdo Template Extraction are recognized and
performed via \fBxorriso\fR option \-jigdo. See the "Alias:" names there for the
meaning of the genisoimage options.
performed via \fBxorriso\fR option \-jigdo. See the "Alias:" names there
for the meaning of the genisoimage options.
.br
Personalities "\fBxorrisofs\fR", "\fBgenisoimage\fR",
and "\fBgenisofs\fR" are aliases for "mkisofs".
.br
If \fBxorriso\fR is started with one of the leafnames "xorrisofs", "genisofs",
If \fBxorriso\fR is started with one of the leafnames "xorrisofs",
"genisofs",
"mkisofs", or "genisoimage", then it performs \-read_mkisofsrc and prepends
\-as "genisofs" to the command line arguments.
I.e. all arguments will be interpreted mkisofs style until "\-\-"
@ -3749,8 +3777,8 @@ closing is applicable and not option \-multi is present.
An eventually acquired input drive is given up.
This is only allowed if no image changes are pending.
.br
dev= must be given as \fBxorriso\fR device address. Addresses like 0,0,0 or ATA:1,1,0
are not supported.
dev= must be given as \fBxorriso\fR device address. Addresses like 0,0,0
or ATA:1,1,0 are not supported.
.br
If a track source is given, then an automatic \-commit happens at the end of
the "cdrecord" option list.
@ -3766,14 +3794,15 @@ A much more elaborate libburn based cdrecord emulator is the program cdrskin.
Personalites "\fBxorrecord\fR", "\fBwodim\fR", and "\fBcdrskin\fR"
are aliases for "cdrecord".
.br
If \fBxorriso\fR is started with one of the leafnames "xorrecord", "cdrskin",
"cdrecord", or "wodim", then it automatically prepends \-as "cdrskin"
If \fBxorriso\fR is started with one of the leafnames "xorrecord",
"cdrskin", "cdrecord", or "wodim", then it automatically prepends \-as "cdrskin"
to the command line arguments. I.e. all arguments will be interpreted cdrecord
style until "\-\-" is encountered and an eventual commit happens.
From then on, options are interpreted as \fBxorriso\fR options.
.br
\-\-no_rc as first argument of such a program start
prevents interpretation of \fBxorriso\fR startup files. See section FILES below.
prevents interpretation of \fBxorriso\fR startup files.
See section FILES below.
.TP
\fB\-read_mkisofsrc\fR
Try one by one to open for reading:
@ -3828,8 +3857,8 @@ files. See section FILES below.
\fB\-options_from_file\fR fileaddress
Read quoted input from fileaddress and execute it like dialog lines.
Empty lines and lines which begin by # are ignored. Normally one line
should hold one \fBxorriso\fR command and all its arguments. Nevertheless lines
may be concatenated by a trailing backslash.
should hold one \fBxorriso\fR command and all its arguments.
Nevertheless lines may be concatenated by a trailing backslash.
.br
See also section "Command processing", paragraph "Quoted input".
.TP
@ -3960,12 +3989,13 @@ The first three items are single words, the rest of the line is the volume id.
.TP
\fB\-scsi_log\fR "on"|"off"
Mode "on" enables very verbous logging of SCSI commands and drive replies.
Logging messages get printed to stderr, not to any of the \fBxorriso\fR output
channels.
Logging messages get printed to stderr, not to any of the \fBxorriso\fR
output channels.
.br
A special property of this option is that the first \-scsi_log setting
among the start arguments is in effect already when the first operations
of \fBxorriso\fR begin. Only "\-scsi_log" with dash "\-" is recognized that way.
of \fBxorriso\fR begin.
Only "\-scsi_log" with dash "\-" is recognized that way.
.TP
\fB\-end\fR
.br
@ -4005,9 +4035,9 @@ Copy output of a channel to the given file. Channel may be one of: "." for all
channels, "I" for info messages, "R" for result lines, "M" for \-mark texts.
.TP
\fB\-mark\fR text
If text is not empty it will get put out on "M" channel each time \fBxorriso\fR
is ready for the next dialog line or before \fBxorriso\fR performs a command that
was entered to the pager prompt.
If text is not empty it will get put out on "M" channel each time
\fBxorriso\fR is ready for the next dialog line or before
\fBxorriso\fR performs a command that was entered to the pager prompt.
.TP
\fB\-prog\fR text
Use text as name of this program in subsequent messages
@ -4310,7 +4340,8 @@ in order to enable multi\-session emulation on overwriteable media.
.SS
.B Let xorriso work underneath growisofs
growisofs expects an ISO formatter program which understands options \-C and
\-M. If \fBxorriso\fR gets started by name "xorrisofs" then it is suitable for that.
\-M. If \fBxorriso\fR gets started by name "xorrisofs" then it is suitable
for that.
.br
$ export MKISOFS="xorrisofs"
.br
@ -4319,7 +4350,8 @@ $ growisofs \-Z /dev/dvd /some/files
$ growisofs \-M /dev/dvd /more/files
.br
If no "xorrisofs" is available on your system, then you will have to create
a link pointing to the \fBxorriso\fR binary and tell growisofs to use it. E.g. by:
a link pointing to the \fBxorriso\fR binary and tell growisofs to use it.
E.g. by:
.br
$ ln \-s $(which xorriso) "$HOME/xorrisofs"
.br
@ -4439,8 +4471,8 @@ it is possible to access the session trees which represent the older backup
versions. With CD media, GNU/Linux mount accepts session numbers directly by
its option "session=".
.br
Multi\-session media and most overwriteable media written by \fBxorriso\fR can tell
the sbsectors of their sessions by \fBxorriso\fR option \-toc.
Multi\-session media and most overwriteable media written by \fBxorriso\fR
can tell the sbsectors of their sessions by \fBxorriso\fR option \-toc.
Used after \-commit the following option prints the matching mount command for
the newly written session (here for mount point /mnt):
.br
@ -4601,12 +4633,13 @@ for libburnia\-project.org
Copyright (c) 2007 \- 2011 Thomas Schmitt
.br
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of \fBxorriso\fR. If you make use
of the license to derive modified versions of \fBxorriso\fR then you are entitled
to modify this text under that same license.
modified in sync with the technical properties of \fBxorriso\fR.
If you make use of the license to derive modified versions of
\fBxorriso\fR then you are entitled to modify this text under that
same license.
.SH CREDITS
\fBxorriso\fR is in part based on work by Vreixo Formoso who provides libisofs
together with Mario Danic who also leads the libburnia team.
\fBxorriso\fR is in part based on work by Vreixo Formoso who provides
libisofs together with Mario Danic who also leads the libburnia team.
Thanks to Andy Polyakov who invented emulated growing,
to Derek Foreman and Ben Jansens who once founded libburn.
.br

122
xorriso/xorriso.info
View File

@ -240,9 +240,8 @@ growing* is performed. It produces an add-on session which is ready for
being written to the given block address. This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
which gives much room for wrong parameter combinations and should thus
only be employed if a strict distinction between ISO formatter
`xorriso' and the burn program is desired. -C $msc1,$msc2 is equivalent
to:
only be employed if a strict distinction between ISO formatter `xorriso'
and the burn program is desired. -C $msc1,$msc2 is equivalent to:
-load sbsector $msc1 -grow_blindly $msc2

@ -638,7 +637,7 @@ activate them only after image loading.
"stdio:" will be prepended automatically. This list is empty by
default.
Else if the path matches the "banned" list then the drive will not
be accepted by `xorriso' but rather lead to a FAILURE event. This
be accepted by `xorriso' but rather lead to a FAILURE event. This
list is empty by default.
Else if the path matches the "caution" list and if it is not a MMC
device, then its address must have the prefix "stdio:" or it will
@ -1040,8 +1039,8 @@ File: xorriso.info, Node: SetInsert, Next: Manip, Prev: Insert, Up: Options
-file_size_limit value [value [...]] --
Set the maximum permissible size for a single data file. The
values get summed up for the actual limit. If the only value is
"off" then the file size is not limited by `xorriso'. Default is a
limit of 100 extents, 4g -2k each:
"off" then the file size is not limited by `xorriso'. Default is
a limit of 100 extents, 4g -2k each:
-file_size_limit 400g -200k --
When mounting ISO 9660 filesystems, old operating systems can
handle only files up to 2g -1 --. Newer ones are good up to 4g -1
@ -1494,7 +1493,7 @@ File: xorriso.info, Node: CmdFind, Next: Filter, Prev: Manip, Up: Options
Default action is *echo*, i.e. to print the address of the found
file. Other actions are certain `xorriso' commands which get
performed on the found files. These commands may have specific
performed on the found files. These commands may have specific
parameters. See also their particular descriptions.
chown and chown_r
@ -2008,7 +2007,7 @@ will be written according to the setting of option -acl.
This may identify the person or other entity which controls the
preparation of the data which shall be recorded. Normally this
should be the id of `xorriso' and not of the person or program
which operates `xorriso'. Please avoid to change it. Permissible
which operates `xorriso'. Please avoid to change it. Permissible
are up to 128 characters.
The special text "@xorriso@" gets converted to the id string of
`xorriso' which is default at program startup.
@ -3241,7 +3240,7 @@ said programs trigger comparable actions.
to "mkisofs" if files are added to the image.
-graft-points is equivalent to -pathspecs on. Note that pathspecs
without "=" are interpreted differently than with `xorriso' option
-add. Directories get merged with the root directory of the ISO
-add. Directories get merged with the root directory of the ISO
image, other filetypes get mapped into that root directory.
If pathspecs are given and if no output file was chosen before or
during the "mkisofs" option list, then standard output (-outdev
@ -3347,7 +3346,8 @@ said programs trigger comparable actions.
an eventual commit happens. From then on, options are interpreted
as `xorriso' options.
--no_rc as first argument of such a program start prevents
interpretation of `xorriso' startup files. See section FILES below.
interpretation of `xorriso' startup files. See section FILES
below.
-read_mkisofsrc
Try one by one to open for reading: ./.mkisofsrc , $MKISOFSRC ,
@ -3397,7 +3397,7 @@ File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Op
Read quoted input from fileaddress and execute it like dialog
lines. Empty lines and lines which begin by # are ignored.
Normally one line should hold one `xorriso' command and all its
arguments. Nevertheless lines may be concatenated by a trailing
arguments. Nevertheless lines may be concatenated by a trailing
backslash.
See also section "Command processing", paragraph "Quoted input".
@ -3512,7 +3512,7 @@ File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Op
the `xorriso' output channels.
A special property of this option is that the first -scsi_log
setting among the start arguments is in effect already when the
first operations of `xorriso' begin. Only "-scsi_log" with dash
first operations of `xorriso' begin. Only "-scsi_log" with dash
"-" is recognized that way.
-end
@ -3844,7 +3844,7 @@ $ growisofs -M /dev/dvd /more/files
If no "xorrisofs" is available on your system, then you will have to
create a link pointing to the `xorriso' binary and tell growisofs to
use it. E.g. by:
use it. E.g. by:
$ ln -s $(which xorriso) "$HOME/xorrisofs"
$ export MKISOFS="$HOME/xorrisofs"
@ -4115,7 +4115,7 @@ for libburnia-project.org
Copyright (c) 2007 - 2011 Thomas Schmitt
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of `xorriso'. If you
modified in sync with the technical properties of `xorriso'. If you
make use of the license to derive modified versions of `xorriso' then
you are entitled to modify this text under that same license.
@ -4268,7 +4268,7 @@ File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top
* -out_charset sets output character set: SetWrite. (line 185)
* -outdev aquires a drive for output: AqDrive. (line 29)
* -overwrite enables overwriting in ISO: SetInsert. (line 127)
* -pacifier controls pacifier text form: Emulation. (line 158)
* -pacifier controls pacifier text form: Emulation. (line 159)
* -padding sets amount or mode of image padding: SetWrite. (line 268)
* -page set terminal geometry: DialogCtl. (line 19)
* -paste_in copies file into disk file: Restore. (line 117)
@ -4290,7 +4290,7 @@ File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top
* -quoted_not_list sets exclusions: SetInsert. (line 72)
* -quoted_path_list inserts paths from disk file: Insert. (line 80)
* -read_mkisofsrc searches and reads .mkisofsrc file: Emulation.
(line 146)
(line 147)
* -reassure enables confirmation question: DialogCtl. (line 32)
* -report_about controls verbosity: Exception. (line 55)
* -return_with controls exit value: Exception. (line 39)
@ -4300,7 +4300,7 @@ File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top
* -rollback discards pending changes: Writing. (line 9)
* -rollback_end ends program without writing: Scripting. (line 137)
* -rom_toc_scan searches for sessions: Loading. (line 210)
* -scdbackup_tag enables scdbackup checksum tag: Emulation. (line 168)
* -scdbackup_tag enables scdbackup checksum tag: Emulation. (line 169)
* -scsi_log reports SCSI commands: Scripting. (line 125)
* -session_log logs written sessions: Scripting. (line 116)
* -session_string composes session info line: Inquiry. (line 56)
@ -4359,7 +4359,7 @@ File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top
* Backslash Interpretation, _definition: Processing. (line 49)
* Backup, enable fast incremental, -disk_dev_ino: Loading. (line 189)
* Backup, enable features, -for_backup: Loading. (line 184)
* Backup, scdbackup checksum tag, -scdbackup: Emulation. (line 168)
* Backup, scdbackup checksum tag, -scdbackup: Emulation. (line 169)
* Blank media, _definition: Media. (line 29)
* Blind growing, _definition: Methods. (line 40)
* Bootability, control, -boot_image: Bootable. (line 26)
@ -4404,10 +4404,10 @@ File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top
* Drive, write and eject, -commit_eject: Writing. (line 40)
* El Torito, _definiton: Extras. (line 19)
* Emulation, -as: Emulation. (line 13)
* Emulation, .mkisofsrc, -read_mkisofsrc: Emulation. (line 146)
* Emulation, .mkisofsrc, -read_mkisofsrc: Emulation. (line 147)
* Emulation, cdrecord, -as: Emulation. (line 111)
* Emulation, mkisofs, -as: Emulation. (line 16)
* Emulation, pacifier form, -pacifier: Emulation. (line 158)
* Emulation, pacifier form, -pacifier: Emulation. (line 159)
* Examples: Examples. (line 6)
* Filter, _definition: Filter. (line 6)
* Filter, apply to file tree, -set_filter_r: Filter. (line 85)
@ -4607,46 +4607,46 @@ Node: Dialog21628
Node: Options23291
Node: AqDrive24899
Node: Loading27807
Node: Insert42142
Node: SetInsert51761
Node: Manip60334
Node: CmdFind69019
Node: Filter80321
Node: Writing84678
Node: SetWrite90976
Node: Bootable105021
Node: Jigdo118341
Node: Charset122605
Node: Exception125364
Node: DialogCtl131504
Node: Inquiry134091
Node: Navigate138474
Node: Verify146414
Node: Restore155009
Node: Emulation161669
Node: Scripting171535
Node: Frontend177683
Node: Examples178982
Node: ExDevices180153
Node: ExCreate180791
Node: ExDialog182065
Node: ExGrowing183327
Node: ExModifying184129
Node: ExBootable184630
Node: ExCharset185179
Node: ExPseudo186007
Node: ExCdrecord186905
Node: ExMkisofs187220
Node: ExGrowisofs188558
Node: ExException189692
Node: ExTime190146
Node: ExIncBackup190605
Node: ExRestore194529
Node: ExRecovery195498
Node: Files196064
Node: Seealso197362
Node: Legal197946
Node: CommandIdx198873
Node: ConceptIdx213541
Node: Insert42143
Node: SetInsert51762
Node: Manip60336
Node: CmdFind69021
Node: Filter80324
Node: Writing84681
Node: SetWrite90979
Node: Bootable105025
Node: Jigdo118345
Node: Charset122609
Node: Exception125368
Node: DialogCtl131508
Node: Inquiry134095
Node: Navigate138478
Node: Verify146418
Node: Restore155013
Node: Emulation161673
Node: Scripting171546
Node: Frontend177696
Node: Examples178995
Node: ExDevices180166
Node: ExCreate180804
Node: ExDialog182078
Node: ExGrowing183340
Node: ExModifying184142
Node: ExBootable184643
Node: ExCharset185192
Node: ExPseudo186020
Node: ExCdrecord186918
Node: ExMkisofs187233
Node: ExGrowisofs188571
Node: ExException189706
Node: ExTime190160
Node: ExIncBackup190619
Node: ExRestore194543
Node: ExRecovery195512
Node: Files196078
Node: Seealso197376
Node: Legal197960
Node: CommandIdx198888
Node: ConceptIdx213556

End Tag Table

221
xorriso/xorriso.texi
View File

@ -122,10 +122,12 @@ session-wise manipulation of such filesystems. It can load the management
information of existing ISO images and it writes the session results to
optical media or to filesystem objects.
@*
Vice versa @command{xorriso} is able to copy file objects out of ISO 9660 filesystems.
Vice versa @command{xorriso} is able to copy file objects out of ISO 9660
filesystems.
@c man .PP
@sp 1
A special property of @command{xorriso} is that it needs neither an external ISO 9660
A special property of @command{xorriso} is that it needs neither an external
ISO 9660
formatter program nor an external burn program for CD, DVD or BD but rather
incorporates the libraries of libburnia-project.org .
@c man .SS
@ -236,11 +238,12 @@ one and the modifications.
See paragraph Creating, Growing, Modifying, Blind Growing below.
@c man .PP
@sp 1
@command{xorriso} adopts the concept of multi-session by loading an eventual image
directory tree, allowing to manipulate it by several actions, and to write
the new image to the target media.
@command{xorriso} adopts the concept of multi-session by loading an eventual
image directory tree, allowing to manipulate it by several actions, and to
write the new image to the target media.
@c man .br
The first session of a @command{xorriso} run begins by the definition of the input
The first session of a @command{xorriso} run begins by the definition of
the input
drive with the eventual ISO image or by the definition of an output drive.
The session ends by command -commit which triggers writing. A -commit is
done automatically when the program ends regularly.
@ -381,8 +384,8 @@ to the given block address. This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
@*
which gives much room for wrong parameter combinations and should thus only be
employed if a strict distinction between ISO formatter @command{xorriso} and the burn
program is desired. -C $msc1,$msc2 is equivalent to:
employed if a strict distinction between ISO formatter @command{xorriso}
and the burn program is desired. -C $msc1,$msc2 is equivalent to:
@*
-load sbsector $msc1 -grow_blindly $msc2
@c man .SS
@ -400,7 +403,8 @@ Output drive, i.e. target for writing, can be any libburn drive.
Some drive types do not support the method of growing but only the methods
of modifying and blind growing. They all are suitable for newly created images.
@*
All drive file objects have to offer rw-permission to the user of @command{xorriso}.
All drive file objects have to offer rw-permission to the user of
@command{xorriso}.
Even those which will not be useable for reading an ISO image.
@c man .PP
@sp 1
@ -494,12 +498,13 @@ is the name of a set of additional information which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
@*
This is what @command{xorriso} uses for a decent representation of the disk files
within the ISO image. Rock Ridge information is produced with any @command{xorriso}
image.
This is what @command{xorriso} uses for a decent representation of the disk
files within the ISO image. Rock Ridge information is produced with any
@command{xorriso} image.
@c man .PP
@sp 1
@command{xorriso} is not named "porriso" because POSIX only guarantees 14 characters
@command{xorriso} is not named "porriso" because POSIX only guarantees
14 characters
of filename length. It is the X/Open System Interface standard XSI which
demands a file name length of up to 255 characters and paths of up to 1024
characters. Rock Ridge fulfills this demand.
@ -512,8 +517,8 @@ images, which are binary program files stored in the ISO image.
The content of the boot image files is not in the scope of El Torito.
@*
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images.
@command{xorriso} is able to create or maintain an El Torito object which makes such
an image bootable. For details see option -boot_image.
@command{xorriso} is able to create or maintain an El Torito object which
makes such an image bootable. For details see option -boot_image.
@*
@cindex MBR, _definiton
It is possible to make ISO images bootable from USB stick or other
@ -543,29 +548,31 @@ It uses this extension if enabled by option
@*
AAIP enhanced images are supposed to be mountable normally, but one cannot
expect that the mounted filesystem will show and respect the eventual ACLs.
For now, only @command{xorriso} is able to retrieve those ACLs. It can bring them into
For now, only @command{xorriso} is able to retrieve those ACLs.
It can bring them into
effect when files get restored to an ACL enabled file system or it can
print them in a format suitable for tool setfacl.
@*
Files with ACL show as group permissions the setting of entry "mask::" if
that entry exists. Nevertheless the non-listed group members get handled
according to entry "group::". @command{xorriso} brings "group::" into effect before
eventually removing the ACL from a file.
according to entry "group::". @command{xorriso} brings "group::" into effect
before eventually removing the ACL from a file.
@c man .PP
@sp 1
@cindex xattr, _definiton
@strong{xattr} (aka EA)
are pairs of name and value which can be attached to file objects. AAIP is
able to represent them and @command{xorriso} allows to record and restore pairs which
able to represent them and @command{xorriso} allows to record and restore
pairs which
have names out of the user namespace. I.e. those which begin with "user.",
like "user.x" or "user.whatever". Name has to be a 0 terminated string.
Value may be any array of bytes which does not exceed the size of 4095 bytes.
xattr processing happens only if it is enabled by option
@strong{-xattr}.
@*
As with ACL, currently only @command{xorriso} is able to retrieve xattr from AAIP
enhanced images, to restore them to xattr capable file systems, or to print
them.
As with ACL, currently only @command{xorriso} is able to retrieve xattr
from AAIP enhanced images, to restore them to xattr capable file systems,
or to print them.
@c man .SS
@node Processing, Dialog, Extras, top
@chapter Command processing
@ -618,8 +625,8 @@ similar to the quotation rules of a shell parser.
@*
@command{xorriso} is not a shell, although it might appear so on first glimpse.
Be aware that the interaction of quotation marks and pattern symbols like "*"
differs from the usual shell parsers. In @command{xorriso}, a quotation mark does not
make a pattern symbol literal.
differs from the usual shell parsers. In @command{xorriso}, a quotation mark
does not make a pattern symbol literal.
@c man .PP
@sp 1
@cindex Quoted input, _definiton
@ -662,8 +669,10 @@ to make dialog more comfortable.
@c man .PP
@sp 1
Readline is an enhancement for the input line. You may know it already from
the bash shell. Whether it is available in @command{xorriso} depends on the availability
of package readline-dev at the time when @command{xorriso} was built from its sourcecode.
the bash shell. Whether it is available in @command{xorriso} depends on the
availability
of package readline-dev at the time when @command{xorriso} was built from
its sourcecode.
@*
It allows to move the cursor over the text in the line by help of the
Leftward and the Rightward arrow key.
@ -873,8 +882,8 @@ accepted. If it is not a MMC device then the prefix "stdio:" will be prepended
automatically. This list is empty by default.
@*
Else if the path matches the "banned" list then the drive will not be
accepted by @command{xorriso} but rather lead to a FAILURE event. This list is empty by
default.
accepted by @command{xorriso} but rather lead to a FAILURE event.
This list is empty by default.
@*
Else if the path matches the "caution" list and if it is not a MMC device,
then its address must have the prefix "stdio:" or it will be rejected.
@ -928,7 +937,8 @@ an eventual recorded character set name gets used as input character set
when reading an image.
@*
Note that the default output charset is the local character set of the
terminal where @command{xorriso} runs. Before attributing this local character set
terminal where @command{xorriso} runs. Before attributing this local
character set
to the produced ISO image, check whether the terminal properly displays
all intended filenames, especially exotic national characters.
@c man .TP
@ -957,7 +967,8 @@ e.g. if you need to apply filters to all updated files.
Mode "without_update" avoids hardlink processing during update commands.
Use this if your filesystem situation does not allow -disk_dev_ino "on".
@*
@command{xorriso} commands which extract files from an ISO image try to hardlink files
@command{xorriso} commands which extract files from an ISO image try to
hardlink files
with identical inode number. The normal scope of this operation is from
image load to image load. One may give up the accumulated hard link addresses
by -hardlinks "discard_extract".
@ -1013,8 +1024,8 @@ Mode "load_check_off" together with "on" or "all" will load recorded MD5 sums
but not test the recorded checksum tags of superblock and directory tree.
This is necessary if growisofs was used as burn program, because it does
not overwrite the superblock checksum tag of the first session.
Therefore load_check_off is in effect when @command{xorriso} -as mkisofs option -M
is performed.
Therefore load_check_off is in effect when @command{xorriso} -as mkisofs
option -M is performed.
@*
The test can be re-enabled by mode "load_check_on".
@*
@ -1380,7 +1391,8 @@ arguments.
@cindex Insert, limit data file size, -file_size_limit
Set the maximum permissible size for a single data file. The values get
summed up for the actual limit. If the only value is "off" then the file
size is not limited by @command{xorriso}. Default is a limit of 100 extents, 4g -2k each:
size is not limited by @command{xorriso}.
Default is a limit of 100 extents, 4g -2k each:
@*
-file_size_limit 400g -200k @minus{}@minus{}
@*
@ -1526,7 +1538,8 @@ an intentional sequence of link hops.
@item -pathspecs "on"|"off"
@kindex -pathspecs sets meaning of = with -add
@cindex Insert, meaning of = with -add, -pathspecs
Control parameter interpretation with @command{xorriso} actions -add and -path_list.
Control parameter interpretation with @command{xorriso}
actions -add and -path_list.
@*
@cindex Pathspec, _definition
"on" enables pathspecs of the form
@ -1995,7 +2008,8 @@ If -else is missing and would be hit, then the result is a non-match.
Default action is @strong{echo},
i.e. to print the address of the found file. Other actions are certain
@command{xorriso} commands which get performed on the found files. These commands
@command{xorriso} commands which get performed on the found files.
These commands
may have specific parameters. See also their particular descriptions.
@c man .br
@table @asis
@ -2245,7 +2259,8 @@ is not applied to any file in the ISO image.
Irrevocably ban commands -external_filter and -unregister_filter,
but not -set_filter. Use this to prevent external filtering in general or
when all intended filters are registered.
External filters may also be banned totally at compile time of @command{xorriso}.
External filters may also be banned totally at compile time of
@command{xorriso}.
By default they are banned if @command{xorriso} runs under setuid permission.
@c man .TP
@item -set_filter name iso_rr_path [***]
@ -2600,7 +2615,8 @@ identify the specification of how the data are recorded.
Permissible are up to 128 characters. This setting gets overridden by
image loading.
@*
The special text "@@xorriso@@" gets converted to the id string of @command{xorriso}
The special text "@@xorriso@@" gets converted to the id string of
@command{xorriso}
which is normally written as -preparer_id. It is a wrong tradition to write
the program id as -application_id.
@c man .TP
@ -2674,12 +2690,12 @@ image loading.
@cindex Image, set preparer id, -preparer_id
Set the preparer id string to be written with the next -commit. This may
identify the person or other entity which controls the preparation of the data
which shall be recorded. Normally this should be the id of @command{xorriso} and not
of the person or program which operates @command{xorriso}. Please avoid to change it.
Permissible are up to 128 characters.
which shall be recorded. Normally this should be the id of @command{xorriso}
and not of the person or program which operates @command{xorriso}.
Please avoid to change it. Permissible are up to 128 characters.
@*
The special text "@@xorriso@@" gets converted to the id string of @command{xorriso}
which is default at program startup.
The special text "@@xorriso@@" gets converted to the id string of
@command{xorriso} which is default at program startup.
@*
Unlike other id strings, this setting is not influenced by image loading.
@c man .TP
@ -2805,7 +2821,8 @@ Append the given number of extra bytes to the image stream.
This is a traditional remedy for a traditional bug in block
device read drivers. Needed only for CD recordings in TAO mode.
Since one can hardly predict on what media an image might end up,
@command{xorriso} adds the traditional 300k of padding by default to all images.
@command{xorriso} adds the traditional 300k of padding by default to
all images.
@*
For images which will never get to a CD it is safe to use -padding 0 .
@*
@ -3098,8 +3115,8 @@ Partitions may be appended with boot block type MBR and with SUN Disk Label.
With MBR:
@*
partition_number may be 1 to 4. Number 1 will put the whole ISO image into
the unclaimed space before partition 1. So together with most @command{xorriso} MBR
features, number 2 would be the most natural choice.
the unclaimed space before partition 1. So together with most @command{xorriso}
MBR features, number 2 would be the most natural choice.
@*
The type_code may be "FAT12", "FAT16", "Linux",
or a hexadecimal number between 0x00 and 0xff. Not all those numbers will
@ -3152,7 +3169,8 @@ After eventual To=From mapping, the file address gets written into the .jigdo
file. Jigdo restore tools will convert these addresses into really
reachable data source addresses from which they can read.
@*
If the list of jigdo parameters is not empty, then @command{xorriso} will refuse to
If the list of jigdo parameters is not empty, then @command{xorriso} will
refuse to
write to non-blank targets, it will disable multi-session emulation, and
eventual padding will be counted as part of the ISO image.
@*
@ -3241,8 +3259,8 @@ names. Shell command iconv -l lists them.
Character sets should not matter as long as only english alphanumeric
characters are used for file names or as long as all writers and readers
of the media use the same character set.
Outside these constraints it may be necessary to let @command{xorriso} convert byte
codes.
Outside these constraints it may be necessary to let @command{xorriso}
convert byte codes.
@*
There is an input conversion from input character set to the local character
set which applies when an ISO image gets loaded. A conversion from local
@ -3251,13 +3269,15 @@ image tree gets written. The sets can be defined independently by options
-in_charset and -out_charset. Normally one will have both identical, if ever.
@*
If conversions are desired then @command{xorriso} needs to know the name of the
local character set. @command{xorriso} can inquire the same info as shell command
local character set. @command{xorriso} can inquire the same info as
shell command
"locale" with argument "charmap". This may be influenced by environment
variables LC_ALL, LC_CTYPE, or LANG and should match the expectations of
the terminal.
@*
The default output charset is the local character set of the terminal where
@command{xorriso} runs. So by default no conversion happens between local filesystem
@command{xorriso} runs. So by default no conversion happens between local
filesystem
names and emerging names in the image. The situation stays ambigous and the
reader has to riddle what character set was used.
@*
@ -3293,7 +3313,8 @@ If this appears necessary, one should consider to set -backslash_codes to
@node Exception, DialogCtl, Charset, Options
@section Exception processing
@c man .PP
Since the tasks of @command{xorriso} are manifold and prone to external influence, there
Since the tasks of @command{xorriso} are manifold and prone to external
influence, there
may arise the need for @command{xorriso} to report and handle problem events.
@*
Those events get classified when they are detected by one of the software
@ -3340,20 +3361,20 @@ be ignorable.
@*
A special property of this option is that it works preemptive if given as
program start argument. I.e. the first -abort_on setting among the
start arguments is in effect already when the first operations of @command{xorriso}
begin. Only "-abort_on" with dash "-" is recognized that way.
start arguments is in effect already when the first operations of
@command{xorriso} begin. Only "-abort_on" with dash "-" is recognized that way.
@c man .TP
@item -return_with severity exit_value
@kindex -return_with controls exit value
@cindex Process, control exit value, -return_with
Set the threshold and exit_value to be returned at program end if no abort
has happened. This is to allow @command{xorriso} to go on after problems but to get
a failure indicating exit value from the program, nevertheless.
has happened. This is to allow @command{xorriso} to go on after problems
but to get a failure indicating exit value from the program, nevertheless.
Useful is a value lower than the -abort_on threshold, down to "WARNING".
@*
exit_value may be either 0 (indicating success to the starter of the program)
or a number between 32 and 63. Some other exit_values are used by @command{xorriso} if
it decides to abort the program run:
or a number between 32 and 63. Some other exit_values are used by
@command{xorriso} if it decides to abort the program run:
@*
1=abort due to external signal
@*
@ -3383,7 +3404,8 @@ Info messages which belong to no event get attributed severity "NOTE".
@*
A special property of this option is that the first -report_about setting
among the start arguments is in effect already when the first operations
of @command{xorriso} begin. Only "-report_about" with dash "-" is recognized that way.
of @command{xorriso} begin. Only "-report_about" with dash "-" is
recognized that way.
@c man .TP
@item -signal_handling mode
@kindex -signal_handling controls handling of system signals
@ -3397,8 +3419,8 @@ ugly messages but puts much effort in releasing eventually used optical drives
before @command{xorriso} ends.
@*
Mode "off" as first -signal_handling among the start arguments prevents all
own signal precautions of @command{xorriso}. Eventually inherited signal handler settings
stay as they are.
own signal precautions of @command{xorriso}. Eventually inherited signal
handler settings stay as they are.
@*
It works like "sig_dfl" if given after other signal handling was already
established at program start.
@ -3408,14 +3430,16 @@ normally a sudden abort of the program. To prevent stuck drives, the
libburn handler is used during burning, blanking, and formatting on MMC drives.
@*
Mode "sig_ign" tries to ignore as many signal types as possible. This imposes
the risk that @command{xorriso} refuses to end until externally kill -9 if performed.
the risk that @command{xorriso} refuses to end until externally kill -9
if performed.
kill -9 then imposes the risk that the drive is left in unusable state and
needs poweroff to be reset. So during burning, blanking, and formatting
wait for at least their normal run time before killing externally.
@*
A special property of this option is that the first -signal_handling setting
among the start arguments is in effect already when the first operations
of @command{xorriso} begin. Only "-signal_handling" with dash "-" is recognized that way.
of @command{xorriso} begin. Only "-signal_handling" with dash "-" is
recognized that way.
@c man .TP
@item -error_behavior occasion behavior
@kindex -error_behavior controls error workarounds
@ -3902,7 +3926,8 @@ and based on extra data on the media. If a drive returns data then one can
quite trust that they are valid. But at some degree of read problems the
correction will fail and the drive is supposed to indicate error.
@*
@command{xorriso} can scan the media for readable data blocks, classify them according
@command{xorriso} can scan the media for readable data blocks, classify them
according
to their read speed, save them to a file, and keep track of successfuly saved
blocks for further tries on the same media.
@*
@ -4134,8 +4159,8 @@ handled like any other ISO image directory.
@*
Option "auto_chmod_off" is default. If "auto_chmod_on" is set then access
restrictions for disk directories get circumvented if those directories
are owned by the effective user who runs @command{xorriso}. This happens by temporarily
granting rwx permission to the owner.
are owned by the effective user who runs @command{xorriso}. This happens
by temporarily granting rwx permission to the owner.
@*
Option "sort_lba_on" may improve read performance with optical drives. It
allows to restore large numbers of hard links without exhausting
@ -4290,11 +4315,13 @@ of mkisofs emulation in the context of a @command{xorriso} run.
Other than with the "cdrecord" personality there is no automatic -commit at
the end of a "mkisofs" option list. Verbosity settings -v (= "UPDATE") and
-quiet (= "SORRY") persist. The output file, eventually chosen with -o,
persists until things happen like -commit, -rollback, -dev, or end of @command{xorriso}.
persists until things happen like -commit, -rollback, -dev, or end of
@command{xorriso}.
-pacifier gets set to "mkisofs" if files are added to the image.
@*
-graft-points is equivalent to -pathspecs on. Note that pathspecs without "="
are interpreted differently than with @command{xorriso} option -add. Directories get
are interpreted differently than with @command{xorriso} option -add.
Directories get
merged with the root directory of the ISO image, other filetypes get mapped
into that root directory.
@*
@ -4302,8 +4329,8 @@ If pathspecs are given and if no output file was chosen before or during the
"mkisofs" option list, then standard output (-outdev "-") will get into effect.
If -o points to a regular file, then it will be truncated to 0 bytes
when finally writing begins. This truncation does not happen if the drive
is chosen by @command{xorriso} options before -as mkisofs or after its list delimiter.
Directories and symbolic links are no valid -o targets.
is chosen by @command{xorriso} options before -as mkisofs or after its
list delimiter. Directories and symbolic links are no valid -o targets.
@*
Writing to stdout is possible only if -as "mkisofs" was among the start
arguments or if other start arguments pointed the output drive to
@ -4376,15 +4403,16 @@ Option @minus{}append_partition is supported.
@minus{}@minus{}old-empty is -compliance old_empty.
@*
The options of genisoimage Jigdo Template Extraction are recognized and
performed via @command{xorriso} option -jigdo. See the "Alias:" names there for the
meaning of the genisoimage options.
performed via @command{xorriso} option -jigdo. See the "Alias:" names there
for the meaning of the genisoimage options.
@*
@sp 1
Personalities "@strong{xorrisofs}", "@strong{genisoimage}",
and "@strong{genisofs}" are aliases for "mkisofs".
@*
If @command{xorriso} is started with one of the leafnames "xorrisofs", "genisofs",
If @command{xorriso} is started with one of the leafnames "xorrisofs",
"genisofs",
"mkisofs", or "genisoimage", then it performs -read_mkisofsrc and prepends
-as "genisofs" to the command line arguments.
I.e. all arguments will be interpreted mkisofs style until "@minus{}@minus{}"
@ -4417,8 +4445,8 @@ closing is applicable and not option -multi is present.
An eventually acquired input drive is given up.
This is only allowed if no image changes are pending.
@*
dev= must be given as @command{xorriso} device address. Addresses like 0,0,0 or ATA:1,1,0
are not supported.
dev= must be given as @command{xorriso} device address. Addresses like 0,0,0
or ATA:1,1,0 are not supported.
@*
If a track source is given, then an automatic -commit happens at the end of
the "cdrecord" option list.
@ -4434,14 +4462,15 @@ A much more elaborate libburn based cdrecord emulator is the program cdrskin.
Personalites "@strong{xorrecord}", "@strong{wodim}", and "@strong{cdrskin}"
are aliases for "cdrecord".
@*
If @command{xorriso} is started with one of the leafnames "xorrecord", "cdrskin",
"cdrecord", or "wodim", then it automatically prepends -as "cdrskin"
If @command{xorriso} is started with one of the leafnames "xorrecord",
"cdrskin", "cdrecord", or "wodim", then it automatically prepends -as "cdrskin"
to the command line arguments. I.e. all arguments will be interpreted cdrecord
style until "@minus{}@minus{}" is encountered and an eventual commit happens.
From then on, options are interpreted as @command{xorriso} options.
@*
@minus{}@minus{}no_rc as first argument of such a program start
prevents interpretation of @command{xorriso} startup files. See section FILES below.
prevents interpretation of @command{xorriso} startup files.
See section FILES below.
@c man .TP
@item -read_mkisofsrc
@kindex -read_mkisofsrc searches and reads .mkisofsrc file
@ -4510,8 +4539,8 @@ files. See section FILES below.
@cindex Process, read command file, -options_from_file
Read quoted input from fileaddress and execute it like dialog lines.
Empty lines and lines which begin by # are ignored. Normally one line
should hold one @command{xorriso} command and all its arguments. Nevertheless lines
may be concatenated by a trailing backslash.
should hold one @command{xorriso} command and all its arguments.
Nevertheless lines may be concatenated by a trailing backslash.
@*
See also section "Command processing", paragraph "Quoted input".
@c man .TP
@ -4673,12 +4702,13 @@ The first three items are single words, the rest of the line is the volume id.
@kindex -scsi_log reports SCSI commands
@cindex Drive, report SCSI commands, -scsi_log
Mode "on" enables very verbous logging of SCSI commands and drive replies.
Logging messages get printed to stderr, not to any of the @command{xorriso} output
channels.
Logging messages get printed to stderr, not to any of the @command{xorriso}
output channels.
@*
A special property of this option is that the first -scsi_log setting
among the start arguments is in effect already when the first operations
of @command{xorriso} begin. Only "-scsi_log" with dash "-" is recognized that way.
of @command{xorriso} begin.
Only "-scsi_log" with dash "-" is recognized that way.
@c man .TP
@item -end
@kindex -end writes pending session and ends program
@ -4736,9 +4766,9 @@ channels, "I" for info messages, "R" for result lines, "M" for -mark texts.
@item -mark text
@kindex -mark sets synchronizing message
@cindex Process, set synchronizing message, -mark
If text is not empty it will get put out on "M" channel each time @command{xorriso}
is ready for the next dialog line or before @command{xorriso} performs a command that
was entered to the pager prompt.
If text is not empty it will get put out on "M" channel each time
@command{xorriso} is ready for the next dialog line or before
@command{xorriso} performs a command that was entered to the pager prompt.
@c man .TP
@item -prog text
@kindex -prog sets program name
@ -5141,7 +5171,8 @@ in order to enable multi-session emulation on overwriteable media.
@node ExGrowisofs, ExException, ExMkisofs, Examples
@section Let @command{xorriso} work underneath growisofs
growisofs expects an ISO formatter program which understands options -C and
-M. If @command{xorriso} gets started by name "xorrisofs" then it is suitable for that.
-M. If @command{xorriso} gets started by name "xorrisofs" then it is suitable
for that.
@*
@sp 1
$ export MKISOFS="xorrisofs"
@ -5152,7 +5183,8 @@ $ growisofs -M /dev/dvd /more/files
@*
@sp 1
If no "xorrisofs" is available on your system, then you will have to create
a link pointing to the @command{xorriso} binary and tell growisofs to use it. E.g. by:
a link pointing to the @command{xorriso} binary and tell growisofs to use it.
E.g. by:
@*
@sp 1
$ ln -s $(which xorriso) "$HOME/xorrisofs"
@ -5309,8 +5341,8 @@ it is possible to access the session trees which represent the older backup
versions. With CD media, GNU/Linux mount accepts session numbers directly by
its option "session=".
@*
Multi-session media and most overwriteable media written by @command{xorriso} can tell
the sbsectors of their sessions by @command{xorriso} option -toc.
Multi-session media and most overwriteable media written by @command{xorriso}
can tell the sbsectors of their sessions by @command{xorriso} option -toc.
Used after -commit the following option prints the matching mount command for
the newly written session (here for mount point /mnt):
@*
@ -5527,13 +5559,14 @@ for libburnia-project.org
Copyright (c) 2007 - 2011 Thomas Schmitt
@*
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of @command{xorriso}. If you make use
of the license to derive modified versions of @command{xorriso} then you are entitled
to modify this text under that same license.
modified in sync with the technical properties of @command{xorriso}.
If you make use of the license to derive modified versions of
@command{xorriso} then you are entitled to modify this text under that
same license.
@c man .SH CREDITS
@section Credits
@command{xorriso} is in part based on work by Vreixo Formoso who provides libisofs
together with Mario Danic who also leads the libburnia team.
@command{xorriso} is in part based on work by Vreixo Formoso who provides
libisofs together with Mario Danic who also leads the libburnia team.
Thanks to Andy Polyakov who invented emulated growing,
to Derek Foreman and Ben Jansens who once founded libburn.
@*