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