1ATTR_LIST(3)                 XFS Compatibility API                ATTR_LIST(3)
2
3
4

NAME

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

C SYNOPSIS

10       #include <attr/attributes.h>
11
12       int attr_list (const char ∗path, char ∗buffer,
13                      const int buffersize, int flags,
14                      attrlist_cursor_t ∗cursor);
15
16       int attr_listf (int fd, char ∗buffer,
17                       const int buffersize, int flags,
18                       attrlist_cursor_t ∗cursor);
19

DESCRIPTION

21       The attr_list and attr_listf functions provide a way to list the exist‐
22       ing attributes of a filesystem object.
23
24       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
34       The contents of an attrlist_t structure include the following members:
35
36          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
40       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
50       The  contents of an attrlist_ent_t structure include the following mem‐
51       bers:
52
53          uint32_t a_valuelen; /∗ number bytes in value of attr ∗/
54          char a_name[]; /∗ attr name (NULL terminated) ∗/
55
56       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
60       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
65       The  flags argument can contain the following symbols bitwise OR´ed to‐
66       gether:
67
68       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
72       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
77       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
85       attr_list will fail if one or more of the following are true:
86
87       [ENOENT]         The named file does not exist.
88
89       [EPERM]          The  effective user ID does not match the owner of the
90                        file and the effective user ID is not super-user.
91
92       [ENOTDIR]        A component of the path prefix is not a directory.
93
94       [EACCES]         Search permission is denied on a component of the path
95                        prefix.
96
97       [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
101       [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
105       [ELOOP]          A path name lookup involved too many symbolic links.
106
107       [ENAMETOOLONG]   The length of path exceeds {MAXPATHLEN}, or a pathname
108                        component is longer than {MAXNAMELEN}.
109
110       [ENOATTR]        attribute does not exist for this file.
111
112       attr_listf will fail if:
113
114       [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
118       [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
122       [EBADF]        Fd does not refer to a valid descriptor.
123

DIAGNOSTICS

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

SEE ALSO

129       attr(1), attr_multi(3), attr_remove(3), attr_set(3)
130
131
132
133Dec 2005                      Extended Attributes                 ATTR_LIST(3)
Impressum