LISTXATTR(2)              System calls             LISTXATTR(2)





NAME
       listxattr,   llistxattr,   flistxattr  -  list  extended
       attribute names

SYNOPSIS
       #include <sys/types.h>
       #include <attr/xattr.h>

       ssize_t listxattr (const char *path,
                            char *list, size_t size);
       ssize_t llistxattr (const char *path,
                            char *list, size_t size);
       ssize_t flistxattr (int filedes,
                            char *list, size_t size);

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 stat(2) data).
       A complete overview of extended attributes concepts  can
       be found in attr(5).

       listxattr retrieves the list of extended attribute names
       associated with the given path in the  filesystem.   The
       list  is  the  set of (NULL-terminated) names, one after
       the other.  Names of extended attributes  to  which  the
       calling process does not have access may be omitted from
       the list.  The length of  the  attribute  name  list  is
       returned.

       llistxattr is identical to 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.

       flistxattr is identical to listxattr, only the open file
       pointed to by filedes (as returned by open(2)) is inter-
       rogated in place of path.

       A single extended attribute name is a simple NULL-termi-
       nated  string.   The  name includes a namespace prefix -
       there may be  several,  disjoint  namespaces  associated
       with an individual inode.

       An  empty  buffer  of 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.

EXAMPLES
       The  list  of names is returned as an unordered array of
       NULL-terminated character strings (attribute  names  are
       separated by NULL characters), like this:
              user.name1\0system.name1\0user.name2\0

       Filesystems  like  ext2,  ext3  and  XFS which implement
       POSIX ACLs using extended  attributes,  might  return  a
       list like this:
              system.posix_acl_access\0system.posix_acl_default\0

RETURN VALUE
       On success, a positive number is returned indicating the
       size of the extended attribute name list.   On  failure,
       -1 is returned and errno is set appropriately.

       If  the size of the list buffer is too small to hold the
       result, errno is set to ERANGE.

       If extended attributes are not supported by the filesys-
       tem, or are disabled, errno is set to ENOTSUP.

       The  errors  documented  for the stat(2) system call are
       also applicable here.

AUTHORS
       Andreas  Gruenbacher,  <a.gruenbacher@computer.org>  and
       the  SGI  XFS development team, <linux-xfs@oss.sgi.com>.
       Please  send  any  bug  reports  or  comments  to  these
       addresses.

SEE ALSO
       getfattr(1), setfattr(1), open(2), stat(2), getxattr(2),
       setxattr(2), removexattr(2), and attr(5).



Dec 2001              Extended Attributes          LISTXATTR(2)
