diff --git a/xorriso/convert_man_to_html.sh b/xorriso/convert_man_to_html.sh index 7c4d6bea..5e3772f4 100755 --- a/xorriso/convert_man_to_html.sh +++ b/xorriso/convert_man_to_html.sh @@ -56,10 +56,13 @@ then -e 's/Dialog, Readline, Result pager:<\/b>/\ 
Dialog, Readline, Result pager:<\/b>/' \ -e 's/Aquiring source and target drive:<\/b>/\ 
Aquiring source and target drive:<\/b>
\ 
/' \ -e 's/Influencing the behavior of image/\ 
Influencing the behavior of image/' \ + -e 's/Inserting files into ISO image:<\/b>/\ 
Inserting files into ISO image:<\/b>
\ 
/' \ -e 's/File manipulations:<\/b>/\ 
File manipulations:<\/b>
\ 
/' \ + -e 's/Tree traversal command -find:<\/b>/\ 
Tree traversal command -find:<\/b>
\ 
/' \ -e 's/^

−iso_rr_pattern/

\ 
\−iso_rr_pattern/' \ -e 's/EXAMPLES):
/EXAMPLES<\/A>):
/' \ - -e 's/Writing the result, drive control:<\/b>/\ 
Writing the result, drive control:<\/b>
/' \ + -e 's/Filters for data file content:<\/b>/\ 
Filters for data file content:<\/b>
\ 
/' \ + -e 's/Writing the result, drive control:<\/b>/\ 
Writing the result, drive control:<\/b>
\ 
/' \ -e 's/^-find \/ /\ \ -find \/ /' \ -e 's/Settings for file insertion:<\/b>/\ 
Settings for file insertion:<\/b>
\ 
/' \ -e 's/^$<\/b> ln -s/\ \ $<\/b> ln -s/' \ diff --git a/xorriso/make_docs.sh b/xorriso/make_docs.sh index a96ae93b..b05ba2eb 100755 --- a/xorriso/make_docs.sh +++ b/xorriso/make_docs.sh @@ -3,7 +3,8 @@ # Produce man page xorriso/xorriso.1 and info file xorriso/xorriso.info # from base file xorris/xorriso.texi. -xorriso/make_xorriso_1 -auto - ( cd xorriso ; makeinfo ./xorriso.texi ) +xorriso/make_xorriso_1 -auto + + diff --git a/xorriso/xorriso.1 b/xorriso/xorriso.1 index 5c2f335f..c4ca744f 100644 --- a/xorriso/xorriso.1 +++ b/xorriso/xorriso.1 @@ -442,7 +442,13 @@ a command with a fixed list length. It is handled as normal text if it appears among the arguments of such a command. .PP \fBPattern expansion\fR -is a property of some particular commands and not a general +converts a list of pattern words into a list of existing file addresses. +Eventual unmatched pattern words appear themselves in that result list, though. +.br +Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' +and respects '/' as separator which may only be matched literally. +.br +It is a property of some particular commands and not a general feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern. Commands which eventually use pattern expansion all have variable argument lists which are marked in this man page by "[***]" rather than "[...]". @@ -828,7 +834,7 @@ Allow for writing only the usage of MMC optical drives. Disallow to write the result into files of nearly arbitrary type. Once set, this command cannot be revoked. .TP -.B File manipulations: +.B Inserting files into ISO image: .PP The following commands expect file addresses of two kinds: .br @@ -859,27 +865,6 @@ eventual existing target directory rather than attempting to replace it. .PP The commands in this section alter the ISO image and not the local filesystem. .TP -\fB\-iso_rr_pattern\fR "on"|"ls"|"off" -Set the pattern expansion mode for the iso_rr_path arguments of several -commands which support this feature. -.br -\fBPattern expansion\fR -converts a list of pattern words into a list of existing file addresses. -Eventual unmatched pattern words appear themselves in that result list, though. -.br -Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' -and respects '/' as separator which may only be matched literally. -.br -Setting "off" disables this feature for all commands which are marked in this -man page by "iso_rr_path [***]" or "iso_rr_pattern [***]". -.br -Setting "on" enables it for all those commands. -.br -Setting "ls" enables it only for those which are marked by -"iso_rr_pattern [***]". -.br -Default is "on". -.TP \fB\-disk_pattern\fR "on"|"ls"|"off" Set the pattern expansion mode for the disk_path arguments of several commands which support this feature. @@ -1031,6 +1016,226 @@ get the same type as the disk_path. If a disk_path does not begin with '/' then -cdx is prepended. If the iso_rr_path does not begin with '/' then -cd is prepended. .TP +\fB\-mkdir\fR iso_rr_path [...] +Create empty directories if they do not exist yet. +Existence as directory generates a WARNING event, existence as +other file causes a FAILURE event. +.TP +.B Settings for file insertion: +.TP +\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 xorriso. Default is a limit of 100 extents, 4g -2k each: +.br + -file_size_limit 400g -200k -- +.br +When mounting ISO 9660 filesystems, old operating systems can handle only files +up to 2g -1 --. Newer ones are good up to 4g -1 --. +You need quite a new Linux kernel to read correctly the final bytes +of a file >= 4g if its size is not aligned to 2048 byte blocks. +.br +xorriso's own data read capabilities are not affected by eventual +operating system size limits. They apply to mounting only. Nevertheless, +the target filesystem of an -extract must be able to take the file size. +.TP +\fB\-not_mgt\fR code[:code[...]] +Control the behavior of the exclusion lists. +.br +Exclusion processing happens before disk_paths get mapped to the ISO image +and before disk files get compared with image files. +The absolute disk path of the source is matched against the -not_paths list. +The leafname of the disk path is matched against the patterns in the -not_leaf +list. If a match is detected then the disk path will not be regarded as an +existing file and not be added to the ISO image. +.br +Several codes are defined. +The _on/_off settings persist until they are revoked by their_off/_on +counterparts. +.br +"erase" empties the lists which were accumulated by -not_paths and -not_leaf. +.br +"reset" is like "erase" but also re-installs default behavior. +.br +"off" disables exclusion processing temporarily without invalidating +the lists and settings. +.br +"on" re-enables exclusion processing. +.br +"param_off" applies exclusion processing only to paths below disk_path +parameter of commands. I.e. explicitly given disk_paths are exempted +from exclusion processing. +.br +"param_on" applies exclusion processing to command parameters as well as +to files below such parameters. +.br +"subtree_off" with "param_on" excludes parameter paths only if they +match a -not_paths item exactly. +.br +"subtree_on" additionally excludes parameter paths which lead to a file +address below any -not_paths item. +.br +"ignore_off" treats excluded disk files as if they were missing. I.e. they +get reported with -compare and deleted from the image with -update. +.br +"ignore_on" keeps excluded files out of -compare or -update activities. +.TP +\fB\-not_paths\fR disk_path [***] +Add the given paths to the list of excluded absolute disk paths. If a given +path is relative, then the current -cdx is prepended to form an absolute path. +Eventual pattern matching happens at definition time and not when exclusion +checks are made. +.br +(Do not forget to end the list of disk_paths by "--") +.TP +\fB\-not_leaf\fR pattern +Add a single shell parser style pattern to the list of exclusions for +disk leafnames. These patterns are evaluated when the exclusion checks are +made. +.TP +\fB\-not_list\fR disk_path +Read lines from disk_path and use each of them either as -not_paths argument, +if they contain a / character, or as -not_leaf pattern. +.TP +\fB\-quoted_not_list\fR disk_path +Like -not_list but with quoted input reading rules. Each word is +handled as one argument for -not_paths resp. -not_leaf. +.TP +\fB\-follow\fR occasion[:occasion[...]] +Enable or disable resolution of symbolic links and mountpoints under +disk_paths. This applies to actions -add, -du*x, -ls*x, -findx, +and to -disk_pattern expansion. +.br +There are two kinds of follow decisison to be made: +.br +"link" is the hop from a symbolic link to its target file object. +If enabled then symbolic links are handled as their target file objects, +else symbolic links are handled as themselves. +.br +"mount" is the hop from one filesystem to another subordinate filesystem. +If enabled then mountpoint directories are handled as any other directory, +else mountpoints are handled as empty directories if they are encountered in +directory tree traversals. +.br +Less general than above occasions: +.br +"pattern" is mount and link hopping, but only during -disk_pattern expansion. +.br +"param" is link hopping for parameter words (after eventual pattern expansion). +If enabled then -ls*x will show the link targets rather than the links +themselves. -du*x, -findx, and -add will process the link targets but not +follow links in an eventual directory tree below the targets (unless "link" +is enabled). +.br +Occasions can be combined in a colon separated list. All occasions +mentioned in the list will then lead to a positive follow decision. +.br +"off" prevents any positive follow decision. Use it if no other occasion +applies. +.br +Shortcuts: +.br +"default" is equivalent to "pattern:mount:limit=100". +.br +"on" always decides positive. Equivalent to "link:mount". +.br + +Not an occasion but an optional setting is: +.br +"limit=" which sets the maximum number of link hops. +A link hop consists of a sequence of symbolic links and a final target +of different type. Nevertheless those hops can loop. Example: +.br + $ ln -s .. uploop +.br +Link hopping has a built-in loop detection which stops hopping at the first +repetition of a link target. Then the repeated link is handled as itself +and not as its target. +Regrettably one can construct link networks which +cause exponential workload before their loops get detected. +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 xorriso actions -add and -path_list. +.br +"on" enables pathspecs of the form +\fBtarget=source\fR +like with program mkisofs -graft-points. +It also disables -disk_pattern expansion for command -add. +.br +"off" disables pathspecs of the form target=source +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 name. +.br +With setting "off", name collisions cause FAILURE events. +With setting "nondir", only directories are protected by such events, other +existing file types get treated with -rm before the new file gets added. +Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an +existing directory and all its subordinates. +.br +If restoring of files is enabled, then the overwrite rule applies to the +target file objects on disk as well, but "on" is downgraded to "nondir". +.TP +\fB\-split_size\fR number["k"|"m"] +Set the threshold for automatic splitting of regular files. Such splitting +maps a large disk file onto a ISO directory with several part files in it. +This is necessary if the size of the disk file exceeds -file_size_limit. +Older operating systems can handle files in mounted ISO 9660 filesystems +only if they are smaller than 2 GiB resp. 4 GiB. +.br +Default is 0 which will exclude files larger than -file_size_limit by a +FAILURE event. +A well tested -split_size is 2047m. Sizes above -file_size_limit are not +permissible. +.br +While option -split_size is set larger than 0 such a directory with split +file pieces will be recognized and handled like a regular file by options +-compare* , -update*, and in overwrite situations. There are -ossirox +options "concat_split_on" and "concat_split_off" which control the handling +when files get restored to disk. +.br +In order to be recognizable, the names of the part files have to +describe the splitting by 5 numbers: +.br + part_number,total_parts,byte_offset,byte_count,disk_file_size +.br +which are embedded in the following text form: +.br + part_#_of_#_at_#_with_#_of_# +.br +Scaling characters like "m" or "k" are taken into respect. +All digits are interpreted as decimal, even if leading zeros are present. +.br +E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 +.br +No other files are allowed in the directory. All parts have to be present and +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 File manipulations: +.PP +The following commands manipulate files in the ISO image, regardless whether +they stem from the loaded image or were newly inserted. +.PP +.TP +\fB\-iso_rr_pattern\fR "on"|"ls"|"off" +Set the pattern expansion mode for the iso_rr_path arguments of several +commands which support this feature. +.br +Setting "off" disables pattern expansion for all commands which are marked +in this man page by "iso_rr_path [***]" or "iso_rr_pattern [***]". +.br +Setting "on" enables it for all those commands. +.br +Setting "ls" enables it only for those which are marked by +"iso_rr_pattern [***]". +.br +Default is "on". +.TP \fB\-rm\fR iso_rr_path [***] Delete the given files from the ISO image. .br @@ -1044,6 +1249,9 @@ media in modification mode. Delete the given files or directory trees from the ISO image. See also the note with option -rm. .TP +\fB\-rmdir\fR iso_rr_path [***] +Delete empty directories. +.TP \fB\-mv\fR iso_rr_path [***] iso_rr_path Rename the given file objects in the ISO tree to the last argument in the list. Use the same rules as with shell command mv. @@ -1170,96 +1378,6 @@ whitespace after the end quote will be ignored. Non-printables bytes and quotes must be represented as \\XYZ by their octal ASCII code XYZ. Use code \\000 for 0-bytes. .TP -\fB\-external_filter\fR name option[:option] program_path [arguments] -- -Register a content filter by associating a name with a program path, -program arguments, and some behavioral options. Once registered it can be -applied to multiple data files in the ISO image, regardless whether their -content resides in the loaded ISO image or in the local filesystem. -External filter processes may produce synthetic file content by reading the -original content from stdin and writing to stdout whatever they want. -They must deliver the same output on the same input in repeated runs. -.br -Options are: -.br - "default" means that no other option is intended. -.br - "suffix=..." sets a file name suffix. If it is not empty then it will be -appended to the file name or removed from it. -.br - "remove_suffix" will remove an eventual file name suffix -rather than appending it. -.br - "if_nonempty" will leave 0-sized files unfiltered. -.br - "if_reduction" will try filtering and revoke it if the content size does not -shrink. -.br - "if_block_reduction" will revoke if the number of 2 kB blocks does not shrink. -.br - "used=..." is ignored. Command -status shows it with the number of -files which currently have the filter applied. -.br -Examples: -.br - -external_filter bzip2 suffix=.bz2:if_block_reduction \\ -.br - /usr/bin/bzip2 -- -.br - -external_filter bunzip2 suffix=.bz2:remove_suffix \\ -.br - /usr/bin/bunzip2 -- -.TP -\fB\-unregister_filter\fR name -Remove an -external_filter registration. This is only possible if the filter -is not applied to any file in the ISO image. -.TP -\fB\-close_filter_list\fR -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 xorriso. -By default they are banned if xorriso runs under setuid permission. -.TP -\fB\-set_filter\fR name iso_rr_path [***] -Apply an -external_filter or a built-in filter to the given data files in the -ISO image. -If the filter suffix is not empty , then it will be applied to the file name. -Renaming only happens if the filter really gets attached and is not revoked by -its options. -By default files which already bear the suffix will not get filtered. The -others will get the suffix appended to their names. -If the filter has option "remove_suffix", then the filter will only be -applied if the suffix is present and can be removed. -Name oversize or collision caused by suffix change will prevent filtering. -.br -With most filter types this command will immediately run the filter once for -each file in order to determine the output size. -Content reading operations like -extract , -compare and image generation will -perform further filter runs and deliver filtered content. -.br -At image generation time the filter output must still be the same as the -output from the first run. Filtering for image generation does not happen -with files from the loaded ISO image if the write method of growing is in -effect (i.e -indev and -outdev are identical). -.br -The reserved filter name "--remove-all-filters" revokes -filtering. This will revoke eventual suffix renamings as well. -Use "--remove-all-filters+" to -prevent any suffix renaming. -.br -Built-in filters are "--zisofs" and -"--zisofs-decode". The former is to be -applied via -set_filter, the latter is automatically applied if zisofs -compressed content is detected with a file when loading the ISO image. -.br -Another built-in filter pair is "--gzip" -and "--gunzip" with suffix ".gz". -They behave about like external gzip and gunzip but avoid forking a process -for each single file. So they are much faster if there are many small files. -.TP -\fB\-set_filter_r\fR name iso_rr_path [***] -Like -set_filter but affecting all data files below eventual directories. -.TP \fB\-alter_date\fR type timestring iso_rr_path [***] Alter the date entries of a file in the ISO image. type is one of "a", "m", "b" for access time, modification time, @@ -1299,6 +1417,9 @@ where "A0" is year 2000, "B0" is 2010, etc. \fB\-alter_date_r\fR type timestring iso_rr_path [***] Like -alter_date but affecting all files below eventual directories. .TP +.B Tree traversal command -find: +.PP +.TP \fB\-find\fR iso_rr_path [test [op] [test ...]] [-exec action [params]] -- A restricted substitute for shell command find in the ISO image. It performs an action on matching file objects at or below iso_rr_path. @@ -1522,24 +1643,111 @@ E.g.: .br -find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r -- .TP -\fB\-mkdir\fR iso_rr_path [...] -Create empty directories if they do not exist yet. -Existence as directory generates a WARNING event, existence as -other file causes a FAILURE event. +.B Filters for data file content: +.PP +\fBFilters\fR may be installed between data files in the ISO image and their +content source outside the image. They may also be used vice versa between +data content in the image and target files on disk. +.br +Built-in filters are "--zisofs" and +"--zisofs-decode". The former is to be +applied via -set_filter, the latter is automatically applied if zisofs +compressed content is detected with a file when loading the ISO image. +.br +Another built-in filter pair is "--gzip" +and "--gunzip" with suffix ".gz". +They behave about like external gzip and gunzip but avoid forking a process +for each single file. So they are much faster if there are many small files. +.PP .TP -\fB\-rmdir\fR iso_rr_path [***] -Delete empty directories. +\fB\-external_filter\fR name option[:option] program_path [arguments] -- +Register a content filter by associating a name with a program path, +program arguments, and some behavioral options. Once registered it can be +applied to multiple data files in the ISO image, regardless whether their +content resides in the loaded ISO image or in the local filesystem. +External filter processes may produce synthetic file content by reading the +original content from stdin and writing to stdout whatever they want. +They must deliver the same output on the same input in repeated runs. +.br +Options are: +.br + "default" means that no other option is intended. +.br + "suffix=..." sets a file name suffix. If it is not empty then it will be +appended to the file name or removed from it. +.br + "remove_suffix" will remove an eventual file name suffix +rather than appending it. +.br + "if_nonempty" will leave 0-sized files unfiltered. +.br + "if_reduction" will try filtering and revoke it if the content size does not +shrink. +.br + "if_block_reduction" will revoke if the number of 2 kB blocks does not shrink. +.br + "used=..." is ignored. Command -status shows it with the number of +files which currently have the filter applied. +.br +Examples: +.br + -external_filter bzip2 suffix=.bz2:if_block_reduction \\ +.br + /usr/bin/bzip2 -- +.br + -external_filter bunzip2 suffix=.bz2:remove_suffix \\ +.br + /usr/bin/bunzip2 -- .TP -\fB\-rollback\fR -Discard the manipulated ISO image and reload it from -indev. +\fB\-unregister_filter\fR name +Remove an -external_filter registration. This is only possible if the filter +is not applied to any file in the ISO image. .TP -\fB\-rollback_end\fR -Discard the manipulated ISO image. End program without loading a new image. +\fB\-close_filter_list\fR +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 xorriso. +By default they are banned if xorriso runs under setuid permission. +.TP +\fB\-set_filter\fR name iso_rr_path [***] +Apply an -external_filter or a built-in filter to the given data files in the +ISO image. +If the filter suffix is not empty , then it will be applied to the file name. +Renaming only happens if the filter really gets attached and is not revoked by +its options. +By default files which already bear the suffix will not get filtered. The +others will get the suffix appended to their names. +If the filter has option "remove_suffix", then the filter will only be +applied if the suffix is present and can be removed. +Name oversize or collision caused by suffix change will prevent filtering. +.br +With most filter types this command will immediately run the filter once for +each file in order to determine the output size. +Content reading operations like -extract , -compare and image generation will +perform further filter runs and deliver filtered content. +.br +At image generation time the filter output must still be the same as the +output from the first run. Filtering for image generation does not happen +with files from the loaded ISO image if the write method of growing is in +effect (i.e -indev and -outdev are identical). +.br +The reserved filter name "--remove-all-filters" revokes +filtering. This will revoke eventual suffix renamings as well. +Use "--remove-all-filters+" to +prevent any suffix renaming. +.TP +\fB\-set_filter_r\fR name iso_rr_path [***] +Like -set_filter but affecting all data files below eventual directories. .TP .B Writing the result, drive control: .PP (see also paragraph about settings below) .TP +\fB\-rollback\fR +Discard the manipulated ISO image and reload it from -indev. +(Use -rollback_end if immediate program end is desired.) +.TP \fB\-commit\fR Perform the write operation. Afterwards eventually make the -outdev the new -dev and load the image from there. @@ -1672,208 +1880,14 @@ Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserve space. Put out a list of media types supported by -indev, resp. -outdev, resp. both. The currently recognized type is marked by text "(current)". .TP -.B Settings for file insertion: -.TP -\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 xorriso. Default is a limit of 100 extents, 4g -2k each: -.br - -file_size_limit 400g -200k -- -.br -When mounting ISO 9660 filesystems, old operating systems can handle only files -up to 2g -1 --. Newer ones are good up to 4g -1 --. -You need quite a new Linux kernel to read correctly the final bytes -of a file >= 4g if its size is not aligned to 2048 byte blocks. -.br -xorriso's own data read capabilities are not affected by eventual -operating system size limits. They apply to mounting only. Nevertheless, -the target filesystem of an -extract must be able to take the file size. -.TP -\fB\-not_mgt\fR code[:code[...]] -Control the behavior of the exclusion lists. -.br -Exclusion processing happens before disk_paths get mapped to the ISO image -and before disk files get compared with image files. -The absolute disk path of the source is matched against the -not_paths list. -The leafname of the disk path is matched against the patterns in the -not_leaf -list. If a match is detected then the disk path will not be regarded as an -existing file and not be added to the ISO image. -.br -Several codes are defined. -The _on/_off settings persist until they are revoked by their_off/_on -counterparts. -.br -"erase" empties the lists which were accumulated by -not_paths and -not_leaf. -.br -"reset" is like "erase" but also re-installs default behavior. -.br -"off" disables exclusion processing temporarily without invalidating -the lists and settings. -.br -"on" re-enables exclusion processing. -.br -"param_off" applies exclusion processing only to paths below disk_path -parameter of commands. I.e. explicitly given disk_paths are exempted -from exclusion processing. -.br -"param_on" applies exclusion processing to command parameters as well as -to files below such parameters. -.br -"subtree_off" with "param_on" excludes parameter paths only if they -match a -not_paths item exactly. -.br -"subtree_on" additionally excludes parameter paths which lead to a file -address below any -not_paths item. -.br -"ignore_off" treats excluded disk files as if they were missing. I.e. they -get reported with -compare and deleted from the image with -update. -.br -"ignore_on" keeps excluded files out of -compare or -update activities. -.TP -\fB\-not_paths\fR disk_path [***] -Add the given paths to the list of excluded absolute disk paths. If a given -path is relative, then the current -cdx is prepended to form an absolute path. -Eventual pattern matching happens at definition time and not when exclusion -checks are made. -.br -(Do not forget to end the list of disk_paths by "--") -.TP -\fB\-not_leaf\fR pattern -Add a single shell parser style pattern to the list of exclusions for -disk leafnames. These patterns are evaluated when the exclusion checks are -made. -.TP -\fB\-not_list\fR disk_path -Read lines from disk_path and use each of them either as -not_paths argument, -if they contain a / character, or as -not_leaf pattern. -.TP -\fB\-quoted_not_list\fR disk_path -Like -not_list but with quoted input reading rules. Each word is -handled as one argument for -not_paths resp. -not_leaf. -.TP -\fB\-follow\fR occasion[:occasion[...]] -Enable or disable resolution of symbolic links and mountpoints under -disk_paths. This applies to actions -add, -du*x, -ls*x, -findx, -and to -disk_pattern expansion. -.br -There are two kinds of follow decisison to be made: -.br -"link" is the hop from a symbolic link to its target file object. -If enabled then symbolic links are handled as their target file objects, -else symbolic links are handled as themselves. -.br -"mount" is the hop from one filesystem to another subordinate filesystem. -If enabled then mountpoint directories are handled as any other directory, -else mountpoints are handled as empty directories if they are encountered in -directory tree traversals. -.br -Less general than above occasions: -.br -"pattern" is mount and link hopping, but only during -disk_pattern expansion. -.br -"param" is link hopping for parameter words (after eventual pattern expansion). -If enabled then -ls*x will show the link targets rather than the links -themselves. -du*x, -findx, and -add will process the link targets but not -follow links in an eventual directory tree below the targets (unless "link" -is enabled). -.br -Occasions can be combined in a colon separated list. All occasions -mentioned in the list will then lead to a positive follow decision. -.br -"off" prevents any positive follow decision. Use it if no other occasion -applies. -.br -Shortcuts: -.br -"default" is equivalent to "pattern:mount:limit=100". -.br -"on" always decides positive. Equivalent to "link:mount". -.br - -Not an occasion but an optional setting is: -.br -"limit=" which sets the maximum number of link hops. -A link hop consists of a sequence of symbolic links and a final target -of different type. Nevertheless those hops can loop. Example: -.br - $ ln -s .. uploop -.br -Link hopping has a built-in loop detection which stops hopping at the first -repetition of a link target. Then the repeated link is handled as itself -and not as its target. -Regrettably one can construct link networks which -cause exponential workload before their loops get detected. -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 xorriso actions -add and -path_list. -.br -"on" enables pathspecs of the form -\fBtarget=source\fR -like with program mkisofs -graft-points. -It also disables -disk_pattern expansion for command -add. -.br -"off" disables pathspecs of the form target=source -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 name. -.br -With setting "off", name collisions cause FAILURE events. -With setting "nondir", only directories are protected by such events, other -existing file types get treated with -rm before the new file gets added. -Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an -existing directory and all its subordinates. -.br -If restoring of files is enabled, then the overwrite rule applies to the -target file objects on disk as well, but "on" is downgraded to "nondir". -.TP -\fB\-split_size\fR number["k"|"m"] -Set the threshold for automatic splitting of regular files. Such splitting -maps a large disk file onto a ISO directory with several part files in it. -This is necessary if the size of the disk file exceeds -file_size_limit. -Older operating systems can handle files in mounted ISO 9660 filesystems -only if they are smaller than 2 GiB resp. 4 GiB. -.br -Default is 0 which will exclude files larger than -file_size_limit by a -FAILURE event. -A well tested -split_size is 2047m. Sizes above -file_size_limit are not -permissible. -.br -While option -split_size is set larger than 0 such a directory with split -file pieces will be recognized and handled like a regular file by options --compare* , -update*, and in overwrite situations. There are -ossirox -options "concat_split_on" and "concat_split_off" which control the handling -when files get restored to disk. -.br -In order to be recognizable, the names of the part files have to -describe the splitting by 5 numbers: -.br - part_number,total_parts,byte_offset,byte_count,disk_file_size -.br -which are embedded in the following text form: -.br - part_#_of_#_at_#_with_#_of_# -.br -Scaling characters like "m" or "k" are taken into respect. -All digits are interpreted as decimal, even if leading zeros are present. -.br -E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 -.br -No other files are allowed in the directory. All parts have to be present and -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: .PP Rock Ridge info will be generated by the program unconditionally. ACLs will be written according to the setting of option -acl. .TP \fB\-joliet\fR "on"|"off" -If enabled by "on", generate Joliet info additional to Rock Ridge info. +If enabled by "on", generate Joliet tree additional to ISO 9660 + Rock Ridge +tree. .TP \fB\-compliance\fR rule[:rule...] Adjust the compliance to specifications of ISO 9660 and its contemporary @@ -3245,7 +3259,10 @@ of xorriso begin. Only "-scsi_log" with dash "-" is recognized that way. .TP \fB\-end\fR .br -End program immediately +End program after writing eventually pending changes. +.TP +\fB\-rollback_end\fR +Discard pending changes. End program immediately. .TP \fB#\fR any text Only in dialog or file execution mode, and only as first diff --git a/xorriso/xorriso.info b/xorriso/xorriso.info index aaa69f0b..83ec3692 100644 --- a/xorriso/xorriso.info +++ b/xorriso/xorriso.info @@ -52,8 +52,8 @@ filesystems. ISO 9660 formatter program nor an external burn program for CD, DVD or BD but rather incorporates the libraries of libburnia-project.org . -Overview of features -==================== +1.1 Features +============ Operates on an existing ISO image or creates a new one. Copies files from disk filesystem into the ISO image. @@ -158,6 +158,7 @@ media. These media can assume several states in which they offer different capabilities. + *Blank* media can be written from scratch. They contain no ISO image suitable for xorriso. Blank is the state of newly purchased optical media. With used CD-RW @@ -166,10 +167,12 @@ Overwriteable media are considered blank if they are new or if they have been marked as blank by xorriso. Action -blank "as_needed" can be used to do this marking on overwriteable media, or to apply eventual mandatory formatting to new media. + *Appendable* media accept further sessions. Either they are MMC multi-session media in appendable state, or they are overwriteable media which contain an ISO image suitable for xorriso. Appendable is the state after writing a session with option -close off. + *Closed* media cannot be written. They may contain an ISO image suitable for xorriso. Closed is the state of DVD-ROM media and of multi-session media which @@ -384,11 +387,17 @@ The list delimiter is silently tolerated if it appears after the parameters of a command with a fixed list length. It is handled as normal text if it appears among the arguments of such a command. - *Pattern expansion* is a property of some particular commands and -not a general feature. It gets controlled by commands -iso_rr_pattern -and -disk_pattern. Commands which eventually use pattern expansion all -have variable argument lists which are marked in this man page by -"[***]" rather than "[...]". + *Pattern expansion* converts a list of pattern words into a list of +existing file addresses. Eventual unmatched pattern words appear +themselves in that result list, though. +Pattern matching supports the usual shell parser wildcards '*' '?' +'[xyz]' and respects '/' as separator which may only be matched +literally. +It is a property of some particular commands and not a general feature. +It gets controlled by commands -iso_rr_pattern and -disk_pattern. +Commands which eventually use pattern expansion all have variable +argument lists which are marked in this man page by "[***]" rather than +"[...]". Some other commands perform pattern matching unconditionally. Command and parameter words are either read from program arguments, @@ -473,9 +482,12 @@ inner dashes are interpreted as underscores. * AqDrive:: Aquiring source and target drive * Loading:: Influencing the behavior of image loading -* Manipulation:: File manipulations -* Writing:: Writing the result, drive control +* Insert:: Inserting files into ISO image * SetInsert:: Settings for file insertion +* Manip:: File manipulations +* CmdFind:: Tree traversal command -find +* Filter:: Filters for data file content +* Writing:: Writing the result, drive control * SetWrite:: Settings for result writing * Bootable:: El Torito bootable ISO images * Charset:: Character sets @@ -548,7 +560,7 @@ influence the behavior of image loading. See next option group. output begins. The output drive is given up when writing is done.  -File: xorriso.info, Node: Loading, Next: Manipulation, Prev: AqDrive, Up: Options +File: xorriso.info, Node: Loading, Next: Insert, Prev: AqDrive, Up: Options 9.2 Influencing the behavior of image loading ============================================= @@ -777,10 +789,10 @@ activate them only after image loading. set, this command cannot be revoked.  -File: xorriso.info, Node: Manipulation, Next: Writing, Prev: Loading, Up: Options +File: xorriso.info, Node: Insert, Next: SetInsert, Prev: Loading, Up: Options -9.3 File manipulations -====================== +9.3 Inserting files into ISO image +================================== The following commands expect file addresses of two kinds: *disk_path* is a path to an object in the local filesystem tree. *iso_rr_path* is @@ -806,23 +818,6 @@ replace it. The commands in this section alter the ISO image and not the local filesystem. --iso_rr_pattern "on"|"ls"|"off" - Set the pattern expansion mode for the iso_rr_path arguments of - several commands which support this feature. - *Pattern expansion* converts a list of pattern words into a list - of existing file addresses. Eventual unmatched pattern words - appear themselves in that result list, though. - Pattern matching supports the usual shell parser wildcards '*' '?' - '[xyz]' and respects '/' as separator which may only be matched - literally. - Setting "off" disables this feature for all commands which are - marked in this man page by "iso_rr_path [***]" or "iso_rr_pattern - [***]". - Setting "on" enables it for all those commands. - Setting "ls" enables it only for those which are marked by - "iso_rr_pattern [***]". - Default is "on". - -disk_pattern "on"|"ls"|"off" Set the pattern expansion mode for the disk_path arguments of several commands which support this feature. @@ -958,6 +953,200 @@ filesystem. If a disk_path does not begin with '/' then -cdx is prepended. If the iso_rr_path does not begin with '/' then -cd is prepended. +-mkdir iso_rr_path [...] + Create empty directories if they do not exist yet. Existence as + directory generates a WARNING event, existence as other file + causes a FAILURE event. + + +File: xorriso.info, Node: SetInsert, Next: Manip, Prev: Insert, Up: Options + +9.4 Settings for file insertion +=============================== + +-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: + -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 + --. You need quite a new Linux kernel to read correctly the final + bytes of a file >= 4g if its size is not aligned to 2048 byte + blocks. + xorriso's own data read capabilities are not affected by eventual + operating system size limits. They apply to mounting only. + Nevertheless, the target filesystem of an -extract must be able to + take the file size. + +-not_mgt code[:code[...]] + Control the behavior of the exclusion lists. + Exclusion processing happens before disk_paths get mapped to the + ISO image and before disk files get compared with image files. + The absolute disk path of the source is matched against the + -not_paths list. The leafname of the disk path is matched against + the patterns in the -not_leaf list. If a match is detected then + the disk path will not be regarded as an existing file and not be + added to the ISO image. + Several codes are defined. The _on/_off settings persist until + they are revoked by their_off/_on counterparts. + "erase" empties the lists which were accumulated by -not_paths and + -not_leaf. + "reset" is like "erase" but also re-installs default behavior. + "off" disables exclusion processing temporarily without + invalidating the lists and settings. + "on" re-enables exclusion processing. + "param_off" applies exclusion processing only to paths below + disk_path parameter of commands. I.e. explicitly given disk_paths + are exempted from exclusion processing. + "param_on" applies exclusion processing to command parameters as + well as to files below such parameters. + "subtree_off" with "param_on" excludes parameter paths only if they + match a -not_paths item exactly. + "subtree_on" additionally excludes parameter paths which lead to a + file address below any -not_paths item. + "ignore_off" treats excluded disk files as if they were missing. + I.e. they get reported with -compare and deleted from the image + with -update. + "ignore_on" keeps excluded files out of -compare or -update + activities. + +-not_paths disk_path [***] + Add the given paths to the list of excluded absolute disk paths. + If a given path is relative, then the current -cdx is prepended to + form an absolute path. Eventual pattern matching happens at + definition time and not when exclusion checks are made. + (Do not forget to end the list of disk_paths by "--") + +-not_leaf pattern + Add a single shell parser style pattern to the list of exclusions + for disk leafnames. These patterns are evaluated when the + exclusion checks are made. + +-not_list disk_path + Read lines from disk_path and use each of them either as + -not_paths argument, if they contain a / character, or as + -not_leaf pattern. + +-quoted_not_list disk_path + Like -not_list but with quoted input reading rules. Each word is + handled as one argument for -not_paths resp. -not_leaf. + +-follow occasion[:occasion[...]] + Enable or disable resolution of symbolic links and mountpoints + under disk_paths. This applies to actions -add, -du*x, -ls*x, + -findx, and to -disk_pattern expansion. + There are two kinds of follow decisison to be made: + "link" is the hop from a symbolic link to its target file object. + If enabled then symbolic links are handled as their target file + objects, else symbolic links are handled as themselves. + "mount" is the hop from one filesystem to another subordinate + filesystem. If enabled then mountpoint directories are handled as + any other directory, else mountpoints are handled as empty + directories if they are encountered in directory tree traversals. + Less general than above occasions: + "pattern" is mount and link hopping, but only during -disk_pattern + expansion. + "param" is link hopping for parameter words (after eventual + pattern expansion). If enabled then -ls*x will show the link + targets rather than the links themselves. -du*x, -findx, and -add + will process the link targets but not follow links in an eventual + directory tree below the targets (unless "link" is enabled). + Occasions can be combined in a colon separated list. All occasions + mentioned in the list will then lead to a positive follow decision. + "off" prevents any positive follow decision. Use it if no other + occasion applies. + Shortcuts: + "default" is equivalent to "pattern:mount:limit=100". + "on" always decides positive. Equivalent to "link:mount". + + Not an occasion but an optional setting is: + "limit=" which sets the maximum number of link hops. A + link hop consists of a sequence of symbolic links and a final + target of different type. Nevertheless those hops can loop. + Example: + $ ln -s .. uploop + Link hopping has a built-in loop detection which stops hopping at + the first repetition of a link target. Then the repeated link is + handled as itself and not as its target. Regrettably one can + construct link networks which cause exponential workload before + their loops get detected. The number given with "limit=" can curb + this workload at the risk of truncating an intentional sequence of + link hops. + +-pathspecs "on"|"off" + Control parameter interpretation with xorriso actions -add and + -path_list. + "on" enables pathspecs of the form *target=source* like with + program mkisofs -graft-points. It also disables -disk_pattern + expansion for command -add. + "off" disables pathspecs of the form target=source and eventually + enables -disk_pattern expansion. + +-overwrite "on"|"nondir"|"off" + Allow or disallow to overwrite existing files in the ISO image by + files with the same name. + With setting "off", name collisions cause FAILURE events. With + setting "nondir", only directories are protected by such events, + other existing file types get treated with -rm before the new file + gets added. Setting "on" allows automatic -rm_r. I.e. a + non-directory can replace an existing directory and all its + subordinates. + If restoring of files is enabled, then the overwrite rule applies + to the target file objects on disk as well, but "on" is downgraded + to "nondir". + +-split_size number["k"|"m"] + Set the threshold for automatic splitting of regular files. Such + splitting maps a large disk file onto a ISO directory with several + part files in it. This is necessary if the size of the disk file + exceeds -file_size_limit. Older operating systems can handle + files in mounted ISO 9660 filesystems only if they are smaller + than 2 GiB resp. 4 GiB. + Default is 0 which will exclude files larger than -file_size_limit + by a FAILURE event. A well tested -split_size is 2047m. Sizes + above -file_size_limit are not permissible. + While option -split_size is set larger than 0 such a directory + with split file pieces will be recognized and handled like a + regular file by options -compare* , -update*, and in overwrite + situations. There are -ossirox options "concat_split_on" and + "concat_split_off" which control the handling when files get + restored to disk. + In order to be recognizable, the names of the part files have to + describe the splitting by 5 numbers: + part_number,total_parts,byte_offset,byte_count,disk_file_size + which are embedded in the following text form: + part_#_of_#_at_#_with_#_of_# + Scaling characters like "m" or "k" are taken into respect. All + digits are interpreted as decimal, even if leading zeros are + present. + E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 + No other files are allowed in the directory. All parts have to be + present and their numbers have to be plausible. E.g. byte_count + must be valid as -cut_out argument and their contents may not + overlap. + + +File: xorriso.info, Node: Manip, Next: CmdFind, Prev: SetInsert, Up: Options + +9.5 File manipulations +====================== + +The following commands manipulate files in the ISO image, regardless +whether they stem from the loaded image or were newly inserted. + +-iso_rr_pattern "on"|"ls"|"off" + Set the pattern expansion mode for the iso_rr_path arguments of + several commands which support this feature. + Setting "off" disables pattern expansion for all commands which + are marked in this man page by "iso_rr_path [***]" or + "iso_rr_pattern [***]". + Setting "on" enables it for all those commands. + Setting "ls" enables it only for those which are marked by + "iso_rr_pattern [***]". + Default is "on". + -rm iso_rr_path [***] Delete the given files from the ISO image. Note: This does not free any space on the -indev media, even if @@ -969,6 +1158,9 @@ filesystem. Delete the given files or directory trees from the ISO image. See also the note with option -rm. +-rmdir iso_rr_path [***] + Delete empty directories. + -mv iso_rr_path [***] iso_rr_path Rename the given file objects in the ISO tree to the last argument in the list. Use the same rules as with shell command mv. @@ -1080,82 +1272,6 @@ filesystem. ignored. Non-printables bytes and quotes must be represented as \XYZ by their octal ASCII code XYZ. Use code \000 for 0-bytes. --external_filter name option[:option] program_path [arguments] -- - Register a content filter by associating a name with a program - path, program arguments, and some behavioral options. Once - registered it can be applied to multiple data files in the ISO - image, regardless whether their content resides in the loaded ISO - image or in the local filesystem. External filter processes may - produce synthetic file content by reading the original content - from stdin and writing to stdout whatever they want. They must - deliver the same output on the same input in repeated runs. - Options are: - "default" means that no other option is intended. - "suffix=..." sets a file name suffix. If it is not empty then it - will be appended to the file name or removed from it. - "remove_suffix" will remove an eventual file name suffix rather - than appending it. - "if_nonempty" will leave 0-sized files unfiltered. - "if_reduction" will try filtering and revoke it if the content - size does not shrink. - "if_block_reduction" will revoke if the number of 2 kB blocks does - not shrink. - "used=..." is ignored. Command -status shows it with the number of - files which currently have the filter applied. - Examples: - -external_filter bzip2 suffix=.bz2:if_block_reduction \ - /usr/bin/bzip2 -- - -external_filter bunzip2 suffix=.bz2:remove_suffix \ - /usr/bin/bunzip2 -- - --unregister_filter name - Remove an -external_filter registration. This is only possible if - the filter is not applied to any file in the ISO image. - --close_filter_list - 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 xorriso. By - default they are banned if xorriso runs under setuid permission. - --set_filter name iso_rr_path [***] - Apply an -external_filter or a built-in filter to the given data - files in the ISO image. If the filter suffix is not empty , then - it will be applied to the file name. Renaming only happens if the - filter really gets attached and is not revoked by its options. By - default files which already bear the suffix will not get filtered. - The others will get the suffix appended to their names. If the - filter has option "remove_suffix", then the filter will only be - applied if the suffix is present and can be removed. Name - oversize or collision caused by suffix change will prevent - filtering. - With most filter types this command will immediately run the - filter once for each file in order to determine the output size. - Content reading operations like -extract , -compare and image - generation will perform further filter runs and deliver filtered - content. - At image generation time the filter output must still be the same - as the output from the first run. Filtering for image generation - does not happen with files from the loaded ISO image if the write - method of growing is in effect (i.e -indev and -outdev are - identical). - The reserved filter name "--remove-all-filters" revokes filtering. - This will revoke eventual suffix renamings as well. Use - "--remove-all-filters+" to prevent any suffix renaming. - Built-in filters are "--zisofs" and "--zisofs-decode". The former - is to be applied via -set_filter, the latter is automatically - applied if zisofs compressed content is detected with a file when - loading the ISO image. - Another built-in filter pair is "--gzip" and "--gunzip" with - suffix ".gz". They behave about like external gzip and gunzip but - avoid forking a process for each single file. So they are much - faster if there are many small files. - --set_filter_r name iso_rr_path [***] - Like -set_filter but affecting all data files below eventual - directories. - -alter_date type timestring iso_rr_path [***] Alter the date entries of a file in the ISO image. type is one of "a", "m", "b" for access time, modification time, both times. @@ -1180,6 +1296,13 @@ filesystem. Like -alter_date but affecting all files below eventual directories. + +File: xorriso.info, Node: CmdFind, Next: Filter, Prev: Manip, Up: Options + +9.6 Tree traversal command -find +================================ + + -find iso_rr_path [test [op] [test ...]] [-exec action [params]] -- A restricted substitute for shell command find in the ISO image. It performs an action on matching file objects at or below @@ -1358,29 +1481,105 @@ filesystem. -find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r -- --mkdir iso_rr_path [...] - Create empty directories if they do not exist yet. Existence as - directory generates a WARNING event, existence as other file - causes a FAILURE event. + +File: xorriso.info, Node: Filter, Next: Writing, Prev: CmdFind, Up: Options --rmdir iso_rr_path [***] - Delete empty directories. +9.7 Filters for data file content +================================= --rollback - Discard the manipulated ISO image and reload it from -indev. +*Filters* may be installed between data files in the ISO image and their +content source outside the image. They may also be used vice versa +between data content in the image and target files on disk. --rollback_end - Discard the manipulated ISO image. End program without loading a - new image. +Built-in filters are "--zisofs" and "--zisofs-decode". The former is to +be applied via -set_filter, the latter is automatically applied if +zisofs compressed content is detected with a file when loading the ISO +image. +Another built-in filter pair is "--gzip" and "--gunzip" with suffix +".gz". They behave about like external gzip and gunzip but avoid +forking a process for each single file. So they are much faster if +there are many small files. + +-external_filter name option[:option] program_path [arguments] -- + Register a content filter by associating a name with a program + path, program arguments, and some behavioral options. Once + registered it can be applied to multiple data files in the ISO + image, regardless whether their content resides in the loaded ISO + image or in the local filesystem. External filter processes may + produce synthetic file content by reading the original content + from stdin and writing to stdout whatever they want. They must + deliver the same output on the same input in repeated runs. + Options are: + "default" means that no other option is intended. + "suffix=..." sets a file name suffix. If it is not empty then it + will be appended to the file name or removed from it. + "remove_suffix" will remove an eventual file name suffix rather + than appending it. + "if_nonempty" will leave 0-sized files unfiltered. + "if_reduction" will try filtering and revoke it if the content + size does not shrink. + "if_block_reduction" will revoke if the number of 2 kB blocks does + not shrink. + "used=..." is ignored. Command -status shows it with the number of + files which currently have the filter applied. + Examples: + -external_filter bzip2 suffix=.bz2:if_block_reduction \ + /usr/bin/bzip2 -- + -external_filter bunzip2 suffix=.bz2:remove_suffix \ + /usr/bin/bunzip2 -- + +-unregister_filter name + Remove an -external_filter registration. This is only possible if + the filter is not applied to any file in the ISO image. + +-close_filter_list + 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 xorriso. By + default they are banned if xorriso runs under setuid permission. + +-set_filter name iso_rr_path [***] + Apply an -external_filter or a built-in filter to the given data + files in the ISO image. If the filter suffix is not empty , then + it will be applied to the file name. Renaming only happens if the + filter really gets attached and is not revoked by its options. By + default files which already bear the suffix will not get filtered. + The others will get the suffix appended to their names. If the + filter has option "remove_suffix", then the filter will only be + applied if the suffix is present and can be removed. Name + oversize or collision caused by suffix change will prevent + filtering. + With most filter types this command will immediately run the + filter once for each file in order to determine the output size. + Content reading operations like -extract , -compare and image + generation will perform further filter runs and deliver filtered + content. + At image generation time the filter output must still be the same + as the output from the first run. Filtering for image generation + does not happen with files from the loaded ISO image if the write + method of growing is in effect (i.e -indev and -outdev are + identical). + The reserved filter name "--remove-all-filters" revokes filtering. + This will revoke eventual suffix renamings as well. Use + "--remove-all-filters+" to prevent any suffix renaming. + +-set_filter_r name iso_rr_path [***] + Like -set_filter but affecting all data files below eventual + directories.  -File: xorriso.info, Node: Writing, Next: SetInsert, Prev: Manipulation, Up: Options +File: xorriso.info, Node: Writing, Next: SetWrite, Prev: Filter, Up: Options -9.4 Writing the result, drive control +9.8 Writing the result, drive control ===================================== (see also paragraph about settings below) +-rollback + Discard the manipulated ISO image and reload it from -indev. (Use + -rollback_end if immediate program end is desired.) + -commit Perform the write operation. Afterwards eventually make the -outdev the new -dev and load the image from there. Switch to @@ -1493,186 +1692,17 @@ File: xorriso.info, Node: Writing, Next: SetInsert, Prev: Manipulation, Up: "(current)".  -File: xorriso.info, Node: SetInsert, Next: SetWrite, Prev: Writing, Up: Options +File: xorriso.info, Node: SetWrite, Next: Bootable, Prev: Writing, Up: Options -9.5 Settings for file insertion -=============================== - --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: - -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 - --. You need quite a new Linux kernel to read correctly the final - bytes of a file >= 4g if its size is not aligned to 2048 byte - blocks. - xorriso's own data read capabilities are not affected by eventual - operating system size limits. They apply to mounting only. - Nevertheless, the target filesystem of an -extract must be able to - take the file size. - --not_mgt code[:code[...]] - Control the behavior of the exclusion lists. - Exclusion processing happens before disk_paths get mapped to the - ISO image and before disk files get compared with image files. - The absolute disk path of the source is matched against the - -not_paths list. The leafname of the disk path is matched against - the patterns in the -not_leaf list. If a match is detected then - the disk path will not be regarded as an existing file and not be - added to the ISO image. - Several codes are defined. The _on/_off settings persist until - they are revoked by their_off/_on counterparts. - "erase" empties the lists which were accumulated by -not_paths and - -not_leaf. - "reset" is like "erase" but also re-installs default behavior. - "off" disables exclusion processing temporarily without - invalidating the lists and settings. - "on" re-enables exclusion processing. - "param_off" applies exclusion processing only to paths below - disk_path parameter of commands. I.e. explicitly given disk_paths - are exempted from exclusion processing. - "param_on" applies exclusion processing to command parameters as - well as to files below such parameters. - "subtree_off" with "param_on" excludes parameter paths only if they - match a -not_paths item exactly. - "subtree_on" additionally excludes parameter paths which lead to a - file address below any -not_paths item. - "ignore_off" treats excluded disk files as if they were missing. - I.e. they get reported with -compare and deleted from the image - with -update. - "ignore_on" keeps excluded files out of -compare or -update - activities. - --not_paths disk_path [***] - Add the given paths to the list of excluded absolute disk paths. - If a given path is relative, then the current -cdx is prepended to - form an absolute path. Eventual pattern matching happens at - definition time and not when exclusion checks are made. - (Do not forget to end the list of disk_paths by "--") - --not_leaf pattern - Add a single shell parser style pattern to the list of exclusions - for disk leafnames. These patterns are evaluated when the - exclusion checks are made. - --not_list disk_path - Read lines from disk_path and use each of them either as - -not_paths argument, if they contain a / character, or as - -not_leaf pattern. - --quoted_not_list disk_path - Like -not_list but with quoted input reading rules. Each word is - handled as one argument for -not_paths resp. -not_leaf. - --follow occasion[:occasion[...]] - Enable or disable resolution of symbolic links and mountpoints - under disk_paths. This applies to actions -add, -du*x, -ls*x, - -findx, and to -disk_pattern expansion. - There are two kinds of follow decisison to be made: - "link" is the hop from a symbolic link to its target file object. - If enabled then symbolic links are handled as their target file - objects, else symbolic links are handled as themselves. - "mount" is the hop from one filesystem to another subordinate - filesystem. If enabled then mountpoint directories are handled as - any other directory, else mountpoints are handled as empty - directories if they are encountered in directory tree traversals. - Less general than above occasions: - "pattern" is mount and link hopping, but only during -disk_pattern - expansion. - "param" is link hopping for parameter words (after eventual - pattern expansion). If enabled then -ls*x will show the link - targets rather than the links themselves. -du*x, -findx, and -add - will process the link targets but not follow links in an eventual - directory tree below the targets (unless "link" is enabled). - Occasions can be combined in a colon separated list. All occasions - mentioned in the list will then lead to a positive follow decision. - "off" prevents any positive follow decision. Use it if no other - occasion applies. - Shortcuts: - "default" is equivalent to "pattern:mount:limit=100". - "on" always decides positive. Equivalent to "link:mount". - - Not an occasion but an optional setting is: - "limit=" which sets the maximum number of link hops. A - link hop consists of a sequence of symbolic links and a final - target of different type. Nevertheless those hops can loop. - Example: - $ ln -s .. uploop - Link hopping has a built-in loop detection which stops hopping at - the first repetition of a link target. Then the repeated link is - handled as itself and not as its target. Regrettably one can - construct link networks which cause exponential workload before - their loops get detected. The number given with "limit=" can curb - this workload at the risk of truncating an intentional sequence of - link hops. - --pathspecs "on"|"off" - Control parameter interpretation with xorriso actions -add and - -path_list. - "on" enables pathspecs of the form *target=source* like with - program mkisofs -graft-points. It also disables -disk_pattern - expansion for command -add. - "off" disables pathspecs of the form target=source and eventually - enables -disk_pattern expansion. - --overwrite "on"|"nondir"|"off" - Allow or disallow to overwrite existing files in the ISO image by - files with the same name. - With setting "off", name collisions cause FAILURE events. With - setting "nondir", only directories are protected by such events, - other existing file types get treated with -rm before the new file - gets added. Setting "on" allows automatic -rm_r. I.e. a - non-directory can replace an existing directory and all its - subordinates. - If restoring of files is enabled, then the overwrite rule applies - to the target file objects on disk as well, but "on" is downgraded - to "nondir". - --split_size number["k"|"m"] - Set the threshold for automatic splitting of regular files. Such - splitting maps a large disk file onto a ISO directory with several - part files in it. This is necessary if the size of the disk file - exceeds -file_size_limit. Older operating systems can handle - files in mounted ISO 9660 filesystems only if they are smaller - than 2 GiB resp. 4 GiB. - Default is 0 which will exclude files larger than -file_size_limit - by a FAILURE event. A well tested -split_size is 2047m. Sizes - above -file_size_limit are not permissible. - While option -split_size is set larger than 0 such a directory - with split file pieces will be recognized and handled like a - regular file by options -compare* , -update*, and in overwrite - situations. There are -ossirox options "concat_split_on" and - "concat_split_off" which control the handling when files get - restored to disk. - In order to be recognizable, the names of the part files have to - describe the splitting by 5 numbers: - part_number,total_parts,byte_offset,byte_count,disk_file_size - which are embedded in the following text form: - part_#_of_#_at_#_with_#_of_# - Scaling characters like "m" or "k" are taken into respect. All - digits are interpreted as decimal, even if leading zeros are - present. - E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 - No other files are allowed in the directory. All parts have to be - present and their numbers have to be plausible. E.g. byte_count - must be valid as -cut_out argument and their contents may not - overlap. - - -File: xorriso.info, Node: SetWrite, Next: Bootable, Prev: SetInsert, Up: Options - -9.6 Settings for result writing +9.9 Settings for result writing =============================== Rock Ridge info will be generated by the program unconditionally. ACLs will be written according to the setting of option -acl. -joliet "on"|"off" - If enabled by "on", generate Joliet info additional to Rock Ridge - info. + If enabled by "on", generate Joliet tree additional to ISO 9660 + + Rock Ridge tree. -compliance rule[:rule...] Adjust the compliance to specifications of ISO 9660 and its @@ -1850,8 +1880,8 @@ will be written according to the setting of option -acl.  File: xorriso.info, Node: Bootable, Next: Charset, Prev: SetWrite, Up: Options -9.7 El Torito bootable ISO images -================================= +9.10 El Torito bootable ISO images +================================== Contrary to published specifications many BIOSes will load an El Torito object from the first session on media and not from the last one, which @@ -1919,8 +1949,8 @@ unless one can assume overwriteable media.  File: xorriso.info, Node: Charset, Next: Exception, Prev: Bootable, Up: Options -9.8 Character sets -================== +9.11 Character sets +=================== File names are strings of non-zero bytes with 8 bit each. Unfortunately the same byte string may appear as different peculiar national @@ -1971,8 +2001,8 @@ display on your terminal.  File: xorriso.info, Node: Exception, Next: DialogCtl, Prev: Charset, Up: Options -9.9 Exception processing -======================== +9.12 Exception processing +========================= Since the tasks of xorriso are manifold and prone to external influence, there may arise the need for xorriso to report and handle @@ -2060,7 +2090,7 @@ failed unexpectedly.  File: xorriso.info, Node: DialogCtl, Next: Inquiry, Prev: Exception, Up: Options -9.10 Dialog mode control +9.13 Dialog mode control ======================== -dialog "on"|"off"|"single_line" @@ -2111,7 +2141,7 @@ File: xorriso.info, Node: DialogCtl, Next: Inquiry, Prev: Exception, Up: Opt  File: xorriso.info, Node: Inquiry, Next: Navigate, Prev: DialogCtl, Up: Options -9.11 Drive and media related inquiry actions +9.14 Drive and media related inquiry actions ============================================ -devices @@ -2194,7 +2224,7 @@ File: xorriso.info, Node: Inquiry, Next: Navigate, Prev: DialogCtl, Up: Opti  File: xorriso.info, Node: Navigate, Next: Verify, Prev: Inquiry, Up: Options -9.12 Navigation in ISO image and disk filesystem +9.15 Navigation in ISO image and disk filesystem ================================================ -cd iso_rr_path @@ -2364,7 +2394,7 @@ File: xorriso.info, Node: Navigate, Next: Verify, Prev: Inquiry, Up: Options  File: xorriso.info, Node: Verify, Next: Restore, Prev: Navigate, Up: Options -9.13 Evaluation of readability and recovery +9.16 Evaluation of readability and recovery =========================================== It is not uncommon that optical media produce read errors. The reasons @@ -2505,7 +2535,7 @@ transmission errors. sets the number of bytes to be read in one read operation. This gets rounded down to full blocks of 2048 bytes. 0 means automatic size. - + -check_md5 severity iso_rr_path [***] Compare the data content of the given files in the loaded image with their recorded MD5 checksums, if there are any. In case of @@ -2527,7 +2557,7 @@ transmission errors.  File: xorriso.info, Node: Restore, Next: Emulation, Prev: Verify, Up: Options -9.14 osirrox ISO-to-disk restore options +9.17 osirrox ISO-to-disk restore options ======================================== Normally xorriso only writes to disk files which were given as stdio: @@ -2656,7 +2686,7 @@ The directory permissions on disk have to allow rwx.  File: xorriso.info, Node: Emulation, Next: Scripting, Prev: Restore, Up: Options -9.15 Command compatibility emulations (cdrtools) +9.18 Command compatibility emulations (cdrtools) ================================================ Writing of ISO 9660 on CD is traditionally done by program mkisofs as @@ -2770,7 +2800,7 @@ programs trigger comparable actions.  File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Options -9.16 Scripting, dialog and program control features +9.19 Scripting, dialog and program control features =================================================== -no_rc @@ -2889,7 +2919,10 @@ File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Op is recognized that way. -end - End program immediately + End program after writing eventually pending changes. + +-rollback_end + Discard pending changes. End program immediately. # any text Only in dialog or file execution mode, and only as first @@ -2897,9 +2930,9 @@ File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Op store it in history.  -File: xorriso.info, Node: Frontend, Prev: Scripting, Up: Options +File: xorriso.info, Node: Frontend, Next: ExDevices, Prev: Scripting, Up: Options -9.17 Support for frontend programs via stdin and stdout +9.20 Support for frontend programs via stdin and stdout ======================================================= -pkt_output "on"|"off" @@ -2956,7 +2989,7 @@ File: xorriso.info, Node: Examples, Next: Files, Prev: Options, Up: Top * ExRecovery:: Try to retrieve blocks from a damaged media  -File: xorriso.info, Node: ExDevices, Next: ExCreate, Prev: Examples, Up: Examples +File: xorriso.info, Node: ExDevices, Next: ExCreate, Prev: Frontend, Up: Examples 10.1 As superuser learn about available drives ============================================== @@ -3466,58 +3499,481 @@ File: xorriso.info, Node: Index, Prev: Legal, Up: Top 14 Index ******** +* Menu: + +* CommandIdx:: Alphabetic Command List +* ConceptIdx:: Alphabetic List of Concepts and Objects + + +File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Index, Up: Index + +14.1 Alphabetic Command List +============================ + [index] * Menu: +* # starts a comment line: Scripting. (line 128) +* -abort_on controls abort on error: Exception. (line 27) +* -acl controls handling of ACLs: Loading. (line 128) +* -add inserts one or more paths: Insert. (line 42) +* -add_plainly inserts one or more paths: Insert. (line 61) +* -alter_date sets timestamps in ISO image: Manip. (line 146) +* -alter_date_r sets timestamps in ISO image: Manip. (line 166) +* -application_id sets application id: SetWrite. (line 82) +* -as emulates mkisofs or cdrecord: Emulation. (line 13) +* -assert_volid rejects undesired images: Loading. (line 65) +* -auto_charset learns character set from image: Loading. (line 80) +* -backslash_codes enables backslash conversion: Scripting. (line 45) +* -ban_stdio_write demands real drive: Loading. (line 225) +* -blank erases media: Writing. (line 45) +* -boot_image controls bootability: Bootable. (line 20) +* -calm_drive reduces drive activity: Loading. (line 214) +* -cd sets working directory in ISO: Navigate. (line 7) +* -cdx sets working directory on disk: Navigate. (line 16) +* -charset sets input/output character set: Charset. (line 43) +* -check_md5 verifies file checksum: Verify. (line 144) +* -check_md5_r verifies file tree checksums: Verify. (line 160) +* -check_media reads media block by block: Verify. (line 21) +* -check_media_defaults sets -check_media options: Verify. (line 40) +* -chgrp sets group in ISO image: Manip. (line 50) +* -chgrp_r sets group in ISO image: Manip. (line 55) +* -chmod sets permissions in ISO image: Manip. (line 58) +* -chmod_r sets permissions in ISO image: Manip. (line 70) +* -chown sets ownership in ISO image: Manip. (line 42) +* -chown_r sets ownership in ISO image: Manip. (line 47) +* -close controls media closing: SetWrite. (line 172) +* -close_filter_list bans filter registration: Filter. (line 52) +* -commit writes pending ISO image: Writing. (line 13) +* -commit_eject writes and ejects: Writing. (line 40) +* -compare reports ISO/disk differences: Navigate. (line 130) +* -compare_l reports ISO/disk differences: Navigate. (line 148) +* -compare_r reports ISO/disk differences: Navigate. (line 143) +* -compliance controls standard compliance: SetWrite. (line 14) +* -cp_rx copies file trees to disk: Restore. (line 104) +* -cpax copies files to disk: Restore. (line 100) +* -cpr inserts like with cp -r: Insert. (line 152) +* -cpx copies files to disk: Restore. (line 88) +* -cut_out inserts piece of data file: Insert. (line 126) +* -dev aquires one drive for input and output: AqDrive. (line 10) +* -devices gets list of drives: Inquiry. (line 7) +* -dialog enables dialog mode: DialogCtl. (line 7) +* -disk_dev_ino fast incremental backup: Loading. (line 168) +* -disk_pattern controls pattern expansion: Insert. (line 31) +* -drive_class controls drive accessability: Loading. (line 35) +* -du show directory size in ISO image: Navigate. (line 84) +* -dummy controls write simulation: SetWrite. (line 161) +* -dus show directory size in ISO image: Navigate. (line 88) +* -dusx show directory size on disk: Navigate. (line 97) +* -dux show directory size on disk: Navigate. (line 92) +* -dvd_obs set write block size: SetWrite. (line 148) +* -eject ejects drive tray: Writing. (line 36) +* -end writes pending session and ends program: Scripting. (line 122) +* -errfile_log logs problematic disk files: Scripting. (line 84) +* -error_behavior controls error workarounds: Exception. (line 69) +* -external_filter registers data filter: Filter. (line 20) +* -external_filter unregisters data filter: Filter. (line 48) +* -extract copies file tree to disk: Restore. (line 56) +* -extract_cut copies file piece to disk: Restore. (line 77) +* -extract_l copies files to disk: Restore. (line 72) +* -extract_single copies file to disk: Restore. (line 68) +* -file_size_limit limits data file size: SetInsert. (line 7) +* -find traverses and alters ISO tree: CmdFind. (line 8) +* -findx traverses disk tree: Navigate. (line 101) +* -follow softlinks and mount points: SetInsert. (line 76) +* -for_backup -acl,-xattr,-hardlinks,-md5: Loading. (line 163) +* -format formats media: Writing. (line 69) +* -fs sets size of fifo: SetWrite. (line 165) +* -getfacl shows ACL in ISO image: Navigate. (line 65) +* -getfacl_r shows ACL in ISO image: Navigate. (line 72) +* -getfattr shows xattr in ISO image: Navigate. (line 76) +* -getfattr_r shows xattr in ISO image: Navigate. (line 80) +* -gid sets global ownership: SetWrite. (line 105) +* -grow_blindly overides next writeable address: AqDrive. (line 44) +* -hardlinks controls handling of hard links: Loading. (line 91) +* -help prints help text: Scripting. (line 16) +* -history brings text into readline history: Scripting. (line 22) +* -in_charset sets input character set: Loading. (line 73) +* -indev aquires a drive for input: AqDrive. (line 22) +* -iso_rr_pattern controls pattern expansion: Manip. (line 10) +* -joliet enables production of Joliet tree: SetWrite. (line 10) +* -list_delimiter replaces '--': Scripting. (line 38) +* -list_formats lists available formats: Writing. (line 107) +* -list_profiles lists supported media: Writing. (line 119) +* -load addresses a particular session as input: Loading. (line 11) +* -local_charset sets terminal character set: Charset. (line 47) +* -logfile logs output channels to file: Frontend. (line 20) +* -ls lists files in ISO image: Navigate. (line 26) +* -lsd lists files in ISO image: Navigate. (line 34) +* -lsdl lists files in ISO image: Navigate. (line 42) +* -lsdlx lists files on disk: Navigate. (line 61) +* -lsdx lists files on disk: Navigate. (line 53) +* -lsl lists files in ISO image: Navigate. (line 38) +* -lslx lists files on disk: Navigate. (line 57) +* -lsx lists files on disk: Navigate. (line 46) +* -map inserts path: Insert. (line 85) +* -map_l inserts paths from disk file: Insert. (line 94) +* -map_single inserts path: Insert. (line 90) +* -mark sets synchronizing message: Frontend. (line 25) +* -md5 controls handling of MD5 sums: Loading. (line 141) +* -mkdir creates ISO directory: Insert. (line 166) +* -mount issues mount command for ISO session: Restore. (line 122) +* -mount_cmd composes mount command line: Inquiry. (line 31) +* -mount_cmd controls mount command: Inquiry. (line 47) +* -mv renames file in ISO image: Manip. (line 35) +* -no_rc disables startup files: Scripting. (line 7) +* -not_leaf sets exclusion pattern: SetInsert. (line 62) +* -not_list sets exclusions from disk file: SetInsert. (line 67) +* -not_mgt controls file exclusion: SetInsert. (line 23) +* -not_paths sets absolute exclusion paths: SetInsert. (line 55) +* -options_from_file reads commands from file: Scripting. (line 12) +* -osirrox enables ISO-to-disk copying: Restore. (line 18) +* -out_charset sets output character set: SetWrite. (line 95) +* -outdev aquires a drive for output: AqDrive. (line 29) +* -overwrite enables overwriting in ISO: SetInsert. (line 127) +* -pacifier controls pacifier text form: Emulation. (line 94) +* -padding sets amount of image padding: SetWrite. (line 178) +* -page set terminal geometry: DialogCtl. (line 15) +* -paste_in copies file into disk file: Restore. (line 117) +* -path_list inserts paths from disk file: Insert. (line 75) +* -pathspecs sets meaning of = with -add: SetInsert. (line 118) +* -pkt_output consolidates text output: Frontend. (line 7) +* -print prints text line: Scripting. (line 77) +* -print_size predicts image size: Inquiry. (line 69) +* -prog sets program name: Frontend. (line 29) +* -prog_help prints help text: Frontend. (line 32) +* -prompt prompts for enter key: Scripting. (line 80) +* -publisher sets publisher id: SetWrite. (line 76) +* -pvd_info shows image id strings: Inquiry. (line 78) +* -pwd tells working directory in ISO: Navigate. (line 20) +* -pwdx tells working directory on disk: Navigate. (line 23) +* -quoted_not_list sets exclusions: SetInsert. (line 72) +* -quoted_path_list inserts paths from disk file: Insert. (line 80) +* -reassure enables confirmation question: DialogCtl. (line 28) +* -report_about controls verbosity: Exception. (line 55) +* -return_with controls exit value: Exception. (line 39) +* -rm deletes files from ISO image: Manip. (line 21) +* -rm_r deletes trees from ISO image: Manip. (line 28) +* -rmdir deletes ISO directory: Manip. (line 32) +* -rollback discards pending changes: Writing. (line 9) +* -rollback_end ends program without writing: Scripting. (line 125) +* -rom_toc_scan searches for sessions: Loading. (line 189) +* -scdbackup_tag enables scdbackup checksum tag: Emulation. (line 104) +* -scsi_log reports SCSI commands: Scripting. (line 113) +* -session_log logs written sessions: Scripting. (line 104) +* -session_string composes session info line: Inquiry. (line 56) +* -set_filter applies filter to file: Filter. (line 59) +* -set_filter_r applies filter to file tree: Filter. (line 84) +* -setfacl sets ACL in ISO image: Manip. (line 73) +* -setfacl_list sets ACL in ISO image: Manip. (line 100) +* -setfacl_r sets ACL in ISO image: Manip. (line 97) +* -setfattr sets xattr in ISO image: Manip. (line 110) +* -setfattr_list sets xattr in ISO image: Manip. (line 126) +* -setfattr_r sets xattr in ISO image: Manip. (line 123) +* -show_stream shows data source and filters: Navigate. (line 153) +* -show_stream_r shows data source and filters: Navigate. (line 168) +* -speed set write speed: SetWrite. (line 121) +* -split_size enables large file splitting: SetInsert. (line 140) +* -status shows current settings: Scripting. (line 25) +* -status_history_max curbs -status history: Scripting. (line 34) +* -stdio_sync controls stdio buffer: SetWrite. (line 155) +* -stream_recording controls defect management: SetWrite. (line 136) +* -system_id sets system id: SetWrite. (line 88) +* -tell_media_space reports free space: Inquiry. (line 74) +* -temp_mem_limit curbs memory consumption: Scripting. (line 70) +* -toc shows list of sessions: Inquiry. (line 18) +* -uid sets global ownership: SetWrite. (line 101) +* -update inserts path if different: Insert. (line 99) +* -update_l inserts paths if different: Insert. (line 121) +* -update_r inserts paths if different: Insert. (line 110) +* -use_readline enables readline for dialog: DialogCtl. (line 24) +* -version prints help text: Scripting. (line 19) +* -volid sets volume id: SetWrite. (line 52) +* -volset_id sets volume set id: SetWrite. (line 71) +* -xattr controls handling of xattr (EA): Loading. (line 136) +* -zisofs controls zisofs production: SetWrite. (line 109) + + +File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Index + +14.2 Alphabetic List of Concepts and Objects +============================================ + +[index] +* Menu: + +* ACL, _definiton: Extras. (line 35) +* ACL, control handling, -acl: Loading. (line 128) +* ACL, set in ISO image, -setfacl: Manip. (line 73) +* ACL, set in ISO image, -setfacl_list: Manip. (line 100) +* ACL, set in ISO image, -setfacl_r: Manip. (line 97) +* ACL, show in ISO image, -getfacl: Navigate. (line 65) +* ACL, show in ISO image, -getfacl_r: Navigate. (line 72) +* Appendable media, _definition: Media. (line 34) +* Backslash Interpretation, _definition: Processing. (line 49) +* Backup, enable fast incremental, -disk_dev_ino: Loading. (line 168) +* Backup, enable features, -for_backup: Loading. (line 163) +* Backup, scdbackup checksum tag, -scdbackup: Emulation. (line 104) +* Blank media, _definition: Media. (line 25) +* Blind growing, _definition: Methods. (line 40) +* Bootability, control, -boot_image: Bootable. (line 20) +* cdrecord, Emulation: Emulation. (line 61) +* Character Set, _definition: Charset. (line 6) +* Character Set, for input, -in_charset: Loading. (line 73) +* Character Set, for input/output, -charset: Charset. (line 43) +* Character Set, for output, -out_charset: SetWrite. (line 95) +* Character set, learn from image, -auto_charset: Loading. (line 80) +* Character Set, of terminal, -local_charset: Charset. (line 47) +* Closed media, _definition: Media. (line 39) +* Comment, #: Scripting. (line 128) +* Create, new ISO image, _definiton: Methods. (line 6) +* Delete, from ISO image, -rm: Manip. (line 21) +* Delete, from ISO image, -rm_r: Manip. (line 28) +* Delete, ISO directory, -rmdir: Manip. (line 32) +* Dialog, bring text into history, -history: Scripting. (line 22) +* Dialog, confirmation question, -reassure: DialogCtl. (line 28) +* Dialog, enable dialog mode, -dialog: DialogCtl. (line 7) +* Dialog, line editing, -use_readline: DialogCtl. (line 24) +* Dialog, terminal geometry, -page: DialogCtl. (line 15) +* Directory, create, -mkdir: Insert. (line 166) +* Directory, delete, -rmdir: Manip. (line 32) +* disk_path, _definition: Insert. (line 6) +* Drive, _definiton: Drives. (line 6) +* Drive, accessability, -drive_class: Loading. (line 35) +* Drive, demand real MMC, -ban_stdio_write: Loading. (line 225) +* Drive, eject tray, -eject: Writing. (line 36) +* Drive, for input and output, -dev: AqDrive. (line 10) +* Drive, for input, -indev: AqDrive. (line 22) +* Drive, for output, -outdev: AqDrive. (line 29) +* Drive, get drive list, -devices: Inquiry. (line 7) +* Drive, list supported media, -list_profiles: Writing. (line 119) +* Drive, reduce activity, -calm_drive: Loading. (line 214) +* Drive, report SCSI commands, -scsi_log: Scripting. (line 113) +* Drive, write and eject, -commit_eject: Writing. (line 40) +* El Torito, _definiton: Extras. (line 19) +* Emulation, -as: Emulation. (line 13) +* Emulation, cdrecord, -as: Emulation. (line 61) +* Emulation, mkisofs, -as: Emulation. (line 16) +* Emulation, pacifier form, -pacifier: Emulation. (line 94) +* Examples: Examples. (line 6) +* Filter, _definition: Filter. (line 6) +* Filter, apply to file tree, -set_filter_r: Filter. (line 84) +* Filter, apply to file, -set_filter: Filter. (line 59) +* Filter, ban registration, -close_filter_list: Filter. (line 52) +* Filter, register, -external_filter: Filter. (line 20) +* Filter, show chain, -show_stream: Navigate. (line 153) +* Filter, show chains of tree, -show_stream_r: Navigate. (line 168) +* Filter, unregister, -unregister_filter: Filter. (line 48) +* Filter, zisofs parameters, -zisofs: SetWrite. (line 109) +* Group, global in ISO image, -gid: SetWrite. (line 105) +* Group, in ISO image, -chgrp: Manip. (line 50) +* Group, in ISO image, -chgrp_r: Manip. (line 55) +* Growing, _definition: Methods. (line 19) +* Hard links, control handling, -hardlinks: Loading. (line 91) +* Image, _definition: Model. (line 9) +* Image, demand volume id, -assert_volid: Loading. (line 65) +* Image, discard pending changes, -rollback: Writing. (line 9) +* Image, set application id, -application_id: SetWrite. (line 82) +* Image, set publisher id, -publisher: SetWrite. (line 76) +* Image, set system id, -system_id: SetWrite. (line 88) +* Image, set volume id, -volid: SetWrite. (line 52) +* Image, set volume set id, -volset_id: SetWrite. (line 71) +* Image, show id strings, -pvd_info: Inquiry. (line 78) +* Insert, enable overwriting, -overwrite: SetInsert. (line 127) +* Insert, file exclusion absolute, -not_paths: SetInsert. (line 55) +* Insert, file exclusion from file, -not_list: SetInsert. (line 67) +* Insert, file exclusion pattern, -not_leaf: SetInsert. (line 62) +* Insert, file exclusion, -not_mgt: SetInsert. (line 23) +* Insert, file exclusion, -quoted_not_list: SetInsert. (line 72) +* Insert, if different, -update: Insert. (line 99) +* Insert, if different, -update_l: Insert. (line 121) +* Insert, if different, -update_r: Insert. (line 110) +* Insert, large file splitting, -split_size: SetInsert. (line 140) +* Insert, limit data file size, -file_size_limit: SetInsert. (line 7) +* Insert, links or mount points, -follow: SetInsert. (line 76) +* Insert, meaning of = with -add, -pathspecs: SetInsert. (line 118) +* Insert, non-dashed arguments, -add_plainly: Insert. (line 61) +* Insert, path, -map: Insert. (line 85) +* Insert, path, -map_single: Insert. (line 90) +* Insert, paths from disk file, -map_l: Insert. (line 94) +* Insert, paths from disk file, -path_list: Insert. (line 75) +* Insert, paths from disk file, -quoted_path_list: Insert. (line 80) +* Insert, paths, -cpr: Insert. (line 152) +* Insert, pathspecs, -add: Insert. (line 42) +* Insert, piece of data file, -cut_out: Insert. (line 126) +* iso_rr_path, _definition: Insert. (line 7) +* List delimiter, _definiton: Processing. (line 8) +* MD5, control handling, -md5: Loading. (line 141) +* Media, erase, -blank: Writing. (line 45) +* Media, format, -format: Writing. (line 69) +* Media, list formats, -list_formats: Writing. (line 107) +* mkisofs, Emulation: Emulation. (line 16) +* Modifying, _definition: Methods. (line 27) +* Multi-session media, _definition: Media. (line 7) +* Multi-session, _definition: Model. (line 18) +* Navigate, directory size in ISO image, -du: Navigate. (line 84) +* Navigate, directory size in ISO image, -dus: Navigate. (line 88) +* Navigate, directory size in on disk, -dusx: Navigate. (line 97) +* Navigate, directory size in on disk, -dux: Navigate. (line 92) +* Navigate, list disk files, -lsdlx: Navigate. (line 61) +* Navigate, list disk files, -lsdx: Navigate. (line 53) +* Navigate, list disk files, -lslx: Navigate. (line 57) +* Navigate, list disk files, -lsx: Navigate. (line 46) +* Navigate, list ISO files, -ls: Navigate. (line 26) +* Navigate, list ISO files, -lsd: Navigate. (line 34) +* Navigate, list ISO files, -lsdl: Navigate. (line 42) +* Navigate, list ISO files, -lsl: Navigate. (line 38) +* Navigate, set disk working directory, -cdx: Navigate. (line 16) +* Navigate, set ISO working directory, -cd: Navigate. (line 7) +* Navigate, tell disk working directory, -pwdx: Navigate. (line 23) +* Navigate, tell ISO working directory, -pwd: Navigate. (line 20) +* Next writeable address, -grow_blindly: AqDrive. (line 44) +* Overwriteable media, _definition: Media. (line 10) +* Ownership, global in ISO image, -uid: SetWrite. (line 101) +* Ownership, in ISO image, -chown: Manip. (line 42) +* Ownership, in ISO image, -chown_r: Manip. (line 47) +* Pathspec, _definition: SetInsert. (line 120) +* Pattern expansion, _definition: Processing. (line 22) +* Pattern expansion, for disk paths, -disk_pattern: Insert. (line 31) +* Pattern expansion, for ISO paths, -iso_rr_pattern: Manip. (line 10) +* Permissions, in ISO image, -chmod: Manip. (line 58) +* Permissions, in ISO image, -chmod_r: Manip. (line 70) +* Process, consolidate text output, -pkt_output: Frontend. (line 7) +* Process, control abort on error, -abort_on: Exception. (line 27) +* Process, control exit value, -return_with: Exception. (line 39) +* Process, control verbosity, -report_about: Exception. (line 55) +* Process, disable startup files, -no_rc: Scripting. (line 7) +* Process, end program and write, -end: Scripting. (line 122) +* Process, end program, no writing, -rollback_end: Scripting. (line 125) +* Process, error workarounds, -error_behavior: Exception. (line 69) +* Process, log output channels to file, -logfile: Frontend. (line 20) +* Process, read command file, -options_from_file: Scripting. (line 12) +* Process, set synchronizing message, -mark: Frontend. (line 25) +* Program, backslash conversion, -backslash_codes: Scripting. (line 45) +* Program, curb memory, -temp_mem_limit: Scripting. (line 70) +* Program, end and write, -end: Scripting. (line 122) +* Program, end without writing, -rollback_end: Scripting. (line 125) +* Program, print help text, -help: Scripting. (line 16) +* Program, print help text, -prog_help: Frontend. (line 32) +* Program, print text line, -print: Scripting. (line 77) +* Program, print version, -version: Scripting. (line 19) +* Program, prompt for enter key, -prompt: Scripting. (line 80) +* Program, replace --, -list_delimiter: Scripting. (line 38) +* Program, set name, -prog: Frontend. (line 29) +* Program, show current settings, -status: Scripting. (line 25) +* Program, status history, -status_history_max: Scripting. (line 34) +* Quoted input, _definiton: Processing. (line 43) +* Recovery, retrieve blocks, -check_media: Verify. (line 21) +* Rename, in ISO image, -mv: Manip. (line 35) +* Restore, copy file into disk file, -paste_in: Restore. (line 117) +* Restore, copy file piece to disk, -extract_cut: Restore. (line 77) +* Restore, copy file to disk, -extract_single: Restore. (line 68) +* Restore, copy file tree to disk, -extract: Restore. (line 56) +* Restore, copy file trees to disk, -cp_rx: Restore. (line 104) +* Restore, copy files to disk, -cpax: Restore. (line 100) +* Restore, copy files to disk, -cpx: Restore. (line 88) +* Restore, copy files to disk, -extract_l: Restore. (line 72) +* Restore, enable ISO-to-disk, -osirrox: Restore. (line 18) +* Rock Ridge, _definiton: Extras. (line 6) +* Session, _definition: Model. (line 6) +* Session, info string, -session_string: Inquiry. (line 56) +* Session, issue mount command, -mount: Restore. (line 122) +* Session, log when written, -session_log: Scripting. (line 104) +* Session, mount command line, -mount_cmd: Inquiry. (line 31) +* Session, mount parameters, -mount_opts: Inquiry. (line 47) +* Session, select as input, -load: Loading. (line 11) +* Table-of-content, search sessions, -rom_toc_scan: Loading. (line 189) +* Table-of-content, show, -toc: Inquiry. (line 18) +* Timestamps, set in ISO image, -alter_date: Manip. (line 146) +* Timestamps, set in ISO image, -alter_date_r: Manip. (line 166) +* Tree, disk, traverse, -findx: Navigate. (line 101) +* Tree, ISO, traverse and alter, -find: CmdFind. (line 8) +* Verify, check blocks, -check_media: Verify. (line 21) +* Verify, compare ISO and disk file, -compare: Navigate. (line 130) +* Verify, compare ISO and disk tree, -compare_r: Navigate. (line 143) +* Verify, compare ISO and disk, -compare_l: Navigate. (line 148) +* Verify, file checksum, -check_md5: Verify. (line 144) +* Verify, file tree checksums, -check_md5_r: Verify. (line 160) +* Verify, preset -check_media, -check_media_defaults: Verify. (line 40) +* Write, block size, -dvd_obs: SetWrite. (line 148) +* Write, bootability, -boot_image: Bootable. (line 20) +* Write, buffer syncing, -stdio_sync: SetWrite. (line 155) +* Write, close media, -close: SetWrite. (line 172) +* Write, compliance to specs, -compliance: SetWrite. (line 14) +* Write, defect management, -stream_recording: SetWrite. (line 136) +* Write, enable Joliet, -joliet: SetWrite. (line 10) +* Write, fifo size, -fs: SetWrite. (line 165) +* Write, free space, -tell_media_space: Inquiry. (line 74) +* Write, log problematic disk files, -errfile_log: Scripting. (line 84) +* Write, log written sessions, -session_log: Scripting. (line 104) +* Write, padding image, -padding: SetWrite. (line 178) +* Write, pending ISO image, -commit: Writing. (line 13) +* Write, predict image size, -print_size: Inquiry. (line 69) +* Write, set speed, -speed: SetWrite. (line 121) +* Write, simulation, -dummy: SetWrite. (line 161) +* xattr, _definiton: Extras. (line 49) +* xattr, control handling, -xattr: Loading. (line 136) +* xattr, set in ISO image, -setfattr: Manip. (line 110) +* xattr, set in ISO image, -setfattr_list: Manip. (line 126) +* xattr, set in ISO image, -setfattr_r: Manip. (line 123) +* xattr, show in ISO image, -getfattr: Navigate. (line 76) +* xattr, show in ISO image, -getfattr_r: Navigate. (line 80) + +  Tag Table: Node: Top290 Node: Overview1112 -Node: Model2996 -Node: Media5876 -Node: Methods8303 -Node: Drives10850 -Node: Extras14116 -Node: Processing17441 -Node: Dialog20639 -Node: Options22296 -Node: AqDrive23702 -Node: Loading26608 -Node: Manipulation39047 -Node: Writing67959 -Node: SetInsert74115 -Node: SetWrite82686 -Node: Bootable91554 -Node: Charset95269 -Node: Exception98021 -Node: DialogCtl102534 -Node: Inquiry104879 -Node: Navigate109019 -Node: Verify116373 -Node: Restore124788 -Node: Emulation131444 -Node: Scripting137550 -Node: Frontend143012 -Node: Examples144195 -Node: ExDevices145364 -Node: ExCreate145846 -Node: ExDialog147120 -Node: ExGrowing148382 -Node: ExModifying149184 -Node: ExBootable149685 -Node: ExCharset150232 -Node: ExPseudo151060 -Node: ExCdrecord151954 -Node: ExMkisofs152269 -Node: ExGrowisofs153272 -Node: ExException154396 -Node: ExTime154850 -Node: ExIncBackup155309 -Node: ExRestore158781 -Node: ExRecovery159750 -Node: Files160315 -Node: Seealso160902 -Node: Legal161426 -Node: Index162343 +Node: Model2980 +Node: Media5860 +Node: Methods8290 +Node: Drives10837 +Node: Extras14103 +Node: Processing17428 +Node: Dialog20924 +Node: Options22581 +Node: AqDrive24149 +Node: Loading27055 +Node: Insert39488 +Node: SetInsert47845 +Node: Manip56412 +Node: CmdFind64288 +Node: Filter72847 +Node: Writing77196 +Node: SetWrite83485 +Node: Bootable92362 +Node: Charset96079 +Node: Exception98833 +Node: DialogCtl103348 +Node: Inquiry105693 +Node: Navigate109833 +Node: Verify117187 +Node: Restore125607 +Node: Emulation132263 +Node: Scripting138369 +Node: Frontend143931 +Node: Examples145132 +Node: ExDevices146301 +Node: ExCreate146783 +Node: ExDialog148057 +Node: ExGrowing149319 +Node: ExModifying150121 +Node: ExBootable150622 +Node: ExCharset151169 +Node: ExPseudo151997 +Node: ExCdrecord152891 +Node: ExMkisofs153206 +Node: ExGrowisofs154209 +Node: ExException155333 +Node: ExTime155787 +Node: ExIncBackup156246 +Node: ExRestore159718 +Node: ExRecovery160687 +Node: Files161252 +Node: Seealso161839 +Node: Legal162363 +Node: Index163280 +Node: CommandIdx163481 +Node: ConceptIdx176715  End Tag Table diff --git a/xorriso/xorriso.texi b/xorriso/xorriso.texi index 0794fd9f..7a1ae2ed 100644 --- a/xorriso/xorriso.texi +++ b/xorriso/xorriso.texi @@ -38,7 +38,7 @@ @c man .\" First parameter, NAME, should be all caps @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection @c man .\" other parameters are allowed: see man(7), man(1) -@c man .TH XORRISO 1 "Mar 17, 2010" +@c man .TH XORRISO 1 "Mar 18, 2010" @c man .\" Please adjust this date whenever revising the manpage. @c man .\" @c man .\" Some roff macros, for reference: @@ -97,7 +97,7 @@ with Rock Ridge extensions. * Legal:: Author, Copyright, Credits * Index:: Index @end menu -@node Overview, Model, top, top +@node Overview, Model, Top, Top @chapter Overview @c man .SH SYNOPSIS @c man .B xorriso @@ -119,7 +119,7 @@ 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 incorporates the libraries of libburnia-project.org . @c man .SS -@unnumberedsec Overview of features +@section Features @c man .B Overview of features: @* Operates on an existing ISO image or creates a new one. @@ -182,10 +182,12 @@ Adjustable thresholds for abort, exit value, and problem reporting. @chapter Session model @c man \fBSession model:\fR @c man .br +@cindex Session, _definition Unlike other filesystems, ISO 9660 is not intended for read-write operation but rather for being generated in a single sweep and being written to media as a @strong{session}. @* +@cindex Image, _definition The data content of the session is called filesystem @strong{image}. @c man .PP @sp 1 @@ -196,6 +198,7 @@ even from regular disk files. FreeBSD mounts ISO images from devices that represent arbitrary media or from regular disk files. @c man .PP @sp 1 +@cindex Multi-session, _definition This session usage model has been extended on CD media by the concept of @strong{multi-session} , which allows to add information to the CD and gives the mount programs @@ -249,10 +252,12 @@ to store intermediate states and to continue with image manipulations. @c man .B Media types and states: There are two families of media in the MMC standard: @* +@cindex Multi-session media, _definition @strong{Multi-session media} are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and unformatted DVD-RW. These media provide a table of content which describes their existing sessions. See option @strong{-toc}. @* +@cindex Overwriteable media, _definition @strong{Overwriteable media} are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW. They allow random write access but do not provide information about their session history. If they contain one or more ISO 9660 sessions and if the @@ -269,6 +274,8 @@ Pipes and other writeable file types are handled as blank multi-session media. These media can assume several states in which they offer different capabilities. @* +@sp 1 +@cindex Blank media, _definition @strong{Blank} media can be written from scratch. They contain no ISO image suitable for xorriso. @* @@ -279,12 +286,16 @@ been marked as blank by xorriso. Action -blank "as_needed" can be used to do this marking on overwriteable media, or to apply eventual mandatory formatting to new media. @* +@sp 1 +@cindex Appendable media, _definition @strong{Appendable} media accept further sessions. Either they are MMC multi-session media in appendable state, or they are overwriteable media which contain an ISO image suitable for xorriso. @* Appendable is the state after writing a session with option -close off. @* +@sp 1 +@cindex Closed media, _definition @strong{Closed} media cannot be written. They may contain an ISO image suitable for xorriso. @* @@ -303,6 +314,7 @@ not even that. Option -rom_toc_scan might or might not help in such cases. @chapter Creating, Growing, Modifying, Blind Growing: @c man .B Creating, Growing, Modifying, Blind Growing: @* +@cindex Create, new ISO image, _definiton A new empty ISO image gets @strong{created} if there is no input drive with a valid ISO 9660 image when the first time an output drive is defined. This is achieved by option -dev on blank media @@ -319,6 +331,7 @@ and output drive determines which write method will be used. They have quite different capabilities and constraints. @c man .PP @sp 1 +@cindex Growing, _definition The method of @strong{growing} adds new data to the existing media. These data comprise of eventual new file content and they override the existing ISO 9660 + Rock Ridge directory tree. It is possible to hide files from @@ -328,6 +341,7 @@ optical media it is quite easy to recover them by mounting older sessions. Growing is achieved by option -dev. @c man .PP @sp 1 +@cindex Modifying, _definition The write method of @strong{modifying} produces compact filesystem images with no outdated files or directory trees. Modifying can write its images to target media which are completely unsuitable for multi-session @@ -344,6 +358,7 @@ if option -grow_blindly is set to its default "off". This is achieved by options -indev and -outdev. @c man .PP @sp 1 +@cindex Blind growing, _definition If option -grow_blindly is set to a non-negative number and if -indev and -outdev are both set to different drives, then @strong{blind growing} is performed. It produces an add-on session which is ready for being written @@ -361,6 +376,7 @@ program is desired. -C $msc1,$msc2 is equivalent to: @chapter Libburn drives @c man .B Libburn drives: @c man .br +@cindex Drive, _definiton Input drive, i.e. source of an existing or empty ISO image, can be any random access readable libburn drive: optical media with readable data, blank optical media, regular files, block devices. @@ -454,6 +470,7 @@ prefix "stdio:" to other paths. @chapter Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr @c man .B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr: @c man .br +@cindex Rock Ridge, _definiton @strong{Rock Ridge} is the name of a set of additional information which enhance an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem @@ -470,6 +487,7 @@ demands a file name length of up to 255 characters and paths of up to 1024 characters. Rock Ridge fulfills this demand. @c man .PP @sp 1 +@cindex El Torito, _definiton An @strong{El Torito} boot record connects a boot image, which is a binary program plus some other files stored in the ISO image, with the bootstrapping facility of @@ -490,6 +508,7 @@ appear as hard disk rather than as CDROM. An MBR does not hamper CDROM booting. The MBR of a follow-up session can get in effect only on overwriteable media. @c man .PP @sp 1 +@cindex ACL, _definiton @strong{ACL} are an advanced way of controlling access permissions to file objects. Neither ISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs has @@ -509,6 +528,7 @@ according to entry "group::". 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 xorriso allows to record and restore pairs which @@ -529,6 +549,7 @@ them. Commands are either actions which happen immediately or settings which influence following actions. So their sequence does matter. @* +@cindex List delimiter, _definiton Commands consist of a command word, followed by zero or more parameter words. If the list of parameter words is of variable length (indicated by "[...]" or "[***]") then it has to be @@ -550,8 +571,15 @@ a command with a fixed list length. It is handled as normal text if it appears among the arguments of such a command. @c man .PP @sp 1 +@cindex Pattern expansion, _definition @strong{Pattern expansion} -is a property of some particular commands and not a general +converts a list of pattern words into a list of existing file addresses. +Eventual unmatched pattern words appear themselves in that result list, though. +@* +Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' +and respects '/' as separator which may only be matched literally. +@* +It is a property of some particular commands and not a general feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern. Commands which eventually use pattern expansion all have variable argument lists which are marked in this man page by "[***]" rather than "[...]". @@ -569,6 +597,7 @@ differs from the usual shell parsers. In xorriso, a quotation mark does not make a pattern symbol literal. @c man .PP @sp 1 +@cindex Quoted input, _definiton @strong{Quoted input} converts whitespace separated text pieces into words. The double quotation mark " and the single quotation mark ' can be used to @@ -576,6 +605,7 @@ enclose whitespace and make it part of words (e.g. of file names). Each mark type can enclose the marks of the other type. A trailing backslash \ outside quotations or an open quotation cause the next input line to be appended. @* +@cindex Backslash Interpretation, _definition Quoted input accepts any ASCII character except NUL (0) as content of quotes. Nevertheless it can be cumbersome for the user to produce those characters at all. Therefore quoted input and program arguments allow optional @@ -655,9 +685,12 @@ inner dashes are interpreted as underscores. @menu * AqDrive:: Aquiring source and target drive * Loading:: Influencing the behavior of image loading -* Manipulation:: File manipulations -* Writing:: Writing the result, drive control +* Insert:: Inserting files into ISO image * SetInsert:: Settings for file insertion +* Manip:: File manipulations +* CmdFind:: Tree traversal command -find +* Filter:: Filters for data file content +* Writing:: Writing the result, drive control * SetWrite:: Settings for result writing * Bootable:: El Torito bootable ISO images * Charset:: Character sets @@ -682,6 +715,8 @@ the behavior of image loading. See next option group. @sp 1 @c man .TP @item -dev address +@kindex -dev aquires one drive for input and output +@cindex Drive, for input and output, -dev Set input and output drive to the same address and load an eventual ISO image. If there is no ISO image then create a blank one. Set the image expansion method to growing. @@ -696,12 +731,16 @@ An empty address string "" gives up the current device without aquiring a new one. @c man .TP @item -indev address +@kindex -indev aquires a drive for input +@cindex Drive, for input, -indev Set input drive and load an eventual ISO image. If the new input drive differs from -outdev then switch from growing to modifying or to blind growing. It depends on the setting of -grow_blindly which of both gets activated. The same rules and restrictions apply as with -dev. @c man .TP @item -outdev address +@kindex -outdev aquires a drive for output +@cindex Drive, for output, -outdev Set output drive and if it differs from the input drive then switch from growing to modifying or to blind growing. Unlike -dev and -indev this action does not load a new ISO image. So it can be performed even if there are pending @@ -719,6 +758,8 @@ An empty address string "" gives up the current output drive without aquiring a new one. No writing is possible without an output drive. @c man .TP @item -grow_blindly "off"|predicted_nwa +@kindex -grow_blindly overides next writeable address +@cindex Next writeable address, -grow_blindly If predicted_nwa is a non-negative number then perform blind growing rather than modifying if -indev and -outdev are set to different drives. "off" or "-1" switch to modifying, which is the default. @@ -735,7 +776,7 @@ begins. The output drive is given up when writing is done. @end table @c man .TP @c man .B Influencing the behavior of image loading: -@node Loading, Manipulation, AqDrive, Options +@node Loading, Insert, AqDrive, Options @section Influencing the behavior of image loading @c man .PP The following options should normally be performed before loading an image @@ -745,6 +786,8 @@ them only after image loading. @sp 1 @c man .TP @item -load entity id +@kindex -load addresses a particular session as input +@cindex Session, select as input, -load Load a particular (possibly outdated) ISO image from -dev or -indev. Usually all available sessions are shown with option -toc. @* @@ -772,6 +815,8 @@ setting is valid for -rollback until next -dev or -indev, where it will be reset to "auto". @c man .TP @item -drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern +@kindex -drive_class controls drive accessability +@cindex Drive, accessability, -drive_class Add a drive path pattern to one of the safety lists or make those lists empty. There are three lists defined which get tested in the following sequence: @* @@ -807,6 +852,8 @@ prevent inadverted mishaps. For reliably blocking access to a device file you have to deny its rw-permissions in the filesystem. @c man .TP @item -assert_volid pattern severity +@kindex -assert_volid rejects undesired images +@cindex Image, demand volume id, -assert_volid 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 (like FAILURE, see -abort_on). An empty search @@ -816,6 +863,8 @@ This option does not hamper the creation of an empty image from blank input media and does not discard an already loaded image. @c man .TP @item -in_charset character_set_name +@kindex -in_charset sets input character set +@cindex Character Set, for input, -in_charset Set the character set from which to convert file names when loading an image. This has eventually to be done before specifying -dev , -indev or -rollback. See paragraph "Character sets" for more explanations. @@ -823,6 +872,8 @@ When loading the written image after -commit the setting of -out_charset will be copied to -in_charset. @c man .TP @item -auto_charset "on"|"off" +@kindex -auto_charset learns character set from image +@cindex Character set, learn from image, -auto_charset Enable or disable recording and interpretation of the output character set name in an xattr attribute of the image root directory. If enabled then an eventual recorded character set name gets used as input character set @@ -834,6 +885,8 @@ to the produced ISO image, check whether the terminal properly displays all intended filenames, especially exotic national characters. @c man .TP @item -hardlinks mode[:mode...] +@kindex -hardlinks controls handling of hard links +@cindex Hard links, control handling, -hardlinks Enable or disable loading and recording of hardlink relations. @* In default mode "off", iso_rr files lose their inode numbers at image load @@ -873,6 +926,8 @@ the resulting image will violate the RRIP-1.10 specs for entry PX in the same way as mkisofs does. @c man .TP @item -acl "on"|"off" +@kindex -acl controls handling of ACLs +@cindex ACL, control handling, -acl Enable or disable processing of ACLs. If enabled, then xorriso will obtain ACLs from disk file objects, store ACLs in the ISO image using the libisofs specific AAIP format, @@ -881,11 +936,15 @@ and restore ACLs to disk files when extracting them from ISO images. See also options -getfacl, -setfacl. @c man .TP @item -xattr "on"|"off" +@kindex -xattr controls handling of xattr (EA) +@cindex xattr, control handling, -xattr Enable or disable processing of xattr attributes in user namespace. If enabled, then xorriso will handle xattr similar to ACL. See also options -getfattr, -setfattr and above paragraph about xattr. @c man .TP @item -md5 "on"|"all"|"off" +@kindex -md5 controls handling of MD5 sums +@cindex MD5, control handling, -md5 Enable or disable processing of MD5 checksums for the overall session and for each single data file. If enabled then images get loaded only if eventual checksums tags of superblock and directory tree match properly. The MD5 @@ -910,11 +969,15 @@ Checksums can be exploited via options -check_md5, -check_md5_r, via find actions get_md5, check_md5, and via -check_media. @c man .TP @item -for_backup +@kindex -for_backup -acl,-xattr,-hardlinks,-md5 +@cindex Backup, enable features, -for_backup Enable all extra features which help to produce or to restore backups with highest fidelity of file properties. Currently this is a shortcut for: -hardlinks on -acl on -xattr on -md5 on. @c man .TP @item -disk_dev_ino "on"|"ino_only"|"off" +@kindex -disk_dev_ino fast incremental backup +@cindex Backup, enable fast incremental, -disk_dev_ino Enable or disable processing of recorded file identification numbers (dev_t and ino_t). They are eventually stored as xattr and allow to substantially accelerate file comparison. The root node gets a global start @@ -938,6 +1001,8 @@ Note that -disk_dev_ino "off" is totally in effect only if -hardlinks is "off", too. @c man .TP @item -rom_toc_scan "on"|"force"|"off"[:"emul_on"|"emul_off"] +@kindex -rom_toc_scan searches for sessions +@cindex Table-of-content, search sessions, -rom_toc_scan Read-only drives do not tell the actual media type but show any media as ROM (e.g. as DVD-ROM). The session history of MMC multi-session media might be truncated to first and last session or even be completely false. @@ -963,6 +1028,8 @@ To be in effect, the -rom_toc_scan setting has to be made before the -*dev command which aquires drive and media. @c man .TP @item -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off" +@kindex -calm_drive reduces drive activity +@cindex Drive, reduce activity, -calm_drive Reduce drive noise until it is actually used again. Some drives stay alert for substantial time after they have been used for reading. This reduces the startup time for the next drive operation but can be loud and waste @@ -974,20 +1041,24 @@ Mode "on" causes -calm_drive to be performed automatically after each -dev, -indev, and -outdev. Mode "off" disables this. @c man .TP @item -ban_stdio_write +@kindex -ban_stdio_write demands real drive +@cindex Drive, demand real MMC, -ban_stdio_write Allow for writing only the usage of MMC optical drives. Disallow to write the result into files of nearly arbitrary type. Once set, this command cannot be revoked. @end table @c man .TP -@c man .B File manipulations: -@node Manipulation, Writing, Loading, Options -@section File manipulations +@c man .B Inserting files into ISO image: +@node Insert, SetInsert, Loading, Options +@section Inserting files into ISO image @c man .PP The following commands expect file addresses of two kinds: @c man .br +@cindex disk_path, _definition @strong{disk_path} is a path to an object in the local filesystem tree. @c man .br +@cindex iso_rr_path, _definition @strong{iso_rr_path} is the Rock Ridge name of a file object in the ISO image. (Do not confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.) @@ -1017,28 +1088,9 @@ The commands in this section alter the ISO image and not the local filesystem. @table @asis @sp 1 @c man .TP -@item -iso_rr_pattern "on"|"ls"|"off" -Set the pattern expansion mode for the iso_rr_path arguments of several -commands which support this feature. -@* -@strong{Pattern expansion} -converts a list of pattern words into a list of existing file addresses. -Eventual unmatched pattern words appear themselves in that result list, though. -@* -Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' -and respects '/' as separator which may only be matched literally. -@* -Setting "off" disables this feature for all commands which are marked in this -man page by "iso_rr_path [***]" or "iso_rr_pattern [***]". -@* -Setting "on" enables it for all those commands. -@* -Setting "ls" enables it only for those which are marked by -"iso_rr_pattern [***]". -@* -Default is "on". -@c man .TP @item -disk_pattern "on"|"ls"|"off" +@kindex -disk_pattern controls pattern expansion +@cindex Pattern expansion, for disk paths, -disk_pattern Set the pattern expansion mode for the disk_path arguments of several commands which support this feature. @* @@ -1053,6 +1105,8 @@ Setting "ls" enables it only for those which are marked by Default is "ls". @c man .TP @item -add pathspec [...] | disk_path [***] +@kindex -add inserts one or more paths +@cindex Insert, pathspecs, -add Insert the given files or directory trees from filesystem into the ISO image. @* @@ -1075,6 +1129,8 @@ The resulting words are used as both, iso_rr_path and disk path. Eventually -cdx gets prepended to disk_path and -cd to iso_rr_path. @c man .TP @item -add_plainly mode +@kindex -add_plainly inserts one or more paths +@cindex Insert, non-dashed arguments, -add_plainly If set to mode "unknown" then any command word that does not begin with "-" and is not recognized as known command will be subject to a virtual -add command. I.e. it will be used as pathspec or as disk_path and added to the image. @@ -1090,26 +1146,38 @@ Mode "none" is the default. It prevents any words from being understood as files to add, if they are not parameters to appropriate commands. @c man .TP @item -path_list disk_path +@kindex -path_list inserts paths from disk file +@cindex Insert, paths from disk file, -path_list Like -add but read the parameter words from file disk_path or standard input if disk_path is "-". The list must contain exactly one pathspec resp. disk_path pattern per line. @c man .TP @item -quoted_path_list disk_path +@kindex -quoted_path_list inserts paths from disk file +@cindex Insert, paths from disk file, -quoted_path_list Like -path_list but with quoted input reading rules. Lines get split into parameter words for -add. Whitespace outside quotes is discarded. @c man .TP @item -map disk_path iso_rr_path +@kindex -map inserts path +@cindex Insert, path, -map Insert file object disk_path into the ISO image as iso_rr_path. If disk_path is a directory then its whole sub tree is inserted into the ISO image. @c man .TP @item -map_single disk_path iso_rr_path +@kindex -map_single inserts path +@cindex Insert, path, -map_single Like -map, but if disk_path is a directory then its sub tree is not inserted. @c man .TP @item -map_l disk_prefix iso_rr_prefix disk_path [***] +@kindex -map_l inserts paths from disk file +@cindex Insert, paths from disk file, -map_l Perform -map with each of the disk_path arguments. iso_rr_path will be composed from disk_path by replacing disk_prefix by iso_rr_prefix. @c man .TP @item -update disk_path iso_rr_path +@kindex -update inserts path if different +@cindex Insert, if different, -update 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. By default this comparison will imply lengthy @@ -1122,6 +1190,8 @@ whole subtree will be inserted. Else only directory attributes will be updated. @c man .TP @item -update_r disk_path iso_rr_path +@kindex -update_r inserts paths if different +@cindex Insert, if different, -update_r Like -update but working recursively. I.e. all file objects below both addresses get compared whether they have counterparts below the other address and whether both counterparts match. If there is a mismatch then the necessary @@ -1134,10 +1204,14 @@ If iso_rr_path does not exist yet, then it gets added. If disk_path does not exist, then iso_rr_path gets deleted. @c man .TP @item -update_l disk_prefix iso_rr_prefix disk_path [***] +@kindex -update_l inserts paths if different +@cindex Insert, if different, -update_l Perform -update_r with each of the disk_path arguments. iso_rr_path will be composed from disk_path by replacing disk_prefix by iso_rr_prefix. @c man .TP @item -cut_out disk_path byte_offset byte_count iso_rr_path +@kindex -cut_out inserts piece of data file +@cindex Insert, piece of data file, -cut_out Map a byte interval of a regular disk file into a regular file in the ISO image. This may be necessary if the disk file is larger than a single media, or if @@ -1173,6 +1247,8 @@ situations. See option -split_size for details. @c man .TP @item -cpr disk_path [***] iso_rr_path +@kindex -cpr inserts like with cp -r +@cindex Insert, paths, -cpr Insert the given files or directory trees from filesystem into the ISO image. @* @@ -1189,7 +1265,264 @@ get the same type as the disk_path. If a disk_path does not begin with '/' then -cdx is prepended. If the iso_rr_path does not begin with '/' then -cd is prepended. @c man .TP +@item -mkdir iso_rr_path [...] +@kindex -mkdir creates ISO directory +@cindex Directory, create, -mkdir +Create empty directories if they do not exist yet. +Existence as directory generates a WARNING event, existence as +other file causes a FAILURE event. +@end table +@c man .TP +@c man .B Settings for file insertion: +@node SetInsert, Manip, Insert, Options +@section Settings for file insertion +@c man .TP +@table @asis +@item -file_size_limit value [value [...]] @minus{}@minus{} +@kindex -file_size_limit limits data file size +@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 xorriso. Default is a limit of 100 extents, 4g -2k each: +@* + -file_size_limit 400g -200k @minus{}@minus{} +@* +When mounting ISO 9660 filesystems, old operating systems can handle only files +up to 2g -1 @minus{}@minus{}. Newer ones are good up to 4g -1 @minus{}@minus{}. +You need quite a new Linux kernel to read correctly the final bytes +of a file >= 4g if its size is not aligned to 2048 byte blocks. +@* +xorriso's own data read capabilities are not affected by eventual +operating system size limits. They apply to mounting only. Nevertheless, +the target filesystem of an -extract must be able to take the file size. +@c man .TP +@item -not_mgt code[:code[...]] +@kindex -not_mgt controls file exclusion +@cindex Insert, file exclusion, -not_mgt +Control the behavior of the exclusion lists. +@* +Exclusion processing happens before disk_paths get mapped to the ISO image +and before disk files get compared with image files. +The absolute disk path of the source is matched against the -not_paths list. +The leafname of the disk path is matched against the patterns in the -not_leaf +list. If a match is detected then the disk path will not be regarded as an +existing file and not be added to the ISO image. +@* +Several codes are defined. +The _on/_off settings persist until they are revoked by their_off/_on +counterparts. +@* +"erase" empties the lists which were accumulated by -not_paths and -not_leaf. +@* +"reset" is like "erase" but also re-installs default behavior. +@* +"off" disables exclusion processing temporarily without invalidating +the lists and settings. +@* +"on" re-enables exclusion processing. +@* +"param_off" applies exclusion processing only to paths below disk_path +parameter of commands. I.e. explicitly given disk_paths are exempted +from exclusion processing. +@* +"param_on" applies exclusion processing to command parameters as well as +to files below such parameters. +@* +"subtree_off" with "param_on" excludes parameter paths only if they +match a -not_paths item exactly. +@* +"subtree_on" additionally excludes parameter paths which lead to a file +address below any -not_paths item. +@* +"ignore_off" treats excluded disk files as if they were missing. I.e. they +get reported with -compare and deleted from the image with -update. +@* +"ignore_on" keeps excluded files out of -compare or -update activities. +@c man .TP +@item -not_paths disk_path [***] +@kindex -not_paths sets absolute exclusion paths +@cindex Insert, file exclusion absolute, -not_paths +Add the given paths to the list of excluded absolute disk paths. If a given +path is relative, then the current -cdx is prepended to form an absolute path. +Eventual pattern matching happens at definition time and not when exclusion +checks are made. +@* +(Do not forget to end the list of disk_paths by "@minus{}@minus{}") +@c man .TP +@item -not_leaf pattern +@kindex -not_leaf sets exclusion pattern +@cindex Insert, file exclusion pattern, -not_leaf +Add a single shell parser style pattern to the list of exclusions for +disk leafnames. These patterns are evaluated when the exclusion checks are +made. +@c man .TP +@item -not_list disk_path +@kindex -not_list sets exclusions from disk file +@cindex Insert, file exclusion from file, -not_list +Read lines from disk_path and use each of them either as -not_paths argument, +if they contain a / character, or as -not_leaf pattern. +@c man .TP +@item -quoted_not_list disk_path +@kindex -quoted_not_list sets exclusions +@cindex Insert, file exclusion, -quoted_not_list +Like -not_list but with quoted input reading rules. Each word is +handled as one argument for -not_paths resp. -not_leaf. +@c man .TP +@item -follow occasion[:occasion[...]] +@kindex -follow softlinks and mount points +@cindex Insert, links or mount points, -follow +Enable or disable resolution of symbolic links and mountpoints under +disk_paths. This applies to actions -add, -du*x, -ls*x, -findx, +and to -disk_pattern expansion. +@* +There are two kinds of follow decisison to be made: +@* +"link" is the hop from a symbolic link to its target file object. +If enabled then symbolic links are handled as their target file objects, +else symbolic links are handled as themselves. +@* +"mount" is the hop from one filesystem to another subordinate filesystem. +If enabled then mountpoint directories are handled as any other directory, +else mountpoints are handled as empty directories if they are encountered in +directory tree traversals. +@* +Less general than above occasions: +@* +"pattern" is mount and link hopping, but only during -disk_pattern expansion. +@* +"param" is link hopping for parameter words (after eventual pattern expansion). +If enabled then -ls*x will show the link targets rather than the links +themselves. -du*x, -findx, and -add will process the link targets but not +follow links in an eventual directory tree below the targets (unless "link" +is enabled). +@* +Occasions can be combined in a colon separated list. All occasions +mentioned in the list will then lead to a positive follow decision. +@* +"off" prevents any positive follow decision. Use it if no other occasion +applies. +@* +Shortcuts: +@* +"default" is equivalent to "pattern:mount:limit=100". +@* +"on" always decides positive. Equivalent to "link:mount". +@* +@sp 1 + +Not an occasion but an optional setting is: +@* +"limit=" which sets the maximum number of link hops. +A link hop consists of a sequence of symbolic links and a final target +of different type. Nevertheless those hops can loop. Example: +@* + $ ln -s .. uploop +@* +Link hopping has a built-in loop detection which stops hopping at the first +repetition of a link target. Then the repeated link is handled as itself +and not as its target. +Regrettably one can construct link networks which +cause exponential workload before their loops get detected. +The number given with "limit=" can curb this workload at the risk of truncating +an intentional sequence of link hops. +@c man .TP +@item -pathspecs "on"|"off" +@kindex -pathspecs sets meaning of = with -add +@cindex Insert, meaning of = with -add, -pathspecs +Control parameter interpretation with xorriso actions -add and -path_list. +@* +@cindex Pathspec, _definition +"on" enables pathspecs of the form +@strong{target=source} +like with program mkisofs -graft-points. +It also disables -disk_pattern expansion for command -add. +@* +"off" disables pathspecs of the form target=source +and eventually enables -disk_pattern expansion. +@c man .TP +@item -overwrite "on"|"nondir"|"off" +@kindex -overwrite enables overwriting in ISO +@cindex Insert, enable overwriting, -overwrite +Allow or disallow to overwrite existing files in the +ISO image by files with the same name. +@* +With setting "off", name collisions cause FAILURE events. +With setting "nondir", only directories are protected by such events, other +existing file types get treated with -rm before the new file gets added. +Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an +existing directory and all its subordinates. +@* +If restoring of files is enabled, then the overwrite rule applies to the +target file objects on disk as well, but "on" is downgraded to "nondir". +@c man .TP +@item -split_size number["k"|"m"] +@kindex -split_size enables large file splitting +@cindex Insert, large file splitting, -split_size +Set the threshold for automatic splitting of regular files. Such splitting +maps a large disk file onto a ISO directory with several part files in it. +This is necessary if the size of the disk file exceeds -file_size_limit. +Older operating systems can handle files in mounted ISO 9660 filesystems +only if they are smaller than 2 GiB resp. 4 GiB. +@* +Default is 0 which will exclude files larger than -file_size_limit by a +FAILURE event. +A well tested -split_size is 2047m. Sizes above -file_size_limit are not +permissible. +@* +While option -split_size is set larger than 0 such a directory with split +file pieces will be recognized and handled like a regular file by options +-compare* , -update*, and in overwrite situations. There are -ossirox +options "concat_split_on" and "concat_split_off" which control the handling +when files get restored to disk. +@* +In order to be recognizable, the names of the part files have to +describe the splitting by 5 numbers: +@* + part_number,total_parts,byte_offset,byte_count,disk_file_size +@* +which are embedded in the following text form: +@* + part_#_of_#_at_#_with_#_of_# +@* +Scaling characters like "m" or "k" are taken into respect. +All digits are interpreted as decimal, even if leading zeros are present. +@* +E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 +@* +No other files are allowed in the directory. All parts have to be present and +their numbers have to be plausible. E.g. byte_count must be valid as -cut_out +argument and their contents may not overlap. +@end table +@c man .TP +@c man .B File manipulations: +@node Manip, CmdFind, SetInsert, Options +@section File manipulations +@c man .PP +The following commands manipulate files in the ISO image, regardless whether +they stem from the loaded image or were newly inserted. +@c man .PP +@table @asis +@sp 1 +@c man .TP +@item -iso_rr_pattern "on"|"ls"|"off" +@kindex -iso_rr_pattern controls pattern expansion +@cindex Pattern expansion, for ISO paths, -iso_rr_pattern +Set the pattern expansion mode for the iso_rr_path arguments of several +commands which support this feature. +@* +Setting "off" disables pattern expansion for all commands which are marked +in this man page by "iso_rr_path [***]" or "iso_rr_pattern [***]". +@* +Setting "on" enables it for all those commands. +@* +Setting "ls" enables it only for those which are marked by +"iso_rr_pattern [***]". +@* +Default is "on". +@c man .TP @item -rm iso_rr_path [***] +@kindex -rm deletes files from ISO image +@cindex Delete, from ISO image, -rm Delete the given files from the ISO image. @* Note: This does not free any space on the -indev media, even if @@ -1199,10 +1532,20 @@ The image size will shrink if the image is written to a different media in modification mode. @c man .TP @item -rm_r iso_rr_path [***] +@kindex -rm_r deletes trees from ISO image +@cindex Delete, from ISO image, -rm_r Delete the given files or directory trees from the ISO image. See also the note with option -rm. @c man .TP +@item -rmdir iso_rr_path [***] +@kindex -rmdir deletes ISO directory +@cindex Delete, ISO directory, -rmdir +@cindex Directory, delete, -rmdir +Delete empty directories. +@c man .TP @item -mv iso_rr_path [***] iso_rr_path +@kindex -mv renames file in ISO image +@cindex Rename, in ISO image, -mv Rename the given file objects in the ISO tree to the last argument in the list. Use the same rules as with shell command mv. @* @@ -1211,20 +1554,30 @@ characters then it must match exactly one existing file address, or else the command fails with a FAILURE event. @c man .TP @item -chown uid iso_rr_path [***] +@kindex -chown sets ownership in ISO image +@cindex Ownership, in ISO image, -chown Set ownership of file objects in the ISO image. uid may either be a decimal number or the name of a user known to the operating system. @c man .TP @item -chown_r uid iso_rr_path [***] +@kindex -chown_r sets ownership in ISO image +@cindex Ownership, in ISO image, -chown_r Like -chown but affecting all files below eventual directories. @c man .TP @item -chgrp gid iso_rr_path [***] +@kindex -chgrp sets group in ISO image +@cindex Group, in ISO image, -chgrp Set group attribute of file objects in the ISO image. gid may either be a decimal number or the name of a group known to the operating system. @c man .TP @item -chgrp_r gid iso_rr_path [***] +@kindex -chgrp_r sets group in ISO image +@cindex Group, in ISO image, -chgrp_r Like -chgrp but affecting all files below eventual directories. @c man .TP @item -chmod mode iso_rr_path [***] +@kindex -chmod sets permissions in ISO image +@cindex Permissions, in ISO image, -chmod Equivalent to shell command chmod in the ISO image. mode is either an octal number beginning with "0" or a comma separated list of statements of the form [ugoa]*[+-=][rwxst]* . @@ -1244,9 +1597,13 @@ r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit For octal numbers see man 2 stat. @c man .TP @item -chmod_r mode iso_rr_path [***] +@kindex -chmod_r sets permissions in ISO image +@cindex Permissions, in ISO image, -chmod_r Like -chmod but affecting all files below eventual directories. @c man .TP @item -setfacl acl_text iso_rr_path [***] +@kindex -setfacl sets ACL in ISO image +@cindex ACL, set in ISO image, -setfacl Attach the given ACL to the given iso_rr_paths after deleting their eventually existing ACLs. If acl_text is empty, or contains the text "clear" or the text @@ -1276,9 +1633,13 @@ This indicates that the entry goes to the "default" ACL rather than to the u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx @c man .TP @item -setfacl_r acl_text iso_rr_path [***] +@kindex -setfacl_r sets ACL in ISO image +@cindex ACL, set in ISO image, -setfacl_r Like -setfacl but affecting all files below eventual directories. @c man .TP @item -setfacl_list disk_path +@kindex -setfacl_list sets ACL in ISO image +@cindex ACL, set in ISO image, -setfacl_list Read the output of -getfacl_r or shell command getfacl -R and apply it to the iso_rr_paths as given in lines beginning with "# file:". This will change ownership, group and ACL of the given files. @@ -1289,6 +1650,8 @@ Since -getfacl and getfacl -R strip leading "/" from file paths, the setting of -cd does always matter. @c man .TP @item -setfattr [-]name value iso_rr_path [***] +@kindex -setfattr sets xattr in ISO image +@cindex xattr, set in ISO image, -setfattr Attach the given xattr pair of name and value to the given iso_rr_paths. If the given name is prefixed by "-", then the pair with that name gets removed from the xattr list. If name is "@minus{}@minus{}remove@minus{}all" @@ -1304,9 +1667,13 @@ See also option -backslash_codes. Other than with option -setfattr_list, the byte value 0 cannot be expressed via -setfattr. @c man .TP @item -setfattr_r [-]name value iso_rr_path [***] +@kindex -setfattr_r sets xattr in ISO image +@cindex xattr, set in ISO image, -setfattr_r Like -setfattr but affecting all files below eventual directories. @c man .TP @item -setfattr_list disk_path +@kindex -setfattr_list sets xattr in ISO image +@cindex xattr, set in ISO image, -setfattr_list Read the output of -getfattr_r or shell command getfattr -Rd and apply it to the iso_rr_paths as given in lines beginning with "# file:". All previously existing user space xattr of the given iso_rr_paths will be deleted. @@ -1328,97 +1695,9 @@ whitespace after the end quote will be ignored. Non-printables bytes and quotes must be represented as \XYZ by their octal ASCII code XYZ. Use code \000 for 0-bytes. @c man .TP -@item -external_filter name option[:option] program_path [arguments] @minus{}@minus{} -Register a content filter by associating a name with a program path, -program arguments, and some behavioral options. Once registered it can be -applied to multiple data files in the ISO image, regardless whether their -content resides in the loaded ISO image or in the local filesystem. -External filter processes may produce synthetic file content by reading the -original content from stdin and writing to stdout whatever they want. -They must deliver the same output on the same input in repeated runs. -@* -Options are: -@* - "default" means that no other option is intended. -@* - "suffix=..." sets a file name suffix. If it is not empty then it will be -appended to the file name or removed from it. -@* - "remove_suffix" will remove an eventual file name suffix -rather than appending it. -@* - "if_nonempty" will leave 0-sized files unfiltered. -@* - "if_reduction" will try filtering and revoke it if the content size does not -shrink. -@* - "if_block_reduction" will revoke if the number of 2 kB blocks does not shrink. -@* - "used=..." is ignored. Command -status shows it with the number of -files which currently have the filter applied. -@* -Examples: -@* - -external_filter bzip2 suffix=.bz2:if_block_reduction \ -@* - /usr/bin/bzip2 @minus{}@minus{} -@* - -external_filter bunzip2 suffix=.bz2:remove_suffix \ -@* - /usr/bin/bunzip2 @minus{}@minus{} -@c man .TP -@item -unregister_filter name -Remove an -external_filter registration. This is only possible if the filter -is not applied to any file in the ISO image. -@c man .TP -@item -close_filter_list -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 xorriso. -By default they are banned if xorriso runs under setuid permission. -@c man .TP -@item -set_filter name iso_rr_path [***] -Apply an -external_filter or a built-in filter to the given data files in the -ISO image. -If the filter suffix is not empty , then it will be applied to the file name. -Renaming only happens if the filter really gets attached and is not revoked by -its options. -By default files which already bear the suffix will not get filtered. The -others will get the suffix appended to their names. -If the filter has option "remove_suffix", then the filter will only be -applied if the suffix is present and can be removed. -Name oversize or collision caused by suffix change will prevent filtering. -@* -With most filter types this command will immediately run the filter once for -each file in order to determine the output size. -Content reading operations like -extract , -compare and image generation will -perform further filter runs and deliver filtered content. -@* -At image generation time the filter output must still be the same as the -output from the first run. Filtering for image generation does not happen -with files from the loaded ISO image if the write method of growing is in -effect (i.e -indev and -outdev are identical). -@* -The reserved filter name "@minus{}@minus{}remove-all-filters" revokes -filtering. This will revoke eventual suffix renamings as well. -Use "@minus{}@minus{}remove-all-filters+" to -prevent any suffix renaming. -@* -Built-in filters are "@minus{}@minus{}zisofs" and -"@minus{}@minus{}zisofs-decode". The former is to be -applied via -set_filter, the latter is automatically applied if zisofs -compressed content is detected with a file when loading the ISO image. -@* -Another built-in filter pair is "@minus{}@minus{}gzip" -and "@minus{}@minus{}gunzip" with suffix ".gz". -They behave about like external gzip and gunzip but avoid forking a process -for each single file. So they are much faster if there are many small files. -@c man .TP -@item -set_filter_r name iso_rr_path [***] -Like -set_filter but affecting all data files below eventual directories. -@c man .TP @item -alter_date type timestring iso_rr_path [***] +@kindex -alter_date sets timestamps in ISO image +@cindex Timestamps, set in ISO image, -alter_date Alter the date entries of a file in the ISO image. type is one of "a", "m", "b" for access time, modification time, both times. @@ -1455,9 +1734,21 @@ scdbackup timestamps: where "A0" is year 2000, "B0" is 2010, etc. @c man .TP @item -alter_date_r type timestring iso_rr_path [***] +@kindex -alter_date_r sets timestamps in ISO image +@cindex Timestamps, set in ISO image, -alter_date_r Like -alter_date but affecting all files below eventual directories. +@end table +@c man .TP +@c man .B Tree traversal command -find: +@node CmdFind, Filter, Manip, Options +@section Tree traversal command -find +@c man .PP +@table @asis +@sp 1 @c man .TP @item -find iso_rr_path [test [op] [test ...]] [-exec action [params]] @minus{}@minus{} +@kindex -find traverses and alters ISO tree +@cindex Tree, ISO, traverse and alter, -find A restricted substitute for shell command find in the ISO image. It performs an action on matching file objects at or below iso_rr_path. @* @@ -1700,31 +1991,139 @@ E.g.: @* -find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r @minus{}@minus{} @end table +@end table @c man .TP -@item -mkdir iso_rr_path [...] -Create empty directories if they do not exist yet. -Existence as directory generates a WARNING event, existence as -other file causes a FAILURE event. +@c man .B Filters for data file content: +@c man .PP +@node Filter, Writing, CmdFind, Options +@section Filters for data file content +@cindex Filter, _definition +@strong{Filters} may be installed between data files in the ISO image and their +content source outside the image. They may also be used vice versa between +data content in the image and target files on disk. +@* +@sp 1 +Built-in filters are "@minus{}@minus{}zisofs" and +"@minus{}@minus{}zisofs-decode". The former is to be +applied via -set_filter, the latter is automatically applied if zisofs +compressed content is detected with a file when loading the ISO image. +@* +Another built-in filter pair is "@minus{}@minus{}gzip" +and "@minus{}@minus{}gunzip" with suffix ".gz". +They behave about like external gzip and gunzip but avoid forking a process +for each single file. So they are much faster if there are many small files. +@c man .PP +@table @asis +@sp 1 @c man .TP -@item -rmdir iso_rr_path [***] -Delete empty directories. +@item -external_filter name option[:option] program_path [arguments] @minus{}@minus{} +@kindex -external_filter registers data filter +@cindex Filter, register, -external_filter +Register a content filter by associating a name with a program path, +program arguments, and some behavioral options. Once registered it can be +applied to multiple data files in the ISO image, regardless whether their +content resides in the loaded ISO image or in the local filesystem. +External filter processes may produce synthetic file content by reading the +original content from stdin and writing to stdout whatever they want. +They must deliver the same output on the same input in repeated runs. +@* +Options are: +@* + "default" means that no other option is intended. +@* + "suffix=..." sets a file name suffix. If it is not empty then it will be +appended to the file name or removed from it. +@* + "remove_suffix" will remove an eventual file name suffix +rather than appending it. +@* + "if_nonempty" will leave 0-sized files unfiltered. +@* + "if_reduction" will try filtering and revoke it if the content size does not +shrink. +@* + "if_block_reduction" will revoke if the number of 2 kB blocks does not shrink. +@* + "used=..." is ignored. Command -status shows it with the number of +files which currently have the filter applied. +@* +Examples: +@* + -external_filter bzip2 suffix=.bz2:if_block_reduction \ +@* + /usr/bin/bzip2 @minus{}@minus{} +@* + -external_filter bunzip2 suffix=.bz2:remove_suffix \ +@* + /usr/bin/bunzip2 @minus{}@minus{} @c man .TP -@item -rollback -Discard the manipulated ISO image and reload it from -indev. +@item -unregister_filter name +@kindex -external_filter unregisters data filter +@cindex Filter, unregister, -unregister_filter +Remove an -external_filter registration. This is only possible if the filter +is not applied to any file in the ISO image. @c man .TP -@item -rollback_end -Discard the manipulated ISO image. End program without loading a new image. +@item -close_filter_list +@kindex -close_filter_list bans filter registration +@cindex Filter, ban registration, -close_filter_list +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 xorriso. +By default they are banned if xorriso runs under setuid permission. +@c man .TP +@item -set_filter name iso_rr_path [***] +@kindex -set_filter applies filter to file +@cindex Filter, apply to file, -set_filter +Apply an -external_filter or a built-in filter to the given data files in the +ISO image. +If the filter suffix is not empty , then it will be applied to the file name. +Renaming only happens if the filter really gets attached and is not revoked by +its options. +By default files which already bear the suffix will not get filtered. The +others will get the suffix appended to their names. +If the filter has option "remove_suffix", then the filter will only be +applied if the suffix is present and can be removed. +Name oversize or collision caused by suffix change will prevent filtering. +@* +With most filter types this command will immediately run the filter once for +each file in order to determine the output size. +Content reading operations like -extract , -compare and image generation will +perform further filter runs and deliver filtered content. +@* +At image generation time the filter output must still be the same as the +output from the first run. Filtering for image generation does not happen +with files from the loaded ISO image if the write method of growing is in +effect (i.e -indev and -outdev are identical). +@* +The reserved filter name "@minus{}@minus{}remove-all-filters" revokes +filtering. This will revoke eventual suffix renamings as well. +Use "@minus{}@minus{}remove-all-filters+" to +prevent any suffix renaming. +@c man .TP +@item -set_filter_r name iso_rr_path [***] +@kindex -set_filter_r applies filter to file tree +@cindex Filter, apply to file tree, -set_filter_r +Like -set_filter but affecting all data files below eventual directories. @end table @c man .TP @c man .B Writing the result, drive control: -@node Writing, SetInsert, Manipulation, Options +@node Writing, SetWrite, Filter, Options @section Writing the result, drive control @c man .PP (see also paragraph about settings below) @table @asis @sp 1 @c man .TP +@item -rollback +@kindex -rollback discards pending changes +@cindex Image, discard pending changes, -rollback +Discard the manipulated ISO image and reload it from -indev. +(Use -rollback_end if immediate program end is desired.) +@c man .TP @item -commit +@kindex -commit writes pending ISO image +@cindex Write, pending ISO image, -commit Perform the write operation. Afterwards eventually make the -outdev the new -dev and load the image from there. Switch to growing mode. @@ -1754,15 +2153,21 @@ burn programs but you may well try some of those listed below under SEE ALSO. @c man .TP @item -eject "in"|"out"|"all" +@kindex -eject ejects drive tray +@cindex Drive, eject tray, -eject Eject the media in -indev, resp. -outdev, resp. both drives. Note: It is not possible yet to effectively eject disk files. @c man .TP @item -commit_eject "in"|"out"|"all"|"none" +@kindex -commit_eject writes and ejects +@cindex Drive, write and eject, -commit_eject Combined -commit and -eject. When writing has finished do not make -outdev the new -dev, and load no ISO image. Rather eject -indev and/or -outdev. Eventually give up any non-ejected drive. @c man .TP @item -blank mode +@kindex -blank erases media +@cindex Media, erase, -blank Make media ready for writing from scratch (if not -dummy is activated). @* This affects only the -outdev not the -indev. @@ -1792,6 +2197,8 @@ reported percentages. Blanking was successful if no SORRY event or worse occured. @c man .TP @item -format mode +@kindex -format formats media +@cindex Media, format, -format Convert unformatted DVD-RW into overwriteable ones, "de-ice" DVD+RW, format newly purchased BD-RE or BD-R, re-format DVD-RAM or BD-RE. @* @@ -1840,6 +2247,8 @@ reported percentages. Formatting was successful if no SORRY event or worse occured. Be patient with apparently frozen progress. @c man .TP @item -list_formats +@kindex -list_formats lists available formats +@cindex Media, list formats, -list_formats Put out a list of format descriptors as reported by the output drive for the current media. The list gives the index number after "Format idx", a MMC format code, the announced size in blocks (like "2236704s") @@ -1853,212 +2262,14 @@ MMC format codes are manifold. Most important are: Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserve space. @c man .TP @item -list_profiles "in"|"out"|"all" +@kindex -list_profiles lists supported media +@cindex Drive, list supported media, -list_profiles Put out a list of media types supported by -indev, resp. -outdev, resp. both. The currently recognized type is marked by text "(current)". @end table @c man .TP -@c man .B Settings for file insertion: -@node SetInsert, SetWrite, Writing, Options -@section Settings for file insertion -@c man .TP -@table @asis -@item -file_size_limit value [value [...]] @minus{}@minus{} -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: -@* - -file_size_limit 400g -200k @minus{}@minus{} -@* -When mounting ISO 9660 filesystems, old operating systems can handle only files -up to 2g -1 @minus{}@minus{}. Newer ones are good up to 4g -1 @minus{}@minus{}. -You need quite a new Linux kernel to read correctly the final bytes -of a file >= 4g if its size is not aligned to 2048 byte blocks. -@* -xorriso's own data read capabilities are not affected by eventual -operating system size limits. They apply to mounting only. Nevertheless, -the target filesystem of an -extract must be able to take the file size. -@c man .TP -@item -not_mgt code[:code[...]] -Control the behavior of the exclusion lists. -@* -Exclusion processing happens before disk_paths get mapped to the ISO image -and before disk files get compared with image files. -The absolute disk path of the source is matched against the -not_paths list. -The leafname of the disk path is matched against the patterns in the -not_leaf -list. If a match is detected then the disk path will not be regarded as an -existing file and not be added to the ISO image. -@* -Several codes are defined. -The _on/_off settings persist until they are revoked by their_off/_on -counterparts. -@* -"erase" empties the lists which were accumulated by -not_paths and -not_leaf. -@* -"reset" is like "erase" but also re-installs default behavior. -@* -"off" disables exclusion processing temporarily without invalidating -the lists and settings. -@* -"on" re-enables exclusion processing. -@* -"param_off" applies exclusion processing only to paths below disk_path -parameter of commands. I.e. explicitly given disk_paths are exempted -from exclusion processing. -@* -"param_on" applies exclusion processing to command parameters as well as -to files below such parameters. -@* -"subtree_off" with "param_on" excludes parameter paths only if they -match a -not_paths item exactly. -@* -"subtree_on" additionally excludes parameter paths which lead to a file -address below any -not_paths item. -@* -"ignore_off" treats excluded disk files as if they were missing. I.e. they -get reported with -compare and deleted from the image with -update. -@* -"ignore_on" keeps excluded files out of -compare or -update activities. -@c man .TP -@item -not_paths disk_path [***] -Add the given paths to the list of excluded absolute disk paths. If a given -path is relative, then the current -cdx is prepended to form an absolute path. -Eventual pattern matching happens at definition time and not when exclusion -checks are made. -@* -(Do not forget to end the list of disk_paths by "@minus{}@minus{}") -@c man .TP -@item -not_leaf pattern -Add a single shell parser style pattern to the list of exclusions for -disk leafnames. These patterns are evaluated when the exclusion checks are -made. -@c man .TP -@item -not_list disk_path -Read lines from disk_path and use each of them either as -not_paths argument, -if they contain a / character, or as -not_leaf pattern. -@c man .TP -@item -quoted_not_list disk_path -Like -not_list but with quoted input reading rules. Each word is -handled as one argument for -not_paths resp. -not_leaf. -@c man .TP -@item -follow occasion[:occasion[...]] -Enable or disable resolution of symbolic links and mountpoints under -disk_paths. This applies to actions -add, -du*x, -ls*x, -findx, -and to -disk_pattern expansion. -@* -There are two kinds of follow decisison to be made: -@* -"link" is the hop from a symbolic link to its target file object. -If enabled then symbolic links are handled as their target file objects, -else symbolic links are handled as themselves. -@* -"mount" is the hop from one filesystem to another subordinate filesystem. -If enabled then mountpoint directories are handled as any other directory, -else mountpoints are handled as empty directories if they are encountered in -directory tree traversals. -@* -Less general than above occasions: -@* -"pattern" is mount and link hopping, but only during -disk_pattern expansion. -@* -"param" is link hopping for parameter words (after eventual pattern expansion). -If enabled then -ls*x will show the link targets rather than the links -themselves. -du*x, -findx, and -add will process the link targets but not -follow links in an eventual directory tree below the targets (unless "link" -is enabled). -@* -Occasions can be combined in a colon separated list. All occasions -mentioned in the list will then lead to a positive follow decision. -@* -"off" prevents any positive follow decision. Use it if no other occasion -applies. -@* -Shortcuts: -@* -"default" is equivalent to "pattern:mount:limit=100". -@* -"on" always decides positive. Equivalent to "link:mount". -@* -@sp 1 - -Not an occasion but an optional setting is: -@* -"limit=" which sets the maximum number of link hops. -A link hop consists of a sequence of symbolic links and a final target -of different type. Nevertheless those hops can loop. Example: -@* - $ ln -s .. uploop -@* -Link hopping has a built-in loop detection which stops hopping at the first -repetition of a link target. Then the repeated link is handled as itself -and not as its target. -Regrettably one can construct link networks which -cause exponential workload before their loops get detected. -The number given with "limit=" can curb this workload at the risk of truncating -an intentional sequence of link hops. -@c man .TP -@item -pathspecs "on"|"off" -Control parameter interpretation with xorriso actions -add and -path_list. -@* -"on" enables pathspecs of the form -@strong{target=source} -like with program mkisofs -graft-points. -It also disables -disk_pattern expansion for command -add. -@* -"off" disables pathspecs of the form target=source -and eventually enables -disk_pattern expansion. -@c man .TP -@item -overwrite "on"|"nondir"|"off" -Allow or disallow to overwrite existing files in the -ISO image by files with the same name. -@* -With setting "off", name collisions cause FAILURE events. -With setting "nondir", only directories are protected by such events, other -existing file types get treated with -rm before the new file gets added. -Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an -existing directory and all its subordinates. -@* -If restoring of files is enabled, then the overwrite rule applies to the -target file objects on disk as well, but "on" is downgraded to "nondir". -@c man .TP -@item -split_size number["k"|"m"] -Set the threshold for automatic splitting of regular files. Such splitting -maps a large disk file onto a ISO directory with several part files in it. -This is necessary if the size of the disk file exceeds -file_size_limit. -Older operating systems can handle files in mounted ISO 9660 filesystems -only if they are smaller than 2 GiB resp. 4 GiB. -@* -Default is 0 which will exclude files larger than -file_size_limit by a -FAILURE event. -A well tested -split_size is 2047m. Sizes above -file_size_limit are not -permissible. -@* -While option -split_size is set larger than 0 such a directory with split -file pieces will be recognized and handled like a regular file by options --compare* , -update*, and in overwrite situations. There are -ossirox -options "concat_split_on" and "concat_split_off" which control the handling -when files get restored to disk. -@* -In order to be recognizable, the names of the part files have to -describe the splitting by 5 numbers: -@* - part_number,total_parts,byte_offset,byte_count,disk_file_size -@* -which are embedded in the following text form: -@* - part_#_of_#_at_#_with_#_of_# -@* -Scaling characters like "m" or "k" are taken into respect. -All digits are interpreted as decimal, even if leading zeros are present. -@* -E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 -@* -No other files are allowed in the directory. All parts have to be present and -their numbers have to be plausible. E.g. byte_count must be valid as -cut_out -argument and their contents may not overlap. -@end table -@c man .TP @c man .B Settings for result writing: -@node SetWrite, Bootable, SetInsert, Options +@node SetWrite, Bootable, Writing, Options @section Settings for result writing @c man .PP Rock Ridge info will be generated by the program unconditionally. @@ -2067,9 +2278,14 @@ ACLs will be written according to the setting of option -acl. @sp 1 @c man .TP @item -joliet "on"|"off" -If enabled by "on", generate Joliet info additional to Rock Ridge info. +@kindex -joliet enables production of Joliet tree +@cindex Write, enable Joliet, -joliet +If enabled by "on", generate Joliet tree additional to ISO 9660 + Rock Ridge +tree. @c man .TP @item -compliance rule[:rule...] +@kindex -compliance controls standard compliance +@cindex Write, compliance to specs, -compliance Adjust the compliance to specifications of ISO 9660 and its contemporary extensions. In some cases it is worth to deviate a bit in order to circumvent bugs of the intended @@ -2122,6 +2338,8 @@ Note: The term "ISO file" means the plain ISO 9660 names and attributes which get visible if the reader ignores Rock Ridge. @c man .TP @item -volid text +@kindex -volid sets volume id +@cindex Image, set volume id, -volid Specify the volume ID. xorriso accepts any text up to 32 characters, but according to rarely obeyed specs stricter rules apply: @* @@ -2142,23 +2360,31 @@ or -rollback. If you insist in -volid "ISOIMAGE", set it again after those commands. @c man .TP @item -volset_id text +@kindex -volset_id sets volume set id +@cindex Image, set volume set id, -volset_id Set the volume set id string to be written with the next -commit. Permissible are up to 128 characters. This setting gets overridden by image loading. @c man .TP @item -publisher text +@kindex -publisher sets publisher id +@cindex Image, set publisher id, -publisher Set the publisher id string to be written with the next -commit. This may identify the person or organisation who specified what shall be recorded. Permissible are up to 128 characters. This setting gets overridden by image loading. @c man .TP @item -application_id text +@kindex -application_id sets application id +@cindex Image, set application id, -application_id Set the application id string to be written with the next -commit. This may identify the specification of how the data are recorded. Permissible are up to 128 characters. This setting gets overridden by image loading. @c man .TP @item -system_id text +@kindex -system_id sets system id +@cindex Image, set system id, -system_id Set the system id string to be written with the next -commit. This may identify the system which can recognize and act upon the content of the System Area in image blocks 0 to 15. @@ -2166,18 +2392,26 @@ Permissible are up to 32 characters. This setting gets overridden by image loading. @c man .TP @item -out_charset character_set_name +@kindex -out_charset sets output character set +@cindex Character Set, for output, -out_charset Set the character set to which file names get converted when writing an image. See paragraph "Character sets" for more explanations. When loading the written image after -commit the setting of -out_charset will be copied to -in_charset. @c man .TP @item -uid uid +@kindex -uid sets global ownership +@cindex Ownership, global in ISO image, -uid User id to be used for all files when the new ISO tree gets written to media. @c man .TP @item -gid gid +@kindex -gid sets global ownership +@cindex Group, global in ISO image, -gid Group id to be used for all files when the new ISO tree gets written to media. @c man .TP @item -zisofs option[:options] +@kindex -zisofs controls zisofs production +@cindex Filter, zisofs parameters, -zisofs Set global parameters for zisofs compression. This data format is recognized and transparently uncompressed by some Linux kernels. It is to be applied via option -set_filter with built-in filter "@minus{}@minus{}zisofs". @@ -2194,6 +2428,8 @@ mkzftree. "default" same as "level=6:block_size=32k:by_magic=off" @c man .TP @item -speed number[k|m|c|d|b] +@kindex -speed set write speed +@cindex Write, set speed, -speed Set the burn speed. Default is 0 = maximum speed. Speed can be given in media dependent numbers or as a desired throughput per second in MMC compliant kB (= 1000) @@ -2214,6 +2450,8 @@ the speed value given by the burn program only as upper limit for their own decision. @c man .TP @item -stream_recording "on"|"off"|"full"|"data"|number +@kindex -stream_recording controls defect management +@cindex Write, defect management, -stream_recording Setting "on" tries to circumvent the management of defects on DVD-RAM, BD-RE, or BD-R. Defect management keeps partly damaged media usable. But it reduces write speed to half nominal speed even if the media is in perfect shape. @@ -2228,6 +2466,8 @@ in order to set an own address limit. written and writing of file content blocks begins. @c man .TP @item -dvd_obs "default"|"32k"|"64k" +@kindex -dvd_obs set write block size +@cindex Write, block size, -dvd_obs GNU/Linux specific: Set the number of bytes to be transmitted with each write operation to DVD or BD media. A number of 64 KB may improve throughput with bus systems which @@ -2235,16 +2475,22 @@ show latency problems. The default depends on media type, on option -stream_recording , and on compile time options. @c man .TP @item -stdio_sync "on"|"off"|number +@kindex -stdio_sync controls stdio buffer +@cindex Write, buffer syncing, -stdio_sync Set the number of bytes after which to force output to stdio: pseudo drives. This forcing keeps the memory from being clogged with lots of pending data for slow devices. Default "on" is the same as "16m". Forced output can be disabled by "off". @c man .TP @item -dummy "on"|"off" +@kindex -dummy controls write simulation +@cindex Write, simulation, -dummy If "on" then simulate burning or refuse with FAILURE event if no simulation is possible, do neither blank nor format. @c man .TP @item -fs number["k"|"m"] +@kindex -fs sets size of fifo +@cindex Write, fifo size, -fs Set the size of the fifo buffer which smoothens the data stream from ISO image generation to media burning. Default is 4 MiB, minimum 64 kiB, maximum 1 GiB. @@ -2252,6 +2498,8 @@ The number may be followed by letter "k" or "m" which means unit is kiB (= 1024) or MiB (= 1024 kiB). @c man .TP @item -close "on"|"off" +@kindex -close controls media closing +@cindex Write, close media, -close If "on" then mark the written media as not appendable any more (if possible at all with the given type of target media). @* @@ -2259,6 +2507,8 @@ This is the contrary of cdrecord, wodim, cdrskin option -multi, and is one aspect of growisofs option -dvd-compat. @c man .TP @item -padding number["k"|"m"] +@kindex -padding sets amount of image padding +@cindex Write, padding image, -padding 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. @@ -2290,6 +2540,9 @@ can assume overwriteable media. @sp 1 @c man .TP @item -boot_image "any"|"isolinux" +@kindex -boot_image controls bootability +@cindex Write, bootability, -boot_image +@cindex Bootability, control, -boot_image @* "discard"|"keep"|"patch"|"show_status"|bootspec @* @@ -2362,6 +2615,7 @@ missing. @node Charset, Exception, Bootable, Options @section Character sets @c man .PP +@cindex Character Set, _definition File names are strings of non-zero bytes with 8 bit each. Unfortunately the same byte string may appear as different peculiar national characters on differently nationalized terminals. @@ -2406,10 +2660,14 @@ and enable -backslash_codes to avoid evil character display on your terminal. @sp 1 @c man .TP @item -charset character_set_name +@kindex -charset sets input/output character set +@cindex Character Set, for input/output, -charset Set the character set from which to convert file names when loading an image and to which to convert when writing an image. @c man .TP @item -local_charset character_set_name +@kindex -local_charset sets terminal character set +@cindex Character Set, of terminal, -local_charset Override the system assumption of the local character set name. If this appears necessary, one should consider to set -backslash_codes to "on" in order to avoid dangerous binary codes being sent to the terminal. @@ -2454,6 +2712,8 @@ or an important resource failed unexpectedly. @sp 1 @c man .TP @item -abort_on severity +@kindex -abort_on controls abort on error +@cindex Process, control abort on error, -abort_on Set the severity threshold for events to abort the program. @* Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY" @@ -2468,6 +2728,8 @@ start arguments is in effect already when the first operations of 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 xorriso to go on after problems but to get a failure indicating exit value from the program, nevertheless. @@ -2490,6 +2752,8 @@ it decides to abort the program run: 6=program abort during dialog processing @c man .TP @item -report_about severity +@kindex -report_about controls verbosity +@cindex Process, control verbosity, -report_about Set the threshold for events to be reported. @* Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "ALL" @@ -2506,6 +2770,8 @@ among the start arguments is in effect already when the first operations of xorriso begin. Only "-report_about" with dash "-" is recognized that way. @c man .TP @item -error_behavior occasion behavior +@kindex -error_behavior controls error workarounds +@cindex Process, error workarounds, -error_behavior Control the program behavior at problem event occasions. For now this applies to occasions "image_loading" which is given while an image tree is read from the input device, and to "file_extraction" which @@ -2538,6 +2804,8 @@ file content stems from the loaded ISO image and is not filtered. @table @asis @c man .TP @item -dialog "on"|"off"|"single_line" +@kindex -dialog enables dialog mode +@cindex Dialog, enable dialog mode, -dialog Enable or disable to enter dialog mode after all arguments are processed. In dialog mode input lines get prompted via readline or from stdin. @* @@ -2546,6 +2814,8 @@ line continuation by trailing backslash outside quotation marks. Mode "single_line" does not. @c man .TP @item -page length width +@kindex -page set terminal geometry +@cindex Dialog, terminal geometry, -page Describe terminal to the text pager. See also above, paragraph Result pager. @* If parameter length is nonzero then the user gets prompted after that @@ -2556,11 +2826,15 @@ to compute the number of terminal lines which get occupied by an output line. A usual terminal width is 80. @c man .TP @item -use_readline "on"|"off" +@kindex -use_readline enables readline for dialog +@cindex Dialog, line editing, -use_readline If "on" then use readline for dialog. Else use plain stdin. @* See also above, paragraph Dialog, Readline, Result pager. @c man .TP @item -reassure "on"|"tree"|"off" +@kindex -reassure enables confirmation question +@cindex Dialog, confirmation question, -reassure If "on" then ask the user for "y" or "n": @* before deleting or overwriting any file in the ISO image, @@ -2600,6 +2874,8 @@ use -rollback to revoke the whole session. @table @asis @c man .TP @item -devices +@kindex -devices gets list of drives +@cindex Drive, get drive list, -devices Show list of available MMC drives with the addresses of their libburn standard device files. @* @@ -2616,6 +2892,8 @@ Drives which are occupied by other processes get not shown. @c man .TP @item -toc @* +@kindex -toc shows list of sessions +@cindex Table-of-content, show, -toc Show media specific table of content. This is the media session history, not the ISO image directory tree. @* @@ -2632,6 +2910,8 @@ Some read-only drives and media show no usable session history at all. Eventually option -rom_toc_scan might help. @c man .TP @item -mount_cmd drive entity id path +@kindex -mount_cmd composes mount command line +@cindex Session, mount command line, -mount_cmd Emit an appropriate command line for mounting the ISO session indicated by drive, entity and id. The result will be different on GNU/Linux and on FreeBSD. @@ -2651,6 +2931,8 @@ The command gets printed to the result channel. See option -mount for direct execution of this command. @c man .TP @item -mount_opts option[:option...] +@kindex -mount_cmd controls mount command +@cindex Session, mount parameters, -mount_opts Set options which influence -mount and -mount_cmd. Currently there is only option "exclusive" which is default and its counterpart "shared". The latter causes xorriso not to give up the affected drive with command -mount. @@ -2660,6 +2942,8 @@ to a mounted optical media, of course. Take care to umount all sessions before ejecting. @c man .TP @item -session_string drive entity id format +@kindex -session_string composes session info line +@cindex Session, info string, -session_string Print to the result channel a text which gets composed according to format and the parameters of the addressed session. @* @@ -2678,15 +2962,21 @@ address. session number, resp. volume id of the depicted session. @c man .TP @item -print_size +@kindex -print_size predicts image size +@cindex Write, predict image size, -print_size Print the foreseeable consumption of 2048 byte blocks by next -commit. This can last a while as a -commit gets prepared and only in last moment is revoked by this option. @c man .TP @item -tell_media_space +@kindex -tell_media_space reports free space +@cindex Write, free space, -tell_media_space Print available space on output media and the free space after subtracting already foreseeable consumption by next -commit. @c man .TP @item -pvd_info +@kindex -pvd_info shows image id strings +@cindex Image, show id strings, -pvd_info Print various id strings which can be found in loaded ISO images. Some of them may be changed by options -volid, -publisher, -application_id. For these ids -pvd_info reports what would be written with the next -commit. @@ -2698,6 +2988,8 @@ ids -pvd_info reports what would be written with the next -commit. @table @asis @c man .TP @item -cd iso_rr_path +@kindex -cd sets working directory in ISO +@cindex Navigate, set ISO working directory, -cd Change the current working directory in the ISO image. This is prepended to iso_rr_paths which do not begin with '/'. @* @@ -2708,18 +3000,26 @@ Use -mkdir if you want to enforce the existence of the directory already at first insertion. @c man .TP @item -cdx disk_path +@kindex -cdx sets working directory on disk +@cindex Navigate, set disk working directory, -cdx Change the current working directory in the local filesystem. To be prepended to disk_paths which do not begin with '/'. @c man .TP @item -pwd @* +@kindex -pwd tells working directory in ISO +@cindex Navigate, tell ISO working directory, -pwd Tell the current working directory in the ISO image. @c man .TP @item -pwdx +@kindex -pwdx tells working directory on disk +@cindex Navigate, tell disk working directory, -pwdx @* Tell the current working directory in the local filesystem. @c man .TP @item -ls iso_rr_pattern [***] +@kindex -ls lists files in ISO image +@cindex Navigate, list ISO files, -ls 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 @@ -2730,18 +3030,26 @@ Directories are listed by their content rather than as single file item. Pattern expansion may be disabled by command -iso_rr_pattern. @c man .TP @item -lsd iso_rr_pattern [***] +@kindex -lsd lists files in ISO image +@cindex Navigate, list ISO files, -lsd Like -ls but listing directories as themselves and not by their content. This resembles shell command ls -d. @c man .TP @item -lsl iso_rr_pattern [***] +@kindex -lsl lists files in ISO image +@cindex Navigate, list ISO files, -lsl Like -ls but also list some of the file attributes. The output format resembles shell command ls -ln. @c man .TP @item -lsdl iso_rr_pattern [***] +@kindex -lsdl lists files in ISO image +@cindex Navigate, list ISO files, -lsdl Like -lsd but also list some of the file attributes. The output format resembles shell command ls -dln. @c man .TP @item -lsx disk_pattern [***] +@kindex -lsx lists files on disk +@cindex Navigate, list disk files, -lsx List files in the local filesystem which match shell patterns. Patterns which do not begin with '/' are used relative to -cdx. @* @@ -2750,55 +3058,79 @@ Directories are listed by their content rather than as single file item. Pattern expansion may be disabled by command -disk_pattern. @c man .TP @item -lsdx disk_pattern [***] +@kindex -lsdx lists files on disk +@cindex Navigate, list disk files, -lsdx Like -lsx but listing directories as themselves and not by their content. This resembles shell command ls -d. @c man .TP @item -lslx disk_pattern [***] +@kindex -lslx lists files on disk +@cindex Navigate, list disk files, -lslx Like -lsx but also listing some of the file attributes. Output format resembles shell command ls -ln. @c man .TP @item -lsdlx disk_pattern [***] +@kindex -lsdlx lists files on disk +@cindex Navigate, list disk files, -lsdlx Like -lsdx but also listing some of the file attributes. Output format resembles shell command ls -dln. @c man .TP @item -getfacl iso_rr_pattern [***] +@kindex -getfacl shows ACL in ISO image +@cindex ACL, show in ISO image, -getfacl Print the access permissions of the given files in the ISO image using the format of shell command getfacl. If a file has no ACL then it gets fabricated from the -chmod settings. A file may have a real ACL if it was introduced into the ISO image while option -acl was set to "on". @c man .TP @item -getfacl_r iso_rr_pattern [***] +@kindex -getfacl_r shows ACL in ISO image +@cindex ACL, show in ISO image, -getfacl_r Like -gefacl but listing recursively the whole file trees underneath eventual directories. @c man .TP @item -getfattr iso_rr_pattern [***] +@kindex -getfattr shows xattr in ISO image +@cindex xattr, show in ISO image, -getfattr Print the xattr of the given files in the ISO image. If a file has no such xattr then noting is printed for it. @c man .TP @item -getfattr_r iso_rr_pattern [***] +@kindex -getfattr_r shows xattr in ISO image +@cindex xattr, show in ISO image, -getfattr_r Like -gefattr but listing recursively the whole file trees underneath eventual directories. @c man .TP @item -du iso_rr_pattern [***] +@kindex -du show directory size in ISO image +@cindex Navigate, directory size in ISO image, -du Recursively list size of directories and files in the ISO image which match one of the patterns. similar to shell command du -k. @c man .TP @item -dus iso_rr_pattern [***] +@kindex -dus show directory size in ISO image +@cindex Navigate, directory size in ISO image, -dus List size of directories and files in the ISO image which match one of the patterns. Similar to shell command du -sk. @c man .TP @item -dux disk_pattern [***] +@kindex -dux show directory size on disk +@cindex Navigate, directory size in on disk, -dux Recursively list size of directories and files in the local filesystem which match one of the patterns. Similar to shell command du -k. @c man .TP @item -dusx disk_pattern [***] +@kindex -dusx show directory size on disk +@cindex Navigate, directory size in on disk, -dusx List size of directories and files in the local filesystem which match one of the patterns. Similar to shell command du -sk. @c man .TP @item -findx disk_path [-name pattern] [-type t] [-exec action [params]] @minus{}@minus{} +@kindex -findx traverses disk tree +@cindex Tree, disk, traverse, -findx Like -find but operating on local filesystem and not on the ISO image. This is subject to the settings of -follow. @* @@ -2840,6 +3172,8 @@ in the ISO image. To be used with -type "m" to truncate mount points. @end table @c man .TP @item -compare disk_path iso_rr_path +@kindex -compare reports ISO/disk differences +@cindex Verify, compare ISO and disk file, -compare Compare attributes and eventual data file content of a fileobject in the local filesystem with a file object in the ISO image. The iso_rr_path may well point to an image file object which is not yet committed, i.e. of which @@ -2853,15 +3187,21 @@ Both to the result channel. In case of no differences no result lines are emitted. @c man .TP @item -compare_r disk_path iso_rr_path +@kindex -compare_r reports ISO/disk differences +@cindex Verify, compare ISO and disk tree, -compare_r Like -compare but working recursively. I.e. all file objects below both addresses get compared whether they have counterparts below the other address and whether both counterparts match. @c man .TP @item -compare_l disk_prefix iso_rr_prefix disk_path [***] +@kindex -compare_l reports ISO/disk differences +@cindex Verify, compare ISO and disk, -compare_l Perform -compare_r with each of the disk_path arguments. iso_rr_path will be composed from disk_path by replacing disk_prefix by iso_rr_prefix. @c man .TP @item -show_stream iso_rr_path [***] +@kindex -show_stream shows data source and filters +@cindex Filter, show chain, -show_stream Display the content stream chain of data files in the ISO image. The chain consists of the iso_rr_name and one or more streams, separated by " < " marks. A stream consists of one or more texts eventually in ''-quotation marks, @@ -2882,6 +3222,8 @@ Example: '/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x' @c man .TP @item -show_stream_r iso_rr_path [***] +@kindex -show_stream_r shows data source and filters +@cindex Filter, show chains of tree, -show_stream_r Like -show_stream but working recursively. @end table @c man .TP @@ -2906,6 +3248,9 @@ They work independently of the media type and can detect transmission errors. @sp 1 @c man .TP @item -check_media [option [option ...]] @minus{}@minus{} +@kindex -check_media reads media block by block +@cindex Verify, check blocks, -check_media +@cindex Recovery, retrieve blocks, -check_media Try to read data blocks from the indev drive, eventually copy them to a disk file, and finally report about the encountered quality. Several options may be used to modify the default behavior. @@ -2928,6 +3273,8 @@ checksum tags for the ISO session data and eventually checks them against the checksums computed from the data stream. @c man .TP @item -check_media_defaults [option [option ...]] @minus{}@minus{} +@kindex -check_media_defaults sets -check_media options +@cindex Verify, preset -check_media, -check_media_defaults Preset options for runs of -check_media, -extract_cut and best_effort file extraction. Eventual options given with -check_media will override the preset options. -extract_cut will override some options automatically. @@ -3051,6 +3398,8 @@ sets the number of bytes to be read in one read operation. This gets rounded down to full blocks of 2048 bytes. 0 means automatic size. @end table @c man .TP +@kindex -check_md5 verifies file checksum +@cindex Verify, file checksum, -check_md5 @item -check_md5 severity iso_rr_path [***] Compare the data content of the given files in the loaded image with their recorded MD5 checksums, if there are any. In case of any mismatch an event of @@ -3067,6 +3416,8 @@ MD5 sum. Be aware that this covers only one session and not the whole image if there are older sessions. @c man .TP @item -check_md5_r severity iso_rr_path [***] +@kindex -check_md5_r verifies file tree checksums +@cindex Verify, file tree checksums, -check_md5_r Like -check_md5 but checking all data files underneath the given paths. Only mismatching data files will be reported. @end table @@ -3091,6 +3442,8 @@ The directory permissions on disk have to allow rwx. @sp 1 @c man .TP @item -osirrox "on"|"device_files"|"off"|"banned"|[:option:...] +@kindex -osirrox enables ISO-to-disk copying +@cindex Restore, enable ISO-to-disk, -osirrox Setting "off" disables disk filesystem manipulations. This is the default unless the program was started with leafname "osirrox". Elsewise the capability to restore files can be enabled explicitly by -osirrox "on". @@ -3132,6 +3485,8 @@ written, or ejected. But be aware that even harmless inquiries can spoil ongoing burns of CD-R[W] and DVD-R[W]. @c man .TP @item -extract iso_rr_path disk_path +@kindex -extract copies file tree to disk +@cindex Restore, copy file tree to disk, -extract 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. @@ -3146,14 +3501,20 @@ As many attributes as possible are copied together with restored file objects. @c man .TP @item -extract_single iso_rr_path disk_path +@kindex -extract_single copies file to disk +@cindex Restore, copy file to disk, -extract_single Like -extract, but if iso_rr_path is a directory then its sub tree gets not restored. @c man .TP @item -extract_l iso_rr_prefix disk_prefix iso_rr_path [***] +@kindex -extract_l copies files to disk +@cindex Restore, copy files to disk, -extract_l Perform -extract with each of the iso_rr_path arguments. disk_path will be composed from iso_rr_path by replacing iso_rr_prefix by disk_prefix. @c man .TP @item -extract_cut iso_rr_path byte_offset byte_count disk_path +@kindex -extract_cut copies file piece to disk +@cindex Restore, copy file piece to disk, -extract_cut Copy a byte interval from a data file out of an ISO image into a newly created disk file. The main purpose for this is to allow handling of large files if they @@ -3167,6 +3528,8 @@ is performed. It may be quicker and more rugged than the general reading method. @c man .TP @item -cpx iso_rr_path [***] disk_path +@kindex -cpx copies files to disk +@cindex Restore, copy files to disk, -cpx 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 @@ -3179,10 +3542,14 @@ and only if they actually represent a complete collection of -cut_out split file parts. @c man .TP @item -cpax iso_rr_path [***] disk_path +@kindex -cpax copies files to disk +@cindex Restore, copy files to disk, -cpax Like -cpx but restoring mtime, atime as in ISO image and trying to set ownership and group as in ISO image. @c man .TP @item -cp_rx iso_rr_path [***] disk_path +@kindex -cp_rx copies file trees to disk +@cindex Restore, copy file trees to disk, -cp_rx Like -cpx but also extracting whole directory trees from the ISO image. @* The resulting disk paths are determined as with shell command cp -r : @@ -3191,15 +3558,21 @@ underneath this directory and will keep their leaf names. The ISO directory "/" has no leaf name and thus gets mapped directly to disk_path. @c man .TP @item -cp_rax iso_rr_path [***] disk_path +@kindex -cp_rx copies file trees to disk +@cindex Restore, copy file trees to disk, -cp_rx Like -cp_rx but restoring mtime, atime as in ISO image and trying to set ownership and group as in ISO image. @c man .TP @item -paste_in iso_rr_path disk_path byte_offset byte_count +@kindex -paste_in copies file into disk file +@cindex Restore, copy file into disk file, -paste_in Read the content of a ISO data file and write it into a data file on disk beginning at the byte_offset. Write at most byte_count bytes. This is the inverse of option -cut_out. @c man .TP @item -mount drive entity id path +@kindex -mount issues mount command for ISO session +@cindex Session, issue mount command, -mount Produce the same line as -mount_cmd and then execute it as external program run after giving up the depicted drive. See also -mount_opts. This demands -osirrox to be enabled and normally will succeed only for the @@ -3220,12 +3593,16 @@ of commands which in said programs trigger comparable actions. @sp 1 @c man .TP @item -as personality option [options] @minus{}@minus{} +@kindex -as emulates mkisofs or cdrecord +@cindex Emulation, -as @* Perform the variable length option list as sparse emulation of the program depicted by the personality word. @* @sp 1 +@cindex Emulation, mkisofs, -as +@cindex mkisofs, Emulation Personality "@strong{mkisofs}" accepts the options listed with: @* -as mkisofs -help @minus{}@minus{} @@ -3281,6 +3658,8 @@ as xorriso options. @* @sp 1 +@cindex Emulation, cdrecord, -as +@cindex cdrecord, Emulation Personality "@strong{cdrecord}" accepts the options listed with: @* -as cdrecord -help @minus{}@minus{} @@ -3324,6 +3703,8 @@ style until "@minus{}@minus{}" is encountered and an eventual commit happens. From then on, options are interpreted as xorriso options. @c man .TP @item -pacifier behavior_code +@kindex -pacifier controls pacifier text form +@cindex Emulation, pacifier form, -pacifier Control behavior of UPDATE pacifiers during write operations. The following behavior codes are defined: @* @@ -3340,6 +3721,8 @@ X of Y MB written (fifo nn%) [buf mmm%] nn% done, estimate finish Tue Jul 15 20:13:28 2008 @c man .TP @item -scdbackup_tag list_path record_name +@kindex -scdbackup_tag enables scdbackup checksum tag +@cindex Backup, scdbackup checksum tag, -scdbackup Set the parameter "name" for a scdbackup checksum record. It will be appended in an scdbackup checksum tag to the -md5 session tag if the image starts at LBA 0. This is the case if it gets written as first @@ -3358,25 +3741,37 @@ Program scdbackup_verify will recognize and verify tag resp. record. @table @asis @c man .TP @item -no_rc +@kindex -no_rc disables startup files +@cindex Process, disable startup files, -no_rc @* Only if used as first command line argument this option prevents reading and interpretation of eventual startup files. See section FILES below. @c man .TP @item -options_from_file fileaddress +@kindex -options_from_file reads commands from file +@cindex Process, read command file, -options_from_file Read quoted input from fileaddress and executes it like dialog lines. @c man .TP @item -help +@kindex -help prints help text +@cindex Program, print help text, -help @* Print helptext. @c man .TP @item -version +@kindex -version prints help text +@cindex Program, print version, -version Print program name and version, component versions, license. @c man .TP @item -history textline +@kindex -history brings text into readline history +@cindex Dialog, bring text into history, -history Copy textline into libreadline history. @c man .TP @item -status mode|filter +@kindex -status shows current settings +@cindex Program, show current settings, -status Print the current settings of xorriso. Modes: @* @@ -3391,9 +3786,13 @@ output lines of -status:long_history. A line is put out only if its start matches the filter text. No wildcards. @c man .TP @item -status_history_max number +@kindex -status_history_max curbs -status history +@cindex Program, status history, -status_history_max Set maximum number of history lines to be reported with -status "long_history". @c man .TP @item -list_delimiter word +@kindex -list_delimiter replaces '@minus{}@minus{}' +@cindex Program, replace @minus{}@minus{}, -list_delimiter Set the list delimiter to be used instead of "@minus{}@minus{}". It has to be a single word, must not be empty, not longer than 80 characters, and must not contain @@ -3403,6 +3802,8 @@ For brevity the list delimiter is referred as "@minus{}@minus{}" throughout this text. @c man .TP @item -backslash_codes "on"|"off"|mode[:mode] +@kindex -backslash_codes enables backslash conversion +@cindex Program, backslash conversion, -backslash_codes Enable or disable the interpretation of symbolic representations of special characters with quoted input, or with program arguments, or with program text output. If enabled the following translations apply: @@ -3440,6 +3841,8 @@ Mode "on" is "with_quoted_input:with_program_arguments:encode_output". @c man .TP @item -temp_mem_limit number["k"|"m"] +@kindex -temp_mem_limit curbs memory consumption +@cindex Program, curb memory, -temp_mem_limit Set the maximum size of temporary memory to be used for image dependent buffering. Currently this applies to pattern expansion, LBA sorting, restoring of hard links. @@ -3447,14 +3850,20 @@ restoring of hard links. Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 GiB. @c man .TP @item -print text +@kindex -print prints text line +@cindex Program, print text line, -print Print a text to result channel. @c man .TP @item -prompt text +@kindex -prompt prompts for enter key +@cindex Program, prompt for enter key, -prompt Show text at beginning of output line and wait for the user to hit the Enter key resp. to send a line via stdin. @c man .TP @item -errfile_log mode path|channel +@kindex -errfile_log logs problematic disk files +@cindex Write, log problematic disk files, -errfile_log @* If problem events are related to input files from the filesystem, then their disk_paths can be logged to a file or to output channels R or I. @@ -3475,6 +3884,9 @@ The errfile paths are transported as messages of very low severity "ERRFILE". This transport becomes visible with -report_about "ALL". @c man .TP @item -session_log path +@kindex -session_log logs written sessions +@cindex Write, log written sessions, -session_log +@cindex Session, log when written, -session_log If path is not empty it gives the address of a plain text file where a log record gets appended after each session. This log can be used to determine the start_lba of a session for mount options -o sbsector= @@ -3485,6 +3897,8 @@ Record format is: timestamp start_lba size volume-id The first three items are single words, the rest of the line is the volume id. @c man .TP @item -scsi_log "on"|"off" +@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 xorriso output channels. @@ -3494,21 +3908,34 @@ among the start arguments is in effect already when the first operations of xorriso begin. Only "-scsi_log" with dash "-" is recognized that way. @c man .TP @item -end +@kindex -end writes pending session and ends program +@cindex Process, end program and write, -end +@cindex Program, end and write, -end @* -End program immediately +End program after writing eventually pending changes. +@c man .TP +@item -rollback_end +@kindex -rollback_end ends program without writing +@cindex Program, end without writing, -rollback_end +@cindex Process, end program, no writing, -rollback_end +Discard pending changes. End program immediately. @c man .TP @item # any text +@kindex # starts a comment line +@cindex Comment, # 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. @end table @c man .TP @c man .B Support for frontend programs via stdin and stdout: -@node Frontend,, Scripting, Options +@node Frontend, ExDevices, Scripting, Options @section Support for frontend programs via stdin and stdout @table @asis @c man .TP @item -pkt_output "on"|"off" +@kindex -pkt_output consolidates text output +@cindex Process, consolidate text output, -pkt_output Consolidate text output on stdout and classify each line by a channel indicator: @* @@ -3528,17 +3955,25 @@ Example: I:1: enter option and arguments : @c man .TP @item -logfile channel fileaddress +@kindex -logfile logs output channels to file +@cindex Process, log output channels to file, -logfile 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. @c man .TP @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 after a dialog line has been processed. @c man .TP @item -prog text +@kindex -prog sets program name +@cindex Program, set name, -prog Use text as name of this program in subsequent messages @c man .TP @item -prog_help text +@kindex -prog_help prints help text +@cindex Program, print help text, -prog_help Use text as name of this program and perform -help. @end table @c man .br @@ -3578,6 +4013,7 @@ Use text as name of this program and perform -help. @c man Restore directory trees from a particular ISO session to disk @c man .br @c man Try to retrieve blocks from a damaged media +@cindex Examples @menu * ExDevices:: As superuser learn about available drives * ExCreate:: Blank media and compose a new ISO image as batch run @@ -3598,7 +4034,7 @@ Use text as name of this program and perform -help. @end menu @c man .SS @c man .B As superuser learn about available drives -@node ExDevices, ExCreate, Examples, Examples +@node ExDevices, ExCreate, Frontend, Examples @section As superuser learn about available drives Consider to give rw permissions to those users or groups which shall be able to use the drives with xorriso. @@ -4278,7 +4714,21 @@ to Derek Foreman and Ben Jansens who once founded libburn. @* Compliments towards Joerg Schilling whose cdrtools served me for ten years. +@c man-ignore-lines begin @node Index,, Legal, top @chapter Index +@menu +* CommandIdx:: Alphabetic Command List +* ConceptIdx:: Alphabetic List of Concepts and Objects +@end menu + +@node CommandIdx, ConceptIdx, Index, Index +@section Alphabetic Command List +@printindex ky + +@node ConceptIdx,, CommandIdx, Index +@section Alphabetic List of Concepts and Objects @printindex cp + +@c man-ignore-lines end @bye diff --git a/xorriso/xorriso_timestamp.h b/xorriso/xorriso_timestamp.h index 07c13f8c..f33db3fc 100644 --- a/xorriso/xorriso_timestamp.h +++ b/xorriso/xorriso_timestamp.h @@ -1 +1 @@ -#define Xorriso_timestamP "2010.03.18.101202" +#define Xorriso_timestamP "2010.03.20.165317"