1.\" $OpenBSD: chmod.2,v 1.25 2014/02/13 07:30:39 guenther 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: February 13 2014 $ 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.Fd #include <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.Fd #include <sys/stat.h> 48.Fd #include <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 155Upon successful completion, a value of 0 is returned. 156Otherwise, a value of \-1 is returned and 157.Va errno 158is set to indicate the error. 159.Sh ERRORS 160The 161.Fn chmod 162and 163.Fn fchmodat 164functions will fail and the file mode will be unchanged if: 165.Bl -tag -width Er 166.It Bq Er ENOTDIR 167A component of the path prefix is not a directory. 168.It Bq Er ENAMETOOLONG 169A component of a pathname exceeded 170.Dv {NAME_MAX} 171characters, or an entire path name exceeded 172.Dv {PATH_MAX} 173characters. 174.It Bq Er ENOENT 175The named file does not exist. 176.It Bq Er EACCES 177Search permission is denied for a component of the path prefix. 178.It Bq Er EINVAL 179.Fa mode 180contains bits other than the file type and those described above. 181.It Bq Er ELOOP 182Too many symbolic links were encountered in translating the pathname. 183.It Bq Er EPERM 184The effective user ID does not match the owner of the file and 185the effective user ID is not the superuser. 186.It Bq Er EROFS 187The named file resides on a read-only file system. 188.It Bq Er EFAULT 189.Fa path 190points outside the process's allocated address space. 191.It Bq Er EIO 192An I/O error occurred while reading from or writing to the file system. 193.El 194.Pp 195Additionally, the 196.Fn fchmodat 197function will fail if: 198.Bl -tag -width Er 199.It Bq Er EINVAL 200The value of the 201.Fa flag 202argument was neither zero nor 203.Dv AT_SYMLINK_NOFOLLOW . 204.It Bq Er EBADF 205The 206.Fa path 207argument specifies a relative path and the 208.Fa fd 209argument is neither 210.Dv AT_FDCWD 211nor a valid file descriptor. 212.It Bq Er ENOTDIR 213The 214.Fa path 215argument specifies a relative path and the 216.Fa fd 217argument is a valid file descriptor but it does not reference a directory. 218.It Bq Er EOPNOTSUPP 219The 220.Fa flag 221argument specifies 222.Dv AT_SYMLINK_NOFOLLOW 223on a symbolic link and the file system does not support that operation. 224.It Bq Er EACCES 225The 226.Fa path 227argument specifies a relative path but search permission is denied 228for the directory which the 229.Fa fd 230file descriptor references. 231.El 232.Pp 233.Fn fchmod 234will fail and the file mode will be unchanged if: 235.Bl -tag -width Er 236.It Bq Er EBADF 237The descriptor is not valid. 238.It Bq Er EINVAL 239.Fa fd 240refers to a socket, not to a file. 241.It Bq Er EINVAL 242.Fa mode 243contains bits other than the file type and those described above. 244.It Bq Er EPERM 245The effective user ID does not match the owner of the file and 246the effective user ID is not the superuser. 247.It Bq Er EROFS 248The file resides on a read-only file system. 249.It Bq Er EIO 250An I/O error occurred while reading from or writing to the file system. 251.El 252.Sh SEE ALSO 253.Xr chmod 1 , 254.Xr chown 2 , 255.Xr open 2 , 256.Xr stat 2 , 257.Xr sticky 8 258.Sh STANDARDS 259The 260.Fn chmod , 261.Fn fchmod , 262and 263.Fn fchmodat 264functions are expected to conform to 265.St -p1003.1-2008 . 266.Sh HISTORY 267The 268.Fn chmod 269system call first appeared in 270.At v1 ; 271.Fn fchmod 272in 273.Bx 4.1c ; 274and 275.Fn fchmodat 276has been available since 277.Ox 5.0 . 278