Man Pages

attr_list(3) - phpMan attr_list(3) - phpMan

Command: man perldoc info search(apropos)  


ATTR_LIST(3)                 XFS Compatibility API                ATTR_LIST(3)



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 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  ele-
       ments  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 decod-
       ing 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  pro-
       cess?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).



Dec 2005                      Extended Attributes                 ATTR_LIST(3)