]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
92f114db | 2 | .\" and Copyright (C) 2006, 2014 Michael Kerrisk |
fea681da | 3 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
5 | .\" |
6 | .\" Modified by Michael Haardt <michael@moria.de> | |
7 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
8 | .\" Modified 1997-01-12 by Michael Haardt | |
9 | .\" <michael@cantor.informatik.rwth-aachen.de>: NFS details | |
c11b1abf | 10 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 11 | .\" |
6e00b7a8 | 12 | .TH CHMOD 2 2021-08-27 "Linux" "Linux Programmer's Manual" |
fea681da | 13 | .SH NAME |
92f114db | 14 | chmod, fchmod, fchmodat \- change permissions of a file |
2411a568 AC |
15 | .SH LIBRARY |
16 | Standard C library | |
8fc3b2cf | 17 | .RI ( libc ", " \-lc ) |
fea681da | 18 | .SH SYNOPSIS |
92f114db | 19 | .nf |
fea681da | 20 | .B #include <sys/stat.h> |
68e4db0a | 21 | .PP |
b828fc25 | 22 | .BI "int chmod(const char *" pathname ", mode_t " mode ); |
47752f33 | 23 | .BI "int fchmod(int " fd ", mode_t " mode ); |
eaa18d3c | 24 | .PP |
92f114db MK |
25 | .BR "#include <fcntl.h>" " /* Definition of AT_* constants */" |
26 | .B #include <sys/stat.h> | |
68e4db0a | 27 | .PP |
92f114db MK |
28 | .BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \ |
29 | mode ", int " flags ); | |
30 | .fi | |
68e4db0a | 31 | .PP |
d39ad78f | 32 | .RS -4 |
cc4615cc MK |
33 | Feature Test Macro Requirements for glibc (see |
34 | .BR feature_test_macros (7)): | |
d39ad78f | 35 | .RE |
68e4db0a | 36 | .PP |
9d2adbae | 37 | .nf |
cc4615cc | 38 | .BR fchmod (): |
9d2adbae | 39 | Since glibc 2.24: |
5c10d2c5 | 40 | _POSIX_C_SOURCE >= 199309L |
d4afcdb4 | 41 | .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) |
9d2adbae MK |
42 | Glibc 2.19 to 2.23 |
43 | _POSIX_C_SOURCE | |
44 | Glibc 2.16 to 2.19: | |
45 | _BSD_SOURCE || _POSIX_C_SOURCE | |
46 | Glibc 2.12 to 2.16: | |
5c10d2c5 | 47 | _BSD_SOURCE || _XOPEN_SOURCE >= 500 |
58a6844d | 48 | || _POSIX_C_SOURCE >= 200809L |
9d2adbae | 49 | Glibc 2.11 and earlier: |
5c10d2c5 | 50 | _BSD_SOURCE || _XOPEN_SOURCE >= 500 |
7d34a794 | 51 | .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED) |
9d2adbae | 52 | .fi |
68e4db0a | 53 | .PP |
92f114db | 54 | .BR fchmodat (): |
9d2adbae MK |
55 | .nf |
56 | Since glibc 2.10: | |
5c10d2c5 | 57 | _POSIX_C_SOURCE >= 200809L |
9d2adbae MK |
58 | Before glibc 2.10: |
59 | _ATFILE_SOURCE | |
60 | .fi | |
fea681da | 61 | .SH DESCRIPTION |
3894e138 MK |
62 | The |
63 | .BR chmod () | |
64 | and | |
65 | .BR fchmod () | |
0eadc752 | 66 | system calls change a file's mode bits. |
698ac0e2 MK |
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: | |
0689a4da MK |
70 | .IP * 2 |
71 | .BR chmod () | |
698ac0e2 | 72 | changes the mode of the file specified whose pathname is given in |
b828fc25 | 73 | .IR pathname , |
0689a4da MK |
74 | which is dereferenced if it is a symbolic link. |
75 | .IP * | |
76 | .BR fchmod () | |
698ac0e2 | 77 | changes the mode of the file referred to by the open file descriptor |
0689a4da MK |
78 | .IR fd . |
79 | .PP | |
698ac0e2 | 80 | The new file mode is specified in |
0689a4da MK |
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)) | |
fea681da | 88 | .TP |
0689a4da MK |
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)) | |
fea681da | 98 | .TP |
0689a4da MK |
99 | .BR S_ISVTX " (01000)" |
100 | sticky bit (restricted deletion flag, as described in | |
101 | .BR unlink (2)) | |
fea681da | 102 | .TP |
0689a4da MK |
103 | .BR S_IRUSR " (00400)" |
104 | read by owner | |
fea681da | 105 | .TP |
0689a4da MK |
106 | .BR S_IWUSR " (00200)" |
107 | write by owner | |
fea681da | 108 | .TP |
0689a4da MK |
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) | |
fea681da | 112 | .TP |
0689a4da MK |
113 | .BR S_IRGRP " (00040)" |
114 | read by group | |
fea681da | 115 | .TP |
0689a4da MK |
116 | .BR S_IWGRP " (00020)" |
117 | write by group | |
fea681da | 118 | .TP |
0689a4da MK |
119 | .BR S_IXGRP " (00010)" |
120 | execute/search by group | |
fea681da | 121 | .TP |
0689a4da MK |
122 | .BR S_IROTH " (00004)" |
123 | read by others | |
fea681da | 124 | .TP |
0689a4da MK |
125 | .BR S_IWOTH " (00002)" |
126 | write by others | |
fea681da | 127 | .TP |
0689a4da MK |
128 | .BR S_IXOTH " (00001)" |
129 | execute/search by others | |
cf0a9ace | 130 | .PP |
fea681da MK |
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). | |
efeece04 | 135 | .PP |
fea681da MK |
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 | |
682edefb MK |
140 | supplementary group IDs, the |
141 | .B S_ISGID | |
142 | bit will be turned off, | |
fea681da | 143 | but this will not cause an error to be returned. |
efeece04 | 144 | .PP |
9ee4a2b6 | 145 | As a security measure, depending on the filesystem, |
c7400a2c | 146 | the set-user-ID and set-group-ID execution bits |
fea681da | 147 | may be turned off if a file is written. |
329ad271 | 148 | (On Linux, this occurs if the writing process does not have the |
fea681da MK |
149 | .B CAP_FSETID |
150 | capability.) | |
9ee4a2b6 | 151 | On some filesystems, only the superuser can set the sticky bit, |
fea681da | 152 | which may have a special meaning. |
c7400a2c | 153 | For the sticky bit, and for set-user-ID and set-group-ID bits on |
fea681da | 154 | directories, see |
e6fc1596 | 155 | .BR inode (7). |
efeece04 | 156 | .PP |
9ee4a2b6 | 157 | On NFS filesystems, restricting the permissions will immediately influence |
fea681da | 158 | already open files, because the access control is done on the server, but |
c13182ef MK |
159 | open files are maintained by the client. |
160 | Widening the permissions may be | |
fea681da | 161 | delayed for other clients if attribute caching is enabled on them. |
92f114db MK |
162 | .\" |
163 | .\" | |
164 | .SS fchmodat() | |
165 | The | |
166 | .BR fchmodat () | |
167 | system call operates in exactly the same way as | |
cadd38ba | 168 | .BR chmod (), |
92f114db | 169 | except for the differences described here. |
efeece04 | 170 | .PP |
92f114db MK |
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 | |
9d3ea7a2 | 178 | .BR chmod () |
92f114db | 179 | for a relative pathname). |
efeece04 | 180 | .PP |
92f114db MK |
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 | |
98d3114d | 191 | .BR chmod ()). |
efeece04 | 192 | .PP |
92f114db MK |
193 | If |
194 | .I pathname | |
195 | is absolute, then | |
196 | .I dirfd | |
197 | is ignored. | |
efeece04 | 198 | .PP |
92f114db MK |
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. | |
7a99cc77 MK |
208 | .PP |
209 | See | |
210 | .BR openat (2) | |
211 | for an explanation of the need for | |
212 | .BR fchmodat (). | |
47297adb | 213 | .SH RETURN VALUE |
c13182ef MK |
214 | On success, zero is returned. |
215 | On error, \-1 is returned, and | |
fea681da | 216 | .I errno |
f6a4078b | 217 | is set to indicate the error. |
fea681da | 218 | .SH ERRORS |
3894e138 MK |
219 | Depending on the filesystem, |
220 | errors other than those listed below can be returned. | |
efeece04 | 221 | .PP |
c13182ef | 222 | The more general errors for |
e511ffb6 | 223 | .BR chmod () |
fea681da | 224 | are listed below: |
fea681da MK |
225 | .TP |
226 | .B EACCES | |
227 | Search permission is denied on a component of the path prefix. | |
228 | (See also | |
ad7cc990 | 229 | .BR path_resolution (7).) |
fea681da | 230 | .TP |
90879cbd MK |
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 | |
fea681da | 246 | .B EFAULT |
b828fc25 | 247 | .I pathname |
fea681da MK |
248 | points outside your accessible address space. |
249 | .TP | |
90879cbd MK |
250 | .B EINVAL |
251 | .RB ( fchmodat ()) | |
252 | Invalid flag specified in | |
253 | .IR flags . | |
254 | .TP | |
fea681da MK |
255 | .B EIO |
256 | An I/O error occurred. | |
257 | .TP | |
258 | .B ELOOP | |
259 | Too many symbolic links were encountered in resolving | |
b828fc25 | 260 | .IR pathname . |
fea681da MK |
261 | .TP |
262 | .B ENAMETOOLONG | |
b828fc25 | 263 | .I pathname |
fea681da MK |
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 | |
90879cbd MK |
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 | |
fea681da MK |
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 | |
85342fa7 MK |
295 | .B EPERM |
296 | The file is marked immutable or append-only. | |
297 | (See | |
298 | .BR ioctl_iflags (2).) | |
299 | .TP | |
fea681da | 300 | .B EROFS |
9ee4a2b6 | 301 | The named file resides on a read-only filesystem. |
92f114db MK |
302 | .SH VERSIONS |
303 | .BR fchmodat () | |
304 | was added to Linux in kernel 2.6.16; | |
305 | library support was added to glibc in version 2.4. | |
47297adb | 306 | .SH CONFORMING TO |
92f114db MK |
307 | .BR chmod (), |
308 | .BR fchmod (): | |
5dec01d6 | 309 | 4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008. |
efeece04 | 310 | .PP |
92f114db MK |
311 | .BR fchmodat (): |
312 | POSIX.1-2008. | |
313 | .SH NOTES | |
0722a578 | 314 | .SS C library/kernel differences |
7a99cc77 MK |
315 | The GNU C library |
316 | .BR fchmodat () | |
317 | wrapper function implements the POSIX-specified | |
92f114db MK |
318 | interface described in this page. |
319 | This interface differs from the underlying Linux system call, which does | |
320 | .I not | |
321 | have a | |
322 | .I flags | |
323 | argument. | |
782d6223 MK |
324 | .SS Glibc notes |
325 | On older kernels where | |
326 | .BR fchmodat () | |
327 | is unavailable, the glibc wrapper function falls back to the use of | |
328 | .BR chmod (). | |
329 | When | |
330 | .I pathname | |
331 | is a relative pathname, | |
332 | glibc constructs a pathname based on the symbolic link in | |
1ae6b2c7 | 333 | .I /proc/self/fd |
782d6223 | 334 | that corresponds to the |
1ae6b2c7 | 335 | .I dirfd |
782d6223 | 336 | argument. |
47297adb | 337 | .SH SEE ALSO |
3dd7a7ee | 338 | .BR chmod (1), |
fea681da MK |
339 | .BR chown (2), |
340 | .BR execve (2), | |
341 | .BR open (2), | |
ad7cc990 | 342 | .BR stat (2), |
e6fc1596 | 343 | .BR inode (7), |
92f114db MK |
344 | .BR path_resolution (7), |
345 | .BR symlink (7) |