1.\" $NetBSD: chmod.2,v 1.7 1995/02/27 12:32:06 cgd 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)chmod.2 8.1 (Berkeley) 6/4/93 35.\" 36.Dd June 4, 1993 37.Dt CHMOD 2 38.Os BSD 4 39.Sh NAME 40.Nm chmod , 41.Nm fchmod , 42.Nm fchmodat 43.Nd change mode of file 44.Sh SYNOPSIS 45.Fd #include <sys/types.h> 46.Fd #include <sys/stat.h> 47.Ft int 48.Fo chmod 49.Fa "const char *path" 50.Fa "mode_t mode" 51.Fc 52.Ft int 53.Fo fchmod 54.Fa "int fildes" 55.Fa "mode_t mode" 56.Fc 57.Ft int 58.Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag" 59.Sh DESCRIPTION 60The function 61.Fn chmod 62sets the file permission bits 63of the file 64specified by the pathname 65.Fa path 66to 67.Fa mode . 68.Fn fchmod 69sets the permission bits of the specified 70file descriptor 71.Fa fildes . 72.Fn chmod 73verifies that the process owner (user) either owns 74the file specified by 75.Fa path 76(or 77.Fa fildes ) , 78or 79is the super-user. 80.Pp 81The 82.Fn fchmodat 83is equivalent to 84.Fn chmod 85except in the case where 86.Fa path 87specifies a relative path. 88In this case the file to be changed is determined relative to the directory 89associated with the file descriptor 90.Fa fd 91instead of the current working directory. 92The values for the 93.Fa flag 94are constructed by a bitwise-inclusive OR of flags from the following list, defined 95in 96.In fcntl.h : 97.Bl -tag -width indent 98.It Dv AT_SYMLINK_NOFOLLOW 99If 100.Fa path 101names a symbolic link, then the mode of the symbolic link is changed. 102.El 103.Bl -tag -width indent 104.It Dv AT_SYMLINK_NOFOLLOW_ANY 105If 106.Fa path 107names a symbolic link, then the mode of the symbolic link is changed and if 108if the path has any other symbolic links, an error is returned. 109.El 110.Pp 111If 112.Fn fchmodat 113is passed the special value 114.Dv AT_FDCWD 115in the 116.Fa fd 117parameter, the current working directory is used. 118If also 119.Fa flag 120is zero, the behavior is identical to a call to 121.Fn chmod . 122A mode is created from 123.Em or'd 124permission bit masks 125defined in 126.Aq Pa 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 /* save swapped text even after use */ 146.Ed 147.Pp 148The 149.Dv ISVTX 150(the 151.Em sticky bit ) 152indicates to the system which executable files are shareable (the 153default) and the system maintains the program text of the files 154in the swap area. The sticky bit may only be set by the super user 155on shareable executable files. 156.Pp 157If mode 158.Dv ISVTX 159(the `sticky bit') is set on a directory, 160an unprivileged user may not delete or rename 161files of other users in that directory. The sticky bit may be 162set by any user on a directory which the user owns or has appropriate 163permissions. 164For more details of the properties of the sticky bit, see 165.Xr sticky 7 . 166.Pp 167Writing or changing the owner of a file 168turns off the set-user-id and set-group-id bits 169unless the user is the super-user. 170This makes the system somewhat more secure 171by protecting set-user-id (set-group-id) files 172from remaining set-user-id (set-group-id) if they are modified, 173at the expense of a degree of compatibility. 174.Sh RETURN VALUES 175Upon successful completion, a value of 0 is returned. 176Otherwise, a value of -1 is returned and 177.Va errno 178is set to indicate the error. 179.Sh ERRORS 180The 181.Fn chmod 182system call will fail and the file mode will be unchanged if: 183.Bl -tag -width Er 184.\" ========== 185.It Bq Er EACCES 186Search permission is denied for a component of the path prefix. 187.\" ========== 188.It Bq Er EFAULT 189.Fa Path 190points outside the process's allocated address space. 191.\" ========== 192.It Bq Er EINTR 193Its execution was interrupted by a signal. 194.\" ========== 195.It Bq Er EIO 196An I/O error occurred while reading from or writing to the file system. 197.\" ========== 198.It Bq Er ELOOP 199Too many symbolic links were encountered in translating the pathname. 200This is taken to be indicative of a looping symbolic link. 201.\" ========== 202.It Bq Er ELOOP 203If AT_SYMLINK_NOFOLLOW_ANY was passed and a symbolic link was encountered 204in translating the pathname. 205.\" ========== 206.It Bq Er ENAMETOOLONG 207A component of a pathname exceeded 208.Dv {NAME_MAX} 209characters, or an entire path name exceeded 210.Dv {PATH_MAX} 211characters. 212.\" ========== 213.It Bq Er ENOENT 214The named file does not exist. 215.\" ========== 216.It Bq Er ENOTDIR 217A component of the path prefix is not a directory. 218.\" ========== 219.It Bq Er EPERM 220The effective user ID does not match the owner of the file and 221the effective user ID is not the super-user. 222.\" ========== 223.It Bq Er EROFS 224The named file resides on a read-only file system. 225.El 226.Pp 227.Fn fchmod 228will fail if: 229.Bl -tag -width Er 230.\" ========== 231.It Bq Er EBADF 232.Fa fildes 233is not a valid file descriptor. 234.\" ========== 235.It Bq Er EINVAL 236.Fa fildes 237refers to a socket, not to a file. 238.\" ========== 239.It Bq Er EINVAL 240.Fa mode 241is not a valid file mode. 242.\" ========== 243.It Bq Er EINTR 244Its execution was interrupted by a signal. 245.\" ========== 246.It Bq Er EIO 247An I/O error occurred while reading from or writing to the file system. 248.\" ========== 249.It Bq Er EPERM 250The effective user ID does not match the owner of the file and 251the effective user ID is not the super-user. 252.\" ========== 253.It Bq Er EROFS 254The file resides on a read-only file system. 255.El 256.Pp 257In addition to the 258.Fn chmod 259errors, 260.Fn fchmodat 261fails if: 262.Bl -tag -width Er 263.It Bq Er EBADF 264The 265.Fa path 266argument does not specify an absolute path and the 267.Fa fd 268argument is neither 269.Fa AT_FDCWD 270nor a valid file descriptor open for searching. 271.It Bq Er EINVAL 272The value of the 273.Fa flag 274argument is not valid. 275.It Bq Er ENOTDIR 276The 277.Fa path 278argument is not an absolute path and 279.Fa fd 280is neither 281.Dv AT_FDCWD 282nor a file descriptor associated with a directory. 283.El 284.Sh LEGACY SYNOPSIS 285.Fd #include <sys/types.h> 286.Fd #include <sys/stat.h> 287.Pp 288The include file 289.In sys/types.h 290is necessary. 291.Sh SEE ALSO 292.Xr chmod 1 , 293.Xr chown 2 , 294.Xr open 2 , 295.Xr stat 2 , 296.Xr compat 5 , 297.Xr sticky 7 298.Sh STANDARDS 299The 300.Fn chmod 301function is expected to conform to 302.St -p1003.1-88 . 303The 304.Fn fchmodat 305function is expected to conform to POSIX.1-2008 . 306.Sh HISTORY 307The 308.Fn fchmod 309function call 310appeared in 311.Bx 4.2 . 312The 313.Fn fchmodat 314system call appeared in OS X 10.10 315