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