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