18269e767SBrooks Davis.\" Copyright (c) 1980, 1991, 1993, 1994 28269e767SBrooks Davis.\" The Regents of the University of California. All rights reserved. 38269e767SBrooks Davis.\" 48269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without 58269e767SBrooks Davis.\" modification, are permitted provided that the following conditions 68269e767SBrooks Davis.\" are met: 78269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright 88269e767SBrooks Davis.\" notice, this list of conditions and the following disclaimer. 98269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright 108269e767SBrooks Davis.\" notice, this list of conditions and the following disclaimer in the 118269e767SBrooks Davis.\" documentation and/or other materials provided with the distribution. 128269e767SBrooks Davis.\" 3. Neither the name of the University nor the names of its contributors 138269e767SBrooks Davis.\" may be used to endorse or promote products derived from this software 148269e767SBrooks Davis.\" without specific prior written permission. 158269e767SBrooks Davis.\" 168269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 178269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 188269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 198269e767SBrooks Davis.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 208269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 218269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 228269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 238269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 248269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 258269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 268269e767SBrooks Davis.\" SUCH DAMAGE. 278269e767SBrooks Davis.\" 288269e767SBrooks Davis.Dd March 30, 2021 298269e767SBrooks Davis.Dt CHOWN 2 308269e767SBrooks Davis.Os 318269e767SBrooks Davis.Sh NAME 328269e767SBrooks Davis.Nm chown , 338269e767SBrooks Davis.Nm fchown , 348269e767SBrooks Davis.Nm lchown , 358269e767SBrooks Davis.Nm fchownat 368269e767SBrooks Davis.Nd change owner and group of a file 378269e767SBrooks Davis.Sh LIBRARY 388269e767SBrooks Davis.Lb libc 398269e767SBrooks Davis.Sh SYNOPSIS 408269e767SBrooks Davis.In unistd.h 418269e767SBrooks Davis.Ft int 428269e767SBrooks Davis.Fn chown "const char *path" "uid_t owner" "gid_t group" 438269e767SBrooks Davis.Ft int 448269e767SBrooks Davis.Fn fchown "int fd" "uid_t owner" "gid_t group" 458269e767SBrooks Davis.Ft int 468269e767SBrooks Davis.Fn lchown "const char *path" "uid_t owner" "gid_t group" 478269e767SBrooks Davis.Ft int 488269e767SBrooks Davis.Fn fchownat "int fd" "const char *path" "uid_t owner" "gid_t group" "int flag" 498269e767SBrooks Davis.Sh DESCRIPTION 508269e767SBrooks DavisThe owner ID and group ID of the file 518269e767SBrooks Davisnamed by 528269e767SBrooks Davis.Fa path 538269e767SBrooks Davisor referenced by 548269e767SBrooks Davis.Fa fd 558269e767SBrooks Davisis changed as specified by the arguments 568269e767SBrooks Davis.Fa owner 578269e767SBrooks Davisand 588269e767SBrooks Davis.Fa group . 598269e767SBrooks DavisThe owner of a file may change the 608269e767SBrooks Davis.Fa group 618269e767SBrooks Davisto a group of which 628269e767SBrooks Davishe or she is a member, 638269e767SBrooks Davisbut the change 648269e767SBrooks Davis.Fa owner 658269e767SBrooks Daviscapability is restricted to the super-user. 668269e767SBrooks Davis.Pp 678269e767SBrooks DavisThe 688269e767SBrooks Davis.Fn chown 698269e767SBrooks Davissystem call 708269e767SBrooks Davisclears the set-user-id and set-group-id bits 718269e767SBrooks Davison the file 728269e767SBrooks Davisto prevent accidental or mischievous creation of 738269e767SBrooks Davisset-user-id and set-group-id programs if not executed 748269e767SBrooks Davisby the super-user. 758269e767SBrooks DavisThe 768269e767SBrooks Davis.Fn chown 778269e767SBrooks Davissystem call 788269e767SBrooks Davisfollows symbolic links to operate on the target of the link 798269e767SBrooks Davisrather than the link itself. 808269e767SBrooks Davis.Pp 818269e767SBrooks DavisThe 828269e767SBrooks Davis.Fn fchown 838269e767SBrooks Davissystem call 848269e767SBrooks Davisis particularly useful when used in conjunction 858269e767SBrooks Daviswith the file locking primitives (see 868269e767SBrooks Davis.Xr flock 2 ) . 878269e767SBrooks Davis.Pp 888269e767SBrooks DavisThe 898269e767SBrooks Davis.Fn lchown 908269e767SBrooks Davissystem call is similar to 918269e767SBrooks Davis.Fn chown 928269e767SBrooks Davisbut does not follow symbolic links. 938269e767SBrooks Davis.Pp 948269e767SBrooks DavisThe 958269e767SBrooks Davis.Fn fchownat 968269e767SBrooks Davissystem call is equivalent to the 978269e767SBrooks Davis.Fn chown 988269e767SBrooks Davisand 998269e767SBrooks Davis.Fn lchown 1008269e767SBrooks Davisexcept in the case where 1018269e767SBrooks Davis.Fa path 1028269e767SBrooks Davisspecifies a relative path. 1038269e767SBrooks DavisIn this case the file to be changed is determined relative to the directory 1048269e767SBrooks Davisassociated with the file descriptor 1058269e767SBrooks Davis.Fa fd 1068269e767SBrooks Davisinstead of the current working directory. 1078269e767SBrooks Davis.Pp 1088269e767SBrooks DavisValues for 1098269e767SBrooks Davis.Fa flag 1108269e767SBrooks Davisare constructed by a bitwise-inclusive OR of flags from the following 1118269e767SBrooks Davislist, defined in 1128269e767SBrooks Davis.In fcntl.h : 1138269e767SBrooks Davis.Bl -tag -width indent 1148269e767SBrooks Davis.It Dv AT_SYMLINK_NOFOLLOW 1158269e767SBrooks DavisIf 1168269e767SBrooks Davis.Fa path 1178269e767SBrooks Davisnames a symbolic link, ownership of the symbolic link is changed. 1188269e767SBrooks Davis.It Dv AT_RESOLVE_BENEATH 1198269e767SBrooks DavisOnly walk paths below the directory specified by the 1208269e767SBrooks Davis.Ar fd 1218269e767SBrooks Davisdescriptor. 1228269e767SBrooks DavisSee the description of the 1238269e767SBrooks Davis.Dv O_RESOLVE_BENEATH 1248269e767SBrooks Davisflag in the 1258269e767SBrooks Davis.Xr open 2 1268269e767SBrooks Davismanual page. 1278269e767SBrooks Davis.It Dv AT_EMPTY_PATH 1288269e767SBrooks DavisIf the 1298269e767SBrooks Davis.Fa path 1308269e767SBrooks Davisargument is an empty string, operate on the file or directory 1318269e767SBrooks Davisreferenced by the descriptor 1328269e767SBrooks Davis.Fa fd . 1338269e767SBrooks DavisIf 1348269e767SBrooks Davis.Fa fd 1358269e767SBrooks Davisis equal to 1368269e767SBrooks Davis.Dv AT_FDCWD , 1378269e767SBrooks Davisoperate on the current working directory. 1388269e767SBrooks Davis.El 1398269e767SBrooks Davis.Pp 1408269e767SBrooks DavisIf 1418269e767SBrooks Davis.Fn fchownat 1428269e767SBrooks Davisis passed the special value 1438269e767SBrooks Davis.Dv AT_FDCWD 1448269e767SBrooks Davisin the 1458269e767SBrooks Davis.Fa fd 1468269e767SBrooks Davisparameter, the current working directory is used and the behavior is identical 1478269e767SBrooks Davisto a call to 1488269e767SBrooks Davis.Fn chown 1498269e767SBrooks Davisor 1508269e767SBrooks Davis.Fn lchown 1518269e767SBrooks Davisrespectively, depending on whether or not the 1528269e767SBrooks Davis.Dv AT_SYMLINK_NOFOLLOW 1538269e767SBrooks Davisbit is set in the 1548269e767SBrooks Davis.Fa flag 1558269e767SBrooks Davisargument. 1568269e767SBrooks Davis.Pp 1578269e767SBrooks DavisOne of the owner or group id's 1588269e767SBrooks Davismay be left unchanged by specifying it as -1. 1598269e767SBrooks Davis.Sh RETURN VALUES 1608269e767SBrooks Davis.Rv -std 1618269e767SBrooks Davis.Sh ERRORS 1628269e767SBrooks DavisThe 1638269e767SBrooks Davis.Fn chown 1648269e767SBrooks Davisand 1658269e767SBrooks Davis.Fn lchown 1668269e767SBrooks Daviswill fail and the file will be unchanged if: 1678269e767SBrooks Davis.Bl -tag -width Er 1688269e767SBrooks Davis.It Bq Er ENOTDIR 1698269e767SBrooks DavisA component of the path prefix is not a directory. 1708269e767SBrooks Davis.It Bq Er ENAMETOOLONG 1718269e767SBrooks DavisA component of a pathname exceeded 255 characters, 1728269e767SBrooks Davisor an entire path name exceeded 1023 characters. 1738269e767SBrooks Davis.It Bq Er ENOENT 1748269e767SBrooks DavisThe named file does not exist. 1758269e767SBrooks Davis.It Bq Er EACCES 1768269e767SBrooks DavisSearch permission is denied for a component of the path prefix. 1778269e767SBrooks Davis.It Bq Er ELOOP 1788269e767SBrooks DavisToo many symbolic links were encountered in translating the pathname. 1798269e767SBrooks Davis.It Bq Er EPERM 1808269e767SBrooks DavisThe operation would change the ownership, but the effective user ID is not the 1818269e767SBrooks Davissuper-user. 1828269e767SBrooks Davis.It Bq Er EPERM 1838269e767SBrooks DavisThe named file has its immutable or append-only flag set, see the 1848269e767SBrooks Davis.Xr chflags 2 1858269e767SBrooks Davismanual page for more information. 1868269e767SBrooks Davis.It Bq Er EROFS 1878269e767SBrooks DavisThe named file resides on a read-only file system. 1888269e767SBrooks Davis.It Bq Er EFAULT 1898269e767SBrooks DavisThe 1908269e767SBrooks Davis.Fa path 1918269e767SBrooks Davisargument 1928269e767SBrooks Davispoints outside the process's allocated address space. 1938269e767SBrooks Davis.It Bq Er EIO 1948269e767SBrooks DavisAn I/O error occurred while reading from or writing to the file system. 1958269e767SBrooks Davis.It Bq Er EINTEGRITY 1968269e767SBrooks DavisCorrupted data was detected while reading from the file system. 1978269e767SBrooks Davis.El 1988269e767SBrooks Davis.Pp 1998269e767SBrooks DavisThe 2008269e767SBrooks Davis.Fn fchown 2018269e767SBrooks Davissystem call will fail if: 2028269e767SBrooks Davis.Bl -tag -width Er 2038269e767SBrooks Davis.It Bq Er EBADF 2048269e767SBrooks DavisThe 2058269e767SBrooks Davis.Fa fd 2068269e767SBrooks Davisargument 2078269e767SBrooks Davisdoes not refer to a valid descriptor. 2088269e767SBrooks Davis.It Bq Er EINVAL 2098269e767SBrooks DavisThe 2108269e767SBrooks Davis.Fa fd 2118269e767SBrooks Davisargument 2128269e767SBrooks Davisrefers to a socket, not a file. 2138269e767SBrooks Davis.It Bq Er EPERM 2148269e767SBrooks DavisThe effective user ID is not the super-user. 2158269e767SBrooks Davis.It Bq Er EROFS 2168269e767SBrooks DavisThe named file resides on a read-only file system. 2178269e767SBrooks Davis.It Bq Er EIO 2188269e767SBrooks DavisAn I/O error occurred while reading from or writing to the file system. 2198269e767SBrooks Davis.It Bq Er EINTEGRITY 2208269e767SBrooks DavisCorrupted data was detected while reading from the file system. 2218269e767SBrooks Davis.El 2228269e767SBrooks Davis.Pp 2238269e767SBrooks DavisIn addition to the errors specified for 2248269e767SBrooks Davis.Fn chown 2258269e767SBrooks Davisand 2268269e767SBrooks Davis.Fn lchown , 2278269e767SBrooks Davisthe 2288269e767SBrooks Davis.Fn fchownat 2298269e767SBrooks Davissystem call may fail if: 2308269e767SBrooks Davis.Bl -tag -width Er 2318269e767SBrooks Davis.It Bq Er EBADF 2328269e767SBrooks DavisThe 2338269e767SBrooks Davis.Fa path 2348269e767SBrooks Davisargument does not specify an absolute path and the 2358269e767SBrooks Davis.Fa fd 2368269e767SBrooks Davisargument is neither 2378269e767SBrooks Davis.Dv AT_FDCWD 2388269e767SBrooks Davisnor a valid file descriptor open for searching. 2398269e767SBrooks Davis.It Bq Er EINVAL 2408269e767SBrooks DavisThe value of the 2418269e767SBrooks Davis.Fa flag 2428269e767SBrooks Davisargument is not valid. 2438269e767SBrooks Davis.It Bq Er ENOTDIR 2448269e767SBrooks DavisThe 2458269e767SBrooks Davis.Fa path 2468269e767SBrooks Davisargument is not an absolute path and 2478269e767SBrooks Davis.Fa fd 2488269e767SBrooks Davisis neither 2498269e767SBrooks Davis.Dv AT_FDCWD 2508269e767SBrooks Davisnor a file descriptor associated with a directory. 2518269e767SBrooks Davis.It Bq Er ENOTCAPABLE 2528269e767SBrooks Davis.Fa path 2538269e767SBrooks Davisis an absolute path, 2548269e767SBrooks Davisor contained a ".." component leading to a 2558269e767SBrooks Davisdirectory outside of the directory hierarchy specified by 2568269e767SBrooks Davis.Fa fd , 2578269e767SBrooks Davisand the process is in capability mode or the 2588269e767SBrooks Davis.Dv AT_RESOLVE_BENEATH 2598269e767SBrooks Davisflag was specified. 2608269e767SBrooks Davis.El 2618269e767SBrooks Davis.Sh SEE ALSO 2628269e767SBrooks Davis.Xr chgrp 1 , 2638269e767SBrooks Davis.Xr chflags 2 , 2648269e767SBrooks Davis.Xr chmod 2 , 2658269e767SBrooks Davis.Xr flock 2 , 2668269e767SBrooks Davis.Xr chown 8 2678269e767SBrooks Davis.Sh STANDARDS 2688269e767SBrooks DavisThe 2698269e767SBrooks Davis.Fn chown 2708269e767SBrooks Davissystem call is expected to conform to 2718269e767SBrooks Davis.St -p1003.1-90 . 2728269e767SBrooks DavisThe 2738269e767SBrooks Davis.Fn fchownat 2748269e767SBrooks Davissystem call follows The Open Group Extended API Set 2 specification. 2758269e767SBrooks Davis.Sh HISTORY 2768269e767SBrooks DavisThe 2778269e767SBrooks Davis.Fn chown 2788269e767SBrooks Davisfunction appeared in 2798269e767SBrooks Davis.At v1 . 2808269e767SBrooks DavisThe 2818269e767SBrooks Davis.Fn fchown 2828269e767SBrooks Davissystem call appeared in 2838269e767SBrooks Davis.Bx 4.2 . 2848269e767SBrooks Davis.Pp 2858269e767SBrooks DavisThe 2868269e767SBrooks Davis.Fn chown 2878269e767SBrooks Davissystem call was changed to follow symbolic links in 2888269e767SBrooks Davis.Bx 4.4 . 2898269e767SBrooks DavisThe 2908269e767SBrooks Davis.Fn lchown 2918269e767SBrooks Davissystem call was added in 2928269e767SBrooks Davis.Fx 3.0 2938269e767SBrooks Davisto compensate for the loss of functionality. 2948269e767SBrooks Davis.Pp 2958269e767SBrooks DavisThe 2968269e767SBrooks Davis.Fn fchownat 2978269e767SBrooks Davissystem call appeared in 2988269e767SBrooks Davis.Fx 8.0 . 299