From 361b93caa2ffd870480477bed540dcea7e7dc99d Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Sat, 20 Oct 2007 17:12:11 +0000 Subject: [PATCH] Splitted think text from emerging man page, formatted man page --- test/changelog.txt | 110 +++++++- test/xorriso.1 | 664 +++++++++++++++++++++++++++++++++++++++++++++ test/xorriso.txt | 504 +--------------------------------- 3 files changed, 765 insertions(+), 513 deletions(-) create mode 100644 test/xorriso.1 diff --git a/test/changelog.txt b/test/changelog.txt index 28d62413..8a3cfd75 100644 --- a/test/changelog.txt +++ b/test/changelog.txt @@ -257,23 +257,112 @@ Fixed bug with -speed. test/xorriso.c Fixed bug with -prompt. Fixed bug with # comments. (of rev 1194) +18 Oct 2007 [1203] +test/changelog.txt +Updated changelog and todo list + +2007.10.18.144841 [1205] +src/isofs_wrap.c +test/xorrisoburn.c +isoburn_read_volset() now hands out an official volset reference + +2007.10.18.171415 [1206] +test/xorriso.c +test/xorriso.txt +test/xorrisoburn.h +test/xorrisoburn.c +Implemented option -devices + +2007.10.18.183200 [1207] +test/xorriso.c +test/xorrisoburn.h +test/xorrisoburn.c +Implemented option -tell_media_space + +2007.10.18.185731 [1208] +test/xorriso_private.h +test/xorriso.c +test/xorrisoburn.c +Fixed a SIGSEGV with xorriso -version run + +2007.10.18.221756 [1211] +test/xorrisoburn.c +src/libisoburn.h +Took care of disposal of burn_disc ovbject + +18 Oct 2007 [1212] +test/test.c +Silenced compile warning + +2007.10.18.225654 [1213] +src/isofs_wrap.c +test/xorriso.c +test/xorrisoburn.c +Fixed a SIGSEGV with empty drive + +2007.10.19.140031 [1218] +test/xorrisoburn.c +Made reports with -add normal infos (formerly NOTE events) + +2007.10.19.151339 [1219] +test/xorriso.c +test/xorrisoburn.c +test/xorriso.txt +Implemented -print-size + +2007.10.19.164957 [1220] +test/xorriso_private.h +test/xorriso.c +test/xorriso.h +test/xorrisoburn.c +test/xorriso.txt +Implemented verbosity control by option -report_about + +2007.10.19.173547 [1221] +test/xorriso.c +test/xorrisoburn.c +test/xorriso.txt +Implemented option -eject + +2007.10.19.204155 [1222] +test/xorriso_private.h +test/xorriso.h +test/xorriso.c +test/xorrisoburn.h +test/xorrisoburn.c +Implemented option -blank + +2007.10.20.170731 [1223] +src/burn_wrap.c +Directed write mode failure message to libburn queue, repaired wrote_well + +2007.10.20.171046 [1224] +test/xorrisoburn.c +test/xorriso_private.h +test/xorriso.c +Implemented options -format and -blank deformat, -close and closed media + +20 Oct 2007 [] +test/xorriso.txt ++ test/xorriso.1 +test/changelog.txt +Splitted think text from emerging man page, formatted man page + + =============================================================================== TODO =============================================================================== -? what happens to the burn_disc object after writing ? - I suspect a memory leak. +- -tell_media_space : subtract -print-size -- Make message verbosity adjustable: -report_about +? what about overwritig files by -add, currently ? + Explicite files should refuse. What about files in added trees ? + +- Image info and manipulation + - more to come - - Drive info and operation. - -devices - -- isoburn_read_volset() must hand out a reference to volset - and not a mere pointer. - It is not plausible in xorriso why the volset pointer - may not be freed but gets invalidated by isoburn_release_drive() - and has to be NULLed afterwards (or is a memory bomb). + -blank - isoburn_prepare_disc() needs to learn the two fifo parameters chuncksize and number of chunks. @@ -282,6 +371,7 @@ Fixed bug with -prompt. Fixed bug with # comments. (of rev 1194) "Options for image generation and streaming" and add the parameters there. +- care for modifying =============================================================================== diff --git a/test/xorriso.1 b/test/xorriso.1 new file mode 100644 index 00000000..97fd4eff --- /dev/null +++ b/test/xorriso.1 @@ -0,0 +1,664 @@ +.\" 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 XORRIXO 1 "October 20, 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 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 + > Writes result as completely new image to optical media or filesystem objects. +.br +Writes 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. +.SS +.B General information paragraphs: +.br +Session model +.br +Libburn drives +.br +Rock Ridge, POSIX, X/Open +.br +Command processing +.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 a session if 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 +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. +This session usually contains an updated directory tree for the whole media +which governs the data contents in all recorded sessions. +.PP +The multi-session model of the MMC standard applies to CD-R[W], to DVD-R, to +certain states of DVD-RW, and to DVD+R. But it does not apply to overwriteable +MMC media like DVD-RAM, DVD+RW, formatted DVD-RW, and of course not to disk +files or block devices. +Program growisofs by Andy Polyakov showed how to extend this functionality +to overwriteable media or disk files which carry valid ISO 9660 filesystems. +These two expansion methods are referred as "growing" in this text. +.PP +xorriso provides growing as well as an own method which produces a completely + > new ISO image from the old one and the modifications. This unique xorriso + > method produces compact filesystem images with no waste by outdated data blocks + > and it can write modified images to targets which are completely unsuitable + > for multi-session operations. E.g. fast blanked DVD-RW, named pipes, + > character devices, sockets. + > Therefore this method is called "modifying". Its drawback is that the target + > cannot be the same media which holds the unmodified ISO image but that this + > media has to be present while the new image gets written to another media. + > So typically one needs either two optical drives or has to work with + > filesystem objects as source and/or target media. +.PP +xorriso adopts the concept of 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 and ends by command -commit which triggers +writing. A -commit is done automatically when the program ends regularly. +.PP +After -commit a new session begins. A new input drive can only be chosen +as long as the loaded ISO image was not altered. 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 Libburn drives: +.br +Source of an existing ISO image can be any random access readable libburn +drive: optical media with readable data, regular files, block devices. +RockRidge info must be present in existing ISO images and it will be generated +by the program unconditionally. +.PP +Target for writing can be any libburn drive. +Some drive types do not support the method of growing but only the method +of modifying. +.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 superuser in order to see all drives +and to then allow rw-access for the intended users. +.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. +.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 "[...]") 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 +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. +When the program begins then it first 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 was executed up to then. +.PP +The program ends either by command -end or by the end of program arguments +if not command -dialog was encountered up to that moment. +.br +.SH OPTIONS +.TP +.B Aquiring source and target drive: +.TP +\fB\-dev\fR address +Set input and output drive and load eventual ISO image. +Set the image expansion method to growing. +Only allowed as long as no ISO image was loaded and +altered, or after actions -rollback, or -commit. +Violation yields a SORRY event. +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. Switch from +growing to modifying. Same restrictions as with -dev +.TP +> \fB\-outdev\fR address +> Set output drive and switch from growing to modifying. +.TP +\fB\-ban_stdio_write\fR +Allow for writing only the usage of 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 +.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.) +.br +The following commands may depend on settings listed further below. +.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 or renamed file leads to an existing +file object in the ISO image, then the following collision handling happens: +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 -overwrite decides. + > Directories may only be deleted by commands -rmdir or -rm_r. +.PP +The commands in this section alter the ISO image and not the local filesystem. +.TP +\fB\-add\fR path [...] +Insert the given files or directory trees from filesystem +into the ISO image. +.br +Use the same paths on ISO unless -graft-points is set and +the paths have the form iso_rr_path=disk_path . +.TP +> \fB\-path-list\fR disk_path +Like -add but read the pathspecs from file disk_path. +One pathspec 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. +.TP +> \fB\-rm_r iso_rr_path [...] +Delete the given files or directory trees from the ISO image. +.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. +.TP +> \fB\-chown\fR uid iso_rr_path [...] +Equivalent to shell command chown in the ISO image. +.TP +> \fB\-chgrp\fR gid iso_rr_path [...] +Equivalent to shell command chgrp in the ISO image. +.TP +> \fB\-chmod\fR mode iso_rr_path [...] +Equivalent to shell command chmod in the ISO image. +.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. +.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 indrive. +.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 -indev 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 if there is no progress visible for the first +few minutes and if 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 outdrive not the indrive. +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 +"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 faster 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. +As mode submit the word "full" for now. +.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 + +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 +RockRidge info will be generated by the program unconditionally. +.TP +\fB\-J\fR +Generate Joliet info additional to Rock Ridge info. +.TP +> \fB\-f\fR +Follow symbolic links. +.TP +\fB\-uid\fR uid +User id to be used for all files when inserted into the new ISO tree. +.TP +\fB\-gid\fR gid +Group id for the same purpose. +.TP +\fB\-graft-points\fR +For xorriso action -add this enables pathspecs of the form +.B target=source +like with program mkisofs. +.TP +.B Settings for result writing: +.TP +> \fB\-V\fR volid +Specifies the volume ID. +.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 outdrive 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. If "on" do not blank or 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. 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 -multi, +and is one aspect of growisofs -dvd-compat. +.TP +.B Exception processing: +.TP +\fB\-abort_on\fR severity +Set the threshhold 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 threshhold 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 threshhold of -abort_on . +.TP +> \fB\-overwrite\fR "on"|"off" +Allow or disallow to overwrite existing files in the +ISO image by files with the same user defined name. This is +the RockRidge name and not the plain ISO name. +.br +With setting "off", RR name collisions cause SORRY-events. +.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 len width +Describe terminal to the text pager. +.TP +? \fB\-use_readline\fR "on"|"off" +If "on" then use readline for dialog. Else use plain stdin. +.TP +> \fB\-reassure\fR "on"|"off" +If "on" then ask the user for "y" or "n" with any file +before deleting or overwriting it in the ISO image. +.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. +.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 (minus 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 pattern +List files from the current working directory in the ISO +image which match a shell pattern. (I.e. wildcards '*' '?') +.TP +> \fB\-lsx\fR pattern +List files from the current working directory on local filesystem +which match a shell pattern. (I.e. wildcards '*' '?') +.TP +> \fB\-ls_l\fR pattern +Like -ls but also list some of the file attributes. +.TP +> \fB\-ls_lx\fR pattern +Like -lsx but also list some of the file attributes. +.TP +> \fB\-find\fR pattern +Equivalent to shell command find . -name pattern in the ISO image. +.TP +> \fB\-findx\fR pattern +Equivalent to shell command find . -name pattern on filesystem. +.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\-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. +.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 + +>>> to come + +.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 +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 images to optical media +.BR growisofs(1), +.BR cdrecord(1), +.BR wodim(1), +.BR cdrskin(1) +.br +.SH AUTHOR +Thomas Schmitt for libburnia-project.org diff --git a/test/xorriso.txt b/test/xorriso.txt index 710d7786..56e8cc88 100644 --- a/test/xorriso.txt +++ b/test/xorriso.txt @@ -31,239 +31,7 @@ I got an allergy against .so . My immune system mistakes them for .DLL .) >>> currently a stub for xorriso is derived from the source of scdbackup_askme. -------------------------------------------------------------------------- -Emerging man page: - -XORRISO(1) XORRISO(1) - - -NAME -xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images -with Rock Ridge extensions. - -SYNOPSIS -xorriso [settings|actions] - -DESCRIPTION -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. - -A special property of xorriso is that it needs neither an external ISO 9660 -formatter program nor an external burn program but rather incorporates -the libraries of the libburnia project. - -Overview of features: - -Operates on an existing ISO image or creates a new one. -Copies files from filesystem into the ISO image. -Renames or deletes file objects in the ISO image. -Changes file properties in the ISO image. -Writes result as completely new image to optical media or filesystem objects. -Writes result as add-on session to appendable multi-session media, -to overwriteable media, to regular files, and to block devices. -Scans for optical drives, blanks re-useable optical media. -Reads its instructions from command line arguments, dialog, and batch files. - -General information paragraphs: -Session model -Command processing -Libburn drives -Rock Ridge, POSIX, X/Open - -Session model: - -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 . -The data content of a session if called filesystem -.B image . - -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 -regular disk files. - -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. -This session usually contains an updated directory tree for the whole media -which governs the data contents in all recorded sessions. - -The multi-session model of the MMC standard applies to CD-R[W], to DVD-R, to -certain states of DVD-RW, and to DVD+R. But it does not apply to overwriteable -MMC media like DVD-RAM, DVD+RW, formatted DVD-RW, and of course not to disk -files or block devices. -Program growisofs by Andy Polyakov showed how to extend this functionality -to overwriteable media or disk files which carry valid ISO 9660 filesystems. -These two expansion methods are referred as "growing" in this text. - -xorriso provides growing as well as an own method which produces a completely -new ISO image from the old one and the modifications. This unique xorriso -method produces compact filesystem images with no waste by outdated data blocks -and it can write modified images to targets which are completely unsuitable -for multi-session operations. E.g. fast blanked DVD-RW, named pipes, -character devices, sockets. -Therefore this method is called "modifying". Its drawback is that the target -cannot be the same media which holds the unmodified ISO image but that this -media has to be present while the new image gets written to another media. -So typically one needs either two optical drives or has to work with -filesystem objects as source and/or target media. - -xorriso adopts the concept of 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. -The first session of a xorriso run begins by the definition of the input -drive with the eventual ISO image and ends by command -commit which triggers -writing. A -commit is done automatically when the program ends regularly. - -After -commit a new session begins. A new input drive can only be chosen -as long as the loaded ISO image was not altered. Alteration can be revoked -by command -rollback. - -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. -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. - - -Command processing: - -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 "[...]") 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. - -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. -When the program begins then it first 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 was executed up to then. - -The program ends either by command -end or by the end of arguments with -no command -dialog encountered. - -Libburn drives: - -Source of an existing ISO image can be any random access readable libburn -drive: optical media with readable data, regular files, block devices. -RockRidge info must be present in existing ISO images and it will be generated -by the program unconditionally. - -Target for writing can be any libburn drive. -Some drive types do not support the method of growing but only the method -of modifying. - -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. - -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 -Get a list of accessible drives by command - -devices -It might be necessary to do this as superuser in order to see all drives -and to then allow rw-access for the intended users. - -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 -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 -and can only be used as target for the method of modifying. - -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 an optical drive. - - -Rock Ridge, POSIX, X/Open: - -.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. - -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. - -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. - - -OPTIONS - -Aquiring source and target drive: - --dev address Set input and output drive and load eventual ISO image. - Set the image expansion method to growing. - Only allowed as long as no ISO image was loaded and - altered, or after actions -rollback, or -commit. - Violation yields a SORRY event. - An empty address string gives up the current device - without aquiring a new one. - -> -indev address Set input drive and load eventual ISO image. Switch from - growing to modifying. Same restrictions as with -dev - -> -outdev address Set output drive and switch from growing to modifying. ->>> (Do we need the restrictions as with -dev ? ->>> I.e. do we need to know that we are doing modification ->>> before we call isoburn_prepare_*() ? ) - --ban_stdio_write Allow for writing only the usage of optical drives. Disallow - to write the result into files of nearly arbitrary type. - Once set, this command cannot be revoked. - -Data manipulations: - -The following commands may depend on settings listed further below. -disk_path is a path to an object in the local filesystem tree. -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.) - -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. - -If the iso_rr_path of a newly inserted or renamed file leads to an existing -file object in the ISO image, then the following collision handling happens: -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 -overwrite decides. Directories may only be deleted by -commands -rmdir or -rm_r. - -The commands in this section alter the ISO image and not the local filesystem. - --add path [...] Insert the given files or directory trees from filesystem - into the ISO image. - Use the same paths on ISO unless -graft-points is set and - the paths have the form iso_rr_path=disk_path . - -> -path-list disk_path Like -add but read the pathspecs from file disk_path. - One pathspec per line. - -> -cp_r 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. +Emerging man page is now in text/xorriso.1 ( Needs enhancement in libisofs: -cut_out disk_path startbyte bytecount iso_rr_path @@ -279,273 +47,3 @@ The commands in this section alter the ISO image and not the local filesystem. cat /mnt/file_part1 /mnt/file_part2 > $HOME/file ) -> -rm iso_rr_path [...] Delete the given files from the ISO image. - -> -rm_r iso_rr_path [...] - Delete the given files or directory trees from the ISO image. - -> -mv 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. - -> -chown uid iso_rr_path [...] Equivalent to chown in the ISO image. -> -chgrp gid iso_rr_path [...] Equivalent to chgrp in the ISO image. -> -chmod mode iso_rr_path [...] Equivalent to chmod in the ISO image. - -> -alter_date 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. ->>> Can we set ctime ? Do we want to set ctime ? - -> -mkdir iso_rr_path [...] Create empty directories if they do not exist yet. - Existence as directory generates a WARNING event, existence as - other file is a SORRY. - -> -rmdir iso_rr_path [...] Delete empty directories. - --- Mark end of particular action argument list. - --rollback Discard the manipulated ISO image and reload it from indrive. - - -Writing the result: - --commit Perform the write operation. Eventually make the outdrive - the new indrive and load the image from there. Check wether - this is what is expected and eventually warn or abort. - 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. - --eject "in"|"out"|"all" Eject the media in -indev, resp. -outdev, resp. both - drives. - Note: It is not possible yet to effectively eject disk files. - -> -blank mode Blank media resp. invalidate ISO image on media. - This affects only the outdrive not the indrive. - 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, format - "fast" and "all" make CD-RW and unformatted DVD-RW re-usable - or de-format overwriteable DVD-RW. - "format" converts unformatted DVD-RW into overwriteable ones. - - -Settings for data insertion: - -RockRidge info will be generated by the program unconditionally. - --J Generate Joliet info additional to Rock Ridge info. - -> -f Follow symbolic links. - --uid uid User id to be used for all files when inserted into the - new ISO tree. --gid gid Group id for the same purpose. - --graft-points For xorriso action -add this enables pathspecs of the form - target=source like with mkisofs. - - -Settings for result writing: - -> -V volid Specifies the volume ID. (I assume libisofs can do that) - --speed 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 - If there is no hint about the speed unit attached, then the - media in the outdrive will decide. Default unit is CD = 176.4k. - -? -dummy "on"|"off" If "on" simulate burning or refuse with SORRY event if - no simulation is possible. - -> -fs 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. The number may be followed by letter "k" or"m" - which means unit is kiB (= 1024) or MiB (= 1024 kiB). - -? -close "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). - This is the contrary of cdrskin -multi. - - -Exception processing: - --abort_on severity Set the threshhold for events to abort the program. - Events are classified by severity : - "NEVER", "ABORT", "FATAL", "SORRY", "WARNING", "HINT", - "NOTE", "UPDATE", "DEBUG", "ALL" - Severities "NEVER" and "ALL" do not occur but mark the extreme - ends of this potentially expandable range. - It may become necessary to abort the program anyway, despite - the setting by this option. Expect not many "ABORT" events to - be ignorable. - --report_about severity Set the threshhold 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 threshhold of -abort_on . - - -> -overwrite "on"|"off" Allow or disallow to overwrite existing files in the - ISO image by a file with the same user defined name. This is - the RockRidge name and not the plain ISO name. - With setting "off", RR name collisions cause SORRY-events. - - -Dialog mode control: - --dialog "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. - --page len width Describe terminal to the text pager. - -? -use_readline "on"|"off" If "on" then use readline for dialog. Esle use - plain stdin. - -> -reassure "on"|"off" If "on" then ask the user for "y" or "n" with any file - before deleting or overwriting it in the ISO image. - - -Drive and media related inquiry actions: - --toc 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. - --devices Show list of available MMC drives. 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. - --print-size 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. - --tell_media_space Print available space on output media (minus already - foreseeable consumption by next -commit.) - - -Navigation in ISO image and disk filesystem: - -> -cd iso_rr_path Change the current working directory in the emerging ISO - image as it is at the moment. -> -cdx disk_path Change the current working directory on filesystem. - --pwd Tell the current working directory in the ISO image. --pwdx ... on local filesystem. - -> -ls pattern List files from the current working directory in the ISO - image which match a shell pattern. (I.e. wildcards '*' '?') -> -lsx pattern ... on local filesystem. - -> -ls_l pattern Equivalent for ls -l. -> -ls_lx pattern ... on filesystem. - -> -find pattern Equivalent to find . -name pattern in the ISO image. -> -findx pattern ... on filesystem. - - -Scripting, dialog and program control features: - --no_rc Only if used as first command line argument this option - prevents reading and interpretation of eventual startup - files. See section FILES below. - --help Print helptext. - --version Print program name and version. - --history textline Copy textline into libreadline history. - --status [mode|filter] Print the current settings. - Modes: - short... print only important or altered settings - long ... print settings even if they are default values - long_history like long plus history lines - 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. - -? -status_history_max maximum number of history lines to be reported with - -status "long_history". - --options_from_file fileaddress - Reads lines from fileaddress and executes them as dialog lines. - --print text Print a text to result channel. --prompt text Wait for the user to hit the Enter key resp. to send a line - via stdin. - --end End program immediately - -# 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. - - -Support for frontend programs talking into stdin and listening at stdout: - --pkt_output "on"|"off" Consolidate text output on stdout and classify each - line by a channel indicator: 'R:' for result lines, - 'I:' for notes and error messages, 'M:' for -mark texts. --logfile channel fileaddress Copy output of a channel to the given file. - --mark text If text is not empty it will get put out each time an - action has been completed. - --prog text Use text as this program's name in subsequent messages - --prog_help text Use text as this program's name and perform -help. - - -EXAMPLES - ->>> to come - - -FILES - -Startup files: - -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 -The files are read in the sequence given above, but none of them is required -for xorriso to function properly. - - -SEE ALSO - -For mounting xorriso generated ISO images - mount(8) - -Other programs which produce ISO images - mkisofs(8), genisoimage(8) - -Other programs which burn images to optical media - growisofs(1), cdrecord(1), wodim(1), cdrskin(1) - - -AUTHOR - -xorriso is not written at all. -This man page was written by Thomas Schmitt . - -