1.\" $NetBSD: chown.2,v 1.26 2002/04/29 01:41:45 simonb 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)chown.2 8.4 (Berkeley) 4/19/94 35.\" 36.Dd April 19, 1994 37.Dt CHOWN 2 38.Os 39.Sh NAME 40.Nm chown , 41.Nm lchown , 42.Nm fchown 43.Nd change owner and group of a file 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.Fd #include \*[Lt]unistd.h\*[Gt] 48.Ft int 49.Fn chown "const char *path" "uid_t owner" "gid_t group" 50.Ft int 51.Fn lchown "const char *path" "uid_t owner" "gid_t group" 52.Ft int 53.Fn fchown "int fd" "uid_t owner" "gid_t group" 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 107One of the owner or group id's 108may be left unchanged by specifying it as (uid_t)-1 or (gid_t)-1 respectively. 109.Sh RETURN VALUES 110Zero is returned if the operation was successful; 111-1 is returned if an error occurs, with a more specific 112error code being placed in the global variable 113.Va errno . 114.Sh ERRORS 115.Fn chown 116and 117.Fn lchown 118will fail and the file will be unchanged if: 119.Bl -tag -width Er 120.It Bq Er ENOTDIR 121A component of the path prefix is not a directory. 122.It Bq Er ENAMETOOLONG 123A component of a pathname exceeded 124.Dv {NAME_MAX} 125characters, or an entire path name exceeded 126.Dv {PATH_MAX} 127characters. 128.It Bq Er ENOENT 129The named file does not exist. 130.It Bq Er EACCES 131Search permission is denied for a component of the path prefix. 132.It Bq Er ELOOP 133Too many symbolic links were encountered in translating the pathname. 134.It Bq Er EPERM 135The effective user ID is not the super-user. 136.It Bq Er EROFS 137The named file resides on a read-only file system. 138.It Bq Er EFAULT 139.Fa path 140points outside the process's allocated address space. 141.It Bq Er EIO 142An I/O error occurred while reading from or writing to the file system. 143.El 144.Pp 145.Fn fchown 146will fail if: 147.Bl -tag -width Er 148.It Bq Er EBADF 149.Fa fd 150does not refer to a valid descriptor. 151.It Bq Er EINVAL 152.Fa fd 153refers to a socket, not a file. 154.It Bq Er EPERM 155The effective user ID is not the super-user. 156.It Bq Er EROFS 157The named file resides on a read-only file system. 158.It Bq Er EIO 159An I/O error occurred while reading from or writing to the file system. 160.El 161.Sh SEE ALSO 162.Xr chgrp 1 , 163.Xr chmod 2 , 164.Xr flock 2 , 165.Xr symlink 7 , 166.Xr chown 8 167.Sh STANDARDS 168The 169.Fn chown 170function deviates from the semantics defined in 171.St -p1003.1-90 , 172which specifies that, unless the caller is the super-user, both the 173set-user-id and set-group-id bits on a file shall be cleared, regardless 174of the file attribute changed. 175The 176.Fn lchown 177and 178.Fn fchown 179functions, as defined by 180.St -xpg4.2 , 181provide the same semantics. 182.Pp 183To retain conformance to these standards, compatibility interfaces 184are provided by the 185.Lb libposix 186as follows: 187.Bl -bullet -compact 188.It 189The 190.Fn chown 191function conforms to 192.St -p1003.1-90 193and 194.St -xpg4.2 . 195.It 196The 197.Fn lchown 198and 199.Fn fchown 200functions conform to 201.St -xpg4.2 . 202.El 203.Sh HISTORY 204The 205.Fn fchown 206function call appeared in 207.Bx 4.2 . 208.Pp 209The 210.Fn chown 211and 212.Fn fchown 213functions were changed to follow symbolic links in 214.Bx 4.4 . 215The 216.Fn lchown 217function call appeared in 218.Nx 1.3 . 219