6 files changed, 299 insertions, 11 deletions
diff --git a/man/man1/attr.1 b/man/man1/attr.1
index 9c1d905..ab555f1 100644
--- a/man/man1/attr.1
+++ b/man/man1/attr.1
@@ -3,12 +3,14 @@
 attr \- extended attributes on XFS filesystem objects
 .SH SYNOPSIS
 .nf
-\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-s attrname\f1 [ \f3\-V attrvalue\f1 ] \c
+\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-s attrname\f1 [ \f3\-V attrvalue\f1 ] \c
 \f3pathname\f1
 .sp .8v
-\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-g attrname pathname\f1
+\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-g attrname pathname\f1
 .sp .8v
-\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-r attrname pathname\f1
+\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-r attrname pathname\f1
+.sp .8v
+\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-l pathname\f1
 .sp .8v
 .fi
 .SH OVERVIEW
@@ -84,6 +86,18 @@ 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
@@ -131,6 +145,12 @@ attribute namespace rather that the
 .I USER
 attribute namespace.
 .PP
+The
+.B \-S
+option is similar, except it specifies use of the
+.I security
+attribute namespace.
+.PP
 When the
 .B \-q
 option is given
diff --git a/man/man3/attr_get.3 b/man/man3/attr_get.3
index 2f97f8d..c0ab084 100644
--- a/man/man3/attr_get.3
+++ b/man/man3/attr_get.3
@@ -2,6 +2,7 @@
 .SH NAME
 attr_get, attr_getf \- get the value of a user attribute of a filesystem object
 .SH C SYNOPSIS
+.PP
 .sp
 .nf
 .B #include <attr/attributes.h>
@@ -20,7 +21,7 @@ and
 functions provide a way to retrieve the value of an attribute.
 .P
 .I Path\^
-points to a path name for a filesystem object, and 
+points to a path name for a filesystem object, and
 .I fd\^
 refers to the file descriptor associated with a file.
 If the attribute
@@ -32,7 +33,7 @@ The
 .I valuelength
 argument is an input/output argument that on the call to
 .B attr_get
-should contain the maximum size of attribute value the 
+should contain the maximum size of attribute value the
 process is willing to accept.
 On return, the
 .I valuelength
@@ -171,6 +172,7 @@ On success, zero is returned.  On error, \-1 is returned, and
 is set appropriately.
 .SH "SEE ALSO"
 .BR attr (1),
+.BR attr_list (3),
 .BR attr_multi (3),
 .BR attr_remove (3),
 and
diff --git a/man/man3/attr_list.3 b/man/man3/attr_list.3
index e69de29..79013be 100644
--- a/man/man3/attr_list.3
+++ b/man/man3/attr_list.3
@@ -0,0 +1,263 @@
+.TH ATTR_LIST 3 "Extended Attributes" "Dec 2005" "XFS Compatibility API"
+.SH NAME
+attr_list, attr_listf \- list the names of the user attributes of a filesystem object
+.SH C SYNOPSIS
+.PP
+.sp
+.nf
+.B #include <sys/attributes.h>
+.sp
+.B "int attr_list (const char \(**path, char \(**buffer, "
+.B "               const int buffersize, int flags,"
+.B "               attrlist_cursor_t \(**cursor);"
+.PP
+.B "int attr_listf (int fd, char \(**buffer, "
+.B "                const int buffersize, int flags,"
+.B "                attrlist_cursor_t \(**cursor);"
+.Op
+.SH DESCRIPTION
+The
+.B attr_list
+and
+.B attr_listf
+functions provide a way to list the existing attributes of a
+filesystem object.
+.P
+.I Path\^
+points to a path name for a filesystem object, and
+.I fd\^
+refers to the file descriptor associated with a file.
+The
+.I buffer
+will be filled with a structure describing at least a portion of the
+attributes associated with the given filesystem object.
+.I Buffer
+will be overwritten with an \f4attrlist_t\fP structure
+containing a list of the attributes associated with
+that filesystem object, up to a maximum of
+.I buffersize
+bytes.
+The
+.I buffer
+must be sufficiently large to hold the appropriate data structures
+plus at least one maximally sized attribute name,
+but cannot be more than ATTR_MAX_VALUELEN (currently 64KB) bytes in length.
+.PP
+.Op c p a
+The contents of an \f4attrlist_t\fP structure include the following members:
+.P
+.RS 3
+.nf
+.ft 4
+.ta 9n 22n
+__int32_t al_count; /\(** number of entries in attrlist \(**/
+__int32_t al_more; /\(** T/F: more attrs (do syscall again) \(**/
+__int32_t al_offset[1]; /\(** byte offsets of attrs [var-sized] \(**/
+.ft 1
+.fi
+.RE
+.PP
+The
+.I al_count
+field shows the number of attributes represented in this buffer,
+which is also the number of elements in the
+.I al_offset
+array.
+The
+.I al_more
+field will be non-zero if another
+.B attr_list
+call would result in more attributes.
+The
+.I al_offset
+array contains the byte offset within the
+.I buffer
+of the structure describing each of the attributes,
+an \f4attrlist_ent_t\fP structure.
+The \f4ATTR_ENTRY(buffer, index)\fP macro will help with decoding the list.
+It takes a pointer to the
+.I buffer
+and an
+.I index
+into the
+.I al_offset
+array and returns a pointer to the corresponding
+\f4attrlist_ent_t\fP structure.
+.PP
+The contents of an \f4attrlist_ent_t\fP structure
+include the following members:
+.P
+.RS 3
+.nf
+.ft 4
+.ta 9n 22n
+u_int32_t a_valuelen; /\(** number bytes in value of attr \(**/
+char a_name[]; /\(** attr name (NULL terminated) \(**/
+.ft 1
+.fi
+.Op
+.RE
+.PP
+The
+.I a_valuelen
+field shows the size in bytes of the value
+associated with the attribute whose name is stored in the
+.I a_name
+field.
+The name is a NULL terminated string.
+.PP
+Note that the value of the attribute cannot be obtained through
+this interface, the
+.B attr_get
+call should be used to get the value.
+The
+.B attr_list
+interface tells the calling process how large of a buffer
+it must have in order to get the attribute\'s value.
+.PP
+The
+.I flags
+argument can contain the following symbols bitwise OR\'ed together:
+.TP
+.SM
+\%ATTR_ROOT
+List the attributes that are in the
+.B root
+address space, not in the
+.B user
+address space.
+(limited to use by super-user only)
+.TP
+.SM
+\%ATTR_DONTFOLLOW
+Do not follow symbolic links when resolving a
+.I path
+on an
+.B attr_list
+function call.
+The default is to follow symbolic links.
+.PP
+The
+.I cursor
+argument is a pointer to an opaque data structure that the kernel uses
+to track the calling process\'s position in the attribute list.
+The only valid operations on a
+.I cursor
+are to pass it into an
+.B attr_list
+function call or to zero it out.
+It should be zero\'ed out before the first
+.B attr_list
+call.
+Note that multi-threaded applications may keep more than one
+.I cursor
+in order to serve multiple contexts, ie: the
+.B attr_list
+call is "thread-safe".
+.PP
+.B attr_list
+will fail if one or more of the following are true:
+.TP 17
+.SM
+\%[ENOENT]
+The named file does not exist.
+.TP
+.SM
+\%[EPERM]
+The effective user
+.SM ID
+does not match the owner of the file
+and the effective user
+.SM ID
+is not super-user.
+.TP
+.SM
+\%[ENOTDIR]
+A component of the
+path prefix
+is not a directory.
+.TP
+.SM
+\%[EACCES]
+Search permission is denied on a
+component of the
+path prefix.
+.TP
+.SM
+\%[EINVAL]
+A bit was set in the
+.I flag
+argument that is not defined for this system call,
+or the buffer was too small or too large.
+.TP
+.SM
+\%[EFAULT]
+Either
+.I Path
+or
+.I buffer
+points outside the allocated address space of the process, or
+.I buffer
+or
+.I bufsize
+are not 32bit aligned.
+.TP
+.SM
+\%[ELOOP]
+A path name lookup involved too many symbolic links.
+.TP
+.SM
+\%[ENAMETOOLONG]
+The length of
+.I path
+exceeds
+.SM
+.RI { MAXPATHLEN },
+or a pathname component is longer than
+.SM
+.RI { MAXNAMELEN }.
+.TP
+.SM
+\%[ENOATTR]
+.I attribute\^
+does not exist for this file.
+.PP
+.B attr_listf\^
+will fail if:
+.TP 15
+.SM
+\%[EINVAL]
+A bit was set in the
+.I flag
+argument that is not defined for this system call, or
+.I fd\^
+refers to a socket, not a file,
+or the buffer was too small or too large.
+.TP
+.SM
+\%[EFAULT]
+Either
+.I Path
+or
+.I buffer
+points outside the allocated address space of the process, or
+.I buffer
+or
+.I bufsize
+are not 32bit aligned.
+.TP
+.SM
+\%[EBADF]
+.I Fd\^
+does not refer to a valid descriptor.
+.SH "DIAGNOSTICS"
+Upon successful completion, a value of 0 is returned.
+Otherwise, a value of \-1 is returned and
+.I errno\^
+is set to indicate the error.
+.SH "SEE ALSO"
+.BR attr (1),
+.BR attr_multi (3),
+.BR attr_remove (3),
+and
+.BR attr_set (3).
diff --git a/man/man3/attr_multi.3 b/man/man3/attr_multi.3
index aee9072..ed30869 100644
--- a/man/man3/attr_multi.3
+++ b/man/man3/attr_multi.3
@@ -22,10 +22,10 @@ functions provide a way to operate on multiple attributes of a
 filesystem object at once.
 .P
 .I Path
-points to a path name for a filesystem object, and 
+points to a path name for a filesystem object, and
 .I fd
 refers to the file descriptor associated with a file.
-The 
+The
 .I oplist
 is an array of \f4attr_multiop_t\fP structures.
 Each element in that array describes a single attribute operation
@@ -133,7 +133,7 @@ If the process has appropriate priviledges,
 the ROOT namespace will be searched for the named attribute,
 otherwise the USER namespace will be searched.
 The \f4ATTR_CREATE\fP and the \f4ATTR_REPLACE\fP flags
-may also be set in the 
+may also be set in the
 .I am_flags
 field (but not simultaneously).
 If the \f4ATTR_CREATE\fP flag is set,
@@ -257,7 +257,7 @@ is set appropriately.
 Note that the individual operations listed in the
 .I oplist
 array each have their own error return fields.
-The 
+The
 .I errno
 variable only records the result of the
 .I attr_multi
@@ -265,6 +265,7 @@ call itself, not the result of any of the sub-operations.
 .SH "SEE ALSO"
 .BR attr (1),
 .BR attr_get (3),
+.BR attr_list (3),
 .BR attr_remove (3),
 and
 .BR attr_set (3).
diff --git a/man/man3/attr_remove.3 b/man/man3/attr_remove.3
index 9068e11..90fbb72 100644
--- a/man/man3/attr_remove.3
+++ b/man/man3/attr_remove.3
@@ -20,7 +20,7 @@ functions provide a way to remove previously created attributes
 from filesystem objects.
 .P
 .I Path\^
-points to a path name for a filesystem object, and 
+points to a path name for a filesystem object, and
 .I fd\^
 refers to the file descriptor associated with a file.
 If the attribute
@@ -143,6 +143,7 @@ is set appropriately.
 .SH "SEE ALSO"
 .BR attr (1),
 .BR attr_get (3),
+.BR attr_list (3),
 .BR attr_multi (3),
 and
 .BR attr_set (3).
diff --git a/man/man3/attr_set.3 b/man/man3/attr_set.3
index 63c6b7e..9637700 100644
--- a/man/man3/attr_set.3
+++ b/man/man3/attr_set.3
@@ -23,7 +23,7 @@ and
 functions provide a way to create attributes and set/change their values.
 .P
 .I Path\^
-points to a path name for a filesystem object, and 
+points to a path name for a filesystem object, and
 .I fd\^
 refers to the file descriptor associated with a file.
 If the attribute
@@ -203,6 +203,7 @@ is set appropriately.
 .SH "SEE ALSO"
 .BR attr (1),
 .BR attr_get (3),
+.BR attr_list (3),
 .BR attr_multi (3),
 and
 .BR attr_remove (3).