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 permission bit).
38 .TH CHOWN 2 2014-08-19 "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 );
60 Feature Test Macro Requirements for glibc (see
61 .BR feature_test_macros (7)):
69 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
70 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
72 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
81 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
89 These system calls change the owner and group of a file.
95 system calls differ only in how the file is specified:
98 changes the ownership of the file specified by
100 which is dereferenced if it is a symbolic link.
103 changes the ownership of the file referred to by the open file descriptor
109 but does not dereference symbolic links.
111 Only a privileged process (Linux: one with the
113 capability) may change the owner of a file.
114 The owner of a file may change the group of the file
115 to any group of which that owner is a member.
116 A privileged process (Linux: with
118 may change the group arbitrarily.
124 is specified as \-1, then that ID is not changed.
126 When the owner or group of an executable file are
127 changed by an unprivileged user the
131 mode bits are cleared.
132 POSIX does not specify whether
133 this also should happen when root does the
135 the Linux behavior depends on the kernel version.
136 .\" In Linux 2.0 kernels, superuser was like everyone else
137 .\" In 2.2, up to 2.2.12, these bits were not cleared for superuser.
138 .\" Since 2.2.13, superuser is once more like everyone else.
139 In case of a non-group-executable file (i.e., one for which the
143 bit indicates mandatory locking, and is not cleared by a
148 system call operates in exactly the same way as
150 except for the differences described here.
152 If the pathname given in
154 is relative, then it is interpreted relative to the directory
155 referred to by the file descriptor
157 (rather than relative to the current working directory of
158 the calling process, as is done by
160 for a relative pathname).
170 is interpreted relative to the current working
171 directory of the calling process (like
182 argument is a bit mask created by ORing together
183 0 or more of the following values;
185 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
186 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
189 is an empty string, operate on the file referred to by
191 (which may have been obtained using the
197 can refer to any type of file, not just a directory.
202 the call operates on the current working directory.
203 This flag is Linux-specific; define
205 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
206 to obtain its definition.
209 .B AT_SYMLINK_NOFOLLOW
212 is a symbolic link, do not dereference it:
213 instead operate on the link itself, like
217 dereferences symbolic links, like
222 for an explanation of the need for
225 On success, zero is returned.
226 On error, \-1 is returned, and
228 is set appropriately.
230 Depending on the filesystem,
231 errors other than those listed below can be returned.
233 The more general errors for
238 Search permission is denied on a component of the path prefix.
240 .BR path_resolution (7).)
244 points outside your accessible address space.
247 Too many symbolic links were encountered in resolving
255 The file does not exist.
258 Insufficient kernel memory was available.
261 A component of the path prefix is not a directory.
264 The calling process did not have the required permissions
265 (see above) to change owner and/or group.
268 The named file resides on a read-only filesystem.
270 The general errors for
275 The descriptor is not valid.
278 A low-level I/O error occurred while modifying the inode.
289 The same errors that occur for
293 The following additional errors can occur for
298 is not a valid file descriptor.
301 Invalid flag specified in
308 is a file descriptor referring to a file other than a directory.
311 was added to Linux in kernel 2.6.16;
312 library support was added to glibc in version 2.4.
317 4.4BSD, SVr4, POSIX.1-2001, POSIX.1-2008.
319 The 4.4BSD version can be
320 used only by the superuser (that is, ordinary users cannot give away files).
322 .\" SVr4 documents EINVAL, EINTR, ENOLINK and EMULTIHOP returns, but no
323 .\" ENOMEM. POSIX.1 does not document ENOMEM or ELOOP error conditions.
325 .\" SVr4 documents additional EINVAL, EIO, EINTR, and ENOLINK
326 .\" error conditions.
331 .SS Ownership of new files
332 When a new file is created (by, for example,
336 its owner is made the same as the filesystem user ID of the
338 The group of the file depends on a range of factors,
339 including the type of filesystem,
340 the options used to mount the filesystem,
341 and whether or not the set-group-ID permission bit is enabled
342 on the parent directory.
343 If the filesystem supports the
346 .IR "\-o\ bsdgroups" )
350 .IR "\-o\ sysvgroups" )
352 options, then the rules are as follows:
354 If the filesystem is mounted with
356 then the group of a new file is made
357 the same as that of the parent directory.
359 If the filesystem is mounted with
361 and the set-group-ID bit is disabled on the parent directory,
362 then the group of a new file is made the same as the
363 process's filesystem GID.
365 If the filesystem is mounted with
367 and the set-group-ID bit is enabled on the parent directory,
368 then the group of a new file is made
369 the same as that of the parent directory.
376 mount options are supported by ext2, ext3, ext4, and XFS.
377 Filesystems that don't support these mount options follow the
381 On older kernels where
383 is unavailable, the glibc wrapper function falls back to the use of
389 is a relative pathname,
390 glibc constructs a pathname based on the symbolic link in
392 that corresponds to the
398 semantics are deliberately violated on NFS filesystems
399 which have UID mapping enabled.
400 Additionally, the semantics of all system
401 calls which access the file contents are violated, because
403 may cause immediate access revocation on already open files.
405 caching may lead to a delay between the time where ownership have
406 been changed to allow access for a user and the time where the file can
407 actually be accessed by the user on other clients.
408 .SS Historical details
414 system calls supported only 16-bit user and group IDs.
415 Subsequently, Linux 2.4 added
420 supporting 32-bit IDs.
426 wrapper functions transparently deal with the variations across kernel versions.
428 In versions of Linux prior to 2.1.81 (and distinct from 2.1.46),
430 did not follow symbolic links.
433 does follow symbolic links, and there is a new system call
435 that does not follow symbolic links.
436 Since Linux 2.1.86, this new call (that has the same semantics
439 has got the same syscall number, and
441 got the newly introduced number.
444 The following program changes the ownership of the file named in
445 its second command-line argument to the value specified in its
446 first command-line argument.
447 The new owner can be specified either as a numeric user ID,
448 or as a username (which is converted to a user ID by using
450 to perform a lookup in the system password file).
459 main(int argc, char *argv[])
465 if (argc != 3 || argv[1][0] == \(aq\\0\(aq) {
466 fprintf(stderr, "%s <owner> <file>\\n", argv[0]);
470 uid = strtol(argv[1], &endptr, 10); /* Allow a numeric string */
472 if (*endptr != \(aq\\0\(aq) { /* Was not pure numeric string */
473 pwd = getpwnam(argv[1]); /* Try getting UID for username */
482 if (chown(argv[2], uid, \-1) == \-1) {
493 .BR path_resolution (7),