Debian Codegraph @

upstream/debian-unstable/man2/chmod.2

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