]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
6a2df4ee | 2 | .\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl) |
0b4b6235 | 3 | .\" and Copyright (c) 2006, 2007, 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
26 | .\" |
27 | .\" Modified by Michael Haardt <michael@moria.de> | |
28 | .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu> | |
29 | .\" Modified 1996-07-09 by Andries Brouwer <aeb@cwi.nl> | |
30 | .\" Modified 1996-11-06 by Eric S. Raymond <esr@thyrsus.com> | |
31 | .\" Modified 1997-05-18 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de> | |
c11b1abf | 32 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
6a2df4ee | 33 | .\" 2007-07-08, mtk, added an example program; updated SYNOPSIS |
bf1082be MK |
34 | .\" 2008-05-08, mtk, Describe rules governing ownership of new files |
35 | .\" (bsdgroups versus sysvgroups, and the effect of the parent | |
ed948c28 | 36 | .\" directory's set-group-ID mode bit). |
fea681da | 37 | .\" |
9ba01802 | 38 | .TH CHOWN 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da | 39 | .SH NAME |
0b4b6235 | 40 | chown, fchown, lchown, fchownat \- change ownership of a file |
fea681da | 41 | .SH SYNOPSIS |
0b4b6235 | 42 | .nf |
fea681da | 43 | .B #include <unistd.h> |
009a7c83 | 44 | .PP |
cbf12fca | 45 | .BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group ); |
fea681da | 46 | .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group ); |
cbf12fca | 47 | .BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group ); |
009a7c83 | 48 | |
0b4b6235 MK |
49 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
50 | .B #include <unistd.h> | |
009a7c83 | 51 | .PP |
0b4b6235 MK |
52 | .BI "int fchownat(int " dirfd ", const char *" pathname , |
53 | .BI " uid_t " owner ", gid_t " group ", int " flags ); | |
54 | .fi | |
009a7c83 | 55 | .PP |
cc4615cc MK |
56 | .in -4n |
57 | Feature Test Macro Requirements for glibc (see | |
58 | .BR feature_test_macros (7)): | |
59 | .in | |
009a7c83 | 60 | .PP |
cc4615cc MK |
61 | .BR fchown (), |
62 | .BR lchown (): | |
51c8e668 MK |
63 | .PD 0 |
64 | .ad l | |
65 | .RS 4 | |
bc3e200e MK |
66 | /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L |
67 | || _XOPEN_SOURCE\ >=\ 500 | |
cf7fa0a1 | 68 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED |
bc3e200e | 69 | || /* Glibc versions <= 2.19: */ _BSD_SOURCE |
51c8e668 | 70 | .RE |
009a7c83 | 71 | .PP |
0b4b6235 MK |
72 | .BR fchownat (): |
73 | .PD 0 | |
74 | .ad l | |
75 | .RS 4 | |
76 | .TP 4 | |
77 | Since glibc 2.10: | |
b0da7b8b | 78 | _POSIX_C_SOURCE\ >=\ 200809L |
0b4b6235 MK |
79 | .TP |
80 | Before glibc 2.10: | |
81 | _ATFILE_SOURCE | |
82 | .RE | |
51c8e668 MK |
83 | .ad |
84 | .PD | |
fea681da | 85 | .SH DESCRIPTION |
bf1082be | 86 | These system calls change the owner and group of a file. |
2dc723cf MK |
87 | The |
88 | .BR chown (), | |
89 | .BR fchown (), | |
90 | and | |
91 | .BR lchown () | |
92 | system calls differ only in how the file is specified: | |
bf1082be MK |
93 | .IP * 2 |
94 | .BR chown () | |
95 | changes the ownership of the file specified by | |
cbf12fca | 96 | .IR pathname , |
bf1082be MK |
97 | which is dereferenced if it is a symbolic link. |
98 | .IP * | |
99 | .BR fchown () | |
100 | changes the ownership of the file referred to by the open file descriptor | |
fea681da | 101 | .IR fd . |
bf1082be MK |
102 | .IP * |
103 | .BR lchown () | |
104 | is like | |
105 | .BR chown (), | |
106 | but does not dereference symbolic links. | |
107 | .PP | |
fea681da MK |
108 | Only a privileged process (Linux: one with the |
109 | .B CAP_CHOWN | |
110 | capability) may change the owner of a file. | |
111 | The owner of a file may change the group of the file | |
112 | to any group of which that owner is a member. | |
113 | A privileged process (Linux: with | |
114 | .BR CAP_CHOWN ) | |
115 | may change the group arbitrarily. | |
009a7c83 | 116 | .PP |
fea681da MK |
117 | If the |
118 | .I owner | |
119 | or | |
120 | .I group | |
121 | is specified as \-1, then that ID is not changed. | |
009a7c83 | 122 | .PP |
42147607 MK |
123 | When the owner or group of an executable file is |
124 | changed by an unprivileged user, the | |
682edefb MK |
125 | .B S_ISUID |
126 | and | |
127 | .B S_ISGID | |
128 | mode bits are cleared. | |
c13182ef | 129 | POSIX does not specify whether |
fea681da | 130 | this also should happen when root does the |
e1d6264d | 131 | .BR chown (); |
fbfbde8f MK |
132 | the Linux behavior depends on the kernel version, |
133 | and since Linux 2.2.13, root is treated like other users. | |
fea681da MK |
134 | .\" In Linux 2.0 kernels, superuser was like everyone else |
135 | .\" In 2.2, up to 2.2.12, these bits were not cleared for superuser. | |
136 | .\" Since 2.2.13, superuser is once more like everyone else. | |
eacd521c | 137 | In case of a non-group-executable file (i.e., one for which the |
682edefb | 138 | .B S_IXGRP |
eacd521c | 139 | bit is not set) the |
682edefb MK |
140 | .B S_ISGID |
141 | bit indicates mandatory locking, and is not cleared by a | |
e1d6264d | 142 | .BR chown (). |
009a7c83 | 143 | .PP |
b9472299 MK |
144 | When the owner or group of an executable file is changed (by any user), |
145 | all capability sets for the file are cleared. | |
146 | .\" | |
0b4b6235 MK |
147 | .SS fchownat() |
148 | The | |
149 | .BR fchownat () | |
150 | system call operates in exactly the same way as | |
cadd38ba | 151 | .BR chown (), |
0b4b6235 | 152 | except for the differences described here. |
009a7c83 | 153 | .PP |
0b4b6235 MK |
154 | If the pathname given in |
155 | .I pathname | |
156 | is relative, then it is interpreted relative to the directory | |
157 | referred to by the file descriptor | |
158 | .I dirfd | |
159 | (rather than relative to the current working directory of | |
160 | the calling process, as is done by | |
9d3ea7a2 | 161 | .BR chown () |
0b4b6235 | 162 | for a relative pathname). |
009a7c83 | 163 | .PP |
0b4b6235 MK |
164 | If |
165 | .I pathname | |
166 | is relative and | |
167 | .I dirfd | |
168 | is the special value | |
169 | .BR AT_FDCWD , | |
170 | then | |
171 | .I pathname | |
172 | is interpreted relative to the current working | |
173 | directory of the calling process (like | |
98d3114d | 174 | .BR chown ()). |
009a7c83 | 175 | .PP |
0b4b6235 MK |
176 | If |
177 | .I pathname | |
178 | is absolute, then | |
179 | .I dirfd | |
180 | is ignored. | |
009a7c83 | 181 | .PP |
0b4b6235 MK |
182 | The |
183 | .I flags | |
184 | argument is a bit mask created by ORing together | |
185 | 0 or more of the following values; | |
186 | .TP | |
187 | .BR AT_EMPTY_PATH " (since Linux 2.6.39)" | |
188 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
189 | If | |
190 | .I pathname | |
191 | is an empty string, operate on the file referred to by | |
192 | .IR dirfd | |
193 | (which may have been obtained using the | |
194 | .BR open (2) | |
195 | .B O_PATH | |
196 | flag). | |
197 | In this case, | |
198 | .I dirfd | |
199 | can refer to any type of file, not just a directory. | |
481142b9 MK |
200 | If |
201 | .I dirfd | |
202 | is | |
203 | .BR AT_FDCWD , | |
204 | the call operates on the current working directory. | |
0b4b6235 MK |
205 | This flag is Linux-specific; define |
206 | .B _GNU_SOURCE | |
207 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
208 | to obtain its definition. | |
0b4b6235 MK |
209 | .TP |
210 | .B AT_SYMLINK_NOFOLLOW | |
211 | If | |
212 | .I pathname | |
213 | is a symbolic link, do not dereference it: | |
214 | instead operate on the link itself, like | |
9d3ea7a2 | 215 | .BR lchown (). |
0b4b6235 MK |
216 | (By default, |
217 | .BR fchownat () | |
218 | dereferences symbolic links, like | |
9d3ea7a2 | 219 | .BR chown ().) |
0b4b6235 MK |
220 | .PP |
221 | See | |
222 | .BR openat (2) | |
223 | for an explanation of the need for | |
224 | .BR fchownat (). | |
47297adb | 225 | .SH RETURN VALUE |
c13182ef MK |
226 | On success, zero is returned. |
227 | On error, \-1 is returned, and | |
fea681da MK |
228 | .I errno |
229 | is set appropriately. | |
230 | .SH ERRORS | |
2dc723cf MK |
231 | Depending on the filesystem, |
232 | errors other than those listed below can be returned. | |
009a7c83 | 233 | .PP |
c13182ef | 234 | The more general errors for |
e511ffb6 | 235 | .BR chown () |
fea681da MK |
236 | are listed below. |
237 | .TP | |
238 | .B EACCES | |
239 | Search permission is denied on a component of the path prefix. | |
240 | (See also | |
ad7cc990 | 241 | .BR path_resolution (7).) |
fea681da MK |
242 | .TP |
243 | .B EFAULT | |
cbf12fca | 244 | .I pathname |
fea681da MK |
245 | points outside your accessible address space. |
246 | .TP | |
247 | .B ELOOP | |
248 | Too many symbolic links were encountered in resolving | |
cbf12fca | 249 | .IR pathname . |
fea681da MK |
250 | .TP |
251 | .B ENAMETOOLONG | |
cbf12fca | 252 | .I pathname |
fea681da MK |
253 | is too long. |
254 | .TP | |
255 | .B ENOENT | |
256 | The file does not exist. | |
257 | .TP | |
258 | .B ENOMEM | |
259 | Insufficient kernel memory was available. | |
260 | .TP | |
261 | .B ENOTDIR | |
262 | A component of the path prefix is not a directory. | |
263 | .TP | |
264 | .B EPERM | |
265 | The calling process did not have the required permissions | |
266 | (see above) to change owner and/or group. | |
267 | .TP | |
6f943334 MK |
268 | .B EPERM |
269 | The file is marked immutable or append-only. | |
270 | (See | |
271 | .BR ioctl_iflags (2).) | |
272 | .TP | |
fea681da | 273 | .B EROFS |
9ee4a2b6 | 274 | The named file resides on a read-only filesystem. |
fea681da MK |
275 | .PP |
276 | The general errors for | |
e511ffb6 | 277 | .BR fchown () |
fea681da MK |
278 | are listed below: |
279 | .TP | |
280 | .B EBADF | |
ad3450b9 MK |
281 | .I fd |
282 | is not a valid open file descriptor. | |
fea681da MK |
283 | .TP |
284 | .B EIO | |
285 | A low-level I/O error occurred while modifying the inode. | |
286 | .TP | |
287 | .B ENOENT | |
288 | See above. | |
289 | .TP | |
290 | .B EPERM | |
291 | See above. | |
292 | .TP | |
293 | .B EROFS | |
294 | See above. | |
0b4b6235 MK |
295 | .PP |
296 | The same errors that occur for | |
9d3ea7a2 | 297 | .BR chown () |
0b4b6235 MK |
298 | can also occur for |
299 | .BR fchownat (). | |
300 | The following additional errors can occur for | |
301 | .BR fchownat (): | |
302 | .TP | |
303 | .B EBADF | |
304 | .I dirfd | |
305 | is not a valid file descriptor. | |
306 | .TP | |
307 | .B EINVAL | |
308 | Invalid flag specified in | |
309 | .IR flags . | |
310 | .TP | |
311 | .B ENOTDIR | |
312 | .I pathname | |
313 | is relative and | |
314 | .I dirfd | |
315 | is a file descriptor referring to a file other than a directory. | |
316 | .SH VERSIONS | |
317 | .BR fchownat () | |
318 | was added to Linux in kernel 2.6.16; | |
319 | library support was added to glibc in version 2.4. | |
47297adb | 320 | .SH CONFORMING TO |
0b4b6235 MK |
321 | .BR chown (), |
322 | .BR fchown (), | |
323 | .BR lchown (): | |
ed8680a8 | 324 | 4.4BSD, SVr4, POSIX.1-2001, POSIX.1-2008. |
009a7c83 | 325 | .PP |
33a0ccb2 MK |
326 | The 4.4BSD version can be |
327 | used only by the superuser (that is, ordinary users cannot give away files). | |
a1d5f77c MK |
328 | .\" chown(): |
329 | .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no | |
330 | .\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions. | |
331 | .\" fchown(): | |
332 | .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK | |
333 | .\" error conditions. | |
009a7c83 | 334 | .PP |
0b4b6235 MK |
335 | .BR fchownat (): |
336 | POSIX.1-2008. | |
fea681da | 337 | .SH NOTES |
cc0b8800 | 338 | .SS Ownership of new files |
bf1082be MK |
339 | When a new file is created (by, for example, |
340 | .BR open (2) | |
341 | or | |
342 | .BR mkdir (2)), | |
9ee4a2b6 | 343 | its owner is made the same as the filesystem user ID of the |
bf1082be MK |
344 | creating process. |
345 | The group of the file depends on a range of factors, | |
9ee4a2b6 MK |
346 | including the type of filesystem, |
347 | the options used to mount the filesystem, | |
ed948c28 | 348 | and whether or not the set-group-ID mode bit is enabled |
bf1082be | 349 | on the parent directory. |
9ee4a2b6 | 350 | If the filesystem supports the |
1ec37705 | 351 | .B "\-o\ grpid" |
bf1082be | 352 | (or, synonymously |
1ec37705 | 353 | .BR "\-o\ bsdgroups" ) |
bf1082be | 354 | and |
1ec37705 | 355 | .B "\-o\ nogrpid" |
bf1082be | 356 | (or, synonymously |
1ec37705 | 357 | .BR "\-o\ sysvgroups" ) |
bf1082be MK |
358 | .BR mount (8) |
359 | options, then the rules are as follows: | |
360 | .IP * 2 | |
9ee4a2b6 | 361 | If the filesystem is mounted with |
1ec37705 | 362 | .BR "\-o\ grpid" , |
bf1082be MK |
363 | then the group of a new file is made |
364 | the same as that of the parent directory. | |
365 | .IP * | |
9ee4a2b6 | 366 | If the filesystem is mounted with |
1ec37705 | 367 | .BR "\-o\ nogrpid" |
bf1082be MK |
368 | and the set-group-ID bit is disabled on the parent directory, |
369 | then the group of a new file is made the same as the | |
9ee4a2b6 | 370 | process's filesystem GID. |
bf1082be | 371 | .IP * |
9ee4a2b6 | 372 | If the filesystem is mounted with |
1ec37705 | 373 | .BR "\-o\ nogrpid" |
bf1082be MK |
374 | and the set-group-ID bit is enabled on the parent directory, |
375 | then the group of a new file is made | |
376 | the same as that of the parent directory. | |
377 | .PP | |
928cf452 | 378 | As at Linux 4.12, |
a1d5601b | 379 | the |
1ec37705 | 380 | .BR "\-o\ grpid" |
bf1082be | 381 | and |
1ec37705 | 382 | .BR "\-o\ nogrpid" |
bf1082be | 383 | mount options are supported by ext2, ext3, ext4, and XFS. |
9ee4a2b6 | 384 | Filesystems that don't support these mount options follow the |
1ec37705 | 385 | .BR "\-o\ nogrpid" |
bf1082be | 386 | rules. |
375ef286 MK |
387 | .SS Glibc notes |
388 | On older kernels where | |
389 | .BR fchownat () | |
390 | is unavailable, the glibc wrapper function falls back to the use of | |
391 | .BR chown () | |
392 | and | |
393 | .BR lchown (). | |
394 | When | |
395 | .I pathname | |
396 | is a relative pathname, | |
397 | glibc constructs a pathname based on the symbolic link in | |
398 | .IR /proc/self/fd | |
399 | that corresponds to the | |
400 | .IR dirfd | |
401 | argument. | |
cc0b8800 | 402 | .SS NFS |
b07cd0a9 MK |
403 | The |
404 | .BR chown () | |
9ee4a2b6 | 405 | semantics are deliberately violated on NFS filesystems |
b07cd0a9 MK |
406 | which have UID mapping enabled. |
407 | Additionally, the semantics of all system | |
408 | calls which access the file contents are violated, because | |
409 | .BR chown () | |
410 | may cause immediate access revocation on already open files. | |
411 | Client side | |
412 | caching may lead to a delay between the time where ownership have | |
413 | been changed to allow access for a user and the time where the file can | |
414 | actually be accessed by the user on other clients. | |
cc0b8800 MK |
415 | .SS Historical details |
416 | The original Linux | |
417 | .BR chown (), | |
418 | .BR fchown (), | |
419 | and | |
420 | .BR lchown () | |
421 | system calls supported only 16-bit user and group IDs. | |
422 | Subsequently, Linux 2.4 added | |
423 | .BR chown32 (), | |
424 | .BR fchown32 (), | |
425 | and | |
426 | .BR lchown32 (), | |
427 | supporting 32-bit IDs. | |
428 | The glibc | |
429 | .BR chown (), | |
430 | .BR fchown (), | |
431 | and | |
432 | .BR lchown () | |
433 | wrapper functions transparently deal with the variations across kernel versions. | |
009a7c83 | 434 | .PP |
fea681da | 435 | In versions of Linux prior to 2.1.81 (and distinct from 2.1.46), |
e511ffb6 | 436 | .BR chown () |
fea681da MK |
437 | did not follow symbolic links. |
438 | Since Linux 2.1.81, | |
e511ffb6 | 439 | .BR chown () |
fea681da | 440 | does follow symbolic links, and there is a new system call |
e511ffb6 | 441 | .BR lchown () |
fea681da MK |
442 | that does not follow symbolic links. |
443 | Since Linux 2.1.86, this new call (that has the same semantics | |
444 | as the old | |
e511ffb6 | 445 | .BR chown ()) |
fea681da | 446 | has got the same syscall number, and |
e511ffb6 | 447 | .BR chown () |
fea681da | 448 | got the newly introduced number. |
6a2df4ee MK |
449 | .SH EXAMPLE |
450 | .PP | |
451 | The following program changes the ownership of the file named in | |
452 | its second command-line argument to the value specified in its | |
1e50031b | 453 | first command-line argument. |
6a2df4ee MK |
454 | The new owner can be specified either as a numeric user ID, |
455 | or as a username (which is converted to a user ID by using | |
456 | .BR getpwnam (3) | |
457 | to perform a lookup in the system password file). | |
f30b7415 | 458 | .SS Program source |
009a7c83 | 459 | .EX |
6a2df4ee MK |
460 | #include <pwd.h> |
461 | #include <stdio.h> | |
462 | #include <stdlib.h> | |
463 | #include <unistd.h> | |
464 | ||
465 | int | |
466 | main(int argc, char *argv[]) | |
467 | { | |
468 | uid_t uid; | |
469 | struct passwd *pwd; | |
470 | char *endptr; | |
471 | ||
d1a71985 MK |
472 | if (argc != 3 || argv[1][0] == \(aq\e0\(aq) { |
473 | fprintf(stderr, "%s <owner> <file>\en", argv[0]); | |
6a2df4ee MK |
474 | exit(EXIT_FAILURE); |
475 | } | |
476 | ||
477 | uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */ | |
478 | ||
d1a71985 | 479 | if (*endptr != \(aq\e0\(aq) { /* Was not pure numeric string */ |
0adc4176 | 480 | pwd = getpwnam(argv[1]); /* Try getting UID for username */ |
6a2df4ee MK |
481 | if (pwd == NULL) { |
482 | perror("getpwnam"); | |
483 | exit(EXIT_FAILURE); | |
484 | } | |
485 | ||
486 | uid = pwd\->pw_uid; | |
e0bf9127 | 487 | } |
6a2df4ee MK |
488 | |
489 | if (chown(argv[2], uid, \-1) == \-1) { | |
490 | perror("chown"); | |
491 | exit(EXIT_FAILURE); | |
c54ed37e | 492 | } |
e0bf9127 | 493 | |
6a2df4ee | 494 | exit(EXIT_SUCCESS); |
c54ed37e | 495 | } |
009a7c83 | 496 | .EE |
47297adb | 497 | .SH SEE ALSO |
1bf54566 MK |
498 | .BR chgrp (1), |
499 | .BR chown (1), | |
fea681da MK |
500 | .BR chmod (2), |
501 | .BR flock (2), | |
a9cfde1d | 502 | .BR path_resolution (7), |
ad22ad55 | 503 | .BR symlink (7) |