# attr_list

## 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.
    
           **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.
    


* * *