1CHOWN(3P)                  POSIX Programmer's Manual                 CHOWN(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       chown, fchownat — change owner and group of a file
13

SYNOPSIS

15       #include <unistd.h>
16
17       int chown(const char *path, uid_t owner, gid_t group);
18
19       #include <fcntl.h>
20
21       int fchownat(int fd, const char *path, uid_t owner, gid_t group,
22           int flag);
23

DESCRIPTION

25       The chown() function shall change the user and  group  ownership  of  a
26       file.
27
28       The  path  argument points to a pathname naming a file. The user ID and
29       group ID of the named file shall be set to the numeric values contained
30       in owner and group, respectively.
31
32       Only  processes  with  an effective user ID equal to the user ID of the
33       file or with appropriate privileges may change the ownership of a file.
34       If _POSIX_CHOWN_RESTRICTED is in effect for path:
35
36        *  Changing  the  user  ID is restricted to processes with appropriate
37           privileges.
38
39        *  Changing the group ID is permitted to a process with  an  effective
40           user  ID  equal to the user ID of the file, but without appropriate
41           privileges, if and only if owner is equal to the file's user ID  or
42           (uid_t)-1  and group is equal either to the calling process' effec‐
43           tive group ID or to one of its supplementary group IDs.
44
45       If the specified file is a regular file, one or more  of  the  S_IXUSR,
46       S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does
47       not have appropriate privileges, the  set-user-ID  (S_ISUID)  and  set-
48       group-ID (S_ISGID) bits of the file mode shall be cleared upon success‐
49       ful return from chown().  If the specified file is a regular file,  one
50       or  more  of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are
51       set, and the process has appropriate privileges, it is  implementation-
52       defined  whether  the set-user-ID and set-group-ID bits are altered. If
53       the chown() function is successfully invoked on a file that  is  not  a
54       regular  file  and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits
55       of the file mode are set, the set-user-ID and set-group-ID bits may  be
56       cleared.
57
58       If owner or group is specified as (uid_t)-1 or (gid_t)-1, respectively,
59       the corresponding ID of the file shall not be changed.
60
61       Upon successful completion, chown() shall mark for update the last file
62       status  change timestamp of the file, except that if owner is (uid_t)-1
63       and group is (gid_t)-1, the file status change timestamp  need  not  be
64       marked for update.
65
66       The fchownat() function shall be equivalent to the chown() and lchown()
67       functions except in the case where path specifies a relative  path.  In
68       this  case  the file to be changed is determined relative to the direc‐
69       tory associated with the file descriptor  fd  instead  of  the  current
70       working  directory.  If  the  access  mode of the open file description
71       associated with the file descriptor is not O_SEARCH, the function shall
72       check  whether  directory searches are permitted using the current per‐
73       missions of the directory underlying the file descriptor. If the access
74       mode is O_SEARCH, the function shall not perform the check.
75
76       Values for flag are constructed by a bitwise-inclusive OR of flags from
77       the following list, defined in <fcntl.h>:
78
79       AT_SYMLINK_NOFOLLOW
80             If path names a symbolic link, ownership of the symbolic link  is
81             changed.
82
83       If fchownat() is passed the special value AT_FDCWD in the fd parameter,
84       the current working directory shall be used and the behavior  shall  be
85       identical  to  a call to chown() or lchown() respectively, depending on
86       whether or not the AT_SYMLINK_NOFOLLOW bit is set in the flag argument.
87

RETURN VALUE

89       Upon successful completion, these functions shall return 0.  Otherwise,
90       these functions shall return -1 and set errno to indicate the error. If
91       -1 is returned, no changes are made in the user ID and group ID of  the
92       file.
93

ERRORS

95       These functions shall fail if:
96
97       EACCES Search permission is denied on a component of the path prefix.
98
99       ELOOP  A loop exists in symbolic links encountered during resolution of
100              the path argument.
101
102       ENAMETOOLONG
103              The  length  of  a  component  of  a  pathname  is  longer  than
104              {NAME_MAX}.
105
106       ENOENT A component of path does not name an existing file or path is an
107              empty string.
108
109       ENOTDIR
110              A component of the path prefix names an existing  file  that  is
111              neither  a  directory nor a symbolic link to a directory, or the
112              path argument contains at least one  non-<slash>  character  and
113              ends  with  one or more trailing <slash> characters and the last
114              pathname component names an existing  file  that  is  neither  a
115              directory nor a symbolic link to a directory.
116
117       EPERM  The  effective  user ID does not match the owner of the file, or
118              the calling process does not  have  appropriate  privileges  and
119              _POSIX_CHOWN_RESTRICTED   indicates   that   such  privilege  is
120              required.
121
122       EROFS  The named file resides on a read-only file system.
123
124       The fchownat() function shall fail if:
125
126       EACCES The access mode of the open file description associated with  fd
127              is  not O_SEARCH and the permissions of the directory underlying
128              fd do not permit directory searches.
129
130       EBADF  The path argument does not specify an absolute path and  the  fd
131              argument  is  neither  AT_FDCWD nor a valid file descriptor open
132              for reading or searching.
133
134       ENOTDIR
135              The path argument is not an absolute  path  and  fd  is  a  file
136              descriptor associated with a non-directory file.
137
138       These functions may fail if:
139
140       EIO    An  I/O error occurred while reading or writing to the file sys‐
141              tem.
142
143       EINTR  The chown() function was  interrupted  by  a  signal  which  was
144              caught.
145
146       EINVAL The  owner  or group ID supplied is not a value supported by the
147              implementation.
148
149       ELOOP  More than {SYMLOOP_MAX} symbolic links were  encountered  during
150              resolution of the path argument.
151
152       ENAMETOOLONG
153              The length of a pathname exceeds {PATH_MAX}, or pathname resolu‐
154              tion of a symbolic link produced an intermediate result  with  a
155              length that exceeds {PATH_MAX}.
156
157       The fchownat() function may fail if:
158
159       EINVAL The value of the flag argument is not valid.
160
161       The following sections are informative.
162

EXAMPLES

164       None.
165

APPLICATION USAGE

167       Although  chown() can be used on some implementations by the file owner
168       to change the owner and group to any desired values, the only  portable
169       use  of this function is to change the group of a file to the effective
170       GID of the calling process or to a member of its group set.
171

RATIONALE

173       System III and System V allow a user to give away files; that  is,  the
174       owner  of  a file may change its user ID to anything. This is a serious
175       problem for implementations that are intended to meet government  secu‐
176       rity  regulations.   Version 7 and 4.3 BSD permit only the superuser to
177       change the user ID of a file. Some  government  agencies  (usually  not
178       ones concerned directly with security) find this limitation too confin‐
179       ing. This volume of POSIX.1‐2017 uses may to permit secure  implementa‐
180       tions while not disallowing System V.
181
182       System  III  and System V allow the owner of a file to change the group
183       ID to anything. Version 7 permits only  the  superuser  to  change  the
184       group  ID  of a file.  4.3 BSD permits the owner to change the group ID
185       of a file to its effective group ID or to any of the groups in the list
186       of supplementary group IDs, but to no others.
187
188       The POSIX.1‐1990 standard requires that the chown() function invoked by
189       a non-appropriate privileged process clear the S_ISGID and the  S_ISUID
190       bits  for regular files, and permits them to be cleared for other types
191       of files. This is so that changes in accessibility do not  accidentally
192       cause  files  to become security holes.  Unfortunately, requiring these
193       bits to be cleared on non-executable data files also clears the  manda‐
194       tory  file  locking bit (shared with S_ISGID), which is an extension on
195       many implementations (it first appeared in System V). These bits should
196       only  be  required to be cleared on regular files that have one or more
197       of their execute bits set.
198
199       The purpose of the fchownat() function is to enable changing  ownership
200       of  files in directories other than the current working directory with‐
201       out exposure to race conditions. Any part of the path of a  file  could
202       be  changed  in parallel to a call to chown() or lchown(), resulting in
203       unspecified behavior. By opening  a  file  descriptor  for  the  target
204       directory  and  using the fchownat() function it can be guaranteed that
205       the changed file is located relative to the desired directory.
206

FUTURE DIRECTIONS

208       None.
209

SEE ALSO

211       chmod(), fpathconf(), lchown()
212
213       The Base Definitions volume of POSIX.1‐2017, <fcntl.h>,  <sys_types.h>,
214       <unistd.h>
215
217       Portions  of  this text are reprinted and reproduced in electronic form
218       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
219       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
220       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
221       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
222       event of any discrepancy between this version and the original IEEE and
223       The  Open Group Standard, the original IEEE and The Open Group Standard
224       is the referee document. The original Standard can be  obtained  online
225       at http://www.opengroup.org/unix/online.html .
226
227       Any  typographical  or  formatting  errors that appear in this page are
228       most likely to have been introduced during the conversion of the source
229       files  to  man page format. To report such errors, see https://www.ker
230       nel.org/doc/man-pages/reporting_bugs.html .
231
232
233
234IEEE/The Open Group                  2017                            CHOWN(3P)
Impressum