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