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>
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.
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.
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
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
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).
38 .TH CHOWN 2 2016-03-15 "Linux" "Linux Programmer's Manual"
40 chown, fchown, lchown, fchownat \- change ownership of a file
43 .B #include <unistd.h>
45 .BI "int chown(const char *" pathname ", uid_t " owner ", gid_t " group );
47 .BI "int fchown(int " fd ", uid_t " owner ", gid_t " group );
49 .BI "int lchown(const char *" pathname ", uid_t " owner ", gid_t " group );
51 .BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
52 .B #include <unistd.h>
54 .BI "int fchownat(int " dirfd ", const char *" pathname ,
55 .BI " uid_t " owner ", gid_t " group ", int " flags );
59 Feature Test Macro Requirements for glibc (see
60 .BR feature_test_macros (7)):
68 /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
69 || _XOPEN_SOURCE\ >=\ 500
70 .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
71 || /* Glibc versions <= 2.19: */ _BSD_SOURCE
80 _POSIX_C_SOURCE\ >=\ 200809L
88 These system calls change the owner and group of a file.
94 system calls differ only in how the file is specified:
97 changes the ownership of the file specified by
99 which is dereferenced if it is a symbolic link.
102 changes the ownership of the file referred to by the open file descriptor
108 but does not dereference symbolic links.
110 Only a privileged process (Linux: one with the
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
117 may change the group arbitrarily.
123 is specified as \-1, then that ID is not changed.
125 When the owner or group of an executable file is
126 changed by an unprivileged user, the
130 mode bits are cleared.
131 POSIX does not specify whether
132 this also should happen when root does the
134 the Linux behavior depends on the kernel version.
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.
138 In case of a non-group-executable file (i.e., one for which the
142 bit indicates mandatory locking, and is not cleared by a
147 system call operates in exactly the same way as
149 except for the differences described here.
151 If the pathname given in
153 is relative, then it is interpreted relative to the directory
154 referred to by the file descriptor
156 (rather than relative to the current working directory of
157 the calling process, as is done by
159 for a relative pathname).
169 is interpreted relative to the current working
170 directory of the calling process (like
181 argument is a bit mask created by ORing together
182 0 or more of the following values;
184 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
185 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
188 is an empty string, operate on the file referred to by
190 (which may have been obtained using the
196 can refer to any type of file, not just a directory.
201 the call operates on the current working directory.
202 This flag is Linux-specific; define
204 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
205 to obtain its definition.
207 .B AT_SYMLINK_NOFOLLOW
210 is a symbolic link, do not dereference it:
211 instead operate on the link itself, like
215 dereferences symbolic links, like
220 for an explanation of the need for
223 On success, zero is returned.
224 On error, \-1 is returned, and
226 is set appropriately.
228 Depending on the filesystem,
229 errors other than those listed below can be returned.
231 The more general errors for
236 Search permission is denied on a component of the path prefix.
238 .BR path_resolution (7).)
242 points outside your accessible address space.
245 Too many symbolic links were encountered in resolving
253 The file does not exist.
256 Insufficient kernel memory was available.
259 A component of the path prefix is not a directory.
262 The calling process did not have the required permissions
263 (see above) to change owner and/or group.
266 The named file resides on a read-only filesystem.
268 The general errors for
274 is not a valid open file descriptor.
277 A low-level I/O error occurred while modifying the inode.
288 The same errors that occur for
292 The following additional errors can occur for
297 is not a valid file descriptor.
300 Invalid flag specified in
307 is a file descriptor referring to a file other than a directory.
310 was added to Linux in kernel 2.6.16;
311 library support was added to glibc in version 2.4.
316 4.4BSD, SVr4, POSIX.1-2001, POSIX.1-2008.
318 The 4.4BSD version can be
319 used only by the superuser (that is, ordinary users cannot give away files).
321 .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
322 .\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions.
324 .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
325 .\" error conditions.
330 .SS Ownership of new files
331 When a new file is created (by, for example,
335 its owner is made the same as the filesystem user ID of the
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
345 .IR "\-o\ bsdgroups" )
349 .IR "\-o\ sysvgroups" )
351 options, then the rules are as follows:
353 If the filesystem is mounted with
355 then the group of a new file is made
356 the same as that of the parent directory.
358 If the filesystem is mounted with
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.
364 If the filesystem is mounted with
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.
375 mount options are supported by ext2, ext3, ext4, and XFS.
376 Filesystems that don't support these mount options follow the
380 On older kernels where
382 is unavailable, the glibc wrapper function falls back to the use of
388 is a relative pathname,
389 glibc constructs a pathname based on the symbolic link in
391 that corresponds to the
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
402 may cause immediate access revocation on already open files.
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
413 system calls supported only 16-bit user and group IDs.
414 Subsequently, Linux 2.4 added
419 supporting 32-bit IDs.
425 wrapper functions transparently deal with the variations across kernel versions.
427 In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
429 did not follow symbolic links.
432 does follow symbolic links, and there is a new system call
434 that does not follow symbolic links.
435 Since Linux 2.1.86, this new call (that has the same semantics
438 has got the same syscall number, and
440 got the newly introduced number.
443 The following program changes the ownership of the file named in
444 its second command-line argument to the value specified in its
445 first command-line argument.
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
449 to perform a lookup in the system password file).
458 main(int argc, char *argv[])
464 if (argc != 3 || argv[1][0] == \(aq\\0\(aq) {
465 fprintf(stderr, "%s <owner> <file>\\n", argv[0]);
469 uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */
471 if (*endptr != \(aq\\0\(aq) { /* Was not pure numeric string */
472 pwd = getpwnam(argv[1]); /* Try getting UID for username */
481 if (chown(argv[2], uid, \-1) == \-1) {
494 .BR path_resolution (7),