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 allows
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 General information paragraphs:
47 Session model
48 Media types and states
49 Creating, Growing, Modifying, Blind Growing
50 Libburn drives
51 Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
52 Command processing
53 Dialog, Readline, Result pager
54 Maybe you first want to have a look at section EXAMPLES near the end of
56 this text before reading the next few hundred lines of background
57 information.
58 Session model:
60 Unlike other filesystems, ISO 9660 is not intended for read-write
61 operation but rather for being generated in a single sweep and being
62 written to media as a session.
63 The data content of the session is called filesystem image.
64 The written image in its session can then be mounted by the operating
66 system for being used read-only. GNU/Linux is able to mount ISO images
67 from block devices, which may represent optical media, other media or
68 via a loop device even from regular disk files. FreeBSD mounts ISO
69 images from devices that represent arbitrary media or from regular disk
70 files.
71 This session usage model has been extended on CD media by the concept
73 of multi-session , which allows to add information to the CD and gives
74 the mount programs of the operating systems the addresses of the entry
75 points of each session. The mount programs recognize block devices
76 which represent CD media and will by default mount the image in the
77 last session.
78 This session usually contains an updated directory tree for the whole
79 medium which governs the data contents in all recorded sessions. So in
80 the view of the mount program all sessions of a particular medium
81 together form a single filesystem image.
82 Adding a session to an existing ISO image is in this text referred as
83 growing.
84 The multi-session model of the MMC standard does not apply to all media
85 types. But program growisofs by Andy Polyakov showed how to extend this
86 functionality to overwriteable media or disk files which carry valid
87 ISO 9660 filesystems.
88 xorriso provides growing as well as an own method named modifying which
90 produces a completely new ISO image from the old one and the
91 modifications. See paragraph Creating, Growing, Modifying, Blind
92 Growing below.
93 xorriso adopts the concept of multi-session by loading an image
95 directory tree if present, by allowing to manipulate it by several
96 actions, and by writing the new image to the target medium.
97 The first session of a xorriso run begins by the definition of the
98 input drive with the ISO image or by the definition of an output drive.
99 The session ends by command -commit which triggers writing. A -commit
100 is done automatically when the program ends regularly.
101 After -commit a new session begins with the freshly written one as
103 input. A new input drive can only be chosen as long as the loaded ISO
104 image was not altered. Pending alteration can be revoked by command
105 -rollback.
106 Writing a session to the target is supposed to be very expensive in
108 terms of time and of consumed space on appendable or write-once media.
109 Therefore all intended manipulations of a particular ISO image should
110 be done in a single session. But in principle it is possible to store
111 intermediate states and to continue with image manipulations.
112 Media types and states:
114 There are two families of media in the MMC standard:
115 Multi-session media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and
116 unformatted DVD-RW. These media provide a table of content which
117 describes their existing sessions. See option -toc.
118 Similar to multi-session media are DVD-R DL and minimally blanked
119 DVD-RW. They allow only a single session of which the size must be
120 known in advance. xorriso will write onto them only if option -close
121 is set to "on".
122 Overwriteable media are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
123 They allow random write access but do not provide information about
124 their session history. If they contain one or more ISO 9660 sessions
125 and if the first session was written by xorriso, then a table of
126 content can be emulated. Else only a single overall session will be
127 visible.
128 DVD-RW media can be formatted by -format "full". They can be made
129 unformatted by -blank "deformat".
130 Regular files and block devices are handled as overwriteable media.
131 Pipes and other writeable file types are handled as blank multi-session
132 media.
133 These media can assume several states in which they offer different
135 capabilities.
136 Blank media can be written from scratch. They contain no ISO image
137 suitable for xorriso.
138 Blank is the state of newly purchased optical media. With used CD-RW
139 and DVD-RW it can be achieved by action -blank "as_needed".
140 Overwriteable media are considered blank if they are new or if they
141 have been marked as blank by xorriso. Action -blank "as_needed" can be
142 used to do this marking on overwriteable media, or to apply mandatory
143 formatting to new media if necessary.
144 Appendable media accept further sessions. Either they are MMC
145 multi-session media in appendable state, or they are overwriteable
146 media which contain an ISO image suitable for xorriso.
147 Appendable is the state after writing a session with option -close off.
148 Closed media cannot be written. They may contain an ISO image suitable
149 for xorriso.
150 Closed is the state of DVD-ROM media and of multi-session media which
151 were written with option -close on. If the drive is read-only hardware
152 then it will probably show any media as closed CD-ROM resp. DVD-ROM.
153 Overwriteable media assume this state in such read-only drives or if
154 they contain unrecognizable data in the first 32 data blocks.
155 Read-only drives may or may not show session histories of multi-session
156 media. Often only the first and the last session are visible. Sometimes
157 not even that. Option -rom_toc_scan might or might not help in such
158 cases.
159 Creating, Growing, Modifying, Blind Growing:
161 A new empty ISO image gets created if there is no input drive with a
162 valid ISO 9660 image when the first time an output drive is defined.
163 This is achieved by option -dev on blank media or by option -outdev on
164 media in any state.
165 The new empty image can be populated with directories and files.
166 Before it can be written, the medium in the output drive must get into
167 blank state if it was not blank already.
168 If there is a input drive with a valid ISO image, then this image gets
170 loaded as foundation for manipulations and extension. The constellation
171 of input and output drive determines which write method will be used.
172 They have quite different capabilities and constraints.
173 The method of growing adds new data to the existing data on the medium.
175 These data comprise of new file content and they override the existing
176 ISO 9660 + Rock Ridge directory tree. It is possible to hide files from
177 previous sessions but they still exist on the medium and with many
178 types of optical media it is quite easy to recover them by mounting
179 older sessions.
180 Growing is achieved by option -dev.
181 The write method of modifying produces compact filesystem images with
183 no outdated files or directory trees. Modifying can write its images to
184 target media which are completely unsuitable for multi-session
185 operations. E.g. DVD-RW which were treated with -blank
186 deformat_quickest, DVD-R DL, named pipes, character devices, sockets.
187 On the other hand modified sessions cannot be written to appendable
188 media but to blank media only.
189 So for this method one needs either two optical drives or has to work
190 with filesystem objects as source and/or target medium.
191 Modifying takes place if input drive and output drive are not the same
192 and if option -grow_blindly is set to its default "off". This is
193 achieved by options -indev and -outdev.
194 If option -grow_blindly is set to a non-negative number and if -indev
196 and -outdev are both set to different drives, then blind growing is
197 performed. It produces an add-on session which is ready for being
198 written to the given block address. This is the usage model of
199 mkisofs -M $indev -C $msc1,$msc2 -o $outdev
200 which gives much room for wrong parameter combinations and should thus
201 only be employed if a strict distinction between ISO formatter xorriso
202 and the burn program is desired. -C $msc1,$msc2 is equivalent to:
203 -load sbsector $msc1 -grow_blindly $msc2
204 Libburn drives:
206 Input drive, i.e. source of an existing or empty ISO image, can be any
207 random access readable libburn drive: optical media with readable data,
208 blank optical media, regular files, block devices.
209 Output drive, i.e. target for writing, can be any libburn drive. Some
211 drive types do not support the method of growing but only the methods
212 of modifying and blind growing. They all are suitable for newly created
213 images.
214 All drive file objects have to offer rw-permission to the user of
215 xorriso. Even those which will not be useable for reading an ISO
216 image.
217 MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed
219 by the path of their block device or of their generic character device.
220 E.g.
221 -dev /dev/sr0
222 -dev /dev/hdc
223 -dev /dev/sg2
224 On FreeBSD the device files have names like
225 -dev /dev/cd0
226 On OpenSolaris:
227 -dev /dev/rdsk/c4t0d0s2
228 Get a list of accessible drives by command
229 -device_links
230 It might be necessary to do this as superuser in order to see all
231 drives and to then allow rw-access for the intended users. Consider to
232 bundle the authorized users in a group like old "floppy".
233 Filesystem objects of nearly any type can be addressed by prefix
235 "stdio:" and their path in the filesystem. E.g.:
236 -dev stdio:/dev/sdc
237 The default setting of -drive_class allows to address files outside the
238 /dev tree without that prefix. E.g.:
239 -dev /tmp/pseudo_drive
240 If path leads to a regular file or to a block device then the emulated
241 drive is random access readable and can be used for the method of
242 growing if it already contains a valid ISO 9660 image. Any other file
243 type is not readable via "stdio:" and can only be used as target for
244 the method of modifying or blind growing. Non-existing paths in
245 existing directories are handled as empty regular files.
246 A very special kind of pseudo drive are open file descriptors. They are
248 depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open).
249 Addresses "-" or "stdio:/dev/fd/1" depict standard output, which
250 normally is the output channel for result texts. To prevent a fatal
251 intermingling of ISO image and text messages, all result texts get
252 redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is among the
253 start arguments of the program.
254 Standard output is currently suitable for creating one session per
255 program run without dialog. Use in other situations is discouraged and
256 several restrictions apply:
257 It is not allowed to use standard output as pseudo drive if it was not
258 among the start arguments. Do not try to fool this ban via backdoor
259 addresses to stdout.
260 If stdout is used as drive, then -use_readline is permanently disabled.
261 Use of backdoors can cause severe memory and/or tty corruption.
262 Be aware that especially the superuser can write into any accessible
264 file or device by using its path with the "stdio:" prefix. By default
265 any address in the /dev tree without prefix "stdio:" will work only if
266 it leads to a MMC drive.
267 One may use option -ban_stdio_write to surely prevent this risk and to
268 allow only MMC drives.
269 One may prepend "mmc:" to a path to surely disallow any automatic
270 "stdio:".
271 By option -drive_class one may ban certain paths or allow access
272 without prefix "stdio:" to other paths.
273 Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
275 Rock Ridge is the name of a set of additional information which enhance
276 an ISO 9660 filesystem so that it can represent a POSIX compliant
277 filesystem with ownership, access permissions, symbolic links, and
278 other attributes.
279 This is what xorriso uses for a decent representation of the disk files
280 within the ISO image. Rock Ridge information is produced with any
281 xorriso image.
282 xorriso is not named "porriso" because POSIX only guarantees 14
284 characters of filename length. It is the X/Open System Interface
285 standard XSI which demands a file name length of up to 255 characters
286 and paths of up to 1024 characters. Rock Ridge fulfills this demand.
287 An El Torito boot record points the BIOS bootstrapping facility to one
289 or more boot images, which are binary program files stored in the ISO
290 image. The content of the boot image files is not in the scope of El
291 Torito.
292 Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot
293 images. xorriso is able to create or maintain an El Torito object
294 which makes such an image bootable. For details see option -boot_image.
295 It is possible to make ISO images bootable from USB stick or other
296 hard-disk-like media by -boot_image argument system_area= . This
297 installs a Master Boot Record which may get adjusted according to the
298 needs of GRUB resp. ISOLINUX. An MBR contains boot code and a
299 partition table. It does not hamper CDROM booting. The new MBR of a
300 follow-up session can get in effect only on overwriteable media.
301 Emulation -as mkisofs supports the example options out of the ISOLINUX
302 wiki, the options used in GRUB script grub-mkrescue, and the example in
303 the FreeBSD AvgLiveCD wiki.
304 There is support for boot facilities other than PC BIOS: EFI, MIPS Big
305 Endian (SGI), MIPS Little Endian (DEC), SUN SPARC.
306 ACL are an advanced way of controlling access permissions to file
308 objects. Neither ISO 9660 nor Rock Ridge specify a way to record ACLs.
309 So libisofs has introduced a standard conformant extension named AAIP
310 for that purpose. It uses this extension if enabled by option -acl.
311 AAIP enhanced images are supposed to be mountable normally, but one
312 cannot expect that the mounted filesystem will show and respect the
313 ACLs. For now, only xorriso is able to retrieve those ACLs. It can
314 bring them into effect when files get restored to an ACL enabled file
315 system or it can print them in a format suitable for tool setfacl.
316 Files with ACL show as group permissions the setting of entry "mask::"
317 if that entry exists. Nevertheless the non-listed group members get
318 handled according to entry "group::". When removing ACL from a file,
319 xorriso brings "group::" into effect.
320 Recording and restoring of ACLs from and to local files works currently
321 only on GNU/Linux and FreeBSD.
322 xattr (aka EA, or extattr) are pairs of name and value which can be
324 attached to file objects. AAIP is able to represent them and xorriso
325 allows to record and restore pairs which have names out of the user
326 namespace. I.e. those which begin with "user.", like "user.x" or
327 "user.whatever". Name has to be a 0 terminated string. Value may be
328 any array of bytes which does not exceed the size of 4095 bytes. xattr
329 processing happens only if it is enabled by option -xattr.
330 As with ACL, currently only xorriso is able to retrieve xattr from AAIP
331 enhanced images, to restore them to xattr capable file systems, or to
332 print them.
333 Recording and restoring of xattr from and to local files works
334 currently only on GNU/Linux and FreeBSD, where they are known as
335 extattr.
336 Command processing:
338 Commands are either actions which happen immediately or settings which
339 influence following actions. So their sequence does matter.
340 Commands consist of a command word, followed by zero or more parameter
341 words. If the list of parameter words is of variable length (indicated
342 by "[...]" or "[***]") then it has to be terminated by either the list
343 delimiter, or the end of argument list, or an end of an input line.
344 At program start the list delimiter is the word "--". This may be
346 changed by option -list_delimiter in order to allow "--" as argument in
347 a list of variable length. It is advised to reset the delimiter to
348 "--" immediately afterwards.
349 For brevity the list delimiter is referred as "--" throughout this
350 text.
351 The list delimiter is silently tolerated if it appears after the
352 parameters of a command with a fixed list length. It is handled as
353 normal text if it appears among the arguments of such a command.
354 Pattern expansion converts a list of pattern words into a list of
356 existing file addresses. Unmatched pattern words appear themselves in
357 that result list, though.
358 Pattern matching supports the usual shell parser wildcards '*' '?'
359 '[xyz]' and respects '/' as separator which may only be matched
360 literally.
361 It is a property of some particular commands and not a general feature.
362 It gets controlled by commands -iso_rr_pattern and -disk_pattern.
363 Commands which may use pattern expansion all have variable argument
364 lists which are marked in this man page by "[***]" rather than "[...]".
365 Some other commands perform pattern matching unconditionally.
366 Command and parameter words are either read from program arguments,
368 where one argument is one word, or from quoted input lines where words
369 are recognized similar to the quotation rules of a shell parser.
370 xorriso is not a shell, although it might appear so on first glimpse.
371 Be aware that the interaction of quotation marks and pattern symbols
372 like "*" differs from the usual shell parsers. In xorriso, a quotation
373 mark does not make a pattern symbol literal.
374 Quoted input converts whitespace separated text pieces into words. The
376 double quotation mark " and the single quotation mark ' can be used to
377 enclose whitespace and make it part of words (e.g. of file names). Each
378 mark type can enclose the marks of the other type. A trailing backslash
379 \ outside quotations or an open quotation cause the next input line to
380 be appended.
381 Quoted input accepts any ASCII character except NUL (0) as content of
382 quotes. Nevertheless it can be cumbersome for the user to produce
383 those characters at all. Therefore quoted input and program arguments
384 allow optional Backslash Interpretation which can represent all ASCII
385 characters except NUL (0) by backslash codes as in $'...' of bash.
386 It is not enabled by default. See option -backslash_codes.
387 When the program starts then it first looks for argument -no_rc. If
389 this is not present then it looks for its startup files and reads their
390 content as command input lines. Then it interprets the program
391 arguments as commands and parameters. Finally it enters dialog mode if
392 command -dialog "on" was executed up to then.
393 The program ends either by command -end, or by the end of program
395 arguments if not dialog was enabled up to that moment, or by a problem
396 event which triggers the threshold of command -abort_on.
397 Dialog, Readline, Result pager:
399 Dialog mode prompts for a quoted input line, parses it into words, and
400 performs them as commands with their parameters. It provides assisting
401 services to make dialog more comfortable.
402 Readline is an enhancement for the input line. You may know it already
404 from the bash shell. Whether it is available in xorriso depends on the
405 availability of package readline-dev at the time when xorriso was built
406 from its sourcecode.
407 It allows to move the cursor over the text in the line by help of the
408 Leftward and the Rightward arrow key. Text may be inserted at the
409 cursor position. The Delete key removes the character under the cursor.
410 Upward and Downward arrow keys navigate through the history of previous
411 input lines.
412 See man readline for more info about libreadline.
413 Option -page activates a built-in result text pager which may be
415 convenient in dialog. After an action has put out the given number of
416 terminal lines, the pager prompts the user for a line of input.
417 An empty line lets xorriso resume work until the next page is put out.
418 The single character "@" disables paging for the current action.
419 "@@@", "x", "q", "X", or "Q" urge the current action to abort and
420 suppress further result output.
421 Any other line will be interpreted as new dialog line. The current
422 action is urged to abort. Afterwards, the input line is executed.
423 Some actions apply paging to their info output, too.
425 The urge to abort may or may not be obeyed by the current action. All
426 actions try to abort as soon as possible.
427
429 All command words are shown with a leading dash although this dash is
430 not mandatory for the option to be recognized. Nevertheless within
431 option -as the dashes of the emulated options are mandatory.
432 Normally any number of leading dashes is ignored with command words and
433 inner dashes are interpreted as underscores.
434 Aquiring source and target drive:
436 The effect of aquiring a drive may depend on several options in the
438 next paragraph "Influencing the behavior of image loading". If
439 desired, their enabling commands have to be performed before the
440 commands which aquire the drive.
441 -dev address
443 Set input and output drive to the same address and load an ISO
444 image if it is present. If there is no ISO image then create a
445 blank one. Set the image expansion method to growing.
446 This is only allowed as long as no changes are pending in the
447 currently loaded ISO image. If changes are pending, then one has
448 to perform -commit or -rollback first.
449 Special address string "-" means standard output, to which
450 several restrictions apply. See above paragraph "Libburn
451 drives".
452 An empty address string "" gives up the current device without
453 aquiring a new one.
454 -indev address
456 Set input drive and load an ISO image if present. If the new
457 input drive differs from -outdev then switch from growing to
458 modifying or to blind growing. It depends on the setting of
459 -grow_blindly which of both gets activated. The same rules and
460 restrictions apply as with -dev.
461 -outdev address
463 Set output drive and if it differs from the input drive then
464 switch from growing to modifying or to blind growing. Unlike
465 -dev and -indev this action does not load a new ISO image. So it
466 can be performed even if there are pending changes.
467 -outdev can be performed without previous -dev or -indev. In
468 that case an empty ISO image with no changes pending is created.
469 It can either be populated by help of -map, -add et.al. or it
470 can be discarded silently if -dev or -indev are performed
471 afterwards.
472 Special address string "-" means standard output, to which
473 several restrictions apply. See above paragraph "Libburn
474 drives".
475 An empty address string "" gives up the current output drive
476 without aquiring a new one. No writing is possible without an
477 output drive.
478 -grow_blindly "off"|predicted_nwa
480 If predicted_nwa is a non-negative number then perform blind
481 growing rather than modifying if -indev and -outdev are set to
482 different drives. "off" or "-1" switch to modifying, which is
483 the default.
484 predicted_nwa is the block address where the add-on session of
485 blind growing will finally end up. It is the responsibility of
486 the user to ensure this final position and the presence of the
487 older sessions. Else the overall ISO image will not be mountable
488 or will produce read errors when accessing file content. xorriso
489 will write the session to the address as obtained from examining
490 -outdev and not necessarily to predicted_nwa.
491 During a run of blind growing, the input drive is given up
492 before output begins. The output drive is given up when writing
493 is done.
494 Influencing the behavior of image loading:
496 The following options should normally be performed before loading an
498 image by aquiring an input drive. In rare cases it is desirable to
499 activate them only after image loading.
500 -load entity id
502 Load a particular (possibly outdated) ISO session from -dev or
503 -indev. Usually all available sessions are shown with option
504 -toc.
505 entity depicts the kind of addressing. id depicts the particular
506 address. The following entities are defined:
507 "auto" with any id addresses the last session in -toc. This is
508 the default.
509 "session" with id being a number as of a line "ISO session",
510 column "Idx".
511 "track" with id being a number as of a line "ISO track", column
512 "Idx".
513 "lba" or "sbsector" with a number as of a line "ISO ...", column
514 "sbsector".
515 "volid" with a search pattern for a text as of a line "ISO ...",
516 column "Volume Id".
517 Adressing a non-existing entity or one which does not represent
518 an ISO image will either abandon -indev or at least lead to a
519 blank image.
520 If an input drive is set at the moment when -load is executed,
521 then the addressed ISO image is loaded immediately. Else, the
522 setting will be pending until the next -dev or -indev. After the
523 image has been loaded once, the setting is valid for -rollback
524 until next -dev or -indev, where it will be reset to "auto".
525 -displacement [-]lba
527 Compensate a displacement of the image versus the start address
528 for which the image was prepared. This affects only loading of
529 ISO images and reading of their files. The multi-session method
530 of growing is not allowed as long as -displacement is non-zero.
531 I.e. -indev and -outdev must be different. The displacement gets
532 reset to 0 before the drive gets re-aquired after writing.
533 Examples:
534 If a track of a CD starts at block 123456 and gets copied to a
535 disk file where it begins at block 0, then this copy can be
536 loaded with -displacement -123456.
537 If an ISO image was written onto a partition with offset of
538 640000 blocks of 512 bytes, then it can be loaded from the base
539 device by -displacement 160000.
540 In both cases, the ISO sessions should be self contained, i.e.
541 not add-on sessions to an ISO image outside their track resp.
542 partition.
543 -drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern
545 Add a drive path pattern to one of the safety lists or make
546 those lists empty. There are three lists defined which get
547 tested in the following sequence:
548 If a drive address path matches the "harmless" list then the
549 drive will be accepted. If it is not a MMC device then the
550 prefix "stdio:" will be prepended automatically. This list is
551 empty by default.
552 Else if the path matches the "banned" list then the drive will
553 not be accepted by xorriso but rather lead to a FAILURE event.
554 This list is empty by default.
555 Else if the path matches the "caution" list and if it is not a
556 MMC device, then its address must have the prefix "stdio:" or it
557 will be rejected. This list has by default one entry: "/dev".
558 If a drive path matches no list then it is considered
559 "harmless". By default these are all paths which do not begin
560 with directory "/dev".
561 A path matches a list if one of its parent paths or itself
562 matches a list entry. Address prefix "stdio:" or "mmc:" will be
563 ignored when testing for matches.
564 By pseudo-class "clear_list" and pseudo-patterns "banned",
565 "caution", "harmless", or "all", the lists may be made empty.
566 E.g.: -drive_class clear_list banned
567 One will normally define the -drive_class lists in one of the
568 xorriso Startup Files.
569 Note: This is not a security feature but rather a bumper for the
570 superuser to prevent inadverted mishaps. For reliably blocking
571 access to a device file you have to deny its rw-permissions in
572 the filesystem.
573 -assert_volid pattern severity
575 Refuse to load ISO images with volume ids which do not match the
576 given search pattern. When refusing an image, give up the input
577 drive and issue an event of the given severity (like FAILURE,
578 see -abort_on). An empty search pattern accepts any image.
579 This option does not hamper the creation of an empty image from
580 blank input media and does not discard an already loaded image.
581 -in_charset character_set_name
583 Set the character set from which to convert file names when
584 loading an image. See paragraph "Character sets" for more
585 explanations. When loading the written image after -commit the
586 setting of -out_charset will be copied to -in_charset.
587 -auto_charset "on"|"off"
589 Enable or disable recording and interpretation of the output
590 character set name in an xattr attribute of the image root
591 directory. If enabled and if a recorded character set name is
592 found, then this name will be used as namoe of the input
593 character set when reading an image.
594 Note that the default output charset is the local character set
595 of the terminal where xorriso runs. Before attributing this
596 local character set to the produced ISO image, check whether the
597 terminal properly displays all intended filenames, especially
598 exotic national characters.
599 -hardlinks mode[:mode...]
601 Enable or disable loading and recording of hardlink relations.
602 In default mode "off", iso_rr files lose their inode numbers at
603 image load time. Each iso_rr file object which has no inode
604 number at image generation time will get a new unique inode
605 number if -compliance is set to new_rr.
606 Mode "on" preserves inode numbers from the loaded image if such
607 numbers were recorded. When committing a session it searches
608 for families of iso_rr files which stem from the same disk file,
609 have identical content filtering and have identical properties.
610 The family members all get the same inode number. Whether these
611 numbers are respected at mount time depends on the operating
612 system.
613 Commands -update and -update_r track splits and fusions of hard
614 links in filesystems which have stable device and inode numbers.
615 This can cause automatic last minute changes before the session
616 gets written. Command -hardlinks "perform_update" may be used to
617 do these changes earlier, e.g. if you need to apply filters to
618 all updated files.
619 Mode "without_update" avoids hardlink processing during update
620 commands. Use this if your filesystem situation does not allow
621 -disk_dev_ino "on".
622 xorriso commands which extract files from an ISO image try to
623 hardlink files with identical inode number. The normal scope of
624 this operation is from image load to image load. One may give up
625 the accumulated hard link addresses by -hardlinks
626 "discard_extract".
627 A large number of hardlink families may exhaust -temp_mem_limit
628 if not -osirrox "sort_lba_on" and -hardlinks
629 "cheap_sorted_extract" are both in effect. This restricts hard
630 linking to other files restored by the same single extract
631 command. -hardlinks "normal_extract" re-enables wide and
632 expensive hardlink accumulation.
633 -acl "on"|"off"
635 Enable or disable processing of ACLs. If enabled, then xorriso
636 will obtain ACLs from disk file objects, store ACLs in the ISO
637 image using the libisofs specific AAIP format, load AAIP data
638 from ISO images, test ACL during file comparison, and restore
639 ACLs to disk files when extracting them from ISO images. See
640 also options -getfacl, -setfacl.
641 -xattr "on"|"off"
643 Enable or disable processing of xattr attributes in user
644 namespace. If enabled, then xorriso will handle xattr similar
645 to ACL. See also options -getfattr, -setfattr and above
646 paragraph about xattr.
647 -md5 "on"|"all"|"off"|"load_check_off"
649 Enable or disable processing of MD5 checksums for the overall
650 session and for each single data file. If enabled then images
651 with checksum tags get loaded only if the tags of superblock and
652 directory tree match properly. The MD5 checksums of data files
653 and whole session get loaded from the image if there are any.
654 With options -compare and -update the recorded MD5 of a file
655 will be used to avoid content reading from the image. Only the
656 disk file content will be read and compared with that MD5. This
657 can save much time if -disk_dev_ino "on" is not suitable.
658 At image generation time they are computed for each file which
659 gets its data written into the new session. The checksums of
660 files which have their data in older sessions get copied into
661 the new session. Superblock, tree and whole session get a
662 checksum tag each.
663 Mode "all" will additionally check during image generation
664 whether the checksum of a data file changed between the time
665 when its reading began and the time when it ended. This implies
666 reading every file twice.
667 Mode "load_check_off" together with "on" or "all" will load
668 recorded MD5 sums but not test the recorded checksum tags of
669 superblock and directory tree. This is necessary if growisofs
670 was used as burn program, because it does not overwrite the
671 superblock checksum tag of the first session. Therefore
672 load_check_off is in effect when xorriso -as mkisofs option -M
673 is performed.
674 The test can be re-enabled by mode "load_check_on".
675 Checksums can be exploited via options -check_md5, -check_md5_r,
676 via find actions get_md5, check_md5, and via -check_media.
677 -for_backup
679 Enable all extra features which help to produce or to restore
680 backups with highest fidelity of file properties. Currently
681 this is a shortcut for: -hardlinks on -acl on -xattr on -md5 on.
682 -disk_dev_ino "on"|"ino_only"|"off"
684 Enable or disable processing of recorded file identification
685 numbers (dev_t and ino_t). If enabled they are stored as xattr
686 and allow to substantially accelerate file comparison. The root
687 node gets a global start timestamp. If during comparison a file
688 with younger timestamps is found in the ISO image, then it is
689 suspected to have inconsistent content.
690 If device numbers and inode numbers of the disk filesystems are
691 persistent and if no irregular alterations of timestamps or
692 system clock happen, then potential content changes can be
693 detected without reading that content. File content change is
694 assumed if any of mtime, ctime, device number or inode number
695 have changed.
696 Mode "ino_only" replaces the precondition that device numbers
697 are stable by the precondition that mount points in the compared
698 tree always lead to the same filesystems. Use this if mode "on"
699 always sees all files changed.
700 The speed advantage appears only if the loaded session was
701 produced with -disk_dev_ino "on" too.
702 Note that -disk_dev_ino "off" is totally in effect only if
703 -hardlinks is "off", too.
704 -rom_toc_scan "on"|"force"|"off"[:"emul_on"|"emul_off"]
706 Read-only drives do not tell the actual media type but show any
707 media as ROM (e.g. as DVD-ROM). The session history of MMC
708 multi-session media might be truncated to first and last session
709 or even be completely false. (The emulated history of
710 overwriteable media is not affected by this.)
711 To have in case of failure a chance of getting the session
712 history and especially the address of the last session, there is
713 a scan for ISO 9660 filesystem headers which might help but also
714 might yield worse results than the drive's table of content. At
715 its end it can cause read attempts to invalid addresses and thus
716 ugly drive behavior. Setting "on" enables that scan for alleged
717 read-only media.
718 Some operating systems are not able to mount the most recent
719 session of multi-session DVD or BD. If on such a system xorriso
720 has no own MMC capabilities then it may still find that session
721 from a scanned table of content. Setting "force" handles any
722 media like a ROM medium with setting "on".
723 On the other hand the emulation of session history on
724 overwriteable media can hamper reading of partly damaged media.
725 Setting "off:emul_off" disables the elsewise trustworthy
726 table-of-content scan for those media.
727 To be in effect, the -rom_toc_scan setting has to be made before
728 the -*dev command which aquires drive and medium.
729 -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
731 Reduce drive noise until it is actually used again. Some drives
732 stay alert for substantial time after they have been used for
733 reading. This reduces the startup time for the next drive
734 operation but can be loud and waste energy if no i/o with the
735 drive is expected to happen soon.
736 Modes "in", "out", "all" immediately calm down -indev, -outdev,
737 resp. both. Mode "revoke" immediately alerts both. Mode "on"
738 causes -calm_drive to be performed automatically after each
739 -dev, -indev, and -outdev. Mode "off" disables this.
740 -ban_stdio_write
742 Allow for writing only the usage of MMC optical drives. Disallow
743 to write the result into files of nearly arbitrary type. Once
744 set, this command cannot be revoked.
745 -early_stdio_test "on"|"appendable_wo"|"off"
747 If enabled by "on" then regular files and block devices get
748 tested for effective access permissions. This implies to try
749 opening those files for writing, which otherwise will happen
750 only later and only if actual writing is desired.
751 The test result is used for classifying the pseudo drives as
752 overwriteable, read-only, write-only, or uselessly empty. This
753 may lead to earlier detection of severe problems, and may avoid
754 some less severe error events.
755 Mode "appendable_wo" is like "on" with the additional property
756 that non-empty write-only files are regarded as appendable
757 rather than blank.
758 Inserting files into ISO image:
760 The following commands expect file addresses of two kinds:
762 disk_path is a path to an object in the local filesystem tree.
763 iso_rr_path is the Rock Ridge name of a file object in the ISO image.
764 (Do not confuse with the lowlevel ISO 9660 names visible if Rock Ridge
765 gets ignored.)
766 Note that in the ISO image you are as powerful as the superuser. Access
768 permissions of the existing files in the image do not apply to your
769 write operations. They are intended to be in effect with the read-only
770 mounted image.
771 If the iso_rr_path of a newly inserted file leads to an existing file
773 object in the ISO image, then the following collision handling happens:
774 If both objects are directories then they get merged by recursively
775 inserting the subobjects from filesystem into ISO image. If other file
776 types collide then the setting of command -overwrite decides.
777 Renaming of files has similar collision handling, but directories can
778 only be replaced, not merged. Note that if the target directory exists,
779 then -mv inserts the source objects into this directory rather than
780 attempting to replace it.
781 The commands in this section alter the ISO image and not the local
783 filesystem.
784 -disk_pattern "on"|"ls"|"off"
786 Set the pattern expansion mode for the disk_path arguments of
787 several commands which support this feature.
788 Setting "off" disables this feature for all commands which are
789 marked in this man page by "disk_path [***]" or "disk_pattern
790 [***]".
791 Setting "on" enables it for all those commands.
792 Setting "ls" enables it only for those which are marked by
793 "disk_pattern [***]".
794 Default is "ls".
795 -add pathspec [...] | disk_path [***]
797 Insert the given files or directory trees from filesystem into
798 the ISO image.
799 If -pathspecs is set to "on" then pattern expansion is always
800 disabled and character '=' has a special meaning. It separates
801 the ISO image path from the disk path:
802 iso_rr_path=disk_path
803 The separator '=' can be escaped by '\'. If iso_rr_path does
804 not begin with '/' then -cd is prepended. If disk_path does not
805 begin with '/' then -cdx is prepended.
806 If no '=' is given then the word is used as both, iso_rr_path
807 and disk path. If in this case the word does not begin with '/'
808 then -cdx is prepended to the disk_path and -cd is prepended to
809 the iso_rr_path.
810 If -pathspecs is set to "off" then -disk_pattern expansion
811 applies, if enabled. The resulting words are used as both,
812 iso_rr_path and disk path. Relative path words get prepended the
813 setting of -cdx to disk_path and the setting of -cd to
814 iso_rr_path.
815 -add_plainly mode
817 If set to mode "unknown" then any command word that does not
818 begin with "-" and is not recognized as known command will be
819 subject to a virtual -add command. I.e. it will be used as
820 pathspec or as disk_path and added to the image. If enabled,
821 -disk_pattern expansion applies to disk_paths.
822 Mode "dashed" is similar to "unknown" but also adds unrecognized
823 command words even if they begin with "-".
824 Mode "any" announces that all further words are to be added as
825 pathspecs or disk_paths. This does not work in dialog mode.
826 Mode "none" is the default. It prevents any words from being
827 understood as files to add, if they are not parameters to
828 appropriate commands.
829 -path_list disk_path
831 Like -add but read the parameter words from file disk_path or
832 standard input if disk_path is "-". The list must contain
833 exactly one pathspec resp. disk_path pattern per line.
834 -quoted_path_list disk_path
836 Like -path_list but with quoted input reading rules. Lines get
837 split into parameter words for -add. Whitespace outside quotes
838 is discarded.
839 -map disk_path iso_rr_path
841 Insert file object disk_path into the ISO image as iso_rr_path.
842 If disk_path is a directory then its whole sub tree is inserted
843 into the ISO image.
844 -map_single disk_path iso_rr_path
846 Like -map, but if disk_path is a directory then its sub tree is
847 not inserted.
848 -map_l disk_prefix iso_rr_prefix disk_path [***]
850 Perform -map with each of the disk_path arguments. iso_rr_path
851 will be composed from disk_path by replacing disk_prefix by
852 iso_rr_prefix.
853 -update disk_path iso_rr_path
855 Compare file object disk_path with file object iso_rr_path. If
856 they do not match, then perform the necessary image
857 manipulations to make iso_rr_path a matching copy of disk_path.
858 By default this comparison will imply lengthy content reading
859 before a decision is made. Options -disk_dev_ino or -md5 may
860 accelerate comparison if they were already in effect when the
861 loaded session was recorded.
862 If disk_path is a directory and iso_rr_path does not exist yet,
863 then the whole subtree will be inserted. Else only directory
864 attributes will be updated.
865 -update_r disk_path iso_rr_path
867 Like -update but working recursively. I.e. all file objects
868 below both addresses get compared whether they have counterparts
869 below the other address and whether both counterparts match. If
870 there is a mismatch then the necessary update manipulation is
871 done.
872 Note that the comparison result may depend on option -follow.
873 Its setting should always be the same as with the first adding
874 of disk_path as iso_rr_path.
875 If iso_rr_path does not exist yet, then it gets added. If
876 disk_path does not exist, then iso_rr_path gets deleted.
877 -update_l disk_prefix iso_rr_prefix disk_path [***]
879 Perform -update_r with each of the disk_path arguments.
880 iso_rr_path will be composed from disk_path by replacing
881 disk_prefix by iso_rr_prefix.
882 -cut_out disk_path byte_offset byte_count iso_rr_path
884 Map a byte interval of a regular disk file into a regular file
885 in the ISO image. This may be necessary if the disk file is
886 larger than a single medium, or if it exceeds the traditional
887 limit of 2 GiB - 1 for old operating systems, or the limit of 4
888 GiB - 1 for newer ones. Only the newest Linux kernels seem to
889 read properly files >= 4 GiB - 1.
890 A clumsy remedy for this limit is to backup file pieces and to
891 concatenate them at restore time. A well tested chopping size is
892 2047m. It is permissible to request a higher byte_count than
893 available. The resulting file will be truncated to the correct
894 size of a final piece. To request a byte_offset higher than
895 available yields no file in the ISO image but a SORRY event.
896 E.g:
897 -cut_out /my/disk/file 0 2047m \
898 /file/part_1_of_3_at_0_with_2047m_of_5753194821 \
899 -cut_out /my/disk/file 2047m 2047m \
900 /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
901 -cut_out /my/disk/file 4094m 2047m \
902 /file/part_3_of_3_at_4094m_with_2047m_of_5753194821
903 While option -split_size is set larger than 0, and if all pieces
904 of a file reside in the same ISO directory with no other files,
905 and if the names look like above, then their ISO directory will
906 be recognized and handled like a regular file. This affects
907 options -compare*, -update*, and overwrite situations. See
908 option -split_size for details.
909 -cpr disk_path [***] iso_rr_path
911 Insert the given files or directory trees from filesystem into
912 the ISO image.
913 The rules for generating the ISO addresses are similar as with
914 shell command cp -r. Nevertheless, directories of the
915 iso_rr_path are created if necessary. Especially a not yet
916 existing iso_rr_path will be handled as directory if multiple
917 disk_paths are present. The leafnames of the multiple
918 disk_paths will be grafted under that directory as would be done
919 with an existing directory.
920 If a single disk_path is present then a non-existing iso_rr_path
921 will get the same type as the disk_path.
922 If a disk_path does not begin with '/' then -cdx is prepended.
923 If the iso_rr_path does not begin with '/' then -cd is
924 prepended.
925 -mkdir iso_rr_path [...]
927 Create empty directories if they do not exist yet. Existence as
928 directory generates a WARNING event, existence as other file
929 causes a FAILURE event.
930 -clone iso_rr_path_original iso_rr_path_copy
932 Create a copy of the ISO file object iso_rr_path_original with
933 the new address iso_rr_path_copy. If the original is a directory
934 then copy all files and directories underneath. If
935 iso_rr_path_original is a boot catalog file, then it gets not
936 copied but is silently ignored.
937 The copied ISO file objects have the same attributes. Copied
938 data files refer to the same content source as their originals.
939 The copies may then be manipulated independendly of their
940 originals.
941 This command will refuse execution if the address
942 iso_rr_path_copy already exists in the ISO tree.
943 -cp_clone iso_rr_path_original [***] iso_rr_path_dest
945 Create copies of one or more ISO file objects as with command
946 -clone. In case of collision merge directories with existing
947 ones, but do not overwrite existing ISO file objects.
948 The rules for generating the copy addresses are the same as with
949 command -cpr (see above) resp. shell command cp -r. Other than
950 with -cpr, relative iso_rr_path_original will get prepended the
951 -cd path and not the -cdx path. Consider to -mkdir
952 iso_rr_path_dest before -cp_clone so the copy address does not
953 depend on the number of iso_rr_path_original arguments.
954 Settings for file insertion:
956 -file_size_limit value [value [...]] --
958 Set the maximum permissible size for a single data file. The
959 values get summed up for the actual limit. If the only value is
960 "off" then the file size is not limited by xorriso. Default is
961 a limit of 100 extents, 4g -2k each:
962 -file_size_limit 400g -200k --
963 When mounting ISO 9660 filesystems, old operating systems can
964 handle only files up to 2g -1 --. Newer ones are good up to 4g
965 -1 --. You need quite a new Linux kernel to read correctly the
966 final bytes of a file >= 4g if its size is not aligned to 2048
967 byte blocks.
968 xorriso's own data read capabilities are not affected by
969 operating system size limits. Such limits apply to mounting
970 only. Nevertheless, the target filesystem of an -extract must be
971 able to take the file size.
972 -not_mgt code[:code[...]]
974 Control the behavior of the exclusion lists.
975 Exclusion processing happens before disk_paths get mapped to the
976 ISO image and before disk files get compared with image files.
977 The absolute disk path of the source is matched against the
978 -not_paths list. The leafname of the disk path is matched
979 against the patterns in the -not_leaf list. If a match is
980 detected then the disk path will not be regarded as an existing
981 file and not be added to the ISO image.
982 Several codes are defined. The _on/_off settings persist until
983 they are revoked by their_off/_on counterparts.
984 "erase" empties the lists which were accumulated by -not_paths
985 and -not_leaf.
986 "reset" is like "erase" but also re-installs default behavior.
987 "off" disables exclusion processing temporarily without
988 invalidating the lists and settings.
989 "on" re-enables exclusion processing.
990 "param_off" applies exclusion processing only to paths below
991 disk_path parameter of commands. I.e. explicitly given
992 disk_paths are exempted from exclusion processing.
993 "param_on" applies exclusion processing to command parameters as
994 well as to files below such parameters.
995 "subtree_off" with "param_on" excludes parameter paths only if
996 they match a -not_paths item exactly.
997 "subtree_on" additionally excludes parameter paths which lead to
998 a file address below any -not_paths item.
999 "ignore_off" treats excluded disk files as if they were missing.
1000 I.e. they get reported with -compare and deleted from the image
1001 with -update.
1002 "ignore_on" keeps excluded files out of -compare or -update
1003 activities.
1004 -not_paths disk_path [***]
1006 Add the given paths to the list of excluded absolute disk paths.
1007 If a given path is relative, then the current -cdx is prepended
1008 to form an absolute path. Pattern matching, if enabled, happens
1009 at definition time and not when exclusion checks are made.
1010 (Do not forget to end the list of disk_paths by "--")
1011 -not_leaf pattern
1013 Add a single shell parser style pattern to the list of
1014 exclusions for disk leafnames. These patterns are evaluated when
1015 the exclusion checks are made.
1016 -not_list disk_path
1018 Read lines from disk_path and use each of them either as
1019 -not_paths argument, if they contain a / character, or as
1020 -not_leaf pattern.
1021 -quoted_not_list disk_path
1023 Like -not_list but with quoted input reading rules. Each word is
1024 handled as one argument for -not_paths resp. -not_leaf.
1025 -follow occasion[:occasion[...]]
1027 Enable or disable resolution of symbolic links and mountpoints
1028 under disk_paths. This applies to actions -add, -du*x, -ls*x,
1029 -findx, and to -disk_pattern expansion.
1030 There are two kinds of follow decisison to be made:
1031 "link" is the hop from a symbolic link to its target file
1032 object. If enabled then symbolic links are handled as their
1033 target file objects, else symbolic links are handled as
1034 themselves.
1035 "mount" is the hop from one filesystem to another subordinate
1036 filesystem. If enabled then mountpoint directories are handled
1037 as any other directory, else mountpoints are handled as empty
1038 directories if they are encountered in directory tree
1039 traversals.
1040 Less general than above occasions:
1041 "pattern" is mount and link hopping, but only during
1042 -disk_pattern expansion.
1043 "param" is link hopping for parameter words (after eventual
1044 pattern expansion). If enabled then -ls*x will show the link
1045 targets rather than the links themselves. -du*x, -findx, and
1046 -add will process the link targets but not follow links in an
1047 eventual directory tree below the targets (unless "link" is
1048 enabled).
1049 Occasions can be combined in a colon separated list. All
1050 occasions mentioned in the list will then lead to a positive
1051 follow decision.
1052 "off" prevents any positive follow decision. Use it if no other
1053 occasion applies.
1054 Shortcuts:
1055 "default" is equivalent to "pattern:mount:limit=100".
1056 "on" always decides positive. Equivalent to "link:mount".
1057 Not an occasion but an optional setting is:
1059 "limit="<number> which sets the maximum number of link hops. A
1060 link hop consists of a sequence of symbolic links and a final
1061 target of different type. Nevertheless those hops can loop.
1062 Example:
1063 $ ln -s .. uploop
1064 Link hopping has a built-in loop detection which stops hopping
1065 at the first repetition of a link target. Then the repeated link
1066 is handled as itself and not as its target. Regrettably one can
1067 construct link networks which cause exponential workload before
1068 their loops get detected. The number given with "limit=" can
1069 curb this workload at the risk of truncating an intentional
1070 sequence of link hops.
1071 -pathspecs "on"|"off"
1073 Control parameter interpretation with xorriso actions -add and
1074 -path_list.
1075 "on" enables pathspecs of the form target=source like with
1076 program mkisofs -graft-points. It also disables -disk_pattern
1077 expansion for command -add.
1078 "off" disables pathspecs of the form target=source and
1079 re-enables -disk_pattern expansion.
1080 -overwrite "on"|"nondir"|"off"
1082 Allow or disallow to overwrite existing files in the ISO image
1083 by files with the same name.
1084 With setting "off", name collisions cause FAILURE events. With
1085 setting "nondir", only directories are protected by such events,
1086 other existing file types get treated with -rm before the new
1087 file gets added. Setting "on" allows automatic -rm_r. I.e. a
1088 non-directory can replace an existing directory and all its
1089 subordinates.
1090 If restoring of files is enabled, then the overwrite rule
1091 applies to the target file objects on disk as well, but "on" is
1092 downgraded to "nondir".
1093 -split_size number["k"|"m"]
1095 Set the threshold for automatic splitting of regular files. Such
1096 splitting maps a large disk file onto a ISO directory with
1097 several part files in it. This is necessary if the size of the
1098 disk file exceeds -file_size_limit. Older operating systems can
1099 handle files in mounted ISO 9660 filesystems only if they are
1100 smaller than 2 GiB resp. 4 GiB.
1101 Default is 0 which will exclude files larger than
1102 -file_size_limit by a FAILURE event. A well tested -split_size
1103 is 2047m. Sizes above -file_size_limit are not permissible.
1104 While option -split_size is set larger than 0 such a directory
1105 with split file pieces will be recognized and handled like a
1106 regular file by options -compare* , -update*, and in overwrite
1107 situations. There are -ossirox options "concat_split_on" and
1108 "concat_split_off" which control the handling when files get
1109 restored to disk.
1110 In order to be recognizable, the names of the part files have to
1111 describe the splitting by 5 numbers:
1112 part_number,total_parts,byte_offset,byte_count,disk_file_size
1113 which are embedded in the following text form:
1114 part_#_of_#_at_#_with_#_of_#
1115 Scaling characters like "m" or "k" are taken into respect. All
1116 digits are interpreted as decimal, even if leading zeros are
1117 present.
1118 E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
1119 No other files are allowed in the directory. All parts have to
1120 be present and their numbers have to be plausible. E.g.
1121 byte_count must be valid as -cut_out argument and their contents
1122 may not overlap.
1123 File manipulations:
1125 The following commands manipulate files in the ISO image, regardless
1127 whether they stem from the loaded image or were newly inserted.
1128 -iso_rr_pattern "on"|"ls"|"off"
1130 Set the pattern expansion mode for the iso_rr_path arguments of
1131 several commands which support this feature.
1132 Setting "off" disables pattern expansion for all commands which
1133 are marked in this man page by "iso_rr_path [***]" or
1134 "iso_rr_pattern [***]".
1135 Setting "on" enables it for all those commands.
1136 Setting "ls" enables it only for those which are marked by
1137 "iso_rr_pattern [***]".
1138 Default is "on".
1139 -rm iso_rr_path [***]
1141 Delete the given files from the ISO image.
1142 Note: This does not free any space on the -indev medium, even if
1143 the deletion is committed to that same medium.
1144 The image size will shrink if the image is written to a
1145 different medium in modification mode.
1146 -rm_r iso_rr_path [***]
1148 Delete the given files or directory trees from the ISO image.
1149 See also the note with option -rm.
1150 -rmdir iso_rr_path [***]
1152 Delete empty directories.
1153 -mv iso_rr_path [***] iso_rr_path
1155 Rename the given file objects in the ISO tree to the last
1156 argument in the list. Use the same rules as with shell command
1157 mv.
1158 If pattern expansion is enabled and if the last argument
1159 contains wildcard characters then it must match exactly one
1160 existing file address, or else the command fails with a FAILURE
1161 event.
1162 -chown uid iso_rr_path [***]
1164 Set ownership of file objects in the ISO image. uid may either
1165 be a decimal number or the name of a user known to the operating
1166 system.
1167 -chown_r uid iso_rr_path [***]
1169 Like -chown but affecting all files below eventual directories.
1170 -chgrp gid iso_rr_path [***]
1172 Set group attribute of file objects in the ISO image. gid may
1173 either be a decimal number or the name of a group known to the
1174 operating system.
1175 -chgrp_r gid iso_rr_path [***]
1177 Like -chgrp but affecting all files below eventual directories.
1178 -chmod mode iso_rr_path [***]
1180 Equivalent to shell command chmod in the ISO image. mode is
1181 either an octal number beginning with "0" or a comma separated
1182 list of statements of the form [ugoa]*[+-=][rwxst]* .
1183 Like: go-rwx,u+rwx .
1184 Personalities: u=user, g=group, o=others, a=all
1185 Operators: + adds given permissions, - revokes given
1186 permissions, = revokes all old permissions and then adds the
1187 given ones.
1188 Permissions: r=read, w=write, x=execute|inspect,
1189 s=setuid|setgid, t=sticky bit
1190 For octal numbers see man 2 stat.
1191 -chmod_r mode iso_rr_path [***]
1193 Like -chmod but affecting all files below eventual directories.
1194 -setfacl acl_text iso_rr_path [***]
1196 Attach the given ACL to the given iso_rr_paths. If the files
1197 already have ACLs, then those get deleted before the new ones
1198 get into effect. If acl_text is empty, or contains the text
1199 "clear" or the text "--remove-all", then the existing ACLs will
1200 be removed and no new ones will be attached. Any other content
1201 of acl_text will be interpreted as a list of ACL entries. It may
1202 be in the long multi-line format as put out by -getfacl but may
1203 also be abbreviated as follows:
1204 ACL entries are separated by comma or newline. If an entry is
1205 empty text or begins with "#" then it will be ignored. A valid
1206 entry has to begin by a letter out of {ugom} for "user",
1207 "group", "other", "mask". It has to contain two colons ":". A
1208 non-empty text between those ":" gives a user id resp. group id.
1209 After the second ":" there may be letters out of {rwx- #}. The
1210 first three give read, write resp. execute permission. Letters
1211 "-", " " and TAB are ignored. "#" causes the rest of the entry
1212 to be ignored. Letter "X" or any other letters are not
1213 supported. Examples:
1214 g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
1215 group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-
1216 A valid entry may be prefixed by "d", some following characters
1217 and ":". This indicates that the entry goes to the "default"
1218 ACL rather than to the "access" ACL. Example:
1219 u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
1220 -setfacl_r acl_text iso_rr_path [***]
1222 Like -setfacl but affecting all files below eventual
1223 directories.
1224 -setfacl_list disk_path
1226 Read the output of -getfacl_r or shell command getfacl -R and
1227 apply it to the iso_rr_paths as given in lines beginning with "#
1228 file:". This will change ownership, group and ACL of the given
1229 files. If disk_path is "-" then lines are read from standard
1230 input. Line "@" ends the list, "@@@" aborts without changing the
1231 pending iso_rr_path.
1232 Since -getfacl and getfacl -R strip leading "/" from file paths,
1233 the setting of -cd does always matter.
1234 -setfattr [-]name value iso_rr_path [***]
1236 Attach the given xattr pair of name and value to the given
1237 iso_rr_paths. If the given name is prefixed by "-", then the
1238 pair with that name gets removed from the xattr list. If name is
1239 "--remove-all" then all user namespace xattr of the given
1240 iso_rr_paths get deleted. In case of deletion, value must be an
1241 empty text.
1242 Only names from the user namespace are allowed. I.e. a name has
1243 to begin with "user.", like "user.x" or "user.whatever".
1244 Values and names undergo the normal input processing of xorriso.
1245 See also option -backslash_codes. Other than with option
1246 -setfattr_list, the byte value 0 cannot be expressed via
1247 -setfattr.
1248 -setfattr_r [-]name value iso_rr_path [***]
1250 Like -setfattr but affecting all files below eventual
1251 directories.
1252 -setfattr_list disk_path
1254 Read the output of -getfattr_r or shell command getfattr -Rd and
1255 apply it to the iso_rr_paths as given in lines beginning with "#
1256 file:". All previously existing user space xattr of the given
1257 iso_rr_paths will be deleted. If disk_path is "-" then lines
1258 are read from standard input.
1259 Since -getfattr and getfattr -Rd strip leading "/" from file
1260 paths, the setting of -cd does always matter.
1261 Empty input lines and lines which begin by "#" will be ignored
1262 (except "# file:"). Line "@" ends the list, "@@@" aborts without
1263 changing the pending iso_rr_path. Other input lines must have
1264 the form
1265 name="value"
1266 Name must be from user namespace. I.e. user.xyz where xyz should
1267 consist of printable characters only. The separator "=" is not
1268 allowed in names. Value may contain any kind of bytes. It must
1269 be in quotes. Trailing whitespace after the end quote will be
1270 ignored. Non-printables bytes and quotes must be represented as
1271 \XYZ by their octal ASCII code XYZ. Use code \000 for 0-bytes.
1272 -alter_date type timestring iso_rr_path [***]
1274 Alter the date entries of a file in the ISO image. type is one
1275 of "a", "m", "b" for access time, modification time, both times.
1276 timestring may be in the following formats (see also section
1277 EXAMPLES):
1278 As expected by program date:
1279 MMDDhhmm[[CC]YY][.ss]]
1280 As produced by program date:
1281 [Day] MMM DD hh:mm:ss [TZON] YYYY
1282 Relative times counted from current clock time:
1283 +|-Number["s"|"h"|"d"|"w"|"m"|"y"]
1284 where "s" means seconds, "h" hours, "d" days, "w" weeks,
1285 "m"=30d, "y"=365.25d plus 1d added to multiplication result.
1286 Absolute seconds counted from Jan 1 1970:
1287 =Number
1288 xorriso's own timestamps:
1289 YYYY.MM.DD[.hh[mm[ss]]]
1290 scdbackup timestamps:
1291 YYMMDD[.hhmm[ss]]
1292 where "A0" is year 2000, "B0" is 2010, etc.
1293 -alter_date_r type timestring iso_rr_path [***]
1295 Like -alter_date but affecting all files below eventual
1296 directories.
1297 -hide hide_state iso_rr_path [***]
1299 Prevent the names of the given files from showing up in the
1300 directory trees of ISO 9660 and/or Joliet when the image gets
1301 written. The data content of such hidden files will be included
1302 in the resulting image, even if they do not show up in any
1303 directory. But you will need own means to find nameless data in
1304 the image.
1305 Warning: Data which are hidden from the ISO 9660 tree will not
1306 be copied by the write method of modifying.
1307 Possible values of hide_state are: "iso_rr" for hiding from ISO
1308 9660 tree, "joliet" for Joliet tree, "on" for both trees. "off"
1309 means visibility in both directory trees.
1310 This command does not apply to the boot catalog. Rather use:
1311 -boot_image "any" "cat_hidden=on"
1312 Tree traversal command -find:
1314 -find iso_rr_path [test [op] [test ...]] [-exec action [params]] --
1316 A restricted substitute for shell command find in the ISO image.
1317 It performs an action on matching file objects at or below
1318 iso_rr_path.
1319 If not used as last command in the line then the argument list
1320 needs to get terminated by "--".
1321 Tests are optional. If they are omitted then action is applied
1322 to all file objects. If tests are given then they form together
1323 an expression. The action is applied only if the expression
1324 matches the file object. Default expression operator between
1325 tests is -and, i.e. the expression matches only if all its tests
1326 match.
1327 Available tests are:
1328 -name pattern : Matches if pattern matches the file leaf name.
1329 -wholename pattern : Matches if pattern matches the file path as
1330 it would be printed by action "echo". Character '/' is not
1331 special but can be matched by wildcards.
1332 -disk_name pattern : Like -name but testing the leaf name of the
1333 file source on disk. Can be true only for data files which stem
1334 not from the loaded image.
1335 -type type_letter : Matches files of the given type: "block",
1336 "char", "dir", "pipe", "file", "link", "socket", "eltorito", and
1337 "Xotic" which matches what is not matched by the other types.
1338 Only the first letter is interpreted. E.g.: -find / -type d
1339 -damaged : Matches files which use data blocks marked as damaged
1340 by a previous run of -check_media. The damage info vanishes when
1341 a new ISO image gets loaded.
1342 Note that a MD5 session mismatch marks all files of the session
1343 as damaged. If finer distinction is desired, perform -md5 off
1344 before -check_media.
1345 -pending_data : Matches files which get their content from
1346 outside the loaded ISO image.
1347 -lba_range start_lba block_count : Matches files which use data
1348 blocks within the range of start_lba and
1349 start_lba+block_count-1.
1350 -has_acl : Matches files which have a non-trivial ACL.
1351 -has_xattr : Matches files which have xattr name-value pairs
1352 from user namespace.
1353 -has_aaip : Matches files which have ACL or any xattr.
1354 -has_any_xattr : Matches files which have any xattr other than
1355 ACL.
1356 -has_md5 : Matches data files which have MD5 checksums.
1357 -has_filter : Matches files which are filtered by -set_filter.
1358 -hidden hide_state : Matches files which are hidden in "iso_rr"
1359 tree, in "joliet" tree, in both trees ("on"), or not hidden in
1360 any tree ("off"). Those which are hidden in some tree match
1361 -not -hidden "off".
1362 -prune : If this test is reached and the tested file is a
1363 directory then -find will not dive into that directory. This
1364 test itself does always match.
1365 -decision "yes"|"no" : If this test is reached then the
1366 evaluation ends immediately and action is performed if the
1367 decision is "yes" or "true". See operator -if.
1368 -true and -false : Always match resp. match not. Evaluation goes
1369 on.
1370 -sort_lba : Always match. This causes -find to perform its
1371 action in a sequence sorted by the ISO image block addresses of
1372 the files. It may improve throughput with actions which read
1373 data from optical drives. Action will always get the absolute
1374 path as parameter.
1375 Available operators are:
1376 -not : Matches if the next test or sub expression does not
1377 match. Several tests do this specifically:
1378 -undamaged, -lba_range with negative start_lba, -has_no_acl,
1379 -has_no_xattr, -has_no_aaip, -has_no_filter .
1380 -and : Matches if both neighboring tests or expressions match.
1381 -or : Matches if at least one of both neighboring tests or
1382 expressions matches.
1383 -sub ... -subend or ( ... ) : Enclose a sub expression which
1384 gets evaluated first before it is processed by neighboring
1385 operators. Normal precedence is: -not, -or , -and.
1386 -if ... -then ... -elseif ... -then ... -else ... -endif :
1387 Enclose one or more sub expressions. If the -if expression
1388 matches, then the -then expression is evaluated as the result of
1389 the whole expression up to -endif. Else the next -elseif
1390 expression is evaluated and if it matches, its -then expression.
1391 Finally in case of no match, the -else expression is evaluated.
1392 There may be more than one -elseif. Neither -else nor -elseif
1393 are mandatory. If -else is missing and would be hit, then the
1394 result is a non-match.
1395 -if-expressions are the main use case for above test -decision.
1396 Default action is echo, i.e. to print the address of the found
1398 file. Other actions are certain xorriso commands which get
1399 performed on the found files. These commands may have specific
1400 parameters. See also their particular descriptions.
1401 chown and chown_r change the ownership and get the user id as
1402 parameter. E.g.: -exec chown thomas --
1403 chgrp and chgrp_r change the group attribute and get the group
1404 id as parameter. E.g.: -exec chgrp_r staff --
1405 chmod and chmod_r change access permissions and get a mode
1406 string as parameter. E.g.: -exec chmod a-w,a+r --
1407 alter_date and alter_date_r change the timestamps. They get a
1408 type character and a timestring as parameters.
1409 E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" --
1410 lsdl prints file information like shell command ls -dl.
1411 compare performs command -compare with the found file address as
1412 iso_rr_path and the corresponding file address below its
1413 argument disk_path_start. For this the iso_rr_path of the -find
1414 command gets replaced by the disk_path_start.
1415 E.g.: -find /thomas -exec compare /home/thomas --
1416 update performs command -update with the found file address as
1417 iso_rr_path. The corresponding file address is determined like
1418 with above action "compare".
1419 update_merge is like update but does not delete the found file
1420 if it is missing on disk. It may be run several times and
1421 records with all visited files whether their counterpart on disk
1422 has already been seen by one of the update_merge runs. Finally,
1423 a -find run with action "rm_merge" may remove all files that saw
1424 no counterpart on disk.
1425 Up to the next "rm_merge" or "clear_merge" all newly inserted
1426 files will get marked as having a disk counterpart.
1427 rm removes the found iso_rr_path from the image if it is not a
1428 directory with files in it. I.e. this "rm" includes "rmdir".
1429 rm_r removes the found iso_rr_path from the image, including
1430 whole directory trees.
1431 rm_merge removes the found iso_rr_path if it was visited by one
1432 or more previous actions "update_merge" and saw no counterpart
1433 on disk in any of them. The marking from the update actions is
1434 removed in any case.
1435 clear_merge removes an eventual marking from action
1436 "update_merge".
1437 report_damage classifies files whether they hit a data block
1438 that is marked as damaged. The result is printed together with
1439 the address of the first damaged byte, the maximum span of
1440 damages, file size, and the path of the file.
1441 report_lba prints files which are associated to image data
1442 blocks. It tells the logical block address, the block number,
1443 the byte size, and the path of each file. There may be reported
1444 more than one line per file if the file is very large. In this
1445 case each line has a different extent number in column "xt".
1446 getfacl prints access permissions in ACL text form to the result
1447 channel.
1448 setfacl attaches ACLs after removing existing ones. The new ACL
1449 is given in text form as defined with option -setfacl.
1450 E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
1451 getfattr prints xattr name-value pairs from user namespace to
1452 the result channel.
1453 get_any_xattr prints xattr name-value pairs from any namespace
1454 except ACL to the result channel. This is mostly for debugging
1455 of namespace "isofs".
1456 list_extattr mode prints a script to the result channel, which
1457 would use FreeBSD command setextattr to set the file's xattr
1458 name-value pairs of user namespace. Parameter mode controls the
1459 form of the output of names and values. Default mode "e" prints
1460 harmless characters in shell quotation marks, but represents
1461 texts with octal 001 to 037 and 0177 to 0377 by an embedded echo
1462 -e command. Mode "q" prints any characters in shell quotation
1463 marks. This might not be terminal-safe but should work in script
1464 files. Mode "r" uses no quotation marks. Not safe. Mode "b"
1465 prints backslash encoding. Not suitable for shell parsing.
1466 E.g. -exec list_extattr e --
1467 Option -backslash_codes does not affect the output.
1468 get_md5 prints the MD5 sum, if recorded, together with file
1469 path.
1470 check_md5 compares the MD5 sum, if recorded, with the file
1471 content and reports if mismatch.
1472 E.g.: -find / -not -pending_data -exec check_md5 FAILURE --
1473 make_md5 equips a data file with an MD5 sum of its content.
1474 Useful to upgrade the files in the loaded image to full MD5
1475 coverage by the next commit with -md5 "on".
1476 E.g.: -find / -type f -not -has_md5 -exec make_md5 --
1477 setfattr sets or deletes xattr name value pairs.
1478 E.g.: -find / -has_xattr -exec setfattr --remove-all '' --
1479 set_filter applies or removes filters.
1480 E.g.: -exec set_filter --zisofs --
1481 mkisofs_r applies the rules of mkisofs -r to the file object:
1482 user id and group id become 0, all r-permissions get granted,
1483 all w denied. If there is any x-permission, then all three x
1484 get granted. s- and t-bits get removed.
1485 sort_weight attributes a LBA weight number to regular files.
1486 The number may range from -2147483648 to 2147483647. The higher
1487 it is, the lower will be the block address of the file data in
1488 the emerging ISO image. Currently the boot catalog has a
1489 hardcoded weight of 1 billion. Normally it should occupy the
1490 block with the lowest possible address. Data files get added or
1491 loaded with initial weight 0.
1492 E.g.: -exec sort_weight 3 --
1493 show_stream shows the content stream chain of a data file.
1494 hide brings the file into one of the hide states "on", "iso_rr",
1495 "joliet", "off".
1496 E.g.:
1497 -find / -disk_name *_secret -exec hide on
1498 estimate_size prints a lower and an upper estimation of the
1499 number of blocks which the found files together will occupy in
1500 the emerging ISO image. This does not account for the
1501 superblock, for the directories in the -find path, or for image
1502 padding.
1503 find performs another run of -find on the matching file address.
1504 It accepts the same params as -find, except iso_rr_path.
1505 E.g.:
1506 -find / -name '???' -type d -exec find -name '[abc]*' -exec
1507 chmod a-w,a+r --
1508 Filters for data file content:
1510 Filters may be installed between data files in the ISO image and their
1512 content source outside the image. They may also be used vice versa
1513 between data content in the image and target files on disk.
1514 Built-in filters are "--zisofs" and "--zisofs-decode". The former is to
1515 be applied via -set_filter, the latter is automatically applied if
1516 zisofs compressed content is detected with a file when loading the ISO
1517 image.
1518 Another built-in filter pair is "--gzip" and "--gunzip" with suffix
1519 ".gz". They behave about like external gzip and gunzip but avoid
1520 forking a process for each single file. So they are much faster if
1521 there are many small files.
1522 -external_filter name option[:option] program_path [arguments] --
1524 Register a content filter by associating a name with a program
1525 path, program arguments, and some behavioral options. Once
1526 registered it can be applied to multiple data files in the ISO
1527 image, regardless whether their content resides in the loaded
1528 ISO image or in the local filesystem. External filter processes
1529 may produce synthetic file content by reading the original
1530 content from stdin and writing to stdout whatever they want.
1531 They must deliver the same output on the same input in repeated
1532 runs.
1533 Options are:
1534 "default" means that no other option is intended.
1535 "suffix=..." sets a file name suffix. If it is not empty then
1536 it will be appended to the file name or removed from it.
1537 "remove_suffix" will remove a file name suffix rather than
1538 appending it.
1539 "if_nonempty" will leave 0-sized files unfiltered.
1540 "if_reduction" will try filtering and revoke it if the content
1541 size does not shrink.
1542 "if_block_reduction" will revoke if the number of 2 kB blocks
1543 does not shrink.
1544 "used=..." is ignored. Command -status shows it with the number
1545 of files which currently have the filter applied.
1546 Examples:
1547 -external_filter bzip2 suffix=.bz2:if_block_reduction \
1548 /usr/bin/bzip2 --
1549 -external_filter bunzip2 suffix=.bz2:remove_suffix \
1550 /usr/bin/bunzip2 --
1551 -unregister_filter name
1553 Remove an -external_filter registration. This is only possible
1554 if the filter is not applied to any file in the ISO image.
1555 -close_filter_list
1557 Irrevocably ban commands -external_filter and
1558 -unregister_filter, but not -set_filter. Use this to prevent
1559 external filtering in general or when all intended filters are
1560 registered. External filters may also be banned totally at
1561 compile time of xorriso. By default they are banned if xorriso
1562 runs under setuid permission.
1563 -set_filter name iso_rr_path [***]
1565 Apply an -external_filter or a built-in filter to the given data
1566 files in the ISO image. If the filter suffix is not empty ,
1567 then it will be applied to the file name. Renaming only happens
1568 if the filter really gets attached and is not revoked by its
1569 options. By default files which already bear the suffix will
1570 not get filtered. The others will get the suffix appended to
1571 their names. If the filter has option "remove_suffix", then the
1572 filter will only be applied if the suffix is present and can be
1573 removed. Name oversize or collision caused by suffix change
1574 will prevent filtering.
1575 With most filter types this command will immediately run the
1576 filter once for each file in order to determine the output size.
1577 Content reading operations like -extract , -compare and image
1578 generation will perform further filter runs and deliver filtered
1579 content.
1580 At image generation time the filter output must still be the
1581 same as the output from the first run. Filtering for image
1582 generation does not happen with files from the loaded ISO image
1583 if the write method of growing is in effect (i.e -indev and
1584 -outdev are identical).
1585 The reserved filter name "--remove-all-filters" revokes
1586 filtering. This will revoke suffix renamings as well. Use
1587 "--remove-all-filters+" to prevent any suffix renaming.
1588 -set_filter_r name iso_rr_path [***]
1590 Like -set_filter but affecting all data files below eventual
1591 directories.
1592 Writing the result, drive control:
1594 (see also paragraph about settings below)
1596 -rollback
1598 Discard the manipulated ISO image and reload it from -indev.
1599 (Use -rollback_end if immediate program end is desired.)
1600 -commit
1602 Perform the write operation. Afterwards, if -outdev is readable,
1603 make it the new -dev and load the image from there. Switch to
1604 growing mode. (A subsequent -outdev will activate modification
1605 mode or blind growing.) -commit is performed automatically at
1606 end of program if there are uncommitted manipulations pending.
1607 So, to perform a final write operation with no new -dev and no
1608 new loading of image, rather execute option -end. If you want
1609 to go on without image loading, execute -commit_eject "none".
1610 To eject after write without image loading, use -commit_eject
1611 "all".
1612 To suppress a final write, execute -rollback_end.
1613 Writing can last quite a while. It is not unnormal with several
1615 types of media that there is no progress visible for the first
1616 few minutes or that the drive gnaws on the medium for a few
1617 minutes after all data have been transmitted. xorriso and the
1618 drives are in a client-server relationship. The drives have
1619 much freedom about what to do with the media. Some combinations
1620 of drives and media simply do not work, despite the promises by
1621 their vendors. If writing fails then try other media or another
1622 drive. The reason for such failure is hardly ever in the code of
1623 the various burn programs but you may well try some of those
1624 listed below under SEE ALSO.
1625 -eject "in"|"out"|"all"
1627 Eject the medium in -indev, resp. -outdev, resp. both drives.
1628 Note: It is not possible yet to effectively eject disk files.
1629 -commit_eject "in"|"out"|"all"|"none"
1631 Combined -commit and -eject. When writing has finished do not
1632 make -outdev the new -dev, and load no ISO image. Rather eject
1633 -indev and/or -outdev. Give up any non-ejected drive.
1634 -blank mode
1636 Make media ready for writing from scratch (if not -dummy is
1637 activated).
1638 This affects only the -outdev not the -indev. If both drives
1639 are the same and if the ISO image was altered then this command
1640 leads to a FAILURE event. Defined modes are:
1641 as_needed, fast, all, deformat, deformat_quickest
1642 "as_needed" cares for used CD-RW, DVD-RW and for used
1643 overwriteable media by applying -blank "fast". It applies
1644 -format "full" to yet unformatted DVD-RAM and BD-RE. Other
1645 media in blank state are gracefully ignored. Media which cannot
1646 be made ready for writing from scratch cause a FAILURE event.
1647 "fast" makes CD-RW and unformatted DVD-RW re-usable, or
1648 invalidates overwriteable ISO images. "all" might work more
1649 thoroughly and need more time.
1650 "deformat" converts overwriteable DVD-RW into unformatted ones.
1651 "deformat_quickest" is a faster way to deformat or blank DVD-RW
1652 but produces media which are only suitable for a single session.
1653 Some drives announce this state by not offering feature 21h, but
1654 some drives offer it anyway. If feature 21h is missing, then
1655 xorriso will refuse to write on DVD-RW if not option -close is
1656 set to "on".
1657 The progress reports issued by some drives while blanking are
1658 quite unrealistic. Do not conclude success or failure from the
1659 reported percentages. Blanking was successful if no SORRY event
1660 or worse occured.
1661 -format mode
1663 Convert unformatted DVD-RW into overwriteable ones, "de-ice"
1664 DVD+RW, format newly purchased BD-RE or BD-R, re-format DVD-RAM
1665 or BD-RE.
1666 Defined modes are:
1667 as_needed, full, fast, by_index_<num>, fast_by_index_<num>
1668 "as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or
1669 blank unformatted BD-R. Other media are left untouched.
1670 "full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank
1671 unformatted BD-R.
1672 "fast" does the same as "full" but tries to be quicker.
1673 "by_index_" selects a format out of the descriptor list issued
1674 by option -list_formats. The index number from that list is to
1675 be appended to the mode word. E.g: "by_index_3".
1676 "fast_by_index_" does the same as "by_index_" but tries to be
1677 quicker.
1678 "by_size_" selects a format out of the descriptor list which
1679 provides at least the given size. That size is to be appended to
1680 the mode word. E.g: "by_size_4100m". This applies to media with
1681 Defect Management.
1682 "fast_by_size_" does the same as "by_size_" but tries to be
1683 quicker.
1684 The formatting action has no effect on media if -dummy is
1685 activated.
1686 Formatting is normally needed only once during the lifetime of a
1687 medium, if ever. But it is a reason for re-formatting if:
1688 DVD-RW was deformatted by -blank,
1689 DVD+RW has read failures (re-format before next write),
1690 DVD-RAM or BD-RE shall change their amount of defect reserve.
1691 BD-R may be written unformatted or may be formatted before first
1692 use. Formatting activates Defect Management which tries to
1693 catch and repair bad spots on media during the write process at
1694 the expense of half speed even with flawless media.
1695 The progress reports issued by some drives while formatting are
1696 quite unrealistic. Do not conclude success or failure from the
1697 reported percentages. Formatting was successful if no SORRY
1698 event or worse occured. Be patient with apparently frozen
1699 progress.
1700 -list_formats
1702 Put out a list of format descriptors as reported by the output
1703 drive for the current medium. The list gives the index number
1704 after "Format idx", a MMC format code, the announced size in
1705 blocks (like "2236704s") and the same size in MiB.
1706 MMC format codes are manifold. Most important are: "00h" general
1707 formatting, "01h" increases reserve space for DVD-RAM, "26h" for
1708 DVD+RW, "30h" for BD-RE with reserve space, "31h" for BD-RE
1709 without reserve space, "32h" for BD-R.
1710 Smaller format size with DVD-RAM, BD-RE, or BD-R means more
1711 reserve space.
1712 -list_speeds
1714 Put out a list of speed values as reported by the output drive
1715 with the loaded medium. This does not necessarily mean that the
1716 medium is writable or that these speeds are actually achievable.
1717 Especially the lists reported with empty drive or with ROM media
1718 obviously advertise speeds for other media.
1719 It is not mandatory to use speed values out of the listed range.
1720 The drive is supposed to choose a safe speed that is as near to
1721 the desired speed as possible.
1722 At the end of the list, "Write speed L" and "Write speed H" are
1723 the best guesses for lower and upper speed limit. "Write speed
1724 l" and "Write speed h" may appear only with CD and eventually
1725 override the list of other speed offers.
1726 -close_damaged "as_needed"|"force"
1728 Try to close the upcomming track and session if the drive
1729 reported the medium as damaged. This may apply to CD-R, CD-RW,
1730 DVD-R, DVD-RW, DVD+R, DVD+R DL, or BD-R media. It is indicated
1731 by warning messages when the drive gets aquired, and by a remark
1732 "but next track is damaged" with the line "Media status :" of
1733 command -toc.
1734 The setting of option -close determines whether the medium stays
1735 appendable.
1736 Mode "as_needed" gracefully refuses on media which are not
1737 reported as damaged. Mode "force" attempts the close operation
1738 even with media which appear undamaged.
1739 No image changes are allowed to be pending before this command
1740 is performed. After closing was attempted, both drives are
1741 given up.
1742 -list_profiles "in"|"out"|"all"
1744 Put out a list of media types supported by -indev, resp.
1745 -outdev, resp. both. The currently recognized type is marked by
1746 text "(current)".
1747 Settings for result writing:
1749 Rock Ridge info will be generated by the program unconditionally. ACLs
1751 will be written according to the setting of option -acl.
1752 -joliet "on"|"off"
1754 If enabled by "on", generate Joliet tree additional to ISO 9660
1755 + Rock Ridge tree.
1756 -compliance rule[:rule...]
1758 Adjust the compliance to specifications of ISO 9660 and its
1759 contemporary extensions. In some cases it is worth to deviate a
1760 bit in order to circumvent bugs of the intended reader system or
1761 to get unofficial extra features.
1762 There are several adjustable rules which have a keyword each. If
1763 they are mentioned with this option then their rule gets added
1764 to the relaxation list. This list can be erased by rules
1765 "strict" or "clear". It can be reset to its start setting by
1766 "default". All of the following relaxation rules can be revoked
1767 individually by appending "_off". Like "deep_paths_off".
1768 Rule keywords are:
1769 "iso_9660_level="number chooses level 1 with ISO names of the
1770 form 8.3 and -file_size_limit <= 4g - 1, or level 2 with ISO
1771 names up to length 32 and the same -file_size_limit, or level 3
1772 with ISO names up to length 32 and -file_size_limit >= 400g
1773 -200k. If necessary -file_size_limit gets adjusted.
1774 "allow_dir_id_ext" allows ISO names of directories to have a
1775 name extension as with other file types. It does not force dots
1776 and it omits the version number, though. This is a bad tradition
1777 of mkisofs which violates ECMA-119. Especially ISO level 1 only
1778 allows 8 characters in a directory name and not 8.3.
1779 "omit_version" does not add versions (";1") to ISO and Joliet
1780 file names.
1781 "only_iso_version" does not add versions (";1") to Joliet file
1782 names.
1783 "deep_paths" allows ISO file paths deeper than 8 levels.
1784 "long_paths" allows ISO file paths longer than 255 characters.
1785 "long_names" allows up to 37 characters with ISO file names.
1786 "no_force_dots" does not add a dot to ISO file names which have
1787 none.
1788 "no_j_force_dots" does not add a dot to Joliet file names which
1789 have none.
1790 "lowercase" allows lowercase characters in ISO file names.
1791 "full_ascii" allows all ASCII characters in ISO file names.
1792 "untranslated_names" might be dangerous for inadverted reader
1793 programs which rely on the restriction to at most 37 characters
1794 in ISO file names. This option allows ISO file names up to 96
1795 characters with no character conversion. If a file name has more
1796 characters, then image production will fail deliberately.
1797 "untranslated_name_len="number enables untranslated_names with a
1798 smaller limit for the length of file names. 0 disables this
1799 feature, -1 chooses maximum length limit, numbers larger than 0
1800 give the desired length limit.
1801 "joliet_long_names" allows Joliet leaf names up to 103
1802 characters rather than 64.
1803 "joliet_long_paths" allows Joliet paths longer than 240
1804 characters.
1805 "always_gmt" stores timestamps in GMT representation with
1806 timezone 0.
1807 "rec_mtime" records with ISO files the disk file's mtime and not
1808 the creation time of the image.
1809 "new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux
1810 but not for older FreeBSD or for Solaris). This implies
1811 "aaip_susp_1_10_off" which may be changed by subsequent
1812 "aaip_susp_1_10".
1813 Default is "old_rr" which uses Rock Ridge version 1.10. This
1814 implies also "aaip_susp_1_10" which may be changed by subsequent
1815 "aaip_susp_1_10_off".
1816 "aaip_susp_1_10" allows AAIP to be written as unofficial
1817 extension of RRIP rather than as official extension under
1818 SUSP-1.12.
1819 "no_emul_toc" saves 64 kB with the first session on
1820 overwriteable media but makes the image incapable of displaying
1821 its session history.
1822 "iso_9660_1999" causes the production of an additional directory
1823 tree compliant to ISO 9660:1999. It can record long filenames
1824 for readers which do not understand Rock Ridge.
1825 "old_empty" uses the old way of of giving block addresses in the
1826 range of [0,31] to files with no own data content. The new way
1827 is to have a dedicated block to which all such files will point.
1828 Default setting is
1829 "clear:only_iso_version:deep_paths:long_paths:no_j_force_dots:
1830 always_gmt:old_rr".
1831 Note: The term "ISO file" means the plain ISO 9660 names and
1832 attributes which get visible if the reader ignores Rock Ridge.
1833 -volid text
1835 Specify the volume ID. xorriso accepts any text up to 32
1836 characters, but according to rarely obeyed specs stricter rules
1837 apply:
1838 ECMA 119 demands ASCII characters out of [A-Z0-9_]. Like:
1839 "IMAGE_23"
1840 Joliet allows 16 UCS-2 characters. Like: "Windows name"
1841 Be aware that the volume id might get used automatically as name
1842 of the mount point when the medium is inserted into a playful
1843 computer system.
1844 If an ISO image gets loaded while the volume ID is set to
1845 default "ISOIMAGE" or to "", then the volume ID of the loaded
1846 image will become the effective volume id for the next write
1847 run. But as soon as command -volid is performed afterwards, this
1848 pending id is overridden by the new setting.
1849 Consider this when setting -volid "ISOIMAGE" before executing
1850 -dev, -indev, or -rollback. If you insist in -volid "ISOIMAGE",
1851 set it again after those commands.
1852 -volset_id text
1854 Set the volume set id string to be written with the next
1855 -commit. Permissible are up to 128 characters. This setting
1856 gets overridden by image loading.
1857 -publisher text
1859 Set the publisher id string to be written with the next -commit.
1860 This may identify the person or organisation who specified what
1861 shall be recorded. Permissible are up to 128 characters. This
1862 setting gets overridden by image loading.
1863 -application_id text
1865 Set the application id string to be written with the next
1866 -commit. This may identify the specification of how the data are
1867 recorded. Permissible are up to 128 characters. This setting
1868 gets overridden by image loading.
1869 The special text "@xorriso@" gets converted to the id string of
1870 xorriso which is normally written as -preparer_id. It is a wrong
1871 tradition to write the program id as -application_id.
1872 -system_id text
1874 Set the system id string to be written with the next -commit.
1875 This may identify the system which can recognize and act upon
1876 the content of the System Area in image blocks 0 to 15.
1877 Permissible are up to 32 characters. This setting gets
1878 overridden by image loading.
1879 -volume_date type timestring
1881 Set one of the four overall timestamps for subsequent image
1882 writing. Available types are:
1883 "c" time when the volume was created.
1884 "m" time when volume was last modified.
1885 "x" time when the information in the volume expires.
1886 "f" time since when the volume is effectively valid.
1887 "uuid" sets a timestring that overrides "c" and "m" times
1888 literally. It must consist of 16 decimal digits which form
1889 YYYYMMDDhhmmsscc, with YYYY between 1970 and 2999. Time zone is
1890 GMT. It is supposed to match this GRUB line:
1891 search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc
1892 E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
1893 Timestrings for the other types may be given as with option
1894 -alter_date. They are prone to timezone computations. The
1895 timestrings "default" or "overridden" cause default settings:
1896 "c" and "m" will show the current time of image creation. "x"
1897 and "f" will be marked as insignificant. "uuid" will be
1898 deactivated.
1899 -copyright_file text
1901 Set the copyright file name to be written with the next -commit.
1902 This should be the ISO 9660 path of a file in the image which
1903 contains a copyright statement. Permissible are up to 37
1904 characters. This setting gets overridden by image loading.
1905 -abstract_file text
1907 Set the abstract file name to be written with the next -commit.
1908 This should be the ISO 9660 path of a file in the image which
1909 contains an abstract statement about the image content.
1910 Permissible are up to 37 characters. This setting gets
1911 overridden by image loading.
1912 -biblio_file text
1914 Set the biblio file name to be written with the next -commit.
1915 This should be the ISO 9660 path of a file in the image which
1916 contains bibliographic records. Permissible are up to 37
1917 characters. This setting gets overridden by image loading.
1918 -preparer_id
1920 Set the preparer id string to be written with the next -commit.
1921 This may identify the person or other entity which controls the
1922 preparation of the data which shall be recorded. Normally this
1923 should be the id of xorriso and not of the person or program
1924 which operates xorriso. Please avoid to change it. Permissible
1925 are up to 128 characters.
1926 The special text "@xorriso@" gets converted to the id string of
1927 xorriso which is default at program startup.
1928 Unlike other id strings, this setting is not influenced by image
1929 loading.
1930 -out_charset character_set_name
1932 Set the character set to which file names get converted when
1933 writing an image. See paragraph "Character sets" for more
1934 explanations. When loading the written image after -commit the
1935 setting of -out_charset will be copied to -in_charset.
1936 -uid uid
1938 User id to be used for all files when the new ISO tree gets
1939 written to media.
1940 -gid gid
1942 Group id to be used for all files when the new ISO tree gets
1943 written to media.
1944 -zisofs option[:options]
1946 Set global parameters for zisofs compression. This data format
1947 is recognized and transparently uncompressed by some Linux
1948 kernels. It is to be applied via option -set_filter with
1949 built-in filter "--zisofs". Parameters are:
1950 "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow
1951 "block_size="32k|64k|128k size of compression blocks
1952 "by_magic=on" enables an expensive test at image generation
1953 time which checks files from disk whether they already are
1954 zisofs compressed, e.g. by program mkzftree.
1955 "default" same as "level=6:block_size=32k:by_magic=off"
1956 -speed number[k|m|c|d|b]
1958 Set the burn speed. Default is 0 = maximum speed. Speed can be
1959 given in media dependent numbers or as a desired throughput per
1960 second in MMC compliant kB (= 1000) or MB (= 1000 kB). Media
1961 x-speed factor can be set explicity by "c" for CD, "d" for DVD,
1962 "b" for BD, "x" is optional.
1963 Example speeds:
1964 706k = 706kB/s = 4c = 4xCD
1965 5540k = 5540kB/s = 4d = 4xDVD
1966 If there is no hint about the speed unit attached, then the
1967 medium in the -outdev will decide. Default unit is CD = 176.4k.
1968 MMC drives usually activate their own idea of speed and take the
1969 speed value given by the burn program only as upper limit for
1970 their own decision.
1971 -stream_recording "on"|"off"|"full"|"data"|number
1973 Setting "on" tries to circumvent the management of defects on
1974 DVD-RAM, BD-RE, or BD-R. Defect management keeps partly damaged
1975 media usable. But it reduces write speed to half nominal speed
1976 even if the medium is in perfect shape. For the case of
1977 flawless media, one may use -stream_recording "on" to get full
1978 speed.
1979 "full" tries full speed with all write operations, whereas "on"
1980 does this only above byte address 32s. One may give a number of
1981 at least 16s in order to set an own address limit.
1982 "data" causes full speed to start when superblock and directory
1983 entries are written and writing of file content blocks begins.
1984 -dvd_obs "default"|"32k"|"64k"
1986 GNU/Linux specific: Set the number of bytes to be transmitted
1987 with each write operation to DVD or BD media. A number of 64 KB
1988 may improve throughput with bus systems which show latency
1989 problems. The default depends on media type, on option
1990 -stream_recording , and on compile time options.
1991 -stdio_sync "on"|"off"|number
1993 Set the number of bytes after which to force output to stdio:
1994 pseudo drives. This forcing keeps the memory from being clogged
1995 with lots of pending data for slow devices. Default "on" is the
1996 same as "16m". Forced output can be disabled by "off".
1997 -dummy "on"|"off"
1999 If "on" then simulate burning or refuse with FAILURE event if no
2000 simulation is possible, do neither blank nor format.
2001 -fs number["k"|"m"]
2003 Set the size of the fifo buffer which smoothens the data stream
2004 from ISO image generation to media burning. Default is 4 MiB,
2005 minimum 64 kiB, maximum 1 GiB. The number may be followed by
2006 letter "k" or "m" which means unit is kiB (= 1024) or MiB (=
2007 1024 kiB).
2008 -close "on"|"off"
2010 If "on" then mark the written medium as not appendable any more
2011 (if possible at all with the given type of target media).
2012 This is the contrary of cdrecord, wodim, cdrskin option -multi,
2013 and is one aspect of growisofs option -dvd-compat.
2014 -padding number["k"|"m"]|"included"|"appended"
2016 Append the given number of extra bytes to the image stream.
2017 This is a traditional remedy for a traditional bug in block
2018 device read drivers. Needed only for CD recordings in TAO mode.
2019 Since one can hardly predict on what media an image might end
2020 up, xorriso adds the traditional 300k of padding by default to
2021 all images.
2022 For images which will never get to a CD it is safe to use
2023 -padding 0 .
2024 Normally padding is not written as part of the ISO image but
2025 appended after the image end. This is -padding mode "appended".
2026 Emulation command -as "mkisofs" and command -jigdo cause padding
2027 to be written as part of the image. The same effect is achieved
2028 by -padding mode "included".
2029 Bootable ISO images:
2031 Contrary to published specifications many BIOSes will load an El Torito
2033 record from the first session on media and not from the last one, which
2034 gets mounted by default. This makes no problems with overwriteable
2035 media, because they appear to inadverted readers as one single session.
2036 But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that
2037 the whole bootable system has to reside already in the first session
2038 and that the last session still has to bear all files which the booted
2039 system expects after mounting the ISO image.
2040 If a boot image from ISOLINUX or GRUB is known to be present on media
2041 then it is advised to patch it when a follow-up session gets written.
2042 But one should not rely on the capability to influence the bootability
2043 of the existing sessions, unless one can assume overwriteable media.
2044 There are booting mechanisms which do not use an El Torito record but
2045 rather start at the first bytes of the image: PC-BIOS MBR for
2046 hard-disk-like devices, MIPS Volume Header for old SGI computers, DEC
2047 Boot Block for old DECstation, SUN Disk Label for SPARC machines.
2048 The boot firmware EFI may use programs which are located in a FAT
2049 filesystem and announced by an MBR partition table entry.
2050 -boot_image "any"|"isolinux"|"grub"
2052 "discard"|"keep"|"patch"|"show_status"|bootspec|"next"
2053 Define the handling of a set of El Torito boot images which has
2054 been read from an existing ISO image or define how to make a
2055 prepared boot image file set bootable. Such file sets get
2056 produced by ISOLINUX or GRUB.
2057 Each -boot_image command has two arguments: type and setting.
2058 More than one -boot_image command may be used to define the
2059 handling of one or more boot images. Sequence matters.
2060 Types isolinux and grub care for known peculiarities. Type any
2061 makes no assumptions about the origin of the boot images.
2062 El Torito boot images of any type can be newly inserted, or
2064 discarded, or patched, or kept unaltered. Whether to patch or
2065 to keep depends on whether the boot images contain boot info
2066 tables.
2067 A boot info table needs to be patched when the boot image gets
2068 newly introduced into the ISO image or if an existing image gets
2069 relocated. This is automatically done if type "isolinux" or
2070 "grub" is given, but not with "any".
2071 If patching is enabled, then boot images from previous sessions
2072 will be checked whether they seem to bear a boot info table. If
2073 not, then they stay unpatched. This check is not infallible. So
2074 if you do know that the images need no patching, use "any"
2075 "keep". "grub" "patch" will not patch EFI images
2076 (platform_id=0xef).
2077 Most safe is the default: -boot_image "any" "discard".
2078 Advised for GRUB : -boot_image "grub" "patch"
2079 For ISOLINUX : -boot_image "isolinux" "patch"
2080 show_status will print what is known about the loaded boot
2081 images and their designated fate.
2082 A bootspec is a word of the form name=valuei. It is used to
2084 describe the parameters of a boot image by an El Torito record
2085 or a MBR. The names "dir", "bin_path", "efi_path" lead to El
2086 Torito bootable images. Name "system_area" activates a given
2087 file as MBR.
2088 On all media types this is possible within the first session. In
2089 further sessions an existing boot image can get replaced by a
2090 new one, but depending on the media type this may have few
2091 effect at boot time. See above.
2092 The boot image and its supporting files have to be added to the
2093 ISO image by normal means (image loading, -map, -add, ...). In
2094 case of ISOLINUX the files should reside either in ISO image
2095 directory /isolinux or in /boot/isolinux . In that case it
2096 suffices to use as bootspec the text "dir=/isolinux" or
2097 "dir=/boot/isolinux". E.g.:
2098 -boot_image isolinux dir=/boot/isolinux
2099 which bundles these individual settings:
2100 -boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
2101 -boot_image isolinux cat_path=/boot/isolinux/boot.cat
2102 -boot_image isolinux load_size=2048
2103 -boot_image any boot_info_table=on
2104 An El Torito boot catalog file gets inserted into the ISO image
2105 with address cat_path= at -commit time. It is subject to normal
2106 -overwrite and -reassure processing if there is already a file
2107 with the same name. The catalog lists the boot images and is
2108 read by the boot facility to choose one of the boot images. But
2109 it is not necessary that it appears in the directory tree at
2110 all. One may hide it in all trees by cat_hidden=on. Other
2111 possible values are "iso_rr", "joliet", and the default "off".
2112 bin_path= depicts a boot image file, a binary program which is
2113 to be started by the hardware boot facility (e.g. the BIOS) at
2114 boot time.
2115 efi_path= depicts a boot image file that is ready for EFI
2116 booting. Its load_size is determined automatically, no boot
2117 info table gets written, no boot medium gets emulated,
2118 platform_id is 0xef.
2119 emul_type= can be one of "no_emulation", "hard_disk",
2120 "diskette". It controls the boot medium emulation code of a
2121 boot image. The default "no_emulation" is suitable for
2122 ISOLINUX, GRUB, FreeBSD cdboot.
2123 load_size= is a value which depends on the boot image. Default
2124 2048 should be overridden only if a better value is known.
2125 boot_info_table=on may be used to apply patching to a boot image
2126 which is given by "any" "bin_path=". "boot_info_table=off"
2127 disables patching.
2128 platform_id= defines by two hex digits the Platform ID of the
2129 boot image. "00" is 80x86 PC-BIOS, "01" is PowerPC, "02" is Mac,
2130 "ef" is EFI.
2131 id_string=text|56_hexdigits defines the ID string of the boot
2132 catalog section where the boot image will be listed. If the
2133 value consists of 56 characters [0-9A-Fa-f] then it is converted
2134 into 28 bytes, else the first 28 characters become the ID
2135 string. The ID string of the first boot image becomes the
2136 overall catalog ID. It is limited to 24 characters. Other
2137 id_strings become section IDs.
2138 sel_crit=hexdigits defines the Selection Criteria of the boot
2139 image. Up to 20 bytes get read from the given characters
2140 [0-9A-Fa-f]. They get attributed to the boot image entry in the
2141 catalog.
2142 next ends the definition of a boot image and starts a new one.
2143 Any following -bootimage bootspecs will affect the new image.
2144 The first "next" discards loaded boot images and their catalog.
2145 discard gives up an existing boot catalog and its boot images.
2146 keep keeps or copies boot images unaltered and writes a new
2147 catalog.
2148 patch applies patching to existing boot images if they seem to
2149 bear a boot info table.
2150 system_area=disk_path copies at most 32768 bytes from the given
2151 disk file to the very start of the ISO image. This System Area
2152 is reserved for system dependent boot software, e.g. an MBR
2153 which can be used to boot from USB stick or hard disk.
2154 Other than a El Torito boot image, the file disk_path needs not
2155 to be added to the ISO image.
2156 -boot_image isolinux system_area= implies "partition_table=on".
2157 partition_table=on causes a simple partition table to be written
2158 into bytes 446 to 511 of the System Area.
2159 With type "isolinux" it shows a partition that begins at byte 0
2160 and it causes the LBA of the first boot image to be written into
2161 the MBR. For the first session this works only if also
2162 "system_area=" and "bin_path=" or "dir=" is given.
2163 With types "any" and "grub" it shows a single partiton which
2164 starts at byte 512 and ends where the ISO image ends. This
2165 works with or without system_area= or boot image.
2166 In follow-up sessions the existing System Area is preserved by
2167 default. If types "isolinux" or "grub" are set to "patch", then
2168 "partition_table=on" is activated without new boot image. In
2169 this case the existing System Area gets checked whether it bears
2170 addresses and sizes as if it had been processed by
2171 "partition_table=on". If so, then those parameters get updated
2172 when the new System Area is written.
2173 Special "system_area=/dev/zero" causes 32k of NUL-bytes. Use
2174 this to discard an MBR which was loaded with the ISO image.
2175 partition_offset=2kb_block_adr causes a partition table with a
2176 single partition that begins at the given block address. This is
2177 counted in 2048 byte blocks, not in 512 byte blocks. If the
2178 block address is non-zero then it must be at least 16. A
2179 non-zero partition offset causes two superblocks to be generated
2180 and two sets of directory trees. The image is then mountable
2181 from its absolute start as well as from the partition start.
2182 The offset value of an ISO image gets preserved when a new
2183 session is added. So the value defined here is only in effect
2184 if a new ISO image gets written.
2185 partition_hd_cyl=number gives the number of heads per cylinder
2186 for the partition table. 0 chooses a default value. Maximum is
2187 255.
2188 partition_sec_hd=number gives the number of sectors per head for
2189 the partition table. 0 chooses a default value. Maximum is 63.
2190 The product partition_sec_hd * partition_hd_cyl * 512 is the
2191 cylinder size. It should be divisible by 2048 in order to allow
2192 exact alignment. If it is too small to describe the image size
2193 by at most 1024 cylinders, then appropriate values of
2194 partition_hd_cyl are chosen with partition_sec_hd 32 or 63. If
2195 the image is larger than 8,422,686,720 bytes, then the cylinder
2196 size constraints cannot be fulfilled.
2197 partition_cyl_align=mode controls image size alignment to an
2198 integer number of cylinders. It is prescribed by isohybrid specs
2199 and it seems to please program fdisk. Cylinder size must be
2200 divisible by 2048. Images larger than 8,323,596,288 bytes
2201 cannot be aligned.
2202 Mode "auto" is default. Alignment by padding happens only with
2203 "isolinux" "partition_table=on".
2204 Mode "on" causes alignment by padding with "partition_table=on"
2205 for any type. Mode "off" disables alignment for any type.
2206 mips_path=iso_rr_path declares a data file in the image to be a
2207 MIPS Big Endian boot file and causes production of a MIPS Big
2208 Endian Volume Header. This is mutually exclusive with production
2209 of other boot blocks like MBR. It will overwrite the first 512
2210 bytes of any data provided by system_area=. Up to 15 boot files
2211 can be declared by mips_path=.
2212 mipsel_path=iso_rr_path declares a data file in the image to be
2213 the MIPS Little Endian boot file. This is mutually exclusive
2214 with other boot blocks. It will overwrite the first 512 bytes
2215 of any data provided by system_area=. Only a single boot file
2216 can be declared by mipsel_path=.
2217 sparc_label=text causes the production of a SUN Disk Label with
2218 the given text as ASCII label. This boot block format allows to
2219 append images for partitions 2 to 8. Partition 1 will always be
2220 the ISO image. See option -append_partition. The first 512
2221 bytes of any data provided by system_area= will be overwritten.
2222 mips_discard and sparc_discard revoke any boot file declarations
2223 made by mips_path= or mipsel_path=. They also disable production
2224 of SUN Disk Label. This removes the ban on production of other
2225 boot blocks.
2226 -append_partition partition_number type_code disk_path
2228 Cause a prepared filesystem image to be appended to the ISO
2229 image and to be described by a partition table entry in a boot
2230 block at the start of the emerging ISO image. The partition
2231 entry will bear the size of the submitted file rounded up to the
2232 next multiple of 2048 bytes.
2233 Beware of subsequent multi-session runs. The appended partition
2234 will get overwritten.
2235 Partitions may be appended with boot block type MBR and with SUN
2236 Disk Label.
2237 With MBR:
2238 partition_number may be 1 to 4. Number 1 will put the whole ISO
2239 image into the unclaimed space before partition 1. So together
2240 with most xorriso MBR features, number 2 would be the most
2241 natural choice.
2242 The type_code may be "FAT12", "FAT16", "Linux", or a hexadecimal
2243 number between 0x00 and 0xff. Not all those numbers will yield
2244 usable results. For a list of codes search the Internet for
2245 "Partition Types" or run fdisk command "L".
2246 The disk_path must provide the necessary data bytes at commit
2247 time. An empty disk_path disables this feature for the given
2248 partition number.
2249 With SUN Disk Label (selected by -boot_image any sparc_label=):
2250 partition_number may be 2 to 8. Number 1 will always be the ISO
2251 image. Partition start addresses are aligned to 320 KiB. The
2252 type_code does not matter. Submit 0x0.
2253 Partition image name "." causes the partition to become a copy
2254 of the next lower valid one.
2255 Jigdo Template Extraction:
2257 From man genisoimage: "Jigdo is a tool to help in the distribution of
2259 large files like CD and DVD images; see http://atterer.net/jigdo/ for
2260 more details. Debian CDs and DVD ISO images are published on the web in
2261 jigdo format to allow end users to download them more efficiently."
2262 xorriso can produce a .jigdo and a .template file together with a
2263 single-session ISO image. The .jigdo file contains checksums and
2264 symbolic file addresses. The .template file contains the compressed
2265 ISO image with reference tags instead of the content bytes of the
2266 listed files.
2267 Input for this process are the normal arguments for a xorriso session
2268 on a blank -outdev, and a .md5 file which lists those data files which
2269 may be listed in the .jigdo file and externally referenced in the
2270 .template file. Each designated file is represented in the .md5 file
2271 by a single text line:
2272 MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2
2273 blanks, symbolic file address
2274 The file address in an .md5 line has to bear the same basename as the
2275 disk_path of the file which it shall match. The directory path of the
2276 file address is decisive for To=From mapping, not for file recognition.
2277 After To=From mapping, the file address gets written into the .jigdo
2278 file. Jigdo restore tools will convert these addresses into really
2279 reachable data source addresses from which they can read.
2280 If the list of jigdo parameters is not empty, then xorriso will refuse
2281 to write to non-blank targets, it will disable multi-session emulation,
2282 and padding will be counted as part of the ISO image.
2283 -jigdo parameter_name value
2285 Clear Jigdo Template Extraction parameter list or add a
2286 parameter to that list. The alias names are the corresponding
2287 genisoimage options. They are accepted as parameter names as
2288 well. Especially they are recognized by the -as mkisofs
2289 emulation command.
2290 Parameter clear with any value empties the whole list. No
2291 .jigdo and .template file will be produced.
2292 template_path sets the disk_path for the .template file with the
2293 holed and compressed ISO image copy.
2294 Alias: -jigdo-template
2295 jigdo_path sets the disk_path for the .jigdo file with the
2296 checksums and download addresses for filling the holes in
2297 .template.
2298 Alias: -jigdo-jigdo
2299 md5_path sets the disk_path where to find the .md5 input file.
2300 Alias: -md5-list
2301 min_size sets the minimum size for a data file to be listed in
2302 the .jigdo file and being a hole in the .template file.
2303 Alias: -jigdo-min-file-size
2304 exclude adds a regular expression pattern which will get
2305 compared with the absolute disk_path of any data file. A match
2306 causes the file to stay in .template in any case.
2307 Alias: -jigdo-exclude
2308 demand_md5 adds a regular expression pattern which will get
2309 compared with the absolute disk_path of any data file that was
2310 not found in the .md5 list. A match causes a MISHAP event.
2311 Alias: -jigdo-force-md5
2312 mapping adds a string pair of the form To=From to the parameter
2313 list. If a data file gets listed in the .jigdo file, then it is
2314 referred by the file address from its line in the .md5 file.
2315 This file address gets checked whether it begins with the From
2316 string. If so, then this string will be replaced by the To
2317 string and a ':' character, before it goes into the .jigdo file.
2318 The From string should end by a '/' character.
2319 Alias: -jigdo-map
2320 compression chooses one of "bzip2" or "gzip" for the compression
2321 of the template file. The jigdo file is put out uncompressed.
2322 Alias: -jigdo-template-compress
2323 checksum_iso chooses one or more of "md5", "sha1", "sha256",
2324 "sha512" for the auxiliary "# Image Hex" checksums in the jigdo
2325 file. The value may e.g. look like "md5,sha1,sha512". Value
2326 "all" chooses all available algorithms. Note that MD5 stays
2327 always enabled.
2328 Alias: -checksum_algorithm_iso
2329 checksum_template is like checksum_iso but for "# Template Hex".
2330 Alias: -checksum_algorithm_template
2331 Character sets:
2333 File names are strings of non-zero bytes with 8 bit each. Unfortunately
2335 the same byte string may appear as different peculiar national
2336 characters on differently nationalized terminals. The meanings of byte
2337 codes are defined in character sets which have names. Shell command
2338 iconv -l lists them.
2339 Character sets should not matter as long as only english alphanumeric
2340 characters are used for file names or as long as all writers and
2341 readers of the media use the same character set. Outside these
2342 constraints it may be necessary to let xorriso convert byte codes.
2343 There is an input conversion from input character set to the local
2344 character set which applies when an ISO image gets loaded. A conversion
2345 from local character set to the output character set is performed when
2346 an image tree gets written. The sets can be defined independently by
2347 options -in_charset and -out_charset. Normally one will have both
2348 identical, if ever.
2349 If conversions are desired then xorriso needs to know the name of the
2350 local character set. xorriso can inquire the same info as shell command
2351 "locale" with argument "charmap". This may be influenced by environment
2352 variables LC_ALL, LC_CTYPE, or LANG and should match the expectations
2353 of the terminal.
2354 The default output charset is the local character set of the terminal
2355 where xorriso runs. So by default no conversion happens between local
2356 filesystem names and emerging names in the image. The situation stays
2357 ambigous and the reader has to riddle what character set was used.
2358 By option -auto_charset it is possible to attribute the output charset
2359 name to the image. This makes the situation unambigous. But if your
2360 terminal character set does not match the character set of the local
2361 file names, then this attribute can become plainly wrong and cause
2362 problems at read time. To prevent this it is necessary to check
2363 whether the terminal properly displays all intended filenames. Check
2364 especially the exotic national characters.
2365 To enforce recording of a particular character set name without any
2366 conversion at image generation time, set -charset and -local_charset to
2367 the desired name, and enable -backslash_codes to avoid evil character
2368 display on your terminal.
2369 -charset character_set_name
2371 Set the character set from which to convert file names when
2372 loading an image and to which to convert when writing an image.
2373 -local_charset character_set_name
2375 Override the system assumption of the local character set name.
2376 If this appears necessary, one should consider to set
2377 -backslash_codes to "on" in order to avoid dangerous binary
2378 codes being sent to the terminal.
2379 Exception processing:
2381 Since the tasks of xorriso are manifold and prone to external
2383 influence, there may arise the need for xorriso to report and handle
2384 problem events.
2385 Those events get classified when they are detected by one of the
2386 software modules and forwarded to reporting and evaluation modules
2387 which decide about reactions. Event classes are sorted by severity:
2388 "NEVER" The upper end of the severity spectrum.
2389 "ABORT" The program is being aborted and on its way to end.
2390 "FATAL" The main purpose of the run failed or an important resource
2391 failed unexpectedly.
2392 "FAILURE" An important part of the job could not be performed.
2393 "MISHAP" A FAILURE which can be tolerated during ISO image generation.
2394 "SORRY" A less important part of the job could not be performed.
2395 "WARNING" A situation is suspicious of being not intended by the user.
2396 "HINT" A proposal to the user how to achieve better results.
2397 "NOTE" A harmless information about noteworthy circumstances.
2398 "UPDATE" A pacifier message during long running operations.
2399 "DEBUG" A message which would only interest the program developers.
2400 "ALL" The lower end of the severity spectrum.
2401 -abort_on severity
2403 Set the severity threshold for events to abort the program.
2404 Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY"
2405 It may become necessary to abort the program anyway, despite the
2406 setting by this option. Expect not many "ABORT" events to be
2407 ignorable.
2408 A special property of this option is that it works preemptive if
2409 given as program start argument. I.e. the first -abort_on
2410 setting among the start arguments is in effect already when the
2411 first operations of xorriso begin. Only "-abort_on" with dash
2412 "-" is recognized that way.
2413 -return_with severity exit_value
2415 Set the threshold and exit_value to be returned at program end
2416 if no abort has happened. This is to allow xorriso to go on
2417 after problems but to get a failure indicating exit value from
2418 the program, nevertheless. Useful is a value lower than the
2419 -abort_on threshold, down to "WARNING".
2420 exit_value may be either 0 (indicating success to the starter of
2421 the program) or a number between 32 and 63. Some other
2422 exit_values are used by xorriso if it decides to abort the
2423 program run:
2424 1=abort due to external signal
2425 2=no program arguments given
2426 3=creation of xorriso main object failed
2427 4=failure to start libburnia-project.org libraries
2428 5=program abort during argument processing
2429 6=program abort during dialog processing
2430 -report_about severity
2432 Set the threshold for events to be reported.
2433 Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG",
2434 "ALL"
2435 Regardless what is set by -report_about, messages get always
2436 reported if they reach the severity threshold of -abort_on .
2437 Event messages are sent to the info channel "I" which is usually
2438 stderr but may be influenced by command -pkt_output. Info
2439 messages which belong to no event get attributed severity
2440 "NOTE".
2441 A special property of this option is that the first
2442 -report_about setting among the start arguments is in effect
2443 already when the first operations of xorriso begin. Only
2444 "-report_about" with dash "-" is recognized that way.
2445 -signal_handling mode
2447 Control the installation of a signal handler which shall react
2448 on external signals (e.g. from program "kill" or from keys
2449 Ctrl+C) or on signals caused by severe program errors.
2450 Mode "on" is the default. It uses the signal handler of libburn
2451 which produces ugly messages but puts much effort in releasing
2452 optical drives before xorriso ends.
2453 Mode "off" as first -signal_handling among the start arguments
2454 prevents all own signal precautions of xorriso. Inherited signal
2455 handler settings stay as they are.
2456 It works like "sig_dfl" if given after other signal handling was
2457 already established at program start.
2458 Mode "sig_dfl" uses the system provided default handling of
2459 signals, which is normally a sudden abort of the program. To
2460 prevent stuck drives, the libburn handler is used during
2461 burning, blanking, and formatting on MMC drives.
2462 Mode "sig_ign" tries to ignore as many signal types as possible.
2463 This imposes the risk that xorriso refuses to end until
2464 externally kill -9 if performed. kill -9 then imposes the risk
2465 that the drive is left in unusable state and needs poweroff to
2466 be reset. So during burning, blanking, and formatting wait for
2467 at least their normal run time before killing externally.
2468 A special property of this option is that the first
2469 -signal_handling setting among the start arguments is in effect
2470 already when the first operations of xorriso begin. Only
2471 "-signal_handling" with dash "-" is recognized that way.
2472 -error_behavior occasion behavior
2474 Control the program behavior at problem event occasions. For
2475 now this applies to occasions "image_loading" which is given
2476 while an image tree is read from the input device, and to
2477 "file_extraction" which is given with osirrox options like
2478 -extract.
2479 With "image_loading" there are three behaviors available:
2480 "best_effort" goes on with reading after events with severity
2481 below FAILURE if the threshold of option -abort_on allows this.
2482 "failure" aborts image tree reading on first event of at least
2483 SORRY. It issues an own FAILURE event. This is the default.
2484 "fatal" acts like "failure" but issues the own event as FATAL.
2485 With occasion "file_extraction" there are three behaviors:
2486 "keep" maintains incompletely extracted files on disk. This is
2487 the default.
2488 "delete" removes files which encountered errors during content
2489 extraction.
2490 "best_effort" starts a revovery attempt by means of -extract_cut
2491 if the file content stems from the loaded ISO image and is not
2492 filtered.
2493 Dialog mode control:
2495 -dialog "on"|"off"|"single_line"
2497 Enable or disable to enter dialog mode after all arguments are
2498 processed. In dialog mode input lines get prompted via readline
2499 or from stdin.
2500 If no -abort_on severity was set when dialog starts, then
2501 "NEVER" is set to avoid abort in most cases of wrong input or
2502 other problems. Before dialog begins, the default is "FAILURE"
2503 which e.g. aborts on unknown commands.
2504 Mode "on" supports input of newline characters within quotation
2505 marks and line continuation by trailing backslash outside
2506 quotation marks. Mode "single_line" does not.
2507 -page length width
2509 Describe terminal to the text pager. See also above, paragraph
2510 Result pager.
2511 If parameter length is nonzero then the user gets prompted after
2512 that number of terminal lines. Zero length disables paging.
2513 Parameter width is the number of characters per terminal line.
2514 It is used to compute the number of terminal lines which get
2515 occupied by an output line. A usual terminal width is 80.
2516 -use_readline "on"|"off"
2518 If "on" then use readline for dialog. Else use plain stdin.
2519 See also above, paragraph Dialog, Readline, Result pager.
2520 -reassure "on"|"tree"|"off"
2522 If "on" then ask the user for "y" or "n":
2523 before deleting or overwriting any file in the ISO image,
2524 before overwriting any disk file during restore operations,
2525 before rolling back pending image changes,
2526 before committing image changes to media,
2527 before changing the input drive,
2528 before blanking or formatting media,
2529 before ending the program.
2530 With setting "tree" the reassuring prompt will appear for an
2531 eventual directory only once and not for each file in its whole
2532 subtree.
2533 Setting "off" silently kills any kind of image file object resp.
2534 performs above irrevocable actions.
2535 To really produce user prompts, option -dialog needs to be set
2536 to "on". Note that the prompt does not appear in situations
2537 where file removal is forbidden by option -overwrite. -reassure
2538 only imposes an additional curb for removing existing file
2539 objects.
2540 Be aware that file objects get deleted from the ISO image
2541 immediately after confirmation. They are gone even if the
2542 running command gets aborted and its desired effect gets
2543 revoked. In case of severe mess-up, consider to use -rollback to
2544 revoke the whole session.
2545 Drive and media related inquiry actions:
2547 -devices
2549 Show list of available MMC drives with the addresses of their
2550 libburn standard device files.
2551 This is only possible when no ISO image changes are pending.
2552 After this option was executed, there is no drive current and no
2553 image loaded.
2554 In order to be visible, a device has to offer rw-permissions
2555 with its libburn standard device file. Thus it might be only the
2556 superuser who is able to see all drives.
2557 Drives which are occupied by other processes get not shown.
2558 -device_links
2560 Like -devices, but presenting the drives with addresses of
2561 symbolic links which point to the actual device files.
2562 Modern GNU/Linux systems may shuffle drive addresses from boot
2563 to boot. The udev daemon is supposed to create links which
2564 always point to the same drive, regardless of its system
2565 address. The command -device_links shows the addresses of such
2566 links if they begin by "/dev/dvd" or "/dev/cd". Precedence is:
2567 "dvdrw", "cdrw", "dvd", "cdrom", "cd".
2568 -toc
2570 Show media specific table of content. This is the session
2571 history of the medium, not the ISO image directory tree.
2572 In case of overwriteable media holding a valid ISO image, it may
2573 happen that only a single session gets shown. But if the first
2574 session on the overwriteable media was written by xorriso then a
2575 complete session history can be emulated.
2576 A drive which is incapable of writing may show any media as
2577 CD-ROM or DVD-ROM with only one or two sessions on it. The last
2578 of these sessions is supposed to be the most recent real session
2579 then.
2580 Some read-only drives and media show no usable session history
2581 at all. Option -rom_toc_scan might help.
2582 -mount_cmd drive entity id path
2584 Emit an appropriate command line for mounting the ISO session
2585 indicated by drive, entity and id. The result will be different
2586 on GNU/Linux and on FreeBSD.
2587 drive can be "indev" or "outdev" to indicate already acquired
2588 drives, or it can be the path of a not yet acquired drive.
2589 Prefix "stdio:" for non-MMC drives is not mandatory.
2590 entity must be either "sbsector" with the superblock sector
2591 address as id, or "track" with a track number as id, or
2592 "session" with a session number, or "volid" with a search
2593 pattern for the volume id, or "auto" with any text as id.
2594 path will be used as mount point and must already exist as a
2595 directory on disk.
2596 The command gets printed to the result channel. See option
2597 -mount for direct execution of this command.
2598 -mount_opts option[:option...]
2600 Set options which influence -mount and -mount_cmd. Currently
2601 there is only option "exclusive" which is default and its
2602 counterpart "shared". The latter causes xorriso not to give up
2603 the affected drive with command -mount. On GNU/Linux it adds
2604 mount option "loop" which may allow to mount several sessions of
2605 the same block device at the same time. One should not write to
2606 a mounted optical medium, of course. Take care to umount all
2607 sessions before ejecting.
2608 -session_string drive entity id format
2610 Print to the result channel a text which gets composed according
2611 to format and the parameters of the addressed session.
2612 Formats "linux:"path or "freebsd:"path produce the output of
2613 -mount_cmd for the given operating systems.
2614 In other texts xorriso will substitute the following parameter
2615 names. An optional prefix "string:" will be removed.
2616 "%device%" will be substituted by the mountable device path of
2617 the drive address.
2618 "%sbsector%" will be substituted by the session start sector.
2619 "%track%", "%session%", "%volid%" will be substituted by track
2620 number, session number, resp. volume id of the depicted session.
2621 -print_size
2623 Print the foreseeable consumption of 2048 byte blocks by next
2624 -commit. This can last a while as a -commit gets prepared and
2625 only in last moment is revoked by this option. The result
2626 depends on several settings and also on the kind of output
2627 device. If no -jidgo options are given and not command -as
2628 "mkisofs" was used, then -padding (300 kB by default) is not
2629 counted as part of the image size.
2630 -tell_media_space
2632 Print available space on the output medium and the free space
2633 after subtracting already foreseeable consumption by next
2634 -commit.
2635 -pvd_info
2637 Print various id strings which can be found in loaded ISO
2638 images. Some of them may be changed by options like -volid or
2639 -publisher. For these ids -pvd_info reports what would be
2640 written with the next -commit.
2641 Navigation in ISO image and disk filesystem:
2643 -cd iso_rr_path
2645 Change the current working directory in the ISO image. This is
2646 prepended to iso_rr_paths which do not begin with '/'.
2647 It is possible to set the working directory to a path which does
2648 not exist yet in the ISO image. The necessary parent directories
2649 will be created when the first file object is inserted into that
2650 virtual directory. Use -mkdir if you want to enforce the
2651 existence of the directory already at first insertion.
2652 -cdx disk_path
2654 Change the current working directory in the local filesystem.
2655 To be prepended to disk_paths which do not begin with '/'.
2656 -pwd
2658 Tell the current working directory in the ISO image.
2659 -pwdx
2661 Tell the current working directory in the local filesystem.
2662 -ls iso_rr_pattern [***]
2664 List files in the ISO image which match shell patterns (i.e.
2665 with wildcards '*' '?' '[a-z]'). If a pattern does not begin
2666 with '/' then it is compared with addresses relative to -cd.
2667 Directories are listed by their content rather than as single
2668 file item.
2669 Pattern expansion may be disabled by command -iso_rr_pattern.
2670 -lsd iso_rr_pattern [***]
2672 Like -ls but listing directories as themselves and not by their
2673 content. This resembles shell command ls -d.
2674 -lsl iso_rr_pattern [***]
2676 Like -ls but also list some of the file attributes. The output
2677 format resembles shell command ls -ln.
2678 File type 'e' indicates the El Torito boot catalog.
2679 If the file has non-trivial ACL, then a '+' is appended to the
2680 permission info. If the file is hidden, then 'I' for "iso_rr",
2681 'J' for "joliet", resp. 'H' for "on" gets appended. Together
2682 with ACL it is 'i', 'j', resp. 'h'.
2683 -lsdl iso_rr_pattern [***]
2685 Like -lsd but also list some of the file attributes. The output
2686 format resembles shell command ls -dln.
2687 -lsx disk_pattern [***]
2689 List files in the local filesystem which match shell patterns.
2690 Patterns which do not begin with '/' are used relative to -cdx.
2691 Directories are listed by their content rather than as single
2692 file item.
2693 Pattern expansion may be disabled by command -disk_pattern.
2694 -lsdx disk_pattern [***]
2696 Like -lsx but listing directories as themselves and not by their
2697 content. This resembles shell command ls -d.
2698 -lslx disk_pattern [***]
2700 Like -lsx but also listing some of the file attributes. Output
2701 format resembles shell command ls -ln.
2702 -lsdlx disk_pattern [***]
2704 Like -lsdx but also listing some of the file attributes. Output
2705 format resembles shell command ls -dln.
2706 -getfacl iso_rr_pattern [***]
2708 Print the access permissions of the given files in the ISO image
2709 using the format of shell command getfacl. If a file has no ACL
2710 then it gets fabricated from the -chmod settings. A file may
2711 have a real ACL if it was introduced into the ISO image while
2712 option -acl was set to "on".
2713 -getfacl_r iso_rr_pattern [***]
2715 Like -gefacl but listing recursively the whole file trees
2716 underneath eventual directories.
2717 -getfattr iso_rr_pattern [***]
2719 Print the xattr of the given files in the ISO image. If a file
2720 has no such xattr then noting is printed for it.
2721 -getfattr_r iso_rr_pattern [***]
2723 Like -gefattr but listing recursively the whole file trees
2724 underneath eventual directories.
2725 -du iso_rr_pattern [***]
2727 Recursively list size of directories and files in the ISO image
2728 which match one of the patterns. similar to shell command du
2729 -k.
2730 -dus iso_rr_pattern [***]
2732 List size of directories and files in the ISO image which match
2733 one of the patterns. Similar to shell command du -sk.
2734 -dux disk_pattern [***]
2736 Recursively list size of directories and files in the local
2737 filesystem which match one of the patterns. Similar to shell
2738 command du -k.
2739 -dusx disk_pattern [***]
2741 List size of directories and files in the local filesystem which
2742 match one of the patterns. Similar to shell command du -sk.
2743 -findx disk_path [-name pattern] [-type t] [-exec action [params]] --
2745 Like -find but operating on local filesystem and not on the ISO
2746 image. This is subject to the settings of -follow.
2747 -findx accepts the same -type arguments as -find. Additionally
2748 it recognizes type "mountpoint" (or "m") which matches
2749 subdirectories which reside on a different device than their
2750 parent. It never matches the disk_path given as start address
2751 for -findx.
2752 -findx accepts the -exec actions as does -find. But except the
2753 following few actions it will always perform action "echo".
2754 in_iso reports the path if its counterpart exists in the ISO
2755 image. For this the disk_path of the -findx command gets
2756 replaced by the iso_rr_path given as parameter.
2757 E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd --
2758 not_in_iso reports the path if its counterpart does not exist in
2759 the ISO image. The report format is the same as with command
2760 -compare.
2761 add_missing iso_rr_path_start adds the counterpart if it does
2762 not yet exist in the ISO image and marks it for "rm_merge" as
2763 non-removable.
2764 E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd --
2765 is_full_in_iso reports if the counterpart in the ISO image
2766 contains files. To be used with -type "m" to report mount
2767 points.
2768 empty_iso_dir deletes all files from the counterpart in the ISO
2769 image. To be used with -type "m" to truncate mount points.
2770 estimate_size prints a lower and an upper estimation of the
2771 number of blocks which the found files together will occupy in
2772 the emerging ISO image. This does not account for the
2773 superblock, for the directories in the -findx path, or for image
2774 padding.
2775 list_extattr mode prints a script to the result channel, which
2776 would use FreeBSD command setextattr to set the file's xattr
2777 name-value pairs of user namespace. See -find for a description
2778 of parameter mode.
2779 E.g. -exec list_extattr e --
2780 -compare disk_path iso_rr_path
2782 Compare attributes and eventual data file content of a
2783 fileobject in the local filesystem with a file object in the ISO
2784 image. The iso_rr_path may well point to an image file object
2785 which is not yet committed, i.e. of which the data content still
2786 resides in the local filesystem. Such data content is prone to
2787 externally caused changes.
2788 If iso_rr_path is empty then disk_path is used as path in the
2789 ISO image too.
2790 Differing attributes are reported in detail, differing content
2791 is summarized. Both to the result channel. In case of no
2792 differences no result lines are emitted.
2793 -compare_r disk_path iso_rr_path
2795 Like -compare but working recursively. I.e. all file objects
2796 below both addresses get compared whether they have counterparts
2797 below the other address and whether both counterparts match.
2798 -compare_l disk_prefix iso_rr_prefix disk_path [***]
2800 Perform -compare_r with each of the disk_path arguments.
2801 iso_rr_path will be composed from disk_path by replacing
2802 disk_prefix by iso_rr_prefix.
2803 -show_stream iso_rr_path [***]
2805 Display the content stream chain of data files in the ISO image.
2806 The chain consists of the iso_rr_name and one or more streams,
2807 separated by " < " marks. A stream description consists of one
2808 or more texts, separated by ":" characters. The first text
2809 tells the stream type, the following ones, if ever, describe its
2810 individual properties. Frequently used types are:
2811 disk:'disk_path' for local filesystem objects.
2812 image:'iso_rr_path' for ISO image file objects.
2813 cout:'disk_path offset count' for -cut_out files.
2814 extf:'filter_name' for external filters.
2815 Example:
2816 '/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'
2817 -show_stream_r iso_rr_path [***]
2819 Like -show_stream but working recursively.
2820 Evaluation of readability and recovery:
2822 It is not uncommon that optical media produce read errors. The reasons
2824 may be various and get obscured by error correction which is performed
2825 by the drives and based on extra data on the media. If a drive returns
2826 data then one can quite trust that they are valid. But at some degree
2827 of read problems the correction will fail and the drive is supposed to
2828 indicate error.
2829 xorriso can scan a medium for readable data blocks, classify them
2830 according to their read speed, save them to a file, and keep track of
2831 successfuly saved blocks for further tries on the same medium.
2832 By option -md5 checksums may get recorded with data files and whole
2833 sessions. These checksums are reachable only via indev and a loaded
2834 image. They work independently of the media type and can detect
2835 transmission errors.
2836 -check_media [option [option ...]] --
2838 Try to read data blocks from the indev drive, optionally copy
2839 them to a disk file, and finally report about the encountered
2840 quality. Several options may be used to modify the default
2841 behavior.
2842 The options given with this command override the default
2843 settings which may have been changed by option
2844 -check_media_defaults. See there for a description of options.
2845 The result list tells intervals of 2 KiB blocks with start
2846 address, number of blocks and quality. Qualities which begin
2847 with "+" are supposed to be valid readable data. Qualities with
2848 "-" are unreadable or corrupted data. "0" indicates qualities
2849 which are not covered by the check run or are regularly allowed
2850 to be unreadable (e.g. gaps between tracks).
2851 Alternatively it is possible to report damaged files rather than
2852 blocks.
2853 If -md5 is "on" then the default mode what=tracks looks out for
2854 libisofs checksum tags for the ISO session data and checks them
2855 against the checksums computed from the data stream.
2856 -check_media_defaults [option [option ...]] --
2858 Preset options for runs of -check_media, -extract_cut and
2859 best_effort file extraction. Options given with -check_media
2860 will override the preset options. -extract_cut will override
2861 some options automatically.
2862 An option consists of a keyword, a "=" character, and a value.
2863 Options may override each other. So their sequence matters.
2864 The default setting at program start is:
2865 use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
2866 time_limit=28800 item_limit=100000 data_to='' event=ALL
2867 abort_file=/var/opt/xorriso/do_abort_check_media
2868 sector_map='' map_with_volid=off patch_lba0=off report=blocks
2869 bad_limit=valid slow_limit=1.0 chunk_size=0s
2870 Option "reset=now" restores these startup defaults.
2871 Non-default options are:
2872 report="files" lists the files which use damaged blocks (not
2873 with use=outdev). The format is like with find -exec
2874 report_damage. Note that a MD5 session mismatch marks all files
2875 of the session as damaged. If finer distinction is desired,
2876 perform -md5 off before -check_media.
2877 report="blocks_files" first lists damaged blocks and then
2878 affected files.
2879 use="outdev" reads from the output drive instead of the input
2880 drive. This avoids loading the ISO image tree from media.
2881 use="sector_map" does not read any media but loads the file
2882 given by option sector_map= and processes this virtual outcome.
2883 what="disc" scans the payload range of a medium without
2884 respecting track gaps.
2885 what="image" similar to "disc", but restricts scanning to the
2886 range of the ISO 9660 image, if present.
2887 min_lba=limit omits all blocks with addresses lower than limit.
2888 max_lba=limit switches to what=disc and omits all blocks above
2889 limit.
2890 retry="on" forces read retries with single blocks when the
2891 normal read chunk produces a read error. By default, retries are
2892 only enabled with CD media. "retry=off" forbits retries for all
2893 media types.
2894 abort_file=disk_path gives the path of the file which may abort
2895 a scan run. Abort happens if the file exists and its mtime is
2896 not older than the start time of the run. Use shell command
2897 "touch" to trigger this. Other than an aborted program run,
2898 this will report the tested and untested blocks and go on with
2899 running xorriso.
2900 time_limit=seconds gives the number of seconds after which the
2901 scan shall be aborted. This is useful for unattended scanning of
2902 media which may else overwork the drive in its effort to squeeze
2903 out some readable blocks. Abort may be delayed by the drive
2904 gnawing on the last single read operation. Value -1 means
2905 unlimited time.
2906 item_limit=number gives the number of report list items after
2907 which to abort. Value -1 means unlimited item number.
2908 data_to=disk_path copies the valid blocks to the given file.
2909 event=severity sets the given severity for a problem event which
2910 shall be issued at the end of a check run if data blocks were
2911 unreadable or failed to match recorded MD5 checksums. Severity
2912 "ALL" disables this event.
2913 sector_map=disk_path tries to read the file given by disk_path
2914 as sector bitmap and to store such a map file after the scan
2915 run. The bitmap tells which blocks have been read successfully
2916 in previous runs. It allows to do several scans on the same
2917 medium, even with intermediate eject, in order to collect
2918 readable blocks whenever the drive is lucky enough to produce
2919 them. The stored file contains a human readable TOC of tracks
2920 and their start block addresses, followed by binary bitmap data.
2921 map_with_volid="on" examines tracks whether they are ISO images
2922 and prints their volume ids into the human readable TOC of
2923 sector_map=.
2924 patch_lba0="on" transfers within the data_to= file a copy of the
2925 currently loaded session head to the start of that file and
2926 patches it to be valid at that position. This makes the loaded
2927 session the default session of the image file when it gets
2928 mounted or loaded as stdio: drive. But it usually makes the
2929 original session 1 inaccessible.
2930 patch_lba0="force" performs patch_lba0="on" even if xorriso
2931 believes that the copied data are not valid.
2932 patch_lba0= may also bear a number. If it is 32 or higher it is
2933 taken as start address of the session to be copied. In this case
2934 it is not necessary to have an -indev and a loaded image.
2935 ":force" may be appended after the number.
2936 bad_limit=threshold sets the highest quality which shall be
2937 considered as damage. Choose one of "good", "md5_match",
2938 "slow", "partial", "valid", "untested", "invalid", "tao_end",
2939 "off_track", "md5_mismatch", "unreadable".
2940 slow_limit=threshold sets the time threshold for a single read
2941 chunk to be considered slow. This may be a fractional number
2942 like 0.1 or 1.5.
2943 chunk_size=size sets the number of bytes to be read in one read
2944 operation. This gets rounded down to full blocks of 2048 bytes.
2945 0 means automatic size.
2946 -check_md5 severity iso_rr_path [***]
2948 Compare the data content of the given files in the loaded image
2949 with their recorded MD5 checksums, if there are any. In case of
2950 any mismatch an event of the given severity is issued. It may
2951 then be handled by appropriate settings of options -abort_on or
2952 -return_with which both can cause non-zero exit values of the
2953 program run. Severity ALL suppresses that event.
2954 This option reports match and mismatch of data files to the
2955 result channel. Non-data files cause NOTE events. There will
2956 also be UPDATE events from data reading.
2957 If no iso_rr_path is given then the whole loaded session is
2958 compared with its MD5 sum. Be aware that this covers only one
2959 session and not the whole image if there are older sessions.
2960 -check_md5_r severity iso_rr_path [***]
2962 Like -check_md5 but checking all data files underneath the given
2963 paths. Only mismatching data files will be reported.
2964 osirrox ISO-to-disk restore options:
2966 Normally xorriso only writes to disk files which were given as stdio:
2968 pseudo-drives or as log files. But its alter ego osirrox is able to
2969 extract file objects from ISO images and to create, overwrite, or
2970 delete file objects on disk.
2971 Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply. If disk
2972 file objects already exist then the settings of -overwrite and
2973 -reassure apply. But -overwrite "on" only triggers the behavior of
2974 -overwrite "nondir". I.e. directories cannot be deleted.
2975 Access permissions of files in the ISO image do not restrict restoring.
2976 The directory permissions on disk have to allow rwx.
2977 -osirrox "on"|"device_files"|"off"|"banned"|[:option:...]
2979 Setting "off" disables disk filesystem manipulations. This is
2980 the default unless the program was started with leafname
2981 "osirrox". Elsewise the capability to restore files can be
2982 enabled explicitly by -osirrox "on". It can be irrevocably
2983 disabled by -osirrox "banned".
2984 To enable restoring of special files by "device_files" is
2985 potentially dangerous. The meaning of the number st_rdev (see
2986 man 2 stat) depends much on the operating system. Best is to
2987 restore device files only to the same system from where they
2988 were copied. If not enabled, device files in the ISO image are
2989 ignored during restore operations.
2990 Due to a bug of previous versions, device files from previous
2991 sessions might have been altered to major=0, minor=1. So this
2992 combination does not get restored.
2993 Option "concat_split_on" is default. It enables restoring of
2994 split file directories as data files if the directory contains a
2995 complete collection of -cut_out part files. With option
2996 "concat_split_off" such directories are handled like any other
2997 ISO image directory.
2998 Option "auto_chmod_off" is default. If "auto_chmod_on" is set
2999 then access restrictions for disk directories get circumvented
3000 if those directories are owned by the effective user who runs
3001 xorriso. This happens by temporarily granting rwx permission to
3002 the owner.
3003 Option "sort_lba_on" may improve read performance with optical
3004 drives. It allows to restore large numbers of hard links without
3005 exhausting -temp_mem_limit. It does not preserve directory mtime
3006 and it needs -osirrox option auto_chmod_on in order to extract
3007 directories which offer no write permission. Default is
3008 "sort_lba_off".
3009 Option "o_excl_on" is the default unless the program was started
3010 with leafname "osirrox". On GNU/Linux it tries to avoid using
3011 drives which are mounted or in use by other libburn programs.
3012 Option "o_excl_off" allows on GNU/Linux to access such drives.
3013 Drives which get acquired while "o_excl_off" will refuse to get
3014 blanked, formatted, written, or ejected. But be aware that even
3015 harmless inquiries can spoil ongoing burns of CD-R[W] and
3016 DVD-R[W].
3017 Option "strict_acl_off" is default. It tolerates on FreeBSD the
3018 presence of directory "default" ACLs in the ISO image. With
3019 "strict_acl_on" these GNU/Linux ACLs cause on FreeBSD a FAILURE
3020 event during restore with -acl "on".
3021 -extract iso_rr_path disk_path
3023 Copy the file objects at and underneath iso_rr_path to their
3024 corresponding addresses at and underneath disk_path. This is
3025 the inverse of -map or -update_r.
3026 If iso_rr_path is a directory and disk_path is an existing
3027 directory then both trees will be merged. Directory attributes
3028 get extracted only if the disk directory is newly created by the
3029 copy operation. Disk files get removed only if they are to be
3030 replaced by file objects from the ISO image.
3031 As many attributes as possible are copied together with restored
3032 file objects.
3033 -extract_single iso_rr_path disk_path
3035 Like -extract, but if iso_rr_path is a directory then its sub
3036 tree gets not restored.
3037 -extract_l iso_rr_prefix disk_prefix iso_rr_path [***]
3039 Perform -extract with each of the iso_rr_path arguments.
3040 disk_path will be composed from iso_rr_path by replacing
3041 iso_rr_prefix by disk_prefix.
3042 -extract_cut iso_rr_path byte_offset byte_count disk_path
3044 Copy a byte interval from a data file out of an ISO image into a
3045 newly created disk file. The main purpose for this is to allow
3046 handling of large files if they are not supported by mount -t
3047 iso9660 and if the reading system is unable to buffer them as a
3048 whole.
3049 If the data bytes of iso_rr_path are stored in the loaded ISO
3050 image, and no filter is applied, and byte_offset is a multiple
3051 of 2048, then a special run of -check_media is performed. It may
3052 be quicker and more rugged than the general reading method.
3053 -cpx iso_rr_path [***] disk_path
3055 Copy single leaf file objects from the ISO image to the address
3056 given by disk_path. If more then one iso_rr_path is given then
3057 disk_path must be a directory or non-existent. In the latter
3058 case it gets created and the extracted files get installed in it
3059 with the same leafnames.
3060 Missing directory components in disk_path will get created, if
3061 possible.
3062 Directories are allowed as iso_rr_path only with -osirrox
3063 "concat_split_on" and only if they actually represent a complete
3064 collection of -cut_out split file parts.
3065 -cpax iso_rr_path [***] disk_path
3067 Like -cpx but restoring mtime, atime as in ISO image and trying
3068 to set ownership and group as in ISO image.
3069 -cp_rx iso_rr_path [***] disk_path
3071 Like -cpx but also extracting whole directory trees from the ISO
3072 image.
3073 The resulting disk paths are determined as with shell command cp
3074 -r : If disk_path is an existing directory then the trees will
3075 be inserted or merged underneath this directory and will keep
3076 their leaf names. The ISO directory "/" has no leaf name and
3077 thus gets mapped directly to disk_path.
3078 -cp_rax iso_rr_path [***] disk_path
3080 Like -cp_rx but restoring mtime, atime as in ISO image and
3081 trying to set ownership and group as in ISO image.
3082 -paste_in iso_rr_path disk_path byte_offset byte_count
3084 Read the content of a ISO data file and write it into a data
3085 file on disk beginning at the byte_offset. Write at most
3086 byte_count bytes. This is the inverse of option -cut_out.
3087 -mount drive entity id path
3089 Produce the same line as -mount_cmd and then execute it as
3090 external program run after giving up the depicted drive. See
3091 also -mount_opts. This demands -osirrox to be enabled and
3092 normally will succeed only for the superuser. For safety reasons
3093 the mount program is only executed if it is reachable as
3094 /bin/mount or /sbin/mount.
3095 Command compatibility emulations:
3097 Writing of ISO 9660 on CD is traditionally done by program mkisofs as
3099 ISO 9660 image producer and cdrecord as burn program. xorriso does not
3100 strive for their comprehensive emulation. Nevertheless it is ready to
3101 perform some of its core tasks under control of commands which in said
3102 programs trigger comparable actions.
3103 -as personality option [options] --
3105 Perform the variable length option list as sparse emulation of
3106 the program depicted by the personality word.
3107 Personality "mkisofs" accepts the options listed with:
3109 -as mkisofs -help --
3110 Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mode,
3111 -file-mode, -path-list, -m, -exclude-list, -f, -print-size,
3112 -pad, -no-pad, -V, -v, -version, -graft-points, -z,
3113 -no-emul-boot, -b, -c, -boot-info-table, -boot-load-size,
3114 -input-charset, -G, -output-charset, -U, -hide, -hide-joliet,
3115 -hide-list, -hide-joliet-list, file paths and pathspecs. A lot
3116 of options are not supported and lead to failure of the mkisofs
3117 emulation. Some are ignored, but better do not rely on this
3118 tolerance.
3119 The supported options are documented in detail in xorrisofs.info
3120 and in man xorrisofs. The description here is focused on the
3121 effect of mkisofs emulation in the context of a xorriso run.
3122 Other than with the "cdrecord" personality there is no automatic
3123 -commit at the end of a "mkisofs" option list. Verbosity
3124 settings -v (= "UPDATE") and -quiet (= "SORRY") persist. The
3125 output file persists until things happen like -commit,
3126 -rollback, -dev, or end of xorriso. -pacifier gets set to
3127 "mkisofs" if files are added to the image.
3128 -graft-points is equivalent to -pathspecs on. Note that
3129 pathspecs without "=" are interpreted differently than with
3130 xorriso option -add. Directories get merged with the root
3131 directory of the ISO image, other filetypes get mapped into that
3132 root directory.
3133 If pathspecs are given and if no output file was chosen before
3134 or during the "mkisofs" option list, then standard output
3135 (-outdev "-") will get into effect. If -o points to a regular
3136 file, then it will be truncated to 0 bytes when finally writing
3137 begins. This truncation does not happen if the drive is chosen
3138 by xorriso options before -as mkisofs or after its list
3139 delimiter. Directories and symbolic links are no valid -o
3140 targets.
3141 Writing to stdout is possible only if -as "mkisofs" was among
3142 the start arguments or if other start arguments pointed the
3143 output drive to standard output.
3144 -print-size inhibits automatic image production at program end.
3145 This ban is lifted only if the pending image changes get
3146 discarded.
3147 Padding is counted as part of the ISO image if not option
3148 --emul-toc is given.
3149 If no -iso-level is given, then level 1 is chosen when the first
3150 file or directory is added to the image. At the same occasion
3151 directory names get allowed to violate the standard by
3152 -compliance option allow_dir_id_ext. This may be avoided by
3153 option -disallow_dir_id_ext.
3154 Option -root is supported. Option -old-root is implemented by
3155 xorriso commands -mkdir, -cp_clone, -find update_merge, and
3156 -find rm_merge. -root and -old-root set command -disk_dev_ino
3157 to "ino_only" and -md5 to "on", by default. -disk_dev_ino can
3158 be set to "off" by --old-root-no-ino resp. to "on" by
3159 --old-root-devno . -md5 can be set to "off" by
3160 --old-root-no-md5 .
3161 Not original mkisofs options are --quoted_path_list ,
3162 --hardlinks , --acl , --xattr , --md5 , --stdio_sync . They
3163 work like the xorriso options with the same name and hardcoded
3164 argument "on", e.g. -acl "on". Explicit arguments are expected
3165 by --stdio_sync and --scdbackup_tag.
3166 The capability to preserve multi-session history on
3167 overwriteable media gets disabled by default. It can be enabled
3168 by using --emul-toc with the first session. See -compliance
3169 no_emul_toc.
3170 --sort-weight gets as arguments a number and an iso_rr_path.
3171 The number becomes the LBA sorting weight of regular file
3172 iso_rr_path or of all regular files underneath directory
3173 iso_rr_path. (See -find -exec sort_weight).
3174 Adopted from grub-mkisofs are --protective-msdos-label (see
3175 -boot_image grub partition_table=on) and
3176 --modification-date=YYYYMMDDhhmmsscc (see -volume_date uuid).
3177 For EFI bootable GRUB boot images use --efi-boot. It performs
3178 -boot_image grub efi_path= surrounded by two -boot_image "any"
3179 "next". Alternative option -e from Fedora genisoimage sets
3180 bin_path and platform_id for EFI, but performs no "next".
3181 For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE,
3182 where FILE is one of the Syslinux files mbr/isohdp[fp]x*.bin .
3183 Use this instead of -G to apply the effect of -boot_image
3184 isolinux partition_table=on.
3185 --boot-catalog-hide is -boot_image any cat_hidden=on.
3186 -mips-boot is the same as -boot_image any mips_path= .
3187 -mipsel-boot leads to mipsel_path= .
3188 -partition_offset number is -boot_image any
3189 partition_offset=number.
3190 Option -append_partition is supported.
3191 -untranslated_name_len number is -compliance
3192 untranslated_name_len=number.
3193 --old-empty is -compliance old_empty.
3194 The options of genisoimage Jigdo Template Extraction are
3195 recognized and performed via xorriso option -jigdo. See the
3196 "Alias:" names there for the meaning of the genisoimage options.
3197 Personalities "xorrisofs", "genisoimage", and "genisofs" are
3199 aliases for "mkisofs".
3200 If xorriso is started with one of the leafnames "xorrisofs",
3201 "genisofs", "mkisofs", or "genisoimage", then it performs
3202 -read_mkisofsrc and prepends -as "genisofs" to the command line
3203 arguments. I.e. all arguments will be interpreted mkisofs style
3204 until "--" is encountered. From then on, options are
3205 interpreted as xorriso options.
3206 --no_rc as first argument of such a program start prevents
3207 interpretation of startup files. See section FILES below.
3208 Personality "cdrecord" accepts the options listed with:
3210 -as cdrecord -help --
3211 Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip,
3212 padsize=, tsize=, -isosize, -multi, -msinfo,
3213 --grow_overwriteable_iso, write_start_address=, track source
3214 file path or "-" for standard input as track source.
3215 It ignores most other options of cdrecord and cdrskin but
3216 refuses on -audio, -scanbus, and on blanking modes unknown to
3217 xorriso.
3218 The scope is only a single data track per session to be written
3219 to blank, overwriteable, or appendable media. The medium gets
3220 closed if closing is applicable and not option -multi is
3221 present.
3222 If an input drive was aquired, then it is given up. This is
3223 only allowed if no image changes are pending.
3224 dev= must be given as xorriso device address. Addresses like
3225 0,0,0 or ATA:1,1,0 are not supported.
3226 If a track source is given, then an automatic -commit happens at
3227 the end of the "cdrecord" option list.
3228 --grow_overwriteable_iso enables emulation of multi-session on
3229 overwriteable media. To enable emulation of a TOC, the first
3230 session needs -C 0,32 with -as mkisofs (but no -M) and
3231 --grow_overwriteable_iso write_start_address=32s with -as
3232 cdrecord.
3233 A much more elaborate libburn based cdrecord emulator is the
3234 program cdrskin.
3235 Personalites "xorrecord", "wodim", and "cdrskin" are aliases for
3236 "cdrecord".
3237 If xorriso is started with one of the leafnames "xorrecord",
3238 "cdrskin", "cdrecord", or "wodim", then it automatically
3239 prepends -as "cdrskin" to the command line arguments. I.e. all
3240 arguments will be interpreted cdrecord style until "--" is
3241 encountered. From then on, options are interpreted as xorriso
3242 options.
3243 --no_rc as first argument of such a program start prevents
3244 interpretation of xorriso startup files. See section FILES
3245 below.
3246 -read_mkisofsrc
3248 Try one by one to open for reading:
3249 ./.mkisofsrc , $MKISOFSRC , $HOME/.mkisofsrc , $(dirname
3250 $0)/.mkisofsrc
3251 On success interpret the file content as of man mkisofs
3252 CONFIGURATION, and end this command. Do not try further files.
3253 The last address is used only if start argument 0 has a
3254 non-trivial dirname.
3255 The reader currently interprets the following NAME=VALUE pairs:
3256 APPI (-application_id) , PUBL (-publisher) , SYSI (-system_id) ,
3257 VOLI (-volid) , VOLS (-volset_id)
3258 Any other lines will be silently ignored.
3259 -pacifier behavior_code
3261 Control behavior of UPDATE pacifiers during write operations.
3262 The following behavior codes are defined:
3263 "xorriso" is the default format:
3264 Writing: sector XXXXX of YYYYYY [fifo active, nn% fill]
3265 "cdrecord" looks like:
3266 X of Y MB written (fifo nn%) [buf mmm%]
3267 "mkisofs"
3268 nn% done, estimate finish Tue Jul 15 20:13:28 2008
3269 -scdbackup_tag list_path record_name
3271 Set the parameter "name" for a scdbackup checksum record. It
3272 will be appended in an scdbackup checksum tag to the -md5
3273 session tag if the image starts at LBA 0. This is the case if it
3274 gets written as first session onto a sequential medium, or piped
3275 into a program, named pipe or character device.
3276 If list_path is not empty then the record will also be appended
3277 to the data file given by this path.
3278 Program scdbackup_verify will recognize and verify tag resp.
3279 record.
3280 Scripting, dialog and program control features:
3282 -no_rc
3284 Only if used as first command line argument this option prevents
3285 reading and interpretation of startup files. See section FILES
3286 below.
3287 -options_from_file fileaddress
3289 Read quoted input from fileaddress and execute it like dialog
3290 lines. Empty lines and lines which begin by # are ignored.
3291 Normally one line should hold one xorriso command and all its
3292 arguments. Nevertheless lines may be concatenated by a trailing
3293 backslash.
3294 See also section "Command processing", paragraph "Quoted input".
3295 -help
3297 Print helptext.
3298 -version
3300 Print program name and version, component versions, license.
3301 -list_extras code
3303 Tell whether certain extra features were enabled at compile
3304 time. Code "all" lists all features and a headline. Other
3305 codes pick a single feature. Code "codes" lists them. They
3306 share names with related commands (see also there):
3307 "acl" tells whether xorriso has an adapter for local filesystems
3308 ACLs.
3309 "xattr" tells whether xorriso has an adapter for local
3310 filesystems EA.
3311 "jigdo" tells whether production of Jigdo files is possible.
3312 "zisofs" tells whether zisofs and built-in gzip filters are
3313 enabled.
3314 "external_filter" tells whether external filter processes are
3315 allowed and whether they are allowed if real user id and
3316 effective user id differ.
3317 "dvd_obs" tells whether 64 kB output to DVD media is default.
3318 "use_readline" tells whether readline may be enabled in dialog
3319 mode.
3320 -history textline
3322 Copy textline into libreadline history.
3323 -status mode|filter
3325 Print the current settings of xorriso. Modes:
3326 short... print only important or altered settings
3327 long ... print all settings including defaults
3328 long_history like long plus history lines
3329 Filters begin with '-' and are compared literally against the
3330 output lines of -status:long_history. A line is put out only if
3331 its start matches the filter text. No wildcards.
3332 -status_history_max number
3334 Set maximum number of history lines to be reported with -status
3335 "long_history".
3336 -list_delimiter word
3338 Set the list delimiter to be used instead of "--". It has to be
3339 a single word, must not be empty, not longer than 80 characters,
3340 and must not contain quotation marks.
3341 For brevity the list delimiter is referred as "--" throughout
3342 this text.
3343 -backslash_codes "on"|"off"|mode[:mode]
3345 Enable or disable the interpretation of symbolic representations
3346 of special characters with quoted input, or with program
3347 arguments, or with program text output. If enabled the following
3348 translations apply:
3349 \a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014)
3350 \n=linefeed(012) \r=carriage_return(015) \t=tab(011)
3351 \v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code
3352 \x[0-9a-f][0-9a-f]=hex_code \cC=control-C
3353 Translations can occur with quoted input in 3 modes:
3354 "in_double_quotes" translates only inside " quotation.
3355 "in_quotes" translates inside " and ' quotation.
3356 "with_quoted_input" translates inside and outside quotes.
3357 With the start program arguments there is mode:
3358 "with_program_arguments" translates all program arguments.
3359 Mode "encode_output" encodes output characters. It combines
3360 "encode_results" with "encode_infos". Inside single or double
3361 quotation marks encoding applies to ASCII characters octal 001
3362 to 037 , 177 to 377 and to backslash(134). Outside quotation
3363 marks some harmless control characters stay unencoded:
3364 bell(007), backspace(010), tab(011), linefeed(012),
3365 formfeed(014), carriage_return(015).
3366 Mode "off" is default and disables any translation. Mode "on"
3367 is "with_quoted_input:with_program_arguments:encode_output".
3368 -temp_mem_limit number["k"|"m"]
3370 Set the maximum size of temporary memory to be used for image
3371 dependent buffering. Currently this applies to pattern
3372 expansion, LBA sorting, restoring of hard links.
3373 Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1
3374 GiB.
3375 -print text
3377 Print a text line to the result channel which is by default
3378 stdout.
3379 -print_info text
3381 Print a text line to the info channel which is by default
3382 stderr.
3383 -print_mark text
3385 Print a text line to the mark channel which is by default
3386 directed to both, result and info channel. An empty text will
3387 cause no output at all.
3388 -prompt text
3390 Show text at beginning of output line and wait for the user to
3391 hit the Enter key resp. to send a line via stdin.
3392 -sleep seconds
3394 Wait for the given number of seconds before perfoming the next
3395 command. Expect coarse granularity no better than 1/100
3396 seconds.
3397 -errfile_log mode path|channel
3399 If problem events are related to input files from the
3400 filesystem, then their disk_paths can be logged to a file or to
3401 output channels R or I.
3402 Mode can either be "plain" or "marked". The latter causes marker
3403 lines which give the time of log start, burn session start, burn
3404 session end, log end or program end. In mode "plain", only the
3405 file paths are logged.
3406 If path is "-" or "-R" then the log is directed to the result
3407 channel. Path "-I" directs it to the info message channel. Any
3408 text that does not begin with "-" is used as path for a file to
3409 append the log lines.
3410 Problematic files can be recorded multiple times during one
3411 program run. If the program run aborts then the list might not
3412 be complete because some input file arguments might not have
3413 been processed at all.
3414 The errfile paths are transported as messages of very low
3415 severity "ERRFILE". This transport becomes visible with
3416 -report_about "ALL".
3417 -session_log path
3419 If path is not empty it gives the address of a plain text file
3420 where a log record gets appended after each session. This log
3421 can be used to determine the start_lba of a session for mount
3422 options -o sbsector= resp. -s from date or volume id.
3423 Record format is: timestamp start_lba size volume-id
3424 The first three items are single words, the rest of the line is
3425 the volume id.
3426 -scsi_log "on"|"off"
3428 Mode "on" enables very verbous logging of SCSI commands and
3429 drive replies. Logging messages get printed to stderr, not to
3430 any of the xorriso output channels.
3431 A special property of this option is that the first -scsi_log
3432 setting among the start arguments is in effect already when the
3433 first operations of xorriso begin. Only "-scsi_log" with dash
3434 "-" is recognized that way.
3435 -end
3437 End program after writing pending changes.
3438 -rollback_end
3440 Discard pending changes. End program immediately.
3441 # any text
3443 Only in dialog or file execution mode, and only as first
3444 non-whitespace in line: Do not execute the line but store it in
3445 readline history.
3446 Support for frontend programs via stdin and stdout:
3448 -pkt_output "on"|"off"
3450 Consolidate text output on stdout and classify each line by a
3451 channel indicator:
3452 'R:' for result lines,
3453 'I:' for notes and error messages,
3454 'M:' for -mark texts.
3455 Next is a decimal number of which only bit 0 has a meaning for
3456 now. 0 means no newline at end of payload, 1 means that the
3457 newline character at the end of the output line belongs to the
3458 payload. After another colon and a blank follows the payload
3459 text.
3460 Example:
3461 I:1: enter option and arguments :
3462 -logfile channel fileaddress
3464 Copy output of a channel to the given file. Channel may be one
3465 of: "." for all channels, "I" for info messages, "R" for result
3466 lines, "M" for -mark texts.
3467 -mark text
3469 If text is not empty it will get put out on "M" channel each
3470 time xorriso is ready for the next dialog line or before xorriso
3471 performs a command that was entered to the pager prompt.
3472 -prog text
3474 Use text as name of this program in subsequent messages
3475 -prog_help text
3477 Use text as name of this program and perform -help.
3478
3480 Overview of examples:
3481 As superuser learn about available drives
3482 Blank medium and compose a new ISO image as batch run
3483 A dialog session doing about the same
3484 Manipulate an existing ISO image on the same medium
3485 Copy modified ISO image from one medium to another
3486 Bring a prepared ISOLINUX tree onto medium and make it bootable
3487 Change existing file name tree from ISO-8859-1 to UTF-8
3488 Operate on storage facilities other than optical drives
3489 Burn an existing ISO image file to medium
3490 Perform multi-session runs as of cdrtools traditions
3491 Let xorriso work underneath growisofs
3492 Adjust thresholds for verbosity, exit value and program abort
3493 Examples of input timestrings
3494 Incremental backup of a few directory trees
3495 Restore directory trees from a particular ISO session to disk
3496 Try to retrieve blocks from a damaged medium
3497 As superuser learn about available drives
3499 On Linux or FreeBSD consider to give rw-permissions to those users or
3500 groups which shall be able to use the drives with xorriso. On Solaris
3501 use pfexec. Consider to restrict privileges of xorriso to
3502 "base,sys_devices" and to give r-permission to user or group.
3503 $ xorriso -device_links
3504 1 -dev '/dev/cdrom1' rwrw-- : 'TSSTcorp' 'DVD-ROM SH-D162C
3505 1 -dev '/dev/cdrw' rwrw-- : 'TSSTcorp' 'CDDVDW SH-S223B'
3506 2 -dev '/dev/cdrw3' rwrw-- : 'HL-DT-ST' 'BDDVDRW_GGC-H20L'
3507 Blank medium and compose a new ISO image as batch run
3509 Aquire drive /dev/sr2, make medium ready for writing a new image, fill
3510 the image with the files from hard disk directories /home/me/sounds and
3511 /home/me/pictures.
3512 Because no -dialog "on" is given, the program will then end by writing
3513 the session to the medium.
3514 $ xorriso -outdev /dev/sr2 \
3515 -blank as_needed \
3516 -map /home/me/sounds /sounds \
3517 -map /home/me/pictures /pictures
3518 The ISO image may be shaped in a more elaborate way like the following:
3520 Omit some unwanted stuff by removing it from the image directory tree.
3521 Reintroduce some wanted stuff.
3522 $ cd /home/me
3523 $ xorriso -outdev /dev/sr2 \
3524 -blank as_needed \
3525 -map /home/me/sounds /sounds \
3526 -map /home/me/pictures /pictures \
3527 -rm_r \
3528 /sounds/indecent \
3529 '/pictures/*private*' \
3530 /pictures/confidential \
3531 -- \
3532 -cd / \
3533 -add pictures/confidential/work* --
3534 Note that '/pictures/*private*' is a pattern for iso_rr_paths while
3535 pictures/confidential/work* gets expanded by the shell with addresses
3536 from the hard disk. Options -add and -map have different argument rules
3537 but finally the same effect: they put files into the image.
3538 A dialog session doing about the same
3540 Some settings are already given as start argument. The other activities
3541 are done as dialog input. The pager gets set to 20 lines of 80
3542 characters.
3543 The drive is acquired by option -dev rather than -outdev in order to
3544 see the message about its current content. By option -blank this
3545 content is made ready for being overwritten and the loaded ISO image is
3546 made empty.
3547 In order to be able to eject the medium, the session needs to be
3548 committed explicitly.
3549 $ xorriso -dialog on -page 20 80 -disk_pattern on
3550 enter option and arguments :
3551 -dev /dev/sr2
3552 enter option and arguments :
3553 -blank as_needed
3554 enter option and arguments :
3555 -map /home/me/sounds /sounds -map /home/me/pictures /pictures
3556 enter option and arguments :
3557 -rm_r /sounds/indecent /pictures/*private* /pictures/confidential
3558 enter option and arguments :
3559 -cdx /home/me/pictures -cd /pictures
3560 enter option and arguments :
3561 -add confidential/office confidential/factory
3562 enter option and arguments :
3563 -du /
3564 enter option and arguments :
3565 -commit_eject all -end
3566 Manipulate an existing ISO image on the same medium
3568 Load image from drive. Remove (i.e. hide) directory /sounds and its
3569 subordinates. Rename directory /pictures/confidential to
3570 /pictures/restricted. Change access permissions of directory
3571 /pictures/restricted. Add new directory trees /sounds and /movies.
3572 Burn to the same medium, check whether the tree can be loaded, and
3573 eject.
3574 $ xorriso -dev /dev/sr2 \
3575 -rm_r /sounds -- \
3576 -mv \
3577 /pictures/confidential \
3578 /pictures/restricted \
3579 -- \
3580 -chmod go-rwx /pictures/restricted -- \
3581 -map /home/me/prepared_for_dvd/sounds_dummy /sounds \
3582 -map /home/me/prepared_for_dvd/movies /movies \
3583 -commit -eject all
3584 Copy modified ISO image from one medium to another
3586 Load image from input drive. Do the same manipulations as in the
3587 previous example. Aquire output drive and blank it. Burn the modified
3588 image as first and only session to the output drive.
3589 $ xorriso -indev /dev/sr2 \
3590 -rm_r /sounds -- \
3591 ...
3592 -outdev /dev/sr0 -blank as_needed \
3593 -commit -eject all
3594 Bring a prepared ISOLINUX tree onto medium and make it bootable
3596 The user has already created a suitable file tree on disk and copied
3597 the ISOLINUX files into subdirectory ./boot/isolinux of that tree. Now
3598 xorriso can burn an El Torito bootable medium:
3599 $ xorriso -outdev /dev/sr0 -blank as_needed \
3600 -map /home/me/ISOLINUX_prepared_tree / \
3601 -boot_image isolinux dir=/boot/isolinux
3602 Change existing file name tree from ISO-8859-1 to UTF-8
3604 This example assumes that the existing ISO image was written with
3605 character set ISO-8859-1 but that the readers expected UTF-8. Now a new
3606 session with the same files gets added with converted file names. In
3607 order to avoid any weaknesses of the local character set, this command
3608 pretends that it uses already the final target set UTF-8. Therefore
3609 strange file names may appear in messages, which will be made
3610 terminal-safe by option -backslash_codes.
3611 $ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
3612 -out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
3613 -alter_date m +0 / -- -commit -eject all
3614 Operate on storage facilities other than optical drives
3616 Full read-write operation is possible with regular files and block
3617 devices:
3618 $ xorriso -dev /tmp/regular_file ...
3619 Paths underneath /dev normally need prefix "stdio:"
3620 $ xorriso -dev stdio:/dev/sdb ...
3621 If /dev/sdb is to be used frequently and /dev/sda is the system disk,
3622 then consider to place the following lines in a xorriso Startup File.
3623 They allow to use /dev/sdb without prefix and protect disk /dev/sda
3624 from xorriso:
3625 -drive_class banned /dev/sda*
3626 -drive_class harmless /dev/sdb
3627 Other writeable file types are supported write-only:
3628 $ xorriso -outdev /tmp/named_pipe ...
3629 Among the write-only drives is standard output:
3630 $ xorriso -outdev - \
3631 ...
3632 | gzip >image.iso.gz
3633 Burn an existing ISO image file to medium
3635 Actually this works with any kind of data, not only ISO images:
3636 $ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso
3637 Perform multi-session runs as of cdrtools traditions
3639 Between both processes there can be performed arbitrary transportation
3640 or filtering.
3641 The first session is written like this:
3642 $ xorriso -as mkisofs prepared_for_iso/tree1 | \
3643 xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
3644 Follow-up sessions are written like this:
3645 $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
3646 $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
3647 $ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \
3648 xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
3649 Always eject the drive tray between sessions. The old sessions get read
3650 via /dev/sr0. Its device driver might not be aware of the changed
3651 content before it loads the medium again. In this case the previous
3652 session would not be loaded and the new session would contain only the
3653 newly added files.
3654 For the same reason do not let xorriso -as cdrecord load the medium,
3655 but rather do this manually or by a program that reads from /dev/sr0.
3656 This example works for multi-session media only. Add cdrskin option
3657 --grow_overwriteable_iso to all -as cdrecord runs in order to enable
3658 multi-session emulation on overwriteable media.
3659 Let xorriso work underneath growisofs
3661 growisofs expects an ISO formatter program which understands options -C
3662 and -M. If xorriso gets started by name "xorrisofs" then it is suitable
3663 for that.
3664 $ export MKISOFS="xorrisofs"
3665 $ growisofs -Z /dev/dvd /some/files
3666 $ growisofs -M /dev/dvd /more/files
3667 If no "xorrisofs" is available on your system, then you will have to
3668 create a link pointing to the xorriso binary and tell growisofs to use
3669 it. E.g. by:
3670 $ ln -s $(which xorriso) "$HOME/xorrisofs"
3671 $ export MKISOFS="$HOME/xorrisofs"
3672 One may quit mkisofs emulation by argument "--" and make use of all
3673 xorriso commands. growisofs dislikes options which start with "-o" but
3674 -outdev must be set to "-". So use "outdev" instead:
3675 $ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files
3676 $ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files
3677 growisofs has excellent burn capabilities with DVD and BD. It does not
3678 emulate session history on overwriteable media, though.
3679 Adjust thresholds for verbosity, exit value and program abort
3681 Be quite verbous, exit 32 if severity "FAILURE" was encountered, do not
3682 abort prematurely but forcibly go on until the end of commands.
3683 $ xorriso ... \
3684 -report_about UPDATE \
3685 -return_with FAILURE 32 \
3686 -abort_on NEVER \
3687 ...
3688 Examples of input timestrings
3690 As printed by program date: 'Thu Nov 8 14:51:13 CET 2007'
3691 The same without ignored parts: 'Nov 8 14:51:13 2007'
3692 The same as expected by date: 110814512007.13
3693 Four weeks in the future: +4w
3694 The current time: +0
3695 Three hours ago: -3h
3696 Seconds since Jan 1 1970: =1194531416
3697 Incremental backup of a few directory trees
3699 This changes the directory trees /open_source_project and
3700 /personal_mail in the ISO image so that they become exact copies of
3701 their disk counterparts. ISO file objects get created, deleted or get
3702 their attributes adjusted accordingly.
3703 ACL, xattr, hard links and MD5 checksums will be recorded. Accelerated
3704 comparison is enabled at the expense of potentially larger backup size.
3705 Only media with the expected volume id or blank media are accepted.
3706 Files with names matching *.o or *.swp get excluded explicitly.
3707 When done with writing the new session gets checked by its recorded
3708 MD5.
3709 $ xorriso \
3710 -abort_on FATAL \
3711 -for_backup -disk_dev_ino on \
3712 -assert_volid 'PROJECTS_MAIL_*' FATAL \
3713 -dev /dev/sr0 \
3714 -volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
3715 -not_leaf '*.o' -not_leaf '*.swp' \
3716 -update_r /home/thomas/projects /projects \
3717 -update_r /home/thomas/personal_mail /personal_mail \
3718 -commit -toc -check_md5 FAILURE -- -eject all
3719 To be used several times on the same medium, whenever an update of the
3720 two disk trees to the medium is desired. Begin with a blank medium and
3721 update it until he run fails gracefully due to lack of remaining space
3722 on the old one.
3723 This makes sense if the full backup leaves substantial remaining
3724 capacity on media and if the expected changes are much smaller than the
3725 full backup. To apply zisofs compression to those data files which get
3726 newly copied from the local filesystem, insert these options
3727 immediately before -commit :
3728 -hardlinks perform_update \
3729 -find / -type f -pending_data -exec set_filter --zisofs -- \
3730 Options -disk_dev_ino and -for_backup depend on stable device and inode
3731 numbers on disk. Without them, an update run may use -md5 "on" to match
3732 recorded MD5 sums against the current file content on hard disk. This
3733 is usually much faster than the default which compares both contents
3734 directly.
3735 With mount option -o "sbsector=" on GNU/Linux resp. -s on FreeBSD it is
3736 possible to access the session trees which represent the older backup
3737 versions. With CD media, GNU/Linux mount accepts session numbers
3738 directly by its option "session=".
3739 Multi-session media and most overwriteable media written by xorriso can
3740 tell the sbsectors of their sessions by xorriso option -toc. Used
3741 after -commit the following option prints the matching mount command
3742 for the newly written session (here for mount point /mnt):
3743 -mount_cmd "indev" "auto" "auto" /mnt
3744 Options -mount_cmd and -mount are also able to produce the mount
3745 commands for older sessions in the table-of-content. E.g. as superuser:
3746 # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
3747 Above example produces a result similar to -root / -old-root / with
3749 mkisofs. For getting the session trees accumulated in the new
3750 sessions, let all -update commands use a common parent directory and
3751 clone it after updating is done:
3752 -update_r /home/thomas/projects /current/projects \
3753 -update_r /home/thomas/personal_mail /current/personal_mail \
3754 -clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \
3755 The cloned tree will have a name like /2011_02_12_155700.
3756 Sessions on multi-session media are separated by several MB of unused
3758 blocks. So with small sessions the payload capacity can become
3759 substantially lower than the overall media capacity. If the remaining
3760 space on a medium does not suffice for the next gap, the drive is
3761 supposed to close the medium automatically.
3762 Better do not use your youngest backup for -update_r. Have at least
3764 two media which you use alternatingly. So only older backups get
3765 endangered by the new write operation, while the newest backup is
3766 stored safely on a different medium.
3767 Always have a blank medium ready to perform a full backup in case the
3768 update attempt fails due to insufficient remaining capacity. This
3769 failure will not spoil the old medium, of course.
3770 Restore directory trees from a particular ISO session to disk
3772 This is an alternative to mounting the medium and using normal file
3773 operations.
3774 First check which backup sessions are on the medium:
3775 $ xorriso -outdev /dev/sr0 -toc
3776 Then load the desired session and copy the file trees to disk. Enable
3777 restoring of ACL, xattr and hard links. Avoid to create
3778 /home/thomas/restored without rwx-permission.
3779 $ xorriso -for_backup \
3780 -load volid 'PROJECTS_MAIL_2008_06_19*' \
3781 -indev /dev/sr0 \
3782 -osirrox on:auto_chmod_on \
3783 -chmod u+rwx / -- \
3784 -extract /open_source_projects \
3785 /home/thomas/restored/open_source_projects \
3786 -extract /personal_mail /home/thomas/restored/personal_mail \
3787 -rollback_end
3788 The final command -rollback_end prevents an error message about the
3789 altered image being discarded.
3790 Try to retrieve blocks from a damaged medium
3792 $ xorriso -abort_on NEVER -indev /dev/sr0 \
3793 -check_media time_limit=1800 report=blocks_files \
3794 data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --
3795 This can be repeated several times, if necessary with -eject or with
3796 other -indev drives. See the human readable part of
3797 "$HOME"/dvd_copy.map for addresses which can be used on
3798 "$HOME"/dvd_copy with mount option -o sbsector= resp. -s.
3799
3801 Program alias names:
3802 Normal installation of xorriso creates three links or copies which by
3803 their program name pre-select certain settings:
3804 xorrisofs starts xorriso with -as mkisofs emulation.
3805 xorrecord starts xorriso with -as cdrecord emulation.
3806 osirrox starts with -osirrox "on:o_excl_off" which allows to copy files
3807 from ISO image to disk and to apply option -mount to one or more of the
3808 existing ISO sessions.
3809 Startup files:
3811 If not -no_rc is given as the first argument then xorriso attempts on
3812 startup to read and execute lines from the following files:
3813 /etc/default/xorriso
3814 /etc/opt/xorriso/rc
3815 /etc/xorriso/xorriso.conf
3816 $HOME/.xorrisorc
3817 The files are read in the sequence given above, but none of them is
3818 required to exist. The line format is described with command
3819 -options_from_file.
3820 If mkisofs emulation was enabled by program name "xorrisofs",
3821 "mkisofs", "genisoimage", or "genisofs", then afterwards
3822 -read_mkisofsrc is performed, which reads .mkisofsrc files. See there.
3823 Runtime control files:
3825 The default setting of -check_media abort_file= is:
3826 /var/opt/xorriso/do_abort_check_media
3827
3829 For the mkisofs emulation of xorriso
3830 xorrisofs(1)
3831 For the cdrecord emulation of xorriso
3833 xorrecord(1)
3834 For mounting xorriso generated ISO 9660 images (-t iso9660)
3836 mount(8)
3837 Libreadline, a comfortable input line facility
3839 readline(3)
3840 Other programs which produce ISO 9660 images
3842 mkisofs(8), genisoimage(8)
3843 Other programs which burn sessions to optical media
3845 growisofs(1), cdrecord(1), wodim(1), cdrskin(1)
3846 ACL and xattr
3848 getfacl(1), setfacl(1), getfattr(1), setfattr(1)
3849 MD5 checksums
3851 md5sum(1)
3852 On FreeBSD the commands for xattr and MD5 differ
3854 getextattr(8), setextattr(8), md5(1)
3855
3857 To report bugs, request help, or suggest enhancements for xorriso,
3858 please send electronic mail to the public list <bug-xorriso@gnu.org>.
3859 If more privacy is desired, mail to <scdbackup@gmx.net>.
3860 Please describe what you expect xorriso to do, the program arguments
3861 resp. commands by which you tried to achieve it, the messages of
3862 xorriso, and the undesirable outcome of your program run.
3863 Expect to get asked more questions before solutions can be proposed.
3864
3866 Thomas Schmitt <scdbackup@gmx.net>
3867 for libburnia-project.org
3868
3870 Copyright (c) 2007 - 2011 Thomas Schmitt
3871 Permission is granted to distribute this text freely. It shall only be
3872 modified in sync with the technical properties of xorriso. If you make
3873 use of the license to derive modified versions of xorriso then you are
3874 entitled to modify this text under that same license.
3875
3877 xorriso is in part based on work by Vreixo Formoso who provides
3878 libisofs together with Mario Danic who also leads the libburnia team.
3879 Thanks to Andy Polyakov who invented emulated growing, to Derek Foreman
3880 and Ben Jansens who once founded libburn.
3881 Compliments towards Joerg Schilling whose cdrtools served me for ten
3882 years.
3883 Version 1.1.8, Nov 20, 2011 XORRISO(1)