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 .\" 4. 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 .\"     @(#)chown.2     8.4 (Berkeley) 4/19/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd December 9, 2006
  32 .Dt CHOWN 2
  33 .Os
  34 .Sh NAME
  35 .Nm chown ,
  36 .Nm fchown ,
  37 .Nm lchown
  38 .Nd change owner and group of a file
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Ft int
  44 .Fn chown "const char *path" "uid_t owner" "gid_t group"
  45 .Ft int
  46 .Fn fchown "int fd" "uid_t owner" "gid_t group"
  47 .Ft int
  48 .Fn lchown "const char *path" "uid_t owner" "gid_t group"
  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 One of the owner or group id's
  95 may be left unchanged by specifying it as -1.
  96 .Sh RETURN VALUES
  97 .Rv -std
  98 .Sh ERRORS
  99 The
 100 .Fn chown
 101 and
 102 .Fn lchown
 103 will fail and the file will be unchanged if:
 104 .Bl -tag -width Er
 105 .It Bq Er ENOTDIR
 106 A component of the path prefix is not a directory.
 107 .It Bq Er ENAMETOOLONG
 108 A component of a pathname exceeded 255 characters,
 109 or an entire path name exceeded 1023 characters.
 110 .It Bq Er ENOENT
 111 The named file does not exist.
 112 .It Bq Er EACCES
 113 Search permission is denied for a component of the path prefix.
 114 .It Bq Er ELOOP
 115 Too many symbolic links were encountered in translating the pathname.
 116 .It Bq Er EPERM
 117 The operation would change the ownership, but the effective user ID is not the
 118 super-user.
 119 .It Bq Er EPERM
 120 The named file has its immutable or append-only flag set, see the
 121 .Xr chflags 2
 122 manual page for more information.
 123 .It Bq Er EROFS
 124 The named file resides on a read-only file system.
 125 .It Bq Er EFAULT
 126 The
 127 .Fa path
 128 argument
 129 points outside the process's allocated address space.
 130 .It Bq Er EIO
 131 An I/O error occurred while reading from or writing to the file system.
 132 .El
 133 .Pp
 134 The
 135 .Fn fchown
 136 system call will fail if:
 137 .Bl -tag -width Er
 138 .It Bq Er EBADF
 139 The
 140 .Fa fd
 141 argument
 142 does not refer to a valid descriptor.
 143 .It Bq Er EINVAL
 144 The
 145 .Fa fd
 146 argument
 147 refers to a socket, not a file.
 148 .It Bq Er EPERM
 149 The effective user ID is not the super-user.
 150 .It Bq Er EROFS
 151 The named file resides on a read-only file system.
 152 .It Bq Er EIO
 153 An I/O error occurred while reading from or writing to the file system.
 154 .El
 155 .Sh SEE ALSO
 156 .Xr chgrp 1 ,
 157 .Xr chflags 2 ,
 158 .Xr chmod 2 ,
 159 .Xr flock 2 ,
 160 .Xr chown 8
 161 .Sh STANDARDS
 162 The
 163 .Fn chown
 164 system call is expected to conform to
 165 .St -p1003.1-90 .
 166 .Sh HISTORY
 167 The
 168 .Fn chown
 169 function appeared in
 170 .At v7 .
 171 The
 172 .Fn fchown
 173 system call appeared in
 174 .Bx 4.2 .
 175 .Pp
 176 The
 177 .Fn chown
 178 system call was changed to follow symbolic links in
 179 .Bx 4.4 .
 180 The
 181 .Fn lchown
 182 system call was added in
 183 .Fx 3.0
 184 to compensate for the loss of functionality.