Updated xorriso man page

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 "Feb 02, 2008"
+.TH XORRISO 1 "Feb 12, 2008"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -83,7 +83,7 @@ Creating, Growing, Modifying, Blind Growing
 .br
 Libburn drives
 .br
-Rock Ridge, POSIX, X/Open, and El Torito
+Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
 .br
 Command processing
 .br
@@ -346,7 +346,7 @@ One may prepend "mmc:" to a path to surely disallow any automatic "stdio:".
 By option -drive_class one may ban certain paths or allow access without
 prefix "stdio:" to other paths.
 .SS
-.B Rock Ridge, POSIX, X/Open, and El Torito:
+.B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
 .br
 .B Rock Ridge
 is the name of a set of additional informations which enhance
@@ -381,6 +381,34 @@ bears the isohybrid signature of ISOLINUX 3.72 or later. It will occupy the
 first 512 bytes of the emerging ISO image and enable booting from media which
 appear as hard disk rather than as CDROM. An MBR does not hamper CDROM booting.
 The MBR of a follow-up session can get in effect only on overwriteable media.
+.PP
+.B ACL
+are an advanced way of controlling access permissions to file objects. Neither
+ISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs has
+introduced a standard conformant extension named AAIP for that purpose.
+It uses this extension if enabled by option -acl.
+.br
+AAIP enhanced images are supposed to be mountable normally, but one cannot
+expect that the mounted filesystem will show and respect the eventual ACLs.
+For now, only xorriso is able to retrieve those ACLs. It can bring them into
+effect when files get restored to an ACL enabled file system or it can
+print them in a format suitable for tool setfacl.
+.br
+Files with ACL show as group permissions the setting of entry "mask::" if
+that entry exists. Nevertheless the non-listed group members get handled
+according to entry "group::". xorriso brings "group::" into effect before
+eventually removing the ACL from a file.
+.PP
+.B xattr
+are pairs of name and value which can be attached to file objects. AAIP is
+able to represent them and xorriso allows to record and restore pairs which
+have names out of the user namespace. I.e. those which begin with "user.",
+like "user.x" or "user.whatever". Value can be any string which does
+not exceed the size of 4095 characters. xattr processing happens only if
+it is enabled by option -xattr.
+.br
+As with ACL, currently only xorriso is able to retrieve xattr from AAIP
+enhanced images and to restore them to xattr capable file systems.
 .SS
 .B Command processing:
 .br
@@ -531,7 +559,7 @@ apply. See above paragraph "Libburn drives".
 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\-drive_class\fR "harmless"|"banned"|"risky"|"clear_list" disk_pattern
+\fB\-drive_class\fR "harmless"|"banned"|"caution"|"clear_list" disk_pattern
 Add a drive path pattern to one of the safety lists or make those lists empty.
 There are three lists defined which get tested in the following sequence:
 .br
@@ -543,7 +571,7 @@ Else if the path matches the "banned" list then the drive will not be
 accepted by xorriso but rather lead to a FAILURE event. This list is empty by
 default.
 .br
-Else if the path matches the "risky" list and if it is not a MMC device,
+Else if the path matches the "caution" list and if it is not a MMC device,
 then its address must have the prefix "stdio:" or it will be rejected.
 This list has by default one entry: "/dev".
 .br
@@ -554,8 +582,8 @@ A path matches a list if one of its parent paths or itself matches a list
 entry. An eventual address prefix "stdio:" or "mmc:" will be ignored when
 testing for matches.
 .br
-By pseudo-class "clear_list" and pseudo-patterns "banned", "risky", "harmless",
+By pseudo-class "clear_list" and pseudo-patterns "banned", "caution",
-or "all", the lists may be made empty.
+"harmless", or "all", the lists may be made empty.
 .br
 E.g.: -drive_class clear_list banned
 .br
@@ -636,7 +664,7 @@ Enable or disable processing of XFS style Extended Attributes. These are
 pairs of name and value. The names are 0-terminated strings. Values can
 be arbitrary binary data.
 If enabled, then xorriso will import and export xattr similar to ACL.
-See also option -getfattr.
+See also options -getfattr, -setfattr.
 .TP
 \fB\-rom_toc_scan\fR "on"|"off"[:"emul_on"|"emul_off"]
 Read-only drives do not tell the actual media type but show any media as
@@ -980,6 +1008,19 @@ ownership, group and ACL of the given files.
 Since -getfacl and getfacl strip leading "/" from file paths, the setting of
 -cd does always matter.
 .TP
+\fB\-setfattr\fR [-]name value iso_rr_path [***]
+Attach the given xattr pair of name and value to the given iso_rr_paths.
+If the given name is prefixed by "-", then the pair with that name gets
+removed from the xattr list. If name is "--remove-all" then the whole xattr
+list of the given iso_rr_paths is deleted. In case of deletion, value must
+be an empty text.
+.br
+Only names from the user namespace are allowed. I.e. a name has to begin with
+"user.", like "user.x" or "user.whatever".
+.TP
+\fB\-setfattr_r\fR [-]name value iso_rr_path [***]
+Like -setfattr but affecting all files below eventual directories.
+.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,
@@ -1160,6 +1201,12 @@ E.g.:
 .br
   -find / -has_xattr -exec getfattr
 .br
+"setfattr" sets or deletes xattr name value pairs.
+.br
+E.g.:
+.br
+  -find / -has_xattr -exec setfattr --remove-all ''
+.br
 "find" performs another run of -find on the matching file address. It accepts
 the same params as -find, except iso_rr_path.
 E.g.:
@@ -2314,7 +2361,7 @@ handled like any other ISO image directory.
 Option "auto_chmod_off" is default. If "auto_chmod_on" is set then access
 restrictions for disk directories get circumvented if those directories
 are owned by the effective user who runs xorriso. This happens by temporarily
-granting rwx permission to the owner. It will not work with ACL restrictions.
+granting rwx permission to the owner.
 .TP
 \fB\-extract\fR iso_rr_path disk_path
 Restore the file objects at and underneath iso_rr_path to their corresponding
@@ -2403,7 +2450,7 @@ of commands which in said programs trigger comparable actions.
 .TP
 \fB\-as\fR personality option [options] --
 .br
-Perform its variable length option list as sparse emulation of the program
+Perform the variable length option list as sparse emulation of the program
 depicted by the personality word.
 .br
 
@@ -2440,8 +2487,9 @@ Writing to stdout is possible only if -as "mkisofs" was among the start
 arguments or if other start arguments pointed the output drive to
 standard output.
 .br
-Not original mkisofs options are --quoted_path_list (see -quoted_path_list)
+Not original mkisofs options are --quoted_path_list (see -quoted_path_list),
-and isolinux_mbr= (see -boot_image isolinux isohybrid=).
+isolinux_mbr= (see -boot_image isolinux isohybrid=), --acl (see -acl "on"),
+--xattr (see -xattr "on").
 .br
 Personalites "\fBxorrisofs\fR", "\fBgenisoimage\fR", and "\fBgenisofs\fR"
 are aliases for "mkisofs".
@@ -3154,6 +3202,12 @@ Other programs which burn sessions to optical media
 .BR cdrecord(1),
 .BR wodim(1),
 .BR cdrskin(1) 
+.TP
+ACL and xattr
+.BR getfacl(1),
+.BR setfacl(1),
+.BR getfattr(1),
+.BR setfattr(1)
 .br
 .SH AUTHOR
 Thomas Schmitt <scdbackup@gmx.net>