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 February 23, 2021 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_RESOLVE_BENEATH 122Only walk paths below the directory specified by the 123.Ar fd 124descriptor. 125See the description of the 126.Dv O_RESOLVE_BENEATH 127flag in the 128.Xr open 2 129manual page. 130.El 131.Pp 132If 133.Fn fchownat 134is passed the special value 135.Dv AT_FDCWD 136in the 137.Fa fd 138parameter, the current working directory is used and the behavior is identical 139to a call to 140.Fn chown 141or 142.Fn lchown 143respectively, depending on whether or not the 144.Dv AT_SYMLINK_NOFOLLOW 145bit is set in the 146.Fa flag 147argument. 148.Pp 149One of the owner or group id's 150may be left unchanged by specifying it as -1. 151.Sh RETURN VALUES 152.Rv -std 153.Sh ERRORS 154The 155.Fn chown 156and 157.Fn lchown 158will fail and the file will be unchanged if: 159.Bl -tag -width Er 160.It Bq Er ENOTDIR 161A component of the path prefix is not a directory. 162.It Bq Er ENAMETOOLONG 163A component of a pathname exceeded 255 characters, 164or an entire path name exceeded 1023 characters. 165.It Bq Er ENOENT 166The named file does not exist. 167.It Bq Er EACCES 168Search permission is denied for a component of the path prefix. 169.It Bq Er ELOOP 170Too many symbolic links were encountered in translating the pathname. 171.It Bq Er EPERM 172The operation would change the ownership, but the effective user ID is not the 173super-user. 174.It Bq Er EPERM 175The named file has its immutable or append-only flag set, see the 176.Xr chflags 2 177manual page for more information. 178.It Bq Er EROFS 179The named file resides on a read-only file system. 180.It Bq Er EFAULT 181The 182.Fa path 183argument 184points outside the process's allocated address space. 185.It Bq Er EIO 186An I/O error occurred while reading from or writing to the file system. 187.It Bq Er EINTEGRITY 188Corrupted data was detected while reading from the file system. 189.El 190.Pp 191The 192.Fn fchown 193system call will fail if: 194.Bl -tag -width Er 195.It Bq Er EBADF 196The 197.Fa fd 198argument 199does not refer to a valid descriptor. 200.It Bq Er EINVAL 201The 202.Fa fd 203argument 204refers to a socket, not a file. 205.It Bq Er EPERM 206The effective user ID is not the super-user. 207.It Bq Er EROFS 208The named file resides on a read-only file system. 209.It Bq Er EIO 210An I/O error occurred while reading from or writing to the file system. 211.It Bq Er EINTEGRITY 212Corrupted data was detected while reading from the file system. 213.El 214.Pp 215In addition to the errors specified for 216.Fn chown 217and 218.Fn lchown , 219the 220.Fn fchownat 221system call may fail if: 222.Bl -tag -width Er 223.It Bq Er EBADF 224The 225.Fa path 226argument does not specify an absolute path and the 227.Fa fd 228argument is neither 229.Dv AT_FDCWD 230nor a valid file descriptor open for searching. 231.It Bq Er EINVAL 232The value of the 233.Fa flag 234argument is not valid. 235.It Bq Er ENOTDIR 236The 237.Fa path 238argument is not an absolute path and 239.Fa fd 240is neither 241.Dv AT_FDCWD 242nor a file descriptor associated with a directory. 243.It Bq Er ENOTCAPABLE 244.Fa path 245is an absolute path, 246or contained a ".." component leading to a 247directory outside of the directory hierarchy specified by 248.Fa fd , 249and the process is in capability mode or the 250.Dv AT_RESOLVE_BENEATH 251flag was specified. 252.El 253.Sh SEE ALSO 254.Xr chgrp 1 , 255.Xr chflags 2 , 256.Xr chmod 2 , 257.Xr flock 2 , 258.Xr chown 8 259.Sh STANDARDS 260The 261.Fn chown 262system call is expected to conform to 263.St -p1003.1-90 . 264The 265.Fn fchownat 266system call follows The Open Group Extended API Set 2 specification. 267.Sh HISTORY 268The 269.Fn chown 270function appeared in 271.At v1 . 272The 273.Fn fchown 274system call appeared in 275.Bx 4.2 . 276.Pp 277The 278.Fn chown 279system call was changed to follow symbolic links in 280.Bx 4.4 . 281The 282.Fn lchown 283system call was added in 284.Fx 3.0 285to compensate for the loss of functionality. 286.Pp 287The 288.Fn fchownat 289system call appeared in 290.Fx 8.0 . 291