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