Man Linux: Main Page and Category List

NAME

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

C SYNOPSIS

       #include <sys/attributes.h>

       int attr_list (const charpath, charbuffer,
                      const int buffersize, int flags,
                      attrlist_cursor_tcursor);

       int attr_listf (int fd, charbuffer,
                       const int buffersize, int flags,
                       attrlist_cursor_tcursor);

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:

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

SEE ALSO

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