lib/libc/sys/chown.2

   1 .\"     $NetBSD: chown.2,v 1.36 2013/07/30 12:38:16 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 July 30, 2013
  33 .Dt CHOWN 2
  34 .Os
  35 .Sh NAME
  36 .Nm chown ,
  37 .Nm lchown ,
  38 .Nm fchown ,
  39 .Nm fchownat
  40 .Nd change owner and group of a file
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft int
  46 .Fn chown "const char *path" "uid_t owner" "gid_t group"
  47 .Ft int
  48 .Fn lchown "const char *path" "uid_t owner" "gid_t group"
  49 .Ft int
  50 .Fn fchown "int fd" "uid_t owner" "gid_t group"
  51 .In fcntl.h
  52 .Ft int
  53 .Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag"
  54 .Sh DESCRIPTION
  55 The owner ID and group ID of the file
  56 named by
  57 .Fa path
  58 or referenced by
  59 .Fa fd
  60 is changed as specified by the arguments
  61 .Fa owner
  62 and
  63 .Fa group .
  64 The owner of a file may change the
  65 .Fa group
  66 to a group of which
  67 he or she is a member,
  68 but the change
  69 .Fa owner
  70 capability is restricted to the super-user.
  71 .Pp
  72 When called to change the owner of a file,
  73 .Fn chown ,
  74 .Fn lchown
  75 and
  76 .Fn fchown
  77 clear the set-user-id
  78 .Dv ( S_ISUID )
  79 bit on the file.
  80 When a called to change the group of a file,
  81 .Fn chown ,
  82 .Fn lchown
  83 and
  84 .Fn fchown
  85 clear the set-group-id
  86 .Dv ( S_ISGID )
  87 bit on the file.
  88 These actions are taken to prevent accidental or mischievous creation of
  89 set-user-id and set-group-id programs.
  90 .Pp
  91 .Fn lchown
  92 is like
  93 .Fn chown
  94 except in the case where the named file is a symbolic link,
  95 in which case
  96 .Fn lchown
  97 changes the owner and group of the link,
  98 while
  99 .Fn chown
 100 changes the owner and group of the file the link references.
 101 .Pp
 102 .Fn fchown
 103 is particularly useful when used in conjunction
 104 with the file locking primitives (see
 105 .Xr flock 2 ) .
 106 .Pp
 107 .Fn fchownat
 108 works the same way as
 109 .Fn chown
 110 (or
 111 .Fn lchown
 112 if
 113 .Dv AT_SYMLINK_NOFOLLOW
 114 is set in
 115 .Fa flag )
 116 except if
 117 .Fa path
 118 is relative.
 119 In that case, it is looked up from a directory whose file
 120 descriptor was passed as
 121 .Fa fd .
 122 Search permission is required on this directory.
 123 .\"    (These alternatives await a decision about the semantics of O_SEARCH)
 124 .\" Search permission is required on this directory
 125 .\" except if
 126 .\" .Fa fd
 127 .\" was opened with the
 128 .\" .Dv O_SEARCH
 129 .\" flag.
 130 .\"    - or -
 131 .\" This file descriptor must have been opened with the
 132 .\" .Dv O_SEARCH
 133 .\" flag.
 134 .Fa fd
 135 can be set to
 136 .Dv AT_FDCWD
 137 in order to specify the current directory.
 138 .Pp
 139 One of the owner or group id's
 140 may be left unchanged by specifying it as (uid_t)\-1 or (gid_t)\-1 respectively.
 141 .Sh RETURN VALUES
 142 .Rv -std chown lchown fchown fchownat
 143 .Sh ERRORS
 144 .Fn chown ,
 145 .Fn lchown
 146 and
 147 .Fn fchownat
 148 will fail and the file will be unchanged if:
 149 .Bl -tag -width Er
 150 .It Bq Er EACCES
 151 Search permission is denied for a component of the path prefix.
 152 .It Bq Er EFAULT
 153 .Fa path
 154 points outside the process's allocated address space.
 155 .It Bq Er EIO
 156 An I/O error occurred while reading from or writing to the file system.
 157 .It Bq Er ELOOP
 158 Too many symbolic links were encountered in translating the pathname.
 159 .It Bq Er ENAMETOOLONG
 160 A component of a pathname exceeded
 161 .Brq Dv NAME_MAX
 162 characters, or an entire path name exceeded
 163 .Brq Dv PATH_MAX
 164 characters.
 165 .It Bq Er ENOENT
 166 The named file does not exist.
 167 .It Bq Er ENOTDIR
 168 A component of the path prefix is not a directory.
 169 .It Bq Er EPERM
 170 The effective user ID is not the super-user.
 171 .It Bq Er EROFS
 172 The named file resides on a read-only file system.
 173 .El
 174 .Pp
 175 In addition,
 176 .Fn fchownat
 177 will fail if:
 178 .Bl -tag -width Er
 179 .It Bq Er EBADF
 180 .Fa path
 181 does not specify an absolute path and
 182 .Fa fd
 183 is neither
 184 .Dv AT_FDCWD
 185 nor a valid file descriptor open for reading or searching.
 186 .It Bq Er ENOTDIR
 187 .Fa path
 188 is not an absolute path and
 189 .Fa fd
 190 is a file descriptor associated with a non-directory file.
 191 .El
 192 .Pp
 193 .Fn fchown
 194 will fail if:
 195 .Bl -tag -width Er
 196 .It Bq Er EBADF
 197 .Fa fd
 198 does not refer to a valid descriptor.
 199 .It Bq Er EINVAL
 200 .Fa fd
 201 refers to a socket, not a file.
 202 .It Bq Er EIO
 203 An I/O error occurred while reading from or writing to the file system.
 204 .It Bq Er EPERM
 205 The effective user ID is not the super-user.
 206 .It Bq Er EROFS
 207 The named file resides on a read-only file system.
 208 .El
 209 .Sh SEE ALSO
 210 .Xr chgrp 1 ,
 211 .Xr chmod 2 ,
 212 .Xr flock 2 ,
 213 .Xr symlink 7 ,
 214 .Xr chown 8
 215 .Sh STANDARDS
 216 The
 217 .Fn chown
 218 function deviates from the semantics defined in
 219 .St -p1003.1-90 ,
 220 which specifies that, unless the caller is the super-user, both the
 221 set-user-id and set-group-id bits on a file shall be cleared, regardless
 222 of the file attribute changed.
 223 The
 224 .Fn lchown
 225 and
 226 .Fn fchown
 227 functions, as defined by
 228 .St -xpg4.2 ,
 229 provide the same semantics.
 230 .Fn fchownat
 231 conforms to
 232 .St -p1003.1-2008 .
 233 .Pp
 234 To retain conformance to these standards, compatibility interfaces
 235 are provided by the
 236 .Lb libposix
 237 as follows:
 238 .Bl -bullet -compact
 239 .It
 240 The
 241 .Fn chown
 242 function conforms to
 243 .St -p1003.1-90
 244 and
 245 .St -xpg4.2 .
 246 .It
 247 The
 248 .Fn lchown
 249 and
 250 .Fn fchown
 251 functions conform to
 252 .St -xpg4.2 .
 253 .El
 254 .Sh HISTORY
 255 The
 256 .Fn fchown
 257 function call appeared in
 258 .Bx 4.2 .
 259 .Pp
 260 The
 261 .Fn chown
 262 and
 263 .Fn fchown
 264 functions were changed to follow symbolic links in
 265 .Bx 4.4 .
 266 The
 267 .Fn lchown
 268 function call appeared in
 269 .Nx 1.3 .