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