1XORRISO(1) General Commands Manual XORRISO(1)
2
6 xorriso - creates, loads, manipulates and writes ISO 9660 filesystem
7 images with Rock Ridge extensions.
8
10 xorriso [settings|actions]
11
13 xorriso is a program which copies file objects from POSIX compliant
14 filesystems into Rock Ridge enhanced ISO 9660 filesystems and performs
15 session-wise manipulation of such filesystems. It can load the
16 management information of existing ISO images and it writes the session
17 results to optical media or to filesystem objects.
18 Vice versa xorriso is able to copy file objects out of ISO 9660
19 filesystems.
20 A special property of xorriso is that it needs neither an external ISO
22 9660 formatter program nor an external burn program for CD, DVD or BD
23 but rather incorporates the libraries of libburnia-project.org .
24 Overview of features:
26 Operates on an existing ISO image or creates a new one.
27 Copies files from disk filesystem into the ISO image.
28 Copies files from ISO image to disk filesystem (see osirrox).
29 Renames or deletes file objects in the ISO image.
30 Changes file properties in the ISO image.
31 Updates ISO subtrees incrementally to match given disk subtrees.
32 Writes result either as completely new image or as add-on session to
33 optical media or filesystem objects.
34 Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
35 Can perform multi-session tasks as emulation of mkisofs and cdrecord.
36 Can record and restore hard links and ACL.
37 Content may get zisofs compressed or filtered by external processes.
38 Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
39 Can check media for damages and copy readable blocks to disk.
40 Can attach MD5 checksums to each data file and the whole session.
41 Scans for optical drives, blanks re-usable optical media.
42 Reads its instructions from command line arguments, dialog, and files.
43 Provides navigation commands for interactive ISO image manipulation.
44 Adjustable thresholds for abort, exit value, and problem reporting.
45 Note that xorriso does not write audio CDs and that it does not produce
47 UDF filesystems which are specified for official video DVD or BD.
48 General information paragraphs:
50 Session model
51 Media types and states
52 Creating, Growing, Modifying, Blind Growing
53 Libburn drives
54 Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
55 Command processing
56 Dialog, Readline, Result pager
57 Maybe you first want to have a look at section EXAMPLES near the end of
59 this text before reading the next few hundred lines of background
60 information.
61 Session model:
63 Unlike other filesystems, ISO 9660 (aka ECMA-119) is not intended for
64 read-write operation but rather for being generated in a single sweep
65 and being written to media as a session.
66 The data content of the session is called filesystem image.
67 The written image in its session can then be mounted by the operating
69 system for being used read-only. GNU/Linux is able to mount ISO images
70 from block devices, which may represent optical media, other media or
71 via a loop device even from regular disk files. FreeBSD mounts ISO
72 images from devices that represent arbitrary media or from regular disk
73 files.
74 This session usage model has been extended on CD media by the concept
76 of multi-session , which adds information to the CD and gives the mount
77 programs of the operating systems the addresses of the entry points of
78 each session. The mount programs recognize block devices which
79 represent CD media and will by default mount the image in the last
80 session.
81 This session usually contains an updated directory tree for the whole
82 medium which governs the data contents in all recorded sessions. So in
83 the view of the mount program all sessions of a particular medium
84 together form a single filesystem image.
85 Adding a session to an existing ISO image is in this text referred as
86 growing.
87 The multi-session model of the MMC standard does not apply to all media
88 types. But program growisofs by Andy Polyakov showed how to extend this
89 functionality to overwritable media or disk files which carry valid ISO
90 9660 filesystems.
91 xorriso provides growing as well as an own method named modifying which
93 produces a completely new ISO image from the old one and the
94 modifications. See paragraph Creating, Growing, Modifying, Blind
95 Growing below.
96 xorriso adopts the concept of multi-session by loading an image
98 directory tree if present, by offering to manipulate it by several
99 actions, and by writing the new image to the target medium.
100 The first session of a xorriso run begins by the definition of the
101 input drive with the ISO image or by the definition of an output drive.
102 The session ends by command -commit which triggers writing. A -commit
103 is done automatically when the program ends regularly.
104 After -commit a new session begins with the freshly written one as
106 input. A new input drive can only be chosen as long as the loaded ISO
107 image was not altered. Pending alteration can be revoked by command
108 -rollback.
109 Writing a session to the target is supposed to be very expensive in
111 terms of time and of consumed space on appendable or write-once media.
112 Therefore all intended manipulations of a particular ISO image should
113 be done in a single session. But in principle it is possible to store
114 intermediate states and to continue with image manipulations.
115 Media types and states:
117 There are two families of media in the MMC standard:
118 Multi-session media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and
119 unformatted DVD-RW. These media provide a table of content which
120 describes their existing sessions. See command -toc.
121 Similar to multi-session media are DVD-R DL and minimally blanked
122 DVD-RW. They record only a single session of which the size must be
123 known in advance. xorriso will write onto them only if command -close
124 is set to "on".
125 Overwritable media are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
126 They offer random write access but do not provide information about
127 their session history. If they contain one or more ISO 9660 sessions
128 and if the first session was written by xorriso, then a table of
129 content can be emulated. Else only a single overall session will be
130 visible.
131 DVD-RW media can be formatted by -format "full". They can be made
132 unformatted by -blank "deformat".
133 Regular files and block devices are handled as overwritable media.
134 Pipes and other writeable file types are handled as blank multi-session
135 media.
136 The program growisofs formats by default BD-R to be pseudo-overwritable
137 (POW). xorriso will classify them as
138 Media current: is unsuitable , is POW formatted
139 and will refuse to write to them or to obtain multi-session information
140 from them.
141 These media can assume several states in which they offer different
143 capabilities.
144 Blank media can be written from scratch. They contain no ISO image
145 suitable for xorriso.
146 Blank is the state of newly purchased optical media. With used CD-RW
147 and DVD-RW it can be achieved by action -blank "as_needed".
148 Overwritable media are considered blank if they are new or if they have
149 been marked as blank by xorriso. Action -blank "as_needed" can be used
150 to do this marking on overwritable media, or to apply mandatory
151 formatting to new media if necessary.
152 Appendable media accept further sessions. Either they are MMC
153 multi-session media in appendable state, or they are overwritable media
154 which contain an ISO image suitable for xorriso.
155 Appendable is the state after writing a session with command -close
156 off.
157 Closed media cannot be written. They may contain an ISO image suitable
158 for xorriso.
159 Closed is the state of DVD-ROM media and of multi-session media which
160 were written with command -close on. If the drive is read-only hardware
161 then it will probably show any media as closed CD-ROM or DVD-ROM.
162 Overwritable media assume this state in such read-only drives or if
163 they contain unrecognizable data in the first 32 data blocks.
164 Read-only drives may or may not show session histories of multi-session
165 media. Often only the first and the last session are visible. Sometimes
166 not even that. Command -rom_toc_scan might or might not help in such
167 cases.
168 Creating, Growing, Modifying, Blind Growing:
170 A new empty ISO image gets created if there is no input drive with a
171 valid ISO 9660 image when the first time an output drive is defined.
172 This is achieved by command -dev on blank media or by command -outdev
173 on media in any state.
174 The new empty image can be populated with directories and files.
175 Before it can be written, the medium in the output drive must get into
176 blank state if it was not blank already.
177 If there is a input drive with a valid ISO image, then this image gets
179 loaded as foundation for manipulations and extension. The constellation
180 of input and output drive determines which write method will be used.
181 They have quite different capabilities and constraints.
182 The method of growing adds new data to the existing data on the medium.
184 These data comprise of new file content and they override the existing
185 ISO 9660 + Rock Ridge directory tree. It is possible to hide files from
186 previous sessions but they still exist on the medium and with many
187 types of optical media it is quite easy to recover them by mounting
188 older sessions.
189 Growing is achieved by command -dev.
190 The write method of modifying produces compact filesystem images with
192 no outdated files or directory trees. Modifying can write its images to
193 target media which are completely unsuitable for multi-session
194 operations. E.g. DVD-RW which were treated with -blank
195 deformat_quickest, DVD-R DL, named pipes, character devices, sockets.
196 On the other hand modified sessions cannot be written to appendable
197 media but to blank media only.
198 So for this method one needs either two optical drives or has to work
199 with filesystem objects as source and/or target medium.
200 Modifying takes place if input drive and output drive are not the same
201 and if command -grow_blindly is set to its default "off". This is
202 achieved by commands -indev and -outdev.
203 If command -grow_blindly is set to a non-negative number and if -indev
205 and -outdev are both set to different drives, then blind growing is
206 performed. It produces an add-on session which is ready for being
207 written to the given block address. This is the usage model of
208 mkisofs -M $indev -C $msc1,$msc2 -o $outdev
209 which gives much room for wrong parameter combinations and should thus
210 only be employed if a strict distinction between ISO formatter xorriso
211 and the burn program is desired. -C $msc1,$msc2 is equivalent to:
212 -load sbsector $msc1 -grow_blindly $msc2
213 Libburn drives:
215 Input drive, i.e. source of an existing or empty ISO image, can be any
216 random access readable libburn drive: optical media with readable data,
217 blank optical media, regular files, block devices.
218 Output drive, i.e. target for writing, can be any libburn drive. Some
219 drive types do not support the method of growing but only the methods
220 of modifying and blind growing. They all are suitable for newly created
221 images.
222 All drive file objects have to offer rw-permission to the user of
224 xorriso. Even those which will not be usable for reading an ISO image.
225 With any type of drive object, the data are considered to be organized
226 in blocks of 2 KiB. Access happens in terms of Logical Block Address
227 (LBA) which gives the number of a particular data block.
228 MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed
230 by the path of their block device or of their generic character device.
231 E.g.
232 -dev /dev/sr0
233 -dev /dev/hdc
234 -dev /dev/sg2
235 By default xorriso will try to map the given address to /dev/hd* and
236 /dev/sr*. The command -scsi_dev_family can redirect the mapping from
237 sr to scd or sg. The latter does not suffer from the concurrency
238 problems which plagued /dev/sr of Linux kernels since version 3 up to
239 5.5. But it does not yield the same addresses which are used by
240 mount(8) or by open(2) for read(2).
241 On FreeBSD the device files have names like
242 -dev /dev/cd0
243 On NetBSD:
244 -dev /dev/rcd0d
245 On OpenSolaris:
246 -dev /dev/rdsk/c4t0d0s2
247 Get a list of accessible drives by command
248 -device_links
249 It might be necessary to do this as superuser in order to see all
250 drives and to then allow rw-access for the intended users. Consider to
251 bundle the authorized users in a group like old "floppy".
252 Filesystem objects of nearly any type can be addressed by prefix
254 "stdio:" and their path in the filesystem. E.g.:
255 -dev stdio:/dev/sdc
256 The default setting of -drive_class allows the user to address files
257 outside the /dev tree without that prefix. E.g.:
258 -dev /tmp/pseudo_drive
259 If path leads to a regular file or to a block device then the emulated
260 drive is random access readable and can be used for the method of
261 growing if it already contains a valid ISO 9660 image. Any other file
262 type is not readable via "stdio:" and can only be used as target for
263 the method of modifying or blind growing. Non-existing paths in
264 existing directories are handled as empty regular files.
265 A very special kind of pseudo drive are open file descriptors. They are
267 depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open).
268 Addresses "-" or "stdio:/dev/fd/1" depict standard output, which
269 normally is the output channel for result texts. To prevent a fatal
270 intermingling of ISO image and text messages, all result texts get
271 redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is among the
272 start arguments of the program.
273 Standard output is currently suitable for creating one session per
274 program run without dialog. Use in other situations is discouraged and
275 several restrictions apply:
276 It is not allowed to use standard output as pseudo drive if it was not
277 among the start arguments. Do not try to fool this ban via backdoor
278 addresses to stdout.
279 If stdout is used as drive, then -use_readline is permanently disabled.
280 Use of backdoors can cause severe memory and/or tty corruption.
281 Be aware that especially the superuser can write into any accessible
283 file or device by using its path with the "stdio:" prefix. By default
284 any address in the /dev tree without prefix "stdio:" will work only if
285 it leads to a MMC drive.
286 One may use command -ban_stdio_write to surely prevent this risk and to
287 restrict drive usage to MMC drives.
288 One may prepend "mmc:" to a path to surely disallow any automatic
289 "stdio:".
290 By command -drive_class one may ban certain paths or allow access
291 without prefix "stdio:" to other paths.
292 Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
294 Rock Ridge is the name of a set of additional information which enhance
295 an ISO 9660 filesystem so that it can represent a POSIX compliant
296 filesystem with ownership, access permissions, symbolic links, and
297 other attributes.
298 This is what xorriso uses for a decent representation of the disk files
299 within the ISO image. xorriso produces Rock Ridge information by
300 default. It is strongly discouraged to disable this feature.
301 xorriso is not named "porriso" because POSIX only guarantees 14
303 characters of filename length. It is the X/Open System Interface
304 standard XSI which demands a file name length of up to 255 characters
305 and paths of up to 1024 characters. Rock Ridge fulfills this demand.
306 An El Torito boot record points the BIOS bootstrapping facility to one
308 or more boot images, which are binary program files stored in the ISO
309 image. The content of the boot image files is not in the scope of El
310 Torito.
311 Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot
312 images. xorriso is able to create or maintain an El Torito object
313 which makes such an image bootable. For details see command
314 -boot_image.
315 It is possible to make ISO images bootable from USB stick or other
316 hard-disk-like media. Several options install a MBR (Master Boot
317 Record), It may get adjusted according to the needs of the intended
318 boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX. A
319 MBR contains boot code and a partition table. The new MBR of a
320 follow-up session can get in effect only on overwritable media.
321 MBR is read by PC-BIOS when booting from USB stick or hard disk, and by
322 PowerPC CHRP or PReP when booting. An MBR partition with type 0xee
323 indicates the presence of GPT.
324 Emulation -as mkisofs supports the example options out of the ISOLINUX
325 wiki, the options used in GRUB script grub-mkrescue, and the example in
326 the FreeBSD AvgLiveCD wiki.
327 A GPT (GUID Partition Table) marks partitions in a more modern way. It
328 is read by EFI when booting from USB stick or hard disk, and may be
329 used for finding and mounting a HFS+ partition inside the ISO image.
330 An APM (Apple Partition Map) marks the HFS+ partition. It is read by
331 Macs for booting and for mounting.
332 MBR, GPT and APM are combinable. APM occupies the first 8 bytes of MBR
333 boot code. All three do not hamper El Torito booting from CDROM.
334 There is support for further facilities: MIPS Big Endian (SGI), MIPS
335 Little Endian (DEC), SUN SPARC, HP-PA. Those are mutually not
336 combinable and also not combinable with MBR, GPT, or APM.
337 ACL are an advanced way of controlling access permissions to file
339 objects. Neither ISO 9660 nor Rock Ridge specify a way to record ACLs.
340 So libisofs has introduced a standard conformant extension named AAIP
341 for that purpose. It uses this extension if enabled by command -acl.
342 AAIP enhanced images are supposed to be mountable normally, but one
343 cannot expect that the mounted filesystem will show and respect the
344 ACLs. For now, only xorriso is able to retrieve those ACLs. It can
345 bring them into effect when files get restored to an ACL enabled file
346 system or it can print them in a format suitable for tool setfacl.
347 Files with ACL show as group permissions the setting of entry "mask::"
348 if that entry exists. Nevertheless the non-listed group members get
349 handled according to entry "group::". When removing ACL from a file,
350 xorriso brings "group::" into effect.
351 Recording and restoring of ACLs from and to local files works currently
352 only on GNU/Linux and FreeBSD.
353 xattr (aka EA, or extattr) are pairs of name and value which can be
355 attached to file objects. AAIP is able to represent them and xorriso
356 can record and restore them.
357 But be aware that pairs with names of non-user namespaces are not
358 necessarily portable between operating systems and not even between
359 filesystems. Only those which begin with "user.", like "user.x" or
360 "user.whatever", can unconditionally be expected to be appropriate on
361 other machines and disks. Processing of other xattr may need
362 administrator privileges.
363 Name has to be a 0 terminated string. Value may be any array of bytes
364 which does not exceed the size of 4095 bytes. xattr processing happens
365 only if it is enabled by command -xattr.
366 As with ACL, currently only xorriso is able to retrieve xattr from AAIP
367 enhanced images, to restore them to xattr capable file systems, or to
368 print them.
369 Recording and restoring of xattr from and to local files works
370 currently only on GNU/Linux and FreeBSD, where they are known as
371 extattr.
372 Command processing:
374 Commands are either actions which happen immediately or settings which
375 influence following actions. So their sequence does matter, unless they
376 are given as program arguments and command -x is among them.
377 The list of all current settings can be inquired by command -status
378 "long". Command -status "short" lists a handful of fundamental
379 settings and all settings which are not default at program start.
380 Commands consist of a command word, followed by zero or more parameter
382 words. If the list of parameter words is of variable length (indicated
383 by "[...]" or "[***]") then it must be terminated by either the list
384 delimiter, occur at the end of the argument list, or occur at the end
385 of an input line.
386 At program start the list delimiter is the string "--". This may be
388 changed with the -list_delimiter command in order to allow "--" as
389 parameter in a variable length list. However, it is advised to reset
390 the delimiter to "--" immediately afterwards.
391 For brevity the list delimiter is referred as "--" throughout this
392 text.
393 The list delimiter is silently ignored if it appears after the
394 parameters of a command with a fixed list length. It is handled as
395 normal text if it appears among the parameters of such a command.
396 Pattern expansion converts a list of pattern words into a list of
398 existing file addresses. Unmatched pattern words will appear unaltered
399 in that result list.
400 Pattern matching supports the usual shell parser wildcards '*' '?'
401 '[xyz]' and respects '/' as the path separator, which may only be
402 matched literally.
403 Pattern expansion is a property of some particular commands and not a
404 general feature. It is controlled by commands -iso_rr_pattern and
405 -disk_pattern. Commands which use pattern expansion all have variable
406 parameter lists which are specified in this text by "[***]" rather than
407 "[...]".
408 Some other commands perform pattern matching unconditionally.
409 Command and parameter words are either read from the program arguments,
411 where one argument is one word, or from quoted input lines where words
412 are recognized similar to the quotation rules of a shell parser.
413 xorriso is not a shell, although it might appear so at first glimpse.
414 Be aware that the interaction of quotation marks and pattern symbols
415 like "*" differs from the usual shell parsers. In xorriso, a quotation
416 mark does not make a pattern symbol literal.
417 Quoted input converts whitespace-separated text into words. The double
419 quotation mark " and the single quotation mark ' can be used to enclose
420 whitespace and make it part of words (e.g. of file names). Each mark
421 type can enclose the marks of the other type. A trailing backslash \
422 outside quotations or an open quotation cause the next input line to be
423 appended.
424 Quoted input accepts any 8-bit character except NUL (0) as the content
425 of the quotes. Nevertheless it can be cumbersome for the user to
426 produce those characters directly. Therefore quoted input and program
427 arguments offer optional Backslash Interpretation which can represent
428 all 8-bit characters except NUL (0) via backslash codes as in $'...' of
429 bash.
430 This is not enabled by default. See command -backslash_codes.
431 When the program starts then it first looks for argument -no_rc. If
433 this is not present then it looks for its startup files and reads their
434 content as command input lines. Then it interprets the program
435 arguments as commands and parameters. Finally it enters dialog mode if
436 command -dialog "on" has been executed by this point.
437 The program ends either by command -end, or by the end of program
439 arguments if dialog mode has not been enabled at that point, or by a
440 problem event which triggers the threshold of command -abort_on.
441 Dialog, Readline, Result pager:
443 Dialog mode prompts for a quoted input line, parses it into words, and
444 performs them as commands with their parameters. It provides assisting
445 services to make dialog more comfortable.
446 Readline is an enhancement for the input line. You may already know it
448 from the bash shell. Whether it is available in xorriso depends on the
449 availability of package readline-dev at the time when xorriso was built
450 from its sourcecode.
451 Readline lets the user move the cursor over the text in the line by
452 help of the Left and the Right arrow keys. Text may be inserted at the
453 cursor position. The Delete key removes the character under the cursor.
454 Up and Down arrow keys navigate through the history of previous input
455 lines.
456 See man readline for more info about libreadline.
457 Command -page activates a built-in result text pager which may be
459 convenient in dialog mode. After an action has output the given number
460 of terminal lines, the pager prompts the user for a line of input.
461 An empty line lets xorriso resume work until the next page is output.
462 The single character "@" disables paging for the current action.
463 "@@@", "x", "q", "X", or "Q" request that the current action aborts and
464 suppress further result output.
465 Any other line input will be interpreted as new dialog line. The
466 current action is requested to abort. Afterwards, the input line is
467 executed.
468 Some actions apply paging to their info output, too.
470 The request to abort may or may not be obeyed by the current action.
471 All actions try to abort as soon as possible.
472
474 All command words are shown with a leading dash although this dash is
475 not mandatory for the command to be recognized. Nevertheless within
476 command -as the dashes of the emulated commands are mandatory.
477 Normally any number of leading dashes is ignored with command words and
478 inner dashes are interpreted as underscores.
479 Execution order of program arguments:
481 By default the program arguments of a xorriso run are interpreted as a
483 sequence of commands which get performed exactly in the given order.
484 This requires the user to write commands for desired settings before
485 the commands which shall be influenced by those settings.
486 Many other programs support program arguments in an arbitrary ordering
487 and perform settings and actions in a sequence at their own discretion.
488 xorriso provides an option to enable such a behavior at the cost of
489 loss of expressivity.
490 -x Enable automatic sorting of program arguments into a sequence
492 that (most likely) is sensible. This command may be given at
493 any position among the commands which are handed over as program
494 arguments.
495 Note: It works only if it is given as program argument and with
496 a single dash (i.e. "-x"). It will not work in startup files,
497 nor with -options_from_file, nor in dialog mode, nor as "x" and
498 finally not as "--x". It affects only the commands given as
499 program arguments.
500 -list_arg_sorting
502 List all xorriso commands in the order which applies if command
503 -x is in effect.
504 This list may also be helpful without -x for a user who ponders
505 over the sequence in which to put commands. Deviations from the
506 listed sorting order may well make sense, though.
507 Acquiring source and target drive:
509 The effect of acquiring a drive may depend on several commands in the
511 next paragraph "Influencing the behavior of image loading". If
512 desired, their enabling commands have to be performed before the
513 commands which acquire the drive.
514 -dev address
516 Set input and output drive to the same address and load an ISO
517 image if it is present. If there is no ISO image then create a
518 blank one. Set the image expansion method to growing.
519 This is only allowed as long as no changes are pending in the
520 currently loaded ISO image. If changes are pending, then one has
521 to perform -commit or -rollback first.
522 Special address string "-" means standard output, to which
523 several restrictions apply. See above paragraph "Libburn
524 drives".
525 An empty address string "" gives up the current device without
526 acquiring a new one.
527 -indev address
529 Set input drive and load an ISO image if present. If the new
530 input drive differs from -outdev then switch from growing to
531 modifying or to blind growing. It depends on the setting of
532 -grow_blindly which of both gets activated. The same rules and
533 restrictions apply as with -dev.
534 -outdev address
536 Set output drive and if it differs from the input drive then
537 switch from growing to modifying or to blind growing. Unlike
538 -dev and -indev this action does not load a new ISO image. So it
539 can be performed even if there are pending changes.
540 -outdev can be performed without previous -dev or -indev. In
541 that case an empty ISO image with no changes pending is created.
542 It can either be populated by help of -map, -add et.al. or it
543 can be discarded silently if -dev or -indev are performed
544 afterwards.
545 Special address string "-" means standard output, to which
546 several restrictions apply. See above paragraph "Libburn
547 drives".
548 An empty address string "" gives up the current output drive
549 without acquiring a new one. No writing is possible without an
550 output drive.
551 -drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern
553 Add a drive path pattern to one of the safety lists or make
554 those lists empty. There are three lists defined which get
555 tested in the following sequence:
556 If a drive address path matches the "harmless" list then the
557 drive will be accepted. If it is not a MMC device then the
558 prefix "stdio:" will be prepended automatically. This list is
559 empty by default.
560 Else if the path matches the "banned" list then the drive will
561 not be accepted by xorriso but rather lead to a FAILURE event.
562 This list is empty by default.
563 Else if the path matches the "caution" list and if it is not a
564 MMC device, then its address must have the prefix "stdio:" or it
565 will be rejected. This list has by default one entry: "/dev".
566 If a drive path matches no list then it is considered
567 "harmless". By default these are all paths which do not begin
568 with directory "/dev".
569 A path matches a list if one of its parent paths or itself
570 matches a list entry. Address prefix "stdio:" or "mmc:" will be
571 ignored when testing for matches.
572 By pseudo-class "clear_list" and pseudo-patterns "banned",
573 "caution", "harmless", or "all", the lists may be made empty.
574 E.g.: -drive_class clear_list banned
575 One will normally define the -drive_class lists in one of the
576 xorriso Startup Files.
577 Note: This is not a security feature but rather a bumper for the
578 superuser to prevent inadverted mishaps. For reliably blocking
579 access to a device file you have to deny its rw-permissions in
580 the filesystem.
581 -drive_access "exclusive"|"shared":"unrestricted"|"readonly"
583 Control whether device file locking mechanisms shall be used
584 when acquiring a drive, and whether status or content of the
585 medium in the drive may be altered. Useful and most harmless are
586 the setting "shared:readonly" and the default setting
587 "exclusive:unrestricted".
588 "exclusive" enables tests and locks when acquiring the drive. It
589 depends on the operating system which locking mechanisms get
590 applied, if any. On GNU/Linux it is open(O_EXCL). On FreeBSD it
591 is flock(LOCK_EX).
592 "shared" disables the use of these mechanisms to become able to
593 acquire drives which are mounted, or opened by some process, or
594 guarded by /dev/pktcdvd*.
595 "unrestricted" enables all technically appropriate operations on
596 an acquired drive. "shared:unrestricted" risks to get own burn
597 runs spoiled by other processes or to vice versa spoil
598 activities of such processes. So use "exclusive:unrestricted"
599 unless you know for sure that "shared" is safe.
600 "readonly" disables operations which might surprise a co-user of
601 the drive. For -outdev these are formatting, blanking, writing,
602 ejecting. For -indev this is ejecting. Be aware that even
603 reading and drive status inquiries can disturb an ongoing burn
604 run on CD-R[W] and DVD-R[W].
605 -scsi_dev_family "default"|"sr"|"scd"|"sg"
607 GNU/Linux specific:
608 By default, xorriso tries to map Linux drive addresses to
609 /dev/sr* before they get opened for operating the drive. This
610 coordinates well with other use cases of optical drives, like
611 mount(8). But since year 2010 all /dev/sr* share a global lock
612 which allows only one drive to process an SCSI command while all
613 others have to wait for its completion. This yields awful
614 throughput if more than one drive is writing or reading
615 simultaneously. The global lock is not applied to device files
616 /dev/sg* and also not if the xorriso drive address is prepended
617 by "stdio:".
618 So for simultaneous burn runs on modern GNU/Linux it is
619 advisable to perform -scsi_dev_family "sg" before any -dev,
620 -indev, or -outdev. The drive addresses may then well be given
621 as /dev/sr* but will nevertheless get used as the matching
622 /dev/sg*.
623 If you decide so, consider to put the command into a global
624 startup file like /etc/opt/xorriso/rc.
625 -grow_blindly "off"|predicted_nwa
627 If predicted_nwa is a non-negative number then perform blind
628 growing rather than modifying if -indev and -outdev are set to
629 different drives. "off" or "-1" switch to modifying, which is
630 the default.
631 predicted_nwa is the block address where the add-on session of
632 blind growing will finally end up. It is the responsibility of
633 the user to ensure this final position and the presence of the
634 older sessions. Else the overall ISO image will not be mountable
635 or will produce read errors when accessing file content. xorriso
636 will write the session to the address as obtained from examining
637 -outdev and not necessarily to predicted_nwa.
638 During a run of blind growing, the input drive is given up
639 before output begins. The output drive is given up when writing
640 is done.
641 Influencing the behavior of image loading:
643 The following commands should normally be performed before loading an
645 image by acquiring an input drive. In rare cases it is desirable to
646 activate them only after image loading.
647 -read_speed code|number[k|m|c|d|b]
649 Set the speed for reading. Default is "none", which avoids to
650 send a speed setting command to the drive before reading begins.
651 Further special speed codes are:
652 "max" (or "0") selects maximum speed as announced by the drive.
653 "min" (or "-1") selects minimum speed as announced by the drive.
654 Speed can be given in media dependent numbers or as a desired
655 throughput per second in MMC compliant kB (= 1000) or MB (= 1000
656 kB). Media x-speed factor can be set explicitly by "c" for CD,
657 "d" for DVD, "b" for BD, "x" is optional.
658 Example speeds:
659 706k = 706kB/s = 4c = 4xCD
660 5540k = 5540kB/s = 4d = 4xDVD
661 If there is no hint about the speed unit attached, then the
662 medium in the -indev will decide. Default unit is CD = 176.4k.
663 Depending on the drive, the reported read speeds can be
664 deceivingly low or high. Therefore "min" cannot become higher
665 than 1x speed of the involved medium type. Read speed "max"
666 cannot become lower than 52xCD, 24xDVD, or 20xBD, depending on
667 the medium type.
668 MMC drives usually activate their own idea of speed and take the
669 speed value given by the burn program only as hint for their own
670 decision. Friendly drives adjust their constant angular velocity
671 so that the desired speed is reached at the outer rim of the
672 medium. But often there is only the choice between very slow and
673 very loud.
674 Sometimes no speed setting is obeyed at all, but speed is
675 adjusted to the demand frequency of the reading program. So
676 xorriso offers to set an additional software enforced limit by
677 prefix "soft_force:". The program will take care not to read
678 faster than the soft_force speed. This may be combined with
679 setting the drive speed to a higher value. Setting
680 "soft_force:0" disables this feature.
681 "soft_force:" tries to correct in subsequent waiting periods
682 lost or surplus time of up to 0.25 seconds. This smoothens the
683 overall data stream but also enables short times of higher speed
684 to compensate short times of low speed. Prefix "soft_corr:"
685 sets this hindsight span by giving a number of microseconds. Not
686 more than 1 billion = 1000 seconds. Very short times can cause
687 speed deviations, because systematic inaccuracies of the waiting
688 function cannot be compensated.
689 Examples (combinable):
690 -read_speed 6xBD
691 -read_speed soft_force:4xBD -read_speed soft_corr:100000
692 -load entity id
694 Load a particular (possibly outdated) ISO session from -dev or
695 -indev. Usually all available sessions are shown with command
696 -toc.
697 entity depicts the kind of addressing. id depicts the particular
698 address. The following entities are defined:
699 "auto" with any id addresses the last session in -toc. This is
700 the default.
701 "session" with id being a number as of a line "ISO session",
702 column "Idx".
703 "track" with id being a number as of a line "ISO track", column
704 "Idx".
705 "lba" or "sbsector" with a number as of a line "ISO ...", column
706 "sbsector".
707 "volid" with a search pattern for a text as of a line "ISO ...",
708 column "Volume Id".
709 Addressing a non-existing entity or one which does not represent
710 an ISO image will either abandon -indev or at least lead to a
711 blank image.
712 If an input drive is set at the moment when -load is executed,
713 then the addressed ISO image is loaded immediately. Else, the
714 setting will be pending until the next -dev or -indev. After the
715 image has been loaded once, the setting is valid for -rollback
716 until next -dev or -indev, where it will be reset to "auto".
717 -displacement [-]lba
719 Compensate a displacement of the image versus the start address
720 for which the image was prepared. This affects only loading of
721 ISO images and reading of their files. The multi-session method
722 of growing is not allowed as long as -displacement is non-zero.
723 I.e. -indev and -outdev must be different. The displacement gets
724 reset to 0 before the drive gets re-acquired after writing.
725 Examples:
726 If a track of a CD starts at block 123456 and gets copied to a
727 disk file where it begins at block 0, then this copy can be
728 loaded with
729 -displacement -123456
730 If an ISO image was written onto a partition with offset of
731 640000 blocks of 512 bytes, then it can be loaded from the base
732 device by
733 -load sbsector 160000 -displacement 160000
734 (If the partition start address is not divisible by 4, then you
735 will have to employ a loop device instead.)
736 In both cases, the ISO sessions should be self contained, i.e.
737 not add-on sessions to an ISO image outside their track or
738 partition.
739 -read_fs "any"|"norock"|"nojoliet"|"ecma119"
741 Specify which kind of filesystem tree to load if present. If the
742 wish cannot be fulfilled, then ECMA-119 names are loaded and
743 converted according to -ecma119_map.
744 "any" first tries to read Rock Ridge. If not present, Joliet is
745 tried.
746 "norock" does not try Rock Ridge.
747 "nojoliet" does not try Joliet.
748 "ecma119" tries neither Rock Ridge nor Joliet.
749 -assert_volid pattern severity
751 Refuse to load ISO images with volume IDs which do not match the
752 given search pattern. When refusing an image, give up the input
753 drive and issue an event of the given severity (like FAILURE,
754 see -abort_on). An empty search pattern accepts any image.
755 This command does not hamper the creation of an empty image from
756 blank input media and does not discard an already loaded image.
757 -in_charset character_set_name
759 Set the character set from which to convert file names when
760 loading an image. See paragraph "Character sets" for more
761 explanations. When loading the written image after -commit the
762 setting of -out_charset will be copied to -in_charset.
763 -auto_charset "on"|"off"
765 Enable or disable recording and interpretation of the output
766 character set name in an xattr attribute of the image root
767 directory. If enabled and if a recorded character set name is
768 found, then this name will be used as name of the input
769 character set when reading an image.
770 Note that the default output charset is the local character set
771 of the terminal where xorriso runs. Before attributing this
772 local character set to the produced ISO image, check whether the
773 terminal properly displays all intended filenames, especially
774 exotic national characters.
775 -hardlinks mode[:mode...]
777 Enable or disable loading and recording of hardlink relations.
778 In default mode "off", iso_rr files lose their inode numbers at
779 image load time. Each iso_rr file object which has no inode
780 number at image generation time will get a new unique inode
781 number if -compliance is set to new_rr.
782 Mode "on" preserves inode numbers from the loaded image if such
783 numbers were recorded. When committing a session it searches
784 for families of iso_rr files which stem from the same disk file,
785 have identical content filtering and have identical properties.
786 The family members all get the same inode number. Whether these
787 numbers are respected at mount time depends on the operating
788 system.
789 Command -lsl displays hardlink counts if "lsl_count" is enabled.
790 This can slow down the command substantially after changes to
791 the ISO image have been made. Therefore the default is
792 "no_lsl_count".
793 Commands -update and -update_r track splits and fusions of hard
794 links in filesystems which have stable device and inode numbers.
795 This can cause automatic last minute changes before the session
796 gets written. Command -hardlinks "perform_update" may be used to
797 do these changes earlier, e.g. if you need to apply filters to
798 all updated files.
799 Mode "without_update" avoids hardlink processing during update
800 commands. Use this if your filesystem situation does not allow
801 -disk_dev_ino "on".
802 xorriso commands which extract files from an ISO image try to
803 hardlink files with identical inode number. The normal scope of
804 this operation is from image load to image load. One may give up
805 the accumulated hard link addresses by -hardlinks
806 "discard_extract".
807 A large number of hardlink families may exhaust -temp_mem_limit
808 if not -osirrox "sort_lba_on" and -hardlinks
809 "cheap_sorted_extract" are both in effect. This restricts hard
810 linking to other files restored by the same single extract
811 command. -hardlinks "normal_extract" re-enables wide and
812 expensive hardlink accumulation.
813 -acl "on"|"off"
815 Enable or disable processing of ACLs. If enabled, then xorriso
816 will obtain ACLs from disk file objects, store ACLs in the ISO
817 image using the libisofs specific AAIP format, load AAIP data
818 from ISO images, test ACL during file comparison, and restore
819 ACLs to disk files when extracting them from ISO images. See
820 also commands -getfacl, -setfacl.
821 -xattr "on"|"user"|"any"|"off"
823 Enable or disable processing of xattr attributes. If enabled,
824 then xorriso will handle xattr similar to ACL. See also
825 commands -getfattr, -setfattr and above paragraph about xattr.
826 Modes "on" and "user" read and write only attributes from
827 namespace "user".
828 Mode "any" processes attributes of all namespaces. This might
829 need administrator privileges, even if the owner of the disk
830 file tries to read or write the attributes.
831 Note that it is not possible to set xattr of namespace "isofs."
832 by xorriso xattr manipulation commands.
833 -md5 "on"|"all"|"off"|"load_check_off"
835 Enable or disable processing of MD5 checksums for the overall
836 session and for each single data file. If enabled then images
837 with checksum tags get loaded only if the tags of superblock and
838 directory tree match properly. The MD5 checksums of data files
839 and whole session get loaded from the image if there are any.
840 With commands -compare and -update the recorded MD5 of a file
841 will be used to avoid content reading from the image. Only the
842 disk file content will be read and compared with that MD5. This
843 can save much time if -disk_dev_ino "on" is not suitable.
844 Commands which copy whole data files from ISO to hard disk will
845 verify the copied data stream by the recorded MD5, if -osirrox
846 "check_md5_on" is set.
847 At image generation time they are computed for each file which
848 gets its data written into the new session. The checksums of
849 files which have their data in older sessions get copied into
850 the new session. Superblock, tree and whole session get a
851 checksum tag each.
852 Mode "all" will additionally check during image generation
853 whether the checksum of a data file changed between the time
854 when its reading began and the time when it ended. This implies
855 reading every file twice.
856 Mode "load_check_off" together with "on" or "all" will load
857 recorded MD5 sums but not test the recorded checksum tags of
858 superblock and directory tree. This is necessary if growisofs
859 was used as burn program, because it does not overwrite the
860 superblock checksum tag of the first session. Therefore
861 load_check_off is in effect when xorriso -as mkisofs option -M
862 is performed.
863 The test can be re-enabled by mode "load_check_on".
864 Checksums can be exploited via commands -check_md5,
865 -check_md5_r, via find actions get_md5, check_md5, and via
866 -check_media.
867 -for_backup
869 Enable all extra features which help to produce or to restore
870 backups with highest fidelity of file properties. Currently this
871 is a shortcut for:
872 -hardlinks on -acl on -xattr any -md5 on
873 If you restore a backup with xattr from non-user namespaces,
874 then make sure that the target operating system and filesystem
875 know what these attributes mean. Possibly you will need
876 administrator privileges to record or restore such attributes.
877 At recording time, xorriso will try to tolerate missing
878 privileges and just record what is readable. But at restore
879 time, missing privileges will cause failure events.
880 Command -xattr "user" after command -for_backup excludes
881 non-user attributes from being recorded or restored.
882 -ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase"
884 Choose the conversion of file names when a session gets loaded,
885 if they stem neither from a Rock Ridge name nor from a Joliet
886 name.
887 Mode "stripped" is the default. It shows the names as found in
888 the ISO but removes trailing ";1" or ".;1" if present.
889 Mode "unmapped" shows names as found without removing
890 characters. Warning: Multi-session converts "xyz;1" to "xyz_1"
891 and maybe adds new ";1".
892 Mode "lowercase" is like "stripped" but also maps uppercase
893 letters to lowercase letters. This is compatible to default
894 GNU/Linux mount behavior.
895 Mode "uppercase" is like "stripped" but maps lowercase letters
896 to uppercase, if any occur despite the prescriptions of
897 ECMA-119.
898 -joliet_map "stripped"|"unmapped"
900 Choose the conversion of file names when a session gets loaded
901 from a Joliet tree.
902 Mode "stripped" is the default. It removes trailing ";1" or
903 ".;1" if present.
904 Mode "unmapped" shows names as found without removing
905 characters. Warning: Multi-session converts "xyz;1" to "xyz_1"
906 and maybe adds new ";1".
907 -iso_nowtime "dynamic"|timestring
909 Choose whether to use the current time ("dynamic") or a fixed
910 time point for timestamps of ISO 9660 nodes without a disk
911 source file and as default for superblock timestamps.
912 If a timestring is given, then it is used for such timestamps.
913 For the formats of timestrings see command -alter_date.
914 -disk_dev_ino "on"|"ino_only"|"off"
916 Enable or disable processing of recorded file identification
917 numbers (dev_t and ino_t). If enabled they are stored as xattr
918 and can substantially accelerate file comparison. The root node
919 gets a global start timestamp. If during comparison a file with
920 younger timestamps is found in the ISO image, then it is
921 suspected to have inconsistent content.
922 If device numbers and inode numbers of the disk filesystems are
923 persistent and if no irregular alterations of timestamps or
924 system clock happen, then potential content changes can be
925 detected without reading that content. File content change is
926 assumed if any of mtime, ctime, device number or inode number
927 have changed.
928 Mode "ino_only" replaces the precondition that device numbers
929 are stable by the precondition that mount points in the compared
930 tree always lead to the same filesystems. Use this if mode "on"
931 always sees all files changed.
932 The speed advantage appears only if the loaded session was
933 produced with -disk_dev_ino "on" too.
934 Note that -disk_dev_ino "off" is totally in effect only if
935 -hardlinks is "off", too.
936 -file_name_limit [+]number
938 Set the maximum permissible length for file names in the range
939 of 64 to 255. Path components which are longer than the given
940 number will get truncated and have their last 33 bytes
941 overwritten by a colon ':' and the hex representation of the MD5
942 of the first 4095 bytes of the whole oversized name. Potential
943 incomplete UTF-8 characters will get their leading bytes
944 replaced by '_'.
945 iso_rr_paths with the long components will still be able to
946 access the file paths with truncated components.
947 If -file_name_limit is executed while an ISO tree is present,
948 the file names in the ISO tree get checked for existing
949 truncated file names of the current limit and for name
950 collisions between newly truncated files and existing files. In
951 both cases, the setting will be refused with a SORRY event.
952 One may lift this ban by prepending the character "+" to the
953 argument of -file_name_limit. Truncated filenames may then get
954 truncated again, invalidating their MD5 part. Colliding
955 truncated names are made unique, consuming at least 9 more bytes
956 of the remaining name part.
957 If writing of xattr is enabled, then the length will be stored
958 in "isofs.nt" of the root directory. If reading of xattr is
959 enabled and "isofs.nt" is found, then the found length will get
960 into effect if it is smaller than the current setting of
961 -file_name_limit.
962 File name patterns will only work if they match the truncated
963 name. This might change in future.
964 Files with truncated names get deleted and re-added
965 unconditionally during -update and -update_r. This might change
966 in future.
967 Linux kernels up to at least 4.1 misrepresent names of length
968 254 and 255. If you expect such names in or under disk_paths
969 and plan to mount the ISO by such Linux kernels, consider to set
970 -file_name_limit 253. Else just avoid names longer than 253
971 characters.
972 -rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"]
974 Read-only drives do not tell the actual media type but show any
975 media as ROM (e.g. as DVD-ROM). The session history of MMC
976 multi-session media might be truncated to first and last session
977 or even be completely false. (The emulated history of
978 overwritable media is not affected by this.)
979 To have in case of failure a chance of getting the session
980 history and especially the address of the last session, there is
981 a scan for ISO 9660 filesystem headers which might help but also
982 might yield worse results than the drive's table of content. At
983 its end it can cause read attempts to invalid addresses and thus
984 ugly drive behavior. Setting "on" enables that scan for alleged
985 read-only media.
986 Some operating systems are not able to mount the most recent
987 session of multi-session DVD or BD. If on such a system xorriso
988 has no own MMC capabilities then it may still find that session
989 from a scanned table of content. Setting "force" handles any
990 media like a ROM medium with setting "on".
991 On the other hand the emulation of session history on
992 overwritable media can hamper reading of partly damaged media.
993 Setting "off:emul_off" disables the elsewise trustworthy
994 table-of-content scan for those media.
995 The table-of-content scan on overwritable media normally
996 searches only up to the end of the session that is pointed to by
997 the superblock at block 0. Setting "on:emul_wide" lets the scan
998 continue up to the end of the medium. This may be useful after
999 copying a medium with -check_media patch_lba0=on when not the
1000 last session was loaded.
1001 -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
1003 Reduce drive noise until it is actually used again. Some drives
1004 stay alert for substantial time after they have been used for
1005 reading. This reduces the startup time for the next drive
1006 operation but can be loud and waste energy if no i/o with the
1007 drive is expected to happen soon.
1008 Modes "in", "out", "all" immediately calm down -indev, -outdev,
1009 or both, respectively. Mode "revoke" immediately alerts both.
1010 Mode "on" causes -calm_drive to be performed automatically after
1011 each -dev, -indev, and -outdev. Mode "off" disables this.
1012 -ban_stdio_write
1014 Allow for writing only the usage of MMC optical drives. Disallow
1015 to write the result into files of nearly arbitrary type. Once
1016 set, this command cannot be revoked.
1017 -early_stdio_test "on"|"appendable_wo"|"off"
1019 If enabled by "on" then regular files and block devices get
1020 tested for effective access permissions. This implies to try
1021 opening those files for writing, which otherwise will happen
1022 only later and only if actual writing is desired.
1023 The test result is used for classifying the pseudo drives as
1024 overwritable, read-only, write-only, or uselessly empty. This
1025 may lead to earlier detection of severe problems, and may avoid
1026 some less severe error events.
1027 Mode "appendable_wo" is like "on" with the additional property
1028 that non-empty write-only files are regarded as appendable
1029 rather than blank.
1030 -data_cache_size number_of_tiles blocks_per_tile
1032 Set the size and granularity of the data cache which is used
1033 when ISO images are loaded and when file content is read from
1034 ISO images. The cache consists of several tiles, which each
1035 consists of several blocks. A larger cache reduces the need for
1036 tiles being read multiple times. Larger tiles might additionally
1037 improve the data throughput from the drive, but can be wasteful
1038 if the data are scattered over the medium.
1039 Larger cache sizes help best with image loading from MMC drives.
1040 They are an inferior alternative to -osirrox option
1041 "sort_lba_on".
1042 blocks_per_tile must be a power of 2. E.g. 16, 32, or 64. The
1043 overall cache size must not exceed 1 GiB. The default values
1044 can be restored by parameter "default" instead of one or both of
1045 the numbers. Currently the default is 32 tiles of 32 blocks = 2
1046 MiB.
1047 Inserting files into ISO image:
1049 The following commands expect file addresses of two kinds:
1051 disk_path is a path to an object in the local filesystem tree.
1052 iso_rr_path is the Rock Ridge name of a file object in the ISO image.
1053 If no Rock Ridge information is recorded in the loaded ISO image, then
1054 you will see ISO 9660 names which are of limited length and character
1055 set. If no Rock Ridge information shall be stored in an emerging ISO
1056 image, then their names will get mapped to such restricted ISO 9660
1057 (aka ECMA-119) names.
1058 Note that in the ISO image you are as powerful as the superuser. Access
1060 permissions of the existing files in the image do not apply to your
1061 write operations. They are intended to be in effect with the read-only
1062 mounted image.
1063 If the iso_rr_path of a newly inserted file leads to an existing file
1065 object in the ISO image, then the following collision handling happens:
1066 If both objects are directories then they get merged by recursively
1067 inserting the subobjects from filesystem into ISO image. If other file
1068 types collide then the setting of command -overwrite decides.
1069 Renaming of files has similar collision handling, but directories can
1070 only be replaced, not merged. Note that if the target directory exists,
1071 then -mv inserts the source objects into this directory rather than
1072 attempting to replace it. Command -move, on the other hand, would
1073 attempt to replace it.
1074 The commands in this section alter the ISO image and not the local
1076 filesystem.
1077 -disk_pattern "on"|"ls"|"off"
1079 Set the pattern expansion mode for the disk_path parameters of
1080 several commands which support this feature.
1081 Setting "off" disables this feature for all commands which are
1082 marked in this man page by "disk_path [***]" or "disk_pattern
1083 [***]".
1084 Setting "on" enables it for all those commands.
1085 Setting "ls" enables it only for those which are marked by
1086 "disk_pattern [***]".
1087 Default is "ls".
1088 -add pathspec [...] | disk_path [***]
1090 Insert the given files or directory trees from filesystem into
1091 the ISO image.
1092 If -pathspecs is set to "on" or "as_mkisofs" then pattern
1093 expansion is always disabled and character '=' has a special
1094 meaning. It separates the ISO image path from the disk path:
1095 iso_rr_path=disk_path
1096 Character '=' in the iso_rr_path must be escaped by '\' (i.e. as
1097 "\=").
1098 With -pathspecs "on", the character '\' must not be escaped. The
1099 character '=' in the disk_path must not be escaped.
1100 With -pathspecs "as_mkisofs", all characters '\' must be escaped
1101 in both, iso_rr_path and disk_path. The character '=' may or may
1102 not be escaped in the disk_path.
1103 If iso_rr_path does not begin with '/' then -cd is prepended.
1104 If disk_path does not begin with '/' then -cdx is prepended.
1105 If no '=' is given then the word is used as both, iso_rr_path
1106 and disk path. If in this case the word does not begin with '/'
1107 then -cdx is prepended to the disk_path and -cd is prepended to
1108 the iso_rr_path.
1109 If -pathspecs is set to "off" then -disk_pattern expansion
1110 applies, if enabled. The resulting words are used as both,
1111 iso_rr_path and disk path. Relative path words get prepended the
1112 setting of -cdx to disk_path and the setting of -cd to
1113 iso_rr_path.
1114 -add_plainly mode
1116 If set to mode "unknown" then any command word that does not
1117 begin with "-" and is not recognized as known command will be
1118 subject to a virtual -add command. I.e. it will be used as
1119 pathspec or as disk_path and added to the image. If enabled,
1120 -disk_pattern expansion applies to disk_paths.
1121 Mode "dashed" is similar to "unknown" but also adds unrecognized
1122 command words even if they begin with "-".
1123 Mode "any" announces that all further words are to be added as
1124 pathspecs or disk_paths. This does not work in dialog mode.
1125 Mode "none" is the default. It prevents any words from being
1126 understood as files to add, if they are not parameters to
1127 appropriate commands.
1128 -path_list disk_path
1130 Like -add but read the parameter words from file disk_path or
1131 standard input if disk_path is "-". The list must contain
1132 exactly one pathspec or disk_path pattern per line.
1133 -quoted_path_list disk_path
1135 Like -path_list but with quoted input reading rules. Lines get
1136 split into parameter words for -add. Whitespace outside quotes
1137 is discarded.
1138 -map disk_path iso_rr_path
1140 Insert file object disk_path into the ISO image as iso_rr_path.
1141 If disk_path is a directory then its whole sub tree is inserted
1142 into the ISO image.
1143 -map_single disk_path iso_rr_path
1145 Like -map, but if disk_path is a directory then its sub tree is
1146 not inserted.
1147 -map_l disk_prefix iso_rr_prefix disk_path [***]
1149 Perform -map with each of the disk_path parameters. iso_rr_path
1150 will be composed from disk_path by replacing disk_prefix by
1151 iso_rr_prefix.
1152 -update disk_path iso_rr_path
1154 Compare file object disk_path with file object iso_rr_path. If
1155 they do not match, then perform the necessary image
1156 manipulations to make iso_rr_path a matching copy of disk_path.
1157 By default this comparison will imply lengthy content reading
1158 before a decision is made. Commands -disk_dev_ino or -md5 may
1159 accelerate comparison if they were already in effect when the
1160 loaded session was recorded.
1161 If disk_path is a directory and iso_rr_path does not exist yet,
1162 then the whole subtree will be inserted. Else only directory
1163 attributes will be updated.
1164 -update_r disk_path iso_rr_path
1166 Like -update but working recursively. I.e. all file objects
1167 below both addresses get compared whether they have counterparts
1168 below the other address and whether both counterparts match. If
1169 there is a mismatch then the necessary update manipulation is
1170 done.
1171 Note that the comparison result may depend on command -follow.
1172 Its setting should always be the same as with the first adding
1173 of disk_path as iso_rr_path.
1174 If iso_rr_path does not exist yet, then it gets added. If
1175 disk_path does not exist, then iso_rr_path gets deleted.
1176 -update_l disk_prefix iso_rr_prefix disk_path [***]
1178 Perform -update_r with each of the disk_path parameters.
1179 iso_rr_path will be composed from disk_path by replacing
1180 disk_prefix by iso_rr_prefix.
1181 -update_li iso_rr_prefix disk_prefix iso_rr_path [***]
1183 Perform -update_r with each of the iso_rr_path parameters.
1184 disk_path will be composed from iso_rr_path by replacing
1185 iso_rr_prefix by disk_prefix.
1186 -update_lxi disk_prefix iso_rr_prefix disk_path [***]
1188 Perform -update_r with each of the disk_path parameters and with
1189 iso_rr_paths in the ISO filesystem which are derived from the
1190 disk_path parameters after exchanging disk_prefix by
1191 iso_rr_prefix. So, other than -update_l, this detects missing
1192 matches of disk_path and deletes the corresponding iso_rr_path.
1193 Note that relative disk_paths and disk_path patterns are
1194 interpreted as sub paths of the current disk working directory
1195 -cdx. The corresponding iso_rr_paths are derived by exchanging
1196 disk_prefix by iso_rr_prefix before pattern expansion happens.
1197 The current -cdi directory has no influence.
1198 -cut_out disk_path byte_offset byte_count iso_rr_path
1200 Map a byte interval of a regular disk file or of a device file
1201 into a regular file in the ISO image. The file depicted by
1202 disk_path has to support random read access.
1203 Cutting out a byte interval may be necessary if the disk file is
1204 larger than a single medium, or if it exceeds the traditional
1205 limit of 2 GiB - 1 for old operating systems, or the limit of 4
1206 GiB - 1 for newer ones. Contemporary Linux kernels are able to
1207 read properly files >= 4 GiB - 1.
1208 A clumsy remedy for such limits is to backup file pieces and to
1209 concatenate them at restore time. A well tested chopping size is
1210 2047m. It is permissible to request a higher byte_count than
1211 available. The resulting file will be truncated to the correct
1212 size of a final piece. To request a byte_offset higher than
1213 available yields no file in the ISO image but a SORRY event.
1214 E.g:
1215 -cut_out /my/disk/file 0 2047m \
1216 /file/part_1_of_3_at_0_with_2047m_of_5753194821 \
1217 -cut_out /my/disk/file 2047m 2047m \
1218 /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
1219 -cut_out /my/disk/file 4094m 2047m \
1220 /file/part_3_of_3_at_4094m_with_2047m_of_5753194821
1221 If the directory /file does no yet exist, then its permissions
1222 are not taken from directory /my/disk but rather from
1223 /my/disk/file with additional x-permission for those who have
1224 r-permission.
1225 While command -split_size is set larger than 0, and if all
1226 pieces of a file reside in the same ISO directory with no other
1227 files, and if the names look like above, then their ISO
1228 directory will be recognized and handled like a regular file.
1229 This affects commands -compare*, -update*, and overwrite
1230 situations.
1231 See command -split_size for details.
1232 Another use case is copying the content of a device file as
1233 interval or as a whole into the emerging ISO filesystem. The
1234 fact that the byte_count is allowed to be unreasonably high
1235 enables copying of a whole device:
1236 -cut_out /dev/sdd3 0 1000g /content_of_sdd3
1237 -cpr disk_path [***] iso_rr_path
1239 Insert the given files or directory trees from filesystem into
1240 the ISO image.
1241 The rules for generating the ISO addresses are similar as with
1242 shell command cp -r. Nevertheless, directories of the
1243 iso_rr_path are created if necessary. Especially a not yet
1244 existing iso_rr_path will be handled as directory if multiple
1245 disk_paths are present. The leafnames of the multiple
1246 disk_paths will be grafted under that directory as would be done
1247 with an existing directory.
1248 If a single disk_path is present then a non-existing iso_rr_path
1249 will get the same type as the disk_path.
1250 If a disk_path does not begin with '/' then -cdx is prepended.
1251 If the iso_rr_path does not begin with '/' then -cd is
1252 prepended.
1253 -mkdir iso_rr_path [...]
1255 Create empty directories if they do not exist yet. Existence as
1256 directory generates a WARNING event, existence as other file
1257 causes a FAILURE event.
1258 -lns target_text iso_rr_path
1260 Create a symbolic link with address iso_rr_path which points to
1261 target_text. iso_rr_path may not exist yet.
1262 Hint: Command -clone produces the ISO equivalent of a hard link.
1263 -clone iso_rr_path_original iso_rr_path_copy
1265 Create a copy of the ISO file object iso_rr_path_original with
1266 the new address iso_rr_path_copy. If the original is a directory
1267 then copy all files and directories underneath. If
1268 iso_rr_path_original is a boot catalog file, then it gets not
1269 copied but is silently ignored.
1270 The copied ISO file objects have the same attributes. Copied
1271 data files refer to the same content source as their originals.
1272 The copies may then be manipulated independendly of their
1273 originals.
1274 This command will refuse execution if the address
1275 iso_rr_path_copy already exists in the ISO tree.
1276 -cp_clone iso_rr_path_original [***] iso_rr_path_dest
1278 Create copies of one or more ISO file objects as with command
1279 -clone. In case of collision merge directories with existing
1280 ones, but do not overwrite existing ISO file objects.
1281 The rules for generating the copy addresses are the same as with
1282 command -cpr (see above) or shell command cp -r. Other than with
1283 -cpr, relative iso_rr_path_original will get prepended the -cd
1284 path and not the -cdx path. Consider to -mkdir iso_rr_path_dest
1285 before -cp_clone so the copy address does not depend on the
1286 number of iso_rr_path_original parameters.
1287 Settings for file insertion:
1289 -file_size_limit value [value [...]] --
1291 Set the maximum permissible size for a single data file. The
1292 values get summed up for the actual limit. If the only value is
1293 "off" then the file size is not limited by xorriso. Default is
1294 a limit of 100 extents, 4g -2k each:
1295 -file_size_limit 400g -200k --
1296 When mounting ISO 9660 filesystems, old operating systems can
1297 handle only files up to 2g -1 --. Newer ones are good up to 4g
1298 -1 --. You need quite a new Linux kernel to read correctly the
1299 final bytes of a file >= 4g if its size is not aligned to 2048
1300 byte blocks.
1301 xorriso's own data read capabilities are not affected by
1302 operating system size limits. Such limits apply to mounting
1303 only. Nevertheless, the target filesystem of an -extract must be
1304 able to take the file size.
1305 -not_mgt code[:code[...]]
1307 Control the behavior of the exclusion lists.
1308 Exclusion processing happens before disk_paths get mapped to the
1309 ISO image, before disk files get compared with image files, and
1310 before image files get extracted to disk files.
1311 The absolute disk paths involved in such an action are matched
1312 against the -not_paths list. The leafnames of disk paths are
1313 matched against the patterns in the -not_leaf list. If a match
1314 is detected then the disk path will not be regarded as an
1315 existing file and not be added to the ISO image.
1316 Several codes are defined. The _on/_off settings persist until
1317 they are revoked by their_off/_on counterparts.
1318 "erase" empties the lists which were accumulated by -not_paths
1319 and -not_leaf.
1320 "reset" is like "erase" but also re-installs default behavior.
1321 "off" disables exclusion processing temporarily without
1322 invalidating the lists and settings.
1323 "on" re-enables exclusion processing.
1324 "param_off" applies exclusion processing only to paths below
1325 disk_path parameter of commands. I.e. explicitly given
1326 disk_paths are exempted from exclusion processing.
1327 "param_on" applies exclusion processing to command parameters as
1328 well as to files below such parameters.
1329 "subtree_off" with "param_on" excludes parameter paths only if
1330 they match a -not_paths item exactly.
1331 "subtree_on" additionally excludes parameter paths which lead to
1332 a file address below any -not_paths item.
1333 "ignore_off" treats excluded disk files as if they were missing.
1334 I.e. they get reported with -compare and deleted from the image
1335 with -update.
1336 "ignore_on" keeps excluded files out of -compare or -update
1337 activities.
1338 -not_paths disk_path [***]
1340 Add the given paths to the list of excluded absolute disk paths.
1341 If a given path is relative, then the current -cdx is prepended
1342 to form an absolute path. Pattern matching, if enabled, happens
1343 at definition time and not when exclusion checks are made.
1344 Keep in mind that there may be alternative paths to the same
1345 disk file. The exclusion tests are done literally, so that they
1346 do not keep files from getting into the ISO filesystem by other
1347 paths. Accordingly an exclusion does not prevent a disk file
1348 from being overwritten by file extraction via an alternative not
1349 excluded path. So the exlusions need to be coordinated with the
1350 actual disk_path parameters given with commands.
1351 (Do not forget to end the list of disk_paths by "--")
1352 -not_leaf pattern
1354 Add a single shell parser style pattern to the list of
1355 exclusions for disk leafnames. These patterns are evaluated when
1356 the exclusion checks are made.
1357 -not_list disk_path
1359 Read lines from disk_path and use each of them either as
1360 -not_paths parameter, if they contain a / character, or as
1361 -not_leaf pattern.
1362 -quoted_not_list disk_path
1364 Like -not_list but with quoted input reading rules. Each word is
1365 handled as one parameter for -not_paths or -not_leaf.
1366 -follow occasion[:occasion[...]]
1368 Enable or disable resolution of symbolic links and mountpoints
1369 under disk_paths. This applies to actions -add, -du*x, -ls*x,
1370 -findx, -concat, and to -disk_pattern expansion.
1371 There are three kinds of follow decisison to be made:
1372 link is the hop from a symbolic link to its target file object
1373 for the purpose of reading. I.e. not for command -concat. If
1374 enabled then symbolic links are handled as their target file
1375 objects, else symbolic links are handled as themselves.
1376 mount is the hop from one filesystem to another subordinate
1377 filesystem. If enabled then mountpoint directories are handled
1378 as any other directory, else mountpoints are handled as empty
1379 directories if they are encountered in directory tree
1380 traversals.
1381 concat is the hop from a symbolic link to its target file object
1382 for the purpose of writing. I.e. for command -concat. This is a
1383 security risk !
1384 Less general than above occasions:
1385 pattern is mount and link hopping, but only during -disk_pattern
1386 expansion.
1387 param is link hopping for parameter words (after eventual
1388 pattern expansion). If enabled then -ls*x will show the link
1389 targets rather than the links themselves. -du*x, -findx, and
1390 -add will process the link targets but not follow links in an
1391 eventual directory tree below the targets (unless "link" is
1392 enabled).
1393 Occasions can be combined in a colon separated list. All
1394 occasions mentioned in the list will then lead to a positive
1395 follow decision.
1396 off prevents any positive follow decision. Use it if no other
1397 occasion applies.
1398 Shortcuts:
1399 default is equivalent to "pattern:mount:limit=100".
1400 on always decides positive. Equivalent to "link:mount:concat".
1401 Not an occasion but an optional setting is:
1403 limit=<number> which sets the maximum number of link hops. A
1404 link hop consists of a sequence of symbolic links and a final
1405 target of different type. Nevertheless those hops can loop.
1406 Example:
1407 $ ln -s .. uploop
1408 Link hopping has a built-in loop detection which stops hopping
1409 at the first repetition of a link target. Then the repeated link
1410 is handled as itself and not as its target. Regrettably one can
1411 construct link networks which cause exponential workload before
1412 their loops get detected. The number given with "limit=" can
1413 curb this workload at the risk of truncating an intentional
1414 sequence of link hops.
1415 -pathspecs "on"|"off"|"as_mkisofs"
1417 Control parameter interpretation with xorriso actions -add and
1418 -path_list.
1419 Mode "as_mkisofs" enables pathspecs of the form
1420 iso_rr_path=disk_path
1421 like with program mkisofs -graft-points.
1422 All characters '\' must be escaped in both, iso_rr_path and
1423 disk_path. The character '=' must be escaped in the iso_rr_path
1424 and may or may not be escaped in the disk_path. This mode
1425 temporarily disables -disk_pattern expansion for command -add.
1426 Mode "on" does nearly the same. But '=' must only be escaped in
1427 the iso_rr_path and '\' must not be escaped at all. This has the
1428 disadvantage that one cannot express an iso_rr_path which ends
1429 by '\'.
1430 Mode "off" disables pathspecs of the form target=source and
1431 re-enables -disk_pattern expansion.
1432 -overwrite "on"|"nondir"|"off"
1434 Allow or disallow overwriting of existing files in the ISO image
1435 by files with the same name.
1436 With setting "off", name collisions with at least one
1437 non-directory file cause FAILURE events. Collisions of two
1438 directories lead to merging of their file lists.
1439 With setting "nondir", only directories are protected by such
1440 events, other existing file types get treated with -rm before
1441 the new file gets added. Setting "on" enables automatic -rm_r.
1442 I.e. a non-directory can replace an existing directory and all
1443 its subordinates.
1444 If restoring of files is enabled, then the overwrite rule
1445 applies to the target file objects on disk as well, but "on" is
1446 downgraded to "nondir".
1447 -split_size number["k"|"m"]
1449 Set the threshold for automatic splitting of regular files. Such
1450 splitting maps a large disk file onto a ISO directory with
1451 several part files in it. This is necessary if the size of the
1452 disk file exceeds -file_size_limit. Older operating systems can
1453 handle files in mounted ISO 9660 filesystems only if they are
1454 smaller than 2 GiB or in other cases 4 GiB.
1455 Default is 0 which will exclude files larger than
1456 -file_size_limit by a FAILURE event. A well tested -split_size
1457 is 2047m. Sizes above -file_size_limit are not permissible.
1458 The newly created ISO directory inherits its permissions from
1459 the data file with additional x-permission for those who have
1460 r-permission.
1461 While command -split_size is set larger than 0 such a directory
1462 with split file pieces will be recognized and handled like a
1463 regular file by commands -compare* , -update*, and in overwrite
1464 situations. There are -osirrox parameters "concat_split_on" and
1465 "concat_split_off" which control the handling when files get
1466 restored to disk.
1467 In order to be recognizable, the names of the part files have to
1468 describe the splitting by 5 numbers:
1469 part_number,total_parts,byte_offset,byte_count,disk_file_size
1470 which are embedded in the following text form:
1471 part_#_of_#_at_#_with_#_of_#
1472 Scaling characters like "m" or "k" are taken into respect. All
1473 digits are interpreted as decimal, even if leading zeros are
1474 present.
1475 E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
1476 No other files are allowed in the directory. All parts have to
1477 be present and their numbers have to be plausible. E.g.
1478 byte_count must be valid as -cut_out parameter and their
1479 contents may not overlap.
1480 File manipulations:
1482 The following commands manipulate files in the ISO image, regardless
1484 whether they stem from the loaded image or were newly inserted.
1485 -iso_rr_pattern "on"|"ls"|"off"
1487 Set the pattern expansion mode for the iso_rr_path parameters of
1488 several commands which support this feature.
1489 Setting "off" disables pattern expansion for all commands which
1490 are marked in this man page by "iso_rr_path [***]" or
1491 "iso_rr_pattern [***]".
1492 Setting "on" enables it for all those commands.
1493 Setting "ls" enables it only for those which are marked by
1494 "iso_rr_pattern [***]".
1495 Default is "on".
1496 -rm iso_rr_path [***]
1498 Delete the given files from the ISO image.
1499 Note: This does not free any space on the -indev medium, even if
1500 the deletion is committed to that same medium.
1501 The image size will shrink if the image is written to a
1502 different medium in modification mode.
1503 -rm_r iso_rr_path [***]
1505 Delete the given files or directory trees from the ISO image.
1506 See also the note with command -rm.
1507 -rmdir iso_rr_path [***]
1509 Delete empty directories.
1510 -move iso_rr_path iso_rr_path
1512 Rename the file given by the first (origin) iso_rr_path to the
1513 second (destination) iso_rr_path. Deviate from rules of shell
1514 command mv by not moving the origin file underneath an existing
1515 destination directory. The origin file will rather replace such
1516 a directory, if this is allowed by command -overwrite.
1517 -mv iso_rr_path [***] iso_rr_path
1519 Rename the given file objects in the ISO tree to the last
1520 parameter in the list. Use the same rules as with shell command
1521 mv.
1522 If pattern expansion is enabled and if the last parameter
1523 contains wildcard characters then it must match exactly one
1524 existing file address, or else the command fails with a FAILURE
1525 event.
1526 -chown uid iso_rr_path [***]
1528 Set ownership of file objects in the ISO image. uid may either
1529 be a decimal number or the name of a user known to the operating
1530 system.
1531 -chown_r uid iso_rr_path [***]
1533 Like -chown but affecting all files below eventual directories.
1534 -chgrp gid iso_rr_path [***]
1536 Set group attribute of file objects in the ISO image. gid may
1537 either be a decimal number or the name of a group known to the
1538 operating system.
1539 -chgrp_r gid iso_rr_path [***]
1541 Like -chgrp but affecting all files below eventual directories.
1542 -chmod mode iso_rr_path [***]
1544 Equivalent to shell command chmod in the ISO image. mode is
1545 either an octal number beginning with "0" or a comma separated
1546 list of statements of the form [ugoa]*[+-=][rwxst]* .
1547 Like: go-rwx,u+rwx .
1548 Personalities: u=user, g=group, o=others, a=all
1549 Operators: + adds given permissions, - revokes given
1550 permissions, = revokes all old permissions and then adds the
1551 given ones.
1552 Permissions: r=read, w=write, x=execute|inspect,
1553 s=setuid|setgid, t=sticky bit
1554 For octal numbers see man 2 stat.
1555 -chmod_r mode iso_rr_path [***]
1557 Like -chmod but affecting all files below eventual directories.
1558 -setfacl acl_text iso_rr_path [***]
1560 Attach the given ACL to the given iso_rr_paths. If the files
1561 already have ACLs, then those get deleted before the new ones
1562 get into effect. If acl_text is empty, or contains the text
1563 "clear" or the text "--remove-all", then the existing ACLs will
1564 be removed and no new ones will be attached. Any other content
1565 of acl_text will be interpreted as a list of ACL entries. It may
1566 be in the long multi-line format as put out by -getfacl but may
1567 also be abbreviated as follows:
1568 ACL entries are separated by comma or newline. If an entry is
1569 empty text or begins with "#" then it will be ignored. A valid
1570 entry has to begin by a letter out of {ugom} for "user",
1571 "group", "other", "mask". It has to contain two colons ":". A
1572 non-empty text between those ":" gives a user id or group id.
1573 After the second ":" there may be letters out of {rwx- #}. The
1574 first three give read, write, or execute permission. Letters
1575 "-", " " and TAB are ignored. "#" causes the rest of the entry
1576 to be ignored. Letter "X" or any other letters are not
1577 supported. Examples:
1578 g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
1579 group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-
1580 A valid entry may be prefixed by "d", some following characters
1581 and ":". This indicates that the entry goes to the "default"
1582 ACL rather than to the "access" ACL. Example:
1583 u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
1584 -setfacl_r acl_text iso_rr_path [***]
1586 Like -setfacl but affecting all files below eventual
1587 directories.
1588 -setfacl_list disk_path
1590 Read the output of -getfacl_r or shell command getfacl -R and
1591 apply it to the iso_rr_paths as given in lines beginning with "#
1592 file:". This will change ownership, group and ACL of the given
1593 files. If disk_path is "-" then lines are read from standard
1594 input. Line "@" ends the list, "@@@" aborts without changing the
1595 pending iso_rr_path.
1596 Since -getfacl and getfacl -R strip leading "/" from file paths,
1597 the setting of -cd does always matter.
1598 -setfattr [-]name value iso_rr_path [***]
1600 Attach the given xattr pair of name and value to the given
1601 iso_rr_paths. If the given name is prefixed by "-", then the
1602 pair with that name gets removed from the xattr list. If name is
1603 "--remove-all" then all user namespace xattr of the given
1604 iso_rr_paths get deleted. In case of deletion, value must be an
1605 empty text.
1606 Which names are permissible depends on the setting of command
1607 -xattr. "on" or "user" restricts them to namespace "user". I.e.
1608 a name has to look like "user.x" or "user.whatever".
1609 -xattr setting "any" enables names from all namespaces except
1610 "isofs".
1611 Values and names undergo the normal input processing of xorriso.
1612 See also command -backslash_codes. Other than with command
1613 -setfattr_list, the byte value 0 cannot be expressed via
1614 -setfattr.
1615 -setfattr_r [-]name value iso_rr_path [***]
1617 Like -setfattr but affecting all files below eventual
1618 directories.
1619 -setfattr_list disk_path
1621 Read the output format of -getfattr_r or shell command getfattr
1622 -Rd and apply it to the iso_rr_paths as given in lines beginning
1623 with "# file:". All previously existing xattr of the acceptable
1624 namespaces will be deleted before the new xattr get attached.
1625 The set of acceptable names depends on the setting of command
1626 -xattr.
1627 If disk_path is "-" then lines are read from standard input.
1628 Since -getfattr and getfattr -Rd strip leading "/" from file
1629 paths, the setting of -cd does always matter.
1630 Empty input lines and lines which begin by "#" will be ignored
1631 (except "# file:"). Line "@" ends the list, "@@@" aborts without
1632 changing the pending iso_rr_path. Other input lines must have
1633 the form
1634 name="value"
1635 The separator "=" is not allowed in names. Value may contain
1636 any kind of bytes. It must be in quotes. Trailing whitespace
1637 after the end quote will be ignored. Non-printables bytes and
1638 quotes must be represented as \XYZ by their octal 8-bit code
1639 XYZ. Use code \000 for 0-bytes.
1640 -alter_date type timestring iso_rr_path [***]
1642 Alter the date entries of files in the ISO image. type may be
1643 one of the following:
1644 "a" sets access time, updates ctime.
1645 "m" sets modification time, updates ctime.
1646 "b" sets access time and modification time, updates ctime.
1647 "a-c", "m-c", and "b-c" set the times without updating ctime.
1648 "c" sets the ctime.
1649 timestring may be in the following formats (see also section
1650 EXAMPLES):
1651 As expected by program date:
1652 MMDDhhmm[[CC]YY][.ss]]
1653 As produced by program date:
1654 [Day] MMM DD hh:mm:ss [TZON] YYYY
1655 Relative times counted from current clock time:
1656 +|-Number["s"|"h"|"d"|"w"|"m"|"y"]
1657 where "s" means seconds, "h" hours, "d" days, "w" weeks,
1658 "m"=30d, "y"=365.25d plus 1d added to multiplication result.
1659 Absolute seconds counted from Jan 1 1970:
1660 =Number
1661 xorriso's own timestamps:
1662 YYYY.MM.DD[.hh[mm[ss]]]
1663 scdbackup timestamps:
1664 YYMMDD[.hhmm[ss]]
1665 where "A0" is year 2000, "B0" is 2010, etc.
1666 ECMA-119 volume timestamps:
1667 YYYYMMDDhhmmsscc
1668 These are normally given as GMT. The suffix "LOC" causes local
1669 timezone conversion. E.g. 2013010720574700, 2013010720574700LOC.
1670 The last two digits cc (centiseconds) will be ignored, but must
1671 be present in order to make the format recognizable.
1672 Example:
1673 -alter_date m-c 2013.11.27.103951 /file1 /file2 --
1674 This command does not persistently apply to the boot catalog,
1675 which gets fresh timestamps at -commit time. Command
1676 -volume_date "uuid" can set this time value.
1677 -alter_date_r type timestring iso_rr_path [***]
1679 Like -alter_date but affecting all files below eventual
1680 directories.
1681 -hide hide_state iso_rr_path [***]
1683 Prevent the names of the given files from showing up in the
1684 directory trees of ISO 9660 and/or Joliet and/or HFS+ when the
1685 image gets written. The data content of such hidden files will
1686 be included in the resulting image, even if they do not show up
1687 in any directory. But you will need own means to find nameless
1688 data in the image.
1689 Warning: Data which are hidden from the ISO 9660 tree will not
1690 be copied by the write method of modifying.
1691 Possible values of hide_state are: "iso_rr" for hiding from ISO
1692 9660 tree, "joliet" for Joliet tree, "hfsplus" for HFS+, "on"
1693 for them all. "off" means visibility in all directory trees.
1694 These values may be combined. E.g.: joliet:hfsplus
1695 This command does not apply to the boot catalog. Rather use:
1696 -boot_image "any" "cat_hidden=on"
1697 Tree traversal command -find:
1699 -find iso_rr_path [test [op] [test ...]] [-exec action [params]] --
1701 A restricted substitute for shell command find in the ISO image.
1702 It performs an action on matching file objects at or below
1703 iso_rr_path.
1704 If not used as last command in the line then the parameter list
1705 needs to get terminated by "--".
1706 Tests are optional. If they are omitted then action is applied
1707 to all file objects. If tests are given then they form together
1708 an expression. The action is applied only if the expression
1709 matches the file object. Default expression operator between
1710 tests is -and, i.e. the expression matches only if all its tests
1711 match.
1712 Available tests are:
1713 -name pattern : Matches if pattern matches the file leaf name.
1714 If the pattern does not contain any of the characters "*?[",
1715 then it will be truncated according to -file_name_limit and thus
1716 match the truncated name in the ISO filesystem.
1717 -wholename pattern : Matches if pattern matches the file path as
1718 it would be printed by action "echo". Character '/' can be
1719 matched by wildcards. If pattern pieces between '/' do not
1720 contain any of the characters "*?[", they will be truncated
1721 according to -file_name_limit.
1722 -disk_name pattern : Like -name but testing the leaf name of the
1723 file source on disk. Can match only data files which do not
1724 stem from the loaded image, or for directories above such data
1725 files. With directories the result can change between -find runs
1726 if their content stems from multiple sources.
1727 -disk_path disk_path : Matches if the given disk_path is equal
1728 to the path of the file source on disk. The same restrictions
1729 apply as with -disk_name.
1730 -type type_letter : Matches files of the given type: "block",
1731 "char", "dir", "pipe", "file", "link", "socket", "eltorito", and
1732 "Xotic" which matches what is not matched by the other types.
1733 Only the first letter is interpreted. E.g.: -find / -type d
1734 -size [+-][=]number[cwbdksmg] : Matches files with matching
1735 relation to the given size number.
1736 The prefix defines the desired relation:
1737 No prefix or prefix "=" means: File must have exactly the given
1738 size.
1739 Prefix "+" means: File must be larger than given size.
1740 Prefix "+=" means: File must be larger than or equal to given
1741 size limit.
1742 Prefix "-" means: File must be smaller than given size limit.
1743 Prefix "-=" means: File must be smaller than or equal to given
1744 size limit.
1745 Suffixes are peculiar to stay compatible with program "find":
1746 No suffix means blocks of 512 bytes, "c" means single bytes, "w"
1747 means 2 bytes, "b" means 512 bytes. The suffixes "k", "M", and
1748 "G" mean 1024, 1024k, and 1024M respectively. As usual with
1749 xorriso, the suffixes "d" and "s" mean 512 and 2048 and all
1750 suffixes are recognized as both, uppercase and lowercase
1751 letters.
1752 E.g. match files of 4 GiB or larger:
1753 -size +=4g
1754 -maxdepth number : Matches only files which are at most at the
1755 given depth level relative to the iso_rr_path where -find
1756 starts. That path itself is at depth 0, its directory children
1757 are at 1, their directory children at 2, and so on.
1758 -mindepth number : Matches only files which are at least at the
1759 given depth level.
1760 -damaged : Matches files which use data blocks marked as damaged
1761 by a previous run of -check_media. The damage info vanishes when
1762 a new ISO image gets loaded.
1763 Note that a MD5 session mismatch marks all files of the session
1764 as damaged. If finer distinction is desired, perform -md5 off
1765 before -check_media.
1766 -pending_data : Matches files which get their content from
1767 outside the loaded ISO image.
1768 -lba_range start_lba block_count : Matches files which use data
1769 blocks within the range of start_lba and
1770 start_lba+block_count-1.
1771 -has_acl : Matches files which have a non-trivial ACL.
1772 -has_xattr : Matches files which have xattr name-value pairs
1773 from user namespace.
1774 -has_aaip : Matches files which have ACL or any xattr.
1775 -has_any_xattr : Matches files which have any xattr other than
1776 ACL.
1777 -has_md5 : Matches data files which have MD5 checksums.
1778 -has_hfs_crtp creator type : Matches files which have the given
1779 HFS+ creator and type attached. These are codes of 4 characters
1780 which get stored if -hfsplus is enabled. Use a single dash '-'
1781 as wildcard that matches any such code. E.g:.
1782 -has_hfs_crtp YYDN TEXT
1783 -has_hfs_crtp - -
1784 -has_hfs_bless blessing : Matches files which bear the given
1785 HFS+ blessing. It may be one of : "ppc_bootdir",
1786 "intel_bootfile", "show_folder", "os9_folder", "osx_folder",
1787 "any". See also action set_hfs_bless.
1788 -has_filter : Matches files which are filtered by -set_filter.
1789 -hidden hide_state : Matches files which are hidden in "iso_rr"
1790 tree, in "joliet" tree, in "hfsplus" tree, in all trees ("on"),
1791 or not hidden in any tree ("off").
1792 Those which are hidden in some tree match -not -hidden "off".
1793 -bad_outname namespace : Matches files with names which change
1794 when converted forth and back between the local character set
1795 and one of the namespaces "rockridge", "joliet", "ecma119",
1796 "hfsplus".
1797 All applicable -compliance rules are taken into respect. Rule
1798 "omit_version" is always enabled, because else namespaces
1799 "joliet" and "ecma119" would cause changes with every
1800 non-directory name. Consider to also enable rules
1801 "no_force_dots" and "no_j_force_dots".
1802 The namespaces use different character sets and apply further
1803 restrictions to name length, permissible characters, and
1804 mandatory name components. "rockridge" uses the character set
1805 defined by -out_charset, "joliet" uses UCS-2BE, "ecma119" uses
1806 ASCII, "hfsplus" uses UTF-16BE.
1807 -name_limit_blocker length : Matches file names which would
1808 prevent command -file_name_limit with the given length. The
1809 command itself reports only the first problem file.
1810 -prune : If this test is reached and the tested file is a
1811 directory then -find will not dive into that directory. This
1812 test itself does always match.
1813 -use_pattern "on"|"off" : This pseudo test controls the
1814 interpretation of wildcards with tests -name, -wholename, and
1815 -disk_name. Default is "on". If interpretation is disabled by
1816 "off", then the parameters of -name, -wholename, and -disk_name
1817 have to match literally rather than as search pattern. This
1818 test itself does always match.
1819 -or_use_pattern "on"|"off" : Like -use_pattern, but
1820 automatically appending the test by -or rather than by -and.
1821 Further the test itself does never match. So a subsequent test
1822 -or will cause its other operand to be performed.
1823 -decision "yes"|"no" : If this test is reached then the
1824 evaluation ends immediately and action is performed if the
1825 decision is "yes" or "true". See operator -if.
1826 -true and -false : Always match or match not, respectively.
1827 Evaluation goes on.
1828 -sort_lba : Always match. This causes -find to perform its
1829 action in a sequence sorted by the ISO image block addresses of
1830 the files. It may improve throughput with actions which read
1831 data from optical drives. Action will always get the absolute
1832 path as parameter.
1833 Available operators are:
1834 -not : Matches if the next test or sub expression does not
1835 match. Several tests do this specifically:
1836 -undamaged, -lba_range with negative start_lba, -has_no_acl,
1837 -has_no_xattr, -has_no_aaip, -has_no_filter .
1838 -and : Matches if both neighboring tests or expressions match.
1839 -or : Matches if at least one of both neighboring tests or
1840 expressions matches.
1841 -sub ... -subend or ( ... ) : Enclose a sub expression which
1842 gets evaluated first before it is processed by neighboring
1843 operators. Normal precedence is: -not, -or , -and.
1844 -if ... -then ... -elseif ... -then ... -else ... -endif :
1845 Enclose one or more sub expressions. If the -if expression
1846 matches, then the -then expression is evaluated as the result of
1847 the whole expression up to -endif. Else the next -elseif
1848 expression is evaluated and if it matches, its -then expression.
1849 Finally in case of no match, the -else expression is evaluated.
1850 There may be more than one -elseif. Neither -else nor -elseif
1851 are mandatory. If -else is missing and would be hit, then the
1852 result is a non-match.
1853 -if-expressions are the main use case for above test -decision.
1854 Default action is echo, i.e. to print the address of the found
1856 file. Other actions are certain xorriso commands which get
1857 performed on the found files. These commands may have specific
1858 parameters. See also their particular descriptions.
1859 chown and chown_r change the ownership and get the user id as
1860 parameter. E.g.: -exec chown thomas --
1861 chgrp and chgrp_r change the group attribute and get the group
1862 id as parameter. E.g.: -exec chgrp_r staff --
1863 chmod and chmod_r change access permissions and get a mode
1864 string as parameter. E.g.: -exec chmod a-w,a+r --
1865 alter_date and alter_date_r change the timestamps. They get a
1866 type character and a timestring as parameters.
1867 E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" --
1868 set_to_mtime sets the ctime and atime to the value found in
1869 mtime.
1870 lsdl prints file information like shell command ls -dl.
1871 compare performs command -compare with the found file address as
1872 iso_rr_path and the corresponding file address below its
1873 parameter disk_path_start. For this the iso_rr_path of the -find
1874 command gets replaced by the disk_path_start.
1875 E.g.: -find /thomas -exec compare /home/thomas --
1876 update performs command -update with the found file address as
1877 iso_rr_path. The corresponding file address is determined like
1878 with above action "compare".
1879 update_merge is like update but does not delete the found file
1880 if it is missing on disk. It may be run several times and
1881 records with all visited files whether their counterpart on disk
1882 has already been seen by one of the update_merge runs. Finally,
1883 a -find run with action "rm_merge" may remove all files that saw
1884 no counterpart on disk.
1885 Up to the next "rm_merge" or "clear_merge" all newly inserted
1886 files will get marked as having a disk counterpart.
1887 rm removes the found iso_rr_path from the image if it is not a
1888 directory with files in it. I.e. this "rm" includes "rmdir".
1889 rm_r removes the found iso_rr_path from the image, including
1890 whole directory trees.
1891 rm_merge removes the found iso_rr_path if it was visited by one
1892 or more previous actions "update_merge" and saw no counterpart
1893 on disk in any of them. The marking from the update actions is
1894 removed in any case.
1895 clear_merge removes an eventual marking from action
1896 "update_merge".
1897 report_damage classifies files whether they hit a data block
1898 that is marked as damaged. The result is printed together with
1899 the address of the first damaged byte, the maximum span of
1900 damages, file size, and the path of the file.
1901 report_lba prints files which are associated to image data
1902 blocks. It tells the logical block address, the block number,
1903 the byte size, and the path of each file. There may be reported
1904 more than one line per file if the file has more than one
1905 section. In this case each line has a different extent number
1906 in column "xt".
1907 report_sections like report_lba but telling the byte sizes of
1908 the particular sections rather than the overall byte size of the
1909 file.
1910 getfacl prints access permissions in ACL text form to the result
1911 channel.
1912 setfacl attaches ACLs after removing existing ones. The new ACL
1913 is given in text form as defined with command -setfacl.
1914 E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
1915 getfattr prints xattr name-value pairs to the result channel.
1916 The choice of namespaces depends on the setting of command
1917 -xattr: "on" or "user" restricts it to the namespace "user",
1918 "any" only omits namespace "isofs".
1919 get_any_xattr prints xattr name-value pairs from any namespace
1920 except ACL to the result channel. This is mostly for debugging
1921 of namespace "isofs".
1922 list_extattr mode prints a script to the result channel, which
1923 would use FreeBSD command setextattr to set the file's xattr
1924 name-value pairs of user namespace. Parameter mode controls the
1925 form of the output of names and values. Default mode "e" prints
1926 harmless characters in shell quotation marks, but represents
1927 texts with octal 001 to 037 and 0177 to 0377 by an embedded echo
1928 -e command. Mode "q" prints any characters in shell quotation
1929 marks. This might not be terminal-safe but should work in script
1930 files. Mode "r" uses no quotation marks. Not safe. Mode "b"
1931 prints backslash encoding. Not suitable for shell parsing.
1932 E.g. -exec list_extattr e --
1933 Command -backslash_codes does not affect the output.
1934 get_md5 prints the MD5 sum, if recorded, together with file
1935 path.
1936 check_md5 compares the MD5 sum, if recorded, with the file
1937 content and reports if mismatch.
1938 E.g.: -find / -not -pending_data -exec check_md5 FAILURE --
1939 make_md5 equips a data file with an MD5 sum of its content.
1940 Useful to upgrade the files in the loaded image to full MD5
1941 coverage by the next commit with -md5 "on".
1942 E.g.: -find / -type f -not -has_md5 -exec make_md5 --
1943 setfattr sets or deletes xattr name value pairs.
1944 E.g.: -find / -has_xattr -exec setfattr --remove-all '' --
1945 set_hfs_crtp adds, changes, or removes HFS+ creator and type
1946 attributes.
1947 E.g.: -exec set_hfs_crtp YYDN TEXT
1948 E.g.: -find /my/dir -prune -exec set_hfs_crtp --delete -
1949 get_hfs_crtp prints the HFS+ creator and type attributes
1950 together with the iso_rr_path, if the file has such attributes
1951 at all.
1952 E.g.: -exec get_hfs_crtp
1953 set_hfs_bless applies or removes HFS+ blessings. They are roles
1954 which can be attributed to up to four directories and a data
1955 file:
1956 "ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder",
1957 "osx_folder".
1958 They may be abbreviated as "p", "i", "s", "9", and "x".
1959 Each such role can be attributed to at most one file object.
1960 "intel_bootfile" is the one that would apply to a data file. All
1961 others apply to directories. The -find run will end as soon as
1962 the first blessing is issued. The previous bearer of the
1963 blessing will lose it then. No file object can bear more than
1964 one blessing.
1965 E.g.: -find /my/blessed/directory -exec set_hfs_bless p
1966 Further there is blessing "none" or "n" which revokes any
1967 blessing from the found files. This -find run will not stop when
1968 the first match is reached.
1969 E.g.: -find / -has_hfs_bless any -exec set_hfs_bless none
1970 get_hfs_bless prints the HFS+ blessing role and the iso_rr_path,
1971 if the file is blessed at all.
1972 E.g.: -exec get_hfs_bless
1973 set_filter applies or removes filters.
1974 E.g.: -exec set_filter --zisofs --
1975 mkisofs_r applies the rules of mkisofs -r to the file object:
1976 user id and group id become 0, all r-permissions get granted,
1977 all w denied. If there is any x-permission, then all three x
1978 get granted. s- and t-bits get removed.
1979 sort_weight attributes a LBA weight number to regular files.
1980 The number may range from -2147483648 to 2147483647. The higher
1981 it is, the lower will be the block address of the file data in
1982 the emerging ISO image. Currently the boot catalog has a
1983 hardcoded weight of 1 billion. Normally it should occupy the
1984 block with the lowest possible address.
1985 Data files which are loaded by -indev or -dev get a weight
1986 between 1 and 2 exp 28 = 268,435,456, depending on their block
1987 address. This shall keep them roughly in the same order if the
1988 write method of modifying is applied.
1989 Data files which are added by other commands get an initial
1990 weight of 0. Boot image files have a default weight of 2.
1991 E.g.: -exec sort_weight 3 --
1992 show_stream shows the content stream chain of a data file.
1993 show_stream_id is like show_stream, but also prints between
1994 stream type and first ":" in square brackets libisofs id
1995 numbers: [fs_id,dev_id,ino_id].
1996 hide brings the file into one of the hide states "on", "iso_rr",
1997 "joliet", "hfsplus", "off". They may be combined. E.g.:
1998 joliet:hfsplus
1999 E.g.:
2000 -find / -disk_name *_secret -exec hide on
2001 print_outname prints in the first line the filename as
2002 registered by the program model, and in the second line the
2003 filename after conversion forth and back between local character
2004 set and one of the namespaces "rockridge", "joliet", "ecma119",
2005 or "hfsplus". The third output line is "--" .
2006 The name conversion does not take into respect the possibility
2007 of name collisions in the target namespace. Such collisions are
2008 most likely in "joliet" and "ecma119", where they get resolved
2009 by automatic file name changes.
2010 E.g.:
2011 -find / -bad_outname joliet -exec print_outname joliet
2012 estimate_size prints a lower and an upper estimation of the
2013 number of blocks which the found files together will occupy in
2014 the emerging ISO image. This does not account for the
2015 superblock, for the directories in the -find path, or for image
2016 padding.
2017 find performs another run of -find on the matching file address.
2018 It accepts the same params as -find, except iso_rr_path.
2019 E.g.:
2020 -find / -name '???' -type d -exec find -name '[abc]*' -exec
2021 chmod a-w,a+r --
2022 Filters for data file content:
2024 Filters may be installed between data files in the ISO image and their
2026 content source outside the image. They may also be used vice versa
2027 between data content in the image and target files on disk.
2028 Built-in filters are "--zisofs" and "--zisofs-decode". The former is to
2029 be applied via -set_filter, the latter is automatically applied if
2030 zisofs compressed content is detected with a file when loading the ISO
2031 image.
2032 Another built-in filter pair is "--gzip" and "--gunzip" with suffix
2033 ".gz". They behave about like external gzip and gunzip but avoid
2034 forking a process for each single file. So they are much faster if
2035 there are many small files.
2036 -external_filter name option[:option] program_path [arguments] --
2038 Register a content filter by associating a name with a program
2039 path, program arguments, and some behavioral options. Once
2040 registered it can be applied to multiple data files in the ISO
2041 image, regardless whether their content resides in the loaded
2042 ISO image or in the local filesystem. External filter processes
2043 may produce synthetic file content by reading the original
2044 content from stdin and writing to stdout whatever they want.
2045 They must deliver the same output on the same input in repeated
2046 runs.
2047 Options are:
2048 "default" means that no other option is intended.
2049 "suffix=..." sets a file name suffix. If it is not empty then
2050 it will be appended to the file name or removed from it.
2051 "remove_suffix" will remove a file name suffix rather than
2052 appending it.
2053 "if_nonempty" will leave 0-sized files unfiltered.
2054 "if_reduction" will try filtering and revoke it if the content
2055 size does not shrink.
2056 "if_block_reduction" will revoke if the number of 2 kB blocks
2057 does not shrink.
2058 "used=..." is ignored. Command -status shows it with the number
2059 of files which currently have the filter applied.
2060 Examples:
2061 -external_filter bzip2 suffix=.bz2:if_block_reduction \
2062 /usr/bin/bzip2 --
2063 -external_filter bunzip2 suffix=.bz2:remove_suffix \
2064 /usr/bin/bunzip2 --
2065 -unregister_filter name
2067 Remove an -external_filter registration. This is only possible
2068 if the filter is not applied to any file in the ISO image.
2069 -close_filter_list
2071 Irrevocably ban commands -concat "pipe", -external_filter, and
2072 -unregister_filter, but not -set_filter. Use this to prevent
2073 external filtering in general or when all intended filters are
2074 registered and -concat mode "pipe" shall be disallowed.
2075 External filters may also be banned totally at compile time of
2076 xorriso. By default they are banned if xorriso runs under
2077 setuid permission.
2078 -set_filter name iso_rr_path [***]
2080 Apply an -external_filter or a built-in filter to the given data
2081 files in the ISO image. If the filter suffix is not empty ,
2082 then it will be applied to the file name. Renaming only happens
2083 if the filter really gets attached and is not revoked by its
2084 options. By default files which already bear the suffix will
2085 not get filtered. The others will get the suffix appended to
2086 their names. If the filter has option "remove_suffix", then the
2087 filter will only be applied if the suffix is present and can be
2088 removed. Name oversize or collision caused by suffix change
2089 will prevent filtering.
2090 With most filter types this command will immediately run the
2091 filter once for each file in order to determine the output size.
2092 Content reading operations like -extract , -compare and image
2093 generation will perform further filter runs and deliver filtered
2094 content.
2095 At image generation time the filter output must still be the
2096 same as the output from the first run. Filtering for image
2097 generation does not happen with files from the loaded ISO image
2098 if the write method of growing is in effect (i.e -indev and
2099 -outdev are identical).
2100 The reserved filter name "--remove-all-filters" revokes
2101 filtering. This will revoke suffix renamings as well. Use
2102 "--remove-all-filters+" to prevent any suffix renaming.
2103 Attaching or detaching filters will not alter the state of
2104 -changes_pending. If the filter manipulations shall be the only
2105 changes in a write run, then explicitly execute -changes_pending
2106 "yes".
2107 -set_filter_r name iso_rr_path [***]
2109 Like -set_filter but affecting all data files below eventual
2110 directories.
2111 Writing the result, drive control:
2113 (see also paragraph about settings below)
2115 -rollback
2117 Discard the manipulated ISO image and reload it from -indev.
2118 (Use -rollback_end if immediate program end is desired.)
2119 -changes_pending "no"|"yes"|"mkisofs_printed"|"show_status"
2121 Write runs are performed only if a change of the image has been
2122 made since the image was loaded or created blank. Vice versa the
2123 program will start a write run for pending changes when it ends
2124 normally (i.e. not by abort and not by command -rollback_end).
2125 The command -changes_pending can be used to override the
2126 automatically determined state. This is mainly useful for
2127 setting state "yes" despite no real changes were made. The
2128 sequence -changes_pending "no" -end is equivalent to the command
2129 -rollback_end. State "mkisofs_printed" is caused by emulation
2130 command -as mkisofs if option -print-size is present.
2131 The pseudo-state "show_status" can be used to print the current
2132 state to result channel.
2133 Image loading or manipulations which happen after this command
2134 will again update automatically the change status of the image.
2135 -commit
2137 Perform the write operation. Afterwards, if -outdev is readable,
2138 make it the new -dev and load the image from there. Switch to
2139 growing mode. (A subsequent -outdev will activate modification
2140 mode or blind growing.) -commit is performed automatically at
2141 end of program if there are uncommitted manipulations pending.
2142 So, to perform a final write operation with no new -dev and no
2143 new loading of image, rather execute command -end. If you want
2144 to go on without image loading, execute -commit_eject "none".
2145 To eject after write without image loading, use -commit_eject
2146 "all".
2147 To suppress a final write, execute -rollback_end.
2148 Writing can last quite a while. It is not unnormal with several
2150 types of media that there is no progress visible for the first
2151 few minutes or that the drive gnaws on the medium for a few
2152 minutes after all data have been transmitted. xorriso and the
2153 drives are in a client-server relationship. The drives have
2154 much freedom about what to do with the media. Some combinations
2155 of drives and media simply do not work, despite the promises by
2156 their vendors. If writing fails then try other media or another
2157 drive. The reason for such failure is hardly ever in the code of
2158 the various burn programs but you may well try some of those
2159 listed below under SEE ALSO.
2160 -eject "in"|"out"|"all"
2162 Eject the medium in -indev, -outdev, or both drives,
2163 respectively. Note: It is not possible yet to effectively eject
2164 disk files.
2165 -commit_eject "in"|"out"|"all"|"none"
2167 Combined -commit and -eject. When writing has finished do not
2168 make -outdev the new -dev, and load no ISO image. Rather eject
2169 -indev and/or -outdev. Give up any non-ejected drive.
2170 -blank mode
2172 Make media ready for writing from scratch (if not -dummy is
2173 activated).
2174 This affects only the -outdev not the -indev. If both drives
2175 are the same and if the ISO image was altered then this command
2176 leads to a FAILURE event. Defined modes are:
2177 as_needed, fast, all, deformat, deformat_quickest
2178 "as_needed" cares for used CD-RW, DVD-RW and for used
2179 overwritable media by applying -blank "fast". It applies -format
2180 "full" to yet unformatted DVD-RAM and BD-RE. Other media in
2181 blank state are gracefully ignored. Media which cannot be made
2182 ready for writing from scratch cause a FAILURE event.
2183 "fast" makes CD-RW and unformatted DVD-RW re-usable, or
2184 invalidates overwritable ISO images. "all" might work more
2185 thoroughly and need more time.
2186 "deformat" converts overwritable DVD-RW into unformatted ones.
2187 "deformat_quickest" is a faster way to deformat or blank DVD-RW
2188 but produces media which are only suitable for a single session.
2189 Some drives announce this state by not offering feature 21h, but
2190 some drives offer it anyway. If feature 21h is missing, then
2191 xorriso will refuse to write on DVD-RW if not command -close is
2192 set to "on".
2193 The progress reports issued by some drives while blanking are
2194 quite unrealistic. Do not conclude success or failure from the
2195 reported percentages. Blanking was successful if no SORRY event
2196 or worse occurred.
2197 Mode may be prepended by "force:" in order to override the
2198 evaluation of the medium state by libburn. E.g. "force:fast".
2199 Blanking will nevertheless only succeed if the drive is willing
2200 to do it.
2201 -format mode
2203 Convert unformatted DVD-RW into overwritable ones, "de-ice"
2204 DVD+RW, format newly purchased BD-RE or BD-R, re-format DVD-RAM
2205 or BD-RE.
2206 Defined modes are:
2207 as_needed, full, fast, by_index_<num>, fast_by_index_<num>,
2208 by_size_<num>, fast_by_size_<num>, without_spare
2209 "as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or
2210 blank unformatted BD-R. Other media are left untouched.
2211 "full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank
2212 unformatted BD-R.
2213 "fast" does the same as "full" but tries to be quicker.
2214 "by_index_" selects a format out of the descriptor list issued
2215 by command -list_formats. The index number from that list is to
2216 be appended to the mode word. E.g: "by_index_3".
2217 "fast_by_index_" does the same as "by_index_" but tries to be
2218 quicker.
2219 "by_size_" selects a format out of the descriptor list which
2220 provides at least the given size. That size is to be appended to
2221 the mode word. E.g: "by_size_4100m". This applies to media with
2222 Defect Management. On BD-RE it will not choose format 0x31,
2223 which offers no Defect Management.
2224 "fast_by_size_" does the same as "by_size_" but tries to be
2225 quicker.
2226 "without_spare" selects the largest format out of the descriptor
2227 list which provides no Spare Area for Defect Management. On
2228 BD-RE this will be format 0x31.
2229 The formatting action has no effect on media if -dummy is
2230 activated.
2231 Formatting is normally needed only once during the lifetime of a
2232 medium, if ever. But it is a reason for re-formatting if:
2233 DVD-RW was deformatted by -blank,
2234 DVD+RW has read failures (re-format before next write),
2235 DVD-RAM or BD-RE shall change their amount of defect reserve.
2236 BD-R may be written unformatted or may be formatted before first
2237 use. Formatting activates Defect Management which tries to
2238 catch and repair bad spots on media during the write process at
2239 the expense of half speed even with flawless media.
2240 The progress reports issued by some drives while formatting are
2241 quite unrealistic. Do not conclude success or failure from the
2242 reported percentages. Formatting was successful if no SORRY
2243 event or worse occurred. Be patient with apparently frozen
2244 progress.
2245 -list_formats
2247 Put out a list of format descriptors as reported by the output
2248 drive for the current medium. The list gives the index number
2249 after "Format idx", a MMC format code, the announced size in
2250 blocks (like "2236704s") and the same size in MiB.
2251 MMC format codes are manifold. Most important are: "00h" general
2252 formatting, "01h" increases reserve space for DVD-RAM, "26h" for
2253 DVD+RW, "30h" for BD-RE with reserve space, "31h" for BD-RE
2254 without reserve space, "32h" for BD-R.
2255 Smaller format size with DVD-RAM, BD-RE, or BD-R means more
2256 reserve space.
2257 -list_speeds
2259 Put out a list of speed values as reported by the drives with
2260 the loaded media. The list tells read speeds of the input drive
2261 and of the output drive. Further it tells write speeds of the
2262 output drive.
2263 The list of write speeds does not necessarily mean that the
2264 medium is writable or that these speeds are actually achievable.
2265 Especially the lists reported with empty drive or with ROM media
2266 obviously advertise speeds for other media.
2267 It is not mandatory to use speed values out of the listed range.
2268 The drive is supposed to choose a safe speed that is as near to
2269 the desired speed as possible.
2270 At the end of the list, "Write speed L" and "Write speed H" are
2271 the best guesses for lower and upper write speed limit. "Write
2272 speed l" and "Write speed h" may appear only with CD and
2273 eventually override the list of other speed offers.
2274 Only if the drive reports contradicting speed information there
2275 will appear "Write speed 0", which tells the outcome of speed
2276 selection by command -speed 0, if it deviates from "Write speed
2277 H".
2278 "Read speed L" and "Read speed H" tell the minimum and maximum
2279 read speeds, as reported by the drive. They would be chosen by
2280 -read_speed "min" or "max" if they undercut or surpass the
2281 built-in limits. These are "1x", "52xCD", "24xDVD", "20xBD".
2282 -list_profiles "in"|"out"|"all"
2284 Put out a list of media types supported by -indev, -outdev, or
2285 both, respectively. The currently recognized type is marked by
2286 text "(current)".
2287 -truncate_overwritable entity id adjust
2289 On overwritable medium copy the volume descriptors of an
2290 existing session to the overall descriptors at LBA 0 ff. This
2291 makes all sessions inaccessible which are younger than the
2292 activated one. A reason to do this would be read errors in the
2293 younger sessions and the wish to re-write or skip them.
2294 This operation is only allowed if no changes to the loaded
2295 filesystem are pending. If an -indev is acquired then it is
2296 released before the write operation begins and re-acquired only
2297 in case of success.
2298 The parameters "entity" and "id" have the same meaning as with
2299 command -load. They choose the existing ISO session which shall
2300 become the youngest accessible session. Available entity names
2301 are "session", "track", "lba", "sbsector", "volid". "auto" makes
2302 few sense. id is a number or search text as appropriate for the
2303 given entity.
2304 Parameter "adjust" controls the claimed size of the activated
2305 session. Text "new" means the size of the newly activated
2306 session as it was before this command. I.e. the space of the
2307 then inaccessible younger sessions will be re-used when
2308 appending more sessions.
2309 "old" means the size up to the end of the previously youngest
2310 session. I.e. "old" will not free the space of the then
2311 inaccessible younger sessions for re-use.
2312 A number preceded by "+" gives the number of bytes to be added
2313 to "new". A number without "+" gives the overall number of
2314 bytes. In any case the result may not be smaller than "new".
2315 Numbers may have a unit suffix: "d"=512, "k"=1024, "s"=2048,
2316 "m"=1024k, "g"=1024m.
2317 Normally the volume descriptors at block 16 ff. have to be
2318 readable. Only with entity "lba" or "sbsector" and adjust mode
2319 "new" it is possible to address a session if block 16 ff. yields
2320 no valid volume descriptors.
2321 Examples:
2322 Activate session 4 and enable overwriting of the blocks of
2323 younger sessions:
2324 -truncate_overwritable session 4 new
2325 Activate session 4 and claim the blocks of younger sessions as
2326 useless part of session 4:
2327 -truncate_overwritable session 4 old
2328 Let session 4 claim additional 500 MiB as useless data:
2329 -truncate_overwritable session 4 +500m
2330 -close_damaged "as_needed"|"force"
2332 Try to close the upcoming track and session if the drive
2333 reported the medium as damaged. This may apply to CD-R, CD-RW,
2334 DVD-R, DVD-RW, DVD+R, DVD+R DL, or BD-R media. It is indicated
2335 by warning messages when the drive gets acquired, and by a
2336 remark "but next track is damaged" with the line "Media status
2337 :" of command -toc.
2338 The setting of command -close determines whether the medium
2339 stays appendable.
2340 Mode "as_needed" gracefully refuses on media which are not
2341 reported as damaged. Mode "force" attempts the close operation
2342 even with media which appear undamaged.
2343 No image changes are allowed to be pending before this command
2344 is performed. After closing was attempted, both drives are
2345 given up.
2346 Settings for result writing:
2348 Rock Ridge info will be generated by default. ACLs will be written
2350 according to the setting of command -acl.
2351 -joliet "on"|"off"
2353 If enabled by "on", generate Joliet tree additional to ISO 9660
2354 + Rock Ridge tree.
2355 -hfsplus "on"|"off"
2357 If enabled by "on", generate a HFS+ filesystem inside the ISO
2358 9660 image and mark it by Apple Partition Map (APM) entries in
2359 the System Area, the first 32 KiB of the image.
2360 This may collide with data submitted by -boot_image
2361 system_area=. The first 8 bytes of the System Area get
2362 overwritten by { 0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff }
2363 which can be executed as x86 machine code without negative
2364 effects. So if an MBR gets combined with this feature, then its
2365 first 8 bytes should contain no essential commands.
2366 The next blocks of 2 KiB in the System Area will be occupied by
2367 APM entries. The first one covers the part of the ISO image
2368 before the HFS+ filesystem metadata. The second one marks the
2369 range from HFS+ metadata to the end of file content data. If
2370 more ISO image data follow, then a third partition entry gets
2371 produced. Other features of xorriso might cause the need for
2372 more APM entries.
2373 The HFS+ filesystem is not suitable for add-on sessions produced
2374 by the multi-session method of growing. An existing ISO image
2375 may nevertheless be the base for a new image produced by the
2376 method of modifying. If -hfsplus is enabled when -indev or -dev
2377 gets executed, then AAIP attributes get loaded from the input
2378 image and checked for information about HFS creator, filetype,
2379 or blessing. If found, then they get enabled as settings for the
2380 next image production. Therefore it is advisable to perform
2381 -hfsplus "on" before -indev or -dev.
2382 Information about HFS creator, type, and blessings gets stored
2383 by xorriso if -hfsplus is enabled at -commit time. It is stored
2384 as copy outside the HFS+ partition, but rather along with the
2385 Rock Ridge information. xorriso does not read any information
2386 from the HFS+ meta data.
2387 Be aware that HFS+ is case-insensitive although it can record
2388 file names with upper-case and lower-case letters. Therefore,
2389 file names from the iso_rr name tree may collide in the HFS+
2390 name tree. In this case they get changed by adding underscore
2391 characters and counting numbers. In case of very long names, it
2392 might be necessary to map them to "MANGLED_...".
2393 WARNING:
2394 The HFS+ implementation in libisofs has a limit of 125,829,120
2395 bytes for the size of the overall directory tree. This suffices
2396 for about 300,000 files of normal name length. If the limit gets
2397 exceeded, a FAILURE event will be issued and the ISO production
2398 will not happen.
2399 -rockridge "on"|"off"
2401 Mode "off" disables production of Rock Ridge information for the
2402 ISO 9660 file objects. The multi-session capabilities of xorriso
2403 depend much on the naming fidelity of Rock Ridge. So it is
2404 strongly discouraged to deviate from default setting "on".
2405 -compliance rule[:rule...]
2407 Adjust the compliance to specifications of ISO 9660/ECMA-119 and
2408 its contemporary extensions. In some cases it is worth to
2409 deviate a bit in order to circumvent bugs of the intended reader
2410 system or to get unofficial extra features.
2411 There are several adjustable rules which have a keyword each. If
2412 they are mentioned with this command then their rule gets added
2413 to the relaxation list. This list can be erased by rules
2414 "strict" or "clear". It can be reset to its start setting by
2415 "default". All of the following relaxation rules can be revoked
2416 individually by appending "_off". Like "deep_paths_off".
2417 Rule keywords are:
2418 "iso_9660_level="number chooses level 1 with ECMA-119 names of
2419 the form 8.3 and -file_size_limit <= 4g - 1, or level 2 with
2420 ECMA-119 names up to length 32 and the same -file_size_limit, or
2421 level 3 with ECMA-119 names up to length 32 and -file_size_limit
2422 >= 400g -200k. If necessary -file_size_limit gets adjusted.
2423 "allow_dir_id_ext" allows ECMA-119 names of directories to have
2424 a name extension as with other file types. It does not force
2425 dots and it omits the version number, though. This is a bad
2426 tradition of mkisofs which violates ECMA-119. Especially ISO
2427 level 1 only allows 8 characters in a directory name and not
2428 8.3.
2429 "omit_version" does not add versions (";1") to ECMA-119 and
2430 Joliet file names.
2431 "only_iso_version" does not add versions (";1") to Joliet file
2432 names.
2433 "deep_paths" allows ECMA-119 file paths deeper than 8 levels.
2434 "long_paths" allows ECMA-119 file paths longer than 255
2435 characters.
2436 "long_names" allows up to 37 characters with ECMA-119 file
2437 names.
2438 "no_force_dots" does not add a dot to ECMA-119 file names which
2439 have none.
2440 "no_j_force_dots" does not add a dot to Joliet file names which
2441 have none.
2442 "lowercase" allows lowercase characters in ECMA-119 file names.
2443 "7bit_ascii" allows nearly all 7-bit characters in ECMA-119 file
2444 names. Not allowed are 0x0 and '/'. If not "lowercase" is
2445 enabled, then lowercase letters get converted to uppercase.
2446 "full_ascii" allows all 8-bit characters except 0x0 and '/' in
2447 ECMA-119 file names.
2448 "untranslated_names" might be dangerous for inadverted reader
2449 programs which rely on the restriction to at most 37 characters
2450 in ECMA-119 file names. This rule allows ECMA-119 file names up
2451 to 96 characters with no character conversion. If a file name
2452 has more characters, then image production will fail
2453 deliberately.
2454 "untranslated_name_len="number enables untranslated_names with a
2455 smaller limit for the length of file names. 0 disables this
2456 feature, -1 chooses maximum length limit, numbers larger than 0
2457 give the desired length limit.
2458 "joliet_long_names" allows Joliet leaf names up to 103
2459 characters rather than 64.
2460 "joliet_long_paths" allows Joliet paths longer than 240
2461 characters.
2462 "joliet_utf16" encodes Joliet names in UTF-16BE rather than
2463 UCS-2. The difference is with characters which are not present
2464 in UCS-2 and get encoded in UTF-16 by 2 words of 16 bit each.
2465 Both words then stem from a reserved subset of UCS-2.
2466 "always_gmt" stores timestamps in GMT representation with
2467 timezone 0.
2468 "rec_mtime" records with non-RockRidge directory entries the
2469 disk file's mtime and not the creation time of the image. This
2470 applies to the ECMA-119 tree (plain ISO 9660), to Joliet, and to
2471 ISO 9660:1999. "rec_mtime" is default. If disabled, it gets
2472 automatically re-enabled by -as mkisofs emulation when a
2473 pathspec is encountered.
2474 "new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux
2475 but not for older FreeBSD or for Solaris). This implies
2476 "aaip_susp_1_10_off" which may be changed by subsequent
2477 "aaip_susp_1_10".
2478 Default is "old_rr" which uses Rock Ridge version 1.10. This
2479 implies also "aaip_susp_1_10" which may be changed by subsequent
2480 "aaip_susp_1_10_off".
2481 "aaip_susp_1_10" allows AAIP to be written as unofficial
2482 extension of RRIP rather than as official extension under
2483 SUSP-1.12.
2484 "no_emul_toc" saves 64 kB with the first session on overwritable
2485 media but makes the image incapable of displaying its session
2486 history.
2487 "iso_9660_1999" causes the production of an additional directory
2488 tree compliant to ISO 9660:1999. It can record long filenames
2489 for readers which do not understand Rock Ridge.
2490 "old_empty" uses the old way of of giving block addresses in the
2491 range of [0,31] to files with no own data content. The new way
2492 is to have a dedicated block to which all such files will point.
2493 "max_ce_entries="number sets the maximum number of SUSP CE
2494 entries and thus continuation areas. Each continuation area can
2495 hold at most 2048 bytes of SUSP data (Rock Ridge or AAIP). The
2496 first area can be smaller. There might be some waste at the end
2497 of each area. When the maximum number is exceeded during ISO
2498 filesystem production then either xattr and ACL get dropped from
2499 the affected file or an error gets reported and image production
2500 is prevented.
2501 Linux silently ignores a file when encountering its 32th CE
2502 entry. (Workaround is to mount the filesystem with option
2503 "norock".) So the default setting is 31. Minimum is 1, maximum
2504 is 100000. If a limit higher than 31 is chosen and 31 gets
2505 surpassed, then a warning message gets reported.
2506 "max_ce_drop="mode sets the behavior when the limit of
2507 max_ce_entries= is surpassed. Mode "off" causes an error message
2508 and prevents image production. Mode "xattr" and "xattr_acl"
2509 report a warning, delete from the affected file all xattr of
2510 namespaces other than "isofs", and then try again. If this
2511 still surpasses the limit, then mode "xattr_acl" deletes all ACL
2512 from the file and retries. If this still surpasses the limit,
2513 then an error message gets reported and image production is
2514 prevented.
2515 Default setting is
2516 "clear:iso_9660_level=3:only_iso_version:deep_paths:long_paths:
2517 no_j_force_dots:always_gmt:rec_mtime:old_rr:max_ce_entries=31:
2518 max_ce_drop=xattr_acl"
2519 Note: The term "ECMA-119 name" means the plain ISO 9660 names
2520 and attributes which get visible if the reader ignores Rock
2521 Ridge.
2522 -rr_reloc_dir name
2524 Specify the name of the relocation directory in which deep
2525 directory subtrees shall be placed if -compliance is set to
2526 "deep_paths_off" or "long_paths_off". A deep directory is one
2527 that has a chain of 8 parent directories (including root) above
2528 itself, or one that contains a file with an ECMA-119 path of
2529 more than 255 characters.
2530 The overall directory tree will appear originally deep when
2531 interpreted as Rock Ridge tree. It will appear as re-arranged if
2532 only ECMA-119 information is considered.
2533 The default relocation directory is the root directory. By
2534 giving a non-empty name with -rr_reloc_dir, a directory in the
2535 root directory may get this role. If that directory does not
2536 already exist at -commit time, then it will get created and
2537 marked for Rock Ridge as relocation artefact. At least on
2538 GNU/Linux it will not be displayed in mounted Rock Ridge images.
2539 The name must not contain a '/' character and must not be longer
2540 than 255 bytes.
2541 -volid text
2543 Specify the volume ID, which most operating systems will
2544 consider to be the volume name of the image or medium.
2545 xorriso accepts any text up to 32 characters, but according to
2546 rarely obeyed specs stricter rules apply:
2547 ECMA-119 demands ASCII characters out of [A-Z0-9_]. Like:
2548 "IMAGE_23"
2549 Joliet allows 16 UCS-2 characters. Like:
2550 "Windows name"
2551 Be aware that the volume id might get used automatically as the
2552 name of the mount point when the medium is inserted into a
2553 playful computer system.
2554 If an ISO image gets loaded while the volume ID is set to
2555 default "ISOIMAGE" or to "", then the volume ID of the loaded
2556 image will become the effective volume id for the next write
2557 run. But as soon as command -volid is performed afterwards, this
2558 pending ID is overridden by the new setting.
2559 Consider this when setting -volid "ISOIMAGE" before executing
2560 -dev, -indev, or -rollback. If you insist in -volid "ISOIMAGE",
2561 set it again after those commands.
2562 -volset_id text
2564 Set the volume set ID string to be written with the next
2565 -commit. Permissible are up to 128 characters. This setting
2566 gets overridden by image loading.
2567 -publisher text
2569 Set the publisher ID string to be written with the next -commit.
2570 This may identify the person or organisation who specified what
2571 shall be recorded. Permissible are up to 128 characters. This
2572 setting gets overridden by image loading.
2573 -application_id text
2575 Set the application ID string to be written with the next
2576 -commit. This may identify the specification of how the data are
2577 recorded. Permissible are up to 128 characters. This setting
2578 gets overridden by image loading.
2579 The special text "@xorriso@" gets converted to the ID string of
2580 xorriso which is normally written as -preparer_id. It is a wrong
2581 tradition to write the program ID as -application_id.
2582 -system_id text
2584 Set the system ID string to be written with the next -commit.
2585 This may identify the system which can recognize and act upon
2586 the content of the System Area in image blocks 0 to 15.
2587 Permissible are up to 32 characters. This setting gets
2588 overridden by image loading.
2589 -volume_date type timestring
2591 Set one of the four overall timestamps for subsequent image
2592 writing. Available types are:
2593 "c" time when the volume was created.
2594 "m" time when volume was last modified.
2595 "x" time when the information in the volume expires.
2596 "f" time since when the volume is effectively valid.
2597 "all_file_dates" sets mtime, atime, and ctime of all files and
2598 directories to the given time. If the timestring is
2599 "set_to_mtime", then the atime and ctime of each file and
2600 directory get set to the value found in their mtime.
2601 These actions stay delayed until actual ISO production begins.
2602 Up to then they can be revoked by "all_file_dates" with empty
2603 timestring or timestring "default".
2604 The timestamps of the El Torito boot catalog file get refreshed
2605 when the ISO is produced. They can be influenced by "uuid".
2606 "uuid" sets a timestring that overrides "c" and "m" times
2607 literally and sets the time of the El Torito boot catalog. It
2608 must consist of 16 decimal digits which form YYYYMMDDhhmmsscc,
2609 with YYYY between 1970 and 2999. Time zone is GMT. It is
2610 supposed to match this GRUB line:
2611 search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc
2612 E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
2613 Timestrings for the other types may be given as with command
2614 -alter_date. Some of them are prone to timezone computations.
2615 The timestrings "default" or "overridden" cause default
2616 settings: "c" and "m" will show the current time of image
2617 creation. "x" and "f" will be marked as insignificant. "uuid"
2618 will be deactivated.
2619 At -commit time, some timestamps get set to the maximum value of
2620 effectively written volume creation and modification time: El
2621 Torito boot catalog, HFS+ superblock, ECMA-119 file modification
2622 time if -compliance "no_rec_mtime". The isohybrid MBR id is
2623 computed from "uuid" if given, else from the effective volume
2624 modification date.
2625 -copyright_file text
2627 Set the copyright file name to be written with the next -commit.
2628 This should be the ISO 9660 path of a file in the image which
2629 contains a copyright statement. Permissible are up to 37
2630 characters. This setting gets overridden by image loading.
2631 -abstract_file text
2633 Set the abstract file name to be written with the next -commit.
2634 This should be the ISO 9660 path of a file in the image which
2635 contains an abstract statement about the image content.
2636 Permissible are up to 37 characters. This setting gets
2637 overridden by image loading.
2638 -biblio_file text
2640 Set the biblio file name to be written with the next -commit.
2641 This should be the ISO 9660 path of a file in the image which
2642 contains bibliographic records. Permissible are up to 37
2643 characters. This setting gets overridden by image loading.
2644 -preparer_id text
2646 Set the preparer ID string to be written with the next -commit.
2647 This may identify the person or other entity which controls the
2648 preparation of the data which shall be recorded. Normally this
2649 should be the ID of xorriso and not of the person or program
2650 which operates xorriso. Please avoid to change it. Permissible
2651 are up to 128 characters.
2652 The special text "@xorriso@" gets converted to the ID string of
2653 xorriso which is default at program startup.
2654 Unlike other ID strings, this setting is not influenced by image
2655 loading.
2656 -application_use character|0xXY|disk_path
2658 Specify the content of the Application Use field which can take
2659 at most 512 bytes.
2660 If the parameter of this command is empty, then the field is
2661 filled with 512 0-bytes. If it is a single character, then it
2662 gets repeated 512 times. If it begins by "0x" followed by two
2663 hex digits [0-9a-fA-F], then the digits are read as byte value
2664 which gets repeated 512 times.
2665 Any other parameter text is used as disk_path to open a data
2666 file and to read up to 512 bytes from it. If the file is smaller
2667 than 512 bytes, then the remaining bytes in the field get set to
2668 binary 0.
2669 This setting is not influenced by image loading.
2670 -out_charset character_set_name
2672 Set the character set to which file names get converted when
2673 writing an image. See paragraph "Character sets" for more
2674 explanations. When loading the written image after -commit the
2675 setting of -out_charset will be copied to -in_charset.
2676 -uid uid
2678 User id to be used for all files when the new ISO tree gets
2679 written to media.
2680 -gid gid
2682 Group id to be used for all files when the new ISO tree gets
2683 written to media.
2684 -zisofs parameter[:parameters]
2686 Set global parameters for zisofs compression. This data format
2687 is recognized and transparently uncompressed by some Linux
2688 kernels. It is to be applied via command -set_filter with
2689 built-in filter "--zisofs".
2690 Note: This command is only permitted while no --zisofs filters
2691 are applied to any files.
2692 Parameters are:
2693 "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow
2694 "block_size="32k|64k|128k sets the size of version 1
2695 compression blocks.
2696 "by_magic=on" enables an expensive test at image generation
2697 time which checks files from disk whether they already are
2698 zisofs compressed, e.g. by program mkzftree. "by_magic=v2"
2699 enables processing of already zisofs2 compressed files
2700 additionally to those of zisofs version 1. "by_magic=off"
2701 disables both.
2702 "version_2="off|as_needed|on controls compression by
2703 experimental version zisofs2 which can encode files of size 4
2704 GiB or larger. The Linux kernel (as of 5.9) does not yet know
2705 this format and will complain like
2706 isofs: Unknown ZF compression algorithm: PZ
2707 The files will then appear in their compressed form with zisofs2
2708 header, block pointer list, and compressed data.
2709 zisofs2 is recognized by xorriso in files from loaded images and
2710 gets equipped with --zisofs-decode filters, unless restrictions
2711 on the number of block pointers prevent this.
2712 Mode "off" restricts compression to files smaller than 4 GiB
2713 uncompressed size. Mode "as_needed" uses zisofs2 for larger
2714 files. Mode "on" uses zisofs2 for all zisofs compressed files.
2715 "susp_z2="off|on controls production of SUSP entries "Z2"
2716 instead of "ZF" with zisofs2 compressed files. Unaware Linux
2717 kernels are supposed to silently ignore "Z2" entries.
2718 "block_size_v2="32k|64k|128k|256k|512k|1m sets the size of
2719 compression blocks for zisofs2.
2720 "bpt_target="-1|>0 sets a number of block pointers per file,
2721 which is considered low enough to justify a reduction of block
2722 size. If this number is larger than 0, then block sizes smaller
2723 than the settings of block_size= or block_size_v2= are tried
2724 whether they yield not more block pointers than the given
2725 number. If so, the smallest suitable block size is applied.
2726 The inavoidable final block pointer counts. E.g. a file of 55
2727 KiB has 3 block pointers if block size is 32k, and 2 block
2728 pointers with block size 64k.
2729 bpt_target=-1 disables this automatic block size adjustment.
2730 "max_bpt="1k...128g sets the limit for the overall allocated
2731 block pointer memory. Block pointers occupy virtual memory while
2732 a file gets uncompressed and while a file, which shall be
2733 compressed, waits for ISO filesystem creation.
2734 One pointer occupies 8 bytes of memory and governs block_size or
2735 block_size_v2 uncompressed bytes. I.e. with block size 128k, 1m
2736 of block pointer memory suffices for at most 16g of uncompressed
2737 file size. Each file consumes one end block pointer,
2738 independently of the file size. Partially filled end blocks may
2739 further reduce the effective payload.
2740 In case of overflow of the max_bpt limit while adding
2741 compression filters the program tries to go on by discarding all
2742 buffered block pointers of previously added --zisofs filters.
2743 From then on all newly added filters will discard their block
2744 pointers immediately after being added. Discarded block
2745 pointers cause an additional read and compression run of the
2746 input file during the production of the ISO filesystem.
2747 "max_bpt_f="1k...128g sets the limit for the memory size of the
2748 block pointer list of a single file. max_bpt_f is never larger
2749 than max_bpt. If either is set to violate this rule, the other
2750 gets set to the same value. If both values are the same before
2751 a change by max_bpt= or max_bpt_f=, then both limits stick
2752 together unless the limit is decreased by max_bpt_f=.
2753 "bpt_free_ratio="-1|0.0...1.0 sets a threshold for switching to
2754 block pointer discarding during compression. If less than the
2755 given fraction of the max_bpt_f= memory is free, then block
2756 pointers of compression filters get discarded immediately after
2757 being added. Value -1 disables this feature.
2758 "default" is the same as "level=6:block_size=32k:by_magic=off:
2759 version_2=off:block_size_v2=128k:susp_z2=off:max_bpt=256m:max_bpt_f=256m:
2760 bpt_free_ratio=-1".
2761 -speed code|number[k|m|c|d|b]
2763 Set the burn speed. Default is "max" (or "0") = maximum speed as
2764 announced by the drive. Further special speed codes are:
2765 "min" (or "-1") selects minimum speed as announced by the drive.
2766 "none" avoids to send a speed setting command to the drive
2767 before burning begins.
2768 Speed can be given in media dependent numbers or as a desired
2769 throughput per second in MMC compliant kB (= 1000) or MB (= 1000
2770 kB). Media x-speed factor can be set explicitly by "c" for CD,
2771 "d" for DVD, "b" for BD, "x" is optional.
2772 Example speeds:
2773 706k = 706kB/s = 4c = 4xCD
2774 5540k = 5540kB/s = 4d = 4xDVD
2775 If there is no hint about the speed unit attached, then the
2776 medium in the -outdev will decide. Default unit is CD = 176.4k.
2777 MMC drives usually activate their own idea of speed and take the
2778 speed value given by the burn program only as upper limit for
2779 their own decision.
2780 -stream_recording "on"|"off"|"full"|"data"|number
2782 Setting "on" tries to circumvent the management of defects on
2783 DVD-RAM, BD-RE, or BD-R. Defect management keeps partly damaged
2784 media usable. But it reduces write speed to half nominal speed
2785 even if the medium is in perfect shape. For the case of
2786 flawless media, one may use -stream_recording "on" to get full
2787 speed.
2788 "full" tries full speed with all write operations, whereas "on"
2789 does this only above byte address 32s. One may give a number of
2790 at least 16s in order to set an own address limit.
2791 "data" causes full speed to start when superblock and directory
2792 entries are written and writing of file content blocks begins.
2793 -dvd_obs "default"|"32k"|"64k"|"obs_pad"|"bdr_obs_exempt"
2795 GNU/Linux specific: Set the number of bytes to be transmitted
2796 with each write operation to DVD or BD media. A number of 64 KB
2797 may improve throughput with bus systems which show latency
2798 problems. The default depends on media type, on command
2799 -stream_recording , and on compile time options.
2800 On all systems: "obs_pad" pads the data of the last write
2801 operation of a DVD-R[W] DAO session or BD-R session up to the
2802 full size of an output chunk. This padding has to be applied
2803 automatically to the other DVD and BD media types, where it
2804 causes e.g. ISO images to have trailing unclaimed blocks.
2805 Whether it is applied automatically to BD-R depends on
2806 "bdr_obs_exempt". "obs_pad" can be disabled by "no_obs_pad".
2807 "bdr_obs_exempt" exempts BD-R media from automatic unconditional
2808 transaction end padding, provided that this padding is not
2809 requested by "obs_pad" and that no stream_recording is
2810 requested. "bdr_obs_exempt" can be disabled by "no_obs_exempt".
2811 This is a new feature introduced with version 1.5.6. It might
2812 become default in later versions.
2813 -modesty_on_drive parameter[:parameters]
2815 Control whether the drive buffer shall be kept from getting
2816 completely filled. Parameter "on" (or "1") keeps the program
2817 from trying to write to the burner drive while its buffer is in
2818 danger to be filled over a given limit. If this limit is
2819 exceeded then the program will wait until the filling reaches a
2820 given low percentage value.
2821 This can ease the load on operating system and drive controller
2822 and thus help with achieving better input bandwidth if disk and
2823 burner are not on independent controllers (like hda and hdb). It
2824 may also help with throughput problems of simultaneous burns on
2825 different burners with Linux kernels like 3.16, if one has
2826 reason not to fix the problem by -scsi_dev_family "sg". On the
2827 other hand it increases the risk of buffer underflow and thus
2828 reduced write speed.
2829 Some burners are not suitable because they report buffer fill
2830 with granularity too coarse in size or time, or expect their
2831 buffer to be filled to the top before they go to full speed.
2832 Parameters "off" or "0" disable this feature.
2833 The threshold for beginning to wait is given by parameter
2834 "max_percent=". Parameter "min_percent=" defines the threshold
2835 for resuming transmission. Percentages are permissible in the
2836 range of 25 to 100. Numbers in this range without a prepended
2837 name are interpreted as "on:min_percent=".
2838 E.g.: -modesty_on_drive 75
2839 The optimal values depend on the buffer behavior of the drive.
2840 Parameter "timeout_sec=" defines after which time of
2841 unsuccessful waiting the modesty shall be disabled because it
2842 does not work.
2843 Parameter "min_usec=" defines the initial sleeping period in
2844 microseconds. If the drive buffer appears to be too full for
2845 sending more data, the program will wait the given time and
2846 inquire the buffer fill state again. If repeated inquiry shows
2847 not enough free space, the sleep time will slowly be increased
2848 to what parameter "max_usec=" defines.
2849 Parameters, which are not mentioned with a -modesty_on_drive
2850 command, stay unchanged. Default is:
2851 -modesty_on_drive off:min_percent=90:max_percent=95:
2852 timeout_sec=120:min_usec=5000:max_usec=25000
2853 -use_immed_bit "on"|"off"|"default"
2855 Control whether several long lasting SCSI commands shall be
2856 executed with the Immed bit, which makes the commands end early
2857 while the drive operation is still going on. xorriso then
2858 inquires progress indication until the drive reports to be ready
2859 again. If this feature is turned off, then blanking and
2860 formatting will show no progress indication.
2861 It may depend on the operating system whether -use_immed_bit is
2862 set to "off" by default. Command -status will tell by appending
2863 "/on" or "/off" if a drive has already been acquired and
2864 -use_immed_bit is currently set to "default". Command
2865 -use_immed_bit tolerates and ignores such appended text.
2866 -stdio_sync "on"|"off"|"end"|number
2868 Set the number of bytes after which to force output to stdio:
2869 pseudo drives. This forcing keeps the memory from being clogged
2870 with lots of pending data for slow devices. Default "on" is the
2871 same as "16m". Forced output can be disabled by "off", or be
2872 delayed by "end" until all data are produced. If a number is
2873 chosen, then it must be at least 64k.
2874 -dummy "on"|"off"
2876 If "on" then simulate burning or refuse with FAILURE event if no
2877 simulation is possible, do neither blank nor format.
2878 -fs number["k"|"m"]
2880 Set the size of the fifo buffer which smoothens the data stream
2881 from ISO image generation to media burning. Default is 4 MiB,
2882 minimum 64 kiB, maximum 1 GiB. The number may be followed by
2883 letter "k" or "m" which means unit is kiB (= 1024) or MiB (=
2884 1024 kiB).
2885 -close "on"|"off"|"as_needed"
2887 If -close is set to "on" then mark the written medium as not
2888 appendable any more. This will have no effect on overwritable
2889 media types. Setting "on" is the contrary of cdrecord option
2890 -multi, and is one aspect of growisofs option -dvd-compat.
2891 If set to "off" then keep the medium writable for an appended
2892 session.
2893 If set to "as_needed" then use "on" only if "off" is predicted
2894 to fail with the given medium and its state.
2895 Not all drives correctly recognize fast-blanked DVD-RW which
2896 need "on". If there is well founded suspicion that a burn run
2897 failed due to -close "off", then -close "as_needed" causes a
2898 re-try with "on".
2899 Note that emulation command -as "cdrecord" temporarily overrides
2900 the current setting of -close by its own default -close "on" if
2901 its option -multi is missing.
2902 -write_type "auto"|"tao"|"sao/dao"
2904 Set the write type for the next burn run. "auto" will select SAO
2905 with blank CD media, DAO with blank DVD-R[W] if -close is "on",
2906 and elsewise CD TAO or the equivalent write type of the
2907 particular DVD/BD media. Choosing TAO or SAO/DAO explicitly
2908 might cause the burn run to fail if the desired write type is
2909 not possible with the given media state.
2910 -padding number["k"|"m"]|"included"|"appended"
2912 Append the given number of extra bytes to the image stream.
2913 This is a traditional remedy for a traditional bug in block
2914 device read drivers. Needed only for CD recordings in TAO mode.
2915 Since one can hardly predict on what media an image might end
2916 up, xorriso adds the traditional 300k of padding by default to
2917 all images.
2918 For images which will never get to a CD it is safe to use
2919 -padding 0 .
2920 Normally padding is not written as part of the ISO image but
2921 appended after the image end. This is -padding mode "appended".
2922 Emulation command -as "mkisofs" and command -jigdo cause padding
2923 to be written as part of the image. The same effect is achieved
2924 by -padding mode "included".
2925 Bootable ISO images:
2927 Contrary to published specifications many BIOSes will load an El Torito
2929 record from the first session on media and not from the last one, which
2930 gets mounted by default. This makes no problems with overwritable
2931 media, because they appear to inadverted readers as one single session.
2932 But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that
2933 the whole bootable system has to reside already in the first session
2934 and that the last session still has to bear all files which the booted
2935 system expects after mounting the ISO image.
2936 If a boot image from ISOLINUX or GRUB is known to be present on media
2937 then it is advised to patch it when a follow-up session gets written.
2938 But one should not rely on the capability to influence the bootability
2939 of the existing sessions, unless one can assume overwritable media.
2940 Normally the boot images are data files inside the ISO filesystem. By
2941 special path "--interval:appended_partition_NNN:all::" it is possible
2942 to refer to an appended partition. The number NNN gives the partition
2943 number as used with the corresponding command -append_partition. E.g.:
2944 -append_partition 2 0xef /tmp/efi.img
2945 -boot_image any efi_path=--interval:appended_partition_2:all::
2946 There are booting mechanisms which do not use an El Torito record but
2947 rather start at the first bytes of the image: PC-BIOS MBR or EFI GPT
2948 for hard-disk-like devices, APM partition entries for Macs which expect
2949 HFS+ boot images, MIPS Volume Header for old SGI computers, DEC Boot
2950 Block for old MIPS DECstation, SUN Disk Label for SPARC machines, HP-PA
2951 boot sector for HP PA-RISC machines, DEC Alpha SRM boot sector for old
2952 DEC Alpha machines.
2953 Several of the following commands expect disk paths as input but also
2955 accept description strings for the libisofs interval reader, which is
2956 able to cut out data from disk files or -indev and to zeroize parts of
2957 the content: command -append_partition, boot specs system_area=,
2958 grub2_mbr=, prep_boot_part=, efi_boot_part=.
2959 The description string consists of the following components, separated
2960 by colon ':'
2961 "--interval:"Flags":"Interval":"Zeroizers":"Source
2962 The component "--interval" states that this is not a plain disk path
2963 but rather an interval reader description string. The component Flags
2964 modifies the further interpretation:
2965 "local_fs" demands to read from a file depicted by the path in Source.
2966 "imported_iso" demands to read from the -indev. This works only if
2967 -outdev is not the same as -indev. The Source component is ignored.
2968 "appended_partition_NNN" with a decimal number NNN works only for
2969 -boot_image bootspecs which announce El Torito boot image paths:
2970 bin_path=, efi_path=. The number gives the partition number as used
2971 with the corresponding command -append_partition.
2972 The component Interval consists of two byte address numbers separated
2973 by a "-" character. E.g. "0-429" means to read bytes 0 to 429.
2974 The component Zeroizers consists of zero or more comma separated
2975 strings. They define which part of the read data to zeroize. Byte
2976 number 0 means the byte read from the Interval start address. Each
2977 string may be one of:
2978 "zero_mbrpt" demands to zeroize the MBR partition table if bytes 510
2979 and 511 bear the MBR signature 0x55 0xaa.
2980 "zero_gpt" demands to check for a GPT header in bytes 512 to 1023, to
2981 zeroize it and its partition table blocks.
2982 "zero_apm" demands to check for an APM block 0 and to zeroize its
2983 partition table blocks.
2984 Start_byte"-"End_byte demands to zeroize the read-in bytes beginning
2985 with number Start_byte and ending after End_byte.
2986 The component Source is the file path with flag "local_fs", and ignored
2987 with flag "imported_iso".
2988 Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning
2989 multiplication by {1024, 1024k, 1024m, 1024g, 2048, 512}. A scaled
2990 value end number depicts the last byte of the scaled range.
2991 E.g. "0d-0d" is "0-511".
2992 Examples:
2993 "local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso"
2994 "imported_iso:45056d-47103d::"
2995 -boot_image "any"|"isolinux"|"grub"
2997 "discard"|"keep"|"patch"|"replay"|"show_status"|
2998 bootspec|"next"
2999 Define the equipment of the emerging filesystem with boot entry
3000 points.
3001 With systems which boot via BIOS or EFI this is a set of El
3002 Torito boot images, possibly MBR boot code, and possibly
3003 partition tables of type MBR, GPT, or APM. Such file sets get
3004 produced by boot loader systems like ISOLINUX or GRUB.
3005 Each -boot_image command has two parameters: type and setting.
3007 More than one -boot_image command may be used to define the
3008 handling of one or more boot images. Sequence matters.
3009 Types isolinux and grub care for known peculiarities. Type any
3010 makes no assumptions about the origin of the boot images.
3011 When loading an ISO filesystem, system area and El Torito boot
3013 images get loaded, too. The default behavior is not to write
3014 loaded El Torito boot images and to write the loaded system area
3015 content without alterations.
3016 discard gives up the El Torito boot catalog and its boot images.
3017 regardless whether loaded from an ISO filesystem or defined by
3018 commands. Any BIOS or EFI related boot options get revoked.
3019 Nevertheless, loaded system area data stay valid. If desired,
3020 they have to be erased by
3021 -boot_image any system_area=/dev/zero
3022 keep keeps or copies El Torito boot images unaltered and writes
3023 a new catalog.
3024 patch applies patching to existing El Torito boot images if they
3025 seem to bear a boot info table.
3026 A boot info table needs to be patched when the boot image gets
3027 newly introduced into the ISO image or if an existing image gets
3028 relocated. This is automatically done if type "isolinux" or
3029 "grub" is given, but not with "any".
3030 If patching is enabled, then boot images from previous sessions
3031 will be checked whether they seem to bear a boot info table. If
3032 not, then they stay unpatched. This check is not infallible. So
3033 if you do know that the images need no patching, use "any"
3034 "keep". "grub" "patch" will not patch EFI images
3035 (platform_id=0xef).
3036 replay is a more modern version of "patch", which not only cares
3037 for existing El Torito boot equipment but also for the
3038 recognizable boot provisions in the System Area. It discards any
3039 existing -boot_image setting and executes the commands proposed
3040 by command -report_el_torito "cmd".
3041 This action will only succeed if the file objects mentioned in
3042 the output of command -report_el_torito "cmd" are still
3043 available. Do not remove or rename boot image files after
3044 -indev.
3045 Drop unknown El Torito: -boot_image "any" "discard"
3046 Maintain recognizable stuff: -boot_image "any" "replay"
3047 El Torito only for GRUB: -boot_image "grub" "patch"
3048 El Torito only for ISOLINUX: -boot_image "isolinux" "patch"
3049 show_status will print what is known about the loaded boot
3050 images and their designated fate.
3051 A bootspec is a word of the form name=value. It is used to
3053 describe the parameters of a boot feature. The names "dir",
3054 "bin_path", "efi_path" lead to El Torito bootable images. Name
3055 "system_area" activates a given file as MBR or other disk
3056 header.
3057 On all media types this is possible within the first session. In
3058 further sessions an existing boot image can get replaced by a
3059 new one, but depending on the media type this may have few
3060 effect at boot time. See above.
3061 El Torito boot images have to be added to the ISO image by
3062 normal means (image loading, -map, -add, ...). In case of
3063 ISOLINUX the files should reside either in ISO image directory
3064 /isolinux or in /boot/isolinux . In that case it suffices to
3065 use as bootspec the text "dir=/isolinux" or
3066 "dir=/boot/isolinux". E.g.:
3067 -boot_image isolinux dir=/boot/isolinux
3068 which bundles these individual settings:
3069 -boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
3070 -boot_image isolinux cat_path=/boot/isolinux/boot.cat
3071 -boot_image isolinux load_size=2048
3072 -boot_image any boot_info_table=on
3073 An El Torito boot catalog file gets inserted into the ISO image
3074 with address cat_path= with the first -boot_image "any" "next"
3075 or at -commit time. It is subject to normal -overwrite and
3076 -reassure processing if there is already a file with the same
3077 name. The catalog lists the boot images and is read by the boot
3078 facility to choose one of the boot images. But it is not
3079 necessary that it appears in the directory tree at all. One may
3080 hide it in all trees by cat_hidden=on. Other possible values
3081 are "iso_rr", "joliet", "hfsplus", and the default "off". The
3082 timestamps of the boot catalog file are refreshed at commit
3083 time. Command -volume_date "uuid" can be used to set their
3084 value.
3085 bin_path= depicts an El Torito boot image file, a binary program
3086 which is to be started by the hardware boot facility (e.g. the
3087 BIOS) at boot time.
3088 efi_path= depicts an El Torito boot image file that is ready for
3089 EFI booting. This is normally a FAT filesystem image not larger
3090 than 65535 blocks of 512 bytes (= 32 MiB - 512). Its load_size
3091 is determined automatically, no boot info table gets written, no
3092 boot medium gets emulated, platform_id is 0xef.
3093 emul_type= can be one of "no_emulation", "hard_disk",
3094 "diskette". It controls the boot medium emulation code of a
3095 boot image. The default "no_emulation" is suitable for
3096 ISOLINUX, GRUB, FreeBSD cdboot.
3097 load_size= is a value which depends on the boot image. Default
3098 is 2048 which matches the expectations of most boot images. The
3099 special value "full" means the full size of the boot image file
3100 rounded up to a multiple of 2048 bytes. Maximum is 33,552,384
3101 bytes.
3102 boot_info_table=on causes address patching to bytes 8 to 63 of
3103 the boot image which is given by "any" "bin_path=".
3104 "boot_info_table=off" disables this patching.
3105 grub2_boot_info=on causes address patching to byte 2548 of the
3106 boot image which is given by "any" "bin_path=". The address is
3107 written as 64 bit little-endian number. It is the 2KB block
3108 address of the boot image content, multiplied by 4, and then
3109 incremented by 5. "grub2_boot_info=off" disables this patching.
3110 platform_id= defines by a hexadecimal or decimal number the
3111 Platform ID of the boot image. "0x00" is 80x86 PC-BIOS, "0x01"
3112 is PowerPC, "0x02" is Mac, "0xef" is EFI (decimal "239").
3113 id_string=text|56_hexdigits defines the ID string of the boot
3114 catalog section where the boot image will be listed. If the
3115 value consists of 56 characters [0-9A-Fa-f] then it is converted
3116 into 28 bytes, else the first 28 characters become the ID
3117 string. The ID string of the first boot image becomes the
3118 overall catalog ID. It is limited to 24 characters. Other
3119 id_strings become section IDs.
3120 sel_crit=hexdigits defines the Selection Criteria of the boot
3121 image. Up to 20 bytes get read from the given characters
3122 [0-9A-Fa-f]. They get attributed to the boot image entry in the
3123 catalog.
3124 next ends the definition of a boot image and starts a new one.
3125 Any following -bootimage bootspecs will affect the new image.
3126 The first "next" discards loaded boot images and their catalog.
3127 system_area=disk_path copies at most 32768 bytes from the given
3128 disk file to the very start of the ISO image. This System Area
3129 is reserved for system dependent boot software, e.g. an MBR
3130 which can be used to boot from USB stick or hard disk.
3131 Other than an El Torito boot image, the file disk_path needs not
3132 to be added to the ISO image.
3133 -boot_image isolinux system_area= implies "partition_table=on".
3134 In this case, the disk path should lead to one of the SYSLINUX
3135 files isohdp[fp]x*.bin or to a file which was derived from one
3136 of those files. E.g. to the first 512 bytes from an ISOLINUX
3137 isohybrid ISO image.
3138 In this case, El Torito boot images (dir=, bin_path=, efi_path=)
3139 may be augmented by isolinux partition_entry=gpt_basdat or
3140 isolinux partition_entry=gpt_hfsplus, and by isolinux
3141 partition_entry=apm_hfsplus. The boot image will then be
3142 mentioned in an invalid GPT as Basic Data or GPT HFS+ partition,
3143 and in a valid APM as HFS+ partition. The first three GPT
3144 partitions will also be marked by MBR partitions. The MBR
3145 partition of type 0xEF is what actually is used by EFI firmware
3146 for booting from USB stick.
3147 In multi-session situations the existing System Area is
3148 preserved by default. In in this case, the special disk_path
3149 "." prevents reading of a disk file but nevertheless causes
3150 adjustments in the loaded system area data. Such adjustments may
3151 get ordered by -boot_image commands.
3152 -boot_image any gpt_disk_guid=value controls whether an emerging
3153 GPT shall get a randomly generated disk GUID or whether the GUID
3154 is supplied by the user. Value "random" is default. Value
3155 "volume_date_uuid" produces a low quality GUID from the value
3156 set by -volume_date "uuid".
3157 A string of 32 hex digits, or a RFC 4122 compliant GUID string
3158 may be used to set the disk GUID directly. UEFI prescribes the
3159 first three components of a RFC 4122 GUID string to be
3160 byte-swapped in the binary representation:
3161 E.g. gpt_disk_guid=2303cd2a-73c7-424a-a298-25632da7f446 equals
3162 gpt_disk_guid=2acd0323c7734a42a29825632da7f446
3163 The partition GUIDs get generated by minimally varying the disk
3164 GUID.
3165 -boot_image any part_like_isohybrid=on enables -boot_image
3166 isolinux partition_entry= even if no -boot_image isolinux
3167 system_area= is given. No MBR partition of type 0xee emerges,
3168 even if GPT gets produced. Gaps between GPT and APM partitions
3169 will not be filled by more partitions. Appended partitions get
3170 mentioned in APM if other APM partitions emerge.
3171 -boot_image any iso_mbr_part_type=number sets the partition type
3172 of the MBR partition which represents the ISO or at least
3173 protects it.
3174 Number may be 0x00 to 0xff. The text "default" re-enables the
3175 default types of the various occasions to create an ISO MBR
3176 partition. This is without effect if no such partition emerges
3177 by other settings or if the partition type is prescribed
3178 mandatorily like 0xee for GPT protective MBR or 0x96 for CHRP.
3179 If instead a type_guid is given by a 32-digit hex string like
3180 a2a0d0ebe5b9334487c068b6b72699c7 or by a structured text like
3181 EBD0A0A2-B9E5-4433-87C0-68B6B72699C7, then it will be used as
3182 partition type if the ISO filesystem appears as partition in
3183 GPT. In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be
3184 mapped to 0xef. Any other GUID will be mapped to 0x83.
3185 grub2_mbr=disk_path works like "any" system_area= with
3186 additional patching for modern GRUB MBRs. The content start
3187 address of the first boot image is converted to a count of 512
3188 byte blocks, and an offset of 4 is added. The result is written
3189 as 64 bit little-endian number to byte address 0x1b0.
3190 This feature can be revoked either by grub2_mbr= with empty disk
3191 path, or by submitting a disk_path via system_area=.
3192 partition_table=on causes a simple partition table to be written
3193 into bytes 446 to 511 of the System Area.
3194 With type "isolinux" it shows a partition that begins at byte 0
3195 and it causes the LBA of the first boot image to be written into
3196 the MBR. For the first session this works only if also
3197 "system_area=" and "bin_path=" or "dir=" is given.
3198 With types "any" and "grub" it shows a single partition which
3199 starts at byte 512 and ends where the ISO image ends. This
3200 works with or without system_area= or boot image.
3201 Bootspecs chrp_boot_part=, prep_boot_part=, and efi_boot_part=
3202 overwrite this entry in the MBR partition table.
3203 If types "isolinux" or "grub" are set to "patch", then
3204 "partition_table=on" is activated without new boot image. In
3205 this case the existing System Area gets checked whether it bears
3206 addresses and sizes as if it had been processed by
3207 "partition_table=on". If so, then those parameters get updated
3208 when the new System Area is written.
3209 Special "system_area=/dev/zero" causes 32k of NUL-bytes. Use
3210 this to discard an MBR which was loaded with the ISO image.
3211 appended_part_as=gpt marks partitions from -append_partition in
3212 GPT rather than in MBR. In this case the MBR shows a single
3213 partition of type 0xee which covers the whole output data.
3214 appended_part_as=mbr is the default. Appended partitions get
3215 marked in GPT only if GPT is produced because of other settings.
3216 If given explicitly, this clears setting "gpt" and "apm".
3217 Nevertheless "apm" may be added to "mbr".
3218 appended_part_as=apm marks partitions from -append_partition in
3219 APM additionally to "mbr" or "gpt".
3220 By default, appended partitions get marked in APM only if APM is
3221 produced because of other options together with
3222 part_like_isohybrid="on".
3223 chrp_boot_part=on causes a single partition in MBR which covers
3224 the whole ISO image and has type 0x96. This is not compatible
3225 with any other feature that produces MBR partition entries. It
3226 makes GPT unrecognizable.
3227 prep_boot_part=disk_path inserts the content of a data file into
3228 the image and marks it by an MBR partition of type 0x41. The
3229 parts of the ISO image before and after this partition will be
3230 covered by further MBR partitions. The data file is supposed to
3231 contain ELF executable code.
3232 efi_boot_part=disk_path inserts the content of a data file into
3233 the image and marks it by a GPT partition. If not
3234 chrp_boot_part=on, then the first partition in MBR will have
3235 type 0xee to announce the presence of GPT. The data file is
3236 supposed to contain a FAT filesystem.
3237 Instead of a disk_path, the word --efi-boot-image may be given.
3238 It exposes in GPT the content of the first El Torito EFI boot
3239 image as EFI system partition. EFI boot images are introduced by
3240 bootspec efi_path=. The affected EFI boot image cannot show up
3241 in HFS+ because it is stored outside the HFS+ partition.
3242 partition_offset=2kb_block_adr causes a partition table with a
3243 single partition that begins at the given block address. This is
3244 counted in 2048 byte blocks, not in 512 byte blocks. If the
3245 block address is non-zero then it must be at least 16. A
3246 non-zero partition offset causes two superblocks to be generated
3247 and two sets of directory trees. The image is then mountable
3248 from its absolute start as well as from the partition start.
3249 The offset value of an ISO image gets preserved when a new
3250 session is added. So the value defined here is only in effect
3251 if a new ISO image gets written.
3252 partition_hd_cyl=number gives the number of heads per cylinder
3253 for the partition table. 0 chooses a default value. Maximum is
3254 255.
3255 partition_sec_hd=number gives the number of sectors per head for
3256 the partition table. 0 chooses a default value. Maximum is 63.
3257 The product partition_sec_hd * partition_hd_cyl * 512 is the
3258 cylinder size. It should be divisible by 2048 in order to make
3259 exact alignment possible. With appended partitions and
3260 "appended_part_as=gpt" there is no limit for the number of
3261 cylinders. Else there may be at most 1024 of them. If the
3262 cylinder size is too small to stay below the limit, then
3263 appropriate values of partition_hd_cyl are chosen with
3264 partition_sec_hd 32 or 63. If the image is larger than
3265 8,422,686,720 bytes, then the cylinder size constraints cannot
3266 be fulfilled for MBR.
3267 partition_cyl_align=mode controls image size alignment to an
3268 integer number of cylinders. It is prescribed by isohybrid specs
3269 and it seems to please program fdisk. Cylinder size must be
3270 divisible by 2048. Images larger than 8,323,596,288 bytes
3271 cannot be aligned in MBR partition table.
3272 Mode "auto" is default. Alignment by padding happens only with
3273 "isolinux" "partition_table=on".
3274 Mode "on" causes alignment by padding with "partition_table=on"
3275 for any type. Mode "all" is like "on" but also pads up
3276 partitions from -append_partition to an aligned size.
3277 Mode "off" disables alignment for any type.
3278 mbr_force_bootable=mode enforces an MBR partition with
3279 "bootable/active" flag if options like partition_table= or
3280 grub2_mbr= indicate production of a bootable MBR. These options
3281 normally cause the flag to be set if there is an MBR partition
3282 of type other than 0xee or 0xef. If no such partition exists,
3283 then no bootflag is set, unless mbr_force_bootable="on" forces
3284 creation of a dummy partition of type 0x00 which covers only the
3285 first block of the ISO image.
3286 If no bootable MBR is indicated and a partition gets created by
3287 -append_partition, then mbr_force_bootable="on" causes a
3288 bootflag like it would do with a bootable MBR.
3289 gpt_iso_bootable=on causes bit 2 of the GPT partition flags to
3290 be set for the ISO 9660 partition if such a GPT partition
3291 emerges. This bit is specified as "Legacy BIOS bootable" but its
3292 true significance is unclear. Some GPT-aware BIOS might want to
3293 see it in some partition. Mode "off" revokes this setting.
3294 gpt_iso_not_ro=on causes bit 60 of the GPT partition flags to be
3295 not set for the ISO 9660 partition if such a GPT partition
3296 emerges. This bit is specified as "Read-only" and thus
3297 appropriate. But it is unusual in GPT disk partitions. Mode
3298 "off" revokes this setting and causes the read-only bit to be
3299 set.
3300 mips_path=iso_rr_path declares a data file in the image to be a
3301 MIPS Big Endian boot file and causes production of a MIPS Big
3302 Endian Volume Header. This is mutually exclusive with production
3303 of other boot blocks like MBR. It will overwrite the first 512
3304 bytes of any data provided by system_area=. Up to 15 boot files
3305 can be declared by mips_path=.
3306 mipsel_path=iso_rr_path declares a data file in the image to be
3307 the MIPS Little Endian boot file. This is mutually exclusive
3308 with other boot blocks. It will overwrite the first 512 bytes
3309 of any data provided by system_area=. Only a single boot file
3310 can be declared by mipsel_path=.
3311 sparc_label=text causes the production of a SUN Disk Label with
3312 the given text as ASCII label. Partitions 2 to 8 may be occupied
3313 by appended images. Partition 1 will always be the ISO image.
3314 See command -append_partition. The first 512 bytes of any data
3315 provided by system_area= will be overwritten.
3316 grub2_sparc_core=iso_rr_path causes the content address and size
3317 of the given file to be written after the SUN Disk Label. Both
3318 numbers are counted in bytes. The address is written as 64 bit
3319 big-endian number to byte 0x228. The size is written as 32 bit
3320 big-endian number to byte 0x230.
3321 hppa_cmdline=text sets the PALO command line for HP-PA. Up to
3322 1023 characters are permitted by default. With hppa_hdrversion=4
3323 the limit is 127.
3324 Note that the first five hppa_ bootspecs are mandatory, if any
3325 of the hppa_ bootspecs is used. Only hppa_hdrversion= is allowed
3326 to be missing.
3327 hppa_bootloader=iso_rr_path designates the given path as HP-PA
3328 bootloader file.
3329 hppa_kernel_32=iso_rr_path designates the given path as HP-PA 32
3330 bit kernel file.
3331 hppa_kernel_64=iso_rr_path designates the given path as HP-PA 64
3332 bit kernel file.
3333 hppa_ramdisk=iso_rr_path designates the given path as HP-PA RAM
3334 disk file.
3335 hppa_hdrversion=number chooses between PALO header version 5
3336 (default) and version 4. For the appropriate value see in PALO
3337 source code: PALOHDRVERSION.
3338 alpha_boot=iso_rr_path declares a data file in the image to be
3339 the DEC Alpha SRM Secondary Bootstrap Loader and causes
3340 production of a boot sector which points to it. This is
3341 mutually exclusive with production of other boot blocks like
3342 MBR.
3343 mips_discard, sparc_discard, hppa_discard, alpha_discard revoke
3344 any boot file declarations made for mips/mipsel, sparc, hppa, or
3345 alpha, respectively. This removes the ban on production of
3346 other boot blocks.
3347 hfsplus_serial=hexstring sets a string of 16 digits "0" to "9"
3348 and letters "a" to "f", which will be used as unique serial
3349 number of an emerging HFS+ filesystem.
3350 hfsplus_block_size=number sets the allocation block size to be
3351 used when producing HFS+ filesystems. Permissible are 512, 2048,
3352 or 0. The latter lets the program decide.
3353 apm_block_size=number sets the block size to be used when
3354 describing partitions by an Apple Partition Map. Permissible are
3355 512, 2048, or 0. The latter lets the program decide.
3356 Note that size 512 is not compatible with production of GPT, and
3357 that size 2048 will not be mountable -t hfsplus at least by
3358 older Linux kernels.
3359 -append_partition partition_number type_code disk_path
3361 Cause a prepared filesystem image to be appended to the ISO
3362 image and to be described by a partition table entry in a boot
3363 block at the start of the emerging ISO image. The partition
3364 entry will bear the size of the submitted file rounded up to the
3365 next multiple of 2048 bytes or to the next multiple of the
3366 cylinder size.
3367 Beware of subsequent multi-session runs. The appended partition
3368 will get overwritten.
3369 Partitions may be appended with boot block type MBR and with SUN
3370 Disk Label.
3371 With MBR:
3372 partition_number may be 1 to 4. Number 1 will put the whole ISO
3373 image into the unclaimed space before partition 1. So together
3374 with most xorriso MBR features, number 2 would be the most
3375 natural choice.
3376 The type_code may be "FAT12", "FAT16", "Linux", or a hexadecimal
3377 number between 0x00 and 0xff. Not all those numbers will yield
3378 usable results. For a list of MBR partition type codes search
3379 the Internet for "Partition Types" or run fdisk command "L".
3380 type_code may also be a type GUID as plain hex string like
3381 a2a0d0ebe5b9334487c068b6b72699c7 or as structured text like
3382 EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the
3383 partition is mentioned in GPT. In MBR,
3384 C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped to 0xef. Any
3385 other GUID will be mapped to 0x83. In APM,
3386 48465300-0000-11AA-AA11-00306543ECAC will be mapped to partition
3387 type "Apple_HFS", any other to "Data".
3388 If some other command causes the production of GPT, then the
3389 appended partitions will be mentioned there too.
3390 The disk_path must provide the necessary data bytes at commit
3391 time. An empty disk_path disables this feature for the given
3392 partition number.
3393 With SUN Disk Label (selected by -boot_image any sparc_label=):
3394 partition_number may be 2 to 8. Number 1 will always be the ISO
3395 image. Partition start addresses are aligned to 320 KiB. The
3396 type_code does not matter. Submit 0x0.
3397 Partition image name "." causes the partition to become a copy
3398 of the next lower valid one.
3399 Jigdo Template Extraction:
3401 From man genisoimage: "Jigdo is a tool to help in the distribution of
3403 large files like CD and DVD images; see http://atterer.net/jigdo/ for
3404 more details. Debian CDs and DVD ISO images are published on the web in
3405 jigdo format to allow end users to download them more efficiently."
3406 xorriso can produce a .jigdo and a .template file together with a
3407 single-session ISO image. The .jigdo file contains checksums and
3408 symbolic file addresses. The .template file contains the compressed
3409 ISO image with reference tags instead of the content bytes of the
3410 listed files.
3411 Input for this process are the normal arguments for a xorriso session
3412 on a blank -outdev, and a checksum file which lists those data files
3413 which may be listed in the .jigdo file and externally referenced in the
3414 .template file. Each designated file is represented in the checksum
3415 file by a single text line:
3416 Checksum as hex digits, 2 blanks, size as 12 decimal digits or blanks,
3417 2 blanks, symbolic file address
3418 The kind of checksum is chosen by -jigdo "checksum_algorithm" with
3419 values "md5" (32 hex digits) or "sha256" (64 hex digits). It will also
3420 be used for the file address lines in the .jigdo file. The default is
3421 "md5".
3422 The file address in a checksum file line has to bear the same basename
3423 as the disk_path of the file which it shall match. The directory path
3424 of the file address is decisive for To=From mapping, not for file
3425 recognition. After To=From mapping, the file address gets written into
3426 the .jigdo file. Jigdo restore tools will convert these addresses into
3427 really reachable data source addresses from which they can read.
3428 If the list of jigdo parameters is not empty, then xorriso will refuse
3429 to write to non-blank targets, it will disable multi-session emulation,
3430 and padding will be counted as part of the ISO image.
3431 -jigdo parameter_name value
3433 Clear Jigdo Template Extraction parameter list or add a
3434 parameter to that list. The alias names are the corresponding
3435 genisoimage options. They are accepted as parameter names as
3436 well. Especially they are recognized by the -as mkisofs
3437 emulation command.
3438 Parameter clear with any value empties the whole list. No
3439 .jigdo and .template file will be produced.
3440 checksum_algorithm chooses the checksum algorithm which shall be
3441 used for the data file entries in the .jigdo file and is
3442 expected in the checksum file. Permissible are "md5" or
3443 "sha256". Default is "md5".
3444 Alias: -jigdo-checksum-algorithm
3445 template_path sets the disk_path for the .template file with the
3446 holed and compressed ISO image copy.
3447 Alias: -jigdo-template
3448 jigdo_path sets the disk_path for the .jigdo file with the
3449 checksums and download addresses for filling the holes in
3450 .template.
3451 Alias: -jigdo-jigdo
3452 checksum_path sets the disk_path where to find the checksum file
3453 with symbolic file addresses and checksums according to
3454 checksum_algorithm.
3455 Alias: md5_path
3456 Alias: -checksum-list
3457 Alias: -md5-list
3458 min_size sets the minimum size for a data file to be listed in
3459 the .jigdo file and being a hole in the .template file.
3460 Alias: -jigdo-min-file-size
3461 exclude adds a regular expression pattern which will get
3462 compared with the absolute disk_path of any data file. A match
3463 causes the file to stay in .template in any case.
3464 Alias: -jigdo-exclude
3465 demand_checksum adds a regular expression pattern which will get
3466 compared with the absolute disk_path of any data file that was
3467 not found in the checksum list file as of "checksum_path". A
3468 match causes a MISHAP event.
3469 Alias: demand_md5
3470 Alias: -jigdo-force-checksum
3471 Alias: -jigdo-force-md5
3472 mapping adds a string pair of the form To=From to the parameter
3473 list. If a data file gets listed in the .jigdo file, then it is
3474 referred by the file address from its line in the checksum file.
3475 This file address gets checked whether it begins with the From
3476 string. If so, then this string will be replaced by the To
3477 string and a ':' character, before it goes into the .jigdo file.
3478 The From string should end by a '/' character.
3479 Alias: -jigdo-map
3480 compression chooses one of "bzip2" or "gzip" for the compression
3481 of the template file. The jigdo file is put out uncompressed.
3482 Alias: -jigdo-template-compress
3483 checksum_iso chooses one or more of "md5", "sha1", "sha256",
3484 "sha512" for the auxiliary "# Image Hex" checksums in the jigdo
3485 file. The value may e.g. look like "md5,sha1,sha512". Value
3486 "all" chooses all available algorithms. Note that MD5 stays
3487 always enabled.
3488 Alias: -checksum_algorithm_iso
3489 checksum_template is like checksum_iso but for "# Template Hex".
3490 Alias: -checksum_algorithm_template
3491 Character sets:
3493 File names are strings of non-zero bytes with 8 bit each. Unfortunately
3495 the same byte string may appear as different peculiar national
3496 characters on differently nationalized terminals. The meanings of byte
3497 codes are defined in character sets which have names. Shell command
3498 iconv -l lists them.
3499 The file names on hard disk are assumed to be encoded by the local
3500 character set which is also used for the communication with the user.
3501 Byte codes 32 to 126 of the local character set must match the US-ASCII
3502 characters of the same code. ISO-8859 and UTF-8 fulfill this demand.
3503 By default, xorriso uses the character set as told by shell command
3504 "locale" with argument "charmap". This may be influenced by environment
3505 variables LC_ALL, LC_CTYPE, or LANG and should match the expectations
3506 of the terminal. In some situations it may be necessary to set it by
3507 command -local_charset.
3508 Local character sets should not matter as long as only english
3509 alphanumeric characters are used for file names or as long as all
3510 writers and readers of the media use the same local character set.
3511 Outside these constraints it may be necessary to let xorriso convert
3512 byte codes from and to other character sets.
3513 The Rock Ridge file names in ISO filesystems are assumed to be encoded
3514 by the input character set. The Rock Ridge file names which get
3515 written with ISO filesystems will be encoded by the output character
3516 set.
3517 The sets can be defined independently by commands -in_charset and
3518 -out_charset. Normally one will have both identical, if ever. Other
3519 than the local character set, these two character sets may deviate from
3520 US-ASCII.
3521 The output character sets for Joliet and HFS+ are not influenced by
3522 these commands. Joliet uses output character set UCS-2 or UTF-16. HFS+
3523 uses UTF-16.
3524 The default output charset is the local character set of the terminal
3525 where xorriso runs. So by default no conversion happens between local
3526 filesystem names and emerging Rock Ridge names in the image. The
3527 situation stays ambiguous and the reader has to riddle what character
3528 set was used.
3529 By command -auto_charset it is possible to attribute the output charset
3530 name to the image. This makes the situation unambiguous. But if your
3531 terminal character set does not match the character set of the local
3532 file names, then this attribute can become plainly wrong and cause
3533 problems at read time. To prevent this it is necessary to check
3534 whether the terminal properly displays all intended filenames. Check
3535 especially the exotic national characters.
3536 To enforce recording of a particular character set name without any
3537 conversion at image generation time, set -charset and -local_charset to
3538 the desired name, and enable -backslash_codes to avoid evil character
3539 display on your terminal.
3540 -charset character_set_name
3542 Set the character set from which to convert file names when
3543 loading an image and to which to convert when writing an image.
3544 -local_charset character_set_name
3546 Override the system assumption of the local character set name.
3547 If this appears necessary, one should consider to set
3548 -backslash_codes to "on" in order to avoid dangerous binary
3549 codes being sent to the terminal.
3550 Exception processing:
3552 Since the tasks of xorriso are manifold and prone to external
3554 influence, there may arise the need for xorriso to report and handle
3555 problem events.
3556 Those events get classified when they are detected by one of the
3557 software modules and forwarded to reporting and evaluation modules
3558 which decide about reactions. Event classes are sorted by severity:
3559 "NEVER" The upper end of the severity spectrum.
3560 "ABORT" The program is being aborted and on its way to end.
3561 "FATAL" The main purpose of the run failed or an important resource
3562 failed unexpectedly.
3563 "FAILURE" An important part of the job could not be performed.
3564 "MISHAP" A FAILURE which can be tolerated during ISO image generation.
3565 "SORRY" A less important part of the job could not be performed.
3566 "WARNING" A situation is suspicious of being not intended by the user.
3567 "HINT" A proposal to the user how to achieve better results.
3568 "NOTE" A harmless information about noteworthy circumstances.
3569 "UPDATE" A pacifier message during long running operations.
3570 "DEBUG" A message which would only interest the program developers.
3571 "ALL" The lower end of the severity spectrum.
3572 -abort_on severity
3574 Set the severity threshold for events to abort the program.
3575 Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY"
3576 It may become necessary to abort the program anyway, despite the
3577 setting by this command. Expect not many "ABORT" events to be
3578 ignorable.
3579 A special property of this command is that it works preemptive
3580 if given as program start argument. I.e. the first -abort_on
3581 setting among the start arguments is in effect already when the
3582 first operations of xorriso begin. Only "-abort_on" with dash
3583 "-" is recognized that way.
3584 -return_with severity exit_value
3586 Set the threshold and exit_value to be returned at program end
3587 if no abort has happened. This is to allow xorriso to go on
3588 after problems but to get a failure indicating exit value from
3589 the program, nevertheless. Useful is a value lower than the
3590 -abort_on threshold, down to "WARNING".
3591 exit_value may be either 0 (indicating success to the starter of
3592 the program) or a number between 32 and 63. Some other
3593 exit_values are used by xorriso if it decides to abort the
3594 program run:
3595 1=abort due to external signal
3596 2=no program arguments given
3597 3=creation of xorriso main object failed
3598 4=failure to start libburnia-project.org libraries
3599 5=program abort during argument processing
3600 6=program abort during dialog processing
3601 -report_about severity
3603 Set the threshold for events to be reported.
3604 Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG",
3605 "ALL"
3606 Regardless what is set by -report_about, messages get always
3607 reported if they reach the severity threshold of -abort_on .
3608 Event messages are sent to the info channel "I" which is usually
3609 stderr but may be influenced by command -pkt_output. Info
3610 messages which belong to no event get attributed severity
3611 "NOTE".
3612 A special property of this command is that the first
3613 -report_about setting among the start arguments is in effect
3614 already when the first operations of xorriso begin. Only
3615 "-report_about" with dash "-" is recognized that way.
3616 -signal_handling mode
3618 Control the installation of a signal handler which shall react
3619 on external signals (e.g. from program "kill" or from keys
3620 Ctrl+C) or on signals caused by severe program errors.
3621 Mode "on" is the default. It uses the signal handler of libburn
3622 which produces ugly messages but puts much effort in releasing
3623 optical drives before xorriso ends.
3624 Mode "off" as first -signal_handling among the start arguments
3625 prevents all own signal precautions of xorriso. Inherited signal
3626 handler settings stay as they are.
3627 It works like "sig_dfl" if given after other signal handling was
3628 already established at program start.
3629 Mode "sig_dfl" uses the system provided default handling of
3630 signals, which is normally a sudden abort of the program. To
3631 prevent stuck drives, the libburn handler is used during
3632 burning, blanking, and formatting on MMC drives.
3633 Mode "sig_ign" tries to ignore as many signal types as possible.
3634 This imposes the risk that xorriso refuses to end until
3635 externally kill -9 if performed. kill -9 then imposes the risk
3636 that the drive is left in unusable state and needs poweroff to
3637 be reset. So during burning, blanking, and formatting wait for
3638 at least their normal run time before killing externally.
3639 A special property of this command is that the first
3640 -signal_handling setting among the start arguments is in effect
3641 already when the first operations of xorriso begin. Only
3642 "-signal_handling" with dash "-" is recognized that way.
3643 -error_behavior occasion behavior
3645 Control the program behavior at problem event occasions. For
3646 now this applies to occasions "image_loading" which is given
3647 while an image tree is read from the input device, and to
3648 "file_extraction" which is given with osirrox commands like
3649 -extract.
3650 With "image_loading" there are three behaviors available:
3651 "best_effort" goes on with reading after events with severity
3652 below FAILURE if the threshold of command -abort_on allows this.
3653 "failure" aborts image tree reading on first event of at least
3654 SORRY. It issues an own FAILURE event. This is the default.
3655 "fatal" acts like "failure" but issues the own event as FATAL.
3656 With occasion "file_extraction" there are three behaviors:
3657 "keep" maintains incompletely extracted files on disk. This is
3658 the default.
3659 "delete" removes files which encountered errors during content
3660 extraction.
3661 "best_effort" starts a revovery attempt by means of -extract_cut
3662 if the file content stems from the loaded ISO image and is not
3663 filtered.
3664 Dialog mode control:
3666 -dialog "on"|"off"|"single_line"
3668 Enable or disable to enter dialog mode after all program
3669 arguments are processed. In dialog mode input lines get
3670 prompted via readline or from stdin.
3671 If no -abort_on severity was set when dialog starts, then
3672 "NEVER" is set to avoid abort in most cases of wrong input or
3673 other problems. Before dialog begins, the default is "FAILURE"
3674 which e.g. aborts on unknown commands.
3675 Mode "on" supports input of newline characters within quotation
3676 marks and line continuation by trailing backslash outside
3677 quotation marks. Mode "single_line" does not.
3678 -page length width
3680 Describe terminal to the text pager. See also above, paragraph
3681 Result pager.
3682 If parameter length is nonzero then the user gets prompted after
3683 that number of terminal lines. Zero length disables paging.
3684 Parameter width is the number of characters per terminal line.
3685 It is used to compute the number of terminal lines which get
3686 occupied by an output line. A usual terminal width is 80.
3687 -use_readline "on"|"off"
3689 If "on" then use readline for dialog. Else use plain stdin.
3690 See also above, paragraph Dialog, Readline, Result pager.
3691 -reassure "on"|"tree"|"off"
3693 If "on" then ask the user for "y" or "n":
3694 before deleting or overwriting any file in the ISO image,
3695 before overwriting any disk file during restore operations,
3696 before rolling back pending image changes,
3697 before committing image changes to media,
3698 before changing the input drive,
3699 before blanking or formatting media,
3700 before ending the program.
3701 With setting "tree" the reassuring prompt will appear for an
3702 eventual directory only once and not for each file in its whole
3703 subtree.
3704 Setting "off" silently kills any kind of image file object and
3705 performs above irrevocable actions.
3706 To really produce user prompts, command -dialog needs to be set
3707 to "on". Note that the prompt does not appear in situations
3708 where file removal is forbidden by command -overwrite. -reassure
3709 only imposes an additional curb for removing existing file
3710 objects.
3711 Be aware that file objects get deleted from the ISO image
3712 immediately after confirmation. They are gone even if the
3713 running command gets aborted and its desired effect gets
3714 revoked. In case of severe mess-up, consider to use -rollback to
3715 revoke the whole session.
3716 Drive and media related inquiry actions:
3718 -devices
3720 Show list of available MMC drives with the addresses of their
3721 libburn standard device files.
3722 This is only possible when no ISO image changes are pending.
3723 After this command was executed, there is no drive current and
3724 no image loaded.
3725 In order to be visible, a device has to offer rw-permissions
3726 with its libburn standard device file. Thus it might be only the
3727 superuser who is able to see all drives.
3728 Drives which are occupied by other processes get not shown.
3729 -device_links
3731 Like -devices, but presenting the drives with addresses of
3732 symbolic links which point to the actual device files.
3733 Modern GNU/Linux systems may shuffle drive addresses from boot
3734 to boot. The udev daemon is supposed to create links which
3735 always point to the same drive, regardless of its system
3736 address. The command -device_links shows the addresses of such
3737 links if they begin by "/dev/dvd" or "/dev/cd". Precedence is:
3738 "dvdrw", "cdrw", "dvd", "cdrom", "cd".
3739 -toc
3741 Show media specific tables of content. This is the session
3742 history of the medium, not the ISO image directory tree.
3743 In case of overwritable media holding a valid ISO image, it may
3744 happen that only a single session gets shown. But if the first
3745 session on the overwritable media was written by xorriso then a
3746 complete session history can be emulated.
3747 A drive which is incapable of writing may show any media as
3748 CD-ROM or DVD-ROM with only one or two sessions on it. The last
3749 of these sessions is supposed to be the most recent real session
3750 then.
3751 Some read-only drives and media show no usable session history
3752 at all. Command -rom_toc_scan might help.
3753 If input device and output device are both acquired and not the
3754 same, then both tables-of-content get shown.
3755 -toc_of "in"|"out"|"all"[":short"]
3757 Like command -toc but explicitly choosing which drive's
3758 table-of-content to show. "in" shows -indev or -dev, "out" shows
3759 -outdev or -dev, "all" shows the same as -toc.
3760 If ":short" is appended to the drive choosing word, then only a
3761 short summary of drive state and medium content is printed.
3762 As further difference to -toc, this command does not emit
3763 FAILURE events if the desired drive is not acquired.
3764 -assess_indev_features "plain"|"cmd"|"as_mkisofs"|"replay"
3766 Inspect the filesystem on -indev for the presence of Rock Ridge,
3767 Joliet, or ISO 9660:1999, and for traces of other write options
3768 which seem to have been used when the filesystem was created.
3769 Note that this command does not detect and report a possibly
3770 present HFS+ tree.
3771 Mode "cmd" lists xorriso commands which would activate the
3772 detected settings.
3773 Mode "as_mkisofs" lists options of the -as mkisofs emulation,
3774 which would activate those of the detected settings which are
3775 not default.
3776 Mode "replay" performs the commands which get listed by mode
3777 "cmd".
3778 Mode "plain" lists after a "Indev feature: " header name-value
3779 pairs as delivered by libisofs function
3780 iso_read_image_feature_named(). See libisofs.h. The other modes
3781 derive their output from this list. I.e. the sequence of
3782 commands from "cmd" follows the sequence of "plain".
3783 Not leading to "cmd" lines are:
3784 "size=" tells the number of 2048 byte blocks of the filesystem.
3785 "eltorito=1" tells that El Torito boot equipment was detected.
3786 "tree_loaded=" tells which tree was loaded by -indev:
3787 0 = ISO 9660 , 1 = Joliet , 2 = ISO 9660:1999
3788 "tree_loaded_text=" tells the same by name: "ISO9660", "Joliet",
3789 "ISO9660:1999"
3790 "rr_loaded=1" tells that Rock Ridge information was loaded with
3791 the tree.
3792 "aaip=1" tells that AAIP information was detected (ACL, xattr,
3793 MD5, ...).
3794 "relaxed_vol_atts=1" tells that the volume attributes like
3795 -volid or -preparer_id bear characters outside the restricted
3796 character sets which are specified for them by ECMA-119.
3797 "rrip_1_10_px_ino=1" tells that with Rock Ridge 1.10 a PX entry
3798 was found which looks like from Rock Ridge 1.12.
3799 -mount_cmd drive entity id path
3801 Emit an appropriate command line for mounting the ISO session
3802 indicated by drive, entity and id. The result will be different
3803 on GNU/Linux and on FreeBSD or NetBSD.
3804 drive can be "indev" or "outdev" to indicate already acquired
3805 drives, or it can be the path of a not yet acquired drive.
3806 Prefix "stdio:" for non-MMC drives is not mandatory.
3807 For entity and id, see also command -load. They must be either
3808 "sbsector" with the superblock sector address as id, or "track"
3809 with a track number as id, or "session" with a session number,
3810 or "volid" with a search pattern for the volume id, or "auto"
3811 with which any text as id mounts the first track of the last
3812 session.
3813 path will be used as mount point and must already exist as a
3814 directory on disk.
3815 The command gets printed to the result channel. See command
3816 -mount for direct execution of this command.
3817 -mount_opts option[:option...]
3819 Set options which influence -mount and -mount_cmd. Currently
3820 there is only option "exclusive" which is default and its
3821 counterpart "shared". The latter causes xorriso not to give up
3822 the affected drive with command -mount. On GNU/Linux it adds
3823 mount option "loop" which may enable mounting of several
3824 sessions of the same block device at the same time. One should
3825 not write to a mounted optical medium, of course. Take care to
3826 umount all sessions before ejecting.
3827 -session_string drive entity id format
3829 Print to the result channel a text which gets composed according
3830 to format and the parameters of the addressed session.
3831 Formats "linux:"path or "freebsd:"path produce the output of
3832 -mount_cmd for the given operating systems.
3833 In other texts xorriso will substitute the following parameter
3834 names. An optional prefix "string:" will be removed.
3835 "%device%" will be substituted by the mountable device path of
3836 the drive address.
3837 "%sbsector%" will be substituted by the session start sector.
3838 "%track%", "%session%", "%volid%" will be substituted by track
3839 number, session number, or volume id of the depicted session.
3840 -print_size
3842 Print the foreseeable consumption of 2048 byte blocks by next
3843 -commit. This can last a while as a -commit gets prepared and
3844 only in last moment is revoked by this command. The result
3845 depends on several settings and also on the kind of output
3846 device. If no -jigdo options are set and not command -as
3847 "mkisofs" was used, then -padding (300 kB by default) is not
3848 counted as part of the image size.
3849 If an El Torito boot image file is already depicted, then
3850 command -print_size automatically executes -boot_image "any"
3851 "next". This means that the properties of that boot image
3852 cannot be edited by subsequent commands.
3853 -tell_media_space
3855 Print available space on the output medium and the free space
3856 after subtracting already foreseeable consumption by next
3857 -commit.
3858 Note that the title of the prediction "After commit :" is
3859 misleading. It is rather the space that may still be filled in
3860 this session without making the next -commit fail from medium
3861 overflow.
3862 The free space after the next -commit might be smaller by
3863 several MB. This depends on medium type, number of recorded
3864 sessions, and drive habits.
3865 -pvd_info
3867 Print various ID strings and timestamps which can be found in
3868 loaded ISO images. Some of the IDs may be changed by commands
3869 like -volid or -publisher. For these IDs -pvd_info reports what
3870 would be written with the next -commit. The timestamps get not
3871 automatically propagated from loaded image to newly written
3872 image. The ones for new images may be set by command
3873 -volume_date. See there for the meaning of the particular
3874 timestamps.
3875 -report_el_torito mode
3877 With mode plain print a report about the information found in
3878 the El Torito boot catalog of the loaded ISO image.
3879 With mode help print a text which explains the meaning of the
3880 lines put out by "plain".
3881 Mode cmd tries to print the xorriso commands which are necessary
3882 to produce the found boot equipment: disk identifiers, El Torito
3883 boot images, and System Area. Disk identifiers are strings which
3884 the booting operating system might use to find the ISO
3885 filesystem from where it comes. Currently known is the use of
3886 volume id and modification date.
3887 The intended use case is modification of the filesystem by
3888 having -indev and -outdev pointing to different images or
3889 drives. The result might be insufficient, if the found
3890 equipment cannot be produced by xorriso. Various SORRY events
3891 may arise in this case, but it is not guaranteed that xorriso
3892 recognizes all its insufficiencies.
3893 Mode as_mkisofs tries to print the xorriso -as mkisofs options,
3894 which are necessary to produce the found equipment. The
3895 intended use case is to use the mounted filesystem as input tree
3896 together with the printed options.
3897 If CHRP equipment is detected, then modes cmd and as_mkisofs
3898 issue some of the relaxation commands or options which get
3899 detected by command -assess_indev_features. This happens because
3900 CHRP firmware reads file paths from file /ppc/bootinfo.txt and
3901 tries to find them case-insensitively in the ECMA-119 tree
3902 without using Rock Ridge. If such a path has actually forbidden
3903 properties, like the name "powerpc-ieee1275", then the
3904 relaxations are needed to bring it unmangled into the ECMA-119
3905 tree.
3906 -report_system_area mode
3908 With mode plain print a report about the information found in
3909 the System Area of the loaded ISO image. The report consists of
3910 zero to many lines with a header text, a colon, and information
3911 text.
3912 With mode help print a text which explains the meaning of the
3913 lines put out by "plain". You probably will have to look for
3914 more documentation which explains the technical details of the
3915 mentioned boot facilities.
3916 Modes cmd and as_mkisofs work like with command
3917 -report_el_torito. See above.
3918 With mode gpt_disk_guid print the GPT disk GUID of the loaded
3919 ISO in RFC 4122 text format to result channel. It is not
3920 considered an error if no GPT is present. In this case nothing
3921 is printed to result channel.
3922 With mode gpt_crc_of:disk_path read up to 32 KiB from the disk
3923 file with the path given after the colon. Compute the GPT
3924 compliant CRC number and print it to the result channel. The
3925 number is shown like "0x690fd979". The special disk_path "-"
3926 causes reading from standard input.
3927 With mode make_guid print a pseudo-random GUID in RFC 4122 text
3928 format to result channel.
3929 Navigation in ISO image and disk filesystem:
3931 -cd iso_rr_path
3933 Change the current working directory in the ISO image. This is
3934 prepended to iso_rr_paths which do not begin with '/'.
3935 It is possible to set the working directory to a path which does
3936 not exist yet in the ISO image. The necessary parent directories
3937 will be created when the first file object is inserted into that
3938 virtual directory. Use -mkdir if you want to enforce the
3939 existence of the directory already at first insertion.
3940 -cdx disk_path
3942 Change the current working directory in the local filesystem.
3943 To be prepended to disk_paths which do not begin with '/'.
3944 -pwd
3946 Tell the current working directory in the ISO image.
3947 -pwdx
3949 Tell the current working directory in the local filesystem.
3950 -ls iso_rr_pattern [***]
3952 List files in the ISO image which match shell patterns (i.e.
3953 with wildcards '*' '?' '[a-z]'). If a pattern does not begin
3954 with '/' then it is compared with addresses relative to -cd.
3955 Directories are listed by their content rather than as single
3956 file item.
3957 Pattern expansion may be disabled by command -iso_rr_pattern.
3958 -lsd iso_rr_pattern [***]
3960 Like -ls but listing directories as themselves and not by their
3961 content. This resembles shell command ls -d.
3962 -lsl iso_rr_pattern [***]
3964 Like -ls but also list some of the file attributes. The output
3965 format resembles shell command ls -ln.
3966 File type 'e' indicates the El Torito boot catalog.
3967 If the file has non-trivial ACL, then a '+' is appended to the
3968 permission info. If the file is hidden, then 'I' for "iso_rr",
3969 'J' for "joliet", 'A' for "hfsplus", 'H' for multiple hiding
3970 gets appended. Together with ACL it is 'i', 'j', 'a', 'h'.
3971 -lsdl iso_rr_pattern [***]
3973 Like -lsd but also list some of the file attributes. The output
3974 format resembles shell command ls -dln.
3975 -lsx disk_pattern [***]
3977 List files in the local filesystem which match shell patterns.
3978 Patterns which do not begin with '/' are used relative to -cdx.
3979 Directories are listed by their content rather than as single
3980 file item.
3981 Pattern expansion may be disabled by command -disk_pattern.
3982 -lsdx disk_pattern [***]
3984 Like -lsx but listing directories as themselves and not by their
3985 content. This resembles shell command ls -d.
3986 -lslx disk_pattern [***]
3988 Like -lsx but also listing some of the file attributes. Output
3989 format resembles shell command ls -ln.
3990 -lsdlx disk_pattern [***]
3992 Like -lsdx but also listing some of the file attributes. Output
3993 format resembles shell command ls -dln.
3994 -getfacl iso_rr_pattern [***]
3996 Print the access permissions of the given files in the ISO image
3997 using the format of shell command getfacl. If a file has no ACL
3998 then it gets fabricated from the -chmod settings. A file may
3999 have a real ACL if it was introduced into the ISO image while
4000 command -acl was set to "on".
4001 -getfacl_r iso_rr_pattern [***]
4003 Like -gefacl but listing recursively the whole file trees
4004 underneath eventual directories.
4005 -getfattr iso_rr_pattern [***]
4007 Print the xattr of the given files in the ISO image. If a file
4008 has no such xattr then noting is printed for it. The choice of
4009 namespaces depends on the setting of command -xattr: "on" or
4010 "user" restricts it to namespace "user", "any" only omits
4011 namespace "isofs".
4012 -getfattr_r iso_rr_pattern [***]
4014 Like -gefattr but listing recursively the whole file trees
4015 underneath of directories.
4016 -du iso_rr_pattern [***]
4018 Recursively list size of directories and files in the ISO image
4019 which match one of the patterns. similar to shell command du
4020 -k.
4021 -dus iso_rr_pattern [***]
4023 List size of directories and files in the ISO image which match
4024 one of the patterns. Similar to shell command du -sk.
4025 -dux disk_pattern [***]
4027 Recursively list size of directories and files in the local
4028 filesystem which match one of the patterns. Similar to shell
4029 command du -k.
4030 -dusx disk_pattern [***]
4032 List size of directories and files in the local filesystem which
4033 match one of the patterns. Similar to shell command du -sk.
4034 -findx disk_path [-name pattern] [-type t] [-exec action [params]] --
4036 Like -find but operating on local filesystem and not on the ISO
4037 image. This is subject to the settings of -follow.
4038 -findx accepts the same -type parameters as -find. Additionally
4039 it recognizes type "mountpoint" (or "m") which matches
4040 subdirectories which reside on a different device than their
4041 parent. It never matches the disk_path given as start address
4042 for -findx.
4043 -findx accepts the -exec actions as does -find. But except the
4044 following few actions it will always perform action "echo".
4045 in_iso reports the path if its counterpart exists in the ISO
4046 image. For this the disk_path of the -findx command gets
4047 replaced by the iso_rr_path given as parameter.
4048 E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd --
4049 not_in_iso reports the path if its counterpart does not exist in
4050 the ISO image. The report format is the same as with command
4051 -compare.
4052 add_missing iso_rr_path_start adds the counterpart if it does
4053 not yet exist in the ISO image and marks it for "rm_merge" as
4054 non-removable.
4055 E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd --
4056 is_full_in_iso reports if the counterpart in the ISO image
4057 contains files. To be used with -type "m" to report mount
4058 points.
4059 empty_iso_dir deletes all files from the counterpart in the ISO
4060 image. To be used with -type "m" to truncate mount points.
4061 estimate_size prints a lower and an upper estimation of the
4062 number of blocks which the found files together will occupy in
4063 the emerging ISO image. This does not account for the
4064 superblock, for the directories in the -findx path, or for image
4065 padding.
4066 list_extattr mode prints a script to the result channel, which
4067 would use FreeBSD command setextattr to set the file's xattr
4068 name-value pairs of user namespace. See -find for a description
4069 of parameter mode.
4070 E.g. -exec list_extattr e --
4071 -compare disk_path iso_rr_path
4073 Compare attributes and eventual data file content of a
4074 fileobject in the local filesystem with a file object in the ISO
4075 image. The iso_rr_path may well point to an image file object
4076 which is not yet committed, i.e. of which the data content still
4077 resides in the local filesystem. Such data content is prone to
4078 externally caused changes.
4079 If iso_rr_path is empty then disk_path is used as path in the
4080 ISO image too.
4081 Differing attributes are reported in detail, differing content
4082 is summarized. Both to the result channel. In case of no
4083 differences no result lines are emitted.
4084 -compare_r disk_path iso_rr_path
4086 Like -compare but working recursively. I.e. all file objects
4087 below both addresses get compared whether they have counterparts
4088 below the other address and whether both counterparts match.
4089 -compare_l disk_prefix iso_rr_prefix disk_path [***]
4091 Perform -compare_r with each of the disk_path parameters.
4092 iso_rr_path will be composed from disk_path by replacing
4093 disk_prefix by iso_rr_prefix.
4094 -show_stream iso_rr_path [***]
4096 Display the content stream chain of data files in the ISO image.
4097 The chain consists of the iso_rr_name and one or more streams,
4098 separated by " < " marks. A stream description consists of one
4099 or more texts, separated by ":" characters. The first text
4100 tells the stream type, the following ones, if ever, describe its
4101 individual properties. Frequently used types are:
4102 disk:'disk_path' for local filesystem objects.
4103 image:'iso_rr_path' for ISO image file objects.
4104 cout:'disk_path offset count' for -cut_out files.
4105 extf:'filter_name' for external filters.
4106 --zisofs:algorithm:block_size for zisofs compression filters.
4107 --zisofs-decode:algorithm:block_size for zisofs uncompression
4108 filters.
4109 --gzip for internal gzip compression filters.
4110 --gunzip for internal gzip uncompression filters.
4111 Example:
4112 '/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'
4113 -show_stream_r iso_rr_path [***]
4115 Like -show_stream but working recursively.
4116 Evaluation of readability and recovery:
4118 It is not uncommon that optical media produce read errors. The reasons
4120 may be various and get obscured by error correction which is performed
4121 by the drives and based on extra data on the media. If a drive returns
4122 data then one can quite trust that they are valid. But at some degree
4123 of read problems the correction will fail and the drive is supposed to
4124 indicate error.
4125 xorriso can scan a medium for readable data blocks, classify them
4126 according to their read speed, save them to a file, and keep track of
4127 successfully saved blocks for further tries on the same medium.
4128 By command -md5 checksums may get recorded with data files and whole
4129 sessions. These checksums are reachable only via indev and a loaded
4130 image. They work independently of the media type and can detect
4131 transmission errors.
4132 -check_media [option [option ...]] --
4134 Try to read data blocks from the indev drive, optionally copy
4135 them to a disk file, and finally report about the encountered
4136 quality. Several options may be used to modify the default
4137 behavior.
4138 The parameters given with this command override the default
4139 settings which may have been changed by command
4140 -check_media_defaults. See there for a description of available
4141 options.
4142 The result list tells intervals of 2 KiB blocks with start
4143 address, number of blocks and quality. Qualities which begin
4144 with "+" are supposed to be valid readable data. Qualities with
4145 "-" are unreadable or corrupted data. "0" indicates qualities
4146 which are not covered by the check run or are regularly allowed
4147 to be unreadable (e.g. gaps between tracks).
4148 Alternatively it is possible to report damaged files rather than
4149 blocks.
4150 If -md5 is "on" then the default mode what=tracks looks out for
4151 libisofs checksum tags for the ISO session data and checks them
4152 against the checksums computed from the data stream.
4153 -check_media_defaults [option [option ...]] --
4155 Preset options for runs of -check_media, -extract_cut and
4156 best_effort file extraction. Options given with -check_media
4157 will override the preset options. -extract_cut will override
4158 some options automatically.
4159 An option consists of a keyword, a "=" character, and a value.
4160 Options may override each other. So their sequence matters.
4161 The default setting at program start is:
4162 use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
4163 time_limit=28800 item_limit=100000 data_to='' event=ALL
4164 abort_file=/var/opt/xorriso/do_abort_check_media
4165 sector_map='' map_with_volid=off patch_lba0=off report=blocks
4166 bad_limit=invalid slow_limit=1.0 chunk_size=0s async_chunks=0
4167 Option "reset=now" restores these startup defaults.
4168 Non-default options are:
4169 report="files" lists the files which use damaged blocks (not
4170 with use=outdev). The format is like with find -exec
4171 report_damage. Note that a MD5 session mismatch marks all files
4172 of the session as damaged. If finer distinction is desired,
4173 perform -md5 off before -check_media.
4174 report="blocks_files" first lists damaged blocks and then
4175 affected files.
4176 use="outdev" reads from the output drive instead of the input
4177 drive. This avoids loading the ISO image tree from media.
4178 use="sector_map" does not read any media but loads the file
4179 given by option sector_map= and processes this virtual outcome.
4180 what="disc" scans the payload range of a medium without
4181 respecting track gaps.
4182 what="image" similar to "disc", but restricts scanning to the
4183 range of the ISO 9660 image, if present.
4184 min_lba=limit omits all blocks with addresses lower than limit.
4185 max_lba=limit switches to what=disc and omits all blocks above
4186 limit.
4187 chunk_size=size sets the number of bytes to be read in one
4188 low-level read operation. This gets rounded down to full blocks
4189 of 2048 bytes. 0 means automatic size.
4190 retry="on" forces read retries with minimal senseful chunk size
4191 when the normal read chunk produces a read error. This size is
4192 1s with CD and stdio files, 16s with DVD (1 ECC Block), and 32s
4193 with BD (1 Cluster). By default, retries are only enabled with
4194 CD media. "retry=off" forbits retries for all media types.
4195 abort_file=disk_path gives the path of the file which may abort
4196 a scan run. Abort happens if the file exists and its mtime is
4197 not older than the start time of the run. Use shell command
4198 "touch" to trigger this. Other than an aborted program run,
4199 this will report the tested and untested blocks and go on with
4200 running xorriso.
4201 time_limit=seconds gives the number of seconds after which the
4202 scan shall be aborted. This is useful for unattended scanning of
4203 media which may else overwork the drive in its effort to squeeze
4204 out some readable blocks. Abort may be delayed by the drive
4205 gnawing on the last single read operation. Value -1 means
4206 unlimited time.
4207 item_limit=number gives the number of report list items after
4208 which to abort. Value -1 means unlimited item number.
4209 data_to=disk_path copies the valid blocks to the given file,
4210 which must support random access writing, unless disk_path is
4211 "-" which means standard output.
4212 In the latter case, patch_lba0= settings other than "off" yield
4213 failure. Further the usual result messages of -check_media get
4214 redirected to the info channel. But beware of result messages
4215 from other commands. Beware of -*dev "-" which redirect standard
4216 output to standard error. Keep the run simple:
4217 xorriso -indev /dev/sr0 -check_media data_to=- -- | md5sum
4218 xorriso -outdev /dev/sr0 -check_media data_to=- use=outdev \
4219 what=disc min_lba=0 max_lba=999999 -- | sha256sum
4220 event=severity sets the given severity for a problem event which
4221 shall be issued at the end of a check run if data blocks were
4222 unreadable or failed to match recorded MD5 checksums. Severity
4223 "ALL" disables this event.
4224 sector_map=disk_path tries to read the file given by disk_path
4225 as sector bitmap and to store such a map file after the scan
4226 run. The bitmap tells which blocks have been read successfully
4227 in previous runs. It is the persistent memory for several scans
4228 on the same medium, even with intermediate eject, in order to
4229 collect readable blocks whenever the drive is lucky enough to
4230 produce them. The stored file contains a human readable TOC of
4231 tracks and their start block addresses, followed by binary
4232 bitmap data.
4233 By default, untested blocks are not considered bad, but rather
4234 as intentionally unread. If you expect time_limit= or
4235 item_limit= to abort the run, then consider to use
4236 bad_limit="untested".
4237 map_with_volid="on" examines tracks whether they are ISO images
4238 and prints their volume IDs into the human readable TOC of
4239 sector_map=.
4240 patch_lba0="on" transfers within the data_to= file a copy of the
4241 currently loaded session head to the start of that file and
4242 patches it to be valid at that position. This makes the loaded
4243 session the last valid session of the image file when it gets
4244 mounted or loaded as stdio: drive. New sessions will be appended
4245 after this last session and will overwrite any sessions which
4246 have followed it.
4247 patch_lba0="force" performs patch_lba0="on" even if xorriso
4248 believes that the copied data are not valid.
4249 patch_lba0= may also bear a number. If it is 32 or higher it is
4250 taken as start address of the session to be copied. In this case
4251 it is not necessary to have an -indev and a loaded image.
4252 ":force" may be appended after the number.
4253 bad_limit=threshold sets the highest quality which shall be
4254 considered as damage. Choose one of "good", "md5_match",
4255 "slow", "partial", "valid", "untested", "md5_mismatch",
4256 "invalid", "tao_end", "off_track", "unreadable".
4257 "valid" and "invalid" are qualities imported from a sector_map
4258 file. "tao_end" and "off_track" are intentionally not readable,
4259 but not bad either. "partial" are blocks retrieved from a
4260 partially readable chunk. They are supposed to be ok but stem
4261 from a suspicious neighborhood.
4262 "md5_match" and "md5_mismatch" regions overlap with regions of
4263 other quality. The former is a strong confirmation for quality,
4264 the latter only tells that one or more blocks of the region must
4265 be wrong.
4266 By default bad_limit is set higher than md5_mismatch, so that
4267 mismatches are classified as quality class "0" rather than "-".
4268 This means that the sectors of a MD5 mismatch range are recorded
4269 in the sector_map as successfully read, if the drive handed them
4270 out at all. Set "bad_limit=md5_mismatch" to let the sector_map
4271 record the whole mismatching range as yet not retrieved.
4272 slow_limit=threshold sets the time threshold for a single read
4273 chunk to be considered slow. This may be a fractional number
4274 like 0.1 or 1.5.
4275 async_chunks=number enables asynchronous MD5 processing if
4276 number is 2 or larger. In this case the given number of read
4277 chunks is allocated as fifo buffer. On very fast MMC drives
4278 try: chunk_size=64s async_chunks=16.
4279 -check_md5 severity iso_rr_path [***]
4281 Compare the data content of the given files in the loaded image
4282 with their recorded MD5 checksums, if there are any. In case of
4283 any mismatch an event of the given severity is issued. It may
4284 then be handled by appropriate settings of commands -abort_on or
4285 -return_with which both can cause non-zero exit values of the
4286 program run. Severity ALL suppresses that event.
4287 This command reports match and mismatch of data files to the
4288 result channel. Non-data files cause NOTE events. There will
4289 also be UPDATE events from data reading.
4290 If no iso_rr_path is given then the whole loaded session is
4291 compared with its MD5 sum. Be aware that this covers only one
4292 session and not the whole image if there are older sessions.
4293 -check_md5_r severity iso_rr_path [***]
4295 Like -check_md5 but checking all data files underneath the given
4296 paths. Only mismatching data files will be reported.
4297 osirrox ISO-to-disk restore commands:
4299 Normally xorriso only writes to disk files which were given as stdio:
4301 pseudo-drives or as log files. But its alter ego osirrox is able to
4302 extract file objects from ISO images and to create, overwrite, or
4303 delete file objects on disk.
4304 Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply. The
4305 exclusion tests are made with the paths and names for the disk files.
4306 If exclusion of paths or names in the ISO image is desired, then use
4307 image manipulation commands like -rm or -find ... -exec rm before
4308 extraction, and end the program by -rollback_end .
4309 Excluded disk_path parameters of extraction commands cause SORRY
4310 events. Implicitely given paths in trees under disk_path parameters
4311 are excluded silently.
4312 If disk file objects already exist then the settings of -overwrite and
4313 -reassure apply. But -overwrite "on" only triggers the behavior of
4314 -overwrite "nondir". I.e. directories cannot be deleted.
4315 Access permissions of files in the ISO image do not restrict restoring.
4316 The directory permissions on disk have to allow rwx.
4317 -osirrox setting[:option:...]
4319 Setting off disables disk filesystem manipulations. This is the
4320 default unless the program was started with leafname osirrox.
4321 Elsewise the capability to restore files can be enabled
4322 explicitly by -osirrox on. It can be irrevocably disabled by
4323 -osirrox banned.
4324 The setting blocked is like off. But it can only be revoked by
4325 setting unblock, which elsewise is like on. This can be used to
4326 curb command scripts which might use on undesiredly.
4327 To enable restoring of special files by device_files is
4328 potentially dangerous. The meaning of the number st_rdev (see
4329 man 2 stat) depends much on the operating system. Best is to
4330 restore device files only to the same system from where they
4331 were copied. If not enabled, device files in the ISO image are
4332 ignored during restore operations.
4333 Due to a bug of previous versions, device files from previous
4334 sessions might have been altered to major=0, minor=1. So this
4335 combination does not get restored.
4336 Option concat_split_on is default. It enables restoring of split
4337 file directories as data files if the directory contains a
4338 complete collection of -cut_out part files. With option
4339 concat_split_off such directories are handled like any other ISO
4340 image directory.
4341 Option auto_chmod_off is default. If auto_chmod_on is set then
4342 access restrictions for disk directories get circumvented if
4343 those directories are owned by the effective user who runs
4344 xorriso. This happens by temporarily granting rwx permission to
4345 the owner.
4346 Option sort_lba_on may improve read performance with optical
4347 drives. It can restore large numbers of hard links without
4348 exhausting -temp_mem_limit. It does not preserve directory mtime
4349 and it needs -osirrox option auto_chmod_on in order to extract
4350 directories which offer no write permission. Default is
4351 sort_lba_off.
4352 Option o_excl_on is the default unless the program was started
4353 with leafname "osirrox". On GNU/Linux it tries to avoid using
4354 drives which are mounted or in use by other libburn programs.
4355 Option o_excl_off on GNU/Linux enables access to such drives by
4356 the equivalent of -drive_access "shared:readonly". I.e. drives
4357 which get acquired while o_excl_off will refuse to get blanked,
4358 formatted, written, or ejected. But be aware that even harmless
4359 inquiries can spoil ongoing burns of CD-R[W] and DVD-R[W].
4360 Option strict_acl_off is default. It tolerates on FreeBSD the
4361 presence of directory "default" ACLs in the ISO image. With
4362 strict_acl_on these GNU/Linux ACLs cause on FreeBSD a FAILURE
4363 event during restore with -acl "on".
4364 Option check_md5_off disables MD5 checking during copy to disk.
4365 The default option check_md5_on enables it if -md5 is "on". If a
4366 data file with recorded MD5 is copied as a whole to the disk
4367 filesystem, then the MD5 of the copied content gets computed and
4368 compared with the recorded MD5. A mismatch causes an error
4369 message of severity SORRY. Option check_md5_force causes an
4370 error message if -md5 is "on" but no MD5 is recorded for the
4371 data file.
4372 Option sparse= controls production of sparse files during
4373 extraction of files from the ISO filesystem. Default is
4374 sparse=off.
4375 A positive number like in sparse=1m sets the minimum requirement
4376 for the length of a sequence of 0-bytes which shall be
4377 represented by a gap. This saves disk space if the disk
4378 filesystem supports sparse files. A gap gets created by help of
4379 lseek(2) if a sequence of read buffers, which contain only
4380 0-bytes, bears at least the minimum amount of bytes. Expect read
4381 buffers to be in the size range of 32k or 64k.
4382 Command -paste_in creates gaps only if the writing begins at or
4383 after the end of the existing disk file. So the sequence of
4384 -paste_in commands matters. Command -concat does not create
4385 sparse files.
4386 -extract iso_rr_path disk_path
4388 Copy the file objects at and underneath iso_rr_path to their
4389 corresponding addresses at and underneath disk_path. This is
4390 the inverse of -map or -update_r.
4391 If iso_rr_path is a directory and disk_path is an existing
4392 directory then both trees will be merged. Directory attributes
4393 get extracted only if the disk directory is newly created by the
4394 copy operation. Disk files get removed only if they are to be
4395 replaced by file objects from the ISO image.
4396 As many attributes as possible are copied together with restored
4397 file objects.
4398 -extract_single iso_rr_path disk_path
4400 Like -extract, but if iso_rr_path is a directory then its sub
4401 tree gets not restored.
4402 -extract_l iso_rr_prefix disk_prefix iso_rr_path [***]
4404 Perform -extract with each of the iso_rr_path parameters.
4405 disk_path will be composed from iso_rr_path by replacing
4406 iso_rr_prefix by disk_prefix.
4407 -extract_cut iso_rr_path byte_offset byte_count disk_path
4409 Copy a byte interval from a data file out of an ISO image into a
4410 newly created disk file. The main purpose for this is to offer
4411 a way of handling large files if they are not supported by mount
4412 -t iso9660 or if the target disk filesystem cannot store large
4413 files.
4414 If the data bytes of iso_rr_path are stored in the loaded ISO
4415 image, and no filter is applied, and byte_offset is a multiple
4416 of 2048, then a special run of -check_media is performed. It may
4417 be quicker and more rugged than the general reading method.
4418 -cpx iso_rr_path [***] disk_path
4420 Copy single leaf file objects from the ISO image to the address
4421 given by disk_path. If more then one iso_rr_path is given then
4422 disk_path must be a directory or non-existent. In the latter
4423 case it gets created and the extracted files get installed in it
4424 with the same leafnames.
4425 Missing directory components in disk_path will get created, if
4426 possible.
4427 Directories are allowed as iso_rr_path only with -osirrox
4428 "concat_split_on" and only if they actually represent a complete
4429 collection of -cut_out split file parts.
4430 -cpax iso_rr_path [***] disk_path
4432 Like -cpx but restoring mtime, atime as in ISO image and trying
4433 to set ownership and group as in ISO image.
4434 -cp_rx iso_rr_path [***] disk_path
4436 Like -cpx but also extracting whole directory trees from the ISO
4437 image.
4438 The resulting disk paths are determined as with shell command cp
4439 -r : If disk_path is an existing directory then the trees will
4440 be inserted or merged underneath this directory and will keep
4441 their leaf names. The ISO directory "/" has no leaf name and
4442 thus gets mapped directly to disk_path.
4443 -cp_rax iso_rr_path [***] disk_path
4445 Like -cp_rx but restoring mtime, atime as in ISO image and
4446 trying to set ownership and group as in ISO image.
4447 -paste_in iso_rr_path disk_path byte_offset byte_count
4449 Read the content of a ISO data file and write it into a data
4450 file or device file on disk beginning at the byte_offset. Write
4451 at most byte_count bytes. The file depicted by disk_path has to
4452 support random write access.
4453 This is the inverse of command -cut_out.
4454 -concat mode [target | lim prog [args [...]] lim] iso_rr_path [***]
4456 Copy the data content of one or more data files of the ISO image
4457 into a disk file object, into a file descriptor, or start a
4458 program and copy the data into its standard input. The latter
4459 is subject to the security restrictions for external filters.
4460 Modes overwrite and append write into the target which is given
4461 by the second parameter. This may be the path to a disk file
4462 object, or "-" which means standard output, or a text of the
4463 form /dev/fd/number, where number is an open file descriptor
4464 (e.g. standard error is /dev/fd/2). An existing target file is
4465 not removed before writing begins. If it is not able to take
4466 content data, then this command fails. Mode overwrite truncates
4467 regular data files to 0 size before writing into them. Example:
4468 -concat append /home/me/accumulated_text /my/iso/text --
4469 Mode pipe expects as second parameter a delimiter word which
4471 shall mark the end of the program argument list. The third
4472 argument is the disk_path to the program. It must contain at
4473 least one '/'. $PATH is not applied. Further parameters up to
4474 the announced delimiter word are used as arguments with the
4475 program start. Example:
4476 -iso_rr_pattern on \
4477 -concat pipe + /usr/bin/wc + "/my/iso/files*" --
4478 The further parameters in all modes are the iso_rr_paths of data
4480 files. Their content gets concatenated in the copy.
4481 -extract_boot_images disk_path
4483 Copy boot equipment to disk, which is not necessarily
4484 represented as data files in the ISO filesystem. The data get
4485 written into various files in a disk directory, which may
4486 already exist or of which the parent must exist so that it can
4487 get created.
4488 Files may be missing if their corresponding information is not
4489 present in the ISO filesystem. Existing files do not get
4490 overwritten but rather cause a failure event.
4491 The same data may appear in different files. E.g. the El Torito
4492 boot image for EFI is often the same data as the EFI partition
4493 in MBR or GPT.
4494 File "eltorito_catalog.img" contains the El Torito Boot Catalog.
4495 Files "eltorito_img*_*.img" contain El Torito Boot images. The
4496 first "*" gives the image number, the second "*" gives the type:
4497 "bios", "mac", "ppc", "uefi", or a hex number.
4498 File "mbr_code_isohybrid.img" contains the ISOLINUX MBR
4499 template.
4500 File "mbr_code_grub2.img" contains the GRUB2 MBR template.
4501 File "systemarea.img" contains the whole 32 KiB of System Area
4502 if not all zero.
4503 Files "mbr_part*_efi.img" contain EFI partition images from the
4504 MBR partition table. The "*" text part gives the partition
4505 number.
4506 Files "mbr_part*_prep.img" contain PReP partition images.
4507 Files "gpt_part*_efi.img" contain EFI partition images from GPT.
4508 Files "gpt_part*_hfsplus.img" contain HFS+ partition images from
4509 GPT. To avoid extracting the whole HFS+ aspect of hybrid ISO
4510 filesystems, the partition image is extracted only if it has
4511 less than half of the size of the ISO filesystem or if the
4512 partition is outside the ISO filesystem.
4513 -mount drive entity id path
4515 Produce the same line as -mount_cmd and then execute it as
4516 external program run after giving up the depicted drive. See
4517 also -mount_opts. This demands -osirrox to be enabled and
4518 normally will succeed only for the superuser. For safety reasons
4519 the mount program is only executed if it is reachable as
4520 /bin/mount or /sbin/mount.
4521 Command compatibility emulations:
4523 Writing of ISO 9660 on CD is traditionally done by program mkisofs as
4525 ISO 9660 image producer and cdrecord as burn program. xorriso does not
4526 strive for their comprehensive emulation. Nevertheless it is ready to
4527 perform some of its core tasks under control of commands which in said
4528 programs trigger comparable actions.
4529 -as personality option [options] --
4531 Perform the variable length option list as sparse emulation of
4532 the program depicted by the personality word.
4533 Personality "mkisofs" accepts the options listed with:
4535 -as mkisofs -help --
4536 Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mode,
4537 -file-mode, -path-list, -m, -exclude-list, -f, -print-size,
4538 -pad, -no-pad, -V, -v, -version, -graft-points, -z,
4539 -no-emul-boot, -b, -c, -boot-info-table, -boot-load-size,
4540 -input-charset, -G, -output-charset, -U, -hide, -hide-joliet,
4541 -hide-list, -hide-joliet-list, file paths and pathspecs. A lot
4542 of options are not supported and lead to failure of the mkisofs
4543 emulation. Some are ignored, but better do not rely on this
4544 tolerance.
4545 The supported options are documented in detail in xorrisofs.info
4546 and in man xorrisofs. The description here is focused on the
4547 effect of mkisofs emulation in the context of a xorriso run.
4548 Other than with the "cdrecord" personality there is no automatic
4549 -commit at the end of a "mkisofs" option list. Verbosity
4550 settings -v (= "UPDATE") and -quiet (= "SORRY") persist. The
4551 output file persists until things happen like -commit,
4552 -rollback, -dev, or end of xorriso.
4553 Options which affect all file objects in the ISO image, like -r
4554 or -dir-mode, will be applied only to files which are present in
4555 the ISO image when the command -as ends. If you use several -as
4556 mkisofs commands in the same run, then consider to put such
4557 options into the last -as command.
4558 If files are added to the image, then -pacifier gets set to
4559 "mkisofs" and -stdio_sync is defaulted to "off" if no such
4560 setting was made yet.
4561 -graft-points is equivalent to -pathspecs on. Note that
4562 pathspecs without "=" are interpreted differently than with
4563 xorriso command -add. Directories get merged with the root
4564 directory of the ISO image, other filetypes get mapped into that
4565 root directory.
4566 If pathspecs are given and if no output file was chosen before
4567 or during the "mkisofs" option list, then standard output
4568 (-outdev "-") will get into effect. If -o points to a regular
4569 file, then it will be truncated to 0 bytes when finally writing
4570 begins. This truncation does not happen if the drive is chosen
4571 by xorriso commands before -as mkisofs or after its list
4572 delimiter. Directories and symbolic links are no valid -o
4573 targets.
4574 Writing to stdout is possible only if -as "mkisofs" was among
4575 the start arguments or if other start arguments pointed the
4576 output drive to standard output.
4577 -print-size inhibits automatic image production at program end.
4578 This ban is lifted only if the pending image changes get
4579 discarded.
4580 Padding is counted as part of the ISO image if not option
4581 --emul-toc is given.
4582 If no -iso-level is given, then level 1 is chosen when the first
4583 file or directory is added to the image. At the same occasion
4584 directory names get allowed to violate the standard by
4585 -compliance option allow_dir_id_ext. This may be avoided by
4586 option -disallow_dir_id_ext.
4587 Option -root is supported. Option -old-root is implemented by
4588 xorriso commands -mkdir, -cp_clone, -find update_merge, and
4589 -find rm_merge. -root and -old-root set command -disk_dev_ino
4590 to "ino_only" and -md5 to "on", by default. -disk_dev_ino can
4591 be set to "off" by --old-root-no-ino or to "on" by
4592 --old-root-devno . -md5 can be set to "off" by
4593 --old-root-no-md5 .
4594 Not original mkisofs options are --quoted_path_list ,
4595 --hardlinks , --acl , --xattr , --md5 , --stdio_sync . They
4596 work like the xorriso commands with the same name and hardcoded
4597 parameter "on", e.g. -acl "on". Explicit parameters are
4598 expected by --stdio_sync and --scdbackup_tag.
4599 The capability to preserve multi-session history on overwritable
4600 media gets disabled by default. It can be enabled by using
4601 --emul-toc with the first session. See -compliance no_emul_toc.
4602 --sort-weight gets as parameters a number and an iso_rr_path.
4603 The number becomes the LBA sorting weight of regular file
4604 iso_rr_path or of all regular files underneath directory
4605 iso_rr_path. (See -find -exec sort_weight).
4606 Adopted from grub-mkisofs are --protective-msdos-label (see
4607 -boot_image grub partition_table=on) and
4608 --modification-date=YYYYMMDDhhmmsscc (see -volume_date uuid).
4609 For EFI bootable GRUB boot images use --efi-boot. It performs
4610 -boot_image grub efi_path= surrounded by two -boot_image "any"
4611 "next". Alternative option -e from Fedora genisoimage sets
4612 bin_path and platform_id for EFI, but performs no "next".
4613 For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE,
4614 where FILE is one of the Syslinux files mbr/isohdp[fp]x*.bin .
4615 Use this instead of -G to apply the effect of -boot_image
4616 isolinux partition_table=on.
4617 --boot-catalog-hide is -boot_image any cat_hidden=on.
4618 -mips-boot is the same as -boot_image any mips_path= .
4619 -mipsel-boot leads to mipsel_path= .
4620 -partition_offset number is -boot_image any
4621 partition_offset=number.
4622 Command -append_partition is supported.
4623 -untranslated_name_len number is -compliance
4624 untranslated_name_len=number.
4625 --old-empty is -compliance old_empty.
4626 The options of genisoimage Jigdo Template Extraction are
4627 recognized and performed via xorriso command -jigdo. See the
4628 "Alias:" names there for the meaning of the genisoimage options.
4629 Personalities "xorrisofs", "genisoimage", and "genisofs" are
4631 aliases for "mkisofs".
4632 If xorriso is started with one of the leafnames "xorrisofs",
4633 "genisofs", "mkisofs", or "genisoimage", then it performs
4634 -read_mkisofsrc and prepends -as "genisofs" to the program
4635 arguments. I.e. all arguments will be interpreted mkisofs style
4636 until "--" is encountered. From then on, arguments are
4637 interpreted as xorriso commands.
4638 --no_rc as first argument of such a program start prevents
4639 interpretation of startup files. See section FILES below.
4640 Personality "cdrecord" accepts the options listed with:
4642 -as cdrecord -help --
4643 Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip,
4644 padsize=, tsize=, -isosize, -multi, -msinfo,
4645 --grow_overwriteable_iso, write_start_address=, track source
4646 file path or "-" for standard input as track source.
4647 It ignores most other options of cdrecord and cdrskin but
4648 refuses on -audio, -scanbus, and on blanking modes unknown to
4649 xorriso.
4650 The scope is only a single data track per session to be written
4651 to blank, overwritable, or appendable media. The medium gets
4652 closed if closing is applicable and not option -multi is
4653 present.
4654 If an input drive was acquired, then it is given up. This is
4655 only allowed if no image changes are pending.
4656 dev= must be given as xorriso device address. Addresses like
4657 0,0,0 or ATA:1,1,0 are not supported.
4658 If a track source is given, then an automatic -commit happens at
4659 the end of the "cdrecord" option list.
4660 --grow_overwriteable_iso enables emulation of multi-session on
4661 overwritable media. To enable emulation of a TOC, the first
4662 session needs -C 0,32 with -as mkisofs (but no -M) and
4663 --grow_overwriteable_iso write_start_address=32s with -as
4664 cdrecord.
4665 A much more elaborate libburn based cdrecord emulator is the
4666 program cdrskin.
4667 Personalites "xorrecord", "wodim", and "cdrskin" are aliases for
4668 "cdrecord".
4669 If xorriso is started with one of the leafnames "xorrecord",
4670 "cdrskin", "cdrecord", or "wodim", then it automatically
4671 prepends -as "cdrskin" to the program arguments. I.e. all
4672 arguments will be interpreted cdrecord style until "--" is
4673 encountered. From then on, arguments are interpreted as xorriso
4674 commands.
4675 --no_rc as first argument of such a program start prevents
4676 interpretation of xorriso startup files. See section FILES
4677 below.
4678 -read_mkisofsrc
4680 Try one by one to open for reading:
4681 ./.mkisofsrc , $MKISOFSRC , $HOME/.mkisofsrc , $(dirname
4682 $0)/.mkisofsrc
4683 On success interpret the file content as of man mkisofs
4684 CONFIGURATION, and end this command. Do not try further files.
4685 The last address is used only if start argument 0 has a
4686 non-trivial dirname.
4687 The reader currently interprets the following NAME=VALUE pairs:
4688 APPI (-application_id) , PUBL (-publisher) , SYSI (-system_id) ,
4689 VOLI (-volid) , VOLS (-volset_id)
4690 Any other lines will be silently ignored.
4691 -pacifier behavior_code
4693 Control behavior of UPDATE pacifiers during write operations.
4694 The following behavior codes are defined:
4695 "xorriso" is the default format:
4696 Writing: sector XXXXX of YYYYYY [fifo active, nn% fill]
4697 "cdrecord" looks like:
4698 X of Y MB written (fifo nn%) [buf mmm%]
4699 "mkisofs"
4700 nn% done, estimate finish Tue Jul 15 20:13:28 2008
4701 The frequency of the messages can be adjusted by
4702 "interval=number"
4703 where number gives the seconds between two messages. Permissible
4704 settings are 0.1 to 60.0.
4705 -scdbackup_tag list_path record_name
4707 Set the parameter "name" for a scdbackup checksum record. It
4708 will be appended in an scdbackup checksum tag to the -md5
4709 session tag if the image starts at LBA 0. This is the case if it
4710 gets written as first session onto a sequential medium, or piped
4711 into a program, named pipe or character device.
4712 If list_path is not empty then the record will also be appended
4713 to the data file given by this path.
4714 Program scdbackup_verify will recognize and verify tag and file
4715 record.
4716 An empty record_name disables this feature.
4717 Scripting, dialog and program control features:
4719 -no_rc
4721 Only if used as first program argument this command prevents
4722 reading and interpretation of startup files. See section FILES
4723 below.
4724 -options_from_file fileaddress
4726 Read quoted input from fileaddress and execute it like dialog
4727 lines. Empty lines and lines which begin by # are ignored.
4728 Normally one line should hold one xorriso command and all its
4729 parameters. Nevertheless lines may be concatenated by a
4730 trailing backslash.
4731 See also section "Command processing", paragraph "Quoted input".
4732 -help
4734 Print helptext.
4735 -version
4737 Print program name and version, component versions, license.
4738 -list_extras code
4740 Tell whether certain extra features were enabled at compile
4741 time. Code "all" lists all features and a headline. Other
4742 codes pick a single feature. Code "codes" lists them. They
4743 share names with related commands (see also there):
4744 "acl" tells whether xorriso has an adapter for local filesystems
4745 ACLs.
4746 "xattr" tells whether xorriso has an adapter for local
4747 filesystems EA.
4748 "jigdo" tells whether production of Jigdo files is possible.
4749 "zisofs" tells whether zisofs and built-in gzip filters are
4750 enabled.
4751 "external_filter" tells whether external filter processes are
4752 allowed and whether they are allowed if real user id and
4753 effective user id differ.
4754 "dvd_obs" tells whether 64 kB output to DVD media is default.
4755 "use_readline" tells whether readline may be enabled in dialog
4756 mode.
4757 -history textline
4759 Copy textline into libreadline history.
4760 -status mode|filter
4762 Print the current settings of xorriso. Modes:
4763 short... print only important or altered settings
4764 long ... print all settings including defaults
4765 long_history like long plus history lines
4766 Filters begin with '-' and are compared literally against the
4767 output lines of -status:long_history. A line is put out only if
4768 its start matches the filter text. No wildcards.
4769 -status_history_max number
4771 Set maximum number of history lines to be reported with -status
4772 "long_history".
4773 -list_delimiter word
4775 Set the list delimiter to be used instead of "--". It has to be
4776 a single word, must not be empty, not longer than 80 characters,
4777 and must not contain quotation marks.
4778 For brevity the list delimiter is referred as "--" throughout
4779 this text.
4780 -sh_style_result "on"|"off"
4782 Make the result output of some filesystem inspection commands
4783 look more like the output of equivalent shell commands. The most
4784 important effect is to prevent the wrapping of file addresses
4785 into quotation marks with commands
4786 -pwd -pwdx -ls -lsd -lsl -lsdl -lsx -lsdx -lslx -lsdlx
4787 -du -dus -dux -dusx -findx -find
4788 This will make ambiguous the representation of file names which
4789 contain newline characters. On the other hand it should
4790 facilitate integration of xorriso into shell scripts which
4791 already use the corresponding shell commands.
4792 -backslash_codes "on"|"off"|mode[:mode]
4794 Enable or disable the interpretation of symbolic representations
4795 of special characters with quoted input, or with program
4796 arguments, or with program text output. If enabled the following
4797 translations apply:
4798 \a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014)
4799 \n=linefeed(012) \r=carriage_return(015) \t=tab(011)
4800 \v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code
4801 \x[0-9a-f][0-9a-f]=hex_code \cC=control-C
4802 Translations can occur with quoted input in 3 modes:
4803 "in_double_quotes" translates only inside " quotation.
4804 "in_quotes" translates inside " and ' quotation.
4805 "with_quoted_input" translates inside and outside quotes.
4806 With the start program arguments there is mode:
4807 "with_program_arguments" translates program arguments.
4808 Mode "encode_output" encodes output characters. It combines
4809 "encode_results" with "encode_infos". Inside single or double
4810 quotation marks encoding applies to 8-bit characters octal 001
4811 to 037 , 177 to 377 and to backslash(134). Outside quotation
4812 marks some harmless ASCII control characters stay unencoded:
4813 bell(007), backspace(010), tab(011), linefeed(012),
4814 formfeed(014), carriage_return(015).
4815 Mode "off" is default and disables any translation. Mode "on"
4816 is "with_quoted_input:with_program_arguments:encode_output".
4817 -temp_mem_limit number["k"|"m"]
4819 Set the maximum size of temporary memory to be used for image
4820 dependent buffering. Currently this applies to pattern
4821 expansion, LBA sorting, restoring of hard links.
4822 Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1
4823 GiB.
4824 -print text
4826 Print a text line to the result channel which is by default
4827 stdout.
4828 -print_info text
4830 Print a text line to the info channel which is by default
4831 stderr.
4832 -print_mark text
4834 Print a text line to the mark channel which is by default
4835 directed to both, result and info channel. An empty text will
4836 cause no output at all.
4837 -prompt text
4839 Show text at beginning of output line and wait for the user to
4840 hit the Enter key or to send a line via stdin.
4841 -sleep seconds
4843 Wait for the given number of seconds before performing the next
4844 command. Expect coarse granularity no better than 1/100
4845 seconds.
4846 -errfile_log mode path|channel
4848 If problem events are related to input files from the
4849 filesystem, then their disk_paths can be logged to a file or to
4850 output channels R or I.
4851 Mode can either be "plain" or "marked". The latter causes marker
4852 lines which give the time of log start, burn session start, burn
4853 session end, log end or program end. In mode "plain", only the
4854 file paths are logged.
4855 If path is "-" or "-R" then the log is directed to the result
4856 channel. Path "-I" directs it to the info message channel. Any
4857 text that does not begin with "-" is used as path for a file to
4858 append the log lines.
4859 Problematic files can be recorded multiple times during one
4860 program run. If the program run aborts then the list might not
4861 be complete because some input files might not have been
4862 processed at all.
4863 The errfile paths are transported as messages of very low
4864 severity "ERRFILE". This transport becomes visible with
4865 -report_about "ALL".
4866 -session_log path
4868 If path is not empty it gives the address of a plain text file
4869 where a log record gets appended after each session. This log
4870 can be used to determine the start_lba of a session for mount
4871 options -o sbsector= (on GNU/Linux) or -s (on FreeBSD) from date
4872 or volume ID.
4873 Record format is: timestamp start_lba size volume-id
4874 The first three items are single words, the rest of the line is
4875 the volume ID.
4876 -scsi_log "on"|"off"
4878 Mode "on" enables very verbose logging of SCSI commands and
4879 drive replies. Logging messages get printed to stderr, not to
4880 any of the xorriso output channels.
4881 A special property of this command is that the first -scsi_log
4882 setting among the start arguments is in effect already when the
4883 first operations of xorriso begin. Only "-scsi_log" with dash
4884 "-" is recognized that way.
4885 -end
4887 End program after writing pending changes.
4888 -rollback_end
4890 Discard pending changes. End program immediately.
4891 # any text
4893 Only in dialog or file execution mode, and only as first
4894 non-whitespace in line: Do not execute the line but store it in
4895 readline history.
4896 Support for frontend programs via stdin and stdout:
4898 -pkt_output "on"|"off"
4900 Consolidate text output on stdout and classify each line by a
4901 channel indicator:
4902 'R:' for result lines,
4903 'I:' for notes and error messages,
4904 'M:' for -mark texts.
4905 Next is a decimal number of which only bit 0 has a meaning for
4906 now. 0 means no newline at end of payload, 1 means that the
4907 newline character at the end of the output line belongs to the
4908 payload. After another colon and a blank follows the payload
4909 text.
4910 Example:
4911 I:1: enter option and parameters :
4912 -logfile channel fileaddress
4914 Copy output of a channel to the given file. Channel may be one
4915 of: "." for all channels, "I" for info messages, "R" for result
4916 lines, "M" for -mark texts.
4917 -mark text
4919 If text is not empty it will get put out on "M" channel each
4920 time xorriso is ready for the next dialog line or before xorriso
4921 performs a command that was entered to the pager prompt.
4922 -msg_op opcode parameter_text
4924 This command shall facilitate extraction of particular
4925 information from the message output of other commands. It gives
4926 access to the C API function Xorriso_parse_line() and to the
4927 message sieve that is provided by the C API. Please refer to
4928 their descriptions in file xorriso.h. Further it helps to
4929 interpret the severity codes of info messages.
4930 Intended users are frontend programs which operate xorriso in
4931 dialog mode.
4932 The result output of this command is not caught by the message
4933 sieve.
4934 The following opcodes are defined:
4935 start_sieve
4936 Install the message sieve as of Xorriso_sieve_big() and start
4937 watching program messages. The parameter_text has no meaning.
4938 show_sieve
4939 Show a list of filter rule names. The parameter_text has no
4940 meaning. The list begins by a line with the return value of
4941 Xorriso_sieve_get_result() with flag bit3. If this value is
4942 larger than 0, then the next line tells the number of names. The
4943 following lines show one name each.
4944 read_sieve
4945 Use the parameter_text as name of a filter rule and inquire its
4946 next recorded result. See Xorriso_sieve_big() for a list of
4947 names and reply strings.
4948 The recorded strings are put out on result channel. They get
4949 wrapped into lines which tell their structure. The first line
4950 tells the return value of Xorriso_sieve_get_result(). The next
4951 line tells the number of strings. Each string begins by a line
4952 that tells the number of lines of the string. Then follow these
4953 lines. They are to be concatenated with a newline character
4954 between each of them. Finally the number of still available
4955 recorded results of the given name is put out.
4956 clear_sieve
4957 Dispose all recorded strings and continue watching program
4958 messages. The parameter_text has no meaning.
4959 end_sieve
4960 Dispose the sieve with its filter rules and stop watching
4961 program messages. The parameter_text has no meaning.
4962 parse
4963 Read a text from dialog input and submit it to
4964 Xorriso_parse_line(). The parameter_text word shall consist of
4965 several words separated by blanks. It will be necessary to use
4966 both kinds of quotation marks.
4967 E.g. "'ISO session :' '' 0 0 1"
4968 The five parameter words are: prefix, separators, max_words,
4969 flag, number_of_input_lines. The former four are handed over to
4970 Xorriso_parse_line(). The number of input lines minus one tells
4971 xorriso how many newline characters are part of the input text.
4972 The announced number of text lines will be read from dialog
4973 input, concatenated with a newline character between each of
4974 them, and submitted to Xorriso_parse_line() as parameter line.
4975 Note that newlines outside of quotation marks are interpreted as
4976 separators if the separators parameter is empty.
4977 The parsed strings are put out on result channel. They get
4978 wrapped into lines which tell their structure. The first line
4979 tells the return value of Xorriso_parse_line(). The next line
4980 tells the number of strings. Each string begins by a line that
4981 tells the number of lines of the string. Then follow these
4982 lines. They are to be concatenated with a newline character
4983 between each of them.
4984 If -backslash_codes "encode_output" is enabled, then the strings
4985 undergo encoding as if they were enclosed in quotes. Escpecially
4986 each string will be put out as a single result line.
4987 parse_bulk
4988 Like "parse", but with the fifth parameter word being
4989 number_of_input_texts rather than number_of_input_lines. Each
4990 input text has to be preceded by a line that tells
4991 number_of_input_lines as with "parse". Then come the announced
4992 number of text lines.
4993 All input texts will be read before printing of result lines
4994 begins. This consumes memory in xorriso. So the
4995 number_of_input_texts should not be extremely high. On the other
4996 hand, large transactions of command, input texts, and results
4997 are desirable if connection latency is an issue.
4998 parse_silently
4999 Like "parse" but not issuing a prompting message. Confusing to
5000 humans.
5001 parse_bulk_silently
5002 Like "parse_bulk" but not issuing a prompting message. Confusing
5003 to humans.
5004 compare_sev
5005 The parameter_text should contain two comma separated severity
5006 texts as issued by this program. Like "SORRY,UPDATE". See also
5007 paragraph "Exception processing".
5008 These two severity texts get compared and a number gets printed
5009 to the result channel. This number is 0 if both severities are
5010 equal. It is -1 if the first severity is lower than the second
5011 one. It is 1 is the first severity is higher than the second
5012 one.
5013 Above example "SORRY,UPDATE" will yield 1.
5014 list_sev
5015 Print to the result channel a blank separated list of all
5016 severity names. Sorted from low to high severity.
5017 -named_pipe_loop mode[:mode] disk_path_stdin disk_path_stdout
5019 disk_path_stderr
5020 Temporarily replace standard input, standard output and standard
5021 error by named pipes. Enter dialog mode without readline.
5022 Defined modes are:
5023 "cleanup" removes the submitted pipe files when the loop ends.
5024 "keep" does not delete them. This is the default.
5025 "buffered" reads all lines from the input pipe until EOF before
5026 it opens the output pipes and processes the input lines.
5027 "direct" opens the output pipes after the first input line was
5028 read. Each line is executed directly after it is read. This is
5029 the default.
5030 The other three parameters must either be disk paths to existing
5031 named pipes, or be "-" to leave the according standard i/o
5032 channel unreplaced.
5033 xorriso will open the stdin pipe, read and execute dialog lines
5034 from it until the sender closes the pipe. The output pipes get
5035 opened depending on mode "buffered" or "direct". After all lines
5036 are executed, xorriso will close its side of the pipes and enter
5037 a new cycle of opening, reading and executing.
5038 If an input line consists only of the word "end_named_pipe_loop"
5039 then -named_pipe_loop will end and further xorriso commands may
5040 be executed from other sources.
5041 -launch_frontend program [arguments ...] --
5043 Start the program that is given as first parameter. Submit the
5044 other parameters as program arguments. Enable xorriso dialog
5045 mode.
5046 Two nameless pipe objects are created. xorriso standard input
5047 gets connected to the standard output of the started program.
5048 xorriso standard output and standard error get connected to the
5049 standard input of that program.
5050 xorriso will abort when the started program ends or if it cannot
5051 be started at all. In both cases it will return a non-zero exit
5052 value. The exit value will be zero if the frontend sends -end
5053 or -rollback_end before ending itself.
5054 This command may be totaly banned at compile time. It is banned
5055 by default if xorriso runs under setuid permissions.
5056 The program name will not be searched in the $PATH directories.
5057 To make this clear, it must contain at least one /-character.
5058 Best is an absolute path.
5059 Example:
5060 xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio --
5061 The frontend program should first send via its standard output:
5062 -mark 0 -pkt_output on -msg_op start_sieve - -reassure off
5063 It should be ready to decode -pkt_output and to react on -mark
5064 messages. Best is to increment the -mark number after each sent
5065 command sequence and then to wait for the new number to show up
5066 in a mark message:
5067 ...some...commands... -mark <incremented_number>
5068 Further are advised:
5069 -report_about UPDATE -abort_on NEVER
5070 -iso_rr_pattern off -disk_pattern off
5071 A check of the xorriso version should be done, in order to make
5072 sure that all desired features are present.
5073 Command -launch_frontend will only work once per xorriso run.
5074 If no command parameters are submitted or if program is an empty
5075 text, then no program will be started but nevertheless
5076 -launch_frontend will be irrevocably disabled.
5077 -prog text
5079 Use text as name of this program in subsequent messages
5080 -prog_help text
5082 Use text as name of this program and perform -help.
5083
5085 Overview of examples:
5086 As superuser learn about available drives
5087 Blank medium and compose a new ISO image as batch run
5088 A dialog session doing about the same
5089 Manipulate an existing ISO image on the same medium
5090 Copy modified ISO image from one medium to another
5091 Bring a prepared ISOLINUX tree onto medium and make it bootable
5092 Change existing file name tree from ISO-8859-1 to UTF-8
5093 Operate on storage facilities other than optical drives
5094 Burn an existing ISO image file to medium
5095 Perform multi-session runs as of cdrtools traditions
5096 Let xorriso work underneath growisofs
5097 Adjust thresholds for verbosity, exit value and program abort
5098 Examples of input timestrings
5099 Incremental backup of a few directory trees
5100 Restore directory trees from a particular ISO session to disk
5101 Try to retrieve blocks from a damaged medium
5102 As superuser learn about available drives
5104 On Linux, FreeBSD or NetBSD consider to give rw-permissions to those
5105 users or groups which shall be able to use the drives with xorriso. On
5106 Solaris use pfexec. Consider to restrict privileges of xorriso to
5107 "base,sys_devices" and to give r-permission to user or group.
5108 $ xorriso -device_links
5109 1 -dev '/dev/cdrom1' rwrw-- : 'TSSTcorp' 'DVD-ROM SH-D162C
5110 1 -dev '/dev/cdrw' rwrw-- : 'TSSTcorp' 'CDDVDW SH-S223B'
5111 2 -dev '/dev/cdrw3' rwrw-- : 'HL-DT-ST' 'BDDVDRW_GGC-H20L'
5112 Blank medium and compose a new ISO image as batch run
5114 Acquire drive /dev/sr2, make medium ready for writing a new image, fill
5115 the image with the files from hard disk directories /home/me/sounds and
5116 /home/me/pictures.
5117 Because no -dialog "on" is given, the program will then end by writing
5118 the session to the medium.
5119 $ xorriso -outdev /dev/sr2 \
5120 -blank as_needed \
5121 -map /home/me/sounds /sounds \
5122 -map /home/me/pictures /pictures
5123 The ISO image may be shaped in a more elaborate way like the following:
5125 Omit some unwanted stuff by removing it from the image directory tree.
5126 Reintroduce some wanted stuff.
5127 $ cd /home/me
5128 $ xorriso -outdev /dev/sr2 \
5129 -blank as_needed \
5130 -map /home/me/sounds /sounds \
5131 -map /home/me/pictures /pictures \
5132 -rm_r \
5133 /sounds/indecent \
5134 '/pictures/*private*' \
5135 /pictures/confidential \
5136 -- \
5137 -cd / \
5138 -add pictures/confidential/work* --
5139 Note that '/pictures/*private*' is a pattern for iso_rr_paths while
5140 pictures/confidential/work* gets expanded by the shell with addresses
5141 from the hard disk. Commands -add and -map have different parameter
5142 rules but finally the same effect: they put files into the image.
5143 A dialog session doing about the same
5145 Some settings are already given as start argument. The other activities
5146 are done as dialog input. The pager gets set to 20 lines of 80
5147 characters.
5148 The drive is acquired by command -dev rather than -outdev in order to
5149 see the message about its current content. By command -blank this
5150 content is made ready for being overwritten and the loaded ISO image is
5151 made empty.
5152 In order to be able to eject the medium, the session needs to be
5153 committed explicitly.
5154 $ xorriso -dialog on -page 20 80 -disk_pattern on
5155 enter option and arguments :
5156 -dev /dev/sr2
5157 enter option and arguments :
5158 -blank as_needed
5159 enter option and arguments :
5160 -map /home/me/sounds /sounds -map /home/me/pictures /pictures
5161 enter option and arguments :
5162 -rm_r /sounds/indecent /pictures/*private* /pictures/confidential
5163 enter option and arguments :
5164 -cdx /home/me/pictures -cd /pictures
5165 enter option and arguments :
5166 -add confidential/office confidential/factory
5167 enter option and arguments :
5168 -du /
5169 enter option and arguments :
5170 -commit_eject all -end
5171 Manipulate an existing ISO image on the same medium
5173 Load image from drive. Remove (i.e. hide) directory /sounds and its
5174 subordinates. Rename directory /pictures/confidential to
5175 /pictures/restricted. Change access permissions of directory
5176 /pictures/restricted. Add new directory trees /sounds and /movies.
5177 Burn to the same medium, check whether the tree can be loaded, and
5178 eject.
5179 $ xorriso -dev /dev/sr2 \
5180 -rm_r /sounds -- \
5181 -mv \
5182 /pictures/confidential \
5183 /pictures/restricted \
5184 -- \
5185 -chmod go-rwx /pictures/restricted -- \
5186 -map /home/me/prepared_for_dvd/sounds_dummy /sounds \
5187 -map /home/me/prepared_for_dvd/movies /movies \
5188 -commit -eject all
5189 Copy modified ISO image from one medium to another
5191 Load image from input drive. Do the same manipulations as in the
5192 previous example. Acquire output drive and blank it. Burn the modified
5193 image as first and only session to the output drive.
5194 $ xorriso -indev /dev/sr2 \
5195 -rm_r /sounds -- \
5196 ...
5197 -outdev /dev/sr0 -blank as_needed \
5198 -commit -eject all
5199 Bring a prepared ISOLINUX tree onto medium and make it bootable
5201 The user has already created a suitable file tree on disk and copied
5202 the ISOLINUX files into subdirectory ./boot/isolinux of that tree. Now
5203 xorriso can burn an El Torito bootable medium:
5204 $ xorriso -outdev /dev/sr0 -blank as_needed \
5205 -map /home/me/ISOLINUX_prepared_tree / \
5206 -boot_image isolinux dir=/boot/isolinux
5207 Change existing file name tree from ISO-8859-1 to UTF-8
5209 This example assumes that the existing ISO image was written with
5210 character set ISO-8859-1 but that the readers expected UTF-8. Now a new
5211 session gets added with converted file names. Command -changes_pending
5212 "yes" enables writing despite the lack of any manipulation command.
5213 In order to avoid any weaknesses of the local character set, this
5214 command pretends that it uses already the final target set UTF-8.
5215 Therefore strange file names may appear in messages, which will be made
5216 terminal-safe by command -backslash_codes.
5217 $ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
5218 -out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
5219 -changes_pending yes -commit -eject all
5220 Operate on storage facilities other than optical drives
5222 Full read-write operation is possible with regular files and block
5223 devices:
5224 $ xorriso -dev /tmp/regular_file ...
5225 Paths underneath /dev normally need prefix "stdio:"
5226 $ xorriso -dev stdio:/dev/sdb ...
5227 If /dev/sdb is to be used frequently and /dev/sda is the system disk,
5228 then consider to place the following lines in a xorriso Startup File.
5229 They allow you to use /dev/sdb without prefix and protect disk /dev/sda
5230 from xorriso:
5231 -drive_class banned /dev/sda*
5232 -drive_class harmless /dev/sdb
5233 Other writeable file types are supported write-only:
5234 $ xorriso -outdev /tmp/named_pipe ...
5235 Among the write-only drives is standard output:
5236 $ xorriso -outdev - \
5237 ...
5238 | gzip >image.iso.gz
5239 Burn an existing ISO image file to medium
5241 Actually this works with any kind of data, not only ISO images:
5242 $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso
5243 Perform multi-session runs as of cdrtools traditions
5245 Between both processes there can be performed arbitrary transportation
5246 or filtering.
5247 The first session is written like this:
5248 $ xorriso -as mkisofs prepared_for_iso/tree1 | \
5249 xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
5250 Follow-up sessions are written like this (the run of dd is only to give
5251 demons a chance to spoil it):
5252 $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
5253 $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
5254 $ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \
5255 xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
5256 Always eject the drive tray between sessions.
5257 The run of xorriso -as mkisofs will read old sessions via the CD-ROM
5258 driver of /dev/sr0. This driver might not be aware of the changed
5259 content as long as the medium is not loaded again. In this case the
5260 previous session would not be properly assessed by xorriso and the new
5261 session would contain only the newly added files.
5262 Some systems have not enough patience with automatic tray loading and
5263 some demons may interfere with a first CD-ROM driver read attempt from
5264 a freshly loaded medium.
5265 When loading the tray manually, wait 10 seconds after the drive has
5266 stopped blinking.
5267 A safe automatic way seems to be a separate run of xorriso for loading
5268 the tray with proper waiting, and a subsequent run of dd which shall
5269 offer itself to any problems caused by demons assessing the changed
5270 drive status. If this does not help, insert a run of "sleep 10"
5271 between xorriso and dd.
5272 This example works for multi-session media only. Add cdrskin option
5273 --grow_overwriteable_iso to all -as cdrecord runs in order to enable
5274 multi-session emulation on overwritable media.
5275 Let xorriso work underneath growisofs
5277 growisofs expects an ISO formatter program which understands options -C
5278 and -M. If xorriso gets started by name "xorrisofs" then it is suitable
5279 for that.
5280 $ export MKISOFS="xorrisofs"
5281 $ growisofs -Z /dev/dvd /some/files
5282 $ growisofs -M /dev/dvd /more/files
5283 If no "xorrisofs" is available on your system, then you will have to
5284 create a link pointing to the xorriso binary and tell growisofs to use
5285 it. E.g. by:
5286 $ ln -s $(which xorriso) "$HOME/xorrisofs"
5287 $ export MKISOFS="$HOME/xorrisofs"
5288 One may quit mkisofs emulation by argument "--" and make use of all
5289 xorriso commands. growisofs dislikes options which start with "-o" but
5290 -outdev must be set to "-". So use "outdev" instead:
5291 $ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files
5292 $ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files
5293 growisofs has excellent burn capabilities with DVD and BD. It does not
5294 emulate session history on overwritable media, though.
5295 Adjust thresholds for verbosity, exit value and program abort
5297 Be quite verbose, exit 32 if severity "FAILURE" was encountered, do not
5298 abort prematurely but forcibly go on until the end of commands.
5299 $ xorriso ... \
5300 -report_about UPDATE \
5301 -return_with FAILURE 32 \
5302 -abort_on NEVER \
5303 ...
5304 Examples of input timestrings
5306 As printed by program date: 'Thu Nov 8 14:51:13 CET 2007'
5307 The same without ignored parts: 'Nov 8 14:51:13 2007'
5308 The same as expected by date: 110814512007.13
5309 Four weeks in the future: +4w
5310 The current time: +0
5311 Three hours ago: -3h
5312 Seconds since Jan 1 1970: =1194531416
5313 Incremental backup of a few directory trees
5315 This changes the directory trees /projects and /personal_mail in the
5316 ISO image so that they become exact copies of their disk counterparts.
5317 ISO file objects get created, deleted or get their attributes adjusted
5318 accordingly.
5319 ACL, xattr, hard links and MD5 checksums will be recorded. Accelerated
5320 comparison is enabled at the expense of potentially larger backup size.
5321 Only media with the expected volume ID or blank media are accepted.
5322 Files with names matching *.o or *.swp get excluded explicitly.
5323 When done with writing the new session gets checked by its recorded
5324 MD5.
5325 $ xorriso \
5326 -abort_on FATAL \
5327 -for_backup -disk_dev_ino on \
5328 -assert_volid 'PROJECTS_MAIL_*' FATAL \
5329 -dev /dev/sr0 \
5330 -volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
5331 -not_leaf '*.o' -not_leaf '*.swp' \
5332 -update_r /home/thomas/projects /projects \
5333 -update_r /home/thomas/personal_mail /personal_mail \
5334 -commit -toc -check_md5 FAILURE -- -eject all
5335 To be used several times on the same medium, whenever an update of the
5336 two disk trees to the medium is desired. Begin with a blank medium and
5337 update it until the run fails gracefully due to lack of remaining space
5338 on the old one.
5339 This makes sense if the full backup leaves substantial remaining
5340 capacity on media and if the expected changes are much smaller than the
5341 full backup. To apply zisofs compression to those data files which get
5342 newly copied from the local filesystem, insert these commands
5343 immediately before -commit :
5344 -hardlinks perform_update \
5345 -find / -type f -pending_data -exec set_filter --zisofs -- \
5346 Commands -disk_dev_ino and -for_backup depend on stable device and
5347 inode numbers on disk. Without them, an update run may use -md5 "on" to
5348 match recorded MD5 sums against the current file content on hard disk.
5349 This is usually much faster than the default which compares both
5350 contents directly.
5351 With mount option -o "sbsector=" on GNU/Linux or -s on FreeBSD or
5352 NetBSD it is possible to access the session trees which represent the
5353 older backup versions. With CD media, GNU/Linux mount accepts session
5354 numbers directly by its option "session=".
5355 Multi-session media and most overwritable media written by xorriso can
5356 tell the sbsectors of their sessions by xorriso command -toc. Used
5357 after -commit the following command prints the matching mount command
5358 for the newly written session (here for mount point /mnt):
5359 -mount_cmd "indev" "auto" "auto" /mnt
5360 Commands -mount_cmd and -mount are also able to produce the mount
5361 commands for older sessions in the table-of-content. E.g. as superuser:
5362 # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
5363 Above example produces a result similar to -root / -old-root / with
5365 mkisofs. For getting the session trees accumulated in the new
5366 sessions, let all -update commands use a common parent directory and
5367 clone it after updating is done:
5368 -update_r /home/thomas/projects /current/projects \
5369 -update_r /home/thomas/personal_mail /current/personal_mail \
5370 -clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \
5371 The cloned tree will have a name like /2011_02_12_155700.
5372 Sessions on multi-session media are separated by several MB of unused
5374 blocks. So with small sessions the payload capacity can become
5375 substantially lower than the overall media capacity. If the remaining
5376 space on a medium does not suffice for the next gap, the drive is
5377 supposed to close the medium automatically.
5378 Better do not use your youngest backup for -update_r. Have at least
5380 two media which you use alternatingly. So only older backups get
5381 endangered by the new write operation, while the newest backup is
5382 stored safely on a different medium.
5383 Always have a blank medium ready to perform a full backup in case the
5384 update attempt fails due to insufficient remaining capacity. This
5385 failure will not spoil the old medium, of course.
5386 Restore directory trees from a particular ISO session to disk
5388 This is an alternative to mounting the medium and using normal file
5389 operations.
5390 First check which backup sessions are on the medium:
5391 $ xorriso -outdev /dev/sr0 -toc
5392 Then enable restoring of ACL, xattr and hard links. Load the desired
5393 session and copy the file trees to disk. Avoid to create
5394 /home/thomas/restored without rwx-permission.
5395 $ xorriso -for_backup \
5396 -load volid 'PROJECTS_MAIL_2008_06_19*' \
5397 -indev /dev/sr0 \
5398 -osirrox on:auto_chmod_on \
5399 -chmod u+rwx / -- \
5400 -extract /projects /home/thomas/restored/projects \
5401 -extract /personal_mail /home/thomas/restored/personal_mail \
5402 -rollback_end
5403 The final command -rollback_end prevents an error message about the
5404 altered image being discarded.
5405 Try to retrieve blocks from a damaged medium
5407 $ xorriso -abort_on NEVER -indev /dev/sr0 \
5408 -check_media time_limit=1800 report=blocks_files \
5409 data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --
5410 This can be repeated several times, if necessary with -eject or with
5411 other -indev drives. See the human readable part of
5412 "$HOME"/dvd_copy.map for addresses which can be used on
5413 "$HOME"/dvd_copy with mount option -o sbsector= or -s.
5414
5416 Program alias names:
5417 Normal installation of xorriso creates three links or copies which by
5418 their program name pre-select certain settings:
5419 xorrisofs starts xorriso with -as mkisofs emulation.
5420 xorrecord starts xorriso with -as cdrecord emulation.
5421 osirrox starts with -osirrox "on:o_excl_off" which allows further
5422 commands to copy files from ISO image to disk and to apply command
5423 -mount to one or more of the existing ISO sessions.
5424 Startup files:
5426 If not -no_rc is given as the first argument then xorriso attempts on
5427 startup to read and execute lines from the following files:
5428 /etc/default/xorriso
5429 /etc/opt/xorriso/rc
5430 /etc/xorriso/xorriso.conf
5431 $HOME/.xorrisorc
5432 The files are read in the sequence given above, but none of them is
5433 required to exist. The line format is described with command
5434 -options_from_file.
5435 If mkisofs emulation was enabled by program name "xorrisofs",
5436 "mkisofs", "genisoimage", or "genisofs", then afterwards
5437 -read_mkisofsrc is performed, which reads .mkisofsrc files. See there.
5438 Runtime control files:
5440 The default setting of -check_media abort_file= is:
5441 /var/opt/xorriso/do_abort_check_media
5442
5445 The following environment variables influence the program behavior:
5446 HOME is used to find startup files of xorriso and mkisofs.
5447 SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. It
5448 is supposed to be either undefined or to contain a decimal number which
5449 tells the seconds since january 1st 1970. If it contains a number, then
5450 it is used as time value to set the default of -volume date "uuid",
5451 sets -boot_image "any" "gpt_disk_guid=" to "volume_date_uuid",
5452 -volume_date "all_file_dates" to "set_to_mtime", and -iso_nowtime to
5453 "=$SOURCE_DATE_EPOCH".
5454 Startup files and program options can override the effect of
5455 SOURCE_DATE_EPOCH.
5456
5459 For the mkisofs emulation of xorriso
5460 xorrisofs(1)
5461 For the cdrecord emulation of xorriso
5463 xorrecord(1)
5464 For mounting xorriso generated ISO 9660 images (-t iso9660)
5466 mount(8)
5467 Libreadline, a comfortable input line facility
5469 readline(3)
5470 Other programs which produce ISO 9660 images
5472 mkisofs(8), genisoimage(1)
5473 Other programs which burn sessions to optical media
5475 growisofs(1), cdrecord(1), wodim(1), cdrskin(1)
5476 ACL and xattr
5478 getfacl(1), setfacl(1), getfattr(1), setfattr(1)
5479 MD5 checksums
5481 md5sum(1)
5482 On FreeBSD the commands for xattr and MD5 differ
5484 getextattr(8), setextattr(8), md5(1)
5485
5487 To report bugs, request help, or suggest enhancements for xorriso,
5488 please send electronic mail to the public list <bug-xorriso@gnu.org>.
5489 If more privacy is desired, mail to <scdbackup@gmx.net>.
5490 Please describe what you expect xorriso to do, the program arguments or
5491 dialog commands by which you tried to achieve it, the messages of
5492 xorriso, and the undesirable outcome of your program run.
5493 Expect to get asked more questions before solutions can be proposed.
5494
5496 Thomas Schmitt <scdbackup@gmx.net>
5497 for libburnia-project.org
5498
5500 Copyright (c) 2007 - 2023 Thomas Schmitt
5501 Permission is granted to distribute this text freely. It shall only be
5502 modified in sync with the technical properties of xorriso. If you make
5503 use of the license to derive modified versions of xorriso then you are
5504 entitled to modify this text under that same license.
5505
5507 xorriso is in part based on work by Vreixo Formoso who provides
5508 libisofs together with Mario Danic who also leads the libburnia team.
5509 Vladimir Serbinenko contributed the HFS+ filesystem code and related
5510 knowledge. Thanks to Andy Polyakov who invented emulated growing, to
5511 Derek Foreman and Ben Jansens who once founded libburn.
5512 Compliments towards Joerg Schilling whose cdrtools served me for ten
5513 years.
5514 Version 1.5.6, Jun 07, 2023 XORRISO(1)