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 aattttrrlliisstt__tt 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 aattttrrlliisstt__tt structure include the following members:
- ____iinntt3322__tt aall__ccoouunntt;; //** nnuummbbeerr ooff eennttrriieess iinn aattttrrlliisstt **// ____iinntt3322__tt aall__mmoorree;; //** TT//FF:: mmoorree aattttrrss ((ddoo ssyyssccaallll aaggaaiinn)) **// ____iinntt3322__tt aall__ooffffsseett[[11]];; //** bbyyttee ooffffsseettss ooff aattttrrss [[vvaarr--ssiizzeedd]] **//
- 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 aattttrrlliisstt__eenntt__tt structure. The AATTTTRR__EENNTTRRYY((bbuuffffeerr,, iinnddeexx)) 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 aattttrrlliisstt__eenntt__tt structure.
- The contents of an aattttrrlliisstt__eenntt__tt structure include the following members:
uu__iinntt3322__tt aa__vvaalluueelleenn;; //** nnuummbbeerr bbyytteess iinn vvaalluuee ooff aattttrr **// cchhaarr aa__nnaammee[[]];; //** aattttrr nnaammee ((NNUULLLL tteerrmmiinnaatteedd)) **//- 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.