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