Debian Codegraph @

upstream/debian-trixie/man2/getxattr.2

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