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 .Nd change owner and group of a file
  42 .Sh SYNOPSIS
  43 .In unistd.h
  44 .Ft int
  45 .Fo chown
  46 .Fa "const char *path"
  47 .Fa "uid_t owner"
  48 .Fa "gid_t group"
  49 .Fc
  50 .Ft int
  51 .Fo fchown
  52 .Fa "int fildes"
  53 .Fa "uid_t owner"
  54 .Fa "gid_t group"
  55 .Fc
  56 .Ft int
  57 .Fo lchown
  58 .Fa "const char *path"
  59 .Fa "uid_t owner"
  60 .Fa "gid_t group"
  61 .Fc
  62 .Sh DESCRIPTION
  63 The owner ID and group ID of the file
  64 named by
  65 .Fa path
  66 or referenced by
  67 .Fa fildes
  68 is changed as specified by the arguments
  69 .Fa owner
  70 and
  71 .Fa group .
  72 The owner of a file may change the
  73 .Fa group
  74 to a group of which
  75 he or she is a member,
  76 but the change
  77 .Fa owner
  78 capability is restricted to the super-user.
  79 .Pp
  80 The
  81 .Fn chown
  82 system call
  83 clears the set-user-id and set-group-id bits
  84 on the file
  85 to prevent accidental or mischievous creation of
  86 set-user-id and set-group-id programs if not executed
  87 by the super-user.
  88 The
  89 .Fn chown
  90 system call
  91 follows symbolic links to operate on the target of the link
  92 rather than the link itself.
  93 .Pp
  94 The
  95 .Fn fchown
  96 system call
  97 is particularly useful when used in conjunction
  98 with the file locking primitives (see
  99 .Xr flock 2 ) .
 100 .Pp
 101 The
 102 .Fn lchown
 103 system call is similar to
 104 .Fn chown
 105 but does not follow symbolic links.
 106 .Pp
 107 One of the owner or group id's
 108 may be left unchanged by specifying it as -1.
 109 .Sh RETURN VALUES
 110 .Rv -std
 111 .Sh ERRORS
 112 .Pp
 113 The
 114 .Fn chown
 115 and
 116 .Fn lchown
 117 system calls will fail if:
 118 .Bl -tag -width Er
 119 .\" ==========
 120 .It Bq Er EACCES
 121 Search permission is denied for a component of the path prefix.
 122 .It Bq Er EFAULT
 123 The
 124 .Fa path
 125 argument
 126 points outside the process's allocated address space.
 127 .\" ==========
 128 .It Bq Er ELOOP
 129 Too many symbolic links are encountered in translating the pathname.
 130 This is taken to be indicative of a looping symbolic link.
 131 .\" ==========
 132 .It Bq Er ENAMETOOLONG
 133 A component of a pathname exceeded 255 characters,
 134 or an entire path name exceeded 1023 characters.
 135 .\" ==========
 136 .It Bq Er ENOENT
 137 A component of
 138 .Fa path
 139 does not exist.
 140 .\" ==========
 141 .It Bq Er ENOTDIR
 142 A component of the path prefix is not a directory.
 143 .El
 144 .Pp
 145 The
 146 .Fn fchown
 147 system call will fail if:
 148 .Bl -tag -width Er
 149 .\" ==========
 150 .It Bq Er EBADF
 151 The
 152 .Fa fildes
 153 argument
 154 does not refer to a valid descriptor.
 155 .\" ==========
 156 .It Bq Er EINVAL
 157 The
 158 .Fa fildes
 159 argument
 160 refers to a socket, not a file.
 161 .El
 162 .Pp
 163 Any of these calls will fail if:
 164 .Bl -tag -width Er
 165 .\" ==========
 166 .It Bq Er EINTR
 167 Its execution is interrupted by a signal.
 168 .\" ==========
 169 .It Bq Er EIO
 170 An I/O error occurs while reading from or writing to the file system.
 171 .\" ==========
 172 .It Bq Er EPERM
 173 The effective user ID does not match the owner of the file
 174 and the calling process does not have appropriate (i.e., root) privileges.
 175 .\" ==========
 176 .It Bq Er EROFS
 177 The named file resides on a read-only file system.
 178 .El
 179 .Sh SEE ALSO
 180 .Xr chgrp 1 ,
 181 .Xr chmod 2 ,
 182 .Xr flock 2 ,
 183 .Xr chown 8
 184 .Sh STANDARDS
 185 The
 186 .Fn chown
 187 system call is expected to conform to
 188 .St -p1003.1-90 .
 189 .Sh HISTORY
 190 The
 191 .Fn chown
 192 function appeared in
 193 .At v7 .
 194 The
 195 .Fn fchown
 196 system call appeared in
 197 .Bx 4.2 .
 198 .Pp
 199 The
 200 .Fn chown
 201 and
 202 .Fn fchown
 203 system calls were changed to follow symbolic links in
 204 .Bx 4.4 .
 205 The
 206 .Fn lchown
 207 system call was added in
 208 .Fx 3.0
 209 to compensate for the loss of functionality.