1LISTXATTR(2)               Linux Programmer's Manual              LISTXATTR(2)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

63       On success, a nonnegative number is returned indicating the size of the
64       extended attribute name list.  On failure, -1 is returned and errno  is
65       set appropriately.
66

ERRORS

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

VERSIONS

83       These system calls have been available on Linux since kernel 2.4; glibc
84       support is provided since version 2.3.
85

CONFORMING TO

87       These system calls are Linux-specific.
88

BUGS

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

EXAMPLES

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

COLOPHON

243       This  page  is  part of release 5.07 of the Linux man-pages project.  A
244       description of the project, information about reporting bugs,  and  the
245       latest     version     of     this    page,    can    be    found    at
246       https://www.kernel.org/doc/man-pages/.
247
248
249
250Linux                             2020-06-09                      LISTXATTR(2)
Impressum