1chown(2)                      System Calls Manual                     chown(2)
2
3
4

NAME

6       chown, fchown, lchown, fchownat - change ownership of a file
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <unistd.h>
13
14       int chown(const char *pathname, uid_t owner, gid_t group);
15       int fchown(int fd, uid_t owner, gid_t group);
16       int lchown(const char *pathname, uid_t owner, gid_t group);
17
18       #include <fcntl.h>           /* Definition of AT_* constants */
19       #include <unistd.h>
20
21       int fchownat(int dirfd, const char *pathname,
22                    uid_t owner, gid_t group, int flags);
23
24   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
25
26       fchown(), lchown():
27           /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
28               || _XOPEN_SOURCE >= 500
29               || /* glibc <= 2.19: */ _BSD_SOURCE
30
31       fchownat():
32           Since glibc 2.10:
33               _POSIX_C_SOURCE >= 200809L
34           Before glibc 2.10:
35               _ATFILE_SOURCE
36

DESCRIPTION

38       These  system calls change the owner and group of a file.  The chown(),
39       fchown(), and lchown() system calls differ only  in  how  the  file  is
40       specified:
41
42       •  chown()  changes  the  ownership  of the file specified by pathname,
43          which is dereferenced if it is a symbolic link.
44
45       •  fchown() changes the ownership of the file referred to by  the  open
46          file descriptor fd.
47
48       •  lchown() is like chown(), but does not dereference symbolic links.
49
50       Only  a  privileged  process (Linux: one with the CAP_CHOWN capability)
51       may change the owner of a file.  The owner of a  file  may  change  the
52       group  of  the  file  to  any group of which that owner is a member.  A
53       privileged process (Linux: with CAP_CHOWN) may change the  group  arbi‐
54       trarily.
55
56       If the owner or group is specified as -1, then that ID is not changed.
57
58       When the owner or group of an executable file is changed by an unprivi‐
59       leged user, the S_ISUID and S_ISGID mode bits are cleared.  POSIX  does
60       not specify whether this also should happen when root does the chown();
61       the Linux behavior depends on  the  kernel  version,  and  since  Linux
62       2.2.13,  root is treated like other users.  In case of a non-group-exe‐
63       cutable file (i.e., one for which the S_IXGRP bit is not set) the S_IS‐
64       GID bit indicates mandatory locking, and is not cleared by a chown().
65
66       When the owner or group of an executable file is changed (by any user),
67       all capability sets for the file are cleared.
68
69   fchownat()
70       The fchownat() system call operates in exactly the same way as chown(),
71       except for the differences described here.
72
73       If  the  pathname given in pathname is relative, then it is interpreted
74       relative to the directory referred to  by  the  file  descriptor  dirfd
75       (rather  than  relative to the current working directory of the calling
76       process, as is done by chown() for a relative pathname).
77
78       If pathname is relative and dirfd is the special value  AT_FDCWD,  then
79       pathname  is  interpreted  relative to the current working directory of
80       the calling process (like chown()).
81
82       If pathname is absolute, then dirfd is ignored.
83
84       The flags argument is a bit mask created by ORing together 0 or more of
85       the following values;
86
87       AT_EMPTY_PATH (since Linux 2.6.39)
88              If  pathname is an empty string, operate on the file referred to
89              by dirfd (which may have been obtained using the open(2)  O_PATH
90              flag).   In  this case, dirfd can refer to any type of file, not
91              just a directory.  If dirfd is AT_FDCWD, the  call  operates  on
92              the current working directory.  This flag is Linux-specific; de‐
93              fine _GNU_SOURCE to obtain its definition.
94
95       AT_SYMLINK_NOFOLLOW
96              If pathname is a symbolic link, do not dereference  it:  instead
97              operate  on the link itself, like lchown().  (By default, fchow‐
98              nat() dereferences symbolic links, like chown().)
99
100       See openat(2) for an explanation of the need for fchownat().
101

RETURN VALUE

103       On success, zero is returned.  On error, -1 is returned, and  errno  is
104       set to indicate the error.
105

ERRORS

107       Depending  on  the filesystem, errors other than those listed below can
108       be returned.
109
110       The more general errors for chown() are listed below.
111
112       EACCES Search permission is denied on a component of the  path  prefix.
113              (See also path_resolution(7).)
114
115       EBADF  (fchown()) fd is not a valid open file descriptor.
116
117       EBADF  (fchownat())  pathname is relative but dirfd is neither AT_FDCWD
118              nor a valid file descriptor.
119
120       EFAULT pathname points outside your accessible address space.
121
122       EINVAL (fchownat()) Invalid