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.\" 30.Dd March 30, 2021 31.Dt CHOWN 2 32.Os 33.Sh NAME 34.Nm chown , 35.Nm fchown , 36.Nm lchown , 37.Nm fchownat 38.Nd change owner and group of a file 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft int 44.Fn chown "const char *path" "uid_t owner" "gid_t group" 45.Ft int 46.Fn fchown "int fd" "uid_t owner" "gid_t group" 47.Ft int 48.Fn lchown "const char *path" "uid_t owner" "gid_t group" 49.Ft int 50.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" 51.Sh DESCRIPTION 52The owner ID and group ID of the file 53named by 54.Fa path 55or referenced by 56.Fa fd 57is changed as specified by the arguments 58.Fa owner 59and 60.Fa group . 61The owner of a file may change the 62.Fa group 63to a group of which 64he or she is a member, 65but the change 66.Fa owner 67capability is restricted to the super-user. 68.Pp 69The 70.Fn chown 71system call 72clears the set-user-id and set-group-id bits 73on the file 74to prevent accidental or mischievous creation of 75set-user-id and set-group-id programs if not executed 76by the super-user. 77The 78.Fn chown 79system call 80follows symbolic links to operate on the target of the link 81rather than the link itself. 82.Pp 83The 84.Fn fchown 85system call 86is particularly useful when used in conjunction 87with the file locking primitives (see 88.Xr flock 2 ) . 89.Pp 90The 91.Fn lchown 92system call is similar to 93.Fn chown 94but does not follow symbolic links. 95.Pp 96The 97.Fn fchownat 98system call is equivalent to the 99.Fn chown 100and 101.Fn lchown 102except in the case where 103.Fa path 104specifies a relative path. 105In this case the file to be changed is determined relative to the directory 106associated with the file descriptor 107.Fa fd 108instead of the current working directory. 109.Pp 110Values for 111.Fa flag 112are constructed by a bitwise-inclusive OR of flags from the following 113list, defined in 114.In fcntl.h : 115.Bl -tag -width indent 116.It Dv AT_SYMLINK_NOFOLLOW 117If 118.Fa path 119names a symbolic link, ownership of the symbolic link is changed. 120.It Dv AT_RESOLVE_BENEATH 121Only walk paths below the directory specified by the 122.Ar fd 123descriptor. 124See the description of the 125.Dv O_RESOLVE_BENEATH 126flag in the 127.Xr open 2 128manual page. 129.It Dv AT_EMPTY_PATH 130If the 131.Fa path 132argument is an empty string, operate on the file or directory 133referenced by the descriptor 134.Fa fd . 135If 136.Fa fd 137is equal to 138.Dv AT_FDCWD , 139operate on the current working directory. 140.El 141.Pp 142If 143.Fn fchownat 144is passed the special value 145.Dv AT_FDCWD 146in the 147.Fa fd 148parameter, the current working directory is used and the behavior is identical 149to a call to 150.Fn chown 151or 152.Fn lchown 153respectively, depending on whether or not the 154.Dv AT_SYMLINK_NOFOLLOW 155bit is set in the 156.Fa flag 157argument. 158.Pp 159One of the owner or group id's 160may be left unchanged by specifying it as -1. 161.Sh RETURN VALUES 162.Rv -std 163.Sh ERRORS 164The 165.Fn chown 166and 167.Fn lchown 168will fail and the file will be unchanged if: 169.Bl -tag -width Er 170.It Bq Er ENOTDIR 171A component of the path prefix is not a directory. 172.It Bq Er ENAMETOOLONG 173A component of a pathname exceeded 255 characters, 174or an entire path name exceeded 1023 characters. 175.It Bq Er ENOENT 176The named file does not exist. 177.It Bq Er EACCES 178Search permission is denied for a component of the path prefix. 179.It Bq Er ELOOP 180Too many symbolic links were encountered in translating the pathname. 181.It Bq Er EPERM 182The operation would change the ownership, but the effective user ID is not the 183super-user. 184.It Bq Er EPERM 185The named file has its immutable or append-only flag set, see the 186.Xr chflags 2 187manual page for more information. 188.It Bq Er EROFS 189The named file resides on a read-only file system. 190.It Bq Er EFAULT 191The 192.Fa path 193argument 194points outside the process's allocated address space. 195.It Bq Er EIO 196An I/O error occurred while reading from or writing to the file system. 197.It Bq Er EINTEGRITY 198Corrupted data was detected while reading from the file system. 199.El 200.Pp 201The 202.Fn fchown 203system call will fail if: 204.Bl -tag -width Er 205.It Bq Er EBADF 206The 207.Fa fd 208argument 209does not refer to a valid descriptor. 210.It Bq Er EINVAL 211The 212.Fa fd 213argument 214refers to a socket, not a file. 215.It Bq Er EPERM 216The effective user ID is not the super-user. 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.It Bq Er EINTEGRITY 222Corrupted data was detected while reading from the file system. 223.El 224.Pp 225In addition to the errors specified for 226.Fn chown 227and 228.Fn lchown , 229the 230.Fn fchownat 231system call may fail if: 232.Bl -tag -width Er 233.It Bq Er EBADF 234The 235.Fa path 236argument does not specify an absolute path and the 237.Fa fd 238argument is neither 239.Dv AT_FDCWD 240nor a valid file descriptor open for searching. 241.It Bq Er EINVAL 242The value of the 243.Fa flag 244argument is not valid. 245.It Bq Er ENOTDIR 246The 247.Fa path 248argument is not an absolute path and 249.Fa fd 250is neither 251.Dv AT_FDCWD 252nor a file descriptor associated with a directory. 253.It Bq Er ENOTCAPABLE 254.Fa path 255is an absolute path, 256or contained a ".." component leading to a 257directory outside of the directory hierarchy specified by 258.Fa fd , 259and the process is in capability mode or the 260.Dv AT_RESOLVE_BENEATH 261flag was specified. 262.El 263.Sh SEE ALSO 264.Xr chgrp 1 , 265.Xr chflags 2 , 266.Xr chmod 2 , 267.Xr flock 2 , 268.Xr chown 8 269.Sh STANDARDS 270The 271.Fn chown 272system call is expected to conform to 273.St -p1003.1-90 . 274The 275.Fn fchownat 276system call follows The Open Group Extended API Set 2 specification. 277.Sh HISTORY 278The 279.Fn chown 280function appeared in 281.At v1 . 282The 283.Fn fchown 284system call appeared in 285.Bx 4.2 . 286.Pp 287The 288.Fn chown 289system call was changed to follow symbolic links in 290.Bx 4.4 . 291The 292.Fn lchown 293system call was added in 294.Fx 3.0 295to compensate for the loss of functionality. 296.Pp 297The 298.Fn fchownat 299system call appeared in 300.Fx 8.0 . 301