1.\" $OpenBSD: chown.2,v 1.26 2015/09/10 17:55:21 schwarze 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: September 10 2015 $ 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.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.In fcntl.h 51.In 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 139.Rv -std 140.Sh ERRORS 141.Fn chown , 142.Fn lchown , 143and 144.Fn fchownat 145will fail and the file or link will be unchanged if: 146.Bl -tag -width Er 147.It Bq Er ENOTDIR 148A component of the path prefix is not a directory. 149.It Bq Er ENAMETOOLONG 150A component of a pathname exceeded 151.Dv NAME_MAX 152characters, or an entire pathname (including the terminating NUL) 153exceeded 154.Dv PATH_MAX 155bytes. 156.It Bq Er ENOENT 157The named file does not exist. 158.It Bq Er EACCES 159Search permission is denied for a component of the path prefix. 160.It Bq Er ELOOP 161Too many symbolic links were encountered in translating the pathname. 162.It Bq Er EPERM 163The effective user ID is not the superuser. 164.It Bq Er EROFS 165The named file resides on a read-only file system. 166.It Bq Er EFAULT 167.Fa path 168points outside the process's allocated address space. 169.It Bq Er EIO 170An I/O error occurred while reading from or writing to the file system. 171.El 172.Pp 173Additionally, 174.Fn fchownat 175will fail if: 176.Bl -tag -width Er 177.It Bq Er EINVAL 178The value of the 179.Fa flag 180argument was neither zero nor 181.Dv AT_SYMLINK_NOFOLLOW . 182.It Bq Er EBADF 183The 184.Fa path 185argument specifies a relative path and the 186.Fa fd 187argument is neither 188.Dv AT_FDCWD 189nor a valid file descriptor. 190.It Bq Er ENOTDIR 191The 192.Fa path 193argument specifies a relative path and the 194.Fa fd 195argument is a valid file descriptor but it does not reference a directory. 196.It Bq Er EACCES 197The 198.Fa path 199argument specifies a relative path but search permission is denied 200for the directory which the 201.Fa fd 202file descriptor references. 203.El 204.Pp 205.Fn fchown 206will fail if: 207.Bl -tag -width Er 208.It Bq Er EBADF 209.Fa fd 210does not refer to a valid descriptor. 211.It Bq Er EINVAL 212.Fa fd 213refers to a socket, not a file. 214.It Bq Er EPERM 215The effective user ID is not the superuser. 216.It Bq Er EROFS 217The named file resides on a read-only file system. 218.It Bq Er EIO 219An I/O error occurred while reading from or writing to the file system. 220.El 221.Sh SEE ALSO 222.Xr chgrp 1 , 223.Xr chmod 2 , 224.Xr flock 2 , 225.Xr chown 8 226.Sh STANDARDS 227The 228.Fn chown , 229.Fn fchown , 230.Fn fchownat , 231and 232.Fn lchown 233functions are expected to conform to 234.St -p1003.1-2008 . 235.Sh HISTORY 236The 237.Fn chown 238system call first appeared in 239.At v1 . 240Since 241.At v6 242it supports changing the group as well, 243and in 244.At v7 245.Fa group 246was made a separate argument. 247.Pp 248The 249.Fn fchown 250system call first appeared in 251.Bx 4.1c . 252.Pp 253The 254.Fn chown 255and 256.Fn fchown 257system calls were changed to follow symbolic links in 258.Bx 4.4 ; 259therefore, and for compatibility with 260.At V.4 , 261the 262.Fn lchown 263system call was added to 264.Ox 2.1 . 265.Pp 266The 267.Fn fchownat 268system call has been available since 269.Ox 5.0 . 270