man2/getxattr.2

   1 .\" Copyright (C) Andreas Gruenbacher, February 2001
   2 .\" Copyright (C) Silicon Graphics Inc, September 2001
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH GETXATTR 2 2021-03-22 "Linux man-pages (unreleased)"
   7 .SH NAME
   8 getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <sys/xattr.h>
  15 .PP
  16 .BI "ssize_t getxattr(const char *" path ", const char *" name ,
  17 .BI "                 void *" value ", size_t " size );
  18 .BI "ssize_t lgetxattr(const char *" path ", const char *" name ,
  19 .BI "                 void *" value ", size_t " size );
  20 .BI "ssize_t fgetxattr(int " fd ", const char *" name ,
  21 .BI "                 void *" value ", size_t " size );
  22 .fi
  23 .SH DESCRIPTION
  24 Extended attributes are
  25 .IR name :\c
  26 .I value
  27 pairs associated with inodes (files, directories, symbolic links, etc.).
  28 They are extensions to the normal attributes which are associated
  29 with all inodes in the system (i.e., the
  30 .BR stat (2)
  31 data).
  32 A complete overview of extended attributes concepts can be found in
  33 .BR xattr (7).
  34 .PP
  35 .BR getxattr ()
  36 retrieves the value of the extended attribute identified by
  37 .I name
  38 and associated with the given
  39 .I path
  40 in the filesystem.
  41 The attribute value is placed in the buffer pointed to by
  42 .IR value ;
  43 .I size
  44 specifies the size of that buffer.
  45 The return value of the call is the number of bytes placed in
  46 .IR value .
  47 .PP
  48 .BR lgetxattr ()
  49 is identical to
  50 .BR getxattr (),
  51 except in the case of a symbolic link, where the link itself is
  52 interrogated, not the file that it refers to.
  53 .PP
  54 .BR fgetxattr ()
  55 is identical to
  56 .BR getxattr (),
  57 only the open file referred to by
  58 .I fd
  59 (as returned by
  60 .BR open (2))
  61 is interrogated in place of
  62 .IR path .
  63 .PP
  64 An extended attribute
  65 .I name
  66 is a null-terminated string.
  67 The name includes a namespace prefix; there may be several, disjoint
  68 namespaces associated with an individual inode.
  69 The value of an extended attribute is a chunk of arbitrary textual or
  70 binary data that was assigned using
  71 .BR setxattr (2).
  72 .PP
  73 If
  74 .I size
  75 is specified as zero, these calls return the current size of the
  76 named extended attribute (and leave
  77 .I value
  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 attribute value may change between the two calls,
  83 so that it is still necessary to check the return status
  84 from the second call.)
  85 .SH RETURN VALUE
  86 On success, these calls return a nonnegative value which is
  87 the size (in bytes) of the extended attribute value.
  88 On failure, \-1 is returned and
  89 .I errno
  90 is set to indicate the error.
  91 .SH ERRORS
  92 .TP
  93 .B E2BIG
  94 The size of the attribute value is larger than the maximum size allowed; the
  95 attribute cannot be retrieved.
  96 This can happen on filesystems that support
  97 very large attribute values such as NFSv4, for example.
  98 .TP
  99 .B ENODATA
 100 The named attribute does not exist, or the process has no access to
 101 this attribute.
 102 .\" .RB ( ENOATTR
 103 .\" is defined to be a synonym for
 104 .\" .BR ENODATA
 105 .\" in
 106 .\" .IR <attr/attributes.h> .)
 107 .TP
 108 .B ENOTSUP
 109 Extended attributes are not supported by the filesystem, or are disabled.
 110 .TP
 111 .B ERANGE
 112 The
 113 .I size
 114 of the
 115 .I value
 116 buffer is too small to hold the result.
 117 .PP
 118 In addition, the errors documented in
 119 .BR stat (2)
 120 can also occur.
 121 .SH VERSIONS
 122 These system calls have been available on Linux since kernel 2.4;
 123 glibc support is provided since version 2.3.
 124 .SH STANDARDS
 125 These system calls are Linux-specific.
 126 .\" .SH AUTHORS
 127 .\" Andreas Gruenbacher,
 128 .\" .RI < a.gruenbacher@computer.org >
 129 .\" and the SGI XFS development team,
 130 .\" .RI < linux-xfs@oss.sgi.com >.
 131 .\" Please send any bug reports or comments to these addresses.
 132 .SH EXAMPLES
 133 See
 134 .BR listxattr (2).
 135 .SH SEE ALSO
 136 .BR getfattr (1),
 137 .BR setfattr (1),
 138 .BR listxattr (2),
 139 .BR open (2),
 140 .BR removexattr (2),
 141 .BR setxattr (2),
 142 .BR stat (2),
 143 .BR symlink (7),
 144 .BR xattr (7)