.\" Hey, EMACS: -*- nroff -*- .\" First parameter, NAME, should be all caps .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" other parameters are allowed: see man(7), man(1) .TH XORRISO 1 "December 21, 2007" .\" Please adjust this date whenever revising the manpage. .\" .\" Some roff macros, for reference: .\" .nh disable hyphenation .\" .hy enable hyphenation .\" .ad l left justify .\" .ad b justify to both left and right margins .\" .nf disable filling .\" .fi enable filling .\" .br insert line break .\" .sp insert n+1 empty lines .\" for manpage-specific macros, see man(7) .SH NAME xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions. .SH SYNOPSIS .B xorriso .RI [ settings | actions ] .br .SH DESCRIPTION .PP .B xorriso is a program which maps file objects from POSIX compliant filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows session-wise manipulation of such filesystems. It can load the management information of existing ISO images and it writes the session results to optical media or to filesystem objects. .PP A special property of xorriso is that it needs neither an external ISO 9660 formatter program nor an external burn program for CD or DVD but rather incorporates the libraries of libburnia-project.org . .SS .B Overview of features: .br Operates on an existing ISO image or creates a new one. .br Copies files from filesystem into the ISO image. .br Renames or deletes file objects in the ISO image. .br Changes file properties in the ISO image. .br Can write result as completely new image to optical media or filesystem objects. .br Can write result as add-on session to appendable multi-session media, to overwriteable media, to regular files, and to block devices. .br Scans for optical drives, blanks re-useable optical media. .br Reads its instructions from command line arguments, dialog, and batch files. .br Provides navigation commands for interactive ISO image manipulation. .SS .B General information paragraphs: .br Session model .br Media types and states .br Creating, Growing, Modifying .br Libburn drives .br Rock Ridge, POSIX, X/Open .br Command processing .br Dialog, Readline, Result pager .sp 1 Maybe you first want to have a look at section EXAMPLES near the end of this text before reading the next few hundred lines of background information. .SS .B Session model: .br Unlike other filesystems, ISO 9660 is not intended for read-write operation but rather for being generated in a single sweep and being written to media as a .B session. .br The data content of the session is called filesystem .B image. .PP The written image in its session can then be mounted by the operating system for being used read-only. Linux is able to mount ISO images from block devices, which may represent optical media, other media or via a loop device even from regular disk files. .PP This session usage model has been extended on CD media by the concept of .B multi-session , which allows to add information to the CD and gives the mount programs of the operating systems the addresses of the entry points of each session. The mount programs recognize block devices which represent CD media and will by default mount the image in the last session. .br This session usually contains an updated directory tree for the whole media which governs the data contents in all recorded sessions. So in the view of the mount program all sessions of a particular media together form a single filesystem image. .br Adding a session to an existing ISO image is in this text referred as \fBgrowing\fR. .br The multi-session model of the MMC standard does not apply to all media types. But program growisofs by Andy Polyakov showed how to extend this functionality to overwriteable media or disk files which carry valid ISO 9660 filesystems. This expansion method is referred as as emulated growing. .PP xorriso provides both ways of growing as well as an own method named \fBmodifying\fR which produces a completely new ISO image from the old one and the modifications. See paragraph Creating, Growing, Modifying below. .PP xorriso adopts the concept of multi-session by loading an eventual image directory tree, allowing to manipulate it by several actions, and to write the new image to the target media. .br The first session of a xorriso run begins by the definition of the input drive with the eventual ISO image or by the definition of an output drive. The session ends by command -commit which triggers writing. A -commit is done automatically when the program ends regularly. .PP After -commit a new session begins with the freshly written one as input. A new input drive can only be chosen as long as the loaded ISO image was not altered. Pending alteration can be revoked by command -rollback. .PP Writing a session to the target is supposed to be very expensive in terms of time and of consumed space on appendable or write-once media. Therefore all intended manipulations of a particular ISO image should be done in a single session. .br In some special situations (e.g. in a file-to-file situation) it can be useful to store intermediate states and to continue with image manipulations. .SS .B Media types and states: There are two families of media in the MMC standard: .br \fBMulti-session\fR media are CD-R, CD-RW, DVD-R, DVD+R, and unformatted DVD-RW. These media provide a table of content which describes their existing sessions. .br \fBOverwriteable\fR media are DVD-RAM, DVD+RW, and formatted DVD-RW. They allow random write access but do not provide information about their session history. .br DVD-RW media can be formatted by -format full. They can be made unformatted by -blank deformat. .br Emulated drives are handled as overwriteable media if they are random read-write accessible. If they are only sequentially writeable then they are handled as blank multi-session media. .PP These media can assume several states in which they offer different capabilities. .br \fBBlank\fR media can be written from scratch. They contain no ISO image suitable for xorriso. .br Blank is the state of newly purchased optical media. With used CD-RW and DVD-RW it can be achieved by action -blank fast. Overwriteable media are considered blank unless they contain an ISO image suitable for xorriso. .br \fBAppendable\fR media accept further sessions. Either they are MMC multi-session media in appendable state, or they are overwriteable media which contain an ISO image suitable for xorriso. .br Appendable is the state after writing a session with option -close off. .br \fBClosed\fR media cannot be written. They may contain an ISO image suitable for xorriso. .br Closed is the state of DVD-ROM media and of multi-session media which were written with option -close on. If the drive is incapable of writing it will probably show any media as closed CD-ROM resp. DVD-ROM. .br Overwriteable media assume this state only in such read-only drives. .SS .B Creating, Growing, Modifying: .br A new empty ISO image gets \fBcreated\fR if there is no input drive with a valid ISO 9660 image plus Rock Ridge extensions when the first time an output drive is defined. This is achieved by option -dev on blank media or by option -outdev on media in any state. .br The new empty image can be populated with directories and files. Before it can be written, the media in the output drive must get into blank state if it was not blank already. .PP If there is a input drive with a valid ISO image, then this image gets loaded as foundation for manipulations and extension. The constellation of input and output drive determines which of two write methods will be used. They have quite different capabilities and constraints. .PP The method of \fBgrowing\fR adds new data to the existing media. These data comprise of eventual new file content and they override the existing ISO 9660 + Rock Ridge directory tree. It is possible to hide files from previous sessions but they still exist on media and with many types of optical media it is quite easy to recover them by mounting older sessions. .br Growing is achieved by option -dev. .PP The write method of \fBmodifying\fR produces compact filesystem images with no outdated files or directory trees. Modifying can write its images to target media which are completely unsuitable for multi-session operations. E.g. fast blanked DVD-RW, named pipes, character devices, sockets. On the other hand modified sessions cannot be written to appendable media but to blank media only. .br Modifying takes place whenever input drive and output drive are not the same. This is achieved by options -indev and -outdev. .br So for this method one needs either two optical drives or has to work with filesystem objects as source and/or target media. .SS .B Libburn drives: .br Input drive, i.e. source of an existing or empty ISO image, can be any random access readable libburn drive: optical media with readable data, blank optical media, regular files, block devices. .br Rock Ridge info must be present in existing ISO images and it will be generated by the program unconditionally. .PP Output drive, i.e. target for writing, can be any libburn drive. Some drive types do not support the method of growing but only the method of modifying. They all are suitable for newly created images. .br All drive file objects have to offer rw-permission to the user of xorriso. Even those which will not be useable for reading an ISO image. .PP MMC compliant (i.e. optical) drives on Linux usually get addressed by the path of their block device or of their generic character device. E.g. -dev /dev/sr0 -dev /dev/hdc -dev /dev/sg2 .br Get a list of accessible drives by command -devices .br It might be necessary to do this as .B superuser in order to see all drives and to then allow rw-access for the intended users. Consider to bundle the authorized users in a group like old "floppy". .PP Filesystem objects of nearly any type can be addressed by prefix "stdio:" and their path in the filesystem. E.g.: -dev stdio:/tmp/pseudo_drive .br If path leads to a regular file or to a block device then the emulated drive is random access readable and can be used for the method of growing if it already contains a valid ISO 9660 image. Any other file type is not readable via "stdio:" and can only be used as target for the method of modifying. Non existing paths in existing directories are handled as empty regular files. .PP Be aware that especially the superuser can write into any accessible file or device by using its path with the "stdio:" prefix. Addresses without prefix "stdio:" will only work if they lead to a MMC drive. .br One may use option .B -ban_stdio_write to surely prevent this risk and to allow only MMC drives. .SS .B Rock Ridge, POSIX, X/Open: .br .B Rock Ridge is the name of a set of additional informations which enhance an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem with ownership, access permissions, symbolic links, and other attributes. .PP This is what xorriso uses for a decent representation of the disk files within the ISO image. Rock Ridge information is produced with any xorriso image and xorriso will load for manipulation only Rock Ridge enhanced images. .PP xorriso is not named "porriso" because POSIX only guarantees 14 characters of filename length. It is the X/Open System Interface standard XSI which demands a file name length of up to 255 characters and paths of up to 1024 characters. Rock Ridge fulfills this demand. .SS .B Command processing: .br Commands are either actions or settings. They consist of a command word, followed by zero or more parameter words. If the list of parameter words is of variable length (indicated by "[...]" or "[***]") then it has to be terminated by either the word "--" or the end of argument list or an end of an input line. It is not an error if "--" appears after the parameters of a command with a fixed list length. .PP .B Pattern expansion is a property of some particular commands and not a general feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern. Commands which eventually use pattern expansion all have variable argument lists which are marked in this man page by "[***]" rather than "[...]". .br Some other commands perform pattern matching unconditionally. .PP Command and parameter words are either read from program arguments, where one argument is one word, or from input lines where words are recognized similar to the quotation rules of a shell parser. .br xorriso is not a shell, although it might appear so on first glimpse. Be aware that the interaction of quotation marks and pattern symbols like "*" differs from the usual shell parsers. In xorriso, a quotation mark does not make a pattern symbol literal. .PP When the program begins then it first looks for argument -no_rc. If this is not present then it looks for its startup files and eventually reads their content as command input lines. Then it interprets the program arguments as commands and parameters and finally it enters dialog mode if command -dialog "on" was executed up to then. .PP The program ends either by command -end, or by the end of program arguments if not dialog was enabled up to that moment, or by a problem event which triggers the threshold of command -abort_on. .SS .B Dialog, Readline, Result pager: .br Dialog mode prompts for an input line, parses it into words, and performs them as commands with their parameters. It provides assisting services to make dialog more comfortable. .PP Readline is an enhancement for the input line. You may know it already from the bash shell. .br It allows to move the cursor over the text in the line by help of the leftward and the rightward arrow key. Text may be inserted at the cursor position. The delete key removes the character under the cursor. Upward and Downward arrow keys navigate through the history of previous input lines. .br See man readline for more info about libreadline. .PP Option -page activates a builtin result text pager which may be convenient in dialog. After an action has put out the given number of terminal lines, the pager prompts the user for a line of input. .br An empty line lets xorriso resume work until the next page is put out. .br The single character "@" disables paging for the current action. .br "@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress further result output. .br Any other line will be interpreted as new dialog line. The current action is urged to abort. Afterwards, the input line is executed. .PP Some actions apply paging to their info output, too. .br The urge to abort may or may not be obeyed by the current action. All actions try to abort as soon as possible. .br .SH OPTIONS .br Options marked with prefix '>' are not implemented yet. .br Options with prefix '?' are not tested yet. .br All command words are shown with a leading dash although this dash is not mandatory for the option to be recognized. There may be future emulation modes, where dashes may become mandatory in order to distinguish options from file addresses. .TP .B Aquiring source and target drive: .TP \fB\-dev\fR address Set input and output drive to the same address and load an eventual ISO image. If there is no ISO image then create a blank one. Set the image expansion method to growing. .br This is only allowed as long as no changes are pending in the currently loaded ISO image. Eventually one has to perform -commit or -rollback first. Violation yields a SORRY event. .br An empty address string gives up the current device without aquiring a new one. .TP \fB\-indev\fR address Set input drive and load eventual ISO image. If the new input drive differs from -outdev then switch from growing to modifying. The same rules and restrictions apply as with -dev. .TP \fB\-outdev\fR address Set output drive and if it differs from the input drive then switch from growing to modifying. Unlike -dev and -indev this action does not load a new ISO image. So it can be performed even if there are pending changes. .br -outdev can be performed without previous -dev or -indev. In that case an empty ISO image with no changes pending is created. It can either be populated by help of -add or it can be discarded silently if -dev or -indev are performed afterwards. .br An empty address string gives up the current output drive without aquiring a new one. No writing is possible without an output drive. .TP \fB\-ban_stdio_write\fR Allow for writing only the usage of MMC optical drives. Disallow to write the result into files of nearly arbitrary type. Once set, this command cannot be revoked. .TP .B Data manipulations: .PP The following commands expect file addresses of two kinds: .br .B disk_path is a path to an object in the local filesystem tree. .br .B iso_rr_path is the Rock Ridge name of a file object in the ISO image. (Do not confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.) .PP Note that in the ISO image you are as powerful as the superuser. Access permissions of the existing files in the image do not apply to your write operations. They are intended to be in effect with the read-only mounted image. .PP If the iso_rr_path of a newly inserted file leads to an existing file object in the ISO image, then the following collision handling happens: .br If both objects are directories then they get merged by recursively inserting the subobjects from filesystem into ISO image. If other file types collide then the setting of command .B \-overwrite decides. .br Renaming of files has similar collision handling, but directories can only be replaced, not merged. .PP The commands in this section alter the ISO image and not the local filesystem. .TP \fB\-iso_rr_pattern\fR "on"|"ls"|"off" Set the pattern expansion mode for the iso_rr_path arguments of several commands which support this feature. .br .B Pattern expansion converts a list of pattern words into a list of existing file addresses. Eventual unmatched pattern words appear themselves in that result list, though. .br Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' and respects '/' as separator which may only be matched literally. .br Setting "off" disables this feature for all commands which are marked in this man page by "iso_rr_path [***]" or "iso_rr_pattern [***]". .br Setting "on" enables it for all those commands. .br Setting "ls" enables it only for those which are marked by "iso_rr_pattern [***]". .br Default is "on". .TP \fB\-disk_pattern\fR "on"|"ls"|"off" Set the pattern expansion mode for the disk_path arguments of several commands which support this feature. .br Setting "off" disables this feature for all commands which are marked in this man page by "disk_path [***]" or "disk_pattern [***]". .br Setting "on" enables it for all those commands. .br Setting "ls" enables it only for those which are marked by "disk_pattern [***]". .TP \fB\-add\fR pathspec [...] | disk_path [***] Insert the given files or directory trees from filesystem into the ISO image. .br If -pathspecs is set to "on" then pattern expansion is always disabled and character '=' has a special meaning. It eventually separates the ISO image path from the disk path: .br iso_rr_path=disk_path .br The separator '=' can be escaped by '\\'. If iso_rr_path does not begin with '/' then -cd is prepended. If disk_path does not begin with '/' then -cdx is prepended. .br If no '=' is given then the word is used as both, iso_rr_path and disk path. If in this case the word does not begin with '/' then -cdx is prepended, not -cd. .br If -pathspecs is set to "off" then eventual -disk_pattern expansion applies. The resulting words are used as both, iso_rr_path and disk path. Eventually -cdx gets prepended. .TP \fB\-path_list\fR disk_path Like -add but read the parameter words from file disk_path. One pathspec resp. disk_path pattern per line. .TP > \fB\-cp_r\fR disk_path [***] iso_rr_path Insert the given files or directory trees from filesystem into the ISO image. Use the same rules for generating the ISO addresses as would be done with shell command cp -r. .TP \fB\-rm\fR iso_rr_path [***] Delete the given files from the ISO image. .br Note: This does not free any space on the -indev media, even if the deletion is committed to that same media. .br The image size will shrink if the image is written to a different media in modification mode. .TP \fB\-rm_r\fR iso_rr_path [***] Delete the given files or directory trees from the ISO image. See also the note with option -rm. .TP \fB\-mv\fR iso_rr_path [***] iso_rr_path Rename the given file objects in the ISO tree to the last argument in the list. Use the same rules as with shell command mv. .br If pattern expansion is enabled and if the last argument contains wildcard characters then it must match exactly one existing file address, or else the command fails with a SORRY event. .TP \fB\-chown\fR uid iso_rr_path [***] Set ownership of file objects in the ISO image. uid may either be a decimal number or the name of a user known to the operating system. .TP \fB\-chgrp\fR gid iso_rr_path [***] Set group attribute of file objects in the ISO image. gid may either be a decimal number or the name of a group known to the operating system. .TP \fB\-chmod\fR mode iso_rr_path [***] Equivalent to shell command chmod in the ISO image. mode is either an octal number beginning with "0" or a comma separated list of statements of the form [ugoa]*[+-=][rwxst]* . Like: go-rwx,u+rwx . .br .B Personalities: u=user, g=group, o=others, a=all .br .B Operators: + adds given permissions, - revokes given permissions, = revokes all old permissions and then adds the given ones. .br .B Permissions: r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit .br For octal numbers see man 2 stat. .TP \fB\-alter_date\fR type timestring iso_rr_path [***] Alter the date entries of a file in the ISO image. type is one of "a", "m", "b" for access time, modification time, both times. .br timestring may be in the following formats (see also section EXAMPLES): .br As expected by program date: MMDDhhmm[[CC]YY][.ss]] .br As produced by program date: [Day] MMM DD hh:mm:ss [TZON] YYYY .br Relative times counted from current clock time: +|-Number["s"|"h"|"d"|"w"|"m"|"y"] .br where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d, "y"=365.25d plus 1d added multiplication result. .br Absolute seconds counted from Jan 1 1970: =Number .br xorriso's own timestamps: YYYY.MM.DD[.hh[mm[ss]]] .br scdbackup timestamps: YYMMDD[.hhmm[ss]] .br where "A0" is year 2000, "B0" is 2010, etc. .TP \fB\-mkdir\fR iso_rr_path [...] Create empty directories if they do not exist yet. Existence as directory generates a WARNING event, existence as other file cause a SORRY event. .TP \fB\-rmdir\fR iso_rr_path [***] Delete empty directories. .TP \fB\-\-\fR Mark end of particular action argument list. .TP \fB\-rollback\fR Discard the manipulated ISO image and reload it from -indev. .TP .B Writing the result: (see also paragraph about settings below) .TP \fB\-commit\fR Perform the write operation. Afterwards eventually make the -outdev the new -dev and load the image from there. Switch from eventual modifiying mode to growing mode. (A subsequent -outdev will activate modification mode.) -commit is performed automatically at end of program if there are uncommitted manipulations pending. So to perform a final write operation with no new -dev and no new loading of image, rather execute option -end. To suppress a final write, execute -rollback -end. .br Writing can last quite a while. It is not unnormal with several types of media that there is no progress visible for the first few minutes or that the drive gnaws on the media for a few minutes after all data have been transmitted. xorriso and the drives are in a client-server relationship. The drives have much freedom about what to do with the media. Some combinations of drives and media simply do not work, despite the promises by vendors of drives and media. If writing fails - or even the drive gets stuck and you need to reboot - then try other media or another drive. The reason for such failure is hardly ever in the code of the various burn programs but you may well try some of those listed below under SEE ALSO. .TP \fB\-eject\fR "in"|"out"|"all" Eject the media in -indev, resp. -outdev, resp. both drives. Note: It is not possible yet to effectively eject disk files. .TP \fB\-blank\fR mode Blank media resp. invalidate ISO image on media if not -dummy is activated. .br This affects only the -outdev not the -indev. If both drives are the same and if the ISO image was altered then this command leads to a SORRY event. Defined modes are: fast, all, deformat, deformat_quickest .br "fast" and "all" make CD-RW and unformatted DVD-RW re-usable, or invalidate overwriteable ISO images. "deformat" converts overwriteable DVD-RW into unformatted ones. "deformat_quickest" is a faster way to deformat or blank DVD-RW but produces media which are only suitable for a single session. xorriso will write onto them only if option -close is set to "on". .br The progress reports issued by some drives while blanking are quite unrealistic. Do not conclude success or failure from the reported percentages. Blanking was successful if no FATAL or SORRY event occured. .TP \fB\-format\fR mode Convert unformatted DVD-RW into overwriteable ones, "de-ice" DVD+RW. For now, mode should be the word "full". .br This action has no effect on media if -dummy is activated. .br Be warned that re-formatting DVD+RW is considered to be risky to the media's health. DVD+RW get formatted as far as needed during writing, but an entirely formatted media might be better readable in some DVD players. .br On the other hand unreliable DVD+RW can sometimes be repaired by re-formatting. .br The progress reports issued by some drives while formatting are quite unrealistic. Do not conclude success or failure from the reported percentages. Formatting was successful if no FATAL or SORRY event occured. .TP .B Settings for data insertion: .TP \fB\-follow\fR occasion[:occasion[...]] Enable or disable resolution of symbolic links and mountpoints under disk_paths. This applies to actions -add, -du*x, -ls*x and to -disk_pattern expansion. .br There are two kinds of follow decisison to be made: .br "link" is the hop from a symbolic link to its target file object. If enabled then symbolic links are handled as their target file objects, else symbolic links are handled as themselves. .br "mount" is the hop from one filesystem to another subordinate filesystem. If enabled then mountpoint directories are handled as any other directory, else mountpoints are handled as empty directories if they are encountered in directory tree traversals. .br Less general than above occasions: .br "pattern" is mount and link hopping, but only during -disk_pattern expansion. .br "param" is link hopping for parameter words (after eventual pattern expansion). If enabled then -ls*x will show the link targets rather than the links themselves. -du*x and -add will process the link targets but not follow links in an eventual directory tree below the targets (unless "link" is enabled). .br Occasions can be combined in a colon separated list. All occasions mentioned in the list will then lead to a positive follow decision. .br "off" prevents any positive follow decision. Use it if no other occasion applies. .br Shortcuts: .br "default" is equivalent to "pattern:mount:limit=100". .br "on" always decides positive. Equivalent to "link:mount". .br Not an occasion but an optional setting is: .br "limit=" which sets the maximum number of link hops. A link hop consists of a sequence of symbolic links and a final target of different type. Nevertheless those hops can loop. Example: .br \fB$\fR ln -s .. uploop .br Link hopping has a builtin loop detection which stops hopping at the first repetition of a link target. Then the repeated link is handled as itself and not as its target. Regrettably one can construct link networks which cause exponential workload before their loops get detected. The number given with "limit=" can curb this workload at the risk of truncating an intentional sequence of link hops. .TP \fB\-pathspecs\fR "on"|"off" Control parameter interpretation with xorriso actions -add and -path_list. .br "on" enables pathspecs of the form .B target=source like with program mkisofs -graft-points. It also disables -disk_pattern expansion for command -add. .br "off" disables pathspecs of the form target=source and eventually enables -disk_pattern expansion. .TP \fB\-overwrite\fR "on"|"nondir"|"off" Allow or disallow to overwrite existing files in the ISO image by files with the same user defined name. .br With setting "off", name collisions cause SORRY-events. With setting "nondir", only directories are protected by such events, other existing file types get treated with -rm before the new file gets added. Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an existing directory and all its subordinates. .TP .B Settings for result writing: .TP Rock Ridge info will be generated by the program unconditionally. .TP ? \fB\-J\fR Generate Joliet info additional to Rock Ridge info. .TP > \fB\-V\fR volid Specifies the volume ID. .TP \fB\-uid\fR uid User id to be used for all files when the new ISO tree gets written to media. .TP \fB\-gid\fR gid Group id to be used for all files when the new ISO tree gets written to media. .TP \fB\-speed\fR number[k|m|c|d] Set the burn speed. Default is 0 = maximum speed. Speed can be given in media dependent numbers or as a desired throughput per second in MMC compliant kB (= 1000) or MB (= 1000 kB). Media x-speed factor can be set explicity by "c" for CD and "d" for "DVD". Example speeds: 706k = 706kB/s = 4c = 4xCD 5540k = 5540kB/s = 4d = 4xDVD .br If there is no hint about the speed unit attached, then the media in the -outdev will decide. Default unit is CD = 176.4k. .br MMC drives usually activate their own idea of speed and take the speed value given by the burn program only as upper limit for their own decision. .TP \fB\-dummy\fR "on"|"off" If "on" simulate burning or refuse with SORRY event if no simulation is possible, do neither blank nor format. .TP \fB-fs\fR number["k"|"m"] Set the size of the fifo buffer which smoothens the data stream from ISO image generation to media burning. Default is 4 MiB, minimum 64 kiB, maximum 1 GiB. The number may be followed by letter "k" or "m" which means unit is kiB (= 1024) or MiB (= 1024 kiB). .TP \fB\-close\fR "on"|"off" If "on" then mark the written media as not appendable any more (if possible at all with the given type of target media). .br This is the contrary of cdrecord, wodim, cdrskin option -multi, and is one aspect of growisofs option -dvd-compat. .TP .B Exception processing: .TP \fB\-abort_on\fR severity Set the threshold for events to abort the program. Events are classified by severity : "NEVER", "ABORT", "FATAL", "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "ALL" .br Severities "NEVER" and "ALL" do not occur but mark the extreme ends of this potentially expandable range. .br It may become necessary to abort the program anyway, despite the setting by this option. Expect not many "ABORT" events to be ignorable. .TP \fB\-report_about\fR severity Set the threshold for events to be reported. Events are the same as with -abort_on. Regardless what is set by -report_about, messages get always reported if they reach the severity threshold of -abort_on . .br Event messages are sent to the info channel "I" which is usually stderr but may be influenced by command -pkt_output. Info messages which belong to no event get attributed severity "NOTE". .TP .B Dialog mode control: .TP \fB\-dialog\fR "on"|"off" Enable or disable to enter dialog mode after all arguments are processed. In dialog mode input lines get prompted via readline or from stdin. .TP \fB\-page\fR length width Describe terminal to the text pager. See also above, paragraph Result pager. .br If parameter length is nonzero then the user gets prompted after that number of terminal lines. Zero length disables paging. .br Parameter width is the number of characters per terminal line. It is used to compute the number of terminal lines which get occupied by an output line. A usual terminal width is 80. .TP \fB\-use_readline\fR "on"|"off" If "on" then use readline for dialog. Else use plain stdin. .br See also above, paragraph Dialog, Readline, Result pager. .TP \fB\-reassure\fR "on"|"tree"|"off" If "on" then ask the user for "y" or "n" before deleting or overwriting any file in the ISO image. With setting "tree" the reassuring prompt will appear for an eventual directory only once and not for each file in its whole subtree. Setting "off" silently kills any kind of image file object. To really produce user prompts, option -dialog needs to be set to "on". .br Note that the prompt appears only in situations where file removal is not forbidden by option -overwrite. -reassure only imposes an additional curb for removing existing file objects. .br Be aware that file objects get deleted from the ISO image immediately after confirmation. They are gone even if the running command gets aborted and its desired effect gets revoked. In case of severe mess-up, consider to use -rollback to revoke the whole session. .TP .B Drive and media related inquiry actions: .TP \fB\-toc\fR Show media specific table of content. This is the media structure, not the ISO image directory tree. In case of overwriteable media holding a valid ISO image, a single session gets fabricated from the ISO image size info. .br A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM with only one or two sessions on it. The last of these sessions is supposed to be the most recent real session then. .TP \fB\-devices\fR Show list of available MMC drives with the addresses of their libburn standard device files. .br This is only possible when no ISO image changes are pending. After this option was executed, there is no drive current and no image loaded. Eventually one has to aquire a drive again. .br In order to be visible, a device has to offer rw-permissions with its libburn standard device file. Thus it might be only the .B superuser who is able to see all drives. .br Drives which are occupied by other processes get not shown. .TP \fB\-print-size\fR Print the foreseeable consumption of 2048 byte blocks by next -commit. This can last a while as a -commit gets prepared and only in last moment is revoked by this option. .TP \fB\-tell_media_space\fR Print available space on output media and the free space after subtracting already foreseeable consumption by next -commit. .TP .B Navigation in ISO image and disk filesystem: .TP \fB\-cd\fR iso_rr_path Change the current working directory in the emerging ISO image as it is at the moment. .TP \fB\-cdx\fR disk_path Change the current working directory on filesystem. .TP \fB\-pwd\fR Tell the current working directory in the ISO image. .TP \fB\-pwdx\fR Tell the current working directory on local filesystem. .TP \fB\-ls\fR iso_rr_pattern [***] List files in the ISO image which match shell patterns (i.e. with wildcards '*' '?' '[a-z]'). If a pattern does not begin with '/' then it is compared with addresses relative to -cd, the current working directory in the ISO image. .br Directories are listed by their content rather than as single file item. .br Pattern expansion may be disabled by command -iso_rr_pattern. .TP \fB\-lsd\fR iso_rr_pattern [***] Like -ls but listing directories as themselves and not by their content. This resembles shell command ls -d. .TP \fB\-lsl\fR iso_rr_pattern [***] Like -ls but also list some of the file attributes. Output format resembles shell command ls -ln. .TP \fB\-lsdl\fR iso_rr_pattern [***] Like -lsd but also list some of the file attributes. Output format resembles shell command ls -dln. .TP \fB\-lsx\fR disk_pattern [***] List files on local filesystem which match shell patterns. Patterns which do not begin with '/' are used relative to -cdx, the current working directory in the local filesystem. .br Directories are listed by their content rather than as single file item. .br Pattern expansion may be disabled by command -disk_pattern. .TP \fB\-lsdx\fR disk_pattern [***] Like -lsx but listing directories as themselves and not by their content. This resembles shell command ls -d. .TP \fB\-lslx\fR disk_pattern [***] Like -lsx but also listing some of the file attributes. Output format resembles shell command ls -ln. .TP \fB\-lsdlx\fR disk_pattern [***] Like -lsdx but also listing some of the file attributes. Output format resembles shell command ls -dln. .TP \fB\-du\fR iso_rr_pattern [***] Recursively list size of directories and files in the ISO image which match one of the patterns. similar to shell command du -k. .TP \fB\-dux\fR disk_pattern [***] Recursively list size of directories and files in the local filesystem which match one of the patterns, similar to shell command du -k. .TP \fB\-dus\fR iso_rr_pattern [***] List size of directories and files in the ISO image which match one of the patterns. Similar to shell command du -sk. .TP \fB\-dusx\fR disk_pattern [***] List size of directories and files in the local filesystem which match one of the patterns. Similar to shell command du -sk. .TP \fB\-find\fR iso_rr_path [-name pattern] A very restricted sunstitute for to shell command find in the ISO image. It prints the paths of matchin file objects beginning with iso_rr_path. .br Optional -name pattern is not expanded but used for comparison with the particular file names of the eventual directory tree underneath iso_rr_path. If no -name pattern is given, then any file name matches. .TP > \fB\-findx\fR pattern Like -find but operating on loacl filesystem and not on ISO image. .TP .B Scripting, dialog and program control features: .TP \fB\-no_rc\fR Only if used as first command line argument this option prevents reading and interpretation of eventual startup files. See section FILES below. .TP \fB\-help\fR Print helptext. .TP \fB\-version\fR Print program name and version. .TP \fB\-history\fR textline Copy textline into libreadline history. .TP \fB\-status\fR [mode|filter] Print the current settings of xorriso. Modes: short... print only important or altered settings long ... print all settings including defaults long_history like long plus history lines .br Filters begin with '-' and are compared literally against the output lines of -status:long_history. A line is put out only if its start matches the filter text. No wildcards. .TP \fB\-status_history_max\fR number Set maximum number of history lines to be reported with -status "long_history". .TP \fB\-temp_mem_limit\fR number["k"|"m"] Set the maximum size of temporary memory to be used for image dependent buffering. Currently this applies to pattern expansion only. .br Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 GiB. .TP \fB\-options_from_file\fR fileaddress Reads lines from fileaddress and executes them as dialog lines. .TP \fB\-print\fR text Print a text to result channel. .TP \fB\-prompt\fR text Show text at beginning of output line and wait for the user to hit the Enter key resp. to send a line via stdin. .TP \fB\-end\fR End program immediately .TP \fB#\fR any text In dialog or file execution mode only and only as first non-whitespace in line: Do not execute the line but eventually store it in history. .TP .B Support for frontend programs talking into stdin and listening at stdout: .TP \fB\-pkt_output\fR "on"|"off" Consolidate text output on stdout and classify each line by a channel indicator: .br 'R:' for result lines, 'I:' for notes and error messages, 'M:' for -mark texts. .br Next is a decimal number of which only bit 0 has a meaning for now. 0 means no newline at end of payload, 1 means that the newline character at the end of the output line belongs to the payload. After another colon follows the payload text. .br Example: I:1: enter option and arguments : .TP \fB\-logfile\fR channel fileaddress Copy output of a channel to the given file. .TP \fB\-mark\fR text If text is not empty it will get put out each time an action has been completed. .TP \fB\-prog\fR text Use text as this program's name in subsequent messages .TP \fB\-prog_help\fR text Use text as this program's name and perform -help. .br .SH EXAMPLES .SS .B As superuser learn about available drives Consider to give rw permissions to those users or groups which shall be able to use the drives with xorriso. .br \fB$\fR xorriso -devices .br 0 -dev '/dev/sr0' rwrw-- : '_NEC ' 'DVD_RW ND-4570A' .br 1 -dev '/dev/sr1' rwrw-- : 'HL-DT-ST' 'DVDRAM GSA-4082B' .br 2 -dev '/dev/sr2' rwrw-- : 'PHILIPS ' 'SPD3300L' .SS .B Blank media and compose a new ISO image as batch run Aquire drive /dev/sr2, blank media resp. invalidate existing ISO image. Add the files from hard disk directories /home/me/sounds and /pictures. Omit some unwanted stuff by removing it from the image directory tree. Re-add some wanted stuff. .br Because no -dialog "on" is given, the program will then end by committing the session to media. .br \fB$\fR xorriso -outdev /dev/sr2 \\ -blank fast \\ -pathspecs on \\ -add \\ /sounds=/home/me/sounds \\ /pictures \\ -- \\ -rm_r \\ /sounds/indecent \\ '/pictures/*private*' \\ /pictures/confidential \\ -- \\ -add \\ /pictures/confidential/work* .br Note that '/pictures/*private*' is a pattern for iso_rr_paths while /pictures/confidential/work* gets expanded by the shell with addresses from the hard disk. .SS .B A dialog session doing about the same .br -pathspecs is already given as start argument. The other activities are done as dialog input. The pager gets set to 20 lines of 80 characters. .br The drive is aquired by option -dev rather than -outdev in order to see the message about its current content. By option -blank this content is made ready for being overwritten and the loaded ISO image is made empty. .br In order to be able to eject the media, the session needs to be committed explicitely. .br .B $ xorriso -pathspecs on -dialog on -page 20 80 .br enter option and arguments : .br .B \-dev /dev/sr2 .br enter option and arguments : .br .B \-blank fast .br enter option and arguments : .br .B \-add /sounds=/home/me/sounds /pictures .br enter option and arguments : .br .B \-rm_r /sounds/indecent /pictures/*private* /pictures/confidential .br enter option and arguments : .br .B \-add /pictures/confidential/work_office /pictures/confidential/work_factory .br enter option and arguments : .br .B \-du / .br enter option and arguments : .br .B \-commit -eject all -end .br .SS .B Manipulating an existing ISO image on the same media Load image from drive. Remove (i.e. hide) directory /sounds and its subordinates. Rename directory /pictures/confidential to /pictures/restricted. Change access permissions of directory /pictures/restricted. Add new directory trees /sounds and /movies. Burn to the same media and eject. .br \fB$\fR xorriso -dev /dev/sr2 \\ -rm_r /sounds -- \\ -mv \\ /pictures/confidential \\ /pictures/restricted \\ -- \\ -chmod go-rwx /pictures/restricted -- \\ -pathsspecs on \\ -add \\ /sounds=/home/me/prepared_for_dvd/sounds_dummy \\ /movies=/home/me/prepared_for_dvd/movies \\ -- \\ -commit -eject all .SS .B Copy modified ISO image from one media to another Load image from input drive. Do the same manipulations as in the previous example. Aquire output drive and blank it. Burn the modified image as first and only session to the output drive. .br \fB$\fR xorriso -indev /dev/sr2 \\ -rm_r /sounds -- \\ ... -outdev /dev/sr0 -blank fast \\ -commit -eject all .SS .B Examples of input timestrings .br As printed by program date: .B 'Thu Nov 8 14:51:13 CET 2007' .br The same without ignored parts: .B 'Nov 8 14:51:13 2007' .br The same as expected by date: .B 110814512007.13 .br Four weeks in the future: .B +4w .br The current time: .B +0 .br Three hours ago: .B \-3h .br Seconds since Jan 1 1970: .B =1194531416 .br .SH FILES .SS .B Startup files: .br If not -no_rc is given as the first argument then xorriso attempts on startup to read and execute lines from the following files: /etc/default/xorriso /etc/opt/xorriso/rc /etc/xorriso/cdrskin.conf $HOME/.xorrisorc .br The files are read in the sequence given above, but none of them is required for xorriso to function properly. .br .SH SEE ALSO .TP For mounting xorriso generated ISO 9660 images .br .BR mount(8) .TP Other programs which produce ISO 9660 images .br .BR mkisofs(8), .BR genisoimage(8) .TP Other programs which burn sessions to optical media .BR growisofs(1), .BR cdrecord(1), .BR wodim(1), .BR cdrskin(1) .br .SH AUTHOR Thomas Schmitt .br for libburnia-project.org