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

Adjustments of xorriso man page

Browse Source
This commit is contained in:
Thomas Schmitt 2009-10-27 14:21:54 +00:00
parent 071a7c8279
commit 73e740f822
1 changed files with 79 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
xorriso/xorriso.1
View File

@ -2,7 +2,7 @@
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH XORRISO 1 "Oct 10, 2009"
.TH XORRISO 1 "Oct 27, 2009"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
@ -26,13 +26,13 @@ with Rock Ridge extensions.
.SH DESCRIPTION
.PP
.B xorriso
is a program which maps file objects from POSIX compliant
is a program which copies file objects from POSIX compliant
filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows
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 xorriso is able to restore file objects from ISO 9660 filesystems.
Vice versa xorriso is able to copy file objects out of ISO 9660 filesystems.
.PP
A special property of xorriso is that it needs neither an external ISO 9660
formatter program nor an external burn program for CD, DVD or BD but rather
@ -168,8 +168,8 @@ session history. If they contain one or more ISO 9660 sessions and if the
first session was written by xorriso, then a table of content can
be emulated. Else only a single overall session will be visible.
.br
DVD-RW media can be formatted by -format full.
They can be made unformatted by -blank deformat.
DVD-RW media can be formatted by -format "full".
They can be made unformatted by -blank "deformat".
.br
Regular files and block devices are handled as overwriteable media.
Pipes and other writeable file types are handled as blank multi-session media.
@ -331,7 +331,7 @@ among the start arguments. Do not try to fool this ban via backdoor addresses
to stdout.
.br
If stdout is used as drive, then -use_readline is permanently disabled.
Use of backdoors will cause severe memory and/or tty corruption.
Use of backdoors can cause severe memory and/or tty corruption.
.PP
Be aware that especially the superuser can write into any accessible file or
device by using its path with the "stdio:" prefix. By default any address
@ -353,7 +353,7 @@ prefix "stdio:" to other paths.
is the name of a set of additional informations which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
.PP
.br
This is what xorriso uses for a decent representation of the disk files
within the ISO image. Rock Ridge information is produced with any xorriso
image.
@ -520,8 +520,8 @@ try to abort as soon as possible.
.SH OPTIONS
.br
All command words are shown with a leading dash although this dash is not
mandatory for the option to be recognized. Note that with emulation modes the
dashes of the emulated options are mandatory.
mandatory for the option to be recognized. Nevertheless within option -as
the dashes of the emulated options are mandatory.
.br
Normally any number of leading dashes is ignored with command words and
inner dashes are interpreted as underscores.
@ -652,7 +652,8 @@ have to deny its rw-permissions in the filesystem.
\fB\-assert_volid\fR pattern severity
Refuse to load ISO images with volume ids which do not match the given
search pattern. When refusing an image, give up the input drive and issue
an event of the given severity. An empty search pattern accepts any image.
an event of the given severity (like FAILURE, see -abort_on). An empty search
pattern accepts any image.
.br
This option does not hamper the creation of an empty image from blank
input media and does not discard an already loaded image.
@ -945,10 +946,10 @@ composed from disk_path by replacing disk_prefix by iso_rr_prefix.
\fB\-update\fR disk_path iso_rr_path
Compare file object disk_path with file object iso_rr_path. If they do not
match, then perform the necessary image manipulations to make iso_rr_path
a matching copy of disk_path. This comparison will imply lengthy content
reading before a decision is made. On the other hand it strives for the
smallest possible amount of add-on data which is needed to achieve the
matching copy.
a matching copy of disk_path. By default this comparison will imply lengthy
content reading before a decision is made. Options -disk_dev_ino or -md5 may
accelerate comparison if they were already in effect when the loaded session
was recorded.
.br
If disk_path is a directory and iso_rr_path does not exist yet, then the
whole subtree will be inserted. Else only directory attributes will be
@ -1303,7 +1304,7 @@ Matches if pattern matches the file path as it would be printed by action
"echo". Character '/' is not special but can be matched by wildcards.
.br
\fB\-type\fR type_letter :
Matches files files of the given type:
Matches files of the given type:
"block", "char", "dir", "pipe", "file", "link", "socket", "eltorito",
"Xotic" which eventually matches what is not matched by the other types.
.br
@ -1363,7 +1364,7 @@ Matches if the next test or sub expression does not match.
Several tests do this specifically:
.br
-undamaged, -lba_range with negative start_lba, -has_no_acl, -has_no_xattr,
-has_no_aaip, -has_no_filter
-has_no_aaip, -has_no_filter .
.br
\fB\-and\fR :
Matches if both neighboring tests or expressions match.
@ -1397,7 +1398,7 @@ may have specific parameters. See also their particular descriptions.
as parameter. E.g.: -exec chown thomas --
.br
\fBchgrp\fR and \fBchgrp_r\fR change the group attribute and get the group id
as paramieter. E.g.: -exec chgrp_r staff --
as parameter. E.g.: -exec chgrp_r staff --
.br
\fBchmod\fR and \fBchmod_r\fR change access permissions and get a mode string
as parameter. E.g.: -exec chmod a-w,a+r --
@ -1504,10 +1505,13 @@ Switch to growing mode.
(A subsequent -outdev will activate modification mode or blind growing.)
-commit is performed automatically at end of program if there
are uncommitted manipulations pending.
.br
So, to perform a final write operation with no new -dev
and no new loading of image, rather execute option -end.
If you want to go on without image loading, execute -commit_eject "none".
To eject after write without image loading, use -commit_eject "all".
.br
To suppress a final write, execute -rollback_end.
To eject outdev after write without new loading of image, use -commit_eject.
.br
Writing can last quite a while. It is not unnormal with several
@ -1518,8 +1522,7 @@ xorriso and the drives are in a client-server relationship.
The drives have much freedom about what to do with the media.
Some combinations of drives and media simply do not work,
despite the promises by their vendors.
If writing fails - or even the drive gets stuck and you need
to reboot - then try other media or another drive. The reason
If writing fails then try other media or another drive. The reason
for such failure is hardly ever in the code of the various
burn programs but you may well try some of those listed below
under SEE ALSO.
@ -1548,8 +1551,8 @@ DVD-RAM and BD-RE. Other media in blank state are gracefully ignored.
Media which cannot be made ready for writing from scratch cause a FAILURE
event.
.br
"fast" and "all" make CD-RW and unformatted DVD-RW re-usable,
or invalidate overwriteable ISO images.
"fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates
overwriteable ISO images. "all" might work more thoroughly and need more time.
.br
"deformat" converts overwriteable DVD-RW into unformatted ones.
.br
@ -1775,7 +1778,7 @@ and eventually enables -disk_pattern expansion.
.TP
\fB\-overwrite\fR "on"|"nondir"|"off"
Allow or disallow to overwrite existing files in the
ISO image by files with the same user defined name.
ISO image by files with the same name.
.br
With setting "off", name collisions cause FAILURE events.
With setting "nondir", only directories are protected by such events, other
@ -1823,7 +1826,7 @@ their numbers have to be plausible. E.g. byte_count must be valid as -cut_out
argument and their contents may not overlap.
.TP
.B Settings for result writing:
.TP
.PP
Rock Ridge info will be generated by the program unconditionally.
ACLs will be written according to the setting of option -acl.
.TP
@ -2037,7 +2040,7 @@ can assume overwriteable media.
"discard"|"keep"|"patch"|"show_status"|bootspec
.br
Define the handling of an eventual El Torito object which has
been read from an existing ISO image or defines how to make a prepared
been read from an existing ISO image or define how to make a prepared
ISOLINUX file set bootable.
.br
@ -2342,9 +2345,9 @@ Drives which are occupied by other processes get not shown.
Show media specific table of content. This is the media session history,
not the ISO image directory tree.
.br
In case of overwriteable media holding a valid ISO image, a single session
gets fabricated from the ISO image size info. But if the first session on the
overwriteable media was written by xorriso then in most cases a complete
In case of overwriteable media holding a valid ISO image, it may happen that
only a single session gets shown. But if the first session on the
overwriteable media was written by xorriso then a complete
session history can be emulated.
.br
A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM
@ -2363,13 +2366,12 @@ drive can be "indev" or "outdev" to indicate already aquired drives,
or it can be the path of a not yet acquired drive.
Prefix "stdio:" for non-MMC drives is not mandatory.
.br
entity must be either "sbsector" , "track" , "session" , "volid"
or "auto". See also option -load.
entity must be either "sbsector" with the superblock sector address as id,
or "track" with a track number as id, or "session" with a session number,
or "volid" with a search pattern for the volume id, or "auto" with any text
as id.
.br
id gives the superblock sector address, the track number, the session number,
or a search pattern for the volume id respectively.
.br
path will be used as mount point and must already exist as a directory.
path will be used as mount point and must already exist as a directory on disk.
.br
The command gets printed to the result channel. See option -mount
for direct execution of this command.
@ -2417,9 +2419,8 @@ ids -pvd_info reports what would be written with the next -commit.
.B Navigation in ISO image and disk filesystem:
.TP
\fB\-cd\fR iso_rr_path
Change the current working directory in the emerging ISO
image as it is at the moment. This is prepended to iso_rr_paths
which do not begin with '/'.
Change the current working directory in the ISO image.
This is prepended to iso_rr_paths which do not begin with '/'.
.br
It is possible to set the working directory to a path which does not exist
yet in the ISO image. The necessary parent directories will be created when
@ -2428,7 +2429,7 @@ Use -mkdir if you want to enforce the existence of the directory already at
first insertion.
.TP
\fB\-cdx\fR disk_path
Change the current working directory on filesystem.
Change the current working directory in the local filesystem.
To be prepended to disk_paths which do not begin with '/'.
.TP
\fB\-pwd\fR
@ -2437,13 +2438,13 @@ Tell the current working directory in the ISO image.
.TP
\fB\-pwdx\fR
.br
Tell the current working directory on local filesystem.
Tell the current working directory in the local filesystem.
.TP
\fB\-ls\fR iso_rr_pattern [***]
List files in the ISO image which match shell patterns
(i.e. with wildcards '*' '?' '[a-z]').
If a pattern does not begin with '/' then it is compared with addresses
relative to -cd, the current working directory in the ISO image.
relative to -cd.
.br
Directories are listed by their content rather than as single file item.
.br
@ -2462,9 +2463,8 @@ Like -lsd but also list some of the file attributes.
The output format resembles shell command ls -dln.
.TP
\fB\-lsx\fR disk_pattern [***]
List files on local filesystem which match shell patterns. Patterns which do
not begin with '/' are used relative to -cdx, the current working directory in
the local filesystem.
List files in the local filesystem which match shell patterns. Patterns which
do not begin with '/' are used relative to -cdx.
.br
Directories are listed by their content rather than as single file item.
.br
@ -2512,7 +2512,7 @@ Similar to shell command du -sk.
.TP
\fB\-dux\fR disk_pattern [***]
Recursively list size of directories and files in the local filesystem
which match one of the patterns, similar to shell command du -k.
which match one of the patterns. Similar to shell command du -k.
.TP
\fB\-dusx\fR disk_pattern [***]
List size of directories and files in the local filesystem
@ -2529,7 +2529,7 @@ different device than their parent. It never matches the disk_path
given as start address for -findx.
.br
-findx accepts the -exec actions as does -find. But except the following few
actions it will allways perform action "echo".
actions it will always perform action "echo".
.br
\fBin_iso\fR reports the path if its counterpart exist in the ISO image.
For this the disk_path of the -findx command gets replaced
@ -2627,12 +2627,12 @@ of blocks and quality. Qualities which begin with "+" are
supposed to be valid readable data. Qualities with "-" are unreadable or
corrupted data.
"0" indicates qualities which are not covered by the check run or are regularly
allowed to to be unreadable (e.g. gaps between tracks).
allowed to be unreadable (e.g. gaps between tracks).
.br
Alternatively it is possible to report damaged files rather than blocks.
.br
If -md5 is on then the default mode what=tracks looks out for libisofs
checksum tags for the ISO session data and and eventually checks them
If -md5 is "on" then the default mode what=tracks looks out for libisofs
checksum tags for the ISO session data and eventually checks them
against the checksums computed from the data stream.
.TP
\fB\-check_media_defaults\fR [option [option ...]] --
@ -2654,6 +2654,7 @@ abort_file=/var/opt/xorriso/do_abort_check_media
sector_map='' map_with_volid=off patch_lba0=off report=blocks
.br
bad_limit=valid slow_limit=1.0 chunk_size=0s
.br
Option "reset=now" restores these startup defaults.
.br
Non-default options are:
@ -2729,7 +2730,7 @@ sector_map= and processes this virtual outcome.
Choose one of "good", "md5_match", "slow", "partial", "valid", "untested",
"invalid", "tao_end", "off_track", "md5_mismatch", "unreadable".
.br
"slow_limit=" sets the time threshold for a single read chunk to considered
"slow_limit=" sets the time threshold for a single read chunk to be considered
slow. This may be a fractional number like 0.1 or 1.5.
.br
"chunk_size=" sets the number of bytes to be read in one read operation.
@ -2758,7 +2759,7 @@ Only mismatching data files will be reported.
.PP
Normally xorriso only writes to disk files which were given as stdio:
pseudo-drives or as log files.
But its alter ego, osirrox, is able to extract file objects
But its alter ego osirrox is able to extract file objects
from ISO images and to create, overwrite, or delete file objects on disk.
.br
Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply.
@ -2811,13 +2812,13 @@ written, or ejected. But be aware that even harmless inquiries can spoil
ongoing burns of CD-R[W] and DVD-R[W].
.TP
\fB\-extract\fR iso_rr_path disk_path
Restore the file objects at and underneath iso_rr_path to their corresponding
Copy the file objects at and underneath iso_rr_path to their corresponding
addresses at and underneath disk_path.
This is the inverse of -map or -update_r.
.br
If iso_rr_path is a directory and disk_path is an existing directory then
both trees will be merged. Directory attributes get extracted only if the disk
directory is newly created by the restore operation.
directory is newly created by the copy operation.
Disk files get removed only if they are to be replaced
by file objects from the ISO image.
.br
@ -2846,8 +2847,8 @@ is performed. It may be quicker and more rugged than the general reading
method.
.TP
\fB\-cpx\fR iso_rr_path [***] disk_path
Extract single leaf file objects from the ISO image and store them under
the address given by disk_path. If more then one iso_rr_path is given then
Copy single leaf file objects from the ISO image to the address given by
disk_path. If more then one iso_rr_path is given then
disk_path must be a directory or non-existent. In the latter case it gets
created and the extracted files get installed in it with the same leafnames.
.br
@ -2925,7 +2926,7 @@ If pathspecs are given and if no output file was chosen before or during the
"mkisofs" option list, then standard output (-outdev "-") will get into effect.
If -o points to a regular file, then it will be truncated to 0 bytes
when finally writing begins. This truncation does not happen if the drive
is chosen by xorriso options before or after -as mkisofs.
is chosen by xorriso 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
@ -3036,7 +3037,7 @@ Print program name and version.
\fB\-history\fR textline
Copy textline into libreadline history.
.TP
\fB\-status\fR [mode|filter]
\fB\-status\fR mode|filter
Print the current settings of xorriso.
Modes:
.br
@ -3147,7 +3148,7 @@ The first three items are single words, the rest of the line is the volume id.
End program immediately
.TP
\fB#\fR any text
In dialog or file execution mode only and only as first
Only in dialog or file execution mode, and only as first
non-whitespace in line:
Do not execute the line but eventually store it in history.
.TP
@ -3173,17 +3174,18 @@ Example:
I:1: enter option and arguments :
.TP
\fB\-logfile\fR channel fileaddress
Copy output of a channel to the given file.
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 each time an
action has been completed.
If text is not empty it will get put out each time after a dialog line has been
processed.
.TP
\fB\-prog\fR text
Use text as this program's name in subsequent messages
Use text as name of this program in subsequent messages
.TP
\fB\-prog_help\fR text
Use text as this program's name and perform -help.
Use text as name of this program and perform -help.
.br
.SH EXAMPLES
.SS
@ -3194,7 +3196,7 @@ Blank media and compose a new ISO image as batch run
.br
A dialog session doing about the same
.br
Manipulating an existing ISO image on the same media
Manipulate an existing ISO image on the same media
.br
Copy modified ISO image from one media to another
.br
@ -3252,7 +3254,7 @@ session to media.
.br
The ISO image may be shaped in a more elaborate way like the following:
Omit some unwanted stuff by removing it from the image directory tree.
Re-add some wanted stuff.
Reintroduce some wanted stuff.
.br
\fB$\fR cd /home/me
.br
@ -3276,15 +3278,16 @@ Re-add some wanted stuff.
.br
-cd / \\
.br
-add pictures/confidential/work*
-add pictures/confidential/work* --
.br
Note that '/pictures/*private*' is a pattern for iso_rr_paths
while pictures/confidential/work* gets expanded by the shell
with addresses from the hard disk.
with addresses from the hard disk. Options -add and -map have different
argument rules but finally the same effect: they put files into the image.
.SS
.B A dialog session doing about the same
.br
-pathspecs is already given as start argument. The other activities
Some settings are already given as start argument. The other activities
are done as dialog input. The pager gets set to 20 lines of 80 characters.
.br
The drive is aquired by option -dev rather than -outdev in order to see
@ -3326,15 +3329,16 @@ enter option and arguments :
.br
enter option and arguments :
.br
.B \-commit -eject all -end
.B \-commit_eject all -end
.br
.SS
.B Manipulating an existing ISO image on the same media
.B Manipulate an existing ISO image on the same media
Load image from drive.
Remove (i.e. hide) directory /sounds and its subordinates.
Rename directory /pictures/confidential to /pictures/restricted.
Change access permissions of directory /pictures/restricted.
Add new directory trees /sounds and /movies. Burn to the same media and eject.
Add new directory trees /sounds and /movies.
Burn to the same media, check whether the tree can be loaded, and eject.
.br
\fB$\fR xorriso -dev /dev/sr2 \\
.br
@ -3408,7 +3412,8 @@ Paths underneath /dev normally need prefix "stdio:"
.br
If /dev/sdb is to be used frequently and /dev/sda is the system disk,
then consider to place the following lines in a xorriso Startup File.
They allow to use /dev/sdb without prefix and protect your disk from xorriso:
They allow to use /dev/sdb without prefix and protect disk /dev/sda
from xorriso:
.br
-drive_class banned /dev/sda*
-drive_class harmless /dev/sdb
@ -3628,6 +3633,9 @@ Avoid to eventually create /home/thomas/restored without rwx-permission.
-extract /personal_mail /home/thomas/restored/personal_mail \\
.br
-rollback_end
.br
The final command -rollback_end prevents an error message about the altered
image being discarded.
.SS
.B Try to retrieve as many blocks as possible from a damaged media
.br
@ -3641,9 +3649,6 @@ This can be repeated several times, eventually with -eject or with other
-indev drives. See the human readable part of "$HOME"/dvd_copy.map for
addresses which can be used on "$HOME"/dvd_copy with mount option -o sbsector=
resp. -s.
.br
If you want to make the newest session the default mount session, you
may add option "patch_lba0=on" to the final -check_media run.
.SH FILES
.SS
.B Startup files: