lib/libc/sys/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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd March 30, 2021
  29 .Dt CHOWN 2
  30 .Os
  31 .Sh NAME
  32 .Nm chown ,
  33 .Nm fchown ,
  34 .Nm lchown ,
  35 .Nm fchownat
  36 .Nd change owner and group of a file
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In unistd.h
  41 .Ft int
  42 .Fn chown "const char *path" "uid_t owner" "gid_t group"
  43 .Ft int
  44 .Fn fchown "int fd" "uid_t owner" "gid_t group"
  45 .Ft int
  46 .Fn lchown "const char *path" "uid_t owner" "gid_t group"
  47 .Ft int
  48 .Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag"
  49 .Sh DESCRIPTION
  50 The owner ID and group ID of the file
  51 named by
  52 .Fa path
  53 or referenced by
  54 .Fa fd
  55 is changed as specified by the arguments
  56 .Fa owner
  57 and
  58 .Fa group .
  59 The owner of a file may change the
  60 .Fa group
  61 to a group of which
  62 he or she is a member,
  63 but the change
  64 .Fa owner
  65 capability is restricted to the super-user.
  66 .Pp
  67 The
  68 .Fn chown
  69 system call
  70 clears the set-user-id and set-group-id bits
  71 on the file
  72 to prevent accidental or mischievous creation of
  73 set-user-id and set-group-id programs if not executed
  74 by the super-user.
  75 The
  76 .Fn chown
  77 system call
  78 follows symbolic links to operate on the target of the link
  79 rather than the link itself.
  80 .Pp
  81 The
  82 .Fn fchown
  83 system call
  84 is particularly useful when used in conjunction
  85 with the file locking primitives (see
  86 .Xr flock 2 ) .
  87 .Pp
  88 The
  89 .Fn lchown
  90 system call is similar to
  91 .Fn chown
  92 but does not follow symbolic links.
  93 .Pp
  94 The
  95 .Fn fchownat
  96 system call is equivalent to the
  97 .Fn chown
  98 and
  99 .Fn lchown
 100 except in the case where
 101 .Fa path
 102 specifies a relative path.
 103 In this case the file to be changed is determined relative to the directory
 104 associated with the file descriptor
 105 .Fa fd
 106 instead of the current working directory.
 107 .Pp
 108 Values for
 109 .Fa flag
 110 are constructed by a bitwise-inclusive OR of flags from the following
 111 list, defined in
 112 .In fcntl.h :
 113 .Bl -tag -width indent
 114 .It Dv AT_SYMLINK_NOFOLLOW
 115 If
 116 .Fa path
 117 names a symbolic link, ownership of the symbolic link is changed.
 118 .It Dv AT_RESOLVE_BENEATH
 119 Only walk paths below the directory specified by the
 120 .Ar fd
 121 descriptor.
 122 See the description of the
 123 .Dv O_RESOLVE_BENEATH
 124 flag in the
 125 .Xr open 2
 126 manual page.
 127 .It Dv AT_EMPTY_PATH
 128 If the
 129 .Fa path
 130 argument is an empty string, operate on the file or directory
 131 referenced by the descriptor
 132 .Fa fd .
 133 If
 134 .Fa fd
 135 is equal to
 136 .Dv AT_FDCWD ,
 137 operate on the current working directory.
 138 .El
 139 .Pp
 140 If
 141 .Fn fchownat
 142 is passed the special value
 143 .Dv AT_FDCWD
 144 in the
 145 .Fa fd
 146 parameter, the current working directory is used and the behavior is identical
 147 to a call to
 148 .Fn chown
 149 or
 150 .Fn lchown
 151 respectively, depending on whether or not the
 152 .Dv AT_SYMLINK_NOFOLLOW
 153 bit is set in the
 154 .Fa flag
 155 argument.
 156 .Pp
 157 One of the owner or group id's
 158 may be left unchanged by specifying it as -1.
 159 .Sh RETURN VALUES
 160 .Rv -std
 161 .Sh ERRORS
 162 The
 163 .Fn chown
 164 and
 165 .Fn lchown
 166 will fail and the file will be unchanged if:
 167 .Bl -tag -width Er
 168 .It Bq Er ENOTDIR
 169 A component of the path prefix is not a directory.
 170 .It Bq Er ENAMETOOLONG
 171 A component of a pathname exceeded 255 characters,
 172 or an entire path name exceeded 1023 characters.
 173 .It Bq Er ENOENT
 174 The named file does not exist.
 175 .It Bq Er EACCES
 176 Search permission is denied for a component of the path prefix.
 177 .It Bq Er ELOOP
 178 Too many symbolic links were encountered in translating the pathname.
 179 .It Bq Er EPERM
 180 The operation would change the ownership, but the effective user ID is not the
 181 super-user.
 182 .It Bq Er EPERM
 183 The named file has its immutable or append-only flag set, see the
 184 .Xr chflags 2
 185 manual page for more information.
 186 .It Bq Er EROFS
 187 The named file resides on a read-only file system.
 188 .It Bq Er EFAULT
 189 The
 190 .Fa path
 191 argument
 192 points outside the process's allocated address space.
 193 .It Bq Er EIO
 194 An I/O error occurred while reading from or writing to the file system.
 195 .It Bq Er EINTEGRITY
 196 Corrupted data was detected while reading from the file system.
 197 .El
 198 .Pp
 199 The
 200 .Fn fchown
 201 system call will fail if:
 202 .Bl -tag -width Er
 203 .It Bq Er EBADF
 204 The
 205 .Fa fd
 206 argument
 207 does not refer to a valid descriptor.
 208 .It Bq Er EINVAL
 209 The
 210 .Fa fd
 211 argument
 212 refers to a socket, not a file.
 213 .It Bq Er EPERM
 214 The effective user ID is not the super-user.
 215 .It Bq Er EROFS
 216 The named file resides on a read-only file system.
 217 .It Bq Er EIO
 218 An I/O error occurred while reading from or writing to the file system.
 219 .It Bq Er EINTEGRITY
 220 Corrupted data was detected while reading from the file system.
 221 .El
 222 .Pp
 223 In addition to the errors specified for
 224 .Fn chown
 225 and
 226 .Fn lchown ,
 227 the
 228 .Fn fchownat
 229 system call may fail if:
 230 .Bl -tag -width Er
 231 .It Bq Er EBADF
 232 The
 233 .Fa path
 234 argument does not specify an absolute path and the
 235 .Fa fd
 236 argument is neither
 237 .Dv AT_FDCWD
 238 nor a valid file descriptor open for searching.
 239 .It Bq Er EINVAL
 240 The value of the
 241 .Fa flag
 242 argument is not valid.
 243 .It Bq Er ENOTDIR
 244 The
 245 .Fa path
 246 argument is not an absolute path and
 247 .Fa fd
 248 is neither
 249 .Dv AT_FDCWD
 250 nor a file descriptor associated with a directory.
 251 .It Bq Er ENOTCAPABLE
 252 .Fa path
 253 is an absolute path,
 254 or contained a ".." component leading to a
 255 directory outside of the directory hierarchy specified by
 256 .Fa fd ,
 257 and the process is in capability mode or the
 258 .Dv AT_RESOLVE_BENEATH
 259 flag was specified.
 260 .El
 261 .Sh SEE ALSO
 262 .Xr chgrp 1 ,
 263 .Xr chflags 2 ,
 264 .Xr chmod 2 ,
 265 .Xr flock 2 ,
 266 .Xr chown 8
 267 .Sh STANDARDS
 268 The
 269 .Fn chown
 270 system call is expected to conform to
 271 .St -p1003.1-90 .
 272 The
 273 .Fn fchownat
 274 system call follows The Open Group Extended API Set 2 specification.
 275 .Sh HISTORY
 276 The
 277 .Fn chown
 278 function appeared in
 279 .At v1 .
 280 The
 281 .Fn fchown
 282 system call appeared in
 283 .Bx 4.2 .
 284 .Pp
 285 The
 286 .Fn chown
 287 system call was changed to follow symbolic links in
 288 .Bx 4.4 .
 289 The
 290 .Fn lchown
 291 system call was added in
 292 .Fx 3.0
 293 to compensate for the loss of functionality.
 294 .Pp
 295 The
 296 .Fn fchownat
 297 system call appeared in
 298 .Fx 8.0 .