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. 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 .\" $FreeBSD: src/lib/libc/sys/chown.2,v 1.12.2.6 2001/12/14 18:34:00 ru Exp $
  34 .\" $DragonFly: src/lib/libc/sys/chown.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
  35 .\"
  36 .Dd August 9, 2009
  37 .Dt CHOWN 2
  38 .Os
  39 .Sh NAME
  40 .Nm chown ,
  41 .Nm fchown ,
  42 .Nm lchown ,
  43 .Nm fchownat
  44 .Nd change owner and group of a file
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In unistd.h
  49 .Ft int
  50 .Fn chown "const char *path" "uid_t owner" "gid_t group"
  51 .Ft int
  52 .Fn fchown "int fd" "uid_t owner" "gid_t group"
  53 .Ft int
  54 .Fn lchown "const char *path" "uid_t owner" "gid_t group"
  55 .Ft int
  56 .Fn fchownat "int dirfd" "const char *path" "uid_t owner" "gid_t group" "int flags"
  57 .Sh DESCRIPTION
  58 The owner ID and group ID of the file
  59 named by
  60 .Fa path
  61 or referenced by
  62 .Fa fd
  63 is changed as specified by the arguments
  64 .Fa owner
  65 and
  66 .Fa group .
  67 The owner of a file may change the
  68 .Fa group
  69 to a group of which
  70 he or she is a member,
  71 but the change
  72 .Fa owner
  73 capability is restricted to the super-user.
  74 .Pp
  75 .Fn Chown
  76 clears the set-user-id and set-group-id bits
  77 on the file
  78 to prevent accidental or mischievous creation of
  79 set-user-id and set-group-id programs if not executed
  80 by the super-user.
  81 .Fn chown
  82 follows symbolic links to operate on the target of the link
  83 rather than the link itself.
  84 .Pp
  85 .Fn Fchown
  86 is particularly useful when used in conjunction
  87 with the file locking primitives (see
  88 .Xr flock 2 ) .
  89 .Pp
  90 .Fn Lchown
  91 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 .Pp
  98 The
  99 .Fn fchownat
 100 function is equivalent to the
 101 .Fn chown
 102 or
 103 .Fn lchown
 104 functions except in the case where the
 105 .Fa path
 106 specifies a relative path.
 107 In this case the file to be opened is determined relative to the directory
 108 associated with the file descriptor
 109 .Fa dirfd
 110 instead of the current working directory.
 111 If
 112 .Fn fchownat
 113 is passed the special value
 114 .Dv AT_FDCWD
 115 in the
 116 .Fa dirfd
 117 parameter, the current working directory is used
 118 and the behavior is identical to a call to
 119 .Fn chown
 120 or
 121 .Fn lchown .
 122 .Pp
 123 The values for the
 124 .Fa flags
 125 are constructed by a bitwise-inclusive OR of flags from the following list,
 126 defined in
 127 .In fcntl.h :
 128 .Bl -tag -width indent
 129 .It Dv AT_SYMLINK_NOFOLLOW
 130 If
 131 .Fa path
 132 names a symbolic link, the mode of the symbolic link is changed.
 133 .El
 134 .Sh RETURN VALUES
 135 .Rv -std
 136 .Sh ERRORS
 137 .Fn Chown ,
 138 .Fn lchown
 139 and
 140 .Fn fchownat
 141 will fail and the file will be unchanged if:
 142 .Bl -tag -width Er
 143 .It Bq Er ENOTDIR
 144 A component of the path prefix or
 145 .Fa dirfd
 146 is not a directory.
 147 .It Bq Er ENAMETOOLONG
 148 A component of a pathname exceeded 255 characters,
 149 or an entire path name exceeded 1023 characters.
 150 .It Bq Er ENOENT
 151 The named file does not exist.
 152 .It Bq Er EACCES
 153 Search permission is denied for a component of the path prefix.
 154 .It Bq Er ELOOP
 155 Too many symbolic links were encountered in translating the pathname.
 156 .It Bq Er EPERM
 157 The effective user ID is not the super-user.
 158 .It Bq Er EROFS
 159 The named file resides on a read-only file system.
 160 .It Bq Er EFAULT
 161 .Fa Path
 162 points outside the process's allocated address space.
 163 .It Bq Er EIO
 164 An I/O error occurred while reading from or writing to the file system.
 165 .El
 166 .Pp
 167 .Fn Fchown
 168 will fail if:
 169 .Bl -tag -width Er
 170 .It Bq Er EBADF
 171 .Fa fd
 172 does not refer to a valid descriptor.
 173 .It Bq Er EINVAL
 174 .Fa fd
 175 refers to a socket, not a file.
 176 .It Bq Er EPERM
 177 The effective user ID is not the super-user.
 178 .It Bq Er EROFS
 179 The named file resides on a read-only file system.
 180 .It Bq Er EIO
 181 An I/O error occurred while reading from or writing to the file system.
 182 .El
 183 .Sh SEE ALSO
 184 .Xr chgrp 1 ,
 185 .Xr chmod 2 ,
 186 .Xr flock 2 ,
 187 .Xr chown 8
 188 .Sh STANDARDS
 189 The
 190 .Fn chown
 191 function call is expected to conform to
 192 .St -p1003.1-90 .
 193 .Sh HISTORY
 194 A
 195 .Fn chown
 196 function call appeared in
 197 .At v7 .
 198 The
 199 .Fn fchown
 200 function call
 201 appeared in
 202 .Bx 4.2 .
 203 .Pp
 204 The
 205 .Fn chown
 206 function was changed to follow symbolic links in
 207 .Bx 4.4 .
 208 The
 209 .Fn lchown
 210 function was added in
 211 .Fx 3.0
 212 to compensate for the loss of functionality.
 213 .Pp
 214 The
 215 .Fn fchownat
 216 system call appeared in
 217 .Dx 2.3 .