attr_list(3) — Linux manual page


ATTR_LIST(3)              XFS Compatibility API             ATTR_LIST(3)

NAME         top

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

C SYNOPSIS         top

       #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         top

       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

          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

          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

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

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

              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

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

              The named file does not exist.

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

              A component of the path prefix is not a directory.

              Search permission is denied on a component of the path

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

              Either Path or buffer points outside the allocated address
              space of the process, or buffer or bufsize are not 32bit

              A path name lookup involved too many symbolic links.

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

              attribute does not exist for this file.

       attr_listf will fail if:

              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.

              Either Path or buffer points outside the allocated address
              space of the process, or buffer or bufsize are not 32bit

              Fd does not refer to a valid descriptor.

DIAGNOSTICS         top

       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         top

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

COLOPHON         top

       This page is part of the attr (manipulating filesystem extended
       attributes) project.  Information about the project can be found
       at ⟨⟩.  If you have a bug
       report for this manual page, see
       ⟨⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨git://⟩ on 2021-08-27.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2021-04-19.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Dec 2005                   Extended Attributes              ATTR_LIST(3)

Pages that refer to this page: attr_get(3)attr_multi(3)attr_remove(3)attr_set(3)handle(3)