1 files changed, 137 insertions, 0 deletions
diff --git a/man/man2/listxattr.2 b/man/man2/listxattr.2
new file mode 100644
index 0000000..b1bf578
--- /dev/null
+++ b/man/man2/listxattr.2
@@ -0,0 +1,137 @@
+.\"
+.\" Extended attributes system calls manual pages
+.\"
+.\" (C) Andreas Gruenbacher, February 2001
+.\" (C) Silicon Graphics Inc, September 2001
+.\"
+.TH LISTXATTR 2 "Extended Attributes" "Dec 2001" "System calls"
+.SH NAME
+listxattr, llistxattr, flistxattr \- list extended attribute names
+.SH SYNOPSIS
+.fam C
+.nf
+.B #include <attr/xattr.h>
+.sp
+.BI "ssize_t listxattr (const char\ *" path ",
+.BI "\t\t\t\t char\ *" list ", size_t " size );
+.BI "ssize_t llistxattr (const char\ *" path ",
+.BI "\t\t\t\t char\ *" list ", size_t " size );
+.BI "ssize_t flistxattr (int " filedes ",
+.BI "\t\t\t\t char\ *" list ", size_t " size );
+.fi
+.fam T
+.SH DESCRIPTION
+Extended attributes are name:value
+pairs associated with inodes (files, directories, symlinks, etc).
+They are extensions to the normal attributes which are associated
+with all inodes in the system (i.e. the
+.BR stat (2)
+data).
+A complete overview of extended attributes concepts can be found in
+.BR attr (5).
+.PP
+.B listxattr
+retrieves the
+.I list
+of extended attribute names associated with the given
+.I path
+in the filesystem.
+The list is the set of (NULL-terminated) names, one after the other.
+The length of the attribute name
+.I list
+is returned.
+.PP
+.B llistxattr
+is identical to 
+.BR listxattr ,
+except in the case of a symbolic link, where the list of names of
+extended attributes associated with the link itself is retrieved,
+not the file that it refers to.
+.PP
+.B flistxattr
+is identical to
+.BR listxattr ,
+only the open file pointed to by
+.I filedes
+(as returned by
+.BR open (2))
+is interrogated in place of
+.IR path .
+.PP
+A single extended attribute
+.I name
+is a simple NULL-terminated string.
+The name includes a namespace prefix \- there may be several, disjoint
+namespaces associated with an individual inode.
+.PP
+An empty buffer of
+.I size
+zero can be passed into these calls to return the current size of the
+list of extended attribute names, which can be used to estimate the
+size of a buffer which is sufficiently large to hold the list of names.
+.PP
+The interface is designed to allow guessing of initial buffer
+sizes, and to enlarge buffers when the return value indicates
+that the buffer provided was too small.
+.SH EXAMPLES
+The
+.I list
+of names is returned as an unordered array of NULL-terminated character
+strings (attribute names are separated by NULL characters), like this:
+.fam C
+.RS
+.nf
+user.name1\\0system.name1\\0user.name2\\0
+.fi
+.RE
+.fam T
+.P
+Filesystems like ext2, ext3 and XFS which implement POSIX ACLs using
+extended attributes, might return a
+.I list
+like this:
+.fam C
+.RS
+.nf
+system.posix_acl_access\\0system.posix_acl_default\\0
+.fi
+.RE
+.fam T
+.SH RETURN VALUE
+On success, a positive number is returned indicating the size of the
+extended attribute name list.
+On failure, \-1 is returned and
+.I errno
+is set appropriately.
+.PP
+If the
+.I size
+of the
+.I list
+buffer is too small to hold the result,
+.I errno
+is set to ERANGE.
+.PP
+If extended attributes are not supported by the filesystem, or are disabled,
+.I errno
+is set to ENOTSUP.
+.PP
+The errors documented for the
+.BR stat (2)
+system call are also applicable here.
+.SH AUTHORS
+Andreas Gruenbacher,
+.RI < a.gruenbacher@computer.org >
+and the SGI XFS development team,
+.RI < linux-xfs@oss.sgi.com >.
+Please send any bug reports or comments to these addresses.
+.SH SEE ALSO
+.BR getfattr (1),
+.BR setfattr (1),
+.BR open (2),
+.BR stat (2),
+.BR getxattr (2),
+.BR setxattr (2),
+.BR removexattr (2),
+and
+.BR attr (5).