MAN page from RedHat EL 8 xorriso1-1.5.4-2.el8.x86_64.rpm
Section: User Commands (1)
Updated: Version 1.5.4, Jan 30, 2021Index
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem imageswith Rock Ridge extensions.
xorrisois a program which copies file objects from POSIX compliantfilesystems into Rock Ridge enhanced ISO 9660 filesystems and performssession-wise manipulation of such filesystems. It can load the managementinformation of existing ISO images and it writes the session results tooptical media or to filesystem objects.
Vice versa xorriso is able to copy file objects out of ISO 9660filesystems.
A special property of xorriso is that it needs neither an externalISO 9660formatter program nor an external 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 new one.
Copies files from disk filesystem into the ISO image.
Copies files from ISO image to disk filesystem (see osirrox).
Renames or deletes file objects in the ISO image.
Changes file properties in the ISO image.
Updates ISO subtrees incrementally to match given disk subtrees.
Writes result either as completely new image or as add-on sessionto optical media or filesystem objects.
Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
Can perform multi-session tasks as emulation of mkisofs and cdrecord.
Can record and restore hard links and ACL.
Content may get zisofs compressed or filtered by external processes.
Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
Can check media for damages and copy readable blocks to disk.
Can attach MD5 checksums to each data file and the whole session.
Scans for optical drives, blanks re-usable optical media.
Reads its instructions from command line arguments, dialog, and files.
Provides navigation commands for interactive ISO image manipulation.
Adjustable thresholds for abort, exit value, and problem reporting.
Note that xorriso does not write audio CDs and that it does notproduce UDF filesystems which are specified for official video DVD or BD.
General information paragraphs:
Media types and states
Creating, Growing, Modifying, Blind Growing
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
Dialog, Readline, Result pager
Maybe you first want to have a look at section EXAMPLES near the end ofthis text before reading the next few hundred lines of background information.
Unlike other filesystems, ISO 9660
)is not intended for read-write operation butrather for being generated in a single sweep and being written to media as asession
The data content of the session is called filesystem image
The written image in its session can then be mounted by the operating systemfor being used read-only. GNU/Linux is able to mount ISO images from blockdevices, which may represent optical media, other media or via a loop deviceeven from regular disk files. FreeBSD mounts ISO images from devices thatrepresent arbitrary media or from regular disk files.
This session usage model has been extended on CD media by the concept ofmulti-session ,which adds information to the CD and gives the mount programsof the operating systems the addresses of the entry points of eachsession. The mount programs recognize block devices which representCD media and will by default mount the image in the last session.
This session usually contains an updated directory tree for the whole mediumwhich governs the data contents in all recorded sessions.So in the view of the mount program all sessions of a particular mediumtogether form a single filesystem image.
Adding a session to an existing ISO image is in this text referred asgrowing.
The multi-session model of the MMC standard does not apply to all mediatypes. But program growisofs by Andy Polyakov showed how to extend thisfunctionality to overwritable media or disk files which carry valid ISO 9660filesystems.
xorriso provides growing as well as an own method namedmodifying which produces a completely new ISO image from the oldone and the modifications.See paragraph Creating, Growing, Modifying, Blind Growing below.
xorriso adopts the concept of multi-session by loading animage directory tree if present,by offering to manipulate it by several actions,and by writing the new image to the target medium.
The first session of a xorriso run begins by the definition ofthe input drive with the ISO image or by the definition 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 freshly written one as input.A new input drive can only be chosen as long as the loaded ISO image wasnot altered. Pending alteration can be revoked by command -rollback.
Writing a session to the target is supposed to be very expensive in terms oftime and of consumed space on appendable or write-once media. Therefore allintended manipulations of a particular ISO image should be done in a singlesession. But in principle it is possibleto store intermediate states and to continue with image manipulations.
Media types and states:
There are two families of media in the MMC standard:Multi-session media
are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, andunformatted DVD-RW. These media provide a table of content whichdescribes their existing sessions. See command -toc
Similar to multi-session media are DVD-R DL and minimally blanked DVD-RW.They record only a single session of which the size must be known in advance.xorriso
will write onto them only if command -close is set to "on".Overwritable media
are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.They offer random write access but do not provide information about theirsession history. If they contain one or more ISO 9660 sessions and if thefirst session was written by xorriso
, then a table of content canbe 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 overwritable media.Pipes and other writeable file types are handled as blank multi-session media.
These media can assume several states in which they offer differentcapabilities.
Blank media can be written from scratch. They contain no ISO imagesuitable for xorriso.
Blank is the state of newly purchased optical media.With used CD-RW and DVD-RW it can be achieved by action -blank "as_needed".Overwritable media are considered blank if they are new or if they havebeen marked as blank by xorriso.Action -blank "as_needed" can be used to do this marking on overwritablemedia, or to apply mandatory formatting to new media if necessary.
Appendable media accept further sessions. Either they are MMCmulti-session media in appendable state, or they are overwritable mediawhich contain an ISO image suitable for xorriso.
Appendable is the state after writing a session with command -close off.
Closed media cannot be written. They may contain an ISO image suitablefor xorriso.
Closed is the state of DVD-ROM media and of multi-session media which werewritten with command -close on. If the drive is read-only hardware then it willprobably show any media as closed CD-ROM or DVD-ROM.
Overwritable media assume this state in such read-only drives or if theycontain unrecognizable data in the first 32 data blocks.
Read-only drives may or may not show session histories of multi-sessionmedia. Often only the first and the last session are visible. Sometimesnot even that. Command -rom_toc_scan might or might not help in such cases.
Creating, Growing, Modifying, Blind Growing:
A new empty ISO image gets created
if there is no input drive with a valid ISO 9660 image when the first timean output drive is defined. This is achieved by command -dev on blank mediaor by command -outdev on media in any state.
The new empty image can be populated with directories and files.Before it can be written, the medium in the output drive must get intoblank state if it was not blank already.
If there is a input drive with a valid ISO image, then this image gets loadedas foundation for manipulations and extension. The constellation of inputand output drive determines which write method will be used.They have quite different capabilities and constraints.
The method of growing adds new data to the existing data on themedium. These data comprise of new file content and they override the existingISO 9660 + Rock Ridge directory tree. It is possible to hide files fromprevious sessions but they still exist on the medium and with many types ofoptical media it is quite easy to recover them by mounting older sessions.
Growing is achieved by command -dev.
The write method of modifying produces compact filesystemimages with no outdated files or directory trees. Modifying can write itsimages to target media which are completely unsuitable for multi-sessionoperations. E.g. DVD-RW which were treated with -blank deformat_quickest,DVD-R DL, named pipes, character devices, sockets.On the other hand modified sessions cannot be written to appendable mediabut to blank media only.
So for this method one needs either two optical drives or has to work withfilesystem objects as source and/or target medium.
Modifying takes place if input drive and output drive are not the same andif command -grow_blindly is set to its default "off".This is achieved by commands -indev and -outdev.
If command -grow_blindly is set to a non-negative number and if -indev and-outdev are both set to different drives, then blind growing isperformed. It produces an add-on session which is ready for being writtento the given block address. This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
which gives much room for wrong parameter combinations and should thus only beemployed if a strict distinction between ISO formatter xorrisoand the burn program is desired. -C $msc1,$msc2 is equivalent to:
-load sbsector $msc1 -grow_blindly $msc2
Input drive, i.e. source of an existing or empty ISO image, can be any randomaccess 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 libburn drive.Some drive types do not support the method of growing but only the methodsof modifying and blind growing. They all are suitable for newly created images.
All drive file objects have to offer rw-permission to the user ofxorriso.Even those which will not be usable for reading an ISO image.
With any type of drive object, the data are considered to be organized inblocks of 2 KiB. Access happens in terms of Logical Block Address(LBA) which gives the number of a particular data block.
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed bythe path of their block device or of their generic character device. E.g.
By default xorriso will try to map the given address to /dev/hd* and /dev/sr*.The command -scsi_dev_family can redirect the mapping from sr to scd or sg.The latter does not suffer from the concurrency problems which plague /dev/srof Linux kernels since version 3. But it does not yield the same addresseswhich are used by mount(8) or by open(2) for read(2).
On FreeBSD the device files have names like
Get a list of accessible drives by command
It might be necessary to do this assuperuserin order to see all drives and to then allow rw-access for the intended users.Consider to bundle the authorized users in a group like old "floppy".
Filesystem objects of nearly any type can be addressed by prefix "stdio:" andtheir path in the filesystem. E.g.:
The default setting of -drive_class allows the user to address files outsidethe /dev tree without that prefix. E.g.:
If path leads to a regular file or to a block device then the emulated driveis random access readable and can be used for the method of growing if italready contains a valid ISO 9660 image. Any other file type is not readablevia "stdio:" and can only be used as target for the method of modifying orblind growing.Non-existing paths in existing directories are handled as empty regular files.
A very special kind of pseudo drive are open file descriptors. They aredepicted by "stdio:/dev/fd/" and descriptor number (see man 2 open).
Addresses "-" or "stdio:/dev/fd/1" depict standard output, which normally isthe output channel for result texts.To prevent a fatal intermingling of ISO image and text messages, all resulttexts get redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is amongthe start arguments of the program.
Standard output is currently suitable for creating one sessionper program run without dialog. Use in other situations is discouragedand several restrictions apply:
It is not allowed to use standard output as pseudo drive if it was notamong the start arguments. Do not try to fool this ban via backdoor addressesto stdout.
If stdout is used as drive, then -use_readline is permanently disabled.Use of backdoors can cause severe memory and/or tty corruption.
Be aware that especially the superuser can write into any accessible file ordevice by using its path with the "stdio:" prefix. By default any addressin the /dev tree without prefix "stdio:" will work only if it leads to a MMCdrive.
One may use command-ban_stdio_writeto surely prevent this risk and to restrict drive usage to MMC drives.
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:".
By command -drive_class one may ban certain paths or allow access withoutprefix "stdio:" to other paths.
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:Rock Ridge
is the name of a set of additional information which enhancean ISO 9660 filesystem so that it can represent a POSIX compliant filesystemwith ownership, access permissions, symbolic links, and other attributes.
This is what xorriso
uses for a decent representation of the diskfiles within the ISO image. xorriso
produces Rock Ridge informationby default. It is strongly discouraged to disable this feature.
xorriso is not named "porriso" because POSIX only guarantees14 charactersof filename length. It is the X/Open System Interface standard XSI whichdemands a file name length of up to 255 characters and paths of up to 1024characters. Rock Ridge fulfills this demand.
An El Toritoboot record points the BIOS bootstrapping facility to one or more bootimages, which are binary program files stored in the ISO image.The content of the boot image files is not in the scope of El Torito.
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images.xorriso is able to create or maintain an El Torito object whichmakes such an image bootable. For details see command -boot_image.
It is possible to make ISO images bootable from USB stick or otherhard-disk-like media. Several options install a MBR(Master Boot Record), It may get adjusted according to the needs of theintended boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX.A MBR contains boot code and a partition table.The new MBR of a follow-up session can get in effectonly on overwritable media.
MBR is read by PC-BIOS when booting from USB stick or hard disk,and by PowerPC CHRP or PReP when booting.An MBR partition with type 0xee indicates the presence of GPT.
Emulation -as mkisofs supports the example options out of the ISOLINUX wiki,the options used in GRUB script grub-mkrescue, and the example in theFreeBSD AvgLiveCD wiki.
A GPT (GUID Partition Table) marks partitions in a more modern way.It is read by EFI when booting from USB stick or hard disk, and may be usedfor finding and mounting a HFS+ partition inside the ISO image.
An APM (Apple Partition Map) marks the HFS+ partition.It is read by Macs for booting and for mounting.
MBR, GPT and APM are combinable. APM occupies the first 8 bytes ofMBR boot code. All three do not hamper El Torito booting from CDROM.
There is support for further facilities:MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC, HP-PA.Those are mutually not combinable and also not combinable with MBR, GPT,or APM.
ACLare an advanced way of controlling access permissions to file objects. NeitherISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs hasintroduced a standard conformant extension named AAIP for that purpose.It uses this extension if enabled by command-acl.
AAIP enhanced images are supposed to be mountable normally, but one cannotexpect that the mounted filesystem will show and respect the ACLs.For now, only xorriso is able to retrieve those ACLs.It can bring them intoeffect when files 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 of entry "mask::" ifthat entry exists. Nevertheless the non-listed group members get handledaccording to entry "group::". When removing ACL from a file,xorriso brings "group::" into effect.
Recording and restoring of ACLs from and to local files works currentlyonly on GNU/Linux and FreeBSD.
xattr (aka EA, or extattr)are pairs of name and value which can be attached to file objects. AAIP isable to represent them and xorriso can record and restore them.
But be aware that pairs with names of non-user namespaces are not necessarilyportable between operating systems and not even between filesystems.Only those which begin with "user.", like "user.x" or "user.whatever",can unconditionally be expected to be appropriate on other machines and disks.Processing of other xattr may need administrator privileges.
Name has to be a 0 terminated string.Value may be any array of bytes which does not exceed the size of 4095 bytes.xattr processing happens only if it is enabled by command-xattr.
As with ACL, currently only xorriso is able to retrieve xattrfrom AAIP enhanced images, to restore them to xattr capable file systems,or to print them.
Recording and restoring of xattr from and to local files works currentlyonly on GNU/Linux and FreeBSD, where they are known as extattr.
Commands are either actions which happen immediately or settings whichinfluence following actions. So their sequence does matter, unless they aregiven as program arguments and command-x
is among them.
Commands consist of a command word,followed by zero or more parameter words. If the list of parameter wordsis of variable length (indicated by "[...]" or "[***]") then it must beterminated by either the list delimiter
, occur at the end ofthe argument list, or occur at the end of an input line.
At program start the list delimiter is the string "--".This may be changed with the -list_delimiter command in order to allow"--" as parameter in a variable length list.However, 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 ignored if it appears after the parameters ofa command with a fixed list length. It is handled as normal text if itappears among the parameters of such a command.
Pattern expansionconverts a list of pattern words into a list of existing file addresses.Unmatched pattern words will appear unaltered in that result list.
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]'and respects '/' as the path separator, which may only be matched literally.
Pattern expansion is a property of some particular commands and not a generalfeature. It is controlled by commands -iso_rr_pattern and -disk_pattern.Commands which use pattern expansion all have variable parameterlists which are specified in this text by "[***]" rather than "[...]".
Some other commands perform pattern matching unconditionally.
Command and parameter words are either read from the program arguments, whereone argument is one word, or from quoted input lines where words are recognizedsimilar to the quotation rules of a shell parser.
xorriso is not a shell, although it might appear so at first glimpse.Be aware that the interaction of quotation marks and pattern symbols like "*"differs from the usual shell parsers. In xorriso, a quotation markdoes not make a pattern symbol literal.
Quoted inputconverts whitespace-separated text into words.The double quotation mark " and the single quotation mark ' can be used toenclose whitespace and make it part of words (e.g. of file names). Each marktype can enclose the marks of the other type. A trailing backslash \ outsidequotations or an open quotation cause the next input line to be appended.
Quoted input accepts any 8-bit character except NUL (0) as the content ofthe quotes.Nevertheless it can be cumbersome for the user to produce those charactersdirectly. Therefore quoted input and program arguments offer optionalBackslash Interpretationwhich can represent all 8-bit characters except NUL (0) via backslash codesas in $'...' of bash.
This is not enabled by default. See command -backslash_codes.
When the program starts then it first looks for argument -no_rc. If this isnot present then it looks for its startup files andreads their content as command input lines. Then it interpretsthe program arguments as commands and parameters. Finally it entersdialog mode if command -dialog "on" has been executed by this point.
The program ends either by command -end, or by the end of program argumentsif dialog mode has not been enabled at that point, or by a problemevent which triggers the threshold of command -abort_on.
Dialog, Readline, Result pager:
Dialog mode prompts for a quoted input line, parses it into words, and performsthem as commands with their parameters. It provides assisting servicesto make dialog more comfortable.
Readline is an enhancement for the input line. You may already know it fromthe bash shell. Whether it is available in xorriso depends on theavailabilityof package readline-dev at the time when xorriso was built fromits sourcecode.
Readline lets the user move the cursor over the text in the line by help of theLeft and the Right arrow keys.Text may be inserted at the cursor position. The Delete key removes thecharacter under the cursor. Up and Down arrow keys navigate throughthe history of previous input lines.
See man readlinefor more info about libreadline.
Command -page activates a built-in result text pager which may be convenient indialog mode. After an action has output the given number of terminal lines,the pager prompts the user for a line of input.
An empty line lets xorriso resume work until the next page is output.
The single character "@" disables paging for the current action.
"@@@", "x", "q", "X", or "Q" request that the current action aborts andsuppress further result output.
Any other line input will be interpreted as new dialog line. The current actionis requested to abort. Afterwards, the input line is executed.
Some actions apply paging to their info output, too.
The request to abort may or may not be obeyed by the current action.All actions try to abort as soon as possible.
All command words are shown with a leading dash although this dash is notmandatory for the command to be recognized. Nevertheless within command -asthe dashes of the emulated commands are mandatory.
Normally any number of leading dashes is ignored with command words andinner dashes are interpreted as underscores.
- Execution order of program arguments:
By default the program arguments of a xorriso run are interpreted as asequence of commands which get performed exactly in the given order.This requires the user to write commands for desired settings before thecommands which shall be influenced by those settings.
Many other programs support program arguments in an arbitrary orderingand perform settings and actions in a sequence at their own discretion.xorriso provides an option to enable such a behaviorat the cost of loss of expressivity.
- Enable automatic sorting of program arguments into a sequence that(most likely) is sensible.This command may be given at any position among the commandswhich are handed over as program arguments.
Note: It works only if it is given as program argument andwith a single dash (i.e. "-x"). It will not work in startup files, nor with-options_from_file, nor in dialog mode, nor as "x" and finally not as"--x".It affects only the commands given as program arguments.
- List all xorriso commands in the order which applies if command -x is ineffect.
This list may also be helpful without -x for a user who ponders over thesequence in which to put commands. Deviations from the listed sorting order maywell make sense, though.
- Acquiring source and target drive:
The effect of acquiring a drive may depend on several commands in thenext paragraph "Influencing the behavior of image loading".If desired, their enabling commands have to be performed before thecommands which acquire the drive.
- -dev address
- Set input and output drive to the same address and load an ISO image if itis present.If there is no ISO image then create a blank one.Set the image expansion method to growing.
This is only allowed as long as no changes are pending in the currentlyloaded ISO image. If changes are pending, then one has to perform -commitor -rollback first.
Special address string "-" means standard output, to which several restrictionsapply. See above paragraph "Libburn drives".
An empty address string "" gives up the current devicewithout acquiring a new one.
- -indev address
- Set input drive and load an ISO image if present.If the new input drive differsfrom -outdev then switch from growing to modifying or to blind growing.It depends on the setting of -grow_blindly which of both gets activated.The same rules and restrictions apply as with -dev.
- -outdev address
- Set output drive and if it differs from the input drive then switch fromgrowing to modifying or to blind growing. Unlike -dev and -indev this actiondoes not load a new ISO image. So it can be performed even if there are pendingchanges.
-outdev can be performed without previous -dev or -indev. In that case anempty ISO image with no changes pending is created. It can either be populatedby help of -map, -add et.al. or it can be discarded silently if -dev or -indevare performed afterwards.
Special address string "-" means standard output, to which several restrictionsapply. See above paragraph "Libburn drives".
An empty address string "" gives up the current output drivewithout acquiring a new one. No writing is possible without an output drive.
- -drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern
- Add a drive path pattern to one of the safety lists or make those lists empty.There are three lists defined which get tested in the following sequence:
If a drive address path matches the "harmless" list then the drive will beaccepted. If it is not a MMC device then the prefix "stdio:" will be prependedautomatically. This list is empty by default.
Else if the path matches the "banned" list then the drive will not beaccepted by xorriso but rather lead to a FAILURE event.This list is empty by default.
Else if the path matches the "caution" list and if it is not a MMC device,then its address must have the prefix "stdio:" or it will be rejected.This list has by default one entry: "/dev".
If a drive path matches no list then it is considered "harmless". By defaultthese are all paths which do not begin with directory "/dev".
A path matches a list if one of its parent paths or itself matches a listentry. Address prefix "stdio:" or "mmc:" will be ignored whentesting for matches.
By pseudo-class "clear_list" and pseudo-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 one of the xorrisoStartup Files.
Note: This is not a security feature but rather a bumper for the superuser toprevent inadverted mishaps. For reliably blocking access to a device file youhave to deny its rw-permissions in the filesystem.
- -drive_access "exclusive"|"shared":"unrestricted"|"readonly"
- Control whether device file locking mechanisms shall be used when acquiring adrive, and whether status or content of the medium in the drive may bealtered. Useful and most harmless are the setting "shared:readonly"and the default setting "exclusive:unrestricted".
"exclusive" enables tests and locks when acquiring the drive. It depends on theoperating system which locking mechanisms get applied, if any. On GNU/Linuxit is open(O_EXCL). On FreeBSD it is flock(LOCK_EX).
"shared" disables the use of these mechanisms to become able to acquire driveswhich are mounted, or opened by some process, or guarded by /dev/pktcdvd*.
"unrestricted" enables all technically appropriate operations on an acquireddrive. "shared:unrestricted" risks to get own burn runs spoiled by otherprocesses or to vice versa spoil activities of such processes. So use"exclusive:unrestricted" unless you know for sure that "shared" is safe.
"readonly" disables operations which might surprise a co-user of the drive.For -outdev these are formatting, blanking, writing, ejecting. For -indevthis is ejecting. Be aware that even reading and drive status inquiries candisturb an ongoing burn run on CD-R[W] and DVD-R[W].
- -scsi_dev_family "default"|"sr"|"scd"|"sg"
- GNU/Linux specific:
By default, xorriso tries to map Linux drive addresses to /dev/sr* beforethey get opened for operating the drive. This coordinates well withother use cases of optical drives, like mount(8). But since year 2010all /dev/sr* share a global lock which allows only one drive to processan SCSI command while all others have to wait for its completion.This yields awful throughput if more than one drive is writing or readingsimultaneously.The global lock is not applied to device files /dev/sg* and also not ifthe xorriso drive address is prepended by "stdio:".
So for simultaneous burn runs on modern GNU/Linux it is advisable to perform-scsi_dev_family "sg" before any -dev, -indev, or -outdev. The drive addressesmay then well be given as /dev/sr* but will nevertheless get used asthe matching /dev/sg*.
If you decide so, consider to put the command into a global startup file like/etc/opt/xorriso/rc.
- -grow_blindly "off"|predicted_nwa
- If predicted_nwa is a non-negative number then perform blind growing ratherthan modifying if -indev and -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-on session of blindgrowing will finally end up. It is the responsibility of the user to ensurethis final position and the presence of the older sessions. Else theoverall ISO image will not be mountable or will produce read errors whenaccessing file content. xorriso will write the session to the addressas obtained from examining -outdev and not necessarily to predicted_nwa.
During a run of blind growing, the input drive is given up before outputbegins. The output drive is given up when writing is done.
- Influencing the behavior of image loading:
The following commands should normally be performed before loading an imageby acquiring an input drive. In rare cases it is desirable to activatethem only after image loading.
- -read_speed code|number[k|m|c|d|b]
- Set the speed for reading. Default is "none", which avoids to send a speedsetting command to the drive before reading begins.
Further special speed codes are:
"max" (or "0") selects maximum speed as announced by the drive.
"min" (or "-1") selects minimum speed as announced by the drive.
Speed can be given in media dependent numbers or as adesired throughput per second in MMC compliant kB (= 1000)or MB (= 1000 kB). Media x-speed factor can be set explicitlyby "c" for CD, "d" for DVD, "b" for BD, "x" is optional.
706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD
If there is no hint about the speed unit attached, then themedium in the -indev will decide. Default unit is CD = 176.4k.
Depending on the drive, the reported read speeds can be deceivingly lowor high. Therefore "min" cannot become higher than 1x speed of the involvedmedium type. Read speed "max" cannot become lower than 52xCD, 24xDVD,or 20xBD, depending on the medium type.
MMC drives usually activate their own idea of speed and take the speed valuegiven by the burn program only as hint for their own decision. Friendly drivesadjust their constant angular velocity so that the desired speed is reachedat the outer rim of the medium. But often there is only the choice betweenvery slow and very loud.
Sometimes no speed setting is obeyed at all, but speed is adjusted to thedemand frequency of the reading program. So xorriso offers to set an additionalsoftware enforced limit by prefix "soft_force:". The program will take carenot to read faster than the soft_force speed.This may be combined with setting the drive speed to a higher value.Setting "soft_force:0" disables this feature.
"soft_force:" tries to correct in subsequent waiting periods lost or surplustime of up to 0.25 seconds. This smoothens the overall data stream but alsoenables short times of higher speed to compensate short times of low speed.Prefix "soft_corr:" sets this hindsight span by giving a number ofmicroseconds. Not more than 1 billion = 1000 seconds.Very short times can cause speed deviations, because systematic inaccuracies ofthe waiting function cannot be compensated.
-read_speed soft_force:4xBD -read_speed soft_corr:100000
- -load entity id
- Load a particular (possibly outdated) ISO session from -dev or -indev.Usually all available sessions are shown with command -toc.
entity depicts the kind of addressing. id depicts the particularaddress. 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 of a line "ISO ...", column "sbsector".
"volid" with a search pattern for a text as of a line "ISO ...",column "Volume Id".
Addressing a non-existing entity or one which does not represent an ISOimage will either abandon -indev or at least lead to a blank image.
If an input drive is set at the moment when -load is executed, then theaddressed ISO image is loaded immediately. Else, the setting will be pendinguntil the next -dev or -indev. After the image has been loaded once, thesetting is valid for -rollback until next -dev or -indev, where itwill be reset to "auto".
- -displacement [-]lba
- Compensate a displacement of the image versus the start addressfor which the image was prepared. This affects only loading of ISO imagesand reading of their files. The multi-session method of growing is not allowedas long as -displacement is non-zero. I.e. -indev and -outdev must bedifferent. The displacement gets reset to 0 before the drivegets re-acquired after writing.
If a track of a CD starts at block 123456 and gets copied to a disk filewhere it begins at block 0, then this copy can be loaded with
If an ISO image was written onto a partition with offset of 640000 blocks of512 bytes, then it can be loaded from the base device by
-load sbsector 160000 -displacement 160000
(If the partition start address is not divisible by 4, then you will haveto employ a loop device instead.)
In both cases, the ISO sessions should be self contained, i.e. not add-onsessions to an ISO image outside their track or partition.
- -read_fs "any"|"norock"|"nojoliet"|"ecma119"
- Specify which kind of filesystem tree to load if present. If the wish cannotbe fulfilled, then ECMA-119 names are loaded and converted accordingto -ecma119_map.
"any" first tries to read Rock Ridge. If not present, Joliet is tried.
"norock" does not try Rock Ridge.
"nojoliet" does not try Joliet.
"ecma119" tries neither Rock Ridge nor Joliet.
- -assert_volid pattern severity
- Refuse to load ISO images with volume IDs which do not match the givensearch pattern. When refusing an image, give up the input drive and issuean event of the given severity (like FAILURE, see -abort_on). An empty searchpattern accepts any image.
This command does not hamper the creation of an empty image from blankinput media and does not discard an already loaded image.
- -in_charset character_set_name
- Set the character set from which to convert file names when loading animage. See paragraph "Character sets" for more explanations.When loading the written image after -commit the setting of -out_charsetwill be copied to -in_charset.
- -auto_charset "on"|"off"
- Enable or disable recording and interpretation of the output characterset name in an xattr attribute of the image root directory. If enabled andif a recorded character set name is found, then this name will be used asname of the input character set when reading an image.
Note that the default output charset is the local character set of theterminal where xorriso runs. Before attributing this localcharacter setto the produced ISO image, check whether the terminal properly displaysall intended filenames, especially exotic national characters.
- -hardlinks mode[:mode...]
- Enable or disable loading and recording of hardlink relations.
In default mode "off", iso_rr files lose their inode numbers at image loadtime. Each iso_rr file object which has no inode number at image generationtime will get a new unique inode number if -compliance is set to new_rr.
Mode "on" preserves inode numbers from the loaded image if such numberswere recorded.When committing a session it searches for families of iso_rr fileswhich stem from the same disk file, have identical content filtering and haveidentical properties. The family members all get the same inode number.Whether these numbers are respected at mount time depends on the operatingsystem.
Command -lsl displays hardlink counts if "lsl_count" is enabled. This canslow down the command substantially after changes to the ISO image havebeen made. Therefore the default is "no_lsl_count".
Commands -update and -update_r track splits and fusions of hard links infilesystems which have stable device and inode numbers. This can causeautomatic last minute changes before the session gets written. Command-hardlinks "perform_update" may be used to do these changes earlier,e.g. if you need to apply filters to all updated files.
Mode "without_update" avoids hardlink processing during update commands.Use this if your filesystem situation does not allow -disk_dev_ino "on".
xorriso commands which extract files from an ISO image try tohardlink fileswith identical inode number. The normal scope of this operation is fromimage load to image load. One may give up the accumulated hard link addressesby -hardlinks "discard_extract".
A large number of hardlink families may exhaust -temp_mem_limitif not -osirrox "sort_lba_on" and -hardlinks "cheap_sorted_extract"are both in effect. This restricts hard linking to other files restored bythe same single extract command. -hardlinks "normal_extract" re-enableswide and expensive hardlink accumulation.
- -acl "on"|"off"
- Enable or disable processing of ACLs.If enabled, then xorriso will obtain ACLs from disk file objects,store ACLs in the ISO image using the libisofs specific AAIP format,load AAIP data from ISO images, test ACL during file comparison,and restore ACLs to disk files when extracting them from ISO images.See also commands -getfacl, -setfacl.
- -xattr "on"|"user"|"any"|"off"
- Enable or disable processing of xattr attributes.If enabled, then xorriso will handle xattr similar to ACL.See also commands -getfattr, -setfattr and above paragraph about xattr.
Modes "on" and "user" read and write only attributes from namespace "user".
Mode "any" processes attributes of all namespaces. This might needadministrator privileges, even if the owner of the disk file tries to read orwrite the attributes.
Note that xattr from namespace "isofs." are never read from disk or restoredto disk. Further it is not possible to set them via xorriso xattr manipulationcommands.
- -md5 "on"|"all"|"off"|"load_check_off"
- Enable or disable processing of MD5 checksums for the overall session and foreach single data file. If enabled then images with checksum tags get loadedonly if the tags of superblock and directory tree match properly. The MD5checksums of data files and whole session get loaded from the image if thereare any.
With commands -compare and -update the recorded MD5 of a filewill be used to avoid content reading from the image. Only the disk filecontent will be read and compared with that MD5. This can save much timeif -disk_dev_ino "on" is not suitable.
Commands which copy whole data files from ISO to hard disk will verify thecopied data stream by the recorded MD5, if -osirrox "check_md5_on" is set.
At image generation time they are computed for each file which gets its datawritten into the new session. The checksums of files which have their datain older sessions get copied into the new session. Superblock, tree and wholesession get a checksum tag each.
Mode "all" will additionally check during image generation whether the checksumof a data file changed between the time when its reading began and the timewhen it ended. This implies reading every file twice.
Mode "load_check_off" together with "on" or "all" will load recorded MD5 sumsbut not test the recorded checksum tags of superblock and directory tree.This is necessary if growisofs was used as burn program, because it doesnot overwrite the superblock checksum tag of the first session.Therefore load_check_off is in effect when xorriso -as mkisofsoption -M is performed.
The test can be re-enabled by mode "load_check_on".
Checksums can be exploited via commands -check_md5, -check_md5_r, via findactions get_md5, check_md5, and via -check_media.
- Enable all extra features which help to produce or to restore backups withhighest fidelity of file properties. Currently this is a shortcut for:
-hardlinks on -acl on -xattr any -md5 on
If you restore a backup with xattr from non-user namespaces, then make surethat the target operating system and filesystem know what these attributesmean. Possibly you will need administrator privileges to record or restoresuch attributes. At recording time, xorriso will try to tolerate missingprivileges and just record what is readable.But at restore time, missing privileges will cause failure events.
Command -xattr "user" after command -for_backup excludes non-user attributesfrom being recorded or restored.
- -ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase"
- Choose the conversion of file names when a session gets loaded, if they stemneither from a Rock Ridge name nor from a Joliet name.
Mode "stripped" is the default. It shows the names as found in the ISO butremoves trailing ";1" or ".;1" if present.
Mode "unmapped" shows names as found without removing characters.Warning: Multi-session converts "xyz;1" to "xyz_1" and maybe adds new ";1".
Mode "lowercase" is like "stripped" but also maps uppercase letters tolowercase letters. This is compatible to default GNU/Linux mount behavior.
Mode "uppercase" is like "stripped" but maps lowercase letters to uppercase,if any occur despite the prescriptions of ECMA-119.
- -joliet_map "stripped"|"unmapped"
- Choose the conversion of file names when a session gets loaded from a Joliet tree.
Mode "stripped" is the default. It removes trailing ";1" or ".;1" if present.
Mode "unmapped" shows names as found without removing characters.Warning: Multi-session converts "xyz;1" to "xyz_1" and maybe adds new ";1".
- -iso_nowtime "dynamic"|timestring
- Choose whether to use the current time ("dynamic") or a fixed time pointfor timestamps of ISO 9660 nodes without a disk source file and as defaultfor superblock timestamps.
If a timestring is given, then it is used for such timestamps. For the formatsof timestrings see command -alter_date.
- -disk_dev_ino "on"|"ino_only"|"off"
- Enable or disable processing of recorded file identification numbers(dev_t and ino_t). If enabled they are stored as xattr and cansubstantially accelerate file comparison. The root node gets a global starttimestamp. If during comparison a file with younger timestamps is found in theISO image, then it is suspected to have inconsistent content.
If device numbers and inode numbers of the disk filesystems are persistentand if no irregular alterations of timestamps or system clock happen,then potential content changes can be detected without reading that content.File content change is assumed if any of mtime, ctime, device number or inodenumber have changed.
Mode "ino_only" replaces the precondition that device numbers are stable by theprecondition that mount points in the compared tree always lead to thesame filesystems. Use this if mode "on" always sees all files changed.
The speed advantage appears only if the loaded session was produced with-disk_dev_ino "on" too.
Note that -disk_dev_ino "off" is totally in effect only if -hardlinks is "off",too.
- -file_name_limit [+]number
- Set the maximum permissible length for file names in the range of 64 to 255.Path components which are longer than the given number will get truncatedand have their last 33 bytes overwritten by a colon ':' and thehex representation of the MD5 of the first 4095 bytes of the wholeoversized name. Potential incomplete UTF-8 characters will get theirleading bytes replaced by '_'.
iso_rr_paths with the long components will still be able to access thefile paths with truncated components.
If -file_name_limit is executed while an ISO tree is present, the file namesin the ISO tree get checked for existing truncated file names of the currentlimit and for name collisions between newly truncated files and existing files.In both cases, the setting will be refused with a SORRY event.
One may lift this ban by prepending the character "+" to the argumentof -file_name_limit. Truncated filenames may then get truncated again,invalidating their MD5 part. Colliding truncated names are made unique,consuming at least 9 more bytes of the remaining name part.
If writing of xattr is enabled, then the length will be stored in "isofs.nt"of the root directory.If reading of xattr is enabled and "isofs.nt" is found, then the found lengthwill get into effect if it is smaller than the current settingof -file_name_limit.
File name patterns will only work if they match the truncated name.This might change in future.
Files with truncated names get deleted and re-added unconditionallyduring -update and -update_r. This might change in future.
Linux kernels up to at least 4.1 misrepresent names of length 254 and 255.If you expect such names in or under disk_paths and plan to mount the ISOby such Linux kernels, consider to set -file_name_limit 253.Else just avoid names longer than 253 characters.
- -rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"]
- Read-only drives do not tell the actual media type but show any media asROM (e.g. as DVD-ROM). The session history of MMC multi-session media mightbe truncated to first and last session or even be completely false.(The emulated history of overwritable media is not affected by this.)
To have in case of failure a chance of getting the session history andespecially the address of the last session, there is a scan for ISO 9660filesystem headers which might help but also might yield worse resultsthan the drive's table of content. At its end it can cause read attemptsto invalid addresses and thus ugly drive behavior.Setting "on" enables that scan for alleged read-only media.
Some operating systems are not able to mount the most recent session ofmulti-session DVD or BD. If on such a system xorriso has no own MMCcapabilities then it may still find that session from a scanned table ofcontent. Setting "force" handles any media like a ROM medium with setting "on".
On the other hand the emulation of session history on overwritable mediacan hamper reading of partly damaged media. Setting "off:emul_off" disablesthe elsewise trustworthy table-of-content scan for those media.
The table-of-content scan on overwritable media normally searches only up tothe end of the session that is pointed to by the superblock at block 0.Setting "on:emul_wide" lets the scan continue up to the end of the medium.This may be useful after copying a medium with -check_media patch_lba0=onwhen not the last session was loaded.
- -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
- Reduce drive noise until it is actually used again. Some drives stay alertfor substantial time after they have been used for reading. This reducesthe startup time for the next drive operation but can be loud and wasteenergy if no i/o with the drive is expected to happen soon.
Modes "in", "out", "all" immediately calm down -indev, -outdev, or both,respectively.Mode "revoke" immediately alerts both.Mode "on" causes -calm_drive to be performed automatically after each -dev,-indev, and -outdev. Mode "off" disables this.
- Allow for writing only the usage of MMC optical drives. Disallowto write the result into files of nearly arbitrary type.Once set, this command cannot be revoked.
- -early_stdio_test "on"|"appendable_wo"|"off"
- If enabled by "on" then regular files and block devices get tested foreffective access permissions. This implies to try opening those files forwriting, which otherwise will happen only later and only if actualwriting is desired.
The test result is used for classifying the pseudo drives as overwritable,read-only, write-only, or uselessly empty. This may lead to earlier detectionof severe problems, and may avoid some less severe error events.
Mode "appendable_wo" is like "on" with the additional property thatnon-empty write-only files are regarded as appendable rather than blank.
- -data_cache_size number_of_tiles blocks_per_tile
- Set the size and granularity of the data cache which is used when ISO imagesare loaded and when file content is read from ISO images. The cache consistsof several tiles, which each consists of several blocks. A larger cachereduces the need for tiles being read multiple times. Larger tiles mightadditionally improve the data throughput from the drive, but can bewasteful if the data are scattered over the medium.
Larger cache sizes help best with image loading from MMC drives. They are aninferior alternative to -osirrox option "sort_lba_on".
blocks_per_tile must be a power of 2. E.g. 16, 32, or 64. The overall cachesize must not exceed 1 GiB.The default values can be restored by parameter "default" instead of one orboth of the numbers.Currently the default is 32 tiles of 32 blocks = 2 MiB.
- Inserting files into ISO image:
The following commands expect file addresses of two kinds:
disk_pathis a path to an object in the local filesystem tree.
iso_rr_pathis the Rock Ridge name of a file object in the ISO image.If no Rock Ridge information is recorded in the loaded ISO image, then youwill see ISO 9660 names which are of limited length and character set.If no Rock Ridge information shall be stored in an emerging ISO image, thentheir names will get mapped to such restricted ISO 9660 (aka ECMA-119) names.
Note that in the ISO image you are as powerful as the superuser. Accesspermissions of the existing files in the image do not apply to your writeoperations. They are intended to be in effect with the read-only mounted image.
If the iso_rr_path of a newly inserted file leads to an existingfile object in the ISO image, then the following collision handlinghappens:
If both objects are directories then they get merged by recursively insertingthe subobjects from filesystem into ISO image.If other file types collide then the setting of command-overwritedecides.
Renaming of files has similar collision handling, but directories can onlybe replaced, not merged. Note that if the target directory exists, then -mvinserts the source objects into this directory rather than attemptingto replace it. Command -move, on the other hand, would attempt to replace it.
The commands in this section alter the ISO image and not the local filesystem.
- -disk_pattern "on"|"ls"|"off"
- Set the pattern expansion mode for the disk_path parameters of severalcommands which support this feature.
Setting "off" disables this feature for all commands which are marked in thisman page by "disk_path [***]" or "disk_pattern [***]".
Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked 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" or "as_mkisofs" then pattern expansion is alwaysdisabled and character '=' has a special meaning. It separates the ISO imagepath from the disk path:
Character '=' in the iso_rr_path must be escaped by '\' (i.e. as "\=").
With -pathspecs "on", the character '\' must not be escaped. The character '='in the disk_path must not be escaped.
With -pathspecs "as_mkisofs", all characters '\' must be escaped in both,iso_rr_path and disk_path. The character '=' may or may not be escapedin the disk_path.
If iso_rr_path does not begin with '/' then -cd is prepended.If disk_path does not begin with '/' then -cdx is prepended.
If no '=' is given then the word is used as both, iso_rr_path and disk path.If in this case the word does not begin with '/' then -cdx is prepended tothe disk_path and -cd is prepended to the iso_rr_path.
If -pathspecs is set to "off" then -disk_pattern expansion applies, if enabled.The resulting words are used as both, iso_rr_path and disk path. Relativepath words get prepended the setting of -cdx to disk_path and the settingof -cd to iso_rr_path.
- -add_plainly mode
- If set to mode "unknown" then any command word that does not begin with "-" andis not recognized as known command will be subject to a virtual -add command.I.e. it will be used as pathspec or as disk_path and added to the image.If enabled, -disk_pattern expansion applies to disk_paths.
Mode "dashed" is similar to "unknown" but also adds unrecognized commandwords even if they begin with "-".
Mode "any" announces that all further words are to be added as pathspecsor disk_paths. This does not work in dialog mode.
Mode "none" is the default. It prevents any words from being understoodas files to add, if they are not parameters to appropriate commands.
- -path_list disk_path
- Like -add but read the parameter words from file disk_pathor standard input if disk_path is "-". The list must contain exactly one pathspec or disk_path pattern per line.
- -quoted_path_list disk_path
- Like -path_list but with quoted input reading rules. Lines get split intoparameter words for -add. Whitespace outside quotes is discarded.
- -map disk_path iso_rr_path
- Insert file object disk_path into the ISO image as iso_rr_path. If disk_pathis a directory then its whole sub tree is inserted into the ISO image.
- -map_single disk_path iso_rr_path
- Like -map, but if disk_path is a directory then its sub tree is not inserted.
- -map_l disk_prefix iso_rr_prefix disk_path [***]
- Perform -map with each of the disk_path parameters. iso_rr_path will becomposed from disk_path by replacing disk_prefix by iso_rr_prefix.
- -update disk_path iso_rr_path
- Compare file object disk_path with file object iso_rr_path. If they do notmatch, then perform the necessary image manipulations to make iso_rr_patha matching copy of disk_path. By default this comparison will imply lengthycontent reading before a decision is made. Commands -disk_dev_ino or -md5 mayaccelerate comparison if they were already in effect when the loaded sessionwas recorded.
If disk_path is a directory and iso_rr_path does not exist yet, then thewhole subtree will be inserted. Else only directory attributes will beupdated.
- -update_r disk_path iso_rr_path
- Like -update but working recursively. I.e. all file objects below bothaddresses get compared whether they have counterparts below the other addressand whether both counterparts match. If there is a mismatch then the necessaryupdate manipulation is done.
Note that the comparison result may depend on command -follow. Its settingshould always be the same as with the first adding of disk_path as iso_rr_path.
If iso_rr_path does not exist yet, then it gets added. If disk_path does notexist, then iso_rr_path gets deleted.
- -update_l disk_prefix iso_rr_prefix disk_path [***]
- Perform -update_r with each of the disk_path parameters. iso_rr_path will becomposed from disk_path by replacing disk_prefix by iso_rr_prefix.
- -update_li iso_rr_prefix disk_prefix iso_rr_path [***]
- Perform -update_r with each of the iso_rr_path parameters. disk_path will becomposed from iso_rr_path by replacing iso_rr_prefix by disk_prefix.
- -update_lxi disk_prefix iso_rr_prefix disk_path [***]
- Perform -update_r with each of the disk_path parameters and with iso_rr_pathsin the ISO filesystem which are derived from the disk_path parameters afterexchanging disk_prefix by iso_rr_prefix. So, other than -update_l, this detectsmissing matches of disk_path and deletes the corresponding iso_rr_path.
Note that relative disk_paths and disk_path patterns are interpreted assub paths of the current disk working directory -cdx. The correspondingiso_rr_paths are derived by exchanging disk_prefix by iso_rr_prefix beforepattern expansion happens. The current -cdi directory has no influence.
- -cut_out disk_path byte_offset byte_count iso_rr_path
- Map a byte interval of a regular disk file into a regular file in the ISOimage.This may be necessary if the disk file is larger than a single medium, or ifit exceeds the traditional limit of 2 GiB - 1 for old operating systems,or the limit of