From be0b15a8e7726b942e706ab0be5fe56dff0bff69 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Mon, 16 May 2011 19:20:07 +0000 Subject: [PATCH] Adjusted line lengths to less than 80 chars in source of xorriso manual --- xorriso/xorriso.1 | 221 +++++++++++++++++++++++++------------------ xorriso/xorriso.info | 122 ++++++++++++------------ xorriso/xorriso.texi | 221 +++++++++++++++++++++++++------------------ 3 files changed, 315 insertions(+), 249 deletions(-) diff --git a/xorriso/xorriso.1 b/xorriso/xorriso.1 index 41cd7dcc..9f36e333 100644 --- a/xorriso/xorriso.1 +++ b/xorriso/xorriso.1 @@ -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 diff --git a/xorriso/xorriso.info b/xorriso/xorriso.info index beef4419..e3dc8352 100644 --- a/xorriso/xorriso.info +++ b/xorriso/xorriso.info @@ -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 diff --git a/xorriso/xorriso.texi b/xorriso/xorriso.texi index 27f1a8f6..1fa9dd68 100644 --- a/xorriso/xorriso.texi +++ b/xorriso/xorriso.texi @@ -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. @*