| blob | b3962d5b00e2dc83999076f339ee14625a9c0a38 |
1 .\" $NetBSD: chown.2,v 1.31 2010/05/31 12:16:20 njoly Exp $
2 .\"
3 .\" Copyright (c) 1980, 1991, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)chown.2 8.4 (Berkeley) 4/19/94
31 .\"
32 .Dd April 19, 1994
33 .Dt CHOWN 2
34 .Os
35 .Sh NAME
36 .Nm chown ,
37 .Nm lchown ,
38 .Nm fchown
39 .Nd change owner and group of a file
40 .Sh LIBRARY
41 .Lb libc
42 .Sh SYNOPSIS
43 .In unistd.h
44 .Ft int
45 .Fn chown "const char *path" "uid_t owner" "gid_t group"
46 .Ft int
47 .Fn lchown "const char *path" "uid_t owner" "gid_t group"
48 .Ft int
49 .Fn fchown "int fd" "uid_t owner" "gid_t group"
50 .Sh DESCRIPTION
51 The owner ID and group ID of the file
52 named by
53 .Fa path
54 or referenced by
55 .Fa fd
56 is changed as specified by the arguments
57 .Fa owner
58 and
59 .Fa group .
60 The owner of a file may change the
61 .Fa group
62 to a group of which
63 he or she is a member,
64 but the change
65 .Fa owner
66 capability is restricted to the super-user.
67 .Pp
68 When called to change the owner of a file,
69 .Fn chown ,
70 .Fn lchown
71 and
72 .Fn fchown
73 clear the set-user-id
74 .Dv ( S_ISUID )
75 bit on the file.
76 When a called to change the group of a file,
77 .Fn chown ,
78 .Fn lchown
79 and
80 .Fn fchown
81 clear the set-group-id
82 .Dv ( S_ISGID )
83 bit on the file.
84 These actions are taken to prevent accidental or mischievous creation of
85 set-user-id and set-group-id programs.
86 .Pp
87 .Fn lchown
88 is like
89 .Fn chown
90 except in the case where the named file is a symbolic link,
91 in which case
92 .Fn lchown
93 changes the owner and group of the link,
94 while
95 .Fn chown
96 changes the owner and group of the file the link references.
97 .Pp
98 .Fn fchown
99 is particularly useful when used in conjunction
100 with the file locking primitives (see
101 .Xr flock 2 ) .
102 .Pp
103 One of the owner or group id's
104 may be left unchanged by specifying it as (uid_t)\-1 or (gid_t)\-1 respectively.
105 .Sh RETURN VALUES
106 Zero is returned if the operation was successful;
107 \-1 is returned if an error occurs, with a more specific
108 error code being placed in the global variable
109 .Va errno .
110 .Sh ERRORS
111 .Fn chown
112 and
113 .Fn lchown
114 will fail and the file will be unchanged if:
115 .Bl -tag -width Er
116 .It Bq Er ENOTDIR
117 A component of the path prefix is not a directory.
118 .It Bq Er ENAMETOOLONG
119 A component of a pathname exceeded
120 .Brq Dv NAME_MAX
121 characters, or an entire path name exceeded
122 .Brq Dv PATH_MAX
123 characters.
124 .It Bq Er ENOENT
125 The named file does not exist.
126 .It Bq Er EACCES
127 Search permission is denied for a component of the path prefix.
128 .It Bq Er ELOOP
129 Too many symbolic links were encountered in translating the pathname.
130 .It Bq Er EPERM
131 The effective user ID is not the super-user.
132 .It Bq Er EROFS
133 The named file resides on a read-only file system.
134 .It Bq Er EFAULT
135 .Fa path
136 points outside the process's allocated address space.
137 .It Bq Er EIO
138 An I/O error occurred while reading from or writing to the file system.
139 .El
140 .Pp
141 .Fn fchown
142 will fail if:
143 .Bl -tag -width Er
144 .It Bq Er EBADF
145 .Fa fd
146 does not refer to a valid descriptor.
147 .It Bq Er EINVAL
148 .Fa fd
149 refers to a socket, not a file.
150 .It Bq Er EPERM
151 The effective user ID is not the super-user.
152 .It Bq Er EROFS
153 The named file resides on a read-only file system.
154 .It Bq Er EIO
155 An I/O error occurred while reading from or writing to the file system.
156 .El
157 .Sh SEE ALSO
158 .Xr chgrp 1 ,
159 .Xr chmod 2 ,
160 .Xr flock 2 ,
161 .Xr symlink 7 ,
162 .Xr chown 8
163 .Sh STANDARDS
164 The
165 .Fn chown
166 function deviates from the semantics defined in
167 .St -p1003.1-90 ,
168 which specifies that, unless the caller is the super-user, both the
169 set-user-id and set-group-id bits on a file shall be cleared, regardless
170 of the file attribute changed.
171 The
172 .Fn lchown
173 and
174 .Fn fchown
175 functions, as defined by
176 .St -xpg4.2 ,
177 provide the same semantics.
178 .Pp
179 To retain conformance to these standards, compatibility interfaces
180 are provided by the
181 .Lb libposix
182 as follows:
183 .Bl -bullet -compact
184 .It
185 The
186 .Fn chown
187 function conforms to
188 .St -p1003.1-90
189 and
190 .St -xpg4.2 .
191 .It
192 The
193 .Fn lchown
194 and
195 .Fn fchown
196 functions conform to
197 .St -xpg4.2 .
198 .El
199 .Sh HISTORY
200 The
201 .Fn fchown
202 function call appeared in
203 .Bx 4.2 .
204 .Pp
205 The
206 .Fn chown
207 and
208 .Fn fchown
209 functions were changed to follow symbolic links in
210 .Bx 4.4 .
211 The
212 .Fn lchown
213 function call appeared in
214 .Nx 1.3 .