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/xattr.h>
10
11       ssize_t listxattr(const char *path, char *list, size_t size);
12       ssize_t llistxattr(const char *path, char *list, size_t size);
13       ssize_t flistxattr(int fd, char *list, size_t size);
14

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

VERSIONS

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

CONFORMING TO

86       These system calls are Linux-specific.
87

BUGS

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

EXAMPLES

95       The following program demonstrates the usage of listxattr()  and  getx‐
96       attr(2).  For the file whose pathname is provided as a command-line ar‐
97       gument, it lists all extended file attributes and their values.
98
99       To keep the code simple, the program assumes that  attribute  keys  and
100       values  are constant during the execution of the program.  A production
101       program should expect and handle changes during execution of  the  pro‐
102       gram.   For  example,  the  number of bytes required for attribute keys
103       might increase between the two calls to  listxattr().   An  application
104       could  handle this possibility using a loop that retries the call (per‐
105       haps up to a predetermined maximum number of attempts)  with  a  larger
106       buffer  each time it fails with the error ERANGE.  Calls to getxattr(2)
107       could be handled similarly.
108
109       The following output was recorded by first  creating  a  file,  setting
110       some extended file attributes, and then listing the attributes with the
111       example program.
112
113   Example output
114           $ touch /tmp/foo
115           $ setfattr -n user.fred -v chocolate /tmp/foo
116           $ setfattr -n user.frieda -v bar /tmp/foo
117           $ setfattr -n user.empty /tmp/foo
118           $ ./listxattr /tmp/foo
119           user.fred: chocolate
120           user.frieda: bar
121           user.empty: <no value>
122
123   Program source (listxattr.c)
124       #include <malloc.h>
125       #include <stdio.h>
126       #include <stdlib.h>
127       #include <string.h>
128       #include <sys/types.h>
129       #include <sys/xattr.h>
130
131       int
132       main(int argc, char *argv[])
133       {
134           ssize_t buflen, keylen, vallen;
135           char *buf, *key, *val;
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               printf("\n");
224
225               /*
226                * Forward to next attribute key.
227                */
228               keylen = strlen(key) + 1;
229               buflen -= keylen;
230               key += keylen;
231           }
232
233           free(buf);
234           exit(EXIT_SUCCESS);
235       }
236

SEE ALSO

238       getfattr(1), setfattr(1), getxattr(2), open(2),  removexattr(2),  setx‐
239       attr(2), stat(2), symlink(7), xattr(7)
240

COLOPHON

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