xorriso

man 1 xorriso

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
FILES
SEE ALSO
BUGS
AUTHOR
COPYRIGHT
CREDITS

---

NAME

xorriso - creates, loads, manipulates and writesISO 9660 filesystem images with Rock Ridge extensions.

SYNOPSIS

xorriso [settings|actions]

DESCRIPTION

xorriso is a program which copies file objectsfrom POSIX compliant filesystems into Rock Ridge enhancedISO 9660 filesystems and allows session-wisemanipulation of such filesystems. It can load the managementinformation of existing ISO images and it writes the sessionresults to optical media or to filesystem objects. Vice versa xorriso is able to copy file objects outof ISO 9660 filesystems. A special property of xorriso is that it needsneither an external ISO 9660 formatter program nor anexternal burn program for CD, DVD or BD but ratherincorporates the libraries of libburnia-project.org.

Overview of features:

Operates on an existing ISO image or creates a newone. Copies files from disk filesystem into the ISO image. Copies files from ISO image to disk filesystem (seeosirrox). Renames or deletes file objects in the ISO image. Changes file properties in the ISO image. Updates ISO subtrees incrementally to match given disksubtrees. Writes result either as completely new image or asadd-on session to optical media or filesystemobjects. Can activate ISOLINUX and GRUB boot images via El Torito andMBR. Can perform multi-session tasks as emulation ofmkisofs and cdrecord. Can record and restore hard links and ACL. Content may get zisofs compressed or filtered by externalprocesses. Can issue commands to mount older sessions on GNU/Linux orFreeBSD. Can check media for damages and copy readable blocks todisk. Can attach MD5 checksums to each data file and the wholesession. Scans for optical drives, blanks re-useable opticalmedia. Reads its instructions from command line arguments, dialog,and files. Provides navigation commands for interactive ISO imagemanipulation. Adjustable thresholds for abort, exit value, and problemreporting.

General information paragraphs:

Session model Media types and states Creating, Growing, Modifying, Blind Growing Libburn drives Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr Command processing Dialog, Readline, Result pager Maybe you first want to have a look at section EXAMPLESnear the end of this text before reading the next fewhundred lines of background information.

Session model:

Unlike other filesystems, ISO 9660 is not intended forread-write operation but rather for being generated ina single sweep and being written to media as asession. The data content of the session is called filesystemimage. The written image in its session can then be mounted bythe operating system for being used read-only.GNU/Linux is able to mount ISO images from block devices,which may represent optical media, other media or via a loopdevice even from regular disk files. FreeBSD mounts ISOimages from devices that represent arbitrary media or fromregular disk files. This session usage model has been extended on CD media bythe concept of multi-session , which allows toadd information to the CD and gives the mount programs ofthe operating systems the addresses of the entry points ofeach session. The mount programs recognize block deviceswhich represent CD media and will by default mount the imagein the last session. This session usually contains an updated directory tree forthe whole medium which governs the data contents in allrecorded sessions. So in the view of the mount program allsessions of a particular medium together form a singlefilesystem image. Adding a session to an existing ISO image is in this textreferred as growing. The multi-session model of the MMC standard does notapply to all media types. But program growisofs by AndyPolyakov showed how to extend this functionality tooverwriteable media or disk files which carry valid ISO 9660filesystems. xorriso provides growing as well as an own methodnamed modifying which produces a completely new ISOimage from the old one and the modifications. See paragraphCreating, Growing, Modifying, Blind Growing below. xorriso adopts the concept of multi-sessionby loading an image directory tree if present, by allowingto manipulate it by several actions, and by writing the newimage to the target medium. The first session of a xorriso run begins by thedefinition of the input drive with the ISO image or by thedefinition of an output drive. The session ends by command-commit which triggers writing. A -commit isdone automatically when the program ends regularly. After -commit a new session begins with the freshlywritten one as input. A new input drive can only be chosenas long as the loaded ISO image was not altered. Pendingalteration can be revoked by command -rollback. Writing a session to the target is supposed to be veryexpensive in terms of time and of consumed space onappendable or write-once media. Therefore all intendedmanipulations of a particular ISO image should be done in asingle session. But in principle it is possible to storeintermediate states and to continue with imagemanipulations.

Media types and states:

There are two families of media in the MMCstandard: Multi-session media are CD-R, CD-RW,DVD-R, DVD+R, DVD+R/DL, BD-R, and unformattedDVD-RW. These media provide a table of content whichdescribes their existing sessions. See option-toc. Similar to multi-session media are DVD-R DL andminimally blanked DVD-RW. They allow only a singlesession of which the size must be known in advance.xorriso will write onto them only if option-close is set to "on". Overwriteable media are DVD-RAM, DVD+RW,BD-RE, and formatted DVD-RW. They allow randomwrite access but do not provide information about theirsession history. If they contain one or more ISO 9660sessions and if the first session was written byxorriso, then a table of content can be emulated.Else only a single overall session will be visible. DVD-RW media can be formatted by -format"full". They can be made unformatted by-blank "deformat". Regular files and block devices are handled as overwriteablemedia. Pipes and other writeable file types are handled asblank multi-session media. These media can assume several states in which they offerdifferent capabilities. Blank media can be written from scratch. They contain noISO image suitable forxorriso. Blank is the state of newly purchased optical media. Withused CD-RW and DVD-RW it can be achieved byaction -blank "as_needed". Overwriteablemedia are considered blank if they are new or if they havebeen marked as blank byxorriso. Action -blank"as_needed" can be used to do this marking onoverwriteable media, or to apply mandatory formatting to newmedia if necessary. Appendable media accept further sessions. Either theyare MMC multi-session media in appendable state, orthey are overwriteable media which contain an ISO imagesuitable forxorriso. Appendable is the state after writing a session with option-close off. Closed media cannot be written. They may contain an ISOimage suitable forxorriso. Closed is the state of DVD-ROM media and ofmulti-session media which were written with option-close on. If the drive is read-only hardwarethen it will probably show any media as closed CD-ROMresp. DVD-ROM. Overwriteable media assume this state in suchread-only drives or if they contain unrecognizabledata in the first 32 data blocks. Read-only drives may or may not show session historiesof multi-session media. Often only the first and thelast session are visible. Sometimes not even that. Option-rom_toc_scan might or might not help in suchcases.

Creating, Growing, Modifying, BlindGrowing:

A new empty ISO image gets created if there is noinput drive with a valid ISO 9660 image when the first timean output drive is defined. This is achieved by option-dev on blank media or by option -outdev onmedia in any state. The new empty image can be populated with directories andfiles. Before it can be written, the medium in the outputdrive must get into blank state if it was not blankalready. If there is a input drive with a valid ISO image, thenthis image gets loaded as foundation for manipulations andextension. The constellation of input and output drivedetermines which write method will be used. They have quitedifferent capabilities and constraints. The method of growing adds new data to theexisting data on the medium. These data comprise of new filecontent and they override the existing ISO 9660 + Rock Ridgedirectory tree. It is possible to hide files from previoussessions but they still exist on the medium and with manytypes of optical media it is quite easy to recover them bymounting older sessions. Growing is achieved by option -dev. The write method of modifying produces compactfilesystem images with no outdated files or directory trees.Modifying can write its images to target media which arecompletely unsuitable for multi-session operations.E.g. DVD-RW which were treated with -blankdeformat_quickest, DVD-R DL, named pipes, characterdevices, sockets. On the other hand modified sessions cannotbe written to appendable media but to blank media only. So for this method one needs either two optical drives orhas to work with filesystem objects as source and/or targetmedium. Modifying takes place if input drive and output drive arenot the same and if option -grow_blindly is set to itsdefault "off". This is achieved by options-indev and -outdev. If option -grow_blindly is set to anon-negative number and if -indev and-outdev are both set to different drives, thenblind growing is performed. It produces anadd-on session which is ready for being written to thegiven block address. This is the usage model of mkisofs -M $indev -C $msc1,$msc2 -o$outdev which gives much room for wrong parameter combinations andshould thus only be employed if a strict distinction betweenISO formatterxorriso and the burn program isdesired. -C $msc1,$msc2 is equivalent to: -load sbsector $msc1 -grow_blindly $msc2

Libburn drives:

Input drive, i.e. source of an existing or empty ISOimage, can be any random access readable libburn drive:optical media with readable data, blank optical media,regular files, block devices. Output drive, i.e. target for writing, can be any libburndrive. Some drive types do not support the method of growingbut only the methods of modifying and blind growing. Theyall are suitable for newly created images. All drive file objects have to offer rw-permission tothe user of xorriso. Even those which will not beuseable for reading an ISO image. MMC compliant (i.e. optical) drives on GNU/Linux usuallyget addressed by the path of their block device or of theirgeneric character device. E.g. -dev /dev/sr0 -dev /dev/hdc -dev /dev/sg2 On FreeBSD the device files have names like -dev /dev/cd0 On OpenSolaris: -dev /dev/rdsk/c4t0d0s2 Get a list of accessible drives by command -device_links It might be necessary to do this as superuser inorder to see all drives and to then allow rw-accessfor the intended users. Consider to bundle the authorizedusers in a group like old "floppy". Filesystem objects of nearly any type can be addressed byprefix "stdio:" and their path in the filesystem.E.g.: -dev stdio:/dev/sdc The default setting of -drive_class allows to addressfiles outside the /dev tree without that prefix. E.g.: -dev /tmp/pseudo_drive If path leads to a regular file or to a block device thenthe emulated drive is random access readable and can be usedfor the method of growing if it already contains a valid ISO9660 image. Any other file type is not readable via"stdio:" and can only be used as target for themethod of modifying or blind growing. Non-existingpaths in existing directories are handled as empty regularfiles. A very special kind of pseudo drive are open filedescriptors. They are depicted by "stdio:/dev/fd/"and descriptor number (see man 2 open). Addresses "-" or "stdio:/dev/fd/1"depict standard output, which normally is the output channelfor result texts. To prevent a fatal intermingling of ISOimage and text messages, all result texts get redirected tostderr if -*dev "-" or"stdio:/dev/fd/1" is among the start arguments ofthe program. Standard output is currently suitable for creating onesession per program run without dialog. Use in othersituations is discouraged and several restrictionsapply: It is not allowed to use standard output as pseudo drive ifit was not among the start arguments. Do not try to foolthis ban via backdoor addresses to stdout. If stdout is used as drive, then -use_readline ispermanently disabled. Use of backdoors can cause severememory and/or tty corruption. Be aware that especially the superuser can write into anyaccessible file or device by using its path with the"stdio:" prefix. By default any address in the/dev tree without prefix "stdio:" will work onlyif it leads to a MMC drive. One may use option -ban_stdio_write to surelyprevent this risk and to allow only MMC drives. One may prepend "mmc:" to a path to surelydisallow any automatic "stdio:". By option -drive_class one may ban certain paths orallow access without prefix "stdio:" to otherpaths.

Rock Ridge, POSIX, X/Open, El Torito, ACL,xattr:

Rock Ridge is the name of a set of additionalinformation which enhance an ISO 9660 filesystem so that itcan represent a POSIX compliant filesystem with ownership,access permissions, symbolic links, and otherattributes. This is what xorriso uses for a decent representationof the disk files within the ISO image. Rock Ridgeinformation is produced with anyxorriso image. xorriso is not named "porriso" becausePOSIX only guarantees 14 characters of filename length. Itis the X/Open System Interface standard XSI which demands afile name length of up to 255 characters and paths of up to1024 characters. Rock Ridge fulfills this demand. An El Torito boot record points the BIOSbootstrapping facility to one or more boot images, which arebinary program files stored in the ISO image. The content ofthe boot image files is not in the scope of El Torito. Most bootable GNU/Linux CDs are equipped with ISOLINUX orGRUB boot images. xorriso is able to create ormaintain an El Torito object which makes such an imagebootable. For details see option -boot_image. It is possible to make ISO images bootable from USB stick orother hard-disk-like media by -boot_imageargument system_area= . This installs a Master Boot Recordwhich may get adjusted according to the needs of GRUB resp.ISOLINUX. AnMBR contains boot code and a partitiontable. It does not hamper CDROM booting. The new MBR of afollow-up session can get in effect only onoverwriteable media. Emulation -as mkisofs supports the example options outof the ISOLINUX wiki, the options used in GRUB scriptgrub-mkrescue, and the example in the FreeBSDAvgLiveCD wiki. There is support for boot facilities other than PC BIOS:EFI, MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUNSPARC. ACL are an advanced way of controlling accesspermissions to file objects. Neither ISO 9660 nor Rock Ridgespecify a way to record ACLs. So libisofs has introduced astandard conformant extension named AAIP for that purpose.It uses this extension if enabled by option-acl. AAIP enhanced images are supposed to be mountable normally,but one cannot expect that the mounted filesystem will showand respect the ACLs. For now, onlyxorriso is ableto retrieve those ACLs. It can bring them into effect whenfiles get restored to an ACL enabled file system or it canprint them in a format suitable for tool setfacl. Files with ACL show as group permissions the setting ofentry "mask::" if that entry exists. Neverthelessthe non-listed group members get handled according toentry "group::". When removing ACL from a file,xorriso brings "group::" into effect. Recording and restoring of ACLs from and to local filesworks currently only on GNU/Linux and FreeBSD. xattr (aka EA, or extattr) are pairs of name andvalue which can be attached to file objects. AAIP is able torepresent them andxorriso allows to record andrestore pairs which have names out of the user namespace.I.e. those which begin with "user.", like"user.x" or "user.whatever". Name has tobe a 0 terminated string. Value may be any array of byteswhich does not exceed the size of 4095 bytes. xattrprocessing happens only if it is enabled by option-xattr. As with ACL, currently only xorriso is able toretrieve xattr from AAIP enhanced images, to restore them toxattr capable file systems, or to print them. Recording and restoring of xattr from and to local filesworks currently only on GNU/Linux and FreeBSD, where theyare known as extattr.

Command processing:

Commands are either actions which happen immediately orsettings which influence following actions. So theirsequence does matter. Commands consist of a command word, followed by zero or moreparameter words. If the list of parameter words is ofvariable length (indicated by "[...]" or"[***]") then it has to be terminated by eitherthelist delimiter, or the end of argument list, oran end of an input line. At program start the list delimiter is the word"--". This may be changed by option-list_delimiter in order to allow"--" as argument in a list of variablelength. It is advised to reset the delimiter to"--" immediately afterwards. For brevity the list delimiter is referred as"--" throughout this text. The list delimiter is silently tolerated if it appears afterthe parameters of a command with a fixed list length. It ishandled as normal text if it appears among the arguments ofsuch a command. Pattern expansion converts a list of pattern wordsinto a list of existing file addresses. Unmatched patternwords appear themselves in that result list, though. Pattern matching supports the usual shell parser wildcards’*’ ’?’ ’[xyz]’ andrespects ’/’ as separator which may only bematched literally. It is a property of some particular commands and not ageneral feature. It gets controlled by commands-iso_rr_pattern and -disk_pattern. Commandswhich may use pattern expansion all have variable argumentlists which are marked in this man page by "[***]"rather than "[...]". Some other commands perform pattern matchingunconditionally. Command and parameter words are either read from programarguments, where one argument is one word, or from quotedinput lines where words are recognized similar to thequotation rules of a shell parser. xorriso is not a shell, although it might appear so onfirst glimpse. Be aware that the interaction of quotationmarks and pattern symbols like "*" differs fromthe usual shell parsers. Inxorriso, a quotation markdoes not make a pattern symbol literal. Quoted input converts whitespace separated textpieces into words. The double quotation mark " and thesingle quotation mark ’ can be used to enclosewhitespace and make it part of words (e.g. of file names).Each mark type can enclose the marks of the other type. Atrailing backslash \ outside quotations or an open quotationcause the next input line to be appended. Quoted input accepts any ASCII character except NUL (0) ascontent of quotes. Nevertheless it can be cumbersome for theuser to produce those characters at all. Therefore quotedinput and program arguments allow optionalBackslashInterpretation which can represent all ASCII charactersexcept NUL (0) by backslash codes as in $’...’of bash. It is not enabled by default. See option-backslash_codes. When the program starts then it first looks for argument-no_rc. If this is not present then it looks for itsstartup files and reads their content as command inputlines. Then it interprets the program arguments as commandsand parameters. Finally it enters dialog mode if command-dialog "on" was executed up to then. The program ends either by command -end, or by theend of program arguments if not dialog was enabled up tothat moment, or by a problem event which triggers thethreshold of command -abort_on.

Dialog, Readline, Result pager:

Dialog mode prompts for a quoted input line, parses itinto words, and performs them as commands with theirparameters. It provides assisting services to make dialogmore comfortable. Readline is an enhancement for the input line. You mayknow it already from the bash shell. Whether it is availableinxorriso depends on the availability of packagereadline-dev at the time whenxorriso was builtfrom its sourcecode. It allows to move the cursor over the text in the line byhelp of the Leftward and the Rightward arrow key. Text maybe inserted at the cursor position. The Delete key removesthe character under the cursor. Upward and Downward arrowkeys navigate through the history of previous inputlines. See man readline for more info about libreadline. Option -page activates a built-in result textpager which may be convenient in dialog. After an action hasput out the given number of terminal lines, the pagerprompts the user for a line of input. An empty line lets xorriso resume work until the nextpage is put out. The single character "@" disables paging for thecurrent action. "@@@", "x", "q","X", or "Q" urge the current action toabort and suppress further result output. Any other line will be interpreted as new dialog line. Thecurrent action is urged to abort. Afterwards, the input lineis executed. Some actions apply paging to their info output, too. The urge to abort may or may not be obeyed by the currentaction. All actions try to abort as soon as possible.

OPTIONS

All command words are shown with a leading dash althoughthis dash is not mandatory for the option to be recognized.Nevertheless within option -as the dashes of theemulated options are mandatory. Normally any number of leading dashes is ignored withcommand words and inner dashes are interpreted asunderscores.

Aquiring source and target drive:

The effect of aquiring a drive may depend on severaloptions in the next paragraph "Influencing the behaviorof image loading". If desired, their enabling commandshave to be performed before the commands which aquire thedrive.

-dev address

Set input and output drive to the same address and loadan ISO image if it is present. If there is no ISO image thencreate a blank one. Set the image expansion method togrowing. This is only allowed as long as no changes are pending inthe currently loaded ISO image. If changes are pending, thenone has to perform -commit or -rollbackfirst. Special address string "-" means standardoutput, to which several restrictions apply. See aboveparagraph "Libburn drives". An empty address string "" gives up the currentdevice without aquiring a new one.

-indev address

Set input drive and load an ISO image if present. If thenew input drive differs from -outdev then switch fromgrowing to modifying or to blind growing. It depends on thesetting of -grow_blindly which of both gets activated.The same rules and restrictions apply as with-dev.

-outdev address

Set output drive and if it differs from the input drivethen switch from growing to modifying or to blind growing.Unlike -dev and -indev this action does not loada new ISO image. So it can be performed even if there arepending changes. -outdev can be performed without previous -devor -indev. In that case an empty ISO image with nochanges pending is created. It can either be populated byhelp of -map, -add et.al. or it can be discardedsilently if -dev or -indev are performedafterwards. Special address string "-" means standardoutput, to which several restrictions apply. See aboveparagraph "Libburn drives". An empty address string "" gives up the currentoutput drive without aquiring a new one. No writing ispossible without an output drive.

-grow_blindly"off"|predicted_nwa

If predicted_nwa is a non-negative number thenperform blind growing rather than modifying if -indevand -outdev are set to different drives."off" or "-1" switch to modifying,which is the default. predicted_nwa is the block address where the add-onsession of blind growing will finally end up. It is theresponsibility of the user to ensure this final position andthe presence of the older sessions. Else the overall ISOimage will not be mountable or will produce read errors whenaccessing file content. xorriso will write thesession to the address as obtained from examining-outdev and not necessarily to predicted_nwa. During a run of blind growing, the input drive is given upbefore output begins. The output drive is given up whenwriting is done.

Influencing the behavior of imageloading:

The following options should normally be performed beforeloading an image by aquiring an input drive. In rare casesit is desirable to activate them only after imageloading.

-load entity id

Load a particular (possibly outdated) ISO session from-dev or -indev. Usually all available sessionsare shown with option -toc. entity depicts the kind of addressing. id depicts theparticular address. The following entities are defined: "auto" with any id addresses the last session in-toc. This is the default. "session" with id being a number as of a line"ISO session", column "Idx". "track" with id being a number as of a line"ISO track", column "Idx". "lba" or "sbsector" with a number as ofa line "ISO ...", column "sbsector". "volid" with a search pattern for a text as of aline "ISO ...", column "Volume Id". Adressing a non-existing entity or one which does notrepresent an ISO image will either abandon -indev orat least lead to a blank image. If an input drive is set at the moment when -load isexecuted, then the addressed ISO image is loadedimmediately. Else, the setting will be pending until thenext -dev or -indev. After the image has beenloaded once, the setting is valid for -rollback untilnext -dev or -indev, where it will be reset to"auto".

-displacement [-]lba

Compensate a displacement of the image versus the startaddress for which the image was prepared. This affects onlyloading of ISO images and reading of their files. Themulti-session method of growing is not allowed as longas -displacement is non-zero. I.e. -indevand -outdev must be different. The displacement getsreset to 0 before the drive gets re-aquired afterwriting. Examples: If a track of a CD starts at block 123456 and gets copied toa disk file where it begins at block 0, then this copy canbe loaded with -displacement -123456. If an ISO image was written onto a partition with offset of640000 blocks of 512 bytes, then it can be loaded from thebase device by -displacement 160000. In both cases, the ISO sessions should be self contained,i.e. not add-on sessions to an ISO image outside theirtrack resp. partition.

-drive_class"harmless"|"banned"|"caution"|"clear_list"disk_pattern

Add a drive path pattern to one of the safety lists ormake those lists empty. There are three lists defined whichget tested in the following sequence: If a drive address path matches the "harmless"list then the drive will be accepted. If it is not a MMCdevice then the prefix "stdio:" will be prependedautomatically. This list is empty by default. Else if the path matches the "banned" list thenthe drive will not be accepted by xorriso but ratherlead to a FAILURE event. This list is empty by default. Else if the path matches the "caution" list and ifit is not a MMC device, then its address must have theprefix "stdio:" or it will be rejected. This listhas by default one entry: "/dev". If a drive path matches no list then it is considered"harmless". By default these are all paths whichdo not begin with directory "/dev". A path matches a list if one of its parent paths or itselfmatches a list entry. Address prefix "stdio:" or"mmc:" will be ignored when testing formatches. By pseudo-class "clear_list" andpseudo-patterns "banned","caution", "harmless", or"all", the lists may be made empty. E.g.: -drive_class clear_list banned One will normally define the -drive_class lists in oneof the xorriso Startup Files. Note: This is not a security feature but rather a bumper forthe superuser to prevent inadverted mishaps. For reliablyblocking access to a device file you have to deny itsrw-permissions in the filesystem.

-assert_volid pattern severity

Refuse to load ISO images with volume ids which do notmatch the given search pattern. When refusing an image, giveup the input drive and issue an event of the given severity(like FAILURE, see -abort_on). An empty search patternaccepts any image. This option does not hamper the creation of an empty imagefrom blank input media and does not discard an alreadyloaded image.

-in_charset character_set_name

Set the character set from which to convert file nameswhen loading an image. See paragraph "Charactersets" for more explanations. When loading the writtenimage after -commit the setting of -out_charsetwill be copied to -in_charset.

-auto_charset"on"|"off"

Enable or disable recording and interpretation of theoutput character set name in an xattr attribute of the imageroot directory. If enabled and if a recorded character setname is found, then this name will be used as namoe of theinput character set when reading an image. Note that the default output charset is the local characterset of the terminal wherexorriso runs. Beforeattributing this local character set to the produced ISOimage, check whether the terminal properly displays allintended filenames, especially exotic nationalcharacters.

-hardlinks mode[:mode...]

Enable or disable loading and recording of hardlinkrelations. In default mode "off", iso_rr files lose theirinode numbers at image load time. Each iso_rr file objectwhich has no inode number at image generation time will geta new unique inode number if -compliance is set tonew_rr. Mode "on" preserves inode numbers from the loadedimage if such numbers were recorded. When committing asession it searches for families of iso_rr files which stemfrom the same disk file, have identical content filteringand have identical properties. The family members all getthe same inode number. Whether these numbers are respectedat mount time depends on the operating system. Commands -update and -update_r track splits andfusions of hard links in filesystems which have stabledevice and inode numbers. This can cause automatic lastminute changes before the session gets written. Command-hardlinks "perform_update" may be used todo these changes earlier, e.g. if you need to apply filtersto all updated files. Mode "without_update" avoids hardlink processingduring update commands. Use this if your filesystemsituation does not allow -disk_dev_ino"on". xorriso commands which extract files from an ISO imagetry to hardlink files with identical inode number. Thenormal scope of this operation is from image load to imageload. One may give up the accumulated hard link addresses by-hardlinks "discard_extract". A large number of hardlink families may exhaust-temp_mem_limit if not -osirrox"sort_lba_on" and -hardlinks"cheap_sorted_extract" are both in effect. Thisrestricts hard linking to other files restored by the samesingle extract command. -hardlinks"normal_extract" re-enables wide andexpensive hardlink accumulation.

-acl "on"|"off"

Enable or disable processing of ACLs. If enabled, thenxorriso will obtain ACLs from disk file objects,store ACLs in the ISO image using the libisofs specific AAIPformat, load AAIP data from ISO images, test ACL during filecomparison, and restore ACLs to disk files when extractingthem from ISO images. See also options -getfacl,-setfacl.

-xattr"on"|"off"

Enable or disable processing of xattr attributes in usernamespace. If enabled, thenxorriso will handle xattrsimilar to ACL. See also options -getfattr,-setfattr and above paragraph about xattr.

-md5"on"|"all"|"off"|"load_check_off"

Enable or disable processing of MD5 checksums for theoverall session and for each single data file. If enabledthen images with checksum tags get loaded only if the tagsof superblock and directory tree match properly. The MD5checksums of data files and whole session get loaded fromthe image if there are any. With options -compare and -update the recordedMD5 of a file will be used to avoid content reading from theimage. Only the disk file content will be read and comparedwith that MD5. This can save much time if-disk_dev_ino "on" is not suitable. At image generation time they are computed for each filewhich gets its data written into the new session. Thechecksums of files which have their data in older sessionsget copied into the new session. Superblock, tree and wholesession get a checksum tag each. Mode "all" will additionally check during imagegeneration whether the checksum of a data file changedbetween the time when its reading began and the time when itended. This implies reading every file twice. Mode "load_check_off" together with "on"or "all" will load recorded MD5 sums but not testthe recorded checksum tags of superblock and directory tree.This is necessary if growisofs was used as burn program,because it does not overwrite the superblock checksum tag ofthe first session. Therefore load_check_off is in effectwhen xorriso -as mkisofs option -M isperformed. The test can be re-enabled by mode"load_check_on". Checksums can be exploited via options -check_md5,-check_md5_r, via find actions get_md5, check_md5, andvia -check_media.

-for_backup

Enable all extra features which help to produce or torestore backups with highest fidelity of file properties.Currently this is a shortcut for: -hardlinks on-acl on -xattr on -md5 on.

-disk_dev_ino"on"|"ino_only"|"off"

Enable or disable processing of recorded fileidentification numbers (dev_t and ino_t). If enabled theyare stored as xattr and allow to substantially acceleratefile comparison. The root node gets a global starttimestamp. If during comparison a file with youngertimestamps is found in the ISO image, then it is suspectedto have inconsistent content. If device numbers and inode numbers of the disk filesystemsare persistent and if no irregular alterations of timestampsor system clock happen, then potential content changes canbe detected without reading that content. File contentchange is assumed if any of mtime, ctime, device number orinode number have changed. Mode "ino_only" replaces the precondition thatdevice numbers are stable by the precondition that mountpoints in the compared tree always lead to the samefilesystems. Use this if mode "on" always sees allfiles changed. The speed advantage appears only if the loaded session wasproduced with -disk_dev_ino "on" too. Note that -disk_dev_ino "off" is totally ineffect only if -hardlinks is "off", too.

-rom_toc_scan"on"|"force"|"off"[:"emul_on"|"emul_off"]

Read-only drives do not tell the actual media typebut show any media as ROM (e.g. as DVD-ROM). Thesession history of MMC multi-session media might betruncated to first and last session or even be completelyfalse. (The emulated history of overwriteable media is notaffected by this.) To have in case of failure a chance of getting the sessionhistory and especially the address of the last session,there is a scan for ISO 9660 filesystem headers which mighthelp but also might yield worse results than thedrive’s table of content. At its end it can cause readattempts to invalid addresses and thus ugly drive behavior.Setting "on" enables that scan for allegedread-only media. Some operating systems are not able to mount the most recentsession of multi-session DVD or BD. If on such asystemxorriso has no own MMC capabilities then itmay still find that session from a scanned table of content.Setting "force" handles any media like a ROMmedium with setting "on". On the other hand the emulation of session history onoverwriteable media can hamper reading of partly damagedmedia. Setting "off:emul_off" disables theelsewise trustworthy table-of-content scan forthose media. To be in effect, the -rom_toc_scan setting has to bemade before the -*dev command which aquires drive andmedium.

-calm_drive"in"|"out"|"all"|"revoke"|"on"|"off"

Reduce drive noise until it is actually used again. Somedrives stay alert for substantial time after they have beenused for reading. This reduces the startup time for the nextdrive operation but can be loud and waste energy if no i/owith the drive is expected to happen soon. Modes "in", "out", "all"immediately calm down -indev, -outdev, resp.both. Mode "revoke" immediately alerts both. Mode"on" causes -calm_drive to be performedautomatically after each -dev, -indev, and-outdev. Mode "off" disables this.

-ban_stdio_write

Allow for writing only the usage of MMC optical drives.Disallow to write the result into files of nearly arbitrarytype. Once set, this command cannot be revoked.

-early_stdio_test"on"|"appendable_wo"|"off"

If enabled by "on" then regular files and blockdevices get tested for effective access permissions. Thisimplies to try opening those files for writing, whichotherwise will happen only later and only if actual writingis desired. The test result is used for classifying the pseudo drives asoverwriteable, read-only, write-only, oruselessly empty. This may lead to earlier detection ofsevere problems, and may avoid some less severe errorevents. Mode "appendable_wo" is like "on" withthe additional property that non-emptywrite-only files are regarded as appendable ratherthan blank.

Inserting files into ISO image:

The following commands expect file addresses of twokinds: disk_path is a path to an object in the local filesystemtree. iso_rr_path is the Rock Ridge name of a file object inthe ISO image. (Do not confuse with the lowlevel ISO 9660names visible if Rock Ridge gets ignored.) Note that in the ISO image you are as powerful as thesuperuser. Access permissions of the existing files in theimage do not apply to your write operations. They areintended to be in effect with the read-only mountedimage. If the iso_rr_path of a newly inserted file leads to anexisting file object in the ISO image, then the followingcollision handling happens: If both objects are directories then they get merged byrecursively inserting the subobjects from filesystem intoISO image. If other file types collide then the setting ofcommand-overwrite decides. Renaming of files has similar collision handling, butdirectories can only be replaced, not merged. Note that ifthe target directory exists, then -mv inserts thesource objects into this directory rather than attempting toreplace it. The commands in this section alter the ISO image and notthe local filesystem.

-disk_pattern"on"|"ls"|"off"

Set the pattern expansion mode for the disk_patharguments of several commands which support thisfeature. Setting "off" disables this feature for allcommands which are marked in this man page by"disk_path [***]" or "disk_pattern[***]". Setting "on" enables it for all thosecommands. Setting "ls" enables it only for those which aremarked by "disk_pattern [***]". Default is "ls".

-add pathspec [...] | disk_path[***]

Insert the given files or directory trees from filesysteminto the ISO image. If -pathspecs is set to "on" then patternexpansion is always disabled and character ’=’has a special meaning. It separates the ISO image path fromthe disk path: iso_rr_path=disk_path The separator ’=’ can be escaped by’\’. If iso_rr_path does not begin with’/’ then -cd is prepended. If disk_pathdoes not begin with ’/’ then -cdx isprepended. If no ’=’ is given then the word is used asboth, iso_rr_path and disk path. If in this case the worddoes not begin with ’/’ then -cdx isprepended to the disk_path and -cd is prepended to theiso_rr_path. If -pathspecs is set to "off" then-disk_pattern expansion applies, if enabled. Theresulting words are used as both, iso_rr_path and disk path.Relative path words get prepended the setting of -cdxto disk_path and the setting of -cd toiso_rr_path.

-add_plainly mode

If set to mode "unknown" then any command wordthat does not begin with "-" and is notrecognized as known command will be subject to a virtual-add command. I.e. it will be used as pathspec or asdisk_path and added to the image. If enabled,-disk_pattern expansion applies to disk_paths. Mode "dashed" is similar to "unknown"but also adds unrecognized command words even if they beginwith "-". Mode "any" announces that all further words are tobe added as pathspecs or disk_paths. This does not work indialog mode. Mode "none" is the default. It prevents any wordsfrom being understood as files to add, if they are notparameters to appropriate commands.

-path_list disk_path

Like -add but read the parameter words from filedisk_path or standard input if disk_path is"-". The list must contain exactly onepathspec resp. disk_path pattern per line.

-quoted_path_list disk_path

Like -path_list but with quoted input readingrules. Lines get split into parameter words for -add.Whitespace outside quotes is discarded.

-map disk_path iso_rr_path

Insert file object disk_path into the ISO image asiso_rr_path. If disk_path is a directory then its whole subtree is inserted into the ISO image.

-map_single disk_path iso_rr_path

Like -map, but if disk_path is a directory then itssub tree is not inserted.

-map_l disk_prefix iso_rr_prefix disk_path[***]

Perform -map with each of the disk_path arguments.iso_rr_path will be composed from disk_path by replacingdisk_prefix by iso_rr_prefix.

-update disk_path iso_rr_path

Compare file object disk_path with file objectiso_rr_path. If they do not match, then perform thenecessary image manipulations to make iso_rr_path a matchingcopy of disk_path. By default this comparison will implylengthy content reading before a decision is made. Options-disk_dev_ino or -md5 may accelerate comparisonif they were already in effect when the loaded session wasrecorded. If disk_path is a directory and iso_rr_path does not existyet, then the whole subtree will be inserted. Else onlydirectory attributes will be updated.

-update_r disk_path iso_rr_path

Like -update but working recursively. I.e. all fileobjects below both addresses get compared whether they havecounterparts below the other address and whether bothcounterparts match. If there is a mismatch then thenecessary update manipulation is done. Note that the comparison result may depend on option-follow. Its setting should always be the same as withthe first adding of disk_path as iso_rr_path. If iso_rr_path does not exist yet, then it gets added. Ifdisk_path does not exist, then iso_rr_path gets deleted.

-update_l disk_prefix iso_rr_prefixdisk_path [***]

Perform -update_r with each of the disk_patharguments. iso_rr_path will be composed from disk_path byreplacing disk_prefix by iso_rr_prefix.

-cut_out disk_path byte_offset byte_countiso_rr_path

Map a byte interval of a regular disk file into a regularfile in the ISO image. This may be necessary if the diskfile is larger than a single medium, or if it exceeds thetraditional limit of 2 GiB - 1 for old operatingsystems, or the limit of 4 GiB - 1 for newer ones.Only the newest Linux kernels seem to read properly files>= 4 GiB - 1. A clumsy remedy for this limit is to backup file pieces andto concatenate them at restore time. A well tested choppingsize is 2047m. It is permissible to request a higherbyte_count than available. The resulting file will betruncated to the correct size of a final piece. To request abyte_offset higher than available yields no file in the ISOimage but a SORRY event. E.g: -cut_out /my/disk/file 0 2047m \ /file/part_1_of_3_at_0_with_2047m_of_5753194821 \ -cut_out /my/disk/file 2047m 2047m \ /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \ -cut_out /my/disk/file 4094m 2047m \ /file/part_3_of_3_at_4094m_with_2047m_of_5753194821 While option -split_size is set larger than 0, and ifall pieces of a file reside in the same ISO directory withno other files, and if the names look like above, then theirISO directory will be recognized and handled like a regularfile. This affects options -compare*, -update*,and overwrite situations. See option -split_size fordetails.

-cpr disk_path [***] iso_rr_path

Insert the given files or directory trees from filesysteminto the ISO image. The rules for generating the ISO addresses are similar aswith shell command cp -r. Nevertheless, directories ofthe iso_rr_path are created if necessary. Especially a notyet existing iso_rr_path will be handled as directory ifmultiple disk_paths are present. The leafnames of themultiple disk_paths will be grafted under that directory aswould be done with an existing directory. If a single disk_path is present then a non-existingiso_rr_path will 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 beginwith ’/’ then -cd is prepended.

-mkdir iso_rr_path [...]

Create empty directories if they do not exist yet.Existence as directory generates a WARNING event, existenceas other file causes a FAILURE event.

-clone iso_rr_path_originaliso_rr_path_copy

Create a copy of the ISO file object iso_rr_path_originalwith the new address iso_rr_path_copy. If the original is adirectory then copy all files and directories underneath. Ifiso_rr_path_original is a boot catalog file, then it getsnot copied but is silently ignored. The copied ISO file objects have the same attributes. Copieddata files refer to the same content source as theiroriginals. The copies may then be manipulated independendlyof their originals. This command will refuse execution if the addressiso_rr_path_copy already exists in the ISO tree.

-cp_clone iso_rr_path_original [***]iso_rr_path_dest

Create copies of one or more ISO file objects as withcommand -clone. In case of collision merge directorieswith existing ones, but do not overwrite existing ISO fileobjects. The rules for generating the copy addresses are the same aswith command -cpr (see above) resp. shell command cp-r. Other than with -cpr, relativeiso_rr_path_original will get prepended the -cd pathand not the -cdx path. Consider to -mkdiriso_rr_path_dest before -cp_clone so the copy addressdoes not depend on the number of iso_rr_path_originalarguments.

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 onlyvalue is "off" then the file size is not limitedbyxorriso. Default is a limit of 100 extents, 4g-2k each: -file_size_limit 400g -200k -- When mounting ISO 9660 filesystems, old operating systemscan handle only files up to 2g -1 --.Newer ones are good up to 4g -1 --. Youneed quite a new Linux kernel to read correctly the finalbytes of a file >= 4g if its size is not aligned to 2048byte blocks. xorriso’s own data read capabilities are notaffected by operating system size limits. Such limits applyto 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 tothe ISO image and before disk files get compared with imagefiles. The absolute disk path of the source is matchedagainst the -not_paths list. The leafname of the diskpath is matched against the patterns in the -not_leaflist. If a match is detected then the disk path will not beregarded as an existing file and not be added to the ISOimage. Several codes are defined. The _on/_off settings persistuntil they are revoked by their_off/_on counterparts. "erase" empties the lists which were accumulatedby -not_paths and -not_leaf. "reset" is like "erase" but alsore-installs default behavior. "off" disables exclusion processing temporarilywithout invalidating the lists and settings. "on" re-enables exclusion processing. "param_off" applies exclusion processing only topaths below disk_path parameter of commands. I.e. explicitlygiven disk_paths are exempted from exclusion processing. "param_on" applies exclusion processing to commandparameters as well as to files below such parameters. "subtree_off" with "param_on" excludesparameter paths only if they match a -not_paths itemexactly. "subtree_on" additionally excludes parameter pathswhich lead to a file address below any -not_pathsitem. "ignore_off" treats excluded disk files as if theywere missing. I.e. they get reported with -compare anddeleted 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 diskpaths. If a given path is relative, then the current-cdx is prepended to form an absolute path. Patternmatching, if enabled, happens at definition time and notwhen 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 ofexclusions for disk leafnames. These patterns are evaluatedwhen 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, oras -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_pathsresp. -not_leaf.

-follow occasion[:occasion[...]]

Enable or disable resolution of symbolic links andmountpoints 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 itstarget file object. If enabled then symbolic links arehandled as their target file objects, else symbolic linksare handled as themselves. "mount" is the hop from one filesystem to anothersubordinate filesystem. If enabled then mountpointdirectories are handled as any other directory, elsemountpoints are handled as empty directories if they areencountered in directory tree traversals. Less general than above occasions: "pattern" is mount and link hopping, but onlyduring -disk_pattern expansion. "param" is link hopping for parameter words (aftereventual pattern expansion). If enabled then -ls*xwill show the link targets rather than the links themselves.-du*x, -findx, and -add will process thelink targets but not follow links in an eventual directorytree below the targets (unless "link" isenabled). Occasions can be combined in a colon separated list. Alloccasions mentioned in the list will then lead to a positivefollow decision. "off" prevents any positive follow decision. Useit 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="<number> which sets the maximumnumber of link hops. A link hop consists of a sequence ofsymbolic 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 stopshopping at the first repetition of a link target. Then therepeated link is handled as itself and not as its target.Regrettably one can construct link networks which causeexponential workload before their loops get detected. Thenumber given with "limit=" can curb this workloadat the risk of truncating an intentional sequence of linkhops.

-pathspecs"on"|"off"

Control parameter interpretation with xorrisoactions -add and -path_list. "on" enables pathspecs of the formtarget=source like with program mkisofs-graft-points. It also disables-disk_pattern expansion for command -add. "off" disables pathspecs of the form target=sourceand re-enables -disk_pattern expansion.

-overwrite"on"|"nondir"|"off"

Allow or disallow to overwrite existing files in the ISOimage by files with the same name. With setting "off", name collisions cause FAILUREevents. With setting "nondir", only directoriesare protected by such events, other existing file types gettreated with -rm before the new file gets added.Setting "on" allows automatic -rm_r. I.e. anon-directory can replace an existing directory andall its subordinates. If restoring of files is enabled, then the overwrite ruleapplies to the target file objects on disk as well, but"on" is downgraded to "nondir".

-split_sizenumber["k"|"m"]

Set the threshold for automatic splitting of regularfiles. Such splitting maps a large disk file onto a ISOdirectory with several part files in it. This is necessaryif the size of the disk file exceeds -file_size_limit.Older operating systems can handle files in mounted ISO 9660filesystems only if they are smaller than 2 GiB resp. 4GiB. 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 adirectory with split file pieces will be recognized andhandled 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 whenfiles get restored to disk. In order to be recognizable, the names of the part fileshave 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" aretaken 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 haveto be present and their numbers have to be plausible. E.g.byte_count must be valid as -cut_out argument andtheir contents may not overlap.

File manipulations:

The following commands manipulate files in the ISO image,regardless whether they stem from the loaded image or werenewly inserted.

-iso_rr_pattern"on"|"ls"|"off"

Set the pattern expansion mode for the iso_rr_patharguments of several commands which support thisfeature. Setting "off" disables pattern expansion for allcommands which are marked in this man page by"iso_rr_path [***]" or "iso_rr_pattern[***]". Setting "on" enables it for all thosecommands. Setting "ls" enables it only for those which aremarked 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 -indevmedium, even if the deletion is committed to that samemedium. The image size will shrink if the image is written to adifferent medium in modification mode.

-rm_r iso_rr_path [***]

Delete the given files or directory trees from the ISOimage. 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 lastargument in the list. Use the same rules as with shellcommand mv. If pattern expansion is enabled and if the last argumentcontains wildcard characters then it must match exactly oneexisting file address, or else the command fails with aFAILURE event.

-chown uid iso_rr_path [***]

Set ownership of file objects in the ISO image. uid mayeither be a decimal number or the name of a user known tothe operating system.

-chown_r uid iso_rr_path [***]

Like -chown but affecting all files below eventualdirectories.

-chgrp gid iso_rr_path [***]

Set group attribute of file objects in the ISO image. gidmay either be a decimal number or the name of a group knownto the operating system.

-chgrp_r gid iso_rr_path [***]

Like -chgrp but affecting all files below eventualdirectories.

-chmod mode iso_rr_path [***]

Equivalent to shell command chmod in the ISO image. modeis either an octal number beginning with "0" or acomma separated list of statements of the form[ugoa]*[+-=][rwxst]* . Like: go-rwx,u+rwx . Personalities: u=user, g=group, o=others, a=all Operators: + adds given permissions, - revokesgiven permissions, = revokes all old permissions and thenadds the given ones. Permissions: r=read, w=write, x=execute|inspect,s=setuid|setgid, t=sticky bit For octal numbers see man 2 stat.

-chmod_r mode iso_rr_path [***]

Like -chmod but affecting all files below eventualdirectories.

-setfacl acl_text iso_rr_path [***]

Attach the given ACL to the given iso_rr_paths. If thefiles already have ACLs, then those get deleted before thenew ones get into effect. If acl_text is empty, or containsthe text "clear" or the text"--remove-all", then theexisting ACLs will be removed and no new ones will beattached. Any other content of acl_text will be interpretedas a list of ACL entries. It may be in the longmulti-line format as put out by -getfacl but mayalso be abbreviated as follows: ACL entries are separated by comma or newline. If an entryis empty text or begins with "#" then it will beignored. A valid entry has to begin by a letter out of{ugom} for "user", "group","other", "mask". It has to contain twocolons ":". A non-empty text between those":" gives a user id resp. group id. After thesecond ":" there may be letters out of {rwx-#}. The first three give read, write resp. executepermission. Letters "-", " " andTAB are ignored. "#" causes the rest of the entryto be ignored. Letter "X" or any other letters arenot supported. Examples: g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw- A valid entry may be prefixed by "d", somefollowing characters and ":". This indicates thatthe entry goes to the "default" ACL rather than tothe "access" ACL. Example: u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx

-setfacl_r acl_text iso_rr_path[***]

Like -setfacl but affecting all files beloweventual directories.

-setfacl_list disk_path

Read the output of -getfacl_r or shell commandgetfacl -R and apply it to the iso_rr_paths as givenin lines beginning with "# file:". This willchange ownership, group and ACL of the given files. Ifdisk_path is "-" then lines are read fromstandard input. Line "@" ends the list,"@@@" aborts without changing the pendingiso_rr_path. Since -getfacl and getfacl -R strip leading"/" from file paths, the setting of -cd doesalways matter.

-setfattr [-]name value iso_rr_path[***]

Attach the given xattr pair of name and value to thegiven iso_rr_paths. If the given name is prefixed by"-", then the pair with that name getsremoved from the xattr list. If name is"--remove-all" then all usernamespace xattr of the given iso_rr_paths get deleted. Incase of deletion, value must be an empty text. Only names from the user namespace are allowed. I.e. a namehas to begin with "user.", like "user.x"or "user.whatever". Values and names undergo the normal input processing ofxorriso. See also option -backslash_codes.Other than with option -setfattr_list, the byte value0 cannot be expressed via -setfattr.

-setfattr_r [-]name value iso_rr_path[***]

Like -setfattr but affecting all files beloweventual directories.

-setfattr_list disk_path

Read the output of -getfattr_r or shell commandgetfattr -Rd and apply it to the iso_rr_paths as givenin lines beginning with "# file:". All previouslyexisting user space xattr of the given iso_rr_paths will bedeleted. If disk_path is "-" then lines areread from standard input. Since -getfattr and getfattr -Rd strip leading"/" from file paths, the setting of -cd doesalways matter. Empty input lines and lines which begin by "#"will be ignored (except "# file:"). Line"@" ends the list, "@@@" aborts withoutchanging the pending iso_rr_path. Other input lines musthave the form name="value" Name must be from user namespace. I.e. user.xyz where xyzshould consist of printable characters only. The separator"=" is not allowed in names. Value may contain anykind of bytes. It must be in quotes. Trailing whitespaceafter the end quote will be ignored. Non-printablesbytes and quotes must be represented as \XYZ by their octalASCII code XYZ. Use code \000 for 0-bytes.

-alter_date type timestring iso_rr_path[***]

Alter the date entries of a file in the ISO image. typeis one of "a", "m", "b" foraccess time, modification time, both times. timestring may be in the following formats (see also sectionEXAMPLES): As expected by program date: MMDDhhmm[[CC]YY][.ss]] As produced by program date: [Day] MMM DD hh:mm:ss [TZON] YYYY Relative times counted from current clock time: +|-Number["s"|"h"|"d"|"w"|"m"|"y"] where "s" means seconds, "h" hours,"d" days, "w" weeks, "m"=30d,"y"=365.25d plus 1d added to multiplicationresult. Absolute seconds counted from Jan 1 1970: =Number xorriso’s own timestamps: YYYY.MM.DD[.hh[mm[ss]]] scdbackup timestamps: YYMMDD[.hhmm[ss]] where "A0" is year 2000, "B0" is 2010,etc.

-alter_date_r type timestring iso_rr_path[***]

Like -alter_date but affecting all files beloweventual directories.

-hide hide_state iso_rr_path [***]

Prevent the names of the given files from showing up inthe directory trees of ISO 9660 and/or Joliet when the imagegets written. The data content of such hidden files will beincluded in the resulting image, even if they do not show upin any directory. But you will need own means to findnameless data in the image. Warning: Data which are hidden from the ISO 9660 tree willnot be copied by the write method of modifying. Possible values of hide_state are: "iso_rr" forhiding from ISO 9660 tree, "joliet" for Joliettree, "on" for both trees. "off" meansvisibility in both directory trees. This command does not apply to the boot catalog. Rather use:-boot_image "any""cat_hidden=on"

Tree traversal command -find:

-find iso_rr_path [test [op] [test ...]][-exec action [params]] --

A restricted substitute for shell command find in the ISOimage. It performs an action on matching file objects at orbelow iso_rr_path. If not used as last command in the line then the argumentlist needs to get terminated by"--". Tests are optional. If they are omitted then action isapplied to all file objects. If tests are given then theyform together an expression. The action is applied only ifthe expression matches the file object. Default expressionoperator between tests is -and, i.e. the expressionmatches only if all its tests match. Available tests are: -name pattern : Matches if pattern matches thefile leaf name. -wholename pattern : Matches if pattern matchesthe file path as it would be printed by action"echo". Character ’/’ is not specialbut can be matched by wildcards. -disk_name pattern : Like -name but testingthe leaf name of the file source on disk. Can be true onlyfor data files which stem not from the loaded image. -type type_letter : Matches files of the giventype: "block", "char", "dir","pipe", "file", "link","socket", "eltorito", and"Xotic" which matches what is not matched by theother types. Only the first letter is interpreted. E.g.: -find /-type d -damaged : Matches files which use data blocksmarked as damaged by a previous run of -check_media.The damage info vanishes when a new ISO image getsloaded. Note that a MD5 session mismatch marks all files of thesession as damaged. If finer distinction is desired, perform-md5 off before -check_media. -pending_data : Matches files which get theircontent from outside the loaded ISO image. -lba_range start_lba block_count : Matches fileswhich use data blocks within the range of start_lba andstart_lba+block_count-1. -has_acl : Matches files which have anon-trivial ACL. -has_xattr : Matches files which have xattrname-value pairs from user namespace. -has_aaip : Matches files which have ACL or anyxattr. -has_any_xattr : Matches files which have anyxattr other than ACL. -has_md5 : Matches data files which have MD5checksums. -has_filter : Matches files which are filtered by-set_filter. -hidden hide_state : Matches files which arehidden in "iso_rr" tree, in "joliet"tree, in both trees ("on"), or not hidden in anytree ("off"). Those which are hidden in some treematch -not -hidden "off". -prune : If this test is reached and the testedfile is a directory then -find will not dive into thatdirectory. This test itself does always match. -decision "yes"|"no" : If thistest is reached then the evaluation ends immediately andaction is performed if the decision is "yes" or"true". See operator -if. -true and -false : Always match resp.match not. Evaluation goes on. -sort_lba : Always match. This causes -findto perform its action in a sequence sorted by the ISO imageblock addresses of the files. It may improve throughput withactions which read data from optical drives. Action willalways get the absolute path as parameter. Available operators are: -not : Matches if the next test or sub expressiondoes not match. Several tests do this specifically: -undamaged, -lba_range with negative start_lba,-has_no_acl, -has_no_xattr, -has_no_aaip,-has_no_filter . -and : Matches if both neighboring tests orexpressions match. -or : Matches if at least one of both neighboringtests or expressions matches. -sub ... -subend or ( ...) : Enclose a sub expression which gets evaluatedfirst before it is processed by neighboring operators.Normal precedence is: -not, -or ,-and. -if ... -then ...-elseif ... -then ...-else ...-endif : Enclose one ormore sub expressions. If the -if expression matches,then the -then expression is evaluated as the resultof the whole expression up to -endif. Else the next-elseif expression is evaluated and if it matches, its-then expression. Finally in case of no match, the-else expression is evaluated. There may be more thanone -elseif. Neither -else nor -elseif aremandatory. If -else is missing and would be hit, thenthe result is a non-match. -if-expressions are the main use case for abovetest -decision. Default action is echo, i.e. to print the addressof the found file. Other actions are certainxorrisocommands which get performed on the found files. Thesecommands may have specific parameters. See also theirparticular descriptions. chown and chown_r change the ownership and getthe user id as parameter. E.g.: -exec chown thomas-- chgrp and chgrp_r change the group attribute andget the group id as parameter. E.g.: -exec chgrp_rstaff -- chmod and chmod_r change access permissions andget a mode string as parameter. E.g.: -exec chmoda-w,a+r -- alter_date and alter_date_r change thetimestamps. They get a type character and a timestring asparameters. E.g.: -exec alter_date "m" "Dec 3019:34:12 2007" -- lsdl prints file information like shell command ls-dl. compare performs command -compare with the foundfile address as iso_rr_path and the corresponding fileaddress below its argument disk_path_start. For this theiso_rr_path of the -find command gets replaced by thedisk_path_start. E.g.: -find /thomas -exec compare /home/thomas-- update performs command -update with the foundfile address as iso_rr_path. The corresponding file addressis determined like with above action"compare". update_merge is like update but does not delete thefound file if it is missing on disk. It may be run severaltimes and records with all visited files whether theircounterpart on disk has already been seen by one of theupdate_merge runs. Finally, a -find run with action"rm_merge" may remove all files that saw nocounterpart on disk. Up to the next "rm_merge" or"clear_merge" all newly inserted files will getmarked as having a disk counterpart. rm removes the found iso_rr_path from the image if it isnot a directory with files in it. I.e. this "rm"includes "rmdir". rm_r removes the found iso_rr_path from the image,including whole directory trees. rm_merge removes the found iso_rr_path if it was visitedby one or more previous actions "update_merge" andsaw no counterpart on disk in any of them. The marking fromthe update actions is removed in any case. clear_merge removes an eventual marking from action"update_merge". report_damage classifies files whether they hit a datablock that is marked as damaged. The result is printedtogether with the address of the first damaged byte, themaximum span of damages, file size, and the path of thefile. report_lba prints files which are associated to imagedata blocks. It tells the logical block address, the blocknumber, the byte size, and the path of each file. There maybe reported more than one line per file if the file is verylarge. In this case each line has a different extent numberin column "xt". getfacl prints access permissions in ACL text form tothe result channel. setfacl attaches ACLs after removing existing ones. Thenew ACL is given in text form as defined with option-setfacl. E.g.: -exec setfaclu:lisa:rw,u::rw,g::r,o::-,m::rw -- getfattr prints xattr name-value pairs from usernamespace to the result channel. get_any_xattr prints xattr name-value pairs fromany namespace except ACL to the result channel. This ismostly for debugging of namespace "isofs". list_extattr mode prints a script to the result channel,which would use FreeBSD command setextattr to set thefile’s xattr name-value pairs of user namespace.Parameter mode controls the form of the output of names andvalues. Default mode "e" prints harmlesscharacters in shell quotation marks, but represents textswith octal 001 to 037 and 0177 to 0377 by an embedded echo-e command. Mode "q" prints any charactersin shell quotation marks. This might not beterminal-safe but should work in script files. Mode"r" uses no quotation marks. Not safe. Mode"b" prints backslash encoding. Not suitable forshell parsing. E.g. -exec list_extattr e -- Option -backslash_codes does not affect theoutput. get_md5 prints the MD5 sum, if recorded, together withfile path. check_md5 compares the MD5 sum, if recorded, with thefile content and reports if mismatch. E.g.: -find / -not -pending_data-exec check_md5 FAILURE -- make_md5 equips a data file with an MD5 sum of itscontent. Useful to upgrade the files in the loaded image tofull MD5 coverage by the next commit with -md5"on". E.g.: -find / -type f -not -has_md5-exec make_md5 -- setfattr sets or deletes xattr name value pairs. E.g.: -find / -has_xattr -exec setfattr--remove-all ’’-- set_filter applies or removes filters. E.g.: -exec set_filter --zisofs-- mkisofs_r applies the rules of mkisofs -r to thefile object: user id and group id become 0, all r-permissions getgranted, all w denied. If there is any x-permission,then all three x get granted. s- and t-bits getremoved. sort_weight attributes a LBA weight number to regularfiles. The number may range from -2147483648 to 2147483647.The higher it is, the lower will be the block address of thefile data in the emerging ISO image. Currently the bootcatalog has a hardcoded weight of 1 billion. Normally itshould occupy the block with the lowest possible address.Data files get added or loaded with initial weight 0. E.g.: -exec sort_weight 3 -- show_stream shows the content stream chain of a datafile. hide brings the file into one of the hide states"on", "iso_rr", "joliet","off". E.g.: -find / -disk_name *_secret -exec hideon estimate_size prints a lower and an upper estimation ofthe number of blocks which the found files together willoccupy in the emerging ISO image. This does not account forthe superblock, for the directories in the -find path,or for image padding. find performs another run of -find on the matchingfile address. It accepts the same params as -find,except iso_rr_path. E.g.: -find / -name ’???’ -type d-exec find -name ’[abc]*’-exec chmod a-w,a+r --

Filters for data file content:

Filters may be installed between data files in theISO image and their content source outside the image. Theymay also be used vice versa between data content in theimage and target files on disk. Built-in filters are "--zisofs"and "--zisofs-decode". Theformer is to be applied via -set_filter, the latter isautomatically applied if zisofs compressed content isdetected 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 andgunzip but avoid forking a process for each single file. Sothey 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 aprogram path, program arguments, and some behavioraloptions. Once registered it can be applied to multiple datafiles in the ISO image, regardless whether their contentresides in the loaded ISO image or in the local filesystem.External filter processes may produce synthetic file contentby reading the original content from stdin and writing tostdout whatever they want. They must deliver the same outputon the same input in repeated runs. Options are: "default" means that no other option isintended. "suffix=..." sets a file name suffix. If it is notempty then it will be appended to the file name or removedfrom it. "remove_suffix" will remove a file name suffixrather than appending it. "if_nonempty" will leave 0-sized filesunfiltered. "if_reduction" will try filtering and revoke it ifthe content size does not shrink. "if_block_reduction" will revoke if the number of2 kB blocks does not shrink. "used=..." is ignored. Command -status showsit with the number of files which currently have the filterapplied. 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 isonly possible if the filter is not applied to any file inthe ISO image.

-close_filter_list

Irrevocably ban commands -external_filter and-unregister_filter, but not -set_filter. Usethis to prevent external filtering in general or when allintended filters are registered. External filters may alsobe banned totally at compile time ofxorriso. Bydefault they are banned if xorriso runs under setuidpermission.

-set_filter name iso_rr_path [***]

Apply an -external_filter or a built-infilter to the given data files in the ISO image. If thefilter suffix is not empty , then it will be applied to thefile name. Renaming only happens if the filter really getsattached and is not revoked by its options. By default fileswhich already bear the suffix will not get filtered. Theothers will get the suffix appended to their names. If thefilter has option "remove_suffix", then the filterwill only be applied if the suffix is present and can beremoved. Name oversize or collision caused by suffix changewill prevent filtering. With most filter types this command will immediately run thefilter once for each file in order to determine the outputsize. Content reading operations like -extract ,-compare and image generation will perform furtherfilter runs and deliver filtered content. At image generation time the filter output must still be thesame as the output from the first run. Filtering for imagegeneration does not happen with files from the loaded ISOimage 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 suffix renamings aswell. Use"--remove-all-filters+" toprevent any suffix renaming.

-set_filter_r name iso_rr_path[***]

Like -set_filter but affecting all data files beloweventual directories.

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 programend is desired.)

-commit

Perform the write operation. Afterwards, if -outdevis readable, make it the new -dev and load the imagefrom there. Switch to growing mode. (A subsequent-outdev will activate modification mode or blindgrowing.) -commit is performed automatically at end ofprogram if there are uncommitted manipulations pending. So, to perform a final write operation with no new-dev and no new loading of image, rather executeoption -end. If you want to go on without imageloading, execute -commit_eject "none". Toeject after write without image loading, use-commit_eject "all". To suppress a final write, execute -rollback_end. Writing can last quite a while. It is not unnormal withseveral types of media that there is no progress visible forthe first few minutes or that the drive gnaws on the mediumfor a few minutes after all data have been transmitted.xorriso and the drives are in a client-serverrelationship. The drives have much freedom about what to dowith the media. Some combinations of drives and media simplydo not work, despite the promises by their vendors. Ifwriting fails then try other media or another drive. Thereason for such failure is hardly ever in the code of thevarious burn programs but you may well try some of thoselisted below under SEE ALSO.

-eject"in"|"out"|"all"

Eject the medium in -indev, resp. -outdev,resp. both drives. Note: It is not possible yet toeffectively eject disk files.

-commit_eject"in"|"out"|"all"|"none"

Combined -commit and -eject. When writing hasfinished do not make -outdev the new -dev, andload no ISO image. Rather eject -indev and/or-outdev. Give up any non-ejected drive.

-blank mode

Make media ready for writing from scratch (if not-dummy is activated). This affects only the -outdev not the -indev. Ifboth drives are the same and if the ISO image was alteredthen this command leads to a FAILURE event. Defined modesare: as_needed, fast, all, deformat, deformat_quickest "as_needed" cares for used CD-RW,DVD-RW and for used overwriteable media by applying-blank "fast". It applies -format"full" to yet unformatted DVD-RAM andBD-RE. Other media in blank state are gracefullyignored. Media which cannot be made ready for writing fromscratch cause a FAILURE event. "fast" makes CD-RW and unformattedDVD-RW re-usable, or invalidates overwriteableISO images. "all" might work more thoroughly andneed more time. "deformat" converts overwriteable DVD-RWinto unformatted ones. "deformat_quickest" is a faster way to deformat orblank DVD-RW but produces media which are onlysuitable for a single session. Some drives announce thisstate by not offering feature 21h, but some drives offer itanyway. If feature 21h is missing, thenxorriso willrefuse to write on DVD-RW if not option -closeis set to "on". The progress reports issued by some drives while blankingare quite unrealistic. Do not conclude success or failurefrom the reported percentages. Blanking was successful if noSORRY event or worse occured.

-format mode

Convert unformatted DVD-RW into overwriteable ones,"de-ice" DVD+RW, format newly purchasedBD-RE or BD-R, re-format DVD-RAM orBD-RE. Defined modes are: as_needed, full, fast, by_index_<num>,fast_by_index_<num> "as_needed" formats yet unformatted DVD-RW,DVD-RAM, BD-RE, or blank unformatted BD-R.Other media are left untouched. "full" (re-)formats DVD-RW, DVD+RW,DVD-RAM, BD-RE, or blank unformattedBD-R. "fast" does the same as "full" but triesto be quicker. "by_index_" selects a format out of the descriptorlist issued by option -list_formats. The index numberfrom that list is to be appended to the mode word. E.g:"by_index_3". "fast_by_index_" does the same as"by_index_" but tries to be quicker. "by_size_" selects a format out of the descriptorlist which provides at least the given size. That size is tobe appended to the mode word. E.g:"by_size_4100m". This applies to media with DefectManagement. "fast_by_size_" does the same as"by_size_" but tries to be quicker. The formatting action has no effect on media if -dummyis activated. Formatting is normally needed only once during the lifetimeof a medium, if ever. But it is a reason forre-formatting if: DVD-RW was deformatted by -blank, DVD+RW has read failures (re-format before nextwrite), DVD-RAM or BD-RE shall change their amount ofdefect reserve. BD-R may be written unformatted or may be formattedbefore first use. Formatting activates Defect Managementwhich tries to catch and repair bad spots on media duringthe write process at the expense of half speed even withflawless media. The progress reports issued by some drives while formattingare quite unrealistic. Do not conclude success or failurefrom the reported percentages. Formatting was successful ifno SORRY event or worse occured. Be patient with apparentlyfrozen progress.

-list_formats

Put out a list of format descriptors as reported by theoutput drive for the current medium. The list gives theindex number after "Format idx", a MMC formatcode, the announced size in blocks (like"2236704s") and the same size in MiB. MMC format codes are manifold. Most important are:"00h" general formatting, "01h"increases reserve space for DVD-RAM, "26h"for DVD+RW, "30h" for BD-RE with reservespace, "31h" for BD-RE without reservespace, "32h" for BD-R. Smaller format size with DVD-RAM, BD-RE, orBD-R means more reserve space.

-list_speeds

Put out a list of speed values as reported by the outputdrive with the loaded medium. This does not necessarily meanthat the medium is writable or that these speeds areactually achievable. Especially the lists reported withempty drive or with ROM media obviously advertise speeds forother media. It is not mandatory to use speed values out of the listedrange. The drive is supposed to choose a safe speed that isas near to the desired speed as possible. At the end of the list, "Write speed L" and"Write speed H" are the best guesses for lower andupper speed limit. "Write speed l" and "Writespeed h" may appear only with CD and eventuallyoverride the list of other speed offers.

-close_damaged"as_needed"|"force"

Try to close the upcomming track and session if the drivereported the medium as damaged. This may apply toCD-R, CD-RW, DVD-R, DVD-RW, DVD+R,DVD+R DL, or BD-R media. It is indicated by warningmessages when the drive gets aquired, and by a remark"but next track is damaged" with the line"Media status :" of command -toc. The setting of option -close determines whether themedium stays appendable. Mode "as_needed" gracefully refuses on media whichare not reported as damaged. Mode "force" attemptsthe close operation even with media which appearundamaged. No image changes are allowed to be pending before thiscommand is performed. After closing was attempted, bothdrives are given up.

-list_profiles"in"|"out"|"all"

Put out a list of media types supported by -indev,resp. -outdev, resp. both. The currently recognizedtype is marked by text "(current)".

Settings for result writing:

Rock Ridge info will be generated by the programunconditionally. ACLs will be written according to thesetting of option -acl.

-joliet"on"|"off"

If enabled by "on", generate Joliet treeadditional to ISO 9660 + Rock Ridge tree.

-compliance rule[:rule...]

Adjust the compliance to specifications of ISO 9660 andits contemporary extensions. In some cases it is worth todeviate a bit in order to circumvent bugs of the intendedreader system or to get unofficial extra features. There are several adjustable rules which have a keywordeach. If they are mentioned with this option then their rulegets added to the relaxation list. This list can be erasedby rules "strict" or "clear". It can bereset to its start setting by "default". All ofthe following relaxation rules can be revoked individuallyby appending "_off". Like"deep_paths_off". Rule keywords are: "iso_9660_level="number chooses level 1 with ISOnames of the form 8.3 and -file_size_limit <= 4g- 1, or level 2 with ISO names up to length 32 and thesame -file_size_limit, or level 3 with ISO names up tolength 32 and -file_size_limit >= 400g -200k.If necessary -file_size_limit gets adjusted. "allow_dir_id_ext" allows ISO names of directoriesto have a name extension as with other file types. It doesnot force dots and it omits the version number, though. Thisis a bad tradition of mkisofs which violates ECMA-119.Especially ISO level 1 only allows 8 characters in adirectory name and not 8.3. "omit_version" does not add versions(";1") to ISO and Joliet file names. "only_iso_version" does not add versions(";1") to Joliet file names. "deep_paths" allows ISO file paths deeper than 8levels. "long_paths" allows ISO file paths longer than 255characters. "long_names" allows up to 37 characters with ISOfile names. "no_force_dots" does not add a dot to ISO filenames which have none. "no_j_force_dots" does not add a dot to Jolietfile names which have none. "lowercase" allows lowercase characters in ISOfile names. "full_ascii" allows all ASCII characters in ISOfile names. "untranslated_names" might be dangerous forinadverted reader programs which rely on the restriction toat most 37 characters in ISO file names. This option allowsISO file names up to 96 characters with no characterconversion. If a file name has more characters, then imageproduction will fail deliberately. "untranslated_name_len="number enablesuntranslated_names with a smaller limit for the length offile names. 0 disables this feature, -1 choosesmaximum length limit, numbers larger than 0 give the desiredlength limit. "joliet_long_names" allows Joliet leaf names up to103 characters rather than 64. "joliet_long_paths" allows Joliet paths longerthan 240 characters. "always_gmt" stores timestamps in GMTrepresentation with timezone 0. "rec_mtime" records with ISO files the diskfile’s mtime and not the creation time of theimage. "new_rr" uses Rock Ridge version 1.12 (suitablefor GNU/Linux but not for older FreeBSD or for Solaris).This implies "aaip_susp_1_10_off" which may bechanged by subsequent "aaip_susp_1_10". Default is "old_rr" which uses Rock Ridge version1.10. This implies also "aaip_susp_1_10" which maybe changed by subsequent "aaip_susp_1_10_off". "aaip_susp_1_10" allows AAIP to be written asunofficial extension of RRIP rather than as officialextension under SUSP-1.12. "no_emul_toc" saves 64 kB with the first sessionon overwriteable media but makes the image incapable ofdisplaying its session history. "iso_9660_1999" causes the production of anadditional directory tree compliant to ISO 9660:1999. It canrecord long filenames for readers which do not understandRock Ridge. "old_empty" uses the old way of of giving blockaddresses in the range of [0,31] to files with no own datacontent. The new way is to have a dedicated block to whichall such files will point. Default setting is "clear:only_iso_version:deep_paths:long_paths:no_j_force_dots: always_gmt:old_rr". Note: The term "ISO file" means the plain ISO 9660names and attributes which get visible if the reader ignoresRock Ridge.

-volid text

Specify the volume ID. xorriso accepts any text upto 32 characters, but according to rarely obeyed specsstricter rules apply: ECMA 119 demands ASCII characters out of[A-Z0-9_]. Like: "IMAGE_23" Joliet allows 16 UCS-2 characters. Like: "Windowsname" Be aware that the volume id might get used automatically asname of the mount point when the medium is inserted into aplayful computer system. If an ISO image gets loaded while the volume ID is set todefault "ISOIMAGE" or to "", then thevolume ID of the loaded image will become the effectivevolume id for the next write run. But as soon as command-volid is performed afterwards, this pending id isoverridden by the new setting. Consider this when setting -volid "ISOIMAGE"before executing -dev, -indev, or-rollback. If you insist in -volid"ISOIMAGE", set it again after those commands.

-volset_id text

Set the volume set id string to be written with the next-commit. Permissible are up to 128 characters. Thissetting gets overridden by image loading.

-publisher text

Set the publisher id string to be written with the next-commit. This may identify the person or organisationwho specified what shall be recorded. Permissible are up to128 characters. This setting gets overridden by imageloading.

-application_id text

Set the application id string to be written with the next-commit. This may identify the specification of howthe data are recorded. Permissible are up to 128 characters.This setting gets overridden by image loading. The special text "@xorriso@" gets converted to theid string of xorriso which is normally written as-preparer_id. It is a wrong tradition to write theprogram id as -application_id.

-system_id text

Set the system id string to be written with the next-commit. This may identify the system which canrecognize and act upon the content of the System Area inimage blocks 0 to 15. Permissible are up to 32 characters.This setting gets overridden by image loading.

-volume_date type timestring

Set one of the four overall timestamps for subsequentimage writing. Available types are: "c" time when the volume was created. "m" time when volume was last modified. "x" time when the information in the volumeexpires. "f" time since when the volume is effectivelyvalid. "uuid" sets a timestring that overrides"c" and "m" times literally. It mustconsist of 16 decimal digits which form YYYYMMDDhhmmsscc,with YYYY between 1970 and 2999. Time zone is GMT. It issupposed to match this GRUB line: search --fs-uuid --setYYYY-MM-DD-hh-mm-ss-cc E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0centiseconds). Timestrings for the other types may be given as with option-alter_date. They are prone to timezone computations.The timestrings "default" or"overridden" cause default settings: "c"and "m" will show the current time of imagecreation. "x" and "f" will be marked asinsignificant. "uuid" will be deactivated.

-copyright_file text

Set the copyright file name to be written with the next-commit. This should be the ISO 9660 path of a file inthe image which contains a copyright statement. Permissibleare up to 37 characters. This setting gets overridden byimage loading.

-abstract_file text

Set the abstract file name to be written with the next-commit. This should be the ISO 9660 path of a file inthe image which contains an abstract statement about theimage content. Permissible are up to 37 characters. Thissetting gets overridden by image loading.

-biblio_file text

Set the biblio file name to be written with the next-commit. This should be the ISO 9660 path of a file inthe image which contains bibliographic records. Permissibleare up to 37 characters. This setting gets overridden byimage loading.

-preparer_id

Set the preparer id string to be written with the next-commit. This may identify the person or other entitywhich controls the preparation of the data which shall berecorded. Normally this should be the id ofxorrisoand not of the person or program which operatesxorriso. Please avoid to change it. Permissible areup to 128 characters. The special text "@xorriso@" gets converted to theid string of xorriso which is default at programstartup. Unlike other id strings, this setting is not influenced byimage loading.

-out_charset character_set_name

Set the character set to which file names get convertedwhen writing an image. See paragraph "Charactersets" for more explanations. When loading the writtenimage after -commit the setting of -out_charsetwill be copied to -in_charset.

-uid uid

User id to be used for all files when the new ISO treegets written to media.

-gid gid

Group id to be used for all files when the new ISO treegets written to media.

-zisofs option[:options]

Set global parameters for zisofs compression. This dataformat is recognized and transparently uncompressed by someLinux kernels. It is to be applied via option-set_filter with built-in filter"--zisofs". Parameters are: "level="[0-9] zlib compression: 0=none,1=fast,..., 9=slow "block_size="32k|64k|128k size of compressionblocks "by_magic=on" enables an expensive test at imagegeneration time which checks files from disk whether theyalready are zisofs compressed, e.g. by program mkzftree. "default" same as"level=6:block_size=32k:by_magic=off"

-speed number[k|m|c|d|b]

Set the burn speed. Default is 0 = maximum speed. Speedcan be given in media dependent numbers or as a desiredthroughput per second in MMC compliant kB (= 1000) or MB (=1000 kB). Media x-speed factor can be set explicity by"c" for CD, "d" for DVD, "b"for BD, "x" is optional. Example speeds:   706k = 706kB/s = 4c = 4xCD   5540k = 5540kB/s = 4d = 4xDVD If there is no hint about the speed unit attached, then themedium in the -outdev will decide. Default unit is CD= 176.4k. MMC drives usually activate their own idea of speed and takethe speed value given by the burn program only as upperlimit for their own decision.

-stream_recording"on"|"off"|"full"|"data"|number

Setting "on" tries to circumvent the managementof defects on DVD-RAM, BD-RE, or BD-R.Defect management keeps partly damaged media usable. But itreduces write speed to half nominal speed even if the mediumis in perfect shape. For the case of flawless media, one mayuse -stream_recording "on" to get fullspeed. "full" tries full speed with all write operations,whereas "on" does this only above byte address32s. One may give a number of at least 16s in order to setan own address limit. "data" causes full speed to start when superblockand directory entries are written and writing of filecontent blocks begins.

-dvd_obs"default"|"32k"|"64k"

GNU/Linux specific: Set the number of bytes to betransmitted with each write operation to DVD or BD media. Anumber of 64 KB may improve throughput with bus systemswhich show latency problems. The default depends on mediatype, on option -stream_recording , and on compiletime options.

-stdio_sync"on"|"off"|number

Set the number of bytes after which to force output tostdio: pseudo drives. This forcing keeps the memory frombeing clogged with lots of pending data for slow devices.Default "on" is the same as "16m".Forced output can be disabled by "off".

-dummy"on"|"off"

If "on" then simulate burning or refuse withFAILURE event if no simulation is possible, do neither blanknor format.

-fsnumber["k"|"m"]

Set the size of the fifo buffer which smoothens the datastream from ISO image generation to media burning. Defaultis 4 MiB, minimum 64 kiB, maximum 1 GiB. The number may befollowed by letter "k" or "m" whichmeans unit is kiB (= 1024) or MiB (= 1024 kiB).

-close"on"|"off"

If "on" then mark the written medium as notappendable any more (if possible at all with the given typeof target media). This is the contrary of cdrecord, wodim, cdrskin option-multi, and is one aspect of growisofs option-dvd-compat.

-paddingnumber["k"|"m"]|"included"|"appended"

Append the given number of extra bytes to the imagestream. This is a traditional remedy for a traditional bugin block device read drivers. Needed only for CD recordingsin TAO mode. Since one can hardly predict on what media animage might end up,xorriso adds the traditional 300kof padding by default to all images. For images which will never get to a CD it is safe to use-padding 0 . Normally padding is not written as part of the ISO image butappended after the image end. This is -padding mode"appended". Emulation command -as "mkisofs" and command-jigdo cause padding to be written as part of theimage. The same effect is achieved by -padding mode"included".

Bootable ISO images:

Contrary to published specifications many BIOSes willload an El Torito record from the first session on media andnot from the last one, which gets mounted by default. Thismakes no problems with overwriteable media, because theyappear to inadverted readers as one single session. But with multi-session media CD-R[W],DVD-R[W], DVD+R, it implies that the whole bootablesystem has to reside already in the first session and thatthe last session still has to bear all files which thebooted system expects after mounting the ISO image. If a boot image from ISOLINUX or GRUB is known to be presenton media then it is advised to patch it when afollow-up session gets written. But one should notrely on the capability to influence the bootability of theexisting sessions, unless one can assume overwriteablemedia. There are booting mechanisms which do not use an El Toritorecord but rather start at the first bytes of the image:PC-BIOS MBR for hard-disk-like devices,MIPS Volume Header for old SGI computers, DEC Boot Block forold DECstation, SUN Disk Label for SPARC machines. The boot firmware EFI may use programs which are located ina FAT filesystem and announced by an MBR partition tableentry.

-boot_image"any"|"isolinux"|"grub"

"discard"|"keep"|"patch"|"show_status"|bootspec|"next" Define the handling of a set of El Torito boot images whichhas been read from an existing ISO image or define how tomake a prepared boot image file set bootable. Such file setsget produced by ISOLINUX or GRUB. Each -boot_image command has two arguments: type andsetting. More than one -boot_image command may be usedto define the handling of one or more boot images. Sequencematters. Types isolinux and grub care for knownpeculiarities. Typeany makes no assumptions aboutthe origin of the boot images. El Torito boot images of any type can be newly inserted,or discarded, or patched, or kept unaltered. Whether topatch or to keep depends on whether the boot images containboot info tables. A boot info table needs to be patched when the boot imagegets newly introduced into the ISO image or if an existingimage gets relocated. This is automatically done if type"isolinux" or "grub" is given, but notwith "any". If patching is enabled, then boot images from previoussessions will be checked whether they seem to bear a bootinfo table. If not, then they stay unpatched. This check isnot infallible. So if you do know that the images need nopatching, use "any" "keep"."grub" "patch" will not patch EFI images(platform_id=0xef). Most safe is the default: -boot_image "any""discard". Advised for GRUB : -boot_image "grub""patch" For ISOLINUX : -boot_image "isolinux""patch" show_status will print what is known about the loadedboot images and their designated fate. A bootspec is a word of the form name=valuei. Itis used to describe the parameters of a boot image by an ElTorito record or a MBR. The names "dir","bin_path", "efi_path" lead to El Toritobootable images. Name "system_area" activates agiven file as MBR. On all media types this is possible within the firstsession. In further sessions an existing boot image can getreplaced by a new one, but depending on the media type thismay have few effect at boot time. See above. The boot image and its supporting files have to be added tothe ISO image by normal means (image loading, -map,-add, ...). In case of ISOLINUX the files shouldreside either in ISO image directory /isolinux or in/boot/isolinux . In that case it suffices to use as bootspecthe text "dir=/isolinux" or"dir=/boot/isolinux". E.g.: -boot_image isolinux dir=/boot/isolinux which bundles these individual settings: -boot_image isolinuxbin_path=/boot/isolinux/isolinux.bin -boot_image isolinuxcat_path=/boot/isolinux/boot.cat -boot_image isolinux load_size=2048 -boot_image any boot_info_table=on An El Torito boot catalog file gets inserted into the ISOimage with address cat_path= at -commit time.It is subject to normal -overwrite and -reassureprocessing if there is already a file with the same name.The catalog lists the boot images and is read by the bootfacility to choose one of the boot images. But it is notnecessary that it appears in the directory tree at all. Onemay hide it in all trees by cat_hidden=on. Otherpossible values are "iso_rr", "joliet",and the default "off". bin_path= depicts a boot image file, a binary programwhich is to be started by the hardware boot facility (e.g.the BIOS) at boot time. efi_path= depicts a boot image file that is ready forEFI booting. Its load_size is determined automatically, noboot info table gets written, no boot medium gets emulated,platform_id is 0xef. emul_type= can be one of "no_emulation","hard_disk", "diskette". It controls theboot medium emulation code of a boot image. The default"no_emulation" is suitable for ISOLINUX, GRUB,FreeBSD cdboot. load_size= is a value which depends on the boot image.Default 2048 should be overridden only if a better value isknown. boot_info_table=on may be used to apply patching to aboot image which is given by "any""bin_path=". "boot_info_table=off"disables patching. platform_id= defines by two hex digits the Platform IDof the boot image. "00" is 80x86 PC-BIOS,"01" is PowerPC, "02" is Mac,"ef" is EFI. id_string=text|56_hexdigits defines the ID string of theboot catalog section where the boot image will be listed. Ifthe value consists of 56 characters[0-9A-Fa-f] then it is converted into 28bytes, else the first 28 characters become the ID string.The ID string of the first boot image becomes the overallcatalog ID. It is limited to 24 characters. Other id_stringsbecome section IDs. sel_crit=hexdigits defines the Selection Criteria of theboot image. Up to 20 bytes get read from the givencharacters [0-9A-Fa-f]. They getattributed to the boot image entry in the catalog. next ends the definition of a boot image and starts anew one. Any following -bootimage bootspecs willaffect the new image. The first "next" discardsloaded boot images and their catalog. discard gives up an existing boot catalog and its bootimages. keep keeps or copies boot images unaltered and writes anew catalog. patch applies patching to existing boot images if theyseem to bear a boot info table. system_area=disk_path copies at most 32768 bytes fromthe given disk file to the very start of the ISO image. ThisSystem Area is reserved for system dependent boot software,e.g. an MBR which can be used to boot from USB stick or harddisk. Other than a El Torito boot image, the file disk_path needsnot to be added to the ISO image. -boot_image isolinux system_area= implies"partition_table=on". partition_table=on causes a simple partition table to bewritten into bytes 446 to 511 of the System Area. With type "isolinux" it shows a partition thatbegins at byte 0 and it causes the LBA of the first bootimage to be written into the MBR. For the first session thisworks only if also "system_area=" and"bin_path=" or "dir=" is given. With types "any" and "grub" it shows asingle partiton which starts at byte 512 and ends where theISO image ends. This works with or without system_area= orboot image. In follow-up sessions the existing System Area ispreserved by default. If types "isolinux" or"grub" are set to "patch", then"partition_table=on" is activated without new bootimage. In this case the existing System Area gets checkedwhether it bears addresses and sizes as if it had beenprocessed by "partition_table=on". If so, thenthose parameters get updated when the new System Area iswritten. Special "system_area=/dev/zero" causes 32k ofNUL-bytes. Use this to discard an MBR which was loadedwith the ISO image. partition_offset=2kb_block_adr causes a partition tablewith a single partition that begins at the given blockaddress. This is counted in 2048 byte blocks, not in 512byte blocks. If the block address is non-zero then itmust be at least 16. A non-zero partition offsetcauses two superblocks to be generated and two sets ofdirectory trees. The image is then mountable from itsabsolute start as well as from the partition start. The offset value of an ISO image gets preserved when a newsession is added. So the value defined here is only ineffect if a new ISO image gets written. partition_hd_cyl=number gives the number of heads percylinder for the partition table. 0 chooses a default value.Maximum is 255. partition_sec_hd=number gives the number of sectors perhead for the partition table. 0 chooses a default value.Maximum is 63. The product partition_sec_hd * partition_hd_cyl * 512 is thecylinder size. It should be divisible by 2048 in order toallow exact alignment. If it is too small to describe theimage size by at most 1024 cylinders, then appropriatevalues of partition_hd_cyl are chosen with partition_sec_hd32 or 63. If the image is larger than 8,422,686,720 bytes,then the cylinder size constraints cannot befulfilled. partition_cyl_align=mode controls image size alignmentto an integer number of cylinders. It is prescribed byisohybrid specs and it seems to please program fdisk.Cylinder size must be divisible by 2048. Images larger than8,323,596,288 bytes cannot be aligned. Mode "auto" is default. Alignment by paddinghappens only with "isolinux""partition_table=on". Mode "on" causes alignment by padding with"partition_table=on" for any type. Mode"off" disables alignment for any type. mips_path=iso_rr_path declares a data file in the imageto be a MIPS Big Endian boot file and causes production of aMIPS Big Endian Volume Header. This is mutually exclusivewith production of other boot blocks like MBR. It willoverwrite the first 512 bytes of any data provided bysystem_area=. Up to 15 boot files can be declared bymips_path=. mipsel_path=iso_rr_path declares a data file in theimage to be the MIPS Little Endian boot file. This ismutually exclusive with other boot blocks. It will overwritethe first 512 bytes of any data provided by system_area=.Only a single boot file can be declared bymipsel_path=. sparc_label=text causes the production of a SUN DiskLabel with the given text as ASCII label. This boot blockformat allows to append images for partitions 2 to 8.Partition 1 will always be the ISO image. See option-append_partition. The first 512 bytes of any dataprovided by system_area= will be overwritten. mips_discard and sparc_discard revoke any bootfile declarations made by mips_path= or mipsel_path=. Theyalso disable production of SUN Disk Label. This removes theban on production of other boot blocks.

-append_partition partition_number type_codedisk_path

Cause a prepared filesystem image to be appended to theISO image and to be described by a partition table entry ina boot block at the start of the emerging ISO image. Thepartition entry will bear the size of the submitted filerounded up to the next multiple of 2048 bytes. Beware of subsequent multi-session runs. The appendedpartition will get overwritten. Partitions may be appended with boot block type MBR and withSUN Disk Label. With MBR: partition_number may be 1 to 4. Number 1 will put the wholeISO image into the unclaimed space before partition 1. Sotogether with mostxorriso MBR features, number 2would be the most natural choice. The type_code may be "FAT12", "FAT16","Linux", or a hexadecimal number between 0x00 and0xff. Not all those numbers will yield usable results. For alist of codes search the Internet for "PartitionTypes" or run fdisk command "L". The disk_path must provide the necessary data bytes atcommit time. An empty disk_path disables this feature forthe given partition number. With SUN Disk Label (selected by -boot_image anysparc_label=): partition_number may be 2 to 8. Number 1 will always be theISO image. Partition start addresses are aligned to 320 KiB.The type_code does not matter. Submit 0x0. Partition image name "." causes the partition tobecome a copy of the next lower valid one.

Jigdo Template Extraction:

From man genisoimage: "Jigdo is a tool to help inthe distribution of large files like CD and DVD images; seehttp://atterer.net/jigdo/ for more details. Debian CDs andDVD ISO images are published on the web in jigdo format toallow end users to download them moreefficiently." xorriso can produce a .jigdo and a .template filetogether with a single-session ISO image. The .jigdofile contains checksums and symbolic file addresses. The.template file contains the compressed ISO image withreference tags instead of the content bytes of the listedfiles. Input for this process are the normal arguments for axorriso session on a blank -outdev, and a .md5file which lists those data files which may be listed in the.jigdo file and externally referenced in the .template file.Each designated file is represented in the .md5 file by asingle text line: MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits orblanks, 2 blanks, symbolic file address The file address in an .md5 line has to bear the samebasename as the disk_path of the file which it shall match.The directory path of the file address is decisive forTo=From mapping, not for file recognition. After To=Frommapping, the file address gets written into the .jigdo file.Jigdo restore tools will convert these addresses into reallyreachable data source addresses from which they canread. If the list of jigdo parameters is not empty, thenxorriso will refuse to write to non-blanktargets, it will disable multi-session emulation, andpadding will be counted as part of the ISO image.

-jigdo parameter_name value

Clear Jigdo Template Extraction parameter list or add aparameter to that list. The alias names are thecorresponding genisoimage options. They are accepted asparameter names as well. Especially they are recognized bythe -as mkisofs emulation command. Parameter clear with any value empties the wholelist. No .jigdo and .template file will be produced. template_path sets the disk_path for the .template filewith the holed and compressed ISO image copy. Alias: -jigdo-template jigdo_path sets the disk_path for the .jigdo file withthe checksums and download addresses for filling the holesin .template. Alias: -jigdo-jigdo md5_path sets the disk_path where to find the .md5 inputfile. Alias: -md5-list min_size sets the minimum size for a data file to belisted in the .jigdo file and being a hole in the .templatefile. Alias: -jigdo-min-file-size exclude adds a regular expression pattern which will getcompared with the absolute disk_path of any data file. Amatch causes the file to stay in .template in any case. Alias: -jigdo-exclude demand_md5 adds a regular expression pattern which willget compared with the absolute disk_path of any data filethat was not found in the .md5 list. A match causes a MISHAPevent. Alias: -jigdo-force-md5 mapping adds a string pair of the form To=From to theparameter list. If a data file gets listed in the .jigdofile, then it is referred by the file address from its linein the .md5 file. This file address gets checked whether itbegins with the From string. If so, then this string will bereplaced by the To string and a ’:’ character,before it goes into the .jigdo file. The From string shouldend by a ’/’ character. Alias: -jigdo-map compression chooses one of "bzip2" or"gzip" for the compression of the template file.The jigdo file is put out uncompressed. Alias: -jigdo-template-compress checksum_iso chooses one or more of "md5","sha1", "sha256", "sha512" forthe auxiliary "# Image Hex" checksums in the jigdofile. The value may e.g. look like"md5,sha1,sha512". Value "all" choosesall available algorithms. Note that MD5 stays alwaysenabled. Alias: -checksum_algorithm_iso checksum_template is like checksum_iso but for "#Template Hex". Alias: -checksum_algorithm_template

Character sets:

File names are strings of non-zero bytes with 8 biteach. Unfortunately the same byte string may appear asdifferent peculiar national characters on differentlynationalized terminals. The meanings of byte codes aredefined incharacter sets which have names. Shellcommand iconv -l lists them. Character sets should not matter as long as only englishalphanumeric characters are used for file names or as longas all writers and readers of the media use the samecharacter set. Outside these constraints it may be necessaryto letxorriso convert byte codes. There is an input conversion from input character set to thelocal character set which applies when an ISO image getsloaded. A conversion from local character set to the outputcharacter set is performed when an image tree gets written.The sets can be defined independently by options-in_charset and -out_charset. Normally one willhave both identical, if ever. If conversions are desired then xorriso needs to knowthe name of the local character set.xorriso caninquire the same info as shell command "locale"with argument "charmap". This may be influenced byenvironment variables LC_ALL, LC_CTYPE, or LANG and shouldmatch the expectations of the terminal. The default output charset is the local character set of theterminal where xorriso runs. So by default noconversion happens between local filesystem names andemerging names in the image. The situation stays ambigousand the reader has to riddle what character set wasused. By option -auto_charset it is possible to attributethe output charset name to the image. This makes thesituation unambigous. But if your terminal character setdoes not match the character set of the local file names,then this attribute can become plainly wrong and causeproblems at read time. To prevent this it is necessary tocheck whether the terminal properly displays all intendedfilenames. Check especially the exotic nationalcharacters. To enforce recording of a particular character set namewithout any conversion at image generation time, set-charset and -local_charset to the desired name,and enable -backslash_codes to avoid evil characterdisplay on your terminal.

-charset character_set_name

Set the character set from which to convert file nameswhen loading an image and to which to convert when writingan image.

-local_charset character_set_name

Override the system assumption of the local character setname. If this appears necessary, one should consider to set-backslash_codes to "on" in order to avoiddangerous binary codes being sent to the terminal.

Exception processing:

Since the tasks of xorriso are manifold and proneto external influence, there may arise the need forxorriso to report and handle problem events. Those events get classified when they are detected by one ofthe software modules and forwarded to reporting andevaluation modules which decide about reactions. Eventclasses are sorted by severity: "NEVER" The upper end of the severityspectrum. "ABORT" The program is being aborted and on itsway to end. "FATAL" The main purpose of the run failed or animportant resource failed unexpectedly. "FAILURE" An important part of the job could notbe performed. "MISHAP" A FAILURE which can be tolerated duringISO image generation. "SORRY" A less important part of the job could notbe performed. "WARNING" A situation is suspicious of being notintended by the user. "HINT" A proposal to the user how to achievebetter results. "NOTE" A harmless information about noteworthycircumstances. "UPDATE" A pacifier message during long runningoperations. "DEBUG" A message which would only interest theprogram developers. "ALL" The lower end of the severity spectrum.

-abort_on severity

Set the severity threshold for events to abort theprogram. Useful: "NEVER", "ABORT","FATAL", "FAILURE" , "MISHAP","SORRY" It may become necessary to abort the program anyway, despitethe setting by this option. Expect not many"ABORT" events to be ignorable. A special property of this option is that it workspreemptive if given as program start argument. I.e. thefirst -abort_on setting among the start arguments isin effect already when the first operations ofxorriso begin. Only "-abort_on" withdash "-" is recognized that way.

-return_with severity exit_value

Set the threshold and exit_value to be returned atprogram end if no abort has happened. This is to allowxorriso to go on after problems but to get a failureindicating exit value from the program, nevertheless. Usefulis a value lower than the -abort_on threshold, down to"WARNING". exit_value may be either 0 (indicating success to thestarter of the program) or a number between 32 and 63. Someother exit_values are used byxorriso if it decidesto abort the program run: 1=abort due to external signal 2=no program arguments given 3=creation of xorriso main object failed 4=failure to start libburnia-project.org libraries 5=program abort during argument processing 6=program abort during dialog processing

-report_about severity

Set the threshold for events to be reported. Useful: "SORRY", "WARNING","HINT", "NOTE", "UPDATE","DEBUG", "ALL" Regardless what is set by -report_about, messages getalways reported if they reach the severity threshold of-abort_on . Event messages are sent to the info channel "I"which is usually stderr but may be influenced by command-pkt_output. Info messages which belong to no eventget attributed severity "NOTE". A special property of this option is that the first-report_about setting among the start arguments is ineffect already when the first operations ofxorrisobegin. Only "-report_about" with dash"-" is recognized that way.

-signal_handling mode

Control the installation of a signal handler which shallreact on external signals (e.g. from program"kill" or from keys Ctrl+C) or on signals causedby severe program errors. Mode "on" is the default. It uses the signalhandler of libburn which produces ugly messages but putsmuch effort in releasing optical drives beforexorriso ends. Mode "off" as first -signal_handling amongthe start arguments prevents all own signal precautions ofxorriso. Inherited signal handler settings stay asthey are. It works like "sig_dfl" if given after othersignal handling was already established at programstart. Mode "sig_dfl" uses the system provided defaulthandling of signals, which is normally a sudden abort of theprogram. To prevent stuck drives, the libburn handler isused during burning, blanking, and formatting on MMCdrives. Mode "sig_ign" tries to ignore as many signaltypes as possible. This imposes the risk thatxorrisorefuses to end until externally kill -9 if performed.kill -9 then imposes the risk that the drive is leftin unusable state and needs poweroff to be reset. So duringburning, blanking, and formatting wait for at least theirnormal run time before killing externally. A special property of this option is that the first-signal_handling setting among the start arguments isin effect already when the first operations ofxorriso begin. Only"-signal_handling" with dash"-" is recognized that way.

-error_behavior occasion 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 inputdevice, and to "file_extraction" which is givenwith osirrox options like -extract. With "image_loading" there are three behaviorsavailable: "best_effort" goes on with reading after eventswith severity below FAILURE if the threshold of option-abort_on allows this. "failure" aborts image tree reading on first eventof at least SORRY. It issues an own FAILURE event. This isthe default. "fatal" acts like "failure" but issuesthe own event as FATAL. With occasion "file_extraction" there are threebehaviors: "keep" maintains incompletely extracted files ondisk. This is the default. "delete" removes files which encountered errorsduring content extraction. "best_effort" starts a revovery attempt by meansof -extract_cut if the file content stems from theloaded ISO image and is not filtered.

Dialog mode control:

-dialog"on"|"off"|"single_line"

Enable or disable to enter dialog mode after allarguments are processed. In dialog mode input lines getprompted via readline or from stdin. If no -abort_on severity was set when dialog starts,then "NEVER" is set to avoid abort in most casesof wrong input or other problems. Before dialog begins, thedefault is "FAILURE" which e.g. aborts on unknowncommands. Mode "on" supports input of newline characterswithin quotation marks and line continuation by trailingbackslash outside quotation marks. Mode"single_line" does not.

-page length width

Describe terminal to the text pager. See also above,paragraph Result pager. If parameter length is nonzero then the user gets promptedafter that number of terminal lines. Zero length disablespaging. Parameter width is the number of characters per terminalline. It is used to compute the number of terminal lineswhich get occupied by an output line. A usual terminal widthis 80.

-use_readline"on"|"off"

If "on" then use readline for dialog. Else useplain stdin. See also above, paragraph Dialog, Readline, Resultpager.

-reassure"on"|"tree"|"off"

If "on" then ask the user for "y" or"n": before deleting or overwriting any file in the ISOimage, before overwriting any disk file during restoreoperations, before rolling back pending image changes, before committing image changes to media, before changing the input drive, before blanking or formatting media, before ending the program. With setting "tree" the reassuring prompt willappear for an eventual directory only once and not for eachfile in its whole subtree. Setting "off" silently kills any kind of imagefile object resp. performs above irrevocable actions. To really produce user prompts, option -dialog needsto be set to "on". Note that the prompt does notappear in situations where file removal is forbidden byoption -overwrite. -reassure only imposes anadditional curb for removing existing file objects. Be aware that file objects get deleted from the ISO imageimmediately after confirmation. They are gone even if therunning command gets aborted and its desired effect getsrevoked. In case of severe mess-up, consider to use-rollback to revoke the whole session.

Drive and media related inquiry actions:

-devices

Show list of available MMC drives with the addresses oftheir libburn standard device files. This is only possible when no ISO image changes are pending.After this option was executed, there is no drive currentand no image loaded. In order to be visible, a device has to offerrw-permissions with its libburn standard device file.Thus it might be only thesuperuser who is able tosee all drives. Drives which are occupied by other processes get notshown.

-device_links

Like -devices, but presenting the drives withaddresses of symbolic links which point to the actual devicefiles. Modern GNU/Linux systems may shuffle drive addresses fromboot to boot. The udev daemon is supposed to create linkswhich always point to the same drive, regardless of itssystem address. The command -device_links shows theaddresses of such links if they begin by"/dev/dvd" or "/dev/cd". Precedence is:"dvdrw", "cdrw", "dvd","cdrom", "cd".

-toc

Show media specific table of content. This is the sessionhistory of the medium, not the ISO image directory tree. In case of overwriteable media holding a valid ISO image, itmay happen that only a single session gets shown. But if thefirst session on the overwriteable media was written byxorriso then a complete session history can beemulated. A drive which is incapable of writing may show any media asCD-ROM or DVD-ROM with only one or two sessionson it. The last of these sessions is supposed to be the mostrecent real session then. Some read-only drives and media show no usable sessionhistory at all. Option -rom_toc_scan might help.

-mount_cmd drive entity id path

Emit an appropriate command line for mounting the ISOsession indicated by drive, entity and id. The result willbe different on GNU/Linux and on FreeBSD. drive can be "indev" or "outdev" toindicate already acquired drives, or it can be the path of anot yet acquired drive. Prefix "stdio:" fornon-MMC drives is not mandatory. entity must be either "sbsector" with thesuperblock sector address as id, or "track" with atrack number as id, or "session" with a sessionnumber, or "volid" with a search pattern for thevolume id, or "auto" with any text as id. path will be used as mount point and must already exist as adirectory on disk. The command gets printed to the result channel. See option-mount for direct execution of this command.

-mount_opts option[:option...]

Set options which influence -mount and-mount_cmd. Currently there is only option"exclusive" which is default and its counterpart"shared". The latter causesxorriso not togive up the affected drive with command -mount. OnGNU/Linux it adds mount option "loop" which mayallow to mount several sessions of the same block device atthe same time. One should not write to a mounted opticalmedium, of course. Take care to umount all sessions beforeejecting.

-session_string drive entity idformat

Print to the result channel a text which gets composedaccording to format and the parameters of the addressedsession. Formats "linux:"path or "freebsd:"pathproduce the output of -mount_cmd for the givenoperating systems. In other texts xorriso will substitute the followingparameter names. An optional prefix "string:" willbe removed. "%device%" will be substituted by the mountabledevice path of the drive address. "%sbsector%" will be substituted by the sessionstart sector. "%track%", "%session%","%volid%" will be substituted by track number,session number, resp. volume id of the depicted session.

-print_size

Print the foreseeable consumption of 2048 byte blocks bynext -commit. This can last a while as a -commitgets prepared and only in last moment is revoked by thisoption. The result depends on several settings and also onthe kind of output device. If no -jidgo options aregiven and not command -as "mkisofs" wasused, then -padding (300 kB by default) is not countedas part of the image size.

-tell_media_space

Print available space on the output medium and the freespace after subtracting already foreseeable consumption bynext -commit.

-pvd_info

Print various id strings which can be found in loaded ISOimages. Some of them may be changed by options like-volid or -publisher. For these ids-pvd_info reports what would be written with the next-commit.

Navigation in ISO image and diskfilesystem:

-cd iso_rr_path

Change the current working directory in the ISO image.This is prepended to iso_rr_paths which do not begin with’/’. It is possible to set the working directory to a path whichdoes not exist yet in the ISO image. The necessary parentdirectories will be created when the first file object isinserted into that virtual directory. Use -mkdir ifyou want to enforce the existence of the directory alreadyat first insertion.

-cdx disk_path

Change the current working directory in the localfilesystem. To be prepended to disk_paths which do not beginwith ’/’.

-pwd

Tell the current working directory in the ISO image.

-pwdx

Tell the current working directory in the localfilesystem.

-ls iso_rr_pattern [***]

List files in the ISO image which match shell patterns(i.e. with wildcards ’*’ ’?’’[a-z]’). If a pattern does not begin with’/’ then it is compared with addresses relativeto -cd. Directories are listed by their content rather than assingle file item. Pattern expansion may be disabled by command-iso_rr_pattern.

-lsd iso_rr_pattern [***]

Like -ls but listing directories as themselves andnot by their content. This resembles shell command ls-d.

-lsl iso_rr_pattern [***]

Like -ls but also list some of the file attributes.The output format resembles shell command ls -ln. File type ’e’ indicates the El Torito bootcatalog. If the file has non-trivial ACL, then a’+’ is appended to the permission info. If thefile is hidden, then ’I’ for "iso_rr",’J’ for "joliet", resp.’H’ for "on" gets appended. Togetherwith ACL it is ’i’, ’j’, resp.’h’.

-lsdl iso_rr_pattern [***]

Like -lsd but also list some of the fileattributes. The output format resembles shell command ls-dln.

-lsx disk_pattern [***]

List files in the local filesystem which match shellpatterns. Patterns which do not begin with ’/’are used relative to -cdx. Directories are listed by their content rather than assingle file item. Pattern expansion may be disabled by command-disk_pattern.

-lsdx disk_pattern [***]

Like -lsx but listing directories as themselves andnot by their content. This resembles shell command ls-d.

-lslx disk_pattern [***]

Like -lsx but also listing some of the fileattributes. Output format resembles shell command ls-ln.

-lsdlx disk_pattern [***]

Like -lsdx but also listing some of the fileattributes. Output format resembles shell command ls-dln.

-getfacl iso_rr_pattern [***]

Print the access permissions of the given files in theISO image using the format of shell command getfacl. If afile has no ACL then it gets fabricated from the-chmod settings. A file may have a real ACL if it wasintroduced into the ISO image while option -acl wasset to "on".

-getfacl_r iso_rr_pattern [***]

Like -gefacl but listing recursively the whole filetrees underneath eventual directories.

-getfattr iso_rr_pattern [***]

Print the xattr of the given files in the ISO image. If afile has no such xattr then noting is printed for it.

-getfattr_r iso_rr_pattern [***]

Like -gefattr but listing recursively the wholefile trees underneath eventual directories.

-du iso_rr_pattern [***]

Recursively list size of directories and files in the ISOimage which match one of the patterns. similar to shellcommand du -k.

-dus iso_rr_pattern [***]

List size of directories and files in the ISO image whichmatch one of the patterns. Similar to shell command du-sk.

-dux disk_pattern [***]

Recursively list size of directories and files in thelocal filesystem which match one of the patterns. Similar toshell command du -k.

-dusx disk_pattern [***]

List size of directories and files in the localfilesystem which match one of the patterns. Similar to shellcommand du -sk.

-findx disk_path [-name pattern] [-type t][-exec action [params]] --

Like -find but operating on local filesystem andnot on the ISO image. This is subject to the settings of-follow. -findx accepts the same -type arguments as-find. Additionally it recognizes type"mountpoint" (or "m") which matchessubdirectories which reside on a different device than theirparent. It never matches the disk_path given as startaddress for -findx. -findx accepts the -exec actions as does-find. But except the following few actions it willalways perform action "echo". in_iso reports the path if its counterpart exists in theISO image. For this the disk_path of the -findxcommand gets replaced by the iso_rr_path given asparameter. E.g.: -findx /home/thomas -exec in_iso/thomas_on_cd -- not_in_iso reports the path if its counterpart does notexist in the ISO image. The report format is the same aswith command -compare. add_missing iso_rr_path_start adds the counterpart if itdoes not yet exist in the ISO image and marks it for"rm_merge" as non-removable. E.g.: -findx /home/thomas -exec add_missing/thomas_on_cd -- is_full_in_iso reports if the counterpart in the ISOimage contains files. To be used with -type"m" to report mount points. empty_iso_dir deletes all files from the counterpart inthe ISO image. To be used with -type "m" totruncate mount points. estimate_size prints a lower and an upper estimation ofthe number of blocks which the found files together willoccupy in the emerging ISO image. This does not account forthe superblock, for the directories in the -findxpath, or for image padding. list_extattr mode prints a script to the result channel,which would use FreeBSD command setextattr to set thefile’s xattr name-value pairs of user namespace.See -find for a description of parameter mode. E.g. -exec list_extattr e --

-compare disk_path iso_rr_path

Compare attributes and eventual data file content of afileobject in the local filesystem with a file object in theISO image. The iso_rr_path may well point to an image fileobject which is not yet committed, i.e. of which the datacontent still resides in the local filesystem. Such datacontent is prone to externally caused changes. If iso_rr_path is empty then disk_path is used as path inthe ISO image too. Differing attributes are reported in detail, differingcontent is summarized. Both to the result channel. In caseof no differences no result lines are emitted.

-compare_r disk_path iso_rr_path

Like -compare but working recursively. I.e. allfile objects below both addresses get compared whether theyhave counterparts below the other address and whether bothcounterparts match.

-compare_l disk_prefix iso_rr_prefixdisk_path [***]

Perform -compare_r with each of the disk_patharguments. iso_rr_path will be composed from disk_path byreplacing disk_prefix by iso_rr_prefix.

-show_stream iso_rr_path [***]

Display the content stream chain of data files in the ISOimage. The chain consists of the iso_rr_name and one or morestreams, separated by " < " marks. A streamdescription consists of one or more texts, separated by":" characters. The first text tells the streamtype, the following ones, if ever, describe its individualproperties. Frequently used types are: disk:’disk_path’ for local filesystemobjects. image:’iso_rr_path’ for ISO image fileobjects. cout:’disk_path offset count’ for -cut_outfiles. extf:’filter_name’ for external filters. Example: ’/abc/xyz.gz’ < extf:’gzip’ <disk:’/home/me/x’

-show_stream_r iso_rr_path [***]

Like -show_stream but working recursively.

Evaluation of readability and recovery:

It is not uncommon that optical media produce readerrors. The reasons may be various and get obscured by errorcorrection which is performed by the drives and based onextra data on the media. If a drive returns data then onecan quite trust that they are valid. But at some degree ofread problems the correction will fail and the drive issupposed to indicate error. xorriso can scan a medium for readable data blocks,classify them according to their read speed, save them to afile, and keep track of successfuly saved blocks for furthertries on the same medium. By option -md5 checksums may get recorded with datafiles and whole sessions. These checksums are reachable onlyvia indev and a loaded image. They work independently of themedia type and can detect transmission errors.

-check_media [option [option ...]]--

Try to read data blocks from the indev drive, optionallycopy them to a disk file, and finally report about theencountered quality. Several options may be used to modifythe default behavior. The options given with this command override the defaultsettings which may have been changed by option-check_media_defaults. See there for a description ofoptions. The result list tells intervals of 2 KiB blocks with startaddress, number of blocks and quality. Qualities which beginwith "+" are supposed to be valid readable data.Qualities with "-" are unreadable orcorrupted data. "0" indicates qualities which arenot covered by the check run or are regularly allowed to beunreadable (e.g. gaps between tracks). Alternatively it is possible to report damaged files ratherthan blocks. If -md5 is "on" then the default modewhat=tracks looks out for libisofs checksum tags for the ISOsession data and checks them against the checksums computedfrom the data stream.

-check_media_defaults [option [option ...]]--

Preset options for runs of -check_media,-extract_cut and best_effort file extraction. Optionsgiven with -check_media will override the presetoptions. -extract_cut will override some optionsautomatically. An option consists of a keyword, a "=" character,and a value. Options may override each other. So theirsequence matters. The default setting at program start is: use=indev what=tracks min_lba=-1 max_lba=-1retry=default time_limit=28800 item_limit=100000 data_to=’’event=ALL abort_file=/var/opt/xorriso/do_abort_check_media sector_map=’’ map_with_volid=off patch_lba0=offreport=blocks bad_limit=valid slow_limit=1.0 chunk_size=0s Option "reset=now" restores these startupdefaults. Non-default options are: report="files" lists the files which usedamaged blocks (not with use=outdev). The format is likewith find -exec report_damage. Note that a MD5 sessionmismatch marks all files of the session as damaged. If finerdistinction is desired, perform -md5 off before-check_media. report="blocks_files" first lists damagedblocks and then affected files. use="outdev" reads from the output driveinstead of the input drive. This avoids loading the ISOimage tree from media. use="sector_map" does not read any media butloads the file given by option sector_map= and processesthis virtual outcome. what="disc" scans the payload range of amedium without respecting track gaps. what="image" similar to "disc", butrestricts scanning to the range of the ISO 9660 image, ifpresent. min_lba=limit omits all blocks with addresses lower thanlimit. max_lba=limit switches to what=disc and omits all blocksabove limit. retry="on" forces read retries with singleblocks when the normal read chunk produces a read error. Bydefault, retries are only enabled with CD media."retry=off" forbits retries for all mediatypes. abort_file=disk_path gives the path of the file whichmay abort a scan run. Abort happens if the file exists andits mtime is not older than the start time of the run. Useshell command "touch" to trigger this. Other thanan aborted program run, this will report the tested anduntested blocks and go on with runningxorriso. time_limit=seconds gives the number of seconds afterwhich the scan shall be aborted. This is useful forunattended scanning of media which may else overwork thedrive in its effort to squeeze out some readable blocks.Abort may be delayed by the drive gnawing on the last singleread operation. Value -1 means unlimited time. item_limit=number gives the number of report list itemsafter which to abort. Value -1 means unlimited itemnumber. data_to=disk_path copies the valid blocks to the givenfile. event=severity sets the given severity for a problemevent which shall be issued at the end of a check run ifdata blocks were unreadable or failed to match recorded MD5checksums. Severity "ALL" disables thisevent. sector_map=disk_path tries to read the file given bydisk_path as sector bitmap and to store such a map fileafter the scan run. The bitmap tells which blocks have beenread successfully in previous runs. It allows to do severalscans on the same medium, even with intermediate eject, inorder to collect readable blocks whenever the drive is luckyenough to produce them. The stored file contains a humanreadable TOC of tracks and their start block addresses,followed by binary bitmap data. map_with_volid="on" examines tracks whetherthey are ISO images and prints their volume ids into thehuman readable TOC of sector_map=. patch_lba0="on" transfers within the data_to=file a copy of the currently loaded session head to thestart of that file and patches it to be valid at thatposition. This makes the loaded session the default sessionof the image file when it gets mounted or loaded as stdio:drive. But it usually makes the original session 1inaccessible. patch_lba0="force" performspatch_lba0="on" even if xorriso believesthat the copied data are not valid. patch_lba0= may also bear a number. If it is 32 or higher itis taken as start address of the session to be copied. Inthis case it is not necessary to have an -indev and aloaded image. ":force" may be appended after thenumber. bad_limit=threshold sets the highest quality which shallbe considered as damage. Choose one of "good","md5_match", "slow","partial", "valid","untested", "invalid","tao_end", "off_track","md5_mismatch", "unreadable". slow_limit=threshold sets the time threshold for asingle read chunk to be considered slow. This may be afractional number like 0.1 or 1.5. chunk_size=size sets the number of bytes to be read inone read operation. This gets rounded down to full blocks of2048 bytes. 0 means automatic size.

-check_md5 severity iso_rr_path[***]

Compare the data content of the given files in the loadedimage with their recorded MD5 checksums, if there are any.In case of any mismatch an event of the given severity isissued. It may then be handled by appropriate settings ofoptions -abort_on or -return_with which both cancause non-zero exit values of the program run.Severity ALL suppresses that event. This option reports match and mismatch of data files to theresult channel. Non-data files cause NOTE events.There will also be UPDATE events from data reading. If no iso_rr_path is given then the whole loaded session iscompared with its MD5 sum. Be aware that this covers onlyone session and not the whole image if there are oldersessions.

-check_md5_r severity iso_rr_path[***]

Like -check_md5 but checking all data filesunderneath the given paths. Only mismatching data files willbe reported.

osirrox ISO-to-disk restore options:

Normally xorriso only writes to disk files whichwere given as stdio: pseudo-drives or as log files.But its alter ego osirrox is able to extract file objectsfrom ISO images and to create, overwrite, or delete fileobjects on disk. Disk file exclusions by -not_mgt, -not_leaf,-not_paths apply. If disk file objects already existthen the settings of -overwrite and -reassureapply. But -overwrite "on" only triggers thebehavior of -overwrite "nondir". I.e.directories cannot be deleted. Access permissions of files in the ISO image do not restrictrestoring. The directory permissions on disk have to allowrwx.

-osirrox"on"|"device_files"|"off"|"banned"|[:option:...]

Setting "off" disables disk filesystemmanipulations. This is the default unless the program wasstarted with leafname "osirrox". Elsewise thecapability to restore files can be enabled explicitly by-osirrox "on". It can be irrevocablydisabled by -osirrox "banned". To enable restoring of special files by"device_files" is potentially dangerous. Themeaning of the number st_rdev (see man 2 stat) depends muchon the operating system. Best is to restore device filesonly to the same system from where they were copied. If notenabled, device files in the ISO image are ignored duringrestore operations. Due to a bug of previous versions, device files fromprevious sessions might have been altered to major=0,minor=1. So this combination does not get restored. Option "concat_split_on" is default. It enablesrestoring of split file directories as data files if thedirectory contains a complete collection of -cut_outpart files. With option "concat_split_off" suchdirectories are handled like any other ISO imagedirectory. Option "auto_chmod_off" is default. If"auto_chmod_on" is set then access restrictionsfor disk directories get circumvented if those directoriesare owned by the effective user who runsxorriso.This happens by temporarily granting rwx permission to theowner. Option "sort_lba_on" may improve read performancewith optical drives. It allows to restore large numbers ofhard links without exhausting -temp_mem_limit. It doesnot preserve directory mtime and it needs -osirroxoption auto_chmod_on in order to extract directories whichoffer no write permission. Default is"sort_lba_off". Option "o_excl_on" is the default unless theprogram was started with leafname "osirrox". OnGNU/Linux it tries to avoid using drives which are mountedor in use by other libburn programs. Option"o_excl_off" allows on GNU/Linux to access suchdrives. Drives which get acquired while"o_excl_off" will refuse to get blanked,formatted, written, or ejected. But be aware that evenharmless inquiries can spoil ongoing burns of CD-R[W]and DVD-R[W]. Option "strict_acl_off" is default. It tolerateson FreeBSD the presence of directory "default"ACLs in the ISO image. With "strict_acl_on" theseGNU/Linux ACLs cause on FreeBSD a FAILURE event duringrestore with -acl "on".

-extract iso_rr_path disk_path

Copy the file objects at and underneath iso_rr_path totheir corresponding addresses at and underneath disk_path.This is the inverse of -map or -update_r. If iso_rr_path is a directory and disk_path is an existingdirectory then both trees will be merged. Directoryattributes get extracted only if the disk directory is newlycreated by the copy operation. Disk files get removed onlyif they are to be replaced by file objects from the ISOimage. As many attributes as possible are copied together withrestored file objects.

-extract_single iso_rr_pathdisk_path

Like -extract, but if iso_rr_path is a directorythen its sub tree gets not restored.

-extract_l iso_rr_prefix disk_prefixiso_rr_path [***]

Perform -extract with each of the iso_rr_patharguments. disk_path will be composed from iso_rr_path byreplacing iso_rr_prefix by disk_prefix.

-extract_cut iso_rr_path byte_offsetbyte_count disk_path

Copy a byte interval from a data file out of an ISO imageinto a newly created disk file. The main purpose for this isto allow handling of large files if they are not supportedby mount -t iso9660 and if the reading system isunable to buffer them as a whole. If the data bytes of iso_rr_path are stored in the loadedISO image, and no filter is applied, and byte_offset is amultiple of 2048, then a special run of -check_mediais performed. It may be quicker and more rugged than thegeneral reading method.

-cpx iso_rr_path [***] disk_path

Copy single leaf file objects from the ISO image to theaddress given by disk_path. If more then one iso_rr_path isgiven then disk_path must be a directory ornon-existent. In the latter case it gets created andthe extracted files get installed in it with the sameleafnames. Missing directory components in disk_path will get created,if possible. Directories are allowed as iso_rr_path only with-osirrox "concat_split_on" and only if theyactually represent a complete collection of -cut_outsplit file parts.

-cpax iso_rr_path [***] disk_path

Like -cpx but restoring mtime, atime as in ISOimage and trying to set ownership and group as in ISOimage.

-cp_rx iso_rr_path [***] disk_path

Like -cpx but also extracting whole directory treesfrom the ISO image. The resulting disk paths are determined as with shellcommand cp -r : If disk_path is an existing directorythen the trees will be inserted or merged underneath thisdirectory and will keep their leaf names. The ISO directory"/" has no leaf name and thus gets mapped directlyto disk_path.

-cp_rax iso_rr_path [***] disk_path

Like -cp_rx but restoring mtime, atime as in ISOimage and trying to set ownership and group as in ISOimage.

-paste_in iso_rr_path disk_path byte_offsetbyte_count

Read the content of a ISO data file and write it into adata file on disk beginning at the byte_offset. Write atmost byte_count bytes. This is the inverse of option-cut_out.

-mount drive entity id path

Produce the same line as -mount_cmd and thenexecute it as external program run after giving up thedepicted drive. See also -mount_opts. This demands-osirrox to be enabled and normally will succeed onlyfor the superuser. For safety reasons the mount program isonly executed if it is reachable as /bin/mount or/sbin/mount.

Command compatibility emulations:

Writing of ISO 9660 on CD is traditionally done byprogram mkisofs as ISO 9660 image producer and cdrecord asburn program.xorriso does not strive for theircomprehensive emulation. Nevertheless it is ready to performsome of its core tasks under control of commands which insaid programs trigger comparable actions.

-as personality option [options] --

Perform the variable length option list as sparseemulation of the program depicted by the personalityword. Personality "mkisofs" accepts theoptions listed with: -as mkisofs -help -- Among them: -R (always on), -r, -J,-o, -M, -C, -dir-mode,-file-mode, -path-list, -m,-exclude-list, -f,-print-size, -pad, -no-pad,-V, -v, -version,-graft-points, -z,-no-emul-boot, -b, -c,-boot-info-table,-boot-load-size,-input-charset, -G,-output-charset, -U, -hide,-hide-joliet, -hide-list,-hide-joliet-list, file paths andpathspecs. A lot of options are not supported and lead tofailure of the mkisofs emulation. Some are ignored, butbetter do not rely on this tolerance. The supported options are documented in detail inxorrisofs.info and in man xorrisofs. The description here isfocused on the effect of mkisofs emulation in the context ofaxorriso run. Other than with the "cdrecord" personality thereis no automatic -commit at the end of a"mkisofs" option list. Verbosity settings -v(= "UPDATE") and -quiet (="SORRY") persist. The output file persists untilthings happen like -commit, -rollback,-dev, or end ofxorriso. -pacifier getsset to "mkisofs" if files are added to theimage. -graft-points is equivalent to -pathspecson. Note that pathspecs without "=" areinterpreted differently than withxorriso option-add. Directories get merged with the root directoryof the ISO image, other filetypes get mapped into that rootdirectory. If pathspecs are given and if no output file was chosenbefore or during the "mkisofs" option list, thenstandard output (-outdev "-") will getinto effect. If -o points to a regular file, then itwill be truncated to 0 bytes when finally writing begins.This truncation does not happen if the drive is chosen byxorriso options before -as mkisofs or after itslist delimiter. Directories and symbolic links are no valid-o targets. Writing to stdout is possible only if -as"mkisofs" was among the start arguments or ifother start arguments pointed the output drive to standardoutput. -print-size inhibits automatic image productionat program end. This ban is lifted only if the pending imagechanges get discarded. Padding is counted as part of the ISO image if not option--emul-toc is given. If no -iso-level is given, then level 1 ischosen when the first file or directory is added to theimage. At the same occasion directory names get allowed toviolate the standard by -compliance optionallow_dir_id_ext. This may be avoided by option-disallow_dir_id_ext. Option -root is supported. Option-old-root is implemented by xorrisocommands -mkdir, -cp_clone, -findupdate_merge, and -find rm_merge. -root and-old-root set command -disk_dev_ino to"ino_only" and -md5 to "on", bydefault. -disk_dev_ino can be set to "off"by --old-root-no-ino resp. to"on" by --old-root-devno .-md5 can be set to "off" by--old-root-no-md5 . Not original mkisofs options are--quoted_path_list , --hardlinks ,--acl , --xattr , --md5, --stdio_sync . They work like thexorriso options with the same name and hardcodedargument "on", e.g. -acl "on".Explicit arguments are expected by --stdio_syncand --scdbackup_tag. The capability to preserve multi-session history onoverwriteable media gets disabled by default. It can beenabled by using --emul-toc with the firstsession. See -compliance no_emul_toc. --sort-weight gets as arguments a numberand an iso_rr_path. The number becomes the LBA sortingweight of regular file iso_rr_path or of all regular filesunderneath directory iso_rr_path. (See -find-exec sort_weight). Adopted from grub-mkisofs are--protective-msdos-label (see-boot_image grub partition_table=on) and--modification-date=YYYYMMDDhhmmsscc (see-volume_date uuid). For EFI bootable GRUB boot imagesuse --efi-boot. It performs-boot_image grub efi_path= surrounded by two-boot_image "any" "next".Alternative option -e from Fedora genisoimage setsbin_path and platform_id for EFI, but performs no"next". For MBR bootable ISOLINUX images there is-isohybrid-mbr FILE, where FILE is one of theSyslinux files mbr/isohdp[fp]x*.bin . Use this instead of-G to apply the effect of -boot_image isolinuxpartition_table=on. --boot-catalog-hide is-boot_image any cat_hidden=on. -mips-boot is the same as -boot_image anymips_path= . -mipsel-boot leads to mipsel_path= . -partition_offset number is -boot_image anypartition_offset=number. Option -append_partition is supported. -untranslated_name_len number is -complianceuntranslated_name_len=number. --old-empty is -complianceold_empty. The options of genisoimage Jigdo Template Extraction arerecognized and performed viaxorriso option-jigdo. See the "Alias:" names there for themeaning of the genisoimage options. Personalities "xorrisofs","genisoimage", and"genisofs" are aliases for"mkisofs". If xorriso is started with one of the leafnames"xorrisofs", "genisofs","mkisofs", or "genisoimage", then itperforms -read_mkisofsrc and prepends -as"genisofs" to the command line arguments. I.e. allarguments will be interpreted mkisofs style until"--" is encountered. From then on,options are interpreted as xorriso options. --no_rc as first argument of such a programstart prevents interpretation of startup files. See sectionFILES below. Personality "cdrecord" accepts theoptions listed with: -as cdrecord -help -- Among them: -v, dev=, speed=, blank=, fs=,-eject, -atip, padsize=, tsize=, -isosize,-multi, -msinfo,--grow_overwriteable_iso, write_start_address=,track source file path or "-" for standardinput as track source. It ignores most other options of cdrecord and cdrskin butrefuses on -audio, -scanbus, and on blankingmodes unknown toxorriso. The scope is only a single data track per session to bewritten to blank, overwriteable, or appendable media. Themedium gets closed if closing is applicable and not option-multi is present. If an input drive was aquired, then it is given up. This isonly allowed if no image changes are pending. dev= must be given as xorriso device address.Addresses like 0,0,0 or ATA:1,1,0 are not supported. If a track source is given, then an automatic -commithappens at the end of the "cdrecord" optionlist. --grow_overwriteable_iso enables emulation ofmulti-session on overwriteable media. To enableemulation of a TOC, the first session needs -C 0,32with -as mkisofs (but no -M) and--grow_overwriteable_iso write_start_address=32swith -as cdrecord. A much more elaborate libburn based cdrecord emulator is theprogram cdrskin. Personalites "xorrecord","wodim", and "cdrskin" arealiases for "cdrecord". If xorriso is started with one of the leafnames"xorrecord", "cdrskin","cdrecord", or "wodim", then itautomatically prepends -as "cdrskin" to thecommand line arguments. I.e. all arguments will beinterpreted cdrecord style until "--"is encountered. From then on, options are interpreted asxorriso options. --no_rc as first argument of such a programstart prevents interpretation of xorriso startupfiles. See section FILES below.

-read_mkisofsrc

Try one by one to open for reading: ./.mkisofsrc ,$MKISOFSRC , $HOME/.mkisofsrc , $(dirname $0)/.mkisofsrc On success interpret the file content as of man mkisofsCONFIGURATION, and end this command. Do not try furtherfiles. The last address is used only if start argument 0 hasa non-trivial dirname. The reader currently interprets the following NAME=VALUEpairs: APPI (-application_id) , PUBL(-publisher) , SYSI (-system_id) , VOLI(-volid) , VOLS (-volset_id) Any other lines will be silently ignored.

-pacifier behavior_code

Control behavior of UPDATE pacifiers during writeoperations. The following behavior codes are defined: "xorriso" is the default format: Writing: sector XXXXX of YYYYYY [fifo active, nn% fill] "cdrecord" looks like: X of Y MB written (fifo nn%) [buf mmm%] "mkisofs" nn% done, estimate finish Tue Jul 15 20:13:28 2008

-scdbackup_tag list_pathrecord_name

Set the parameter "name" for a scdbackupchecksum record. It will be appended in an scdbackupchecksum tag to the -md5 session tag if the imagestarts at LBA 0. This is the case if it gets written asfirst session onto a sequential medium, or piped into aprogram, named pipe or character device. If list_path is not empty then the record will also beappended to the data file given by this path. Program scdbackup_verify will recognize and verify tag resp.record.

Scripting, dialog and program controlfeatures:

-no_rc

Only if used as first command line argument this optionprevents reading and interpretation of startup files. Seesection FILES below.

-options_from_file fileaddress

Read quoted input from fileaddress and execute it likedialog lines. Empty lines and lines which begin by # areignored. Normally one line should hold onexorrisocommand and all its arguments. Nevertheless lines may beconcatenated by a trailing backslash. See also section "Command processing", paragraph"Quoted input".

-help

Print helptext.

-version

Print program name and version, component versions,license.

-list_extras code

Tell whether certain extra features were enabled atcompile time. Code "all" lists all features and aheadline. Other codes pick a single feature. Code"codes" lists them. They share names with relatedcommands (see also there): "acl" tells whether xorriso has an adapter forlocal filesystems ACLs. "xattr" tells whether xorriso has an adapter forlocal filesystems EA. "jigdo" tells whether production of Jigdo files ispossible. "zisofs" tells whether zisofs and built-ingzip filters are enabled. "external_filter" tells whether external filterprocesses are allowed and whether they are allowed if realuser id and effective user id differ. "dvd_obs" tells whether 64 kB output to DVD mediais default. "use_readline" tells whether readline may beenabled in dialog mode.

-history textline

Copy textline into libreadline history.

-status mode|filter

Print the current settings of xorriso. Modes: short... print only important or altered settings long ... print all settings including defaults long_history like long plus history lines Filters begin with ’-’ and are comparedliterally against the output lines of-status:long_history. A line is put out only if itsstart matches the filter text. No wildcards.

-status_history_max number

Set maximum number of history lines to be reported with-status "long_history".

-list_delimiter word

Set the list delimiter to be used instead of"--". It has to be a single word, mustnot be empty, not longer than 80 characters, and must notcontain quotation marks. For brevity the list delimiter is referred as"--" throughout this text.

-backslash_codes"on"|"off"|mode[:mode]

Enable or disable the interpretation of symbolicrepresentations of special characters with quoted input, orwith program arguments, or with program text output. Ifenabled the following translations apply: \a=bell(007) \b=backspace(010) \e=Escape(033)\f=formfeed(014) \n=linefeed(012) \r=carriage_return(015) \t=tab(011) \v=vtab(013) \\=backslash(134)\[0-7][0-7][0-7]=octal_code \x[0-9a-f][0-9a-f]=hex_code\cC=control-C Translations can occur with quoted input in 3 modes: "in_double_quotes" translates only inside "quotation. "in_quotes" translates inside " and ’quotation. "with_quoted_input" translates inside and outsidequotes. With the start program arguments there is mode: "with_program_arguments" translates all programarguments. Mode "encode_output" encodes output characters. Itcombines "encode_results" with"encode_infos". Inside single or double quotationmarks encoding applies to ASCII characters octal 001 to 037, 177 to 377 and to backslash(134). Outside quotation markssome harmless control characters stay unencoded: bell(007),backspace(010), tab(011), linefeed(012), formfeed(014),carriage_return(015). Mode "off" is default and disables anytranslation. Mode "on" is"with_quoted_input:with_program_arguments:encode_output".

-temp_mem_limitnumber["k"|"m"]

Set the maximum size of temporary memory to be used forimage dependent buffering. Currently this applies to patternexpansion, LBA sorting, restoring of hard links. Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m= 1 GiB.

-print text

Print a text line to the result channel which is bydefault stdout.

-print_info text

Print a text line to the info channel which is by defaultstderr.

-print_mark text

Print a text line to the mark channel which is by defaultdirected to both, result and info channel. An empty textwill cause no output at all.

-prompt text

Show text at beginning of output line and wait for theuser to hit the Enter key resp. to send a line viastdin.

-sleep seconds

Wait for the given number of seconds before perfoming thenext command. Expect coarse granularity no better than 1/100seconds.

-errfile_log mode path|channel

If problem events are related to input files from thefilesystem, then their disk_paths can be logged to a file orto output channels R or I. Mode can either be "plain" or "marked".The latter causes marker lines which give the time of logstart, burn session start, burn session end, log end orprogram end. In mode "plain", only the file pathsare logged. If path is "-" or "-R" thenthe log is directed to the result channel. Path"-I" directs it to the info message channel.Any text that does not begin with "-" isused as path for a file to append the log lines. Problematic files can be recorded multiple times during oneprogram run. If the program run aborts then the list mightnot be complete because some input file arguments might nothave been processed at all. The errfile paths are transported as messages of very lowseverity "ERRFILE". This transport becomes visiblewith -report_about "ALL".

-session_log path

If path is not empty it gives the address of a plain textfile where a log record gets appended after each session.This log can be used to determine the start_lba of a sessionfor mount options -o sbsector= resp. -s fromdate or volume id. Record format is: timestamp start_lba sizevolume-id The first three items are single words, the rest of the lineis the volume id.

-scsi_log"on"|"off"

Mode "on" enables very verbous logging of SCSIcommands and drive replies. Logging messages get printed tostderr, not to any of thexorriso outputchannels. A special property of this option is that the first-scsi_log setting among the start arguments is ineffect already when the first operations ofxorrisobegin. Only "-scsi_log" with dash"-" is recognized that way.

-end

End program after writing pending changes.

-rollback_end

Discard pending changes. End program immediately.

# any text

Only in dialog or file execution mode, and only as firstnon-whitespace in line: Do not execute the line butstore it in readline history.

Support for frontend programs via stdin andstdout:

-pkt_output"on"|"off"

Consolidate text output on stdout and classify each lineby a channel indicator: ’R:’ for result lines, ’I:’ for notes and error messages, ’M:’ for -mark texts. Next is a decimal number of which only bit 0 has a meaningfor now. 0 means no newline at end of payload, 1 means thatthe newline character at the end of the output line belongsto the payload. After another colon and a blank follows thepayload text. Example: I:1: enter option and arguments :

-logfile channel fileaddress

Copy output of a channel to the given file. Channel maybe one of: "." for all channels, "I" forinfo messages, "R" for result lines, "M"for -mark texts.

-mark text

If text is not empty it will get put out on "M"channel each time xorriso is ready for the nextdialog line or beforexorriso performs a command thatwas entered to the pager prompt.

-prog text

Use text as name of this program in subsequentmessages

-prog_help text

Use text as name of this program and perform-help.

EXAMPLES

Overview of examples:

As superuser learn about available drives Blank medium and compose a new ISO image as batch run A dialog session doing about the same Manipulate an existing ISO image on the same medium Copy modified ISO image from one medium to another Bring a prepared ISOLINUX tree onto medium and make itbootable Change existing file name tree from ISO-8859-1 to UTF-8 Operate on storage facilities other than optical drives Burn an existing ISO image file to medium Perform multi-session runs as of cdrtools traditions Let xorriso work underneath growisofs Adjust thresholds for verbosity, exit value and programabort Examples of input timestrings Incremental backup of a few directory trees Restore directory trees from a particular ISO session todisk Try to retrieve blocks from a damaged medium

As superuser learn about available drives

On Linux or FreeBSD consider to give rw-permissionsto those users or groups which shall be able to use thedrives withxorriso. On Solaris use pfexec. Considerto restrict privileges ofxorriso to"base,sys_devices" and to give r-permissionto user or group. $ xorriso -device_links 1 -dev ’/dev/cdrom1’ rwrw-- :’TSSTcorp’ ’DVD-ROMSH-D162C 1 -dev ’/dev/cdrw’ rwrw-- :’TSSTcorp’ ’CDDVDWSH-S223B’ 2 -dev ’/dev/cdrw3’ rwrw-- :’HL-DT-ST’’BDDVDRW_GGC-H20L’

Blank medium and compose a new ISO image as batchrun

Aquire drive /dev/sr2, make medium ready for writing anew image, fill the image with the files from hard diskdirectories /home/me/sounds and /home/me/pictures. Because no -dialog "on" is given, theprogram will then end by writing the session to themedium. $ xorriso -outdev /dev/sr2 \ -blank as_needed \ -map /home/me/sounds /sounds \ -map /home/me/pictures /pictures The ISO image may be shaped in a more elaborate way likethe following: Omit some unwanted stuff by removing it fromthe image directory tree. Reintroduce some wanted stuff. $ cd /home/me $ xorriso -outdev /dev/sr2 \ -blank as_needed \ -map /home/me/sounds /sounds \ -map /home/me/pictures /pictures \ -rm_r \ /sounds/indecent \ ’/pictures/*private*’ \ /pictures/confidential \ -- \ -cd / \ -add pictures/confidential/work* -- Note that ’/pictures/*private*’ is a pattern foriso_rr_paths while pictures/confidential/work* gets expandedby the shell with addresses from the hard disk. Options-add and -map have different argument rules butfinally the same effect: they put files into the image.

A dialog session doing about the same

Some settings are already given as start argument. Theother activities are done as dialog input. The pager getsset to 20 lines of 80 characters. The drive is acquired by option -dev rather than-outdev in order to see the message about its currentcontent. By option -blank this content is made readyfor being overwritten and the loaded ISO image is madeempty. In order to be able to eject the medium, the session needsto be committed explicitly. $ xorriso -dialog on -page 20 80 -disk_pattern on enter option and arguments : -dev /dev/sr2 enter option and arguments : -blank as_needed enter option and arguments : -map /home/me/sounds /sounds -map /home/me/pictures/pictures enter option and arguments : -rm_r /sounds/indecent /pictures/*private*/pictures/confidential enter option and arguments : -cdx /home/me/pictures -cd /pictures enter option and arguments : -add confidential/office confidential/factory enter option and arguments : -du / enter option and arguments : -commit_eject all -end

Manipulate an existing ISO image on the samemedium

Load image from drive. Remove (i.e. hide) directory/sounds and its subordinates. Rename directory/pictures/confidential to /pictures/restricted. Changeaccess permissions of directory /pictures/restricted. Addnew directory trees /sounds and /movies. Burn to the samemedium, check whether the tree can be loaded, and eject. $ xorriso -dev /dev/sr2 \ -rm_r /sounds -- \ -mv \ /pictures/confidential \ /pictures/restricted \ -- \ -chmod go-rwx /pictures/restricted-- \ -map /home/me/prepared_for_dvd/sounds_dummy /sounds\ -map /home/me/prepared_for_dvd/movies /movies \ -commit -eject all

Copy modified ISO image from one medium toanother

Load image from input drive. Do the same manipulations asin the previous example. Aquire output drive and blank it.Burn the modified image as first and only session to theoutput drive. $ xorriso -indev /dev/sr2 \ -rm_r /sounds -- \ ... -outdev /dev/sr0 -blank as_needed \ -commit -eject all

Bring a prepared ISOLINUX tree onto medium and make itbootable

The user has already created a suitable file tree on diskand copied the ISOLINUX files into subdirectory./boot/isolinux of that tree. Nowxorriso can burn anEl Torito bootable medium: $ xorriso -outdev /dev/sr0 -blank as_needed\ -map /home/me/ISOLINUX_prepared_tree / \ -boot_image isolinux dir=/boot/isolinux

Change existing file name tree from ISO-8859-1 toUTF-8

This example assumes that the existing ISO image waswritten with character set ISO-8859-1 but thatthe readers expected UTF-8. Now a new session with thesame files gets added with converted file names. In order toavoid any weaknesses of the local character set, thiscommand pretends that it uses already the final target setUTF-8. Therefore strange file names may appear inmessages, which will be made terminal-safe by option-backslash_codes. $ xorriso -in_charset ISO-8859-1-local_charset UTF-8 \ -out_charset UTF-8 -backslash_codes on-dev /dev/sr0 \ -alter_date m +0 / -- -commit-eject all

Operate on storage facilities other than opticaldrives

Full read-write operation is possible with regularfiles and block devices: $ xorriso -dev /tmp/regular_file ... Paths underneath /dev normally need prefix"stdio:" $ xorriso -dev stdio:/dev/sdb ... If /dev/sdb is to be used frequently and /dev/sda is thesystem disk, then consider to place the following lines in axorriso Startup File. They allow to use /dev/sdbwithout prefix and protect disk /dev/sda fromxorriso: -drive_class banned /dev/sda* -drive_class harmless /dev/sdb Other writeable file types are supportedwrite-only: $ xorriso -outdev /tmp/named_pipe ... Among the write-only drives is standard output: $ xorriso -outdev - \ ... | gzip >image.iso.gz

Burn an existing ISO image file to medium

Actually this works with any kind of data, not only ISOimages: $ xorriso -as cdrecord -v dev=/dev/sr0blank=as_needed image.iso

Perform multi-session runs as of cdrtoolstraditions

Between both processes there can be performed arbitrarytransportation or filtering. The first session is written like this: $ xorriso -as mkisofs prepared_for_iso/tree1 | \ xorriso -as cdrecord -v dev=/dev/sr0 blank=fast-multi -eject - Follow-up sessions are written like this: $ dd if=/dev/sr0 count=1 >/dev/null 2>&1 $ m=$(xorriso -as cdrecord dev=/dev/sr0-msinfo) $ xorriso -as mkisofs -M /dev/sr0 -C $mprepared_for_iso/tree2 | \ xorriso -as cdrecord -v dev=/dev/sr0-waiti -multi -eject - Always eject the drive tray between sessions. The oldsessions get read via /dev/sr0. Its device driver might notbe aware of the changed content before it loads the mediumagain. In this case the previous session would not be loadedand the new session would contain only the newly addedfiles. For the same reason do not let xorriso -ascdrecord load the medium, but rather do this manually or bya program that reads from /dev/sr0. This example works for multi-session media only. Addcdrskin option --grow_overwriteable_iso to all-as cdrecord runs in order to enablemulti-session emulation on overwriteable media.

Let xorriso work underneath growisofs

growisofs expects an ISO formatter program whichunderstands options -C and -M. Ifxorrisogets started by name "xorrisofs" then it issuitable for that. $ export MKISOFS="xorrisofs" $ growisofs -Z /dev/dvd /some/files $ growisofs -M /dev/dvd /more/files If no "xorrisofs" is available on your system,then you will have to create a link pointing to thexorriso binary and tell growisofs to use it. E.g.by: $ ln -s $(which xorriso)"$HOME/xorrisofs" $ export MKISOFS="$HOME/xorrisofs" One may quit mkisofs emulation by argument"--" and make use of allxorriso commands. growisofs dislikes options whichstart with "-o" but -outdev must beset to "-". So use "outdev"instead: $ growisofs -Z /dev/dvd -- outdev --update_r /my/files /files $ growisofs -M /dev/dvd -- outdev --update_r /my/files /files growisofs has excellent burn capabilities with DVD and BD.It does not emulate session history on overwriteable media,though.

Adjust thresholds for verbosity, exit value andprogram abort

Be quite verbous, exit 32 if severity "FAILURE"was encountered, do not abort prematurely but forcibly go onuntil the end of commands. $ xorriso ... \ -report_about UPDATE \ -return_with FAILURE 32 \ -abort_on NEVER \ ...

Examples of input timestrings

As printed by program date: ’Thu Nov 8 14:51:13CET 2007’ The same without ignored parts: ’Nov 8 14:51:132007’ The same as expected by date: 110814512007.13 Four weeks in the future: +4w The current time: +0 Three hours ago: -3h Seconds since Jan 1 1970: =1194531416

Incremental backup of a few directorytrees

This changes the directory trees /open_source_project and/personal_mail in the ISO image so that they become exactcopies of their disk counterparts. ISO file objects getcreated, deleted or get their attributes adjustedaccordingly. ACL, xattr, hard links and MD5 checksums will be recorded.Accelerated comparison is enabled at the expense ofpotentially larger backup size. Only media with the expectedvolume id or blank media are accepted. Files with namesmatching *.o or *.swp get excluded explicitly. When done with writing the new session gets checked by itsrecorded MD5. $ xorriso \ -abort_on FATAL \ -for_backup -disk_dev_ino on \ -assert_volid ’PROJECTS_MAIL_*’ FATAL\ -dev /dev/sr0 \ -volid PROJECTS_MAIL_"$(date’+%Y_%m_%d_%H%M%S’)" \ -not_leaf ’*.o’ -not_leaf’*.swp’ \ -update_r /home/thomas/projects /projects \ -update_r /home/thomas/personal_mail /personal_mail\ -commit -toc -check_md5 FAILURE-- -eject all To be used several times on the same medium, whenever anupdate of the two disk trees to the medium is desired. Beginwith a blank medium and update it until he run failsgracefully due to lack of remaining space on the oldone. This makes sense if the full backup leaves substantialremaining capacity on media and if the expected changes aremuch smaller than the full backup. To apply zisofscompression to those data files which get newly copied fromthe local filesystem, insert these options immediatelybefore -commit : -hardlinks perform_update \ -find / -type f -pending_data -execset_filter --zisofs -- \ Options -disk_dev_ino and -for_backup depend onstable device and inode numbers on disk. Without them, anupdate run may use -md5 "on" to matchrecorded MD5 sums against the current file content on harddisk. This is usually much faster than the default whichcompares both contents directly. With mount option -o"sbsector=" on GNU/Linux resp.-son FreeBSD it is possible to access the session trees whichrepresent the older backup versions. With CD media,GNU/Linux mount accepts session numbers directly by itsoption "session=". Multi-session media and most overwriteable mediawritten by xorriso can tell the sbsectors of theirsessions byxorriso option -toc. Used after-commit the following option prints the matching mountcommand for the newly written session (here for mount point/mnt): -mount_cmd "indev" "auto""auto" /mnt Options -mount_cmd and -mount are also able toproduce the mount commands for older sessions in thetable-of-content. E.g. as superuser: # osirrox -mount /dev/sr0 "volid"’*2008_12_05*’ /mnt Above example produces a result similar to -root /-old-root / with mkisofs. For getting thesession trees accumulated in the new sessions, let all-update commands use a common parent directory andclone it after updating is done: -update_r /home/thomas/projects /current/projects\ -update_r /home/thomas/personal_mail/current/personal_mail \ -clone /current /"$(date’+%Y_%m_%d_%H%M%S’)" \ The cloned tree will have a name like/2011_02_12_155700. Sessions on multi-session media are separated byseveral MB of unused blocks. So with small sessions thepayload capacity can become substantially lower than theoverall media capacity. If the remaining space on a mediumdoes not suffice for the next gap, the drive is supposed toclose the medium automatically. Better do not use your youngest backup for-update_r. Have at least two media which you usealternatingly. So only older backups get endangered by thenew write operation, while the newest backup is storedsafely on a different medium. Always have a blank medium ready to perform a full backup incase the update attempt fails due to insufficient remainingcapacity. This failure will not spoil the old medium, ofcourse.

Restore directory trees from a particular ISO sessionto disk

This is an alternative to mounting the medium and usingnormal file operations. First check which backup sessions are on the medium: $ xorriso -outdev /dev/sr0 -toc Then load the desired session and copy the file trees todisk. Enable restoring of ACL, xattr and hard links. Avoidto create /home/thomas/restored withoutrwx-permission. $ xorriso -for_backup \ -load volid ’PROJECTS_MAIL_2008_06_19*’\ -indev /dev/sr0 \ -osirrox on:auto_chmod_on \ -chmod u+rwx / -- \ -extract /open_source_projects \ /home/thomas/restored/open_source_projects \ -extract /personal_mail/home/thomas/restored/personal_mail \ -rollback_end The final command -rollback_end prevents an errormessage about the altered image being discarded.

Try to retrieve blocks from a damagedmedium

$ xorriso -abort_on NEVER -indev /dev/sr0\ -check_media time_limit=1800 report=blocks_files \ data_to="$HOME"/dvd_copysector_map="$HOME"/dvd_copy.map -- This can be repeated several times, if necessary with-eject or with other -indev drives. See thehuman readable part of "$HOME"/dvd_copy.map foraddresses which can be used on "$HOME"/dvd_copywith mount option -o sbsector= resp. -s.

FILES

Program alias names:

Normal installation of xorriso creates three linksor copies which by their program name pre-selectcertain settings: xorrisofs starts xorriso with -as mkisofsemulation. xorrecord starts xorriso with -as cdrecordemulation. osirrox starts with -osirrox"on:o_excl_off" which allows to copy files fromISO image to disk and to apply option -mount to one ormore of the existing ISO sessions.

Startup files:

If not -no_rc is given as the first argument thenxorriso attempts on startup to read and execute linesfrom the following files: /etc/default/xorriso /etc/opt/xorriso/rc /etc/xorriso/xorriso.conf $HOME/.xorrisorc The files are read in the sequence given above, but none ofthem is required to exist. The line format is described withcommand -options_from_file. If mkisofs emulation was enabled by program name"xorrisofs", "mkisofs","genisoimage", or "genisofs", thenafterwards -read_mkisofsrc is performed, which reads.mkisofsrc files. See there.

Runtime control files:

The default setting of -check_media abort_file=is: /var/opt/xorriso/do_abort_check_media

SEE ALSO

For the mkisofs emulation of xorriso

xorrisofs(1)

For the cdrecord emulation of xorriso

xorrecord(1)

For mounting xorriso generated ISO 9660 images (-tiso9660)

mount(8)

Libreadline, a comfortable input line facility

readline(3)

Other programs which produce ISO 9660 images

mkisofs(8), genisoimage(8)

Other programs which burn sessions to opticalmedia

growisofs(1), cdrecord(1), wodim(1),cdrskin(1)

ACL and xattr

getfacl(1), setfacl(1), getfattr(1),setfattr(1)

MD5 checksums

md5sum(1)

On FreeBSD the commands for xattr and MD5 differ

getextattr(8), setextattr(8), md5(1)

BUGS

To report bugs, request help, or suggest enhancements forxorriso, please send electronic mail to the publiclist <bug-xorriso@gnu.org>. If more privacy isdesired, mail to <scdbackup@gmx.net>. Please describe what you expect xorriso to do, theprogram arguments resp. commands by which you tried toachieve it, the messages ofxorriso, and theundesirable outcome of your program run. Expect to get asked more questions before solutions can beproposed.

AUTHOR

Thomas Schmitt <scdbackup@gmx.net> for libburnia-project.org

COPYRIGHT

Copyright (c) 2007 - 2011 Thomas Schmitt Permission is granted to distribute this text freely. Itshall only be modified in sync with the technical propertiesofxorriso. If you make use of the license to derivemodified versions ofxorriso then you are entitled tomodify this text under that same license.

CREDITS

xorriso is in part based on work by Vreixo Formosowho provides libisofs together with Mario Danic who alsoleads the libburnia team. Thanks to Andy Polyakov whoinvented emulated growing, to Derek Foreman and Ben Jansenswho once founded libburn. Compliments towards Joerg Schilling whose cdrtools served mefor ten years.

---

---

(HTML generated from xorriso.1 on Sun Nov 20 19:37:45 CET 2011 by man_xorriso_to_html.sh )