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 2021-03-22 "Linux" "Linux Programmer's Manual"
   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 *" list \
  18 ", size_t " size );
  19 .BI "ssize_t llistxattr(const char *" path ", char *" list \
  20 ", size_t " size );
  21 .BI "ssize_t flistxattr(int " fd ", char *" 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 on Linux since kernel 2.4;
 137 glibc support is provided since version 2.3.
 138 .SH CONFORMING TO
 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 <malloc.h>
 200 #include <stdio.h>
 201 #include <stdlib.h>
 202 #include <string.h>
 203 #include <sys/types.h>
 204 #include <sys/xattr.h>
 205
 206 int
 207 main(int argc, char *argv[])
 208 {
 209     ssize_t buflen, keylen, vallen;
 210     char *buf, *key, *val;
 211
 212     if (argc != 2) {
 213         fprintf(stderr, "Usage: %s path\en", argv[0]);
 214         exit(EXIT_FAILURE);
 215     }
 216
 217     /*
 218      * Determine the length of the buffer needed.
 219      */
 220     buflen = listxattr(argv[1], NULL, 0);
 221     if (buflen == \-1) {
 222         perror("listxattr");
 223         exit(EXIT_FAILURE);
 224     }
 225     if (buflen == 0) {
 226         printf("%s has no attributes.\en", argv[1]);
 227         exit(EXIT_SUCCESS);
 228     }
 229
 230     /*
 231      * Allocate the buffer.
 232      */
 233     buf = malloc(buflen);
 234     if (buf == NULL) {
 235         perror("malloc");
 236         exit(EXIT_FAILURE);
 237     }
 238
 239     /*
 240      * Copy the list of attribute keys to the buffer.
 241      */
 242     buflen = listxattr(argv[1], buf, buflen);
 243     if (buflen == \-1) {
 244         perror("listxattr");
 245         exit(EXIT_FAILURE);
 246     }
 247
 248     /*
 249      * Loop over the list of zero terminated strings with the
 250      * attribute keys. Use the remaining buffer length to determine
 251      * the end of the list.
 252      */
 253     key = buf;
 254     while (buflen > 0) {
 255
 256         /*
 257          * Output attribute key.
 258          */
 259         printf("%s: ", key);
 260
 261         /*
 262          * Determine length of the value.
 263          */
 264         vallen = getxattr(argv[1], key, NULL, 0);
 265         if (vallen == \-1)
 266             perror("getxattr");
 267
 268         if (vallen > 0) {
 269
 270             /*
 271              * Allocate value buffer.
 272              * One extra byte is needed to append 0x00.
 273              */
 274             val = malloc(vallen + 1);
 275             if (val == NULL) {
 276                 perror("malloc");
 277                 exit(EXIT_FAILURE);
 278             }
 279
 280             /*
 281              * Copy value to buffer.
 282              */
 283             vallen = getxattr(argv[1], key, val, vallen);
 284             if (vallen == \-1)
 285                 perror("getxattr");
 286             else {
 287                 /*
 288                  * Output attribute value.
 289                  */
 290                 val[vallen] = 0;
 291                 printf("%s", val);
 292             }
 293
 294             free(val);
 295         } else if (vallen == 0)
 296             printf("<no value>");
 297
 298         printf("\en");
 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)