| blob | e35587b28ae860c7edfdcf11a3f954f451b5c983 |
1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
2 .\" and Copyright (c) 1998 Andries Brouwer (aeb@cwi.nl)
3 .\" and Copyright (c) 2006, 2007, 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\"
5 .\" %%%LICENSE_START(VERBATIM)
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.
14 .\"
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.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" %%%LICENSE_END
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>
32 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
33 .\" 2007-07-08, mtk, added an example program; updated SYNOPSIS
34 .\" 2008-05-08, mtk, Describe rules governing ownership of new files
35 .\" (bsdgroups versus sysvgroups, and the effect of the parent
36 .\" directory's set-group-ID mode bit).
37 .\"
38 .TH CHOWN 2 2021-03-22 "Linux" "Linux Programmer's Manual"
39 .SH NAME
40 chown, fchown, lchown, fchownat \- change ownership of a file
41 .SH SYNOPSIS
42 .nf
43 .B #include <unistd.h>
44 .PP
45 .BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group );
46 .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
47 .BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group );
48 .PP
49 .BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
50 .B #include <unistd.h>
51 .PP
52 .BI "int fchownat(int " dirfd ", const char *" pathname ,
53 .BI " uid_t " owner ", gid_t " group ", int " flags );
54 .fi
55 .PP
56 .RS -4
57 Feature Test Macro Requirements for glibc (see
58 .BR feature_test_macros (7)):
59 .RE
60 .PP
61 .BR fchown (),
62 .BR lchown ():
63 .nf
64 /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
65 || _XOPEN_SOURCE >= 500
66 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
67 || /* Glibc <= 2.19: */ _BSD_SOURCE
68 .fi
69 .PP
70 .BR fchownat ():
71 .nf
72 Since glibc 2.10:
73 _POSIX_C_SOURCE >= 200809L
74 Before glibc 2.10:
75 _ATFILE_SOURCE
76 .fi
77 .SH DESCRIPTION
78 These system calls change the owner and group of a file.
79 The
80 .BR chown (),
81 .BR fchown (),
82 and
83 .BR lchown ()
84 system calls differ only in how the file is specified:
85 .IP * 2
86 .BR chown ()
87 changes the ownership of the file specified by
88 .IR pathname ,
89 which is dereferenced if it is a symbolic link.
90 .IP *
91 .BR fchown ()
92 changes the ownership of the file referred to by the open file descriptor
93 .IR fd .
94 .IP *
95 .BR lchown ()
96 is like
97 .BR chown (),
98 but does not dereference symbolic links.
99 .PP
100 Only a privileged process (Linux: one with the
101 .B CAP_CHOWN
102 capability) may change the owner of a file.
103 The owner of a file may change the group of the file
104 to any group of which that owner is a member.
105 A privileged process (Linux: with
106 .BR CAP_CHOWN )
107 may change the group arbitrarily.
108 .PP
109 If the
110 .I owner
111 or
112 .I group
113 is specified as \-1, then that ID is not changed.
114 .PP
115 When the owner or group of an executable file is
116 changed by an unprivileged user, the
117 .B S_ISUID
118 and
119 .B S_ISGID
120 mode bits are cleared.
121 POSIX does not specify whether
122 this also should happen when root does the
123 .BR chown ();
124 the Linux behavior depends on the kernel version,
125 and since Linux 2.2.13, root is treated like other users.
126 .\" In Linux 2.0 kernels, superuser was like everyone else
127 .\" In 2.2, up to 2.2.12, these bits were not cleared for superuser.
128 .\" Since 2.2.13, superuser is once more like everyone else.
129 In case of a non-group-executable file (i.e., one for which the
130 .B S_IXGRP
131 bit is not set) the
132 .B S_ISGID
133 bit indicates mandatory locking, and is not cleared by a
134 .BR chown ().
135 .PP
136 When the owner or group of an executable file is changed (by any user),
137 all capability sets for the file are cleared.
138 .\"
139 .SS fchownat()
140 The
141 .BR fchownat ()
142 system call operates in exactly the same way as
143 .BR chown (),
144 except for the differences described here.
145 .PP
146 If the pathname given in
147 .I pathname
148 is relative, then it is interpreted relative to the directory
149 referred to by the file descriptor
150 .I dirfd
151 (rather than relative to the current working directory of
152 the calling process, as is done by
153 .BR chown ()
154 for a relative pathname).
155 .PP
156 If
157 .I pathname
158 is relative and
159 .I dirfd
160 is the special value
161 .BR AT_FDCWD ,
162 then
163 .I pathname
164 is interpreted relative to the current working
165 directory of the calling process (like
166 .BR chown ()).
167 .PP
168 If
169 .I pathname
170 is absolute, then
171 .I dirfd
172 is ignored.
173 .PP
174 The
175 .I flags
176 argument is a bit mask created by ORing together
177 0 or more of the following values;
178 .TP
179 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
180 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
181 If
182 .I pathname
183 is an empty string, operate on the file referred to by
184 .IR dirfd
185 (which may have been obtained using the
186 .BR open (2)
187 .B O_PATH
188 flag).
189 In this case,
190 .I dirfd
191 can refer to any type of file, not just a directory.
192 If
193 .I dirfd
194 is
195 .BR AT_FDCWD ,
196 the call operates on the current working directory.
197 This flag is Linux-specific; define
198 .B _GNU_SOURCE
199 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
200 to obtain its definition.
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, like
207 .BR lchown ().
208 (By default,
209 .BR fchownat ()
210 dereferences symbolic links, like
211 .BR chown ().)
212 .PP
213 See
214 .BR openat (2)
215 for an explanation of the need for
216 .BR fchownat ().
217 .SH RETURN VALUE
218 On success, zero is returned.
219 On error, \-1 is returned, and
220 .I errno
221 is set to indicate the error.
222 .SH ERRORS
223 Depending on the filesystem,
224 errors other than those listed below can be returned.
225 .PP
226 The more general errors for
227 .BR chown ()
228 are listed below.
229 .TP
230 .B EACCES
231 Search permission is denied on a component of the path prefix.
232 (See also
233 .BR path_resolution (7).)
234 .TP
235 .B EFAULT
236 .I pathname
237 points outside your accessible address space.
238 .TP
239 .B ELOOP
240 Too many symbolic links were encountered in resolving
241 .IR pathname .
242 .TP
243 .B ENAMETOOLONG
244 .I pathname
245 is too long.
246 .TP
247 .B ENOENT
248 The file does not exist.
249 .TP
250 .B ENOMEM
251 Insufficient kernel memory was available.
252 .TP
253 .B ENOTDIR
254 A component of the path prefix is not a directory.
255 .TP
256 .B EPERM
257 The calling process did not have the required permissions
258 (see above) to change owner and/or group.
259 .TP
260 .B EPERM
261 The file is marked immutable or append-only.
262 (See
263 .BR ioctl_iflags (2).)
264 .TP
265 .B EROFS
266 The named file resides on a read-only filesystem.
267 .PP
268 The general errors for
269 .BR fchown ()
270 are listed below:
271 .TP
272 .B EBADF
273 .I fd
274 is not a valid open file descriptor.
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.
287 .PP
288 The same errors that occur for
289 .BR chown ()
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.
312 .SH CONFORMING TO
313 .BR chown (),
314 .BR fchown (),
315 .BR lchown ():
316 4.4BSD, SVr4, POSIX.1-2001, POSIX.1-2008.
317 .PP
318 The 4.4BSD version can be
319 used only by the superuser (that is, ordinary users cannot give away files).
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.
326 .PP
327 .BR fchownat ():
328 POSIX.1-2008.
329 .SH NOTES
330 .SS Ownership of new files
331 When a new file is created (by, for example,
332 .BR open (2)
333 or
334 .BR mkdir (2)),
335 its owner is made the same as the filesystem user ID of the
336 creating process.
337 The group of the file depends on a range of factors,
338 including the type of filesystem,
339 the options used to mount the filesystem,
340 and whether or not the set-group-ID mode bit is enabled
341 on the parent directory.
342 If the filesystem supports the
343 .B "\-o\ grpid"
344 (or, synonymously
345 .BR "\-o\ bsdgroups" )
346 and
347 .B "\-o\ nogrpid"
348 (or, synonymously
349 .BR "\-o\ sysvgroups" )
350 .BR mount (8)
351 options, then the rules are as follows:
352 .IP * 2
353 If the filesystem is mounted with
354 .BR "\-o\ grpid" ,
355 then the group of a new file is made
356 the same as that of the parent directory.
357 .IP *
358 If the filesystem is mounted with
359 .BR "\-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
362 process's filesystem GID.
363 .IP *
364 If the filesystem is mounted with
365 .BR "\-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 4.12,
371 the
372 .BR "\-o\ grpid"
373 and
374 .BR "\-o\ nogrpid"
375 mount options are supported by ext2, ext3, ext4, and XFS.
376 Filesystems that don't support these mount options follow the
377 .BR "\-o\ nogrpid"
378 rules.
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.
394 .SS NFS
395 The
396 .BR chown ()
397 semantics are deliberately violated on NFS filesystems
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.
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.
426 .PP
427 In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
428 .BR chown ()
429 did not follow symbolic links.
430 Since Linux 2.1.81,
431 .BR chown ()
432 does follow symbolic links, and there is a new system call
433 .BR lchown ()
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
437 .BR chown ())
438 has got the same syscall number, and
439 .BR chown ()
440 got the newly introduced number.
441 .SH EXAMPLES
442 The following program changes the ownership of the file named in
443 its second command-line argument to the value specified in its
444 first command-line argument.
445 The new owner can be specified either as a numeric user ID,
446 or as a username (which is converted to a user ID by using
447 .BR getpwnam (3)
448 to perform a lookup in the system password file).
449 .SS Program source
450 .EX
451 #include <pwd.h>
452 #include <stdio.h>
453 #include <stdlib.h>
454 #include <unistd.h>
456 int
457 main(int argc, char *argv[])
458 {
459 uid_t uid;
460 struct passwd *pwd;
461 char *endptr;
463 if (argc != 3 || argv[1][0] == \(aq\e0\(aq) {
464 fprintf(stderr, "%s <owner> <file>\en", argv[0]);
465 exit(EXIT_FAILURE);
466 }
468 uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */
470 if (*endptr != \(aq\e0\(aq) { /* Was not pure numeric string */
471 pwd = getpwnam(argv[1]); /* Try getting UID for username */
472 if (pwd == NULL) {
473 perror("getpwnam");
474 exit(EXIT_FAILURE);
475 }
477 uid = pwd\->pw_uid;
478 }
480 if (chown(argv[2], uid, \-1) == \-1) {
481 perror("chown");
482 exit(EXIT_FAILURE);
483 }
485 exit(EXIT_SUCCESS);
486 }
487 .EE
488 .SH SEE ALSO
489 .BR chgrp (1),
490 .BR chown (1),
491 .BR chmod (2),
492 .BR flock (2),
493 .BR path_resolution (7),
494 .BR symlink (7)