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