NAME

       attr_list, attr_listf - list the names of the user attributes of a filesystem object

C SYNOPSIS

       #include <attr/attributes.h>

       int attr_list (const char ∗path, char ∗buffer,
                      const int buffersize, int flags,
                      attrlist_cursor_t ∗cursor);

       int attr_listf (int fd, char ∗buffer,
                       const int buffersize, int flags,
                       attrlist_cursor_t ∗cursor);

DESCRIPTION

       The  attr_list and attr_listf functions provide a way to list the existing attributes of a
       filesystem object.

       Path points to a path name for a filesystem object, and fd refers to the  file  descriptor
       associated  with a file.  The buffer will be filled with a structure describing at least a
       portion of the attributes associated with the given filesystem  object.   Buffer  will  be
       overwritten  with  an  attrlist_t structure containing a list of the attributes associated
       with that filesystem object, up to a maximum of buffersize  bytes.   The  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.

       The contents of an attrlist_t structure include the following members:

          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] ∗/

       The  al_count  field  shows  the number of attributes represented in this buffer, which is
       also the number of elements in the al_offset array.  The al_more field will be non-zero if
       another  attr_list call would result in more attributes.  The al_offset array contains the
       byte offset within the buffer of the structure  describing  each  of  the  attributes,  an
       attrlist_ent_t structure.  The ATTR_ENTRY(buffer, index) macro will help with decoding the
       list.  It takes a pointer to the buffer and an index into the al_offset array and  returns
       a pointer to the corresponding attrlist_ent_t structure.

       The contents of an attrlist_ent_t structure include the following members:

          uint32_t a_valuelen; /∗ number bytes in value of attr ∗/
          char a_name[]; /∗ attr name (NULL terminated) ∗/

       The  a_valuelen  field  shows the size in bytes of the value associated with the attribute
       whose name is stored in the a_name field.  The name is a NULL terminated string.

       Note that the value of the attribute  cannot  be  obtained  through  this  interface,  the
       attr_get  call should be used to get the value.  The attr_list interface tells the calling
       process how large of a buffer it must have in order to get the attribute's value.

       The flags argument can contain the following symbols bitwise OR'ed together:

       ATTR_ROOT
              List the attributes that are in the root address space, not  in  the  user  address
              space.  (limited to use by super-user only)

       ATTR_DONTFOLLOW
              Do  not  follow symbolic links when resolving a path on an attr_list function call.
              The default is to follow symbolic links.

       The 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
       cursor are to pass it into an attr_list function call or to zero it  out.   It  should  be
       zero'ed  out  before  the first attr_list call.  Note that multi-threaded applications may
       keep more than one cursor in order to serve multiple contexts, ie: the attr_list  call  is
       "thread-safe".

       attr_list will fail if one or more of the following are true:

       [ENOENT]         The named file does not exist.

       [EPERM]          The  effective  user  ID  does  not  match  the owner of the file and the
                        effective user ID is not super-user.

       [ENOTDIR]        A component of the path prefix is not a directory.

       [EACCES]         Search permission is denied on a component of the path prefix.

       [EINVAL]         A bit was set in the flag argument that is not defined  for  this  system
                        call, or the buffer was too small or too large.

       [EFAULT]         Either  Path  or buffer points outside the allocated address space of the
                        process, or buffer or bufsize are not 32bit aligned.

       [ELOOP]          A path name lookup involved too many symbolic links.

       [ENAMETOOLONG]   The length of path exceeds  {MAXPATHLEN},  or  a  pathname  component  is
                        longer than {MAXNAMELEN}.

       [ENOATTR]        attribute  does  not  exist  for  this file.  If the system libc does not
                        define this error code,  then  libattr  will  define  it  to  ENODATA  in
                        <attr/attributes.h>.

       attr_listf will fail if:

       [EINVAL]       A  bit  was  set  in  the flag argument that is not defined for this system
                      call, or fd refers to a socket, not a file, or the buffer was too small  or
                      too large.

       [EFAULT]       Either  Path  or  buffer  points outside the allocated address space of the
                      process, or buffer or bufsize are not 32bit aligned.

       [EBADF]        Fd does not refer to a valid descriptor.

DIAGNOSTICS

       Upon successful completion, a value of 0  is  returned.   Otherwise,  a  value  of  -1  is
       returned and errno is set to indicate the error.

SEE ALSO

       attr(1), attr_multi(3), attr_remove(3), attr_set(3)