1listxattr(2)                  System Calls Manual                 listxattr(2)
2
3
4

NAME

6       listxattr, llistxattr, flistxattr - list extended attribute names
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/xattr.h>
13
14       ssize_t listxattr(const char *path, char *_Nullable list, size_t size);
15       ssize_t llistxattr(const char *path, char *_Nullable list, size_t size);
16       ssize_t flistxattr(int fd, char *_Nullable list, size_t size);
17

DESCRIPTION

19       Extended attributes are name:value pairs associated with inodes (files,
20       directories, symbolic links, etc.).  They are extensions to the  normal
21       attributes  which  are  associated with all inodes in the system (i.e.,
22       the stat(2) data).  A complete overview of extended attributes concepts
23       can be found in xattr(7).
24
25       listxattr()  retrieves  the list of extended attribute names associated
26       with the given path in the filesystem.  The retrieved list is placed in
27       list,  a  caller-allocated buffer whose size (in bytes) is specified in
28       the argument size.  The list is the set of (null-terminated) names, one
29       after  the  other.   Names  of extended attributes to which the calling
30       process does not have access may be omitted from the list.  The  length
31       of the attribute name list is returned.
32
33       llistxattr()  is identical to listxattr(), except in the case of a sym‐
34       bolic link, where the list of names of extended  attributes  associated
35       with the link itself is retrieved, not the file that it refers to.
36
37       flistxattr()  is  identical to listxattr(), only the open file referred
38       to by fd (as returned by open(2)) is interrogated in place of path.
39
40       A single extended attribute name is a null-terminated string.  The name
41       includes  a namespace prefix; there may be several, disjoint namespaces
42       associated with an individual inode.
43
44       If size is specified as zero, these calls return the  current  size  of
45       the  list of extended attribute names (and leave list unchanged).  This
46       can be used to determine the size of the buffer that should be supplied
47       in  a  subsequent call.  (But, bear in mind that there is a possibility
48       that the set of extended attributes may change between the  two  calls,
49       so  that it is still necessary to check the return status from the sec‐
50       ond call.)
51
52   Example
53       The list of names is returned as an unordered array of  null-terminated
54       character strings (attribute names are separated by null bytes ('\0')),
55       like this:
56
57           user.name1\0system.name1\0user.name2\0
58
59       Filesystems that implement POSIX ACLs using extended  attributes  might
60       return a list like this:
61
62           system.posix_acl_access\0system.posix_acl_default\0
63

RETURN VALUE

65       On success, a nonnegative number is returned indicating the size of the
66       extended attribute name list.  On failure, -1 is returned and errno  is
67       set to indicate the error.
68

ERRORS

70       E2BIG  The  size of the list of extended attribute names is larger than
71              the maximum size allowed; the list cannot  be  retrieved.   This
72              can  happen  on  filesystems that support an unlimited number of
73              extended attributes per file such  as  XFS,  for  example.   See
74              BUGS.
75
76       ENOTSUP
77              Extended  attributes are not supported by the filesystem, or are
78              disabled.
79
80       ERANGE The size of the list buffer is too small to hold the result.
81
82       In addition, the errors documented in stat(2) can also occur.
83

STANDARDS

85       Linux.
86

HISTORY

88       Linux 2.4, glibc 2.3.
89

BUGS

91       As noted in xattr(7), the VFS imposes a limit of 64 kB on the  size  of
92       the extended attribute name list returned by listxattr().  If the total
93       size of attribute names attached to a file exceeds this limit, it is no
94       longer possible to retrieve the list of attribute names.
95

EXAMPLES

97       The  following  program demonstrates the usage of listxattr() and getx‐
98       attr(2).  For the file whose pathname is provided as a command-line ar‐
99       gument, it lists all extended file attributes and their values.
100
101       To  keep  the  code simple, the program assumes that attribute keys and
102       values are constant during the execution of the program.  A  production
103       program  should  expect and handle changes during execution of the pro‐
104       gram.  For example, the number of bytes  required  for  attribute  keys
105       might  increase  between  the two calls to listxattr().  An application
106       could handle this possibility using a loop that retries the call  (per‐
107       haps  up  to  a predetermined maximum number of attempts) with a larger
108       buffer each time it fails with the error ERANGE.  Calls to  getxattr(2)
109       could be handled similarly.
110
111       The  following  output  was  recorded by first creating a file, setting
112       some extended file attributes, and then listing the attributes with the
113       example program.
114
115   Example output
116           $ touch /tmp/foo
117           $ setfattr -n user.fred -v chocolate /tmp/foo
118           $ setfattr -n user.frieda -v bar /tmp/foo
119           $ setfattr -n user.empty /tmp/foo
120           $ ./listxattr /tmp/foo
121           user.fred: chocolate
122           user.frieda: bar
123           user.empty: <no value>
124
125   Program source (listxattr.c)
126       #include <stdio.h>
127       #include <stdlib.h>
128       #include <string.h>
129       #include <sys/xattr.h>
130
131       int
132       main(int argc, char *argv[])
133       {
134           char     *buf, *key, *val;
135           ssize_t  buflen, keylen, vallen;
136
137           if (argc != 2) {
138               fprintf(stderr, "Usage: %s path\n", argv[0]);
139               exit(EXIT_FAILURE);
140           }
141
142           /*
143            * Determine the length of the buffer needed.
144            */
145           buflen = listxattr(argv[1], NULL, 0);
146           if (buflen == -1) {
147               perror("listxattr");
148               exit(EXIT_FAILURE);
149           }
150           if (buflen == 0) {
151               printf("%s has no attributes.\n", argv[1]);
152               exit(EXIT_SUCCESS);
153           }
154
155           /*
156            * Allocate the buffer.
157            */
158           buf = malloc(buflen);
159           if (buf == NULL) {
160               perror("malloc");
161               exit(EXIT_FAILURE);
162           }
163
164           /*
165            * Copy the list of attribute keys to the buffer.
166            */
167           buflen = listxattr(argv[1], buf, buflen);
168           if (buflen == -1) {
169               perror("listxattr");
170               exit(EXIT_FAILURE);
171           }
172
173           /*
174            * Loop over the list of zero terminated strings with the
175            * attribute keys. Use the remaining buffer length to determine
176            * the end of the list.
177            */
178           key = buf;
179           while (buflen > 0) {
180
181               /*
182                * Output attribute key.
183                */
184               printf("%s: ", key);
185
186               /*
187                * Determine length of the value.
188                */
189               vallen = getxattr(argv[1], key, NULL, 0);
190               if (vallen == -1)
191                   perror("getxattr");
192
193               if (vallen > 0) {
194
195                   /*
196                    * Allocate value buffer.
197                    * One extra byte is needed to append 0x00.
198                    */
199                   val = malloc(vallen + 1);
200                   if (val == NULL) {
201                       perror("malloc");
202                       exit(EXIT_FAILURE);
203                   }
204
205                   /*
206                    * Copy value to buffer.
207                    */
208                   vallen = getxattr(argv[1], key, val, vallen);
209                   if (vallen == -1) {
210                       perror("getxattr");
211                   } else {
212                       /*
213                        * Output attribute value.
214                        */
215                       val[vallen] = 0;
216                       printf("%s", val);
217                   }
218
219                   free(val);
220               } else if (vallen == 0) {
221                   printf("<no value>");
222               }
223
224               printf("\n");
225
226               /*
227                * Forward to next attribute key.
228                */
229               keylen = strlen(key) + 1;
230               buflen -= keylen;
231               key += keylen;
232           }
233
234           free(buf);
235           exit(EXIT_SUCCESS);
236       }
237

SEE ALSO

239       getfattr(1),  setfattr(1),  getxattr(2), open(2), removexattr(2), setx‐
240       attr(2), stat(2), symlink(7), xattr(7)
241
242
243
244Linux man-pages 6.04              2023-03-30                      listxattr(2)
Impressum