Debian Codegraph @

upstream/debian-trixie/man2/listxattr.2

raw
1 .\" Copyright (C) Andreas Gruenbacher, February 2001
2 .\" Copyright (C) Silicon Graphics Inc, September 2001
3 .\" Copyright (C) 2015 Heinrich Schuchardt <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH listxattr 2 2024-06-15 "Linux man-pages 6.9.1"
8 .SH NAME
9 listxattr, llistxattr, flistxattr \- list extended attribute names
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ", " \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/xattr.h>
16 .P
17 .BI "ssize_t listxattr(const char *" path ", char *_Nullable " list \
18 ", size_t " size );
19 .BI "ssize_t llistxattr(const char *" path ", char *_Nullable " list \
20 ", size_t " size );
21 .BI "ssize_t flistxattr(int " fd ", char *_Nullable " list ", size_t " size );
22 .fi
23 .SH DESCRIPTION
24 Extended attributes are
25 .IR name : value
26 pairs associated with inodes (files, directories, symbolic links, etc.).
27 They are extensions to the normal attributes which are associated
28 with all inodes in the system (i.e., the
29 .BR stat (2)
30 data).
31 A complete overview of extended attributes concepts can be found in
32 .BR xattr (7).
33 .P
34 .BR listxattr ()
35 retrieves the list
36 of extended attribute names associated with the given
37 .I path
38 in the filesystem.
39 The retrieved list is placed in
40 .IR list ,
41 a caller-allocated buffer whose size (in bytes) is specified in the argument
42 .IR size .
43 The list is the set of (null-terminated) names, one after the other.
44 Names of extended attributes to which the calling process does not
45 have access may be omitted from the list.
46 The length of the attribute name
47 .I list
48 is returned.
49 .P
50 .BR llistxattr ()
51 is identical to
52 .BR listxattr (),
53 except in the case of a symbolic link, where the list of names of
54 extended attributes associated with the link itself is retrieved,
55 not the file that it refers to.
56 .P
57 .BR flistxattr ()
58 is identical to
59 .BR listxattr (),
60 only the open file referred to by
61 .I fd
62 (as returned by
63 .BR open (2))
64 is interrogated in place of
65 .IR path .
66 .P
67 A single extended attribute
68 .I name
69 is a null-terminated string.
70 The name includes a namespace prefix; there may be several, disjoint
71 namespaces associated with an individual inode.
72 .P
73 If
74 .I size
75 is specified as zero, these calls return the current size of the
76 list of extended attribute names (and leave
77 .I list
78 unchanged).
79 This can be used to determine the size of the buffer that
80 should be supplied in a subsequent call.
81 (But, bear in mind that there is a possibility that the
82 set of extended attributes may change between the two calls,
83 so that it is still necessary to check the return status
84 from the second call.)
85 .SS Example
86 The
87 .I list
88 of names is returned as an unordered array of null-terminated character strings
89 (attribute names are separated by null bytes (\[aq]\[rs]0\[aq])),
90 like this:
91 .P
92 .in +4n
93 .EX
94 user.name1\[rs]0system.name1\[rs]0user.name2\[rs]0
95 .EE
96 .in
97 .P
98 Filesystems that implement POSIX ACLs using
99 extended attributes might return a
100 .I list
101 like this:
102 .P
103 .in +4n
104 .EX
105 system.posix_acl_access\[rs]0system.posix_acl_default\[rs]0
106 .EE
107 .in
108 .SH RETURN VALUE
109 On success, a nonnegative number is returned indicating the size of the
110 extended attribute name list.
111 On failure, \-1 is returned and
112 .I errno
113 is set to indicate the error.
114 .SH ERRORS
115 .TP
116 .B E2BIG
117 The size of the list of extended attribute names is larger than the maximum
118 size allowed; the list cannot be retrieved.
119 This can happen on filesystems that support an unlimited number of
120 extended attributes per file such as XFS, for example.
121 See BUGS.
122 .TP
123 .B ENOTSUP
124 Extended attributes are not supported by the filesystem, or are disabled.
125 .TP
126 .B ERANGE
127 The
128 .I size
129 of the
130 .I list
131 buffer is too small to hold the result.
132 .P
133 In addition, the errors documented in
134 .BR stat (2)
135 can also occur.
136 .SH STANDARDS
137 Linux.
138 .SH HISTORY
139 Linux 2.4,
140 glibc 2.3.
141 .\" .SH AUTHORS
142 .\" Andreas Gruenbacher,
143 .\" .RI < [email protected] >
144 .\" and the SGI XFS development team,
145 .\" .RI < [email protected] >.
146 .\" Please send any bug reports or comments to these addresses.
147 .SH BUGS
148 .\" The xattr(7) page refers to this text:
149 As noted in
150 .BR xattr (7),
151 the VFS imposes a limit of 64\ kB on the size of the extended
152 attribute name list returned by
153 .BR listxattr ().
154 If the total size of attribute names attached to a file exceeds this limit,
155 it is no longer possible to retrieve the list of attribute names.
156 .SH EXAMPLES
157 The following program demonstrates the usage of
158 .BR listxattr ()
159 and
160 .BR getxattr (2).
161 For the file whose pathname is provided as a command-line argument,
162 it lists all extended file attributes and their values.
163 .P
164 To keep the code simple, the program assumes that attribute keys and
165 values are constant during the execution of the program.
166 A production program should expect and handle changes during
167 execution of the program.
168 For example,
169 the number of bytes required for attribute keys
170 might increase between the two calls to
171 .BR listxattr ().
172 An application could handle this possibility using
173 a loop that retries the call
174 (perhaps up to a predetermined maximum number of attempts)
175 with a larger buffer each time it fails with the error
176 .BR ERANGE .
177 Calls to
178 .BR getxattr (2)
179 could be handled similarly.
180 .P
181 The following output was recorded by first creating a file, setting
182 some extended file attributes,
183 and then listing the attributes with the example program.
184 .SS Example output
185 .in +4n
186 .EX
187 $ \fBtouch /tmp/foo\fP
188 $ \fBsetfattr \-n user.fred \-v chocolate /tmp/foo\fP
189 $ \fBsetfattr \-n user.frieda \-v bar /tmp/foo\fP
190 $ \fBsetfattr \-n user.empty /tmp/foo\fP
191 $ \fB./listxattr /tmp/foo\fP
192 user.fred: chocolate
193 user.frieda: bar
194 user.empty: <no value>
195 .EE
196 .in
197 .SS Program source (listxattr.c)
198 .\" SRC BEGIN (listxattr.c)
199 .EX
200 #include <stdio.h>
201 #include <stdlib.h>
202 #include <string.h>
203 #include <sys/xattr.h>
204 \&
205 int
206 main(int argc, char *argv[])
207 {
208 char *buf, *key, *val;
209 ssize_t buflen, keylen, vallen;
210 \&
211 if (argc != 2) {
212 fprintf(stderr, "Usage: %s path\[rs]n", argv[0]);
213 exit(EXIT_FAILURE);
214 }
215 \&
216 /*
217 * Determine the length of the buffer needed.
218 */
219 buflen = listxattr(argv[1], NULL, 0);
220 if (buflen == \-1) {
221 perror("listxattr");
222 exit(EXIT_FAILURE);
223 }
224 if (buflen == 0) {
225 printf("%s has no attributes.\[rs]n", argv[1]);
226 exit(EXIT_SUCCESS);
227 }
228 \&
229 /*
230 * Allocate the buffer.
231 */
232 buf = malloc(buflen);
233 if (buf == NULL) {
234 perror("malloc");
235 exit(EXIT_FAILURE);
236 }
237 \&
238 /*
239 * Copy the list of attribute keys to the buffer.
240 */
241 buflen = listxattr(argv[1], buf, buflen);
242 if (buflen == \-1) {
243 perror("listxattr");
244 exit(EXIT_FAILURE);
245 }
246 \&
247 /*
248 * Loop over the list of zero terminated strings with the
249 * attribute keys. Use the remaining buffer length to determine
250 * the end of the list.
251 */
252 key = buf;
253 while (buflen > 0) {
254 \&
255 /*
256 * Output attribute key.
257 */
258 printf("%s: ", key);
259 \&
260 /*
261 * Determine length of the value.
262 */
263 vallen = getxattr(argv[1], key, NULL, 0);
264 if (vallen == \-1)
265 perror("getxattr");
266 \&
267 if (vallen > 0) {
268 \&
269 /*
270 * Allocate value buffer.
271 * One extra byte is needed to append 0x00.
272 */
273 val = malloc(vallen + 1);
274 if (val == NULL) {
275 perror("malloc");
276 exit(EXIT_FAILURE);
277 }
278 \&
279 /*
280 * Copy value to buffer.
281 */
282 vallen = getxattr(argv[1], key, val, vallen);
283 if (vallen == \-1) {
284 perror("getxattr");
285 } else {
286 /*
287 * Output attribute value.
288 */
289 val[vallen] = 0;
290 printf("%s", val);
291 }
292 \&
293 free(val);
294 } else if (vallen == 0) {
295 printf("<no value>");
296 }
297 \&
298 printf("\[rs]n");
299 \&
300 /*
301 * Forward to next attribute key.
302 */
303 keylen = strlen(key) + 1;
304 buflen \-= keylen;
305 key += keylen;
306 }
307 \&
308 free(buf);
309 exit(EXIT_SUCCESS);
310 }
311 .EE
312 .\" SRC END
313 .SH SEE ALSO
314 .BR getfattr (1),
315 .BR setfattr (1),
316 .BR getxattr (2),
317 .BR open (2),
318 .BR removexattr (2),
319 .BR setxattr (2),
320 .BR stat (2),
321 .BR symlink (7),
322 .BR xattr (7)