git.saurik.com Git - apple/xnu.git/blob

3 .\"

4 .\" Redistribution and use in source and binary forms, with or without

5 .\" modification, are permitted provided that the following conditions

6 .\" are met:

7 .\" 1. Redistributions of source code must retain the above copyright

8 .\" notice, this list of conditions and the following disclaimer.

9 .\" 2. Redistributions in binary form must reproduce the above copyright

10 .\" notice, this list of conditions and the following disclaimer in the

11 .\" documentation and/or other materials provided with the distribution.

12 .\" 3. All advertising materials mentioning features or use of this software

13 .\" must display the following acknowledgement:

14 .\" This product includes software developed by the University of

15 .\" California, Berkeley and its contributors.

16 .\" 4. Neither the name of the University nor the names of its contributors

17 .\" may be used to endorse or promote products derived from this software

18 .\" without specific prior written permission.

19 .\"

20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

30 .\" SUCH DAMAGE.

31 .\"

32 .\" @(#)chown.2 8.4 (Berkeley) 4/19/94

33 .\"

34 .Dd April 19, 1994

35 .Dt CHOWN 2

36 .Os

37 .Sh NAME

38 .Nm chown ,

39 .Nm fchown ,

40 .Nm lchown ,

41 .Nm fchownat

42 .Nd change owner and group of a file

43 .Sh SYNOPSIS

44 .In unistd.h

45 .Ft int

46 .Fo chown

47 .Fa "const char *path"

48 .Fa "uid_t owner"

49 .Fa "gid_t group"

50 .Fc

51 .Ft int

52 .Fo fchown

53 .Fa "int fildes"

54 .Fa "uid_t owner"

55 .Fa "gid_t group"

56 .Fc

57 .Ft int

58 .Fo lchown

59 .Fa "const char *path"

60 .Fa "uid_t owner"

61 .Fa "gid_t group"

62 .Fc

63 .Ft int

64 .Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag"

65 .Sh DESCRIPTION

66 The owner ID and group ID of the file

67 named by

68 .Fa path

69 or referenced by

70 .Fa fildes

71 is changed as specified by the arguments

72 .Fa owner

73 and

74 .Fa group .

75 The owner of a file may change the

76 .Fa group

77 to a group of which

78 he or she is a member,

79 but the change

80 .Fa owner

81 capability is restricted to the super-user.

82 .Pp

83 The

84 .Fn chown

85 system call clears the set-user-id and set-group-id bits on the file.

86 The

87 .Fn chown

88 system call

89 follows symbolic links to operate on the target of the link

90 rather than the link itself.

91 .Pp

92 The

93 .Fn fchown

94 system call

95 is particularly useful when used in conjunction

96 with the file locking primitives (see

97 .Xr flock 2 ) .

98 .Pp

99 The

100 .Fn lchown

101 system call is similar to

102 .Fn chown

103 but does not follow symbolic links.

104 .Pp

105 The

106 .Fn fchownat

107 system call is equivalent to the

108 .Fn chown

109 and

110 .Fn lchown

111 except in the case where

112 .Fa path

113 specifies a relative path.

114 In this case the file to be changed is determined relative to the directory

115 associated with the file descriptor

116 .Fa fd

117 instead of the current working directory.

118 .Pp

119 Values for

120 .Fa flag

121 are constructed by a bitwise-inclusive OR of flags from the following

122 list, defined in

123 .In fcntl.h :

124 .Bl -tag -width indent

125 .It Dv AT_SYMLINK_NOFOLLOW

126 If

127 .Fa path

128 names a symbolic link, ownership of the symbolic link is changed.

129 .El

130 .Pp

131 If

132 .Fn fchownat

133 is passed the special value

134 .Dv AT_FDCWD

135 in the

136 .Fa fd

137 parameter, the current working directory is used and the behavior is identical

138 to a call to

139 .Fn chown

140 or

141 .Fn lchown

142 respectively, depending on whether or not the

143 .Dv AT_SYMLINK_NOFOLLOW

144 bit is set in the

145 .Fa flag

146 argument.

147 .Pp

148 One of the owner or group id's

149 may be left unchanged by specifying it as -1.

150 .Sh RETURN VALUES

151 .Rv -std

152 .Sh ERRORS

153 .Pp

154 The

155 .Fn chown

156 and

157 .Fn lchown

158 system calls will fail if:

159 .Bl -tag -width Er

160 .\" ==========

161 .It Bq Er EACCES

162 Search permission is denied for a component of the path prefix.

163 .It Bq Er EFAULT

164 The

165 .Fa path

166 argument

167 points outside the process's allocated address space.

168 .\" ==========

169 .It Bq Er ELOOP

170 Too many symbolic links are encountered in translating the pathname.

171 This is taken to be indicative of a looping symbolic link.

172 .\" ==========

173 .It Bq Er ENAMETOOLONG

174 A component of a pathname exceeded 255 characters,

175 or an entire path name exceeded 1023 characters.

176 .\" ==========

177 .It Bq Er ENOENT

178 A component of

179 .Fa path

180 does not exist.

181 .\" ==========

182 .It Bq Er ENOTDIR

183 A component of the path prefix is not a directory.

184 .El

185 .Pp

186 The

187 .Fn fchown

188 system call will fail if:

189 .Bl -tag -width Er

190 .\" ==========

191 .It Bq Er EBADF

192 The

193 .Fa fildes

194 argument

195 does not refer to a valid descriptor.

196 .\" ==========

197 .It Bq Er EINVAL

198 The

199 .Fa fildes

200 argument

201 refers to a socket, not a file.

202 .El

203 .Pp

204 Any of these calls will fail if:

205 .Bl -tag -width Er

206 .\" ==========

207 .It Bq Er EINTR

208 Its execution is interrupted by a signal.

209 .\" ==========

210 .It Bq Er EIO

211 An I/O error occurs while reading from or writing to the file system.

212 .\" ==========

213 .It Bq Er EPERM

214 The effective user ID does not match the owner of the file

215 and the calling process does not have appropriate (i.e., root) privileges.

216 .\" ==========

217 .It Bq Er EROFS

218 The named file resides on a read-only file system.

219 .El

220 .Pp

221 In addition to the errors specified for

222 .Fn chown

223 and

224 .Fn lchown ,

225 the

226 .Fn fchownat

227 system call may fail if:

228 .Bl -tag -width Er

229 .It Bq Er EBADF

230 The

231 .Fa path

232 argument does not specify an absolute path and the

233 .Fa fd

234 argument is neither

235 .Dv AT_FDCWD

236 nor a valid file descriptor open for searching.

237 .It Bq Er EINVAL

238 The value of the

239 .Fa flag

240 argument is not valid.

241 .It Bq Er ENOTDIR

242 The

243 .Fa path

244 argument is not an absolute path and

245 .Fa fd

246 is neither

247 .Dv AT_FDCWD

248 nor a file descriptor associated with a directory.

249 .El

250 .Sh SEE ALSO

251 .Xr chgrp 1 ,

252 .Xr chmod 2 ,

253 .Xr flock 2 ,

254 .Xr chown 8

255 .Sh STANDARDS

256 The

257 .Fn chown

258 system call is expected to conform to

259 .St -p1003.1-90 .

260 The

261 .Fn fchownat

262 system call is expected to conform to POSIX.1-2008 .

263 .Sh HISTORY

264 The

265 .Fn chown

266 function appeared in

267 .At v7 .

268 The

269 .Fn fchown

270 system call appeared in

271 .Bx 4.2 .

272 .Pp

273 The

274 .Fn chown

275 and

276 .Fn fchown

277 system calls were changed to follow symbolic links in

278 .Bx 4.4 .

279 The

280 .Fn lchown

281 system call was added in

282 .Fx 3.0

283 to compensate for the loss of functionality.

284 .Pp

285 The

286 .Fn fchownat

287 system call appeared in OS X 10.10