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