1.\" $OpenBSD: chown.2,v 1.27 2022/02/18 23:17:14 jsg 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 18 2022 $ 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 its 64.Fa group 65to one the owner is a member of. 66The change 67.Fa owner 68capability is restricted to the superuser. 69.Pp 70By default, 71.Fn chown 72clears the set-user-ID and set-group-ID bits on the file 73to prevent accidental or mischievous creation of 74set-user-ID and set-group-ID programs. 75This behaviour can be overridden by setting the 76.Xr sysctl 8 77variable 78.Va fs.posix.setuid 79to zero. 80.Pp 81.Fn lchown 82operates similarly to how 83.Fn chown 84operated on older systems, and does not follow symbolic links. 85It allows the owner and group of a symbolic link to be set. 86.Pp 87The 88.Fn fchownat 89function is equivalent to either the 90.Fn chown 91or 92.Fn lchown 93function depending on the value of 94.Fa flag 95(see below), except that where 96.Fa path 97specifies a relative path, 98the file whose ownership is changed is determined relative to 99the directory associated with file descriptor 100.Fa fd 101instead of the current working directory. 102.Pp 103If 104.Fn fchownat 105is passed the special value 106.Dv AT_FDCWD 107(defined in 108.In fcntl.h ) 109in the 110.Fa fd 111parameter, the current working directory is used 112and the behavior is identical to a call to 113.Fn chown 114or 115.Fn lchown , 116depending on whether or not the 117.Dv AT_SYMLINK_NOFOLLOW 118bit is set in 119.Fa flag . 120.Pp 121The 122.Fa flag 123argument is the bitwise OR of zero or more of the following values: 124.Pp 125.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact 126.It Dv AT_SYMLINK_NOFOLLOW 127If 128.Fa path 129names a symbolic link, then the ownership of the symbolic link is changed. 130.El 131.Pp 132.Fn fchown 133is particularly useful when used in conjunction 134with the file locking primitives (see 135.Xr flock 2 ) . 136.Pp 137One of the owner or group IDs 138may be left unchanged by specifying it as \-1. 139.Sh RETURN VALUES 140.Rv -std 141.Sh ERRORS 142.Fn chown , 143.Fn lchown , 144and 145.Fn fchownat 146will fail and the file or link will be unchanged if: 147.Bl -tag -width Er 148.It Bq Er ENOTDIR 149A component of the path prefix is not a directory. 150.It Bq Er ENAMETOOLONG 151A component of a pathname exceeded 152.Dv NAME_MAX 153characters, or an entire pathname (including the terminating NUL) 154exceeded 155.Dv PATH_MAX 156bytes. 157.It Bq Er ENOENT 158The named file does not exist. 159.It Bq Er EACCES 160Search permission is denied for a component of the path prefix. 161.It Bq Er ELOOP 162Too many symbolic links were encountered in translating the pathname. 163.It Bq Er EPERM 164The effective user ID is not the superuser. 165.It Bq Er EROFS 166The named file resides on a read-only file system. 167.It Bq Er EFAULT 168.Fa path 169points outside the process's allocated address space. 170.It Bq Er EIO 171An I/O error occurred while reading from or writing to the file system. 172.El 173.Pp 174Additionally, 175.Fn fchownat 176will fail if: 177.Bl -tag -width Er 178.It Bq Er EINVAL 179The value of the 180.Fa flag 181argument was neither zero nor 182.Dv AT_SYMLINK_NOFOLLOW . 183.It Bq Er EBADF 184The 185.Fa path 186argument specifies a relative path and the 187.Fa fd 188argument is neither 189.Dv AT_FDCWD 190nor a valid file descriptor. 191.It Bq Er ENOTDIR 192The 193.Fa path 194argument specifies a relative path and the 195.Fa fd 196argument is a valid file descriptor but it does not reference a directory. 197.It Bq Er EACCES 198The 199.Fa path 200argument specifies a relative path but search permission is denied 201for the directory which the 202.Fa fd 203file descriptor references. 204.El 205.Pp 206.Fn fchown 207will fail if: 208.Bl -tag -width Er 209.It Bq Er EBADF 210.Fa fd 211does not refer to a valid descriptor. 212.It Bq Er EINVAL 213.Fa fd 214refers to a socket, not a file. 215.It Bq Er EPERM 216The effective user ID is not the superuser. 217.It Bq Er EROFS 218The named file resides on a read-only file system. 219.It Bq Er EIO 220An I/O error occurred while reading from or writing to the file system. 221.El 222.Sh SEE ALSO 223.Xr chgrp 1 , 224.Xr chmod 2 , 225.Xr flock 2 , 226.Xr chown 8 227.Sh STANDARDS 228The 229.Fn chown , 230.Fn fchown , 231.Fn fchownat , 232and 233.Fn lchown 234functions are expected to conform to 235.St -p1003.1-2008 . 236.Sh HISTORY 237The 238.Fn chown 239system call first appeared in 240.At v1 . 241Since 242.At v6 243it supports changing the group as well, 244and in 245.At v7 246.Fa group 247was made a separate argument. 248.Pp 249The 250.Fn fchown 251system call first appeared in 252.Bx 4.1c . 253.Pp 254The 255.Fn chown 256and 257.Fn fchown 258system calls were changed to follow symbolic links in 259.Bx 4.4 ; 260therefore, and for compatibility with 261.At V.4 , 262the 263.Fn lchown 264system call was added to 265.Ox 2.1 . 266.Pp 267The 268.Fn fchownat 269system call has been available since 270.Ox 5.0 . 271