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