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