1.\" $OpenBSD: chmod.2,v 1.28 2015/09/10 17:55:21 schwarze Exp $ 2.\" $NetBSD: chmod.2,v 1.7 1995/02/27 12:32:06 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: September 10 2015 $ 34.Dt CHMOD 2 35.Os 36.Sh NAME 37.Nm chmod , 38.Nm fchmodat , 39.Nm fchmod 40.Nd change mode of file 41.Sh SYNOPSIS 42.In sys/stat.h 43.Ft int 44.Fn chmod "const char *path" "mode_t mode" 45.Ft int 46.Fn fchmod "int fd" "mode_t mode" 47.In sys/stat.h 48.In fcntl.h 49.Ft int 50.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" 51.Sh DESCRIPTION 52The 53.Fn chmod 54function sets the file permission bits of the file specified by the pathname 55.Fa path 56to 57.Fa mode . 58.Fn chmod 59verifies that the process owner (user) either owns the specified file 60or is the superuser. 61.Pp 62The 63.Fa mode 64argument is the bitwise OR of zero or more of the permission bit masks 65from the following list: 66.Bd -literal -offset indent 67#define S_IRWXU 0000700 /* RWX mask for owner */ 68#define S_IRUSR 0000400 /* R for owner */ 69#define S_IWUSR 0000200 /* W for owner */ 70#define S_IXUSR 0000100 /* X for owner */ 71 72#define S_IRWXG 0000070 /* RWX mask for group */ 73#define S_IRGRP 0000040 /* R for group */ 74#define S_IWGRP 0000020 /* W for group */ 75#define S_IXGRP 0000010 /* X for group */ 76 77#define S_IRWXO 0000007 /* RWX mask for other */ 78#define S_IROTH 0000004 /* R for other */ 79#define S_IWOTH 0000002 /* W for other */ 80#define S_IXOTH 0000001 /* X for other */ 81 82#define S_ISUID 0004000 /* set user id on execution */ 83#define S_ISGID 0002000 /* set group id on execution */ 84#define S_ISVTX 0001000 /* save swapped text even after use */ 85.Ed 86.Pp 87If mode 88.Dv ISVTX 89(the 90.Em sticky bit ) 91is set on a file, it is ignored. 92.Pp 93If mode 94.Dv ISVTX 95(the 96.Em sticky bit ) 97is set on a directory, an unprivileged user may not delete or rename 98files of other users in that directory. 99The sticky bit may be set by any user on a directory which the user owns 100or has appropriate permissions. 101For more details of the properties of the sticky bit, see 102.Xr sticky 8 . 103.Pp 104Writing or changing the owner of a file turns off the set-user-ID and 105set-group-ID bits unless the user is the superuser. 106This makes the system somewhat more secure by protecting 107set-user-ID (set-group-ID) files from remaining set-user-ID (set-group-ID) 108if they are modified, at the expense of a degree of compatibility. 109.Pp 110The 111.Fn fchmodat 112function is equivalent to 113.Fn chmod 114except in the case where 115.Fa path 116specifies a relative path. 117In this case the file to be changed is determined relative to the directory 118associated with the file descriptor 119.Fa fd 120instead of the current working directory. 121.Pp 122If 123.Fn fchmodat 124is passed the special value 125.Dv AT_FDCWD 126(defined in 127.In fcntl.h ) 128in the 129.Fa fd 130parameter, the current working directory is used. 131If 132.Fa flag 133is also zero, the behavior is identical to a call to 134.Fn chmod . 135.Pp 136The 137.Fa flag 138argument is the bitwise OR of zero or more of the following values: 139.Pp 140.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact 141.It Dv AT_SYMLINK_NOFOLLOW 142If 143.Fa path 144names a symbolic link, then the mode of the symbolic link is changed. 145.El 146.Pp 147The 148.Fn fchmod 149function is equivalent to 150.Fn chmod 151except that the file whose permissions are changed is specified 152by the file descriptor 153.Fa fd . 154.Sh RETURN VALUES 155.Rv -std 156.Sh ERRORS 157The 158.Fn chmod 159and 160.Fn fchmodat 161functions will fail and the file mode will be unchanged if: 162.Bl -tag -width Er 163.It Bq Er ENOTDIR 164A component of the path prefix is not a directory. 165.It Bq Er ENAMETOOLONG 166A component of a pathname exceeded 167.Dv NAME_MAX 168characters, or an entire pathname (including the terminating NUL) 169exceeded 170.Dv PATH_MAX 171bytes. 172.It Bq Er ENOENT 173The named file does not exist. 174.It Bq Er EACCES 175Search permission is denied for a component of the path prefix. 176.It Bq Er EINVAL 177.Fa mode 178contains bits other than the file type and those described above. 179.It Bq Er ELOOP 180Too many symbolic links were encountered in translating the pathname. 181.It Bq Er EPERM 182The effective user ID does not match the owner of the file and 183the effective user ID is not the superuser. 184.It Bq Er EROFS 185The named file resides on a read-only file system. 186.It Bq Er EFAULT 187.Fa path 188points outside the process's allocated address space. 189.It Bq Er EIO 190An I/O error occurred while reading from or writing to the file system. 191.El 192.Pp 193Additionally, the 194.Fn fchmodat 195function will fail if: 196.Bl -tag -width Er 197.It Bq Er EINVAL 198The value of the 199.Fa flag 200argument was neither zero nor 201.Dv AT_SYMLINK_NOFOLLOW . 202.It Bq Er EBADF 203The 204.Fa path 205argument specifies a relative path and the 206.Fa fd 207argument is neither 208.Dv AT_FDCWD 209nor a valid file descriptor. 210.It Bq Er ENOTDIR 211The 212.Fa path 213argument specifies a relative path and the 214.Fa fd 215argument is a valid file descriptor but it does not reference a directory. 216.It Bq Er EOPNOTSUPP 217The 218.Fa flag 219argument specifies 220.Dv AT_SYMLINK_NOFOLLOW 221on a symbolic link and the file system does not support that operation. 222.It Bq Er EACCES 223The 224.Fa path 225argument specifies a relative path but search permission is denied 226for the directory which the 227.Fa fd 228file descriptor references. 229.El 230.Pp 231.Fn fchmod 232will fail and the file mode will be unchanged if: 233.Bl -tag -width Er 234.It Bq Er EBADF 235The descriptor is not valid. 236.It Bq Er EINVAL 237.Fa fd 238refers to a socket, not to a file. 239.It Bq Er EINVAL 240.Fa mode 241contains bits other than the file type and those described above. 242.It Bq Er EPERM 243The effective user ID does not match the owner of the file and 244the effective user ID is not the superuser. 245.It Bq Er EROFS 246The file resides on a read-only file system. 247.It Bq Er EIO 248An I/O error occurred while reading from or writing to the file system. 249.El 250.Sh SEE ALSO 251.Xr chmod 1 , 252.Xr chown 2 , 253.Xr open 2 , 254.Xr stat 2 , 255.Xr sticky 8 256.Sh STANDARDS 257The 258.Fn chmod , 259.Fn fchmod , 260and 261.Fn fchmodat 262functions are expected to conform to 263.St -p1003.1-2008 . 264.Sh HISTORY 265The 266.Fn chmod 267system call first appeared in 268.At v1 ; 269.Fn fchmod 270in 271.Bx 4.1c ; 272and 273.Fn fchmodat 274has been available since 275.Ox 5.0 . 276