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 interro­
       gated 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:


       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).


Man(1) output converted with man2html