New options -mount and -mount_cmd

libisoburn/trunk/xorriso/xorriso.1

@@ -2,7 +2,7 @@
 .\" 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 "Nov 28, 2008"
+.TH XORRISO 1 "Dec 05, 2008"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -547,7 +547,8 @@ address. The following entities are defined:
 .br
 "lba" or "sbsector" with a number as of a line "ISO ...", column "sbsector".
 .br
-"volid" with a text as of a line "ISO ...", column "Volume Id".
+"volid" with a search pattern for a text as of a line "ISO ...",
+column "Volume Id".
 .br
 Adressing a non-existing entity or one which does not represent an ISO
 image will either abandon -indev or at least lead to a blank image.
@@ -1791,6 +1792,34 @@ to be the most recent real session then.
 Some read-only drives and media show no usable session history at all.
 Eventually option -rom_toc_scan might help.
 .TP
+\fB\-mount_cmd\fR drive entity id command_form
+Print to the result channel an appropriate command line for mounting the
+ISO session which is depicted by drive, entity and id. The id can be a block
+address with entity "sbsector", a track number with "track", a session number
+with "session", a volume id search pattern with "volid", or any text with
+"auto". See also option -load.
+.br
+drive can be "indev", "outdev" or the address of a not yet aquired drive.
+Prefix "stdio:" for non MMC drives is not mandatory.
+.br
+command_form is either "linux:"path , or "freebsd:"path, or "shell:"command,
+or a path.
+The path will be used as moint point and has already to exist as directory.
+A command line with suitable options is then generated.
+If no recognizable prefix is given then xorriso guesses on which kind of
+system it runs and uses the whole command_form as path.
+.br
+If shell:command is given, then xorriso will substitute in the command text
+the following parameter names:
+.br
+"%device%" will be substituted by the mountable device path of the drive
+address.
+.br
+"%sbsector%" will be substituted by the session start sector.
+.br
+"%track%", "%session%", "%volid%" will be substituted by track number,
+session number, resp. volume id of the depicted session.
+.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
@@ -2168,6 +2197,14 @@ Read the content of a ISO data file and write it into a data file on disk
 beginning at the byte_offset. Write at most byte_count bytes.
 This is the inverse of option -cut_out.
 .TP
+\fB\-mount\fR drive entity id command_form
+Produce the same line as -mount_cmd and then execute it as shell command
+after giving up the depicted drive.
+This demands -osirrox to be enabled and normally will succeed only for the
+superuser. For safety reasons it will refuse to execute the command line
+if it stems from command_form shell:command or if setuid or setgid are in
+effect. In these cases -mount will default to -mount_cmd and a SORRY event.
+.TP
 .B Command compatibility emulations:
 .PP
 Writing of ISO 9660 on CD is traditionally done by program mkisofs
@@ -2499,14 +2536,27 @@ which shall be able to use the drives with xorriso.
 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.
+Aquire drive /dev/sr2, make media ready for writing a new image,
+fill the image with the files from hard disk directories /home/me/sounds
+and /home/me/pictures.
+.br
+Because no -dialog "on" is given, the program will then end by writing the
+session to media.
+.br
+\fB$\fR xorriso -outdev /dev/sr2 \\
+.br
+ -blank as_needed \\
+.br
+ -map /home/me/sounds /sounds \\
+.br
+ -map /home/me/pictures /pictures
+.br
+
+.br
+The ISO image may be shaped in a more elaborate way like the following:
 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 cd /home/me
 .br
 \fB$\fR xorriso -outdev /dev/sr2 \\
@@ -2790,13 +2840,20 @@ This makes sense if the full backup leaves substantial remaining capacity
 on media and if the expected changes are much smaller than the full backup.
 An update run will probably save no time but last longer than a full backup.
 .br 
-With \fBmount\fR option -o \fB"sbsector="\fR on Linux resp. \fB-s\fR on FreeBSD
+With \fBmount\fR option \fB-o "sbsector="\fR on Linux resp. \fB-s\fR on FreeBSD
 it is possible to access the session trees which represent the older backup
 versions. With CD media, Linux mount accepts session numbers directly by
 its option "session=".
 .br
 Multi-session media and most overwriteable media written by xorriso can tell
 the sbsectors of their sessions by xorriso option -toc.
+Used after -commit the following option prints the matching mount command for
+the newly written session (here for mount point /mnt):
+.br
+ -mount_cmd "indev" "auto" "auto" /mnt
+.br
+Options -mount_cmd and -mount are also able to produce the mount commands for
+older sessions in the table-of-content.
 .br
 Sessions on multi-session media are separated by several MB of unused blocks.
 So with small sessions the payload capacity can become substantially lower
@@ -2821,7 +2878,7 @@ First check which backup sessions are on the media:
 Then load the desired session and copy the file trees to disk.
 Avoid to eventually create /home/thomas/restored without rwx-permission.
 .br
-\fB$\fR xorriso -load volid PROJECTS_MAIL_2008_06_19_205956 \\
+\fB$\fR xorriso -load volid 'PROJECTS_MAIL_2008_06_19*' \\
 .br
  -indev /dev/sr0 \\
 .br