1ATTR_LIST(3) XFS Compatibility API ATTR_LIST(3)
2
6 attr_list, attr_listf - list the names of the user attributes of a
7 filesystem object
8
10 #include <attr/attributes.h>
11 int attr_list (const char ∗path, char ∗buffer,
13 const int buffersize, int flags,
14 attrlist_cursor_t ∗cursor);
15 int attr_listf (int fd, char ∗buffer,
17 const int buffersize, int flags,
18 attrlist_cursor_t ∗cursor);
19
21 The attr_list and attr_listf functions provide a way to list the exist‐
22 ing attributes of a filesystem object.
23 Path points to a path name for a filesystem object, and fd refers to
25 the file descriptor associated with a file. The buffer will be filled
26 with a structure describing at least a portion of the attributes asso‐
27 ciated with the given filesystem object. Buffer will be overwritten
28 with an attrlist_t structure containing a list of the attributes asso‐
29 ciated with that filesystem object, up to a maximum of buffersize
30 bytes. The buffer must be sufficiently large to hold the appropriate
31 data structures plus at least one maximally sized attribute name, but
32 cannot be more than ATTR_MAX_VALUELEN (currently 64KB) bytes in length.
33 The contents of an attrlist_t structure include the following members:
35 int32_t al_count; /∗ number of entries in attrlist ∗/
37 int32_t al_more; /∗ T/F: more attrs (do syscall again) ∗/
38 int32_t al_offset[1]; /∗ byte offsets of attrs [var-sized] ∗/
39 The al_count field shows the number of attributes represented in this
41 buffer, which is also the number of elements in the al_offset array.
42 The al_more field will be non-zero if another attr_list call would re‐
43 sult in more attributes. The al_offset array contains the byte offset
44 within the buffer of the structure describing each of the attributes,
45 an attrlist_ent_t structure. The ATTR_ENTRY(buffer, index) macro will
46 help with decoding the list. It takes a pointer to the buffer and an
47 index into the al_offset array and returns a pointer to the correspond‐
48 ing attrlist_ent_t structure.
49 The contents of an attrlist_ent_t structure include the following mem‐
51 bers:
52 uint32_t a_valuelen; /∗ number bytes in value of attr ∗/
54 char a_name[]; /∗ attr name (NULL terminated) ∗/
55 The a_valuelen field shows the size in bytes of the value associated
57 with the attribute whose name is stored in the a_name field. The name
58 is a NULL terminated string.
59 Note that the value of the attribute cannot be obtained through this
61 interface, the attr_get call should be used to get the value. The
62 attr_list interface tells the calling process how large of a buffer it
63 must have in order to get the attribute´s value.
64 The flags argument can contain the following symbols bitwise OR´ed to‐
66 gether:
67 ATTR_ROOT
69 List the attributes that are in the root address space, not in
70 the user address space. (limited to use by super-user only)
71 ATTR_DONTFOLLOW
73 Do not follow symbolic links when resolving a path on an
74 attr_list function call. The default is to follow symbolic
75 links.
76 The cursor argument is a pointer to an opaque data structure that the
78 kernel uses to track the calling process´s position in the attribute
79 list. The only valid operations on a cursor are to pass it into an
80 attr_list function call or to zero it out. It should be zero´ed out
81 before the first attr_list call. Note that multi-threaded applications
82 may keep more than one cursor in order to serve multiple contexts, ie:
83 the attr_list call is "thread-safe".
84 attr_list will fail if one or more of the following are true:
86 [ENOENT] The named file does not exist.
88 [EPERM] The effective user ID does not match the owner of the
90 file and the effective user ID is not super-user.
91 [ENOTDIR] A component of the path prefix is not a directory.
93 [EACCES] Search permission is denied on a component of the path
95 prefix.
96 [EINVAL] A bit was set in the flag argument that is not defined
98 for this system call, or the buffer was too small or
99 too large.
100 [EFAULT] Either Path or buffer points outside the allocated ad‐
102 dress space of the process, or buffer or bufsize are
103 not 32bit aligned.
104 [ELOOP] A path name lookup involved too many symbolic links.
106 [ENAMETOOLONG] The length of path exceeds {MAXPATHLEN}, or a pathname
108 component is longer than {MAXNAMELEN}.
109 [ENOATTR] attribute does not exist for this file.
111 attr_listf will fail if:
113 [EINVAL] A bit was set in the flag argument that is not defined
115 for this system call, or fd refers to a socket, not a
116 file, or the buffer was too small or too large.
117 [EFAULT] Either Path or buffer points outside the allocated ad‐
119 dress space of the process, or buffer or bufsize are not
120 32bit aligned.
121 [EBADF] Fd does not refer to a valid descriptor.
123
125 Upon successful completion, a value of 0 is returned. Otherwise, a
126 value of -1 is returned and errno is set to indicate the error.
127
129 attr(1), attr_multi(3), attr_remove(3), attr_set(3)
130Dec 2005 Extended Attributes ATTR_LIST(3)