1'\" te 2.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved. 3.\" Copyright 1989 AT&T 4.\" Copyright 2021 Oxide Computer Company 5.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 7.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 8.Dd March 13, 2021 9.Dt CHOWN 2 10.Os 11.Sh NAME 12.Nm chown , 13.Nm lchown , 14.Nm fchown , 15.Nm fchownat 16.Nd change owner and group of a file 17.Sh SYNOPSIS 18.In unistd.h 19.In sys/types.h 20.Ft int 21.Fo chown 22.Fa "const char *path" 23.Fa "uid_t owner" 24.Fa "gid_t group" 25.Fc 26.Ft int 27.Fo lchown 28.Fa "const char *path" 29.Fa "uid_t owner" 30.Fa "gid_t group" 31.Fc 32.Ft int 33.Fo fchown 34.Fa "int fildes" 35.Fa "uid_t owner" 36.Fa "gid_t group" 37.Fc 38.Ft int 39.Fo fchownat 40.Fa "int fildes" 41.Fa "const char *path" 42.Fa "uid_t owner" 43.Fa "gid_t group" 44.Fa "int flag" 45.Fc 46.Sh DESCRIPTION 47The 48.Fn chown 49and 50.Fn fchown 51functions set the owner 52.Sy ID 53and group 54.Sy ID 55of the file specified by 56.Fa path 57or referenced by the open file descriptor 58.Fa fildes 59to 60.Fa owner 61and 62.Fa group 63respectively. 64If 65.Fa owner 66or 67.Fa group 68is specified as -1, 69.Fn chown 70and 71.Fn fchown 72do not change the corresponding 73.Sy ID 74of the file. 75.Pp 76The 77.Fn lchown 78function sets the owner 79.Sy ID 80and group 81.Sy ID 82of the named file in the same manner as 83.Fn chown , 84unless the named file is a symbolic link. 85In this case, 86.Fn lchown 87changes the ownership of the symbolic link file itself, while 88.Fn chown 89changes the ownership of the file or directory to which the symbolic link 90refers. 91.Pp 92The 93.Fn fchownat 94function sets the owner ID and group ID of the named file 95in the same manner as 96.Fn chown . 97If, however, the 98.Fa path 99argument is relative 100.Po 101does not start with a 102.Qq / 103.Pc , 104the path is resolved relative to the 105.Fa fildes 106argument rather than the current working directory. 107If the 108.Fa fildes 109argument has the special value 110.Dv AT_FDCWD , 111the path resolution reverts back to current working directory relative. 112If the 113.Fa flag 114argument is set to 115.Dv AT_SYMLINK_NOFOLLOW , 116the function behaves like 117.Fn lchown 118with respect to symbolic links. 119If the 120.Fa path 121argument is absolute, the 122.Fa fildes 123argument is ignored. 124If the 125.Fa path 126argument is a null pointer, the function behaves like 127.Fn fchown . 128.Pp 129If 130.Fn chown , 131.Fn lchown , 132.Fn fchown , 133or 134.Fn fchownat 135is invoked by a process that does not have 136.Brq Dv PRIV_FILE_SETID 137asserted in its effective set, the set-user-ID and set-group-ID bits of the 138file mode, 139.Dv S_ISUID 140and 141.Dv S_ISGID 142respectively, are cleared 143.Po 144see 145.Xr chmod 2 146.Pc . 147Additional restrictions apply when changing the ownership to uid 0. 148.Pp 149The operating system defines several privileges to override restrictions on the 150.Fn chown 151family of functions. 152When the 153.Brq Dv PRIV_FILE_CHOWN 154privilege is asserted in the effective set of the current process, there are no 155restrictions except in the special circumstances of changing ownership to or 156from uid 0. 157When the 158.Brq Dv PRIV_FILE_CHOWN_SELF 159privilege is asserted, ownership changes are restricted to the files of which 160the ownership matches the effective user ID of the current process. 161If neither privilege is asserted in the effective set of the calling process, 162ownership changes are limited to changes of the group of the file to the list of 163supplementary group IDs and the effective group ID. 164.Pp 165The operating system provides a configuration option, 166.Brq Dv _POSIX_CHOWN_RESTRICTED , 167to control the default behavior of processes and the behavior of the NFS server. 168If 169.Brq Dv B_POSIX_CHOWN_RESTRICTED 170is not in effect, the privilege 171.Brq PRIV_FILE_CHOWN_SELF 172is asserted in the inheritable set of all processes unless overridden by 173.Xr policy.conf 4 174or 175.Xr user_attr 4 . 176To set this configuration option, include the following 177line in 178.Pa /etc/system : 179.Bd -literal -offset indent 180set rstchown = 1 181.Ed 182.Pp 183To disable this option, include the following line in 184.Pa /etc/system : 185.Bd -literal -offset indent 186set rstchown = 0 187.Ed 188.Pp 189See 190.Xr system 4 191and 192.Xr fpathconf 2 . 193.Pp 194Upon successful completion, 195.Fn chown , 196.Fn fchown , 197.Fn lchown , 198and 199.Fn fchownat 200mark for update the 201.Fa st_ctime 202field of the file. 203.Sh RETURN VALUES 204Upon successful completion, 205.Sy 0 206is returned. 207Otherwise, 208.Sy -1 209is returned, the owner and group of the named file remain unchanged, and 210.Va errno 211is set to indicate the error. 212.Sh ERRORS 213All of these functions will fail if: 214.Bl -tag -width Er 215.It Er EPERM 216The effective user ID does not match the owner of the file and the 217.Brq Dv PRIV_FILE_CHOWN 218privilege is not asserted in the effective set of the calling process, or the 219.Brq Dv PRIV_FILE_CHOWN_SELF 220privilege is not asserted in the effective set of the calling process. 221.El 222.Pp 223The 224.Fn chown , 225.Fn lchown , 226and 227.Fn fchownat 228functions will fail if: 229.Bl -tag -width Er 230.It Er EACCES 231Search permission is denied on a component of the path prefix of 232.Fa path . 233.It Er EFAULT 234The 235.Fa path 236argument points to an illegal address and for 237.Fn fchownat , 238the file descriptor has the value 239.Dv AT_FDCWD . 240.It Er EINTR 241A signal was caught during the execution of the 242.Fn chown 243or 244.Fn lchown 245function. 246.It Er EINVAL 247The 248.Fa group 249or 250.Fa owner 251argument is out of range. 252.It Er EIO 253An I/O error occurred while reading from or writing to the file system. 254.It Er ELOOP 255Too many symbolic links were encountered in translating 256.Fa path . 257.It Er ENAMETOOLONG 258The length of the 259.Fa path 260argument exceeds 261.Brq Dv PATH_MAX , 262or the length of a 263.Fa path 264component exceeds 265.Brq Dv NAME_MAX 266while 267.Brq Dv _POSIX_NO_TRUNC 268is in effect. 269.It Er ENOLINK 270The 271.Fa path 272argument points to a remote machine and the link to that machine is no longer 273active. 274.It Er ENOENT 275Either a component of the path prefix or the file referred to by 276.Fa path 277does not exist or is a null pathname. 278.It Er ENOTDIR 279A component of the path prefix of 280.Fa path 281is not a directory, or the path supplied to 282.Fn fchownat 283is relative and the file descriptor provided does not refer to a valid 284directory. 285.It Er EROFS 286The named file resides on a read-only file system. 287.El 288.Pp 289The 290.Fn chown 291and 292.Fn fchownat 293functions will fail if: 294.Bl -tag -width Er 295.It Er EBADF 296For 297.Fn fchown , 298the 299.Fa fildes 300argument is not an open file descriptor. 301.Pp 302For 303.Fn fchownat , 304the 305.Fa path 306argument is not absolute and the fildes argument is neither 307.Dv AT_FDCWD , 308nor an open file descriptor. 309.It Er EIO 310An I/O error occurred while reading from or writing to the file system. 311.It Er EINTR 312A signal was caught during execution of the function. 313.It Er ENOLINK 314The 315.Fa fildes 316argument points to a remote machine and the link to that machine is no longer 317active. 318.It Er EINVAL 319The 320.Fa group 321or 322.Fa owner 323argument is out of range. 324.It Er EROFS 325The named file referred to by 326.Fa fildes 327resides on a read-only file system. 328.El 329.Sh INTERFACE STABILITY 330.Sy Committed 331.Sh MT-LEVEL 332.Sy Async-Signal-Safe 333.Sh SEE ALSO 334.Xr chgrp 1 , 335.Xr chown 1 , 336.Xr chmod 2 , 337.Xr fpathconf 2 , 338.Xr system 4 , 339.Xr attributes 5 , 340.Xr standards 5 341