Merge of xfs-cmds-2.4.18:slinx:111138a by nathans.

  bump to version 2.0.0 for extended attribute and other interface changes.
  incorporate new code, docs, etc from ext2/ext3 project.

3 files changed, 232 insertions, 33 deletions

diff --git a/man/man1/attr.1 b/man/man1/attr.1
index bf6cbbe..9c1d905 100644
--- a/man/man1/attr.1
+++ b/man/man1/attr.1
@@ -1,6 +1,6 @@
-.TH attr 1
+.TH ATTR 1 "Extended Attributes" "Dec 2001" "XFS Compatibility API"
 .SH NAME
-attr \- manipulate Extended Attributes on filesystem objects
+attr \- extended attributes on XFS filesystem objects
 .SH SYNOPSIS
 .nf
 \f3attr\f1 [ \f3\-LRq\f1 ] \f3\-s attrname\f1 [ \f3\-V attrvalue\f1 ] \c
@@ -10,33 +10,40 @@ attr \- manipulate Extended Attributes on filesystem objects
 .sp .8v
 \f3attr\f1 [ \f3\-LRq\f1 ] \f3\-r attrname pathname\f1
 .sp .8v
-\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-l pathname\f1
-.sp .8v
 .fi
 .SH OVERVIEW
-Extended Attributes implement the ability for a user to attach
-name/value pairs to objects within the filesystem.
+Extended attributes implement the ability for a user to attach
+name:value pairs to objects within the XFS filesystem.
 .P
 They could be used to store meta-information about the file.
 For example "character-set=kanji" could tell a document browser to
 use the Kanji character set when displaying that document
 and "thumbnail=..." could provide a reduced resolution overview of a
 high resolution graphic image.
+.PP
+This document describes the
+.I attr
+command, which is mostly compatible with the IRIX command of the same name.
+It is thus aimed specifically at users of the XFS filesystem - for
+filesystem independent extended attribute manipulation, consult the
+.IR getfattr (1)
+and 
+.IR setfattr (1)
+documentation.
 .P
-The
+In the XFS filesystem, the
 .I names
 can be up to 256 bytes in length, terminated by the first 0 byte.
 The intent is that they be printable ASCII (or other character set)
 names for the attribute.
-.P
 The
 .I values
-can be up to 256KB of arbitrary binary data.
+can be up to 64KB of arbitrary binary data.
 .P
-Attributes can be attached to all types of inodes:
+Attributes can be attached to all types of XFS inodes:
 regular files, directories, symbolic links, device nodes, etc.
 .P
-There are 2 disjoint attribute name spaces associated with every
+XFS uses 2 disjoint attribute name spaces associated with every
 filesystem object.
 They are the
 .B root
@@ -58,7 +65,7 @@ the value of attributes on any particular file.
 .SH DESCRIPTION
 The
 .I attr
-utility allows the manipulation of Extended Attributes associated with
+utility allows the manipulation of extended attributes associated with
 filesystem objects from within shell scripts.
 .PP
 There are four main operations that
@@ -77,18 +84,6 @@ With the
 flag, \f4stdout\fP will be exactly and only the value of the attribute,
 suitable for storage directly into a file or processing via a piped command.
 .TP
-.B LIST
-The
-.B \-l
-option tells
-.I attr
-to list the names of all the attributes that are associated with the object,
-and the number of bytes in the value of each of those attributes.
-With the
-.B \-q
-flag, \f4stdout\fP will be a simple list of only the attribute names,
-one per line, suitable for input into a script.
-.TP
 .B REMOVE
 The
 .B \-r attrname
@@ -148,17 +143,21 @@ The standard file interchange/archive programs
 .IR tar (1),
 and
 .IR cpio (1)
-will not archive or restore Extended Attributes,
+will not archive or restore extended attributes,
 while the
 .IR xfsdump (8)
 program will.
+.SH "CAVEATS"
+The list option present in the IRIX version of this command is not supported.
+.I getfattr
+provides a mechanism to retrieve all of the attribute names.
 .SH "SEE ALSO"
-attr_get(2), attr_getf(2),
-attr_list(2), attr_listf(2),
-attr_multi(2), attr_multif(2),
-attr_remove(2), attr_removef(2),
-attr_set(2), attr_setf(2),
+getfattr(1),
+setfattr(1),
+attr_get(3),
+attr_set(3),
+attr_multi(3),
+attr_remove(3),
+attr(5),
+and
 xfsdump(8).
-.SH BUGS
-The extended attributes system call used by this program is
-experimental and is currently only supported by the XFS filesystem.
diff --git a/man/man1/getfattr.1 b/man/man1/getfattr.1
new file mode 100644
index 0000000..7b3ea66
--- /dev/null
+++ b/man/man1/getfattr.1
@@ -0,0 +1,129 @@
+.TH GETFATTR 1 "Extended Attributes" "Dec 2001" "File Utilities"
+.SH NAME
+getfattr, aget \- get extended attributes of filesystem objects
+.SH SYNOPSIS
+.nf
+\f3getfattr\f1 [\f3\-lvR5LP\f1] \f3\-n name\f1 [\f3\-e en\f1] \c
+\f3pathname\f1...
+\f3getfattr\f1 [\f3\-lvR5LP\f1] \f3\-d\f1 [\f3\-e en\f1] \c
+[\f3\-s\f1 | \f3\-r regex\f1] \f3pathname\f1...
+\f3getfattr\f1 [\f3\-Vh\f1]
+.fi
+.SH DESCRIPTION
+For each file,
+.B getfattr
+displays the file name,
+and the set of extended attribute names (and optionally values) which
+are associated with that file.
+.PP
+.B aget
+is exactly the same as
+.BR getfattr ,
+and is installed for compatibility purposes.
+.PP
+The output format of
+.B "getfattr \-ds"
+is as follows:
+.fam C
+.RS
+.nf
+ 1:  # file: somedir/
+ 2:  user.name0="value0"
+ 3:  system.name0="value1"
+ 4:  user.name1="value2"
+ 5:  ...
+.fi
+.RE
+.fam T
+.PP
+Line 1 identifies the file name for which the
+following lines are being reported.
+The remaining lines (lines 2 to 4 above) show the
+.I name
+and 
+.I value
+pairs associated with the specified file.
+.SS OPTIONS
+.TP 4
+.I \-n name
+Dump the value of the named extended attribute extended attribute.
+.TP
+.I \-a
+Absolute names \- suppress the stripping of leading '/' from an absolute
+.IR pathname .
+.TP
+.I \-d
+Dump the values of all extended attributes associated with
+.IR pathname .
+.TP
+.I \-e en
+Encode values after retrieving them.
+Valid values of
+.I en
+are "text", "hex", and "base64".
+.TP
+.I \-l
+Do not follow symlinks - if
+.I pathname
+is a symbolic link, it is not followed, but is instead itself the
+inode being examined.
+.TP
+.I \-r
+.I regex
+is a regular expression pattern to apply to the set of extended
+attribute names being returned.
+It defaults to "^user\\." if no
+.I \-r
+is specified, which causes
+.B getfattr
+to operate on only extended attributes from the user namespace.
+.TP
+.I \-s
+Dump out both the "user" and "system" namespaces.
+Refer to
+.BR attr (5)
+for a more detailed discussion on namespaces.
+This option is useful for backing up extended attributes in a filesystem
+independent manner.
+It is implemented using a regular expression ("^user\\.|^system\\.")
+and so cannot be used in conjunction with the
+.I \-r
+option described earlier.
+.TP
+.I \-v
+Dump out the extended attribute value(s) only.
+.TP
+.I \-R
+Recurse into subdirectories, dumping extended attributes for each file
+encountered (breadth first).
+.TP
+.I \-5
+Same as \-R, except done in post-order (depth first).
+.TP
+.I \-L
+Refines the \-R or \-5 option - "logical walk" (do follow symbolic links).
+.TP
+.I \-P
+Refines the \-R or \-5 option - "physical walk" (do not follow symbolic links).
+.TP
+.I \-V
+Print the version of
+.B getfattr
+and exit.
+.TP
+.I \-h
+Print help explaining the command line options.
+.TP
+.I \-\-
+End of command line options.
+All remaining parameters are interpreted as file names, even if they
+start with a dash character.
+.SH AUTHOR
+Andreas Gruenbacher,
+.RI < a.gruenbacher@computer.org >
+and the SGI XFS development team,
+.RI < linux-xfs@oss.sgi.com >.
+.P
+Please send your bug reports or comments to these addresses.
+.SH "SEE ALSO"
+setfattr(1), and attr(5).
diff --git a/man/man1/setfattr.1 b/man/man1/setfattr.1
new file mode 100644
index 0000000..6b71d2a
--- /dev/null
+++ b/man/man1/setfattr.1
@@ -0,0 +1,71 @@
+.TH SETFATTR 1 "Extended Attributes" "Dec 2001" "File Utilities"
+.SH NAME
+setfattr, aset \- set extended attributes of filesystem objects
+.SH SYNOPSIS
+.nf
+\f3setfattr\f1 [\f3\-l\f1] \f3\-n name\f1 [\f3\-v value\f1] \f3pathname\f1...
+\f3setfattr\f1 [\f3\-l\f1] \f3\-x name\f1 \f3pathname\f1...
+\f3setfattr\f1 [\f3\-l\f1] \f3\-B file\f1
+\f3setfattr\f1 [\f3\-Vh\f1]
+.fi
+.SH DESCRIPTION
+The 
+.B setfattr
+command is used to associate a new
+.I value
+with an extended attribute
+.IR name
+for each specified file.
+.PP
+.B aset
+is exactly the same as
+.BR setfattr ,
+and is installed for compatibility purposes.
+.SS OPTIONS
+.TP 4
+.I \-n name
+Set the value of the named extended attribute extended attribute.
+.TP
+.I \-l
+Do not follow symlinks - if
+.I pathname
+is a symbolic link, it is not followed, but is instead itself the
+inode being modified.
+.TP
+.I \-x
+Remove the named extended attribute entirely.
+.TP
+.I \-v
+Specifies the new value for the named extended attribute.
+.TP
+.I \-B
+Restores extended attributes using values from the specified file.
+The file must be in the format generated by the
+.B getfattr
+command (\-sdlR options).
+The file name
+.I \-
+may be used in conjunction with this option, to specify the
+standard input stream to be used rather than a named file.
+.TP
+.I \-V
+Print the version of
+.B setfattr
+and exit.
+.TP
+.I \-h
+Print help explaining the command line options.
+.TP
+.I \-\-
+End of command line options.
+All remaining parameters are interpreted as file names, even if they
+start with a dash character.
+.SH AUTHOR
+Andreas Gruenbacher,
+.RI < a.gruenbacher@computer.org >
+and the SGI XFS development team,
+.RI < linux-xfs@oss.sgi.com >.
+.P
+Please send your bug reports or comments to these addresses.
+.SH "SEE ALSO"
+getfattr(1), and attr(5).