1.\" $OpenBSD: chown.2,v 1.23 2014/02/13 07:30:39 guenther Exp $ 2.\" $NetBSD: chown.2,v 1.10 1995/10/12 15:40:47 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993, 1994 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)chown.2 8.4 (Berkeley) 4/19/94 32.\" 33.Dd $Mdocdate: February 13 2014 $ 34.Dt CHOWN 2 35.Os 36.Sh NAME 37.Nm chown , 38.Nm lchown , 39.Nm fchownat , 40.Nm fchown 41.Nd change owner and group of a file or link 42.Sh SYNOPSIS 43.Fd #include <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.Fd #include <fcntl.h> 51.Fd #include <unistd.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 (or link) named by 56.Fa path 57or referenced by 58.Fa fd 59is changed as specified by the arguments 60.Fa owner 61and 62.Fa group . 63The owner of a file may change the 64.Fa group 65to a group of which he or she is a member, but the change 66.Fa owner 67capability is restricted to the superuser. 68.Pp 69By default, 70.Fn chown 71clears the set-user-ID and set-group-ID bits on the file 72to prevent accidental or mischievous creation of 73set-user-ID and set-group-ID programs. 74This behaviour can be overridden by setting the 75.Xr sysctl 8 76variable 77.Va fs.posix.setuid 78to zero. 79.Pp 80.Fn lchown 81operates similarly to how 82.Fn chown 83operated on older systems, and does not follow symbolic links. 84It allows the owner and group of a symbolic link to be set. 85.Pp 86The 87.Fn fchownat 88function is equivalent to either the 89.Fn chown 90or 91.Fn lchown 92function depending on the value of 93.Fa flag 94(see below), except that where 95.Fa path 96specifies a relative path, 97the file whose ownership is changed is determined relative to 98the directory associated with file descriptor 99.Fa fd 100instead of the current working directory. 101.Pp 102If 103.Fn fchownat 104is passed the special value 105.Dv AT_FDCWD 106(defined in 107.In fcntl.h ) 108in the 109.Fa fd 110parameter, the current working directory is used 111and the behavior is identical to a call to 112.Fn chown 113or 114.Fn lchown , 115depending on whether or not the 116.Dv AT_SYMLINK_NOFOLLOW 117bit is set in 118.Fa flag . 119.Pp 120The 121.Fa flag 122argument is the bitwise OR of zero or more of the following values: 123.Pp 124.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact 125.It Dv AT_SYMLINK_NOFOLLOW 126If 127.Fa path 128names a symbolic link, then the ownership of the symbolic link is changed. 129.El 130.Pp 131.Fn fchown 132is particularly useful when used in conjunction 133with the file locking primitives (see 134.Xr flock 2 ) . 135.Pp 136One of the owner or group IDs 137may be left unchanged by specifying it as \-1. 138.Sh RETURN VALUES 139Zero is returned if the operation was successful; 140\-1 is returned if an error occurs, with a more specific 141error code being placed in the global variable 142.Va errno . 143.Sh ERRORS 144.Fn chown , 145.Fn lchown , 146and 147.Fn fchownat 148will fail and the file or link will be unchanged if: 149.Bl -tag -width Er 150.It Bq Er ENOTDIR 151A component of the path prefix is not a directory. 152.It Bq Er ENAMETOOLONG 153A component of a pathname exceeded 154.Dv {NAME_MAX} 155characters, or an entire path name exceeded 156.Dv {PATH_MAX} 157characters. 158.It Bq Er ENOENT 159The named file does not exist. 160.It Bq Er EACCES 161Search permission is denied for a component of the path prefix. 162.It Bq Er ELOOP 163Too many symbolic links were encountered in translating the pathname. 164.It Bq Er EPERM 165The effective user ID is not the superuser. 166.It Bq Er EROFS 167The named file resides on a read-only file system. 168.It Bq Er EFAULT 169.Fa path 170points outside the process's allocated address space. 171.It Bq Er EIO 172An I/O error occurred while reading from or writing to the file system. 173.El 174.Pp 175Additionally, 176.Fn fchownat 177will fail if: 178.Bl -tag -width Er 179.It Bq Er EINVAL 180The value of the 181.Fa flag 182argument was neither zero nor 183.Dv AT_SYMLINK_NOFOLLOW . 184.It Bq Er EBADF 185The 186.Fa path 187argument specifies a relative path and the 188.Fa fd 189argument is neither 190.Dv AT_FDCWD 191nor a valid file descriptor. 192.It Bq Er ENOTDIR 193The 194.Fa path 195argument specifies a relative path and the 196.Fa fd 197argument is a valid file descriptor but it does not reference a directory. 198.It Bq Er EACCES 199The 200.Fa path 201argument specifies a relative path but search permission is denied 202for the directory which the 203.Fa fd 204file descriptor references. 205.El 206.Pp 207.Fn fchown 208will fail if: 209.Bl -tag -width Er 210.It Bq Er EBADF 211.Fa fd 212does not refer to a valid descriptor. 213.It Bq Er EINVAL 214.Fa fd 215refers to a socket, not a file. 216.It Bq Er EPERM 217The effective user ID is not the superuser. 218.It Bq Er EROFS 219The named file resides on a read-only file system. 220.It Bq Er EIO 221An I/O error occurred while reading from or writing to the file system. 222.El 223.Sh SEE ALSO 224.Xr chgrp 1 , 225.Xr chmod 2 , 226.Xr flock 2 , 227.Xr chown 8 228.Sh STANDARDS 229The 230.Fn chown , 231.Fn fchown , 232.Fn fchownat , 233and 234.Fn lchown 235functions are expected to conform to 236.St -p1003.1-2008 . 237.Sh HISTORY 238The 239.Fn chown 240system call first appeared in 241.At v1 . 242Since 243.At v6 244it supports changing the group as well, 245and in 246.At v7 247.Fa group 248was made a separate argument. 249.Pp 250The 251.Fn fchown 252system call first appeared in 253.Bx 4.1c . 254.Pp 255The 256.Fn chown 257and 258.Fn fchown 259system calls were changed to follow symbolic links in 260.Bx 4.4 ; 261therefore, and for compatibility with 262.At V.4 , 263the 264.Fn lchown 265system call was added to 266.Ox 2.1 . 267.Pp 268The 269.Fn fchownat 270system call has been available since 271.Ox 5.0 . 272