Debian Codegraph @

upstream/debian-trixie/man2/chmod.2

raw
1 .\" Copyright (c) 1992 Drew Eckhardt ([email protected]), March 28, 1992
2 .\" and Copyright (C) 2006, 2014 Michael Kerrisk
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Modified by Michael Haardt <[email protected]>
7 .\" Modified 1993-07-21 by Rik Faith <[email protected]>
8 .\" Modified 1997-01-12 by Michael Haardt
9 .\" <[email protected]>: NFS details
10 .\" Modified 2004-06-23 by Michael Kerrisk <[email protected]>
11 .\"
12 .TH chmod 2 2024-06-13 "Linux man-pages 6.9.1"
13 .SH NAME
14 chmod, fchmod, fchmodat \- change permissions of a file
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <sys/stat.h>
21 .P
22 .BI "int chmod(const char *" pathname ", mode_t " mode );
23 .BI "int fchmod(int " fd ", mode_t " mode );
24 .P
25 .BR "#include <fcntl.h>" " /* Definition of AT_* constants */"
26 .B #include <sys/stat.h>
27 .P
28 .BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \
29 mode ", int " flags );
30 .fi
31 .P
32 .RS -4
33 Feature Test Macro Requirements for glibc (see
34 .BR feature_test_macros (7)):
35 .RE
36 .P
37 .nf
38 .BR fchmod ():
39 Since glibc 2.24:
40 _POSIX_C_SOURCE >= 199309L
41 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
42 glibc 2.19 to glibc 2.23
43 _POSIX_C_SOURCE
44 glibc 2.16 to glibc 2.19:
45 _BSD_SOURCE || _POSIX_C_SOURCE
46 glibc 2.12 to glibc 2.16:
47 _BSD_SOURCE || _XOPEN_SOURCE >= 500
48 || _POSIX_C_SOURCE >= 200809L
49 glibc 2.11 and earlier:
50 _BSD_SOURCE || _XOPEN_SOURCE >= 500
51 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
52 .fi
53 .P
54 .BR fchmodat ():
55 .nf
56 Since glibc 2.10:
57 _POSIX_C_SOURCE >= 200809L
58 Before glibc 2.10:
59 _ATFILE_SOURCE
60 .fi
61 .SH DESCRIPTION
62 The
63 .BR chmod ()
64 and
65 .BR fchmod ()
66 system calls change a file's mode bits.
67 (The file mode consists of the file permission bits plus the set-user-ID,
68 set-group-ID, and sticky bits.)
69 These system calls differ only in how the file is specified:
70 .IP \[bu] 3
71 .BR chmod ()
72 changes the mode of the file specified whose pathname is given in
73 .IR pathname ,
74 which is dereferenced if it is a symbolic link.
75 .IP \[bu]
76 .BR fchmod ()
77 changes the mode of the file referred to by the open file descriptor
78 .IR fd .
79 .P
80 The new file mode is specified in
81 .IR mode ,
82 which is a bit mask created by ORing together zero or
83 more of the following:
84 .TP 18
85 .BR S_ISUID " (04000)"
86 set-user-ID (set process effective user ID on
87 .BR execve (2))
88 .TP
89 .BR S_ISGID " (02000)"
90 set-group-ID (set process effective group ID on
91 .BR execve (2);
92 mandatory locking, as described in
93 .BR fcntl (2);
94 take a new file's group from parent directory, as described in
95 .BR chown (2)
96 and
97 .BR mkdir (2))
98 .TP
99 .BR S_ISVTX " (01000)"
100 sticky bit (restricted deletion flag, as described in
101 .BR unlink (2))
102 .TP
103 .BR S_IRUSR " (00400)"
104 read by owner
105 .TP
106 .BR S_IWUSR " (00200)"
107 write by owner
108 .TP
109 .BR S_IXUSR " (00100)"
110 execute/search by owner ("search" applies for directories,
111 and means that entries within the directory can be accessed)
112 .TP
113 .BR S_IRGRP " (00040)"
114 read by group
115 .TP
116 .BR S_IWGRP " (00020)"
117 write by group
118 .TP
119 .BR S_IXGRP " (00010)"
120 execute/search by group
121 .TP
122 .BR S_IROTH " (00004)"
123 read by others
124 .TP
125 .BR S_IWOTH " (00002)"
126 write by others
127 .TP
128 .BR S_IXOTH " (00001)"
129 execute/search by others
130 .P
131 The effective UID of the calling process must match the owner of the file,
132 or the process must be privileged (Linux: it must have the
133 .B CAP_FOWNER
134 capability).
135 .P
136 If the calling process is not privileged (Linux: does not have the
137 .B CAP_FSETID
138 capability), and the group of the file does not match
139 the effective group ID of the process or one of its
140 supplementary group IDs, the
141 .B S_ISGID
142 bit will be turned off,
143 but this will not cause an error to be returned.
144 .P
145 As a security measure, depending on the filesystem,
146 the set-user-ID and set-group-ID execution bits
147 may be turned off if a file is written.
148 (On Linux, this occurs if the writing process does not have the
149 .B CAP_FSETID
150 capability.)
151 On some filesystems, only the superuser can set the sticky bit,
152 which may have a special meaning.
153 For the sticky bit, and for set-user-ID and set-group-ID bits on
154 directories, see
155 .BR inode (7).
156 .P
157 On NFS filesystems, restricting the permissions will immediately influence
158 already open files, because the access control is done on the server, but
159 open files are maintained by the client.
160 Widening the permissions may be
161 delayed for other clients if attribute caching is enabled on them.
162 .\"
163 .\"
164 .SS fchmodat()
165 The
166 .BR fchmodat ()
167 system call operates in exactly the same way as
168 .BR chmod (),
169 except for the differences described here.
170 .P
171 If the pathname given in
172 .I pathname
173 is relative, then it is interpreted relative to the directory
174 referred to by the file descriptor
175 .I dirfd
176 (rather than relative to the current working directory of
177 the calling process, as is done by
178 .BR chmod ()
179 for a relative pathname).
180 .P
181 If
182 .I pathname
183 is relative and
184 .I dirfd
185 is the special value
186 .BR AT_FDCWD ,
187 then
188 .I pathname
189 is interpreted relative to the current working
190 directory of the calling process (like
191 .BR chmod ()).
192 .P
193 If
194 .I pathname
195 is absolute, then
196 .I dirfd
197 is ignored.
198 .P
199 .I flags
200 can either be 0, or include the following flag:
201 .TP
202 .B AT_SYMLINK_NOFOLLOW
203 If
204 .I pathname
205 is a symbolic link, do not dereference it:
206 instead operate on the link itself.
207 This flag is not currently implemented.
208 .P
209 See
210 .BR openat (2)
211 for an explanation of the need for
212 .BR fchmodat ().
213 .SH RETURN VALUE
214 On success, zero is returned.
215 On error, \-1 is returned, and
216 .I errno
217 is set to indicate the error.
218 .SH ERRORS
219 Depending on the filesystem,
220 errors other than those listed below can be returned.
221 .P
222 The more general errors for
223 .BR chmod ()
224 are listed below:
225 .TP
226 .B EACCES
227 Search permission is denied on a component of the path prefix.
228 (See also
229 .BR path_resolution (7).)
230 .TP
231 .B EBADF
232 .RB ( fchmod ())
233 The file descriptor
234 .I fd
235 is not valid.
236 .TP
237 .B EBADF
238 .RB ( fchmodat ())
239 .I pathname
240 is relative but
241 .I dirfd
242 is neither
243 .B AT_FDCWD
244 nor a valid file descriptor.
245 .TP
246 .B EFAULT
247 .I pathname
248 points outside your accessible address space.
249 .TP
250 .B EINVAL
251 .RB ( fchmodat ())
252 Invalid flag specified in
253 .IR flags .
254 .TP
255 .B EIO
256 An I/O error occurred.
257 .TP
258 .B ELOOP
259 Too many symbolic links were encountered in resolving
260 .IR pathname .
261 .TP
262 .B ENAMETOOLONG
263 .I pathname
264 is too long.
265 .TP
266 .B ENOENT
267 The file does not exist.
268 .TP
269 .B ENOMEM
270 Insufficient kernel memory was available.
271 .TP
272 .B ENOTDIR
273 A component of the path prefix is not a directory.
274 .TP
275 .B ENOTDIR
276 .RB ( fchmodat ())
277 .I pathname
278 is relative and
279 .I dirfd
280 is a file descriptor referring to a file other than a directory.
281 .TP
282 .B ENOTSUP
283 .RB ( fchmodat ())
284 .I flags
285 specified
286 .BR AT_SYMLINK_NOFOLLOW ,
287 which is not supported.
288 .TP
289 .B EPERM
290 The effective UID does not match the owner of the file,
291 and the process is not privileged (Linux: it does not have the
292 .B CAP_FOWNER
293 capability).
294 .TP
295 .B EPERM
296 The file is marked immutable or append-only.
297 (See
298 .BR FS_IOC_SETFLAGS (2const).)
299 .TP
300 .B EROFS
301 The named file resides on a read-only filesystem.
302 .SH VERSIONS
303 .SS C library/kernel differences
304 The GNU C library
305 .BR fchmodat ()
306 wrapper function implements the POSIX-specified
307 interface described in this page.
308 This interface differs from the underlying Linux system call, which does
309 .I not
310 have a
311 .I flags
312 argument.
313 .SS glibc notes
314 On older kernels where
315 .BR fchmodat ()
316 is unavailable, the glibc wrapper function falls back to the use of
317 .BR chmod ().
318 When
319 .I pathname
320 is a relative pathname,
321 glibc constructs a pathname based on the symbolic link in
322 .I /proc/self/fd
323 that corresponds to the
324 .I dirfd
325 argument.
326 .SH STANDARDS
327 POSIX.1-2008.
328 .SH HISTORY
329 .TP
330 .BR chmod ()
331 .TQ
332 .BR fchmod ()
333 4.4BSD, SVr4, POSIX.1-2001.
334 .TP
335 .BR fchmodat ()
336 POSIX.1-2008.
337 Linux 2.6.16,
338 glibc 2.4.
339 .SH SEE ALSO
340 .BR chmod (1),
341 .BR chown (2),
342 .BR execve (2),
343 .BR open (2),
344 .BR stat (2),
345 .BR inode (7),
346 .BR path_resolution (7),
347 .BR symlink (7)