1.\" Copyright (c) 1980, 1991, 1993 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.Dd March 30, 2021 29.Dt CHMOD 2 30.Os 31.Sh NAME 32.Nm chmod , 33.Nm fchmod , 34.Nm lchmod , 35.Nm fchmodat 36.Nd change mode of file 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/stat.h 41.Ft int 42.Fn chmod "const char *path" "mode_t mode" 43.Ft int 44.Fn fchmod "int fd" "mode_t mode" 45.Ft int 46.Fn lchmod "const char *path" "mode_t mode" 47.Ft int 48.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" 49.Sh DESCRIPTION 50The file permission bits of the file named specified by 51.Fa path 52or referenced by the file descriptor 53.Fa fd 54are changed to 55.Fa mode . 56The 57.Fn chmod 58system call verifies that the process owner (user) either owns 59the file specified by 60.Fa path 61(or 62.Fa fd ) , 63or 64is the super-user. 65The 66.Fn chmod 67system call follows symbolic links to operate on the target of the link 68rather than the link itself. 69.Pp 70The 71.Fn lchmod 72system call is similar to 73.Fn chmod 74but does not follow symbolic links. 75.Pp 76The 77.Fn fchmodat 78is equivalent to either 79.Fn chmod 80or 81.Fn lchmod 82depending on the 83.Fa flag 84except in the case where 85.Fa path 86specifies a relative path. 87In this case the file to be changed is determined relative to the directory 88associated with the file descriptor 89.Fa fd 90instead of the current working directory. 91The values for the 92.Fa flag 93are constructed by a bitwise-inclusive OR of flags from the following list, defined 94in 95.In fcntl.h : 96.Bl -tag -width indent 97.It Dv AT_SYMLINK_NOFOLLOW 98If 99.Fa path 100names a symbolic link, then the mode of the symbolic link is changed. 101.It Dv AT_RESOLVE_BENEATH 102Only walk paths below the directory specified by the 103.Ar fd 104descriptor. 105See the description of the 106.Dv O_RESOLVE_BENEATH 107flag in the 108.Xr open 2 109manual page. 110.It Dv AT_EMPTY_PATH 111If the 112.Fa path 113argument is an empty string, operate on the file or directory 114referenced by the descriptor 115.Fa fd . 116If 117.Fa fd 118is equal to 119.Dv AT_FDCWD , 120operate on the current working directory. 121.El 122.Pp 123If 124.Fn fchmodat 125is passed the special value 126.Dv AT_FDCWD 127in the 128.Fa fd 129parameter, the current working directory is used. 130If also 131.Fa flag 132is zero, the behavior is identical to a call to 133.Fn chmod . 134.Pp 135A mode is created from 136.Em or'd 137permission bit masks 138defined in 139.In sys/stat.h : 140.Pp 141.Bd -literal -offset indent -compact 142#define S_IRWXU 0000700 /* RWX mask for owner */ 143#define S_IRUSR 0000400 /* R for owner */ 144#define S_IWUSR 0000200 /* W for owner */ 145#define S_IXUSR 0000100 /* X for owner */ 146 147#define S_IRWXG 0000070 /* RWX mask for group */ 148#define S_IRGRP 0000040 /* R for group */ 149#define S_IWGRP 0000020 /* W for group */ 150#define S_IXGRP 0000010 /* X for group */ 151 152#define S_IRWXO 0000007 /* RWX mask for other */ 153#define S_IROTH 0000004 /* R for other */ 154#define S_IWOTH 0000002 /* W for other */ 155#define S_IXOTH 0000001 /* X for other */ 156 157#define S_ISUID 0004000 /* set user id on execution */ 158#define S_ISGID 0002000 /* set group id on execution */ 159#define S_ISVTX 0001000 /* sticky bit */ 160.Ed 161.Pp 162The non-standard 163.Dv S_ISTXT 164is a synonym for 165.Dv S_ISVTX . 166.Pp 167The 168.Fx 169VM system totally ignores the sticky bit 170.Pq Dv S_ISVTX 171for executables. 172On UFS-based file systems (FFS, LFS) the sticky 173bit may only be set upon directories. 174.Pp 175If mode 176.Dv S_ISVTX 177(the `sticky bit') is set on a directory, 178an unprivileged user may not delete or rename 179files of other users in that directory. 180The sticky bit may be 181set by any user on a directory which the user owns or has appropriate 182permissions. 183For more details of the properties of the sticky bit, see 184.Xr sticky 7 . 185.Pp 186If mode ISUID (set UID) is set on a directory, 187and the MNT_SUIDDIR option was used in the mount of the file system, 188then the owner of any new files and sub-directories 189created within this directory are set 190to be the same as the owner of that directory. 191If this function is enabled, new directories will inherit 192the bit from their parents. 193Execute bits are removed from 194the file, and it will not be given to root. 195This behavior does not change the 196requirements for the user to be allowed to write the file, but only the eventual 197owner after it has been created. 198Group inheritance is not affected. 199.Pp 200This feature is designed for use on fileservers serving PC users via 201ftp, SAMBA, or netatalk. 202It provides security holes for shell users and as 203such should not be used on shell machines, especially on home directories. 204This option requires the SUIDDIR 205option in the kernel to work. 206Only UFS file systems support this option. 207For more details of the suiddir mount option, see 208.Xr mount 8 . 209.Pp 210Writing or changing the owner of a file 211turns off the set-user-id and set-group-id bits 212unless the user is the super-user. 213This makes the system somewhat more secure 214by protecting set-user-id (set-group-id) files 215from remaining set-user-id (set-group-id) if they are modified, 216at the expense of a degree of compatibility. 217.Sh RETURN VALUES 218.Rv -std 219.Sh ERRORS 220The 221.Fn chmod 222system call 223will fail and the file mode will be unchanged if: 224.Bl -tag -width Er 225.It Bq Er ENOTDIR 226A component of the path prefix is not a directory. 227.It Bq Er ENAMETOOLONG 228A component of a pathname exceeded 255 characters, 229or an entire path name exceeded 1023 characters. 230.It Bq Er ENOENT 231The named file does not exist. 232.It Bq Er EACCES 233Search permission is denied for a component of the path prefix. 234.It Bq Er ELOOP 235Too many symbolic links were encountered in translating the pathname. 236.It Bq Er EPERM 237The effective user ID does not match the owner of the file and 238the effective user ID is not the super-user. 239.It Bq Er EPERM 240The effective user ID is not the super-user, the effective user ID do match the 241owner of the file, but the group ID of the file does not match the effective 242group ID nor one of the supplementary group IDs. 243.It Bq Er EPERM 244The named file has its immutable or append-only flag set, see the 245.Xr chflags 2 246manual page for more information. 247.It Bq Er EROFS 248The named file resides on a read-only file system. 249.It Bq Er EFAULT 250The 251.Fa path 252argument 253points outside the process's allocated address space. 254.It Bq Er EIO 255An I/O error occurred while reading from or writing to the file system. 256.It Bq Er EINTEGRITY 257Corrupted data was detected while reading from the file system. 258.It Bq Er EFTYPE 259The effective user ID is not the super-user, the mode includes the sticky bit 260.Dv ( S_ISVTX ) , 261and path does not refer to a directory. 262.El 263.Pp 264The 265.Fn fchmod 266system call will fail if: 267.Bl -tag -width Er 268.It Bq Er EBADF 269The descriptor is not valid. 270.It Bq Er EINVAL 271The 272.Fa fd 273argument 274refers to a socket, not to a file. 275.It Bq Er EROFS 276The file resides on a read-only file system. 277.It Bq Er EIO 278An I/O error occurred while reading from or writing to the file system. 279.It Bq Er EINTEGRITY 280Corrupted data was detected while reading from the file system. 281.El 282.Pp 283In addition to the 284.Fn chmod 285errors, 286.Fn fchmodat 287fails if: 288.Bl -tag -width Er 289.It Bq Er EBADF 290The 291.Fa path 292argument does not specify an absolute path and the 293.Fa fd 294argument is neither 295.Fa AT_FDCWD 296nor a valid file descriptor open for searching. 297.It Bq Er EINVAL 298The value of the 299.Fa flag 300argument is not valid. 301.It Bq Er ENOTDIR 302The 303.Fa path 304argument is not an absolute path and 305.Fa fd 306is neither 307.Dv AT_FDCWD 308nor a file descriptor associated with a directory. 309.It Bq Er ENOTCAPABLE 310.Fa path 311is an absolute path, 312or contained a ".." component leading to a 313directory outside of the directory hierarchy specified by 314.Fa fd , 315and the process is in capability mode or the 316.Dv AT_RESOLVE_BENEATH 317flag was specified. 318.El 319.Sh SEE ALSO 320.Xr chmod 1 , 321.Xr chflags 2 , 322.Xr chown 2 , 323.Xr open 2 , 324.Xr stat 2 , 325.Xr sticky 7 326.Sh STANDARDS 327The 328.Fn chmod 329system call is expected to conform to 330.St -p1003.1-90 , 331except for the return of 332.Er EFTYPE . 333The 334.Dv S_ISVTX 335bit on directories is expected to conform to 336.St -susv3 . 337The 338.Fn fchmodat 339system call is expected to conform to 340.St -p1003.1-2008 . 341.Sh HISTORY 342The 343.Fn chmod 344function appeared in 345.At v1 . 346The 347.Fn fchmod 348system call appeared in 349.Bx 4.2 . 350The 351.Fn lchmod 352system call appeared in 353.Fx 3.0 . 354The 355.Fn fchmodat 356system call appeared in 357.Fx 8.0 . 358