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