bsd/man/man2/chown.2

   1 .\" Copyright (c) 1980, 1991, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   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
  86 clears the set-user-id and set-group-id bits
  87 on the file
  88 to prevent accidental or mischievous creation of
  89 set-user-id and set-group-id programs if not executed
  90 by the super-user.
  91 The
  92 .Fn chown
  93 system call
  94 follows symbolic links to operate on the target of the link
  95 rather than the link itself.
  96 .Pp
  97 The
  98 .Fn fchown
  99 system call
 100 is particularly useful when used in conjunction
 101 with the file locking primitives (see
 102 .Xr flock 2 ) .
 103 .Pp
 104 The
 105 .Fn lchown
 106 system call is similar to
 107 .Fn chown
 108 but does not follow symbolic links.
 109 .Pp
 110 The
 111 .Fn fchownat
 112 system call is equivalent to the
 113 .Fn chown
 114 and
 115 .Fn lchown
 116 except in the case where
 117 .Fa path
 118 specifies a relative path.
 119 In this case the file to be changed is determined relative to the directory
 120 associated with the file descriptor
 121 .Fa fd
 122 instead of the current working directory.
 123 .Pp
 124 Values for
 125 .Fa flag
 126 are constructed by a bitwise-inclusive OR of flags from the following
 127 list, defined in
 128 .In fcntl.h :
 129 .Bl -tag -width indent
 130 .It Dv AT_SYMLINK_NOFOLLOW
 131 If
 132 .Fa path
 133 names a symbolic link, ownership of the symbolic link is changed.
 134 .El
 135 .Pp
 136 If
 137 .Fn fchownat
 138 is passed the special value
 139 .Dv AT_FDCWD
 140 in the
 141 .Fa fd
 142 parameter, the current working directory is used and the behavior is identical
 143 to a call to
 144 .Fn chown
 145 or
 146 .Fn lchown
 147 respectively, depending on whether or not the
 148 .Dv AT_SYMLINK_NOFOLLOW
 149 bit is set in the
 150 .Fa flag
 151 argument.
 152 .Pp
 153 One of the owner or group id's
 154 may be left unchanged by specifying it as -1.
 155 .Sh RETURN VALUES
 156 .Rv -std
 157 .Sh ERRORS
 158 .Pp
 159 The
 160 .Fn chown
 161 and
 162 .Fn lchown
 163 system calls will fail if:
 164 .Bl -tag -width Er
 165 .\" ==========
 166 .It Bq Er EACCES
 167 Search permission is denied for a component of the path prefix.
 168 .It Bq Er EFAULT
 169 The
 170 .Fa path
 171 argument
 172 points outside the process's allocated address space.
 173 .\" ==========
 174 .It Bq Er ELOOP
 175 Too many symbolic links are encountered in translating the pathname.
 176 This is taken to be indicative of a looping symbolic link.
 177 .\" ==========
 178 .It Bq Er ENAMETOOLONG
 179 A component of a pathname exceeded 255 characters,
 180 or an entire path name exceeded 1023 characters.
 181 .\" ==========
 182 .It Bq Er ENOENT
 183 A component of
 184 .Fa path
 185 does not exist.
 186 .\" ==========
 187 .It Bq Er ENOTDIR
 188 A component of the path prefix is not a directory.
 189 .El
 190 .Pp
 191 The
 192 .Fn fchown
 193 system call will fail if:
 194 .Bl -tag -width Er
 195 .\" ==========
 196 .It Bq Er EBADF
 197 The
 198 .Fa fildes
 199 argument
 200 does not refer to a valid descriptor.
 201 .\" ==========
 202 .It Bq Er EINVAL
 203 The
 204 .Fa fildes
 205 argument
 206 refers to a socket, not a file.
 207 .El
 208 .Pp
 209 Any of these calls will fail if:
 210 .Bl -tag -width Er
 211 .\" ==========
 212 .It Bq Er EINTR
 213 Its execution is interrupted by a signal.
 214 .\" ==========
 215 .It Bq Er EIO
 216 An I/O error occurs while reading from or writing to the file system.
 217 .\" ==========
 218 .It Bq Er EPERM
 219 The effective user ID does not match the owner of the file
 220 and the calling process does not have appropriate (i.e., root) privileges.
 221 .\" ==========
 222 .It Bq Er EROFS
 223 The named file resides on a read-only file system.
 224 .El
 225 .Pp
 226 In addition to the errors specified for
 227 .Fn chown
 228 and
 229 .Fn lchown ,
 230 the
 231 .Fn fchownat
 232 system call may fail if:
 233 .Bl -tag -width Er
 234 .It Bq Er EBADF
 235 The
 236 .Fa path
 237 argument does not specify an absolute path and the
 238 .Fa fd
 239 argument is neither
 240 .Dv AT_FDCWD
 241 nor a valid file descriptor open for searching.
 242 .It Bq Er EINVAL
 243 The value of the
 244 .Fa flag
 245 argument is not valid.
 246 .It Bq Er ENOTDIR
 247 The
 248 .Fa path
 249 argument is not an absolute path and
 250 .Fa fd
 251 is neither
 252 .Dv AT_FDCWD
 253 nor a file descriptor associated with a directory.
 254 .El
 255 .Sh SEE ALSO
 256 .Xr chgrp 1 ,
 257 .Xr chmod 2 ,
 258 .Xr flock 2 ,
 259 .Xr chown 8
 260 .Sh STANDARDS
 261 The
 262 .Fn chown
 263 system call is expected to conform to
 264 .St -p1003.1-90 .
 265 The
 266 .Fn fchownat
 267 system call is expected to conform to POSIX.1-2008 .
 268 .Sh HISTORY
 269 The
 270 .Fn chown
 271 function appeared in
 272 .At v7 .
 273 The
 274 .Fn fchown
 275 system call appeared in
 276 .Bx 4.2 .
 277 .Pp
 278 The
 279 .Fn chown
 280 and
 281 .Fn fchown
 282 system calls were changed to follow symbolic links in
 283 .Bx 4.4 .
 284 The
 285 .Fn lchown
 286 system call was added in
 287 .Fx 3.0
 288 to compensate for the loss of functionality.
 289 .Pp
 290 The
 291 .Fn fchownat
 292 system call appeared in OS X 10.10