man2/listxattr.2

   1 .\" Copyright (C) Andreas Gruenbacher, February 2001
   2 .\" Copyright (C) Silicon Graphics Inc, September 2001
   3 .\" Copyright (C) 2015 Heinrich Schuchardt <xypron.glpk@gmx.de>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .TH listxattr 2 (date) "Linux man-pages (unreleased)"
   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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  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
  89 strings (attribute names are separated by null bytes (\[aq]\e0\[aq])), like this:
  90 .PP
  91 .in +4n
  92 .EX
  93 user.name1\e0system.name1\e0user.name2\e0
  94 .EE
  95 .in
  96 .PP
  97 Filesystems that implement POSIX ACLs using
  98 extended attributes might return a
  99 .I list
 100 like this:
 101 .PP
 102 .in +4n
 103 .EX
 104 system.posix_acl_access\e0system.posix_acl_default\e0
 105 .EE
 106 .in
 107 .SH RETURN VALUE
 108 On success, a nonnegative number is returned indicating the size of the
 109 extended attribute name list.
 110 On failure, \-1 is returned and
 111 .I errno
 112 is set to indicate the error.
 113 .SH ERRORS
 114 .TP
 115 .B E2BIG
 116 The size of the list of extended attribute names is larger than the maximum
 117 size allowed; the list cannot be retrieved.
 118 This can happen on filesystems that support an unlimited number of
 119 extended attributes per file such as XFS, for example.
 120 See BUGS.
 121 .TP
 122 .B ENOTSUP
 123 Extended attributes are not supported by the filesystem, or are disabled.
 124 .TP
 125 .B ERANGE
 126 The
 127 .I size
 128 of the
 129 .I list
 130 buffer is too small to hold the result.
 131 .PP
 132 In addition, the errors documented in
 133 .BR stat (2)
 134 can also occur.
 135 .SH VERSIONS
 136 These system calls have been available since Linux 2.4;
 137 glibc support is provided since glibc 2.3.
 138 .SH STANDARDS
 139 These system calls are Linux-specific.
 140 .\" .SH AUTHORS
 141 .\" Andreas Gruenbacher,
 142 .\" .RI < a.gruenbacher@computer.org >
 143 .\" and the SGI XFS development team,
 144 .\" .RI < linux-xfs@oss.sgi.com >.
 145 .\" Please send any bug reports or comments to these addresses.
 146 .SH BUGS
 147 .\" The xattr(7) page refers to this text:
 148 As noted in
 149 .BR xattr (7),
 150 the VFS imposes a limit of 64\ kB on the size of the extended
 151 attribute name list returned by
 152 .BR listxattr ().
 153 If the total size of attribute names attached to a file exceeds this limit,
 154 it is no longer possible to retrieve the list of attribute names.
 155 .SH EXAMPLES
 156 The following program demonstrates the usage of
 157 .BR listxattr ()
 158 and
 159 .BR getxattr (2).
 160 For the file whose pathname is provided as a command-line argument,
 161 it lists all extended file attributes and their values.
 162 .PP
 163 To keep the code simple, the program assumes that attribute keys and
 164 values are constant during the execution of the program.
 165 A production program should expect and handle changes during
 166 execution of the program.
 167 For example,
 168 the number of bytes required for attribute keys
 169 might increase between the two calls to
 170 .BR listxattr ().
 171 An application could handle this possibility using
 172 a loop that retries the call
 173 (perhaps up to a predetermined maximum number of attempts)
 174 with a larger buffer each time it fails with the error
 175 .BR ERANGE .
 176 Calls to
 177 .BR getxattr (2)
 178 could be handled similarly.
 179 .PP
 180 The following output was recorded by first creating a file, setting
 181 some extended file attributes,
 182 and then listing the attributes with the example program.
 183 .SS Example output
 184 .in +4n
 185 .EX
 186 $ \fBtouch /tmp/foo\fP
 187 $ \fBsetfattr \-n user.fred \-v chocolate /tmp/foo\fP
 188 $ \fBsetfattr \-n user.frieda \-v bar /tmp/foo\fP
 189 $ \fBsetfattr \-n user.empty /tmp/foo\fP
 190 $ \fB./listxattr /tmp/foo\fP
 191 user.fred: chocolate
 192 user.frieda: bar
 193 user.empty: <no value>
 194 .EE
 195 .in
 196 .SS Program source (listxattr.c)
 197 .\" SRC BEGIN (listxattr.c)
 198 .EX
 199 #include <stdio.h>
 200 #include <stdlib.h>
 201 #include <string.h>
 202 #include <sys/xattr.h>
 203
 204 int
 205 main(int argc, char *argv[])
 206 {
 207     char     *buf, *key, *val;
 208     ssize_t  buflen, keylen, vallen;
 209
 210     if (argc != 2) {
 211         fprintf(stderr, "Usage: %s path\en", argv[0]);
 212         exit(EXIT_FAILURE);
 213     }
 214
 215     /*
 216      * Determine the length of the buffer needed.
 217      */
 218     buflen = listxattr(argv[1], NULL, 0);
 219     if (buflen == \-1) {
 220         perror("listxattr");
 221         exit(EXIT_FAILURE);
 222     }
 223     if (buflen == 0) {
 224         printf("%s has no attributes.\en", argv[1]);
 225         exit(EXIT_SUCCESS);
 226     }
 227
 228     /*
 229      * Allocate the buffer.
 230      */
 231     buf = malloc(buflen);
 232     if (buf == NULL) {
 233         perror("malloc");
 234         exit(EXIT_FAILURE);
 235     }
 236
 237     /*
 238      * Copy the list of attribute keys to the buffer.
 239      */
 240     buflen = listxattr(argv[1], buf, buflen);
 241     if (buflen == \-1) {
 242         perror("listxattr");
 243         exit(EXIT_FAILURE);
 244     }
 245
 246     /*
 247      * Loop over the list of zero terminated strings with the
 248      * attribute keys. Use the remaining buffer length to determine
 249      * the end of the list.
 250      */
 251     key = buf;
 252     while (buflen > 0) {
 253
 254         /*
 255          * Output attribute key.
 256          */
 257         printf("%s: ", key);
 258
 259         /*
 260          * Determine length of the value.
 261          */
 262         vallen = getxattr(argv[1], key, NULL, 0);
 263         if (vallen == \-1)
 264             perror("getxattr");
 265
 266         if (vallen > 0) {
 267
 268             /*
 269              * Allocate value buffer.
 270              * One extra byte is needed to append 0x00.
 271              */
 272             val = malloc(vallen + 1);
 273             if (val == NULL) {
 274                 perror("malloc");
 275                 exit(EXIT_FAILURE);
 276             }
 277
 278             /*
 279              * Copy value to buffer.
 280              */
 281             vallen = getxattr(argv[1], key, val, vallen);
 282             if (vallen == \-1) {
 283                 perror("getxattr");
 284             } else {
 285                 /*
 286                  * Output attribute value.
 287                  */
 288                 val[vallen] = 0;
 289                 printf("%s", val);
 290             }
 291
 292             free(val);
 293         } else if (vallen == 0) {
 294             printf("<no value>");
 295         }
 296
 297         printf("\en");
 298
 299         /*
 300          * Forward to next attribute key.
 301          */
 302         keylen = strlen(key) + 1;
 303         buflen \-= keylen;
 304         key += keylen;
 305     }
 306
 307     free(buf);
 308     exit(EXIT_SUCCESS);
 309 }
 310 .EE
 311 .\" SRC END
 312 .SH SEE ALSO
 313 .BR getfattr (1),
 314 .BR setfattr (1),
 315 .BR getxattr (2),
 316 .BR open (2),
 317 .BR removexattr (2),
 318 .BR setxattr (2),
 319 .BR stat (2),
 320 .BR symlink (7),
 321 .BR xattr (7)