Debian Codegraph @

upstream/debian-unstable/man2/getxattr.2

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