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