1.\" $NetBSD: chown.2,v 1.36 2013/07/30 12:38:16 njoly Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993, 1994 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)chown.2 8.4 (Berkeley) 4/19/94 31.\" 32.Dd July 30, 2013 33.Dt CHOWN 2 34.Os 35.Sh NAME 36.Nm chown , 37.Nm lchown , 38.Nm fchown , 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 lchown "const char *path" "uid_t owner" "gid_t group" 49.Ft int 50.Fn fchown "int fd" "uid_t owner" "gid_t group" 51.In fcntl.h 52.Ft int 53.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" 54.Sh DESCRIPTION 55The owner ID and group ID of the file 56named by 57.Fa path 58or referenced by 59.Fa fd 60is changed as specified by the arguments 61.Fa owner 62and 63.Fa group . 64The owner of a file may change the 65.Fa group 66to a group of which 67he or she is a member, 68but the change 69.Fa owner 70capability is restricted to the super-user. 71.Pp 72When called to change the owner of a file, 73.Fn chown , 74.Fn lchown 75and 76.Fn fchown 77clear the set-user-id 78.Dv ( S_ISUID ) 79bit on the file. 80When a called to change the group of a file, 81.Fn chown , 82.Fn lchown 83and 84.Fn fchown 85clear the set-group-id 86.Dv ( S_ISGID ) 87bit on the file. 88These actions are taken to prevent accidental or mischievous creation of 89set-user-id and set-group-id programs. 90.Pp 91.Fn lchown 92is like 93.Fn chown 94except in the case where the named file is a symbolic link, 95in which case 96.Fn lchown 97changes the owner and group of the link, 98while 99.Fn chown 100changes the owner and group of the file the link references. 101.Pp 102.Fn fchown 103is particularly useful when used in conjunction 104with the file locking primitives (see 105.Xr flock 2 ) . 106.Pp 107.Fn fchownat 108works the same way as 109.Fn chown 110(or 111.Fn lchown 112if 113.Dv AT_SYMLINK_NOFOLLOW 114is set in 115.Fa flag ) 116except if 117.Fa path 118is relative. 119In that case, it is looked up from a directory whose file 120descriptor was passed as 121.Fa fd . 122Search permission is required on this directory. 123.\" (These alternatives await a decision about the semantics of O_SEARCH) 124.\" Search permission is required on this directory 125.\" except if 126.\" .Fa fd 127.\" was opened with the 128.\" .Dv O_SEARCH 129.\" flag. 130.\" - or - 131.\" This file descriptor must have been opened with the 132.\" .Dv O_SEARCH 133.\" flag. 134.Fa fd 135can be set to 136.Dv AT_FDCWD 137in order to specify the current directory. 138.Pp 139One of the owner or group id's 140may be left unchanged by specifying it as (uid_t)\-1 or (gid_t)\-1 respectively. 141.Sh RETURN VALUES 142.Rv -std chown lchown fchown fchownat 143.Sh ERRORS 144.Fn chown , 145.Fn lchown 146and 147.Fn fchownat 148will fail and the file will be unchanged if: 149.Bl -tag -width Er 150.It Bq Er EACCES 151Search permission is denied for a component of the path prefix. 152.It Bq Er EFAULT 153.Fa path 154points outside the process's allocated address space. 155.It Bq Er EIO 156An I/O error occurred while reading from or writing to the file system. 157.It Bq Er ELOOP 158Too many symbolic links were encountered in translating the pathname. 159.It Bq Er ENAMETOOLONG 160A component of a pathname exceeded 161.Brq Dv NAME_MAX 162characters, or an entire path name exceeded 163.Brq Dv PATH_MAX 164characters. 165.It Bq Er ENOENT 166The named file does not exist. 167.It Bq Er ENOTDIR 168A component of the path prefix is not a directory. 169.It Bq Er EPERM 170The effective user ID is not the super-user. 171.It Bq Er EROFS 172The named file resides on a read-only file system. 173.El 174.Pp 175In addition, 176.Fn fchownat 177will fail if: 178.Bl -tag -width Er 179.It Bq Er EBADF 180.Fa path 181does not specify an absolute path and 182.Fa fd 183is neither 184.Dv AT_FDCWD 185nor a valid file descriptor open for reading or searching. 186.It Bq Er ENOTDIR 187.Fa path 188is not an absolute path and 189.Fa fd 190is a file descriptor associated with a non-directory file. 191.El 192.Pp 193.Fn fchown 194will fail if: 195.Bl -tag -width Er 196.It Bq Er EBADF 197.Fa fd 198does not refer to a valid descriptor. 199.It Bq Er EINVAL 200.Fa fd 201refers to a socket, not a file. 202.It Bq Er EIO 203An I/O error occurred while reading from or writing to the file system. 204.It Bq Er EPERM 205The effective user ID is not the super-user. 206.It Bq Er EROFS 207The named file resides on a read-only file system. 208.El 209.Sh SEE ALSO 210.Xr chgrp 1 , 211.Xr chmod 2 , 212.Xr flock 2 , 213.Xr symlink 7 , 214.Xr chown 8 215.Sh STANDARDS 216The 217.Fn chown 218function deviates from the semantics defined in 219.St -p1003.1-90 , 220which specifies that, unless the caller is the super-user, both the 221set-user-id and set-group-id bits on a file shall be cleared, regardless 222of the file attribute changed. 223The 224.Fn lchown 225and 226.Fn fchown 227functions, as defined by 228.St -xpg4.2 , 229provide the same semantics. 230.Fn fchownat 231conforms to 232.St -p1003.1-2008 . 233.Pp 234To retain conformance to these standards, compatibility interfaces 235are provided by the 236.Lb libposix 237as follows: 238.Bl -bullet -compact 239.It 240The 241.Fn chown 242function conforms to 243.St -p1003.1-90 244and 245.St -xpg4.2 . 246.It 247The 248.Fn lchown 249and 250.Fn fchown 251functions conform to 252.St -xpg4.2 . 253.El 254.Sh HISTORY 255The 256.Fn fchown 257function call appeared in 258.Bx 4.2 . 259.Pp 260The 261.Fn chown 262and 263.Fn fchown 264functions were changed to follow symbolic links in 265.Bx 4.4 . 266The 267.Fn lchown 268function call appeared in 269.Nx 1.3 . 270