Debian Codegraph @

upstream/debian-unstable/man2/setxattr.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 setxattr 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 setxattr, lsetxattr, fsetxattr \- set 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 "int setxattr(" "size_t size;"
18 .BI " const char *" path ", const char *" name ,
19 .BI " const void " value [ size "], size_t " size ", int " flags );
20 .BR "int lsetxattr(" "size_t size;"
21 .BI " const char *" path ", const char *" name ,
22 .BI " const void " value [ size "], size_t " size ", int " flags );
23 .BR "int fsetxattr(" "size_t size;"
24 .BI " int " fd ", const char *" name ,
25 .BI " const void " value [ size "], size_t " size ", int " flags );
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 setxattr ()
39 sets the
40 .I value
41 of the extended attribute identified by
42 .I name
43 and associated with the given
44 .I path
45 in the filesystem.
46 The
47 .I size
48 argument specifies the size (in bytes) of
49 .IR value ;
50 a zero-length value is permitted.
51 .P
52 .BR lsetxattr ()
53 is identical to
54 .BR setxattr (),
55 except in the case of a symbolic link, where the extended attribute is
56 set on the link itself, not the file that it refers to.
57 .P
58 .BR fsetxattr ()
59 is identical to
60 .BR setxattr (),
61 only the extended attribute is set on the open file referred to by
62 .I fd
63 (as returned by
64 .BR open (2))
65 in place of
66 .IR path .
67 .P
68 An extended attribute name is a null-terminated string.
69 The
70 .I name
71 includes a namespace prefix;
72 there may be several,
73 disjoint namespaces associated with an individual inode.
74 The
75 .I value
76 of an extended attribute is a chunk of arbitrary textual or
77 binary data of specified length.
78 .P
79 By default
80 (i.e.,
81 .I flags
82 is zero),
83 the extended attribute will be created if it does not exist,
84 or the value will be replaced if the attribute already exists.
85 To modify these semantics, one of the following values can be specified in
86 .IR flags :
87 .TP
88 .B XATTR_CREATE
89 Perform a pure create, which fails if the named attribute exists already.
90 .TP
91 .B XATTR_REPLACE
92 Perform a pure replace operation,
93 which fails if the named attribute does not already exist.
94 .SH RETURN VALUE
95 On success, zero is returned.
96 On failure, \-1 is returned and
97 .I errno
98 is set to indicate the error.
99 .SH ERRORS
100 .TP
101 .B EDQUOT
102 Disk quota limits meant that
103 there is insufficient space remaining to store the extended attribute.
104 .TP
105 .B EEXIST
106 .B XATTR_CREATE
107 was specified, and the attribute exists already.
108 .TP
109 .B ENODATA
110 .B XATTR_REPLACE
111 was specified, and the attribute does not exist.
112 .\" .RB ( ENOATTR
113 .\" is defined to be a synonym for
114 .\" .BR ENODATA
115 .\" in
116 .\" .IR <attr/attributes.h> .)
117 .TP
118 .B ENOSPC
119 There is insufficient space remaining to store the extended attribute.
120 .TP
121 .B ENOTSUP
122 The namespace prefix of
123 .I name
124 is not valid.
125 .TP
126 .B ENOTSUP
127 Extended attributes are not supported by the filesystem, or are disabled,
128 .TP
129 .B EPERM
130 The file is marked immutable or append-only.
131 (See
132 .BR FS_IOC_SETFLAGS (2const).)
133 .P
134 In addition, the errors documented in
135 .BR stat (2)
136 can also occur.
137 .TP
138 .B ERANGE
139 The size of
140 .I name
141 or
142 .I value
143 exceeds a filesystem-specific limit.
144 .SH STANDARDS
145 Linux.
146 .SH HISTORY
147 Linux 2.4,
148 glibc 2.3.
149 .\" .SH AUTHORS
150 .\" Andreas Gruenbacher,
151 .\" .RI < [email protected] >
152 .\" and the SGI XFS development team,
153 .\" .RI < [email protected] >.
154 .\" Please send any bug reports or comments to these addresses.
155 .SH SEE ALSO
156 .BR getfattr (1),
157 .BR setfattr (1),
158 .BR getxattr (2),
159 .BR listxattr (2),
160 .BR open (2),
161 .BR removexattr (2),
162 .BR stat (2),
163 .BR symlink (7),
164 .BR xattr (7)