1.\" $NetBSD: chown.2,v 1.31 2010/05/31 12:16:20 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 April 19, 1994 33.Dt CHOWN 2 34.Os 35.Sh NAME 36.Nm chown , 37.Nm lchown , 38.Nm fchown 39.Nd change owner and group of a file 40.Sh LIBRARY 41.Lb libc 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 lchown "const char *path" "uid_t owner" "gid_t group" 48.Ft int 49.Fn fchown "int fd" "uid_t owner" "gid_t group" 50.Sh DESCRIPTION 51The owner ID and group ID of the file 52named by 53.Fa path 54or referenced by 55.Fa fd 56is changed as specified by the arguments 57.Fa owner 58and 59.Fa group . 60The owner of a file may change the 61.Fa group 62to a group of which 63he or she is a member, 64but the change 65.Fa owner 66capability is restricted to the super-user. 67.Pp 68When called to change the owner of a file, 69.Fn chown , 70.Fn lchown 71and 72.Fn fchown 73clear the set-user-id 74.Dv ( S_ISUID ) 75bit on the file. 76When a called to change the group of a file, 77.Fn chown , 78.Fn lchown 79and 80.Fn fchown 81clear the set-group-id 82.Dv ( S_ISGID ) 83bit on the file. 84These actions are taken to prevent accidental or mischievous creation of 85set-user-id and set-group-id programs. 86.Pp 87.Fn lchown 88is like 89.Fn chown 90except in the case where the named file is a symbolic link, 91in which case 92.Fn lchown 93changes the owner and group of the link, 94while 95.Fn chown 96changes the owner and group of the file the link references. 97.Pp 98.Fn fchown 99is particularly useful when used in conjunction 100with the file locking primitives (see 101.Xr flock 2 ) . 102.Pp 103One of the owner or group id's 104may be left unchanged by specifying it as (uid_t)\-1 or (gid_t)\-1 respectively. 105.Sh RETURN VALUES 106Zero is returned if the operation was successful; 107\-1 is returned if an error occurs, with a more specific 108error code being placed in the global variable 109.Va errno . 110.Sh ERRORS 111.Fn chown 112and 113.Fn lchown 114will fail and the file will be unchanged if: 115.Bl -tag -width Er 116.It Bq Er ENOTDIR 117A component of the path prefix is not a directory. 118.It Bq Er ENAMETOOLONG 119A component of a pathname exceeded 120.Brq Dv NAME_MAX 121characters, or an entire path name exceeded 122.Brq Dv PATH_MAX 123characters. 124.It Bq Er ENOENT 125The named file does not exist. 126.It Bq Er EACCES 127Search permission is denied for a component of the path prefix. 128.It Bq Er ELOOP 129Too many symbolic links were encountered in translating the pathname. 130.It Bq Er EPERM 131The effective user ID is not the super-user. 132.It Bq Er EROFS 133The named file resides on a read-only file system. 134.It Bq Er EFAULT 135.Fa path 136points outside the process's allocated address space. 137.It Bq Er EIO 138An I/O error occurred while reading from or writing to the file system. 139.El 140.Pp 141.Fn fchown 142will fail if: 143.Bl -tag -width Er 144.It Bq Er EBADF 145.Fa fd 146does not refer to a valid descriptor. 147.It Bq Er EINVAL 148.Fa fd 149refers to a socket, not a file. 150.It Bq Er EPERM 151The effective user ID is not the super-user. 152.It Bq Er EROFS 153The named file resides on a read-only file system. 154.It Bq Er EIO 155An I/O error occurred while reading from or writing to the file system. 156.El 157.Sh SEE ALSO 158.Xr chgrp 1 , 159.Xr chmod 2 , 160.Xr flock 2 , 161.Xr symlink 7 , 162.Xr chown 8 163.Sh STANDARDS 164The 165.Fn chown 166function deviates from the semantics defined in 167.St -p1003.1-90 , 168which specifies that, unless the caller is the super-user, both the 169set-user-id and set-group-id bits on a file shall be cleared, regardless 170of the file attribute changed. 171The 172.Fn lchown 173and 174.Fn fchown 175functions, as defined by 176.St -xpg4.2 , 177provide the same semantics. 178.Pp 179To retain conformance to these standards, compatibility interfaces 180are provided by the 181.Lb libposix 182as follows: 183.Bl -bullet -compact 184.It 185The 186.Fn chown 187function conforms to 188.St -p1003.1-90 189and 190.St -xpg4.2 . 191.It 192The 193.Fn lchown 194and 195.Fn fchown 196functions conform to 197.St -xpg4.2 . 198.El 199.Sh HISTORY 200The 201.Fn fchown 202function call appeared in 203.Bx 4.2 . 204.Pp 205The 206.Fn chown 207and 208.Fn fchown 209functions were changed to follow symbolic links in 210.Bx 4.4 . 211The 212.Fn lchown 213function call appeared in 214.Nx 1.3 . 215