1.\" $NetBSD: chmod.2,v 1.45 2013/01/13 08:15:02 dholland 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 November 18, 2012 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 178Upon successful completion, a value of 0 is returned. 179Otherwise, a value of \-1 is returned and 180.Va errno 181is set to indicate the error. 182.Sh ERRORS 183.Fn chmod 184and 185.Fn lchmod 186will fail and the file mode will be unchanged if: 187.Bl -tag -width Er 188.It Bq Er EACCES 189Search permission is denied for a component of the path prefix. 190.It Bq Er EFAULT 191.Fa path 192points outside the process's allocated address space. 193.It Bq Er EFTYPE 194The effective user ID is not the super-user, the 195.Fa mode 196includes the sticky bit 197.Pq Dv S_ISVTX , 198and 199.Fa path 200does not refer to a directory. 201.It Bq Er EIO 202An I/O error occurred while reading from or writing to the file system. 203.It Bq Er ELOOP 204Too many symbolic links were encountered in translating the pathname. 205.It Bq Er ENAMETOOLONG 206A component of a pathname exceeded 207.Brq Dv NAME_MAX 208characters, or an entire path name exceeded 209.Brq Dv PATH_MAX 210characters. 211.It Bq Er ENOENT 212The named file does not exist. 213.It Bq Er ENOTDIR 214A component of the path prefix is not a directory. 215.It Bq Er EPERM 216The effective user ID does not match the owner of the file and 217the effective user ID is not the super-user; or 218the mode includes the setgid bit 219.Pq Dv S_ISGID 220but the file's group is neither the effective group ID nor is it in the 221group access list. 222.It Bq Er EROFS 223The named file resides on a read-only file system. 224.El 225.Pp 226.Fn fchmod 227will fail if: 228.Bl -tag -width Er 229.It Bq Er EBADF 230The descriptor is not valid. 231.It Bq Er EFTYPE 232The effective user ID is not the super-user, the 233.Fa mode 234includes the sticky bit 235.Pq Dv S_ISVTX , 236and 237.Fa fd 238does not refer to a directory. 239.It Bq Er EINVAL 240.Fa fd 241refers to a socket, not to a file. 242.It Bq Er EIO 243An I/O error occurred while reading from or writing to the file system. 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 super-user; or 247the mode includes the setgid bit 248.Pq Dv S_ISGID 249but the file's group is neither the effective group ID nor is it in the 250group access list. 251.It Bq Er EROFS 252The file resides on a read-only file system. 253.El 254.Sh SEE ALSO 255.Xr chmod 1 , 256.Xr chflags 2 , 257.Xr chown 2 , 258.Xr open 2 , 259.Xr stat 2 , 260.Xr getmode 3 , 261.Xr setmode 3 , 262.Xr sticky 7 , 263.Xr symlink 7 264.Sh STANDARDS 265The 266.Fn chmod 267function conforms to 268.St -p1003.1-90 . 269.Fn fchmodat 270function conforms to 271.St -p1003.1-2008 . 272.Sh HISTORY 273The 274.Fn fchmod 275function call 276appeared in 277.Bx 4.2 . 278The 279.Fn lchmod 280function call appeared in 281.Nx 1.3 . 282