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