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 October 31, 2024 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.Pp 218While it is normally an error to invoke 219.Fn fchmod 220on a socket, it is possible to do so on 221.Dv AF_LOCAL 222sockets before they are bound to a file name; see 223.Xr unix 4 . 224.Sh RETURN VALUES 225.Rv -std 226.Sh ERRORS 227The 228.Fn chmod 229system call 230will fail and the file mode will be unchanged if: 231.Bl -tag -width Er 232.It Bq Er ENOTDIR 233A component of the path prefix is not a directory. 234.It Bq Er ENAMETOOLONG 235A component of a pathname exceeded 255 characters, 236or an entire path name exceeded 1023 characters. 237.It Bq Er ENOENT 238The named file does not exist. 239.It Bq Er EACCES 240Search permission is denied for a component of the path prefix. 241.It Bq Er ELOOP 242Too many symbolic links were encountered in translating the pathname. 243.It Bq Er EPERM 244The effective user ID does not match the owner of the file and 245the effective user ID is not the super-user. 246.It Bq Er EPERM 247The effective user ID is not the super-user, the effective user ID do match the 248owner of the file, but the group ID of the file does not match the effective 249group ID nor one of the supplementary group IDs. 250.It Bq Er EPERM 251The named file has its immutable or append-only flag set, see the 252.Xr chflags 2 253manual page for more information. 254.It Bq Er EROFS 255The named file resides on a read-only file system. 256.It Bq Er EFAULT 257The 258.Fa path 259argument 260points outside the process's allocated address space. 261.It Bq Er EIO 262An I/O error occurred while reading from or writing to the file system. 263.It Bq Er EINTEGRITY 264Corrupted data was detected while reading from the file system. 265.It Bq Er EFTYPE 266The effective user ID is not the super-user, the mode includes the sticky bit 267.Dv ( S_ISVTX ) , 268and path does not refer to a directory. 269.El 270.Pp 271The 272.Fn fchmod 273system call will fail if: 274.Bl -tag -width Er 275.It Bq Er EBADF 276The descriptor is not valid. 277.It Bq Er EINVAL 278The 279.Fa fd 280argument 281refers to a socket, not to a file. 282.It Bq Er EROFS 283The file resides on a read-only file system. 284.It Bq Er EIO 285An I/O error occurred while reading from or writing to the file system. 286.It Bq Er EINTEGRITY 287Corrupted data was detected while reading from the file system. 288.El 289.Pp 290In addition to the 291.Fn chmod 292errors, 293.Fn fchmodat 294fails if: 295.Bl -tag -width Er 296.It Bq Er EBADF 297The 298.Fa path 299argument does not specify an absolute path and the 300.Fa fd 301argument is neither 302.Fa AT_FDCWD 303nor a valid file descriptor open for searching. 304.It Bq Er EINVAL 305The value of the 306.Fa flag 307argument is not valid. 308.It Bq Er ENOTDIR 309The 310.Fa path 311argument is not an absolute path and 312.Fa fd 313is neither 314.Dv AT_FDCWD 315nor a file descriptor associated with a directory. 316.It Bq Er ENOTCAPABLE 317.Fa path 318is an absolute path, 319or contained a ".." component leading to a 320directory outside of the directory hierarchy specified by 321.Fa fd , 322and the process is in capability mode or the 323.Dv AT_RESOLVE_BENEATH 324flag was specified. 325.El 326.Sh SEE ALSO 327.Xr chmod 1 , 328.Xr chflags 2 , 329.Xr chown 2 , 330.Xr open 2 , 331.Xr stat 2 , 332.Xr sticky 7 333.Sh STANDARDS 334The 335.Fn chmod 336system call is expected to conform to 337.St -p1003.1-90 , 338except for the return of 339.Er EFTYPE . 340The 341.Dv S_ISVTX 342bit on directories is expected to conform to 343.St -susv3 . 344The 345.Fn fchmodat 346system call is expected to conform to 347.St -p1003.1-2008 . 348.Sh HISTORY 349The 350.Fn chmod 351function appeared in 352.At v1 . 353The 354.Fn fchmod 355system call appeared in 356.Bx 4.2 . 357The 358.Fn lchmod 359system call appeared in 360.Fx 3.0 . 361The 362.Fn fchmodat 363system call appeared in 364.Fx 8.0 . 365