1.\" $OpenBSD: chmod.2,v 1.17 2011/07/19 20:58:05 matthew 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: July 19 2011 $ 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/types.h> 43.Fd #include <sys/stat.h> 44.Fd #include <fcntl.h> 45.Ft int 46.Fn chmod "const char *path" "mode_t mode" 47.Ft int 48.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" 49.Ft int 50.Fn fchmod "int fd" "mode_t mode" 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 62Values for 63.Fa mode 64are constructed by bitwise-inclusive 65.Tn OR Ns ing 66permission bit masks from the following list defined in 67.In sys/stat.h : 68.Bd -literal -offset indent 69#define S_IRWXU 0000700 /* RWX mask for owner */ 70#define S_IRUSR 0000400 /* R for owner */ 71#define S_IWUSR 0000200 /* W for owner */ 72#define S_IXUSR 0000100 /* X for owner */ 73 74#define S_IRWXG 0000070 /* RWX mask for group */ 75#define S_IRGRP 0000040 /* R for group */ 76#define S_IWGRP 0000020 /* W for group */ 77#define S_IXGRP 0000010 /* X for group */ 78 79#define S_IRWXO 0000007 /* RWX mask for other */ 80#define S_IROTH 0000004 /* R for other */ 81#define S_IWOTH 0000002 /* W for other */ 82#define S_IXOTH 0000001 /* X for other */ 83 84#define S_ISUID 0004000 /* set user id on execution */ 85#define S_ISGID 0002000 /* set group id on execution */ 86#define S_ISVTX 0001000 /* save swapped text even after use */ 87.Ed 88.Pp 89If mode 90.Dv ISVTX 91(the 92.Em sticky bit ) 93is set on a file, it is ignored. 94.Pp 95If mode 96.Dv ISVTX 97(the 98.Em sticky bit ) 99is set on a directory, an unprivileged user may not delete or rename 100files of other users in that directory. 101The sticky bit may be set by any user on a directory which the user owns 102or has appropriate permissions. 103For more details of the properties of the sticky bit, see 104.Xr sticky 8 . 105.Pp 106Writing or changing the owner of a file turns off the set-user-ID and 107set-group-ID bits unless the user is the superuser. 108This makes the system somewhat more secure by protecting 109set-user-ID (set-group-ID) files from remaining set-user-ID (set-group-ID) 110if they are modified, at the expense of a degree of compatibility. 111.Pp 112The 113.Fn fchmodat 114function is equivalent to 115.Fn chmod 116except in the case where 117.Fa path 118specifies a relative path. 119In this case the file to be changed is determined relative to the directory 120associated with the file descriptor 121.Fa fd 122instead of the current working directory. 123.Pp 124If 125.Fn fchmodat 126is passed the special value 127.Dv AT_FDCWD 128(defined in 129.In fcntl.h ) 130in the 131.Fa fd 132parameter, the current working directory is used. 133If 134.Fa flag 135is also zero, the behavior is identical to a call to 136.Fn chmod . 137.Pp 138Values for 139.Fa flag 140are constructed by bitwise-inclusive 141.Tn OR Ns ing 142flags from the following list defined in 143.In fcntl.h : 144.Pp 145.Bl -tag -width AT_SYMLINK_NOFOLLOW -offset indent -compact 146.It Dv AT_SYMLINK_NOFOLLOW 147If 148.Fa path 149names a symbolic link, then the mode of the symbolic link is changed. 150.El 151.Pp 152The 153.Fn fchmod 154function is equivalent to 155.Fn chmod 156except that the file whose permissions are changed is specified 157by the file descriptor 158.Fa fd . 159.Sh RETURN VALUES 160Upon successful completion, a value of 0 is returned. 161Otherwise, a value of \-1 is returned and 162.Va errno 163is set to indicate the error. 164.Sh ERRORS 165The 166.Fn chmod 167and 168.Fn fchmodat 169functions will fail and the file mode will be unchanged if: 170.Bl -tag -width Er 171.It Bq Er ENOTDIR 172A component of the path prefix is not a directory. 173.It Bq Er ENAMETOOLONG 174A component of a pathname exceeded 175.Dv {NAME_MAX} 176characters, or an entire path name exceeded 177.Dv {PATH_MAX} 178characters. 179.It Bq Er ENOENT 180The named file does not exist. 181.It Bq Er EACCES 182Search permission is denied for a component of the path prefix. 183.It Bq Er EINVAL 184.Fa mode 185contains bits other than the file type and those described above. 186.It Bq Er ELOOP 187Too many symbolic links were encountered in translating the pathname. 188.It Bq Er EPERM 189The effective user ID does not match the owner of the file and 190the effective user ID is not the superuser. 191.It Bq Er EROFS 192The named file resides on a read-only file system. 193.It Bq Er EFAULT 194.Fa path 195points outside the process's allocated address space. 196.It Bq Er EIO 197An I/O error occurred while reading from or writing to the file system. 198.El 199.Pp 200Additionally, the 201.Fn fchmodat 202function will fail if: 203.Bl -tag -width Er 204.It Bq Er EBADF 205The 206.Fa path 207argument does not specify an absolute path and the 208.Fa fd 209argument is neither 210.Dv AT_FDCWD 211nor a valid file descriptor open for reading. 212.El 213.Pp 214.Fn fchmod 215will fail and the file mode will be unchanged if: 216.Bl -tag -width Er 217.It Bq Er EBADF 218The descriptor is not valid. 219.It Bq Er EINVAL 220.Fa fd 221refers to a socket, not to a file. 222.It Bq Er EINVAL 223.Fa mode 224contains bits other than the file type and those described above. 225.It Bq Er EROFS 226The file resides on a read-only file system. 227.It Bq Er EIO 228An I/O error occurred while reading from or writing to the file system. 229.El 230.Sh SEE ALSO 231.Xr chmod 1 , 232.Xr chown 2 , 233.Xr open 2 , 234.Xr stat 2 , 235.Xr sticky 8 236.Sh STANDARDS 237The 238.Fn chmod 239function is expected to conform to 240.St -p1003.1-88 . 241.Sh HISTORY 242The 243.Fn fchmod 244function call appeared in 245.Bx 4.2 . 246