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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)chown.2 8.4 (Berkeley) 4/19/94 29.\" $FreeBSD$ 30.\" 31.Dd September 23, 2020 32.Dt CHOWN 2 33.Os 34.Sh NAME 35.Nm chown , 36.Nm fchown , 37.Nm lchown , 38.Nm fchownat 39.Nd change owner and group of a file 40.Sh LIBRARY 41.Lb libc 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 fchown "int fd" "uid_t owner" "gid_t group" 48.Ft int 49.Fn lchown "const char *path" "uid_t owner" "gid_t group" 50.Ft int 51.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" 52.Sh DESCRIPTION 53The owner ID and group ID of the file 54named by 55.Fa path 56or referenced by 57.Fa fd 58is changed as specified by the arguments 59.Fa owner 60and 61.Fa group . 62The owner of a file may change the 63.Fa group 64to a group of which 65he or she is a member, 66but the change 67.Fa owner 68capability is restricted to the super-user. 69.Pp 70The 71.Fn chown 72system call 73clears the set-user-id and set-group-id bits 74on the file 75to prevent accidental or mischievous creation of 76set-user-id and set-group-id programs if not executed 77by the super-user. 78The 79.Fn chown 80system call 81follows symbolic links to operate on the target of the link 82rather than the link itself. 83.Pp 84The 85.Fn fchown 86system call 87is particularly useful when used in conjunction 88with the file locking primitives (see 89.Xr flock 2 ) . 90.Pp 91The 92.Fn lchown 93system call is similar to 94.Fn chown 95but does not follow symbolic links. 96.Pp 97The 98.Fn fchownat 99system call is equivalent to the 100.Fn chown 101and 102.Fn lchown 103except in the case where 104.Fa path 105specifies a relative path. 106In this case the file to be changed is determined relative to the directory 107associated with the file descriptor 108.Fa fd 109instead of the current working directory. 110.Pp 111Values for 112.Fa flag 113are constructed by a bitwise-inclusive OR of flags from the following 114list, defined in 115.In fcntl.h : 116.Bl -tag -width indent 117.It Dv AT_SYMLINK_NOFOLLOW 118If 119.Fa path 120names a symbolic link, ownership of the symbolic link is changed. 121.It Dv AT_BENEATH 122Only allow to change ownership of a file which is beneath of 123the topping directory. 124See the description of the 125.Dv O_BENEATH 126flag in the 127.Xr open 2 128manual page. 129.It Dv AT_RESOLVE_BENEATH 130Only walks paths below the topping directory. 131See the description of the 132.Dv O_RESOLVE_BENEATH 133flag in the 134.Xr open 2 135manual page. 136.El 137.Pp 138If 139.Fn fchownat 140is passed the special value 141.Dv AT_FDCWD 142in the 143.Fa fd 144parameter, the current working directory is used and the behavior is identical 145to a call to 146.Fn chown 147or 148.Fn lchown 149respectively, depending on whether or not the 150.Dv AT_SYMLINK_NOFOLLOW 151bit is set in the 152.Fa flag 153argument. 154.Pp 155One of the owner or group id's 156may be left unchanged by specifying it as -1. 157.Sh RETURN VALUES 158.Rv -std 159.Sh ERRORS 160The 161.Fn chown 162and 163.Fn lchown 164will fail and the file will be unchanged if: 165.Bl -tag -width Er 166.It Bq Er ENOTDIR 167A component of the path prefix is not a directory. 168.It Bq Er ENAMETOOLONG 169A component of a pathname exceeded 255 characters, 170or an entire path name exceeded 1023 characters. 171.It Bq Er ENOENT 172The named file does not exist. 173.It Bq Er EACCES 174Search permission is denied for a component of the path prefix. 175.It Bq Er ELOOP 176Too many symbolic links were encountered in translating the pathname. 177.It Bq Er EPERM 178The operation would change the ownership, but the effective user ID is not the 179super-user. 180.It Bq Er EPERM 181The named file has its immutable or append-only flag set, see the 182.Xr chflags 2 183manual page for more information. 184.It Bq Er EROFS 185The named file resides on a read-only file system. 186.It Bq Er EFAULT 187The 188.Fa path 189argument 190points outside the process's allocated address space. 191.It Bq Er EIO 192An I/O error occurred while reading from or writing to the file system. 193.It Bq Er EINTEGRITY 194Corrupted data was detected while reading from the file system. 195.El 196.Pp 197The 198.Fn fchown 199system call will fail if: 200.Bl -tag -width Er 201.It Bq Er EBADF 202The 203.Fa fd 204argument 205does not refer to a valid descriptor. 206.It Bq Er EINVAL 207The 208.Fa fd 209argument 210refers to a socket, not a file. 211.It Bq Er EPERM 212The effective user ID is not the super-user. 213.It Bq Er EROFS 214The named file resides on a read-only file system. 215.It Bq Er EIO 216An I/O error occurred while reading from or writing to the file system. 217.It Bq Er EINTEGRITY 218Corrupted data was detected while reading from the file system. 219.El 220.Pp 221In addition to the errors specified for 222.Fn chown 223and 224.Fn lchown , 225the 226.Fn fchownat 227system call may fail if: 228.Bl -tag -width Er 229.It Bq Er EBADF 230The 231.Fa path 232argument does not specify an absolute path and the 233.Fa fd 234argument is neither 235.Dv AT_FDCWD 236nor a valid file descriptor open for searching. 237.It Bq Er EINVAL 238The value of the 239.Fa flag 240argument is not valid. 241.It Bq Er ENOTDIR 242The 243.Fa path 244argument is not an absolute path and 245.Fa fd 246is neither 247.Dv AT_FDCWD 248nor a file descriptor associated with a directory. 249.It Bq Er ENOTCAPABLE 250.Fa path 251is an absolute path, 252or contained a ".." component leading to a 253directory outside of the directory hierarchy specified by 254.Fa fd , 255and the process is in capability mode. 256.It Bq Er ENOTCAPABLE 257The 258.Dv AT_BENEATH 259flag was provided to 260.Fn fchownat , 261and the absolute 262.Fa path 263does not have its tail fully contained under the topping directory, 264or the relative 265.Fa path 266escapes it. 267.El 268.Sh SEE ALSO 269.Xr chgrp 1 , 270.Xr chflags 2 , 271.Xr chmod 2 , 272.Xr flock 2 , 273.Xr chown 8 274.Sh STANDARDS 275The 276.Fn chown 277system call is expected to conform to 278.St -p1003.1-90 . 279The 280.Fn fchownat 281system call follows The Open Group Extended API Set 2 specification. 282.Sh HISTORY 283The 284.Fn chown 285function appeared in 286.At v1 . 287The 288.Fn fchown 289system call appeared in 290.Bx 4.2 . 291.Pp 292The 293.Fn chown 294system call was changed to follow symbolic links in 295.Bx 4.4 . 296The 297.Fn lchown 298system call was added in 299.Fx 3.0 300to compensate for the loss of functionality. 301.Pp 302The 303.Fn fchownat 304system call appeared in 305.Fx 8.0 . 306