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

NAME

6       chown, lchown, fchown, fchownat - change owner and group of a file
7

SYNOPSIS

9       #include <unistd.h>
10       #include <sys/types.h>
11
12       int chown(const char *path, uid_t owner, gid_t group);
13
14
15       int lchown(const char *path, uid_t owner, gid_t group);
16
17
18       int fchown(int fildes, uid_t owner, gid_t group);
19
20
21       int fchownat(int fildes, const char *path, uid_t owner,
22            gid_t group, int flag);
23
24

DESCRIPTION

26       The  chown() function sets the owner ID and group ID of the file speci‐
27       fied by path or referenced by the open file descriptor fildes to  owner
28       and  group  respectively. If owner or group is specified as −1, chown()
29       does not change the corresponding ID of the file.
30
31
32       The  lchown() function sets the owner ID and group ID of the named file
33       in  the  same  manner  as  chown(), unless the named file is a symbolic
34       link. In this case, lchown() changes the ownership of the symbolic link
35       file  itself, while chown() changes the ownership of the file or direc‐
36       tory to which the symbolic link refers.
37
38
39       The fchownat() function sets the owner ID and group  ID  of  the  named
40       file   in the same manner as chown(). If, however, the path argument is
41       relative, the path is resolved relative to the fildes  argument  rather
42       than  the  current  working  directory.  If the fildes argument has the
43       special value AT_FDCWD, the path resolution  reverts  back  to  current
44       working directory relative.  If the flag argument is set to SYMLNK, the
45       function behaves like lchown() with respect to symbolic links.  If  the
46       path argument is absolute, the fildes argument is ignored.  If the path
47       argument is a null pointer, the function behaves like fchown().
48
49
50       If  chown(), lchown(), fchown(), or fchownat() is invoked by a  process
51       that does not have {PRIV_FILE_SETID} asserted in its effective set, the
52       set-user-ID and  set-group-ID  bits  of  the  file  mode,  S_ISUID  and
53       S_ISGID  respectively, are cleared (see  chmod(2)). Additional restric‐
54       tions apply when changing the ownership to uid 0.
55
56
57       The operating system defines several privileges  to  override  restric‐
58       tions  on  the  chown() family of functions. When the {PRIV_FILE_CHOWN}
59       privilege is asserted in the effective  set  of  the  current  process,
60       there are no restrictions except in the special circumstances of chang‐
61       ing ownership to or from uid 0. When the {PRIV_FILE_CHOWN_SELF}  privi‐
62       lege  is  asserted,  ownership  changes  are restricted to the files of
63       which the ownership matches  the  effective  user  ID  of  the  current
64       process.   If neither privilege is asserted in the effective set of the
65       calling process, ownership changes are limited to changes of the  group
66       of  the  file  to the list of supplementary group IDs and the effective
67       group ID.
68
69
70       The    operating    system    provides    a    configuration    option,
71       {_POSIX_CHOWN_RESTRICTED}, to control the default behavior of processes
72       and the behavior of the NFS server.   If  {_POSIX_CHOWN_RESTRICTED}  is
73       not  in effect, the privilege {PRIV_FILE_CHOWN_SELF} is asserted in the
74       inheritable set of all processes unless overridden by policy.conf(4) or
75       user_attr(4).  To  set this configuration option, include the following
76       line in /etc/system:
77
78
79       set rstchown = 1
80
81
82       To disable this option, include the following line in  /etc/system:
83
84
85       set rstchown = 0
86
87
88       See system(4) and  fpathconf(2).
89
90
91       Upon successful completion, chown(), fchown()  and  lchown()  mark  for
92       update the st_ctime field of the file.
93

RETURN VALUES

95       Upon  successful  completion, 0 is returned. Otherwise, −1 is returned,
96       the owner and group of the named file remain unchanged,  and  errno  is
97       set to indicate the error.
98

ERRORS

100       All of these functions will fail if:
101
102       EPERM    The effective user ID does not match the owner of the file and
103                the {PRIV_FILE_CHOWN} privilege is not asserted in the  effec‐
104                tive set of the calling process, or the {PRIV_FILE_CHOWN_SELF}
105                privilege is not asserted in the effective set of the  calling
106                process.
107
108
109
110       The chown(), lchown(), and fchownat() functions will fail if:
111
112       EACCES          Search  permission is denied on a component of the path
113                       prefix of path.
114
115
116       EFAULT          The path argument points to an illegal address and  for
117                       fchownat(), the file descriptor has the value AT_FDCWD.
118
119
120       EINTR           A signal was caught during the execution of the chown()
121                       or lchown() function.
122
123
124       EINVAL          The group or owner argument is out of range.
125
126
127       EIO             An I/O error occurred while reading from or writing  to
128                       the file system.
129
130
131       ELOOP           Too many symbolic links were encountered in translating
132                       path.
133
134
135       ENAMETOOLONG    The length of the path argument exceeds {PATH_MAX},  or
136                       the length of a path component exceeds {NAME_MAX} while
137                       {_POSIX_NO_TRUNC} is in effect.
138
139
140       ENOLINK         The path argument points to a remote  machine  and  the
141                       link to that machine is no longer active.
142
143
144       ENOENT          Either  a  component  of  the  path  prefix or the file
145                       referred to by path does not exist or is a  null  path‐
146                       name.
147
148
149       ENOTDIR         A  component of the path prefix of path is not a direc‐
150                       tory, or the path supplied to  fchownat()  is  relative
151                       and  the  file  descriptor provided does not refer to a
152                       valid directory.
153
154
155       EROFS           The named file  resides on a read-only file system.
156
157
158
159       The fchown() and fchownat() functions will fail if:
160
161       EBADF      For fchown()  the  fildes  argument  is  not  an  open  file
162                  descriptor and.
163
164                  For  fchownat(),  the  path argument is not absolute and the
165                  fildes argument is not AT_FDCWD or an open file descriptor.
166
167
168       EIO        An I/O error occurred while reading from or writing  to  the
169                  file system.
170
171
172       EINTR      A signal was caught during execution of the function.
173
174
175       ENOLINK    The  fildes argument points to a remote machine and the link
176                  to that machine is no longer active.
177
178
179       EINVAL     The group or owner argument is out of range.
180
181
182       EROFS      The named file referred to by fildes resides on a  read-only
183                  file system.
184
185

ATTRIBUTES

187       See attributes(5) for descriptions of the following attributes:
188
189
190
191
192       ┌─────────────────────────────┬─────────────────────────────┐
193       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
194       ├─────────────────────────────┼─────────────────────────────┤
195       │Interface Stability          │See below.                   │
196       ├─────────────────────────────┼─────────────────────────────┤
197       │MT-Level                     │See below.                   │
198       └─────────────────────────────┴─────────────────────────────┘
199
200
201       The  chown(), fchown(), and lchown() functions are Standard. The fchow‐
202       nat() function is Evolving.
203
204
205       The chown() and fchownat() functions are Async-Signal-Safe.
206

SEE ALSO

208       chgrp(1), chown(1), chmod(2), fpathconf(2),  system(4),  attributes(5),
209       standards(5)
210
211
212
213SunOS 5.11                        9 Oct 2008                          chown(2)
Impressum