man2/chmod.2

   1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   2 .\" and Copyright (C) 2006, 2014 Michael Kerrisk
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified by Michael Haardt <michael@moria.de>
   7 .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified 1997-01-12 by Michael Haardt
   9 .\"   <michael@cantor.informatik.rwth-aachen.de>: NFS details
  10 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  11 .\"
  12 .TH CHMOD 2 2021-08-27 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  13 .SH NAME
  14 chmod, fchmod, fchmodat \- change permissions of a file
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <sys/stat.h>
  21 .PP
  22 .BI "int chmod(const char *" pathname ", mode_t " mode );
  23 .BI "int fchmod(int " fd ", mode_t " mode );
  24 .PP
  25 .BR "#include <fcntl.h>" "           /* Definition of AT_* constants */"
  26 .B #include <sys/stat.h>
  27 .PP
  28 .BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \
  29 mode ", int " flags );
  30 .fi
  31 .PP
  32 .RS -4
  33 Feature Test Macro Requirements for glibc (see
  34 .BR feature_test_macros (7)):
  35 .RE
  36 .PP
  37 .nf
  38 .BR fchmod ():
  39     Since glibc 2.24:
  40         _POSIX_C_SOURCE >= 199309L
  41 .\"        || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
  42     Glibc 2.19 to 2.23
  43         _POSIX_C_SOURCE
  44     Glibc 2.16 to 2.19:
  45         _BSD_SOURCE || _POSIX_C_SOURCE
  46     Glibc 2.12 to 2.16:
  47         _BSD_SOURCE || _XOPEN_SOURCE >= 500
  48             || _POSIX_C_SOURCE >= 200809L
  49     Glibc 2.11 and earlier:
  50         _BSD_SOURCE || _XOPEN_SOURCE >= 500
  51 .\"        || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
  52 .fi
  53 .PP
  54 .BR fchmodat ():
  55 .nf
  56     Since glibc 2.10:
  57         _POSIX_C_SOURCE >= 200809L
  58     Before glibc 2.10:
  59         _ATFILE_SOURCE
  60 .fi
  61 .SH DESCRIPTION
  62 The
  63 .BR chmod ()
  64 and
  65 .BR fchmod ()
  66 system calls change a file's mode bits.
  67 (The file mode consists of the file permission bits plus the set-user-ID,
  68 set-group-ID, and sticky bits.)
  69 These system calls differ only in how the file is specified:
  70 .IP * 2
  71 .BR chmod ()
  72 changes the mode of the file specified whose pathname is given in
  73 .IR pathname ,
  74 which is dereferenced if it is a symbolic link.
  75 .IP *
  76 .BR fchmod ()
  77 changes the mode of the file referred to by the open file descriptor
  78 .IR fd .
  79 .PP
  80 The new file mode is specified in
  81 .IR mode ,
  82 which is a bit mask created by ORing together zero or
  83 more of the following:
  84 .TP 18
  85 .BR S_ISUID "  (04000)"
  86 set-user-ID (set process effective user ID on
  87 .BR execve (2))
  88 .TP
  89 .BR S_ISGID "  (02000)"
  90 set-group-ID (set process effective group ID on
  91 .BR execve (2);
  92 mandatory locking, as described in
  93 .BR fcntl (2);
  94 take a new file's group from parent directory, as described in
  95 .BR chown (2)
  96 and
  97 .BR mkdir (2))
  98 .TP
  99 .BR S_ISVTX "  (01000)"
 100 sticky bit (restricted deletion flag, as described in
 101 .BR unlink (2))
 102 .TP
 103 .BR S_IRUSR "  (00400)"
 104 read by owner
 105 .TP
 106 .BR S_IWUSR "  (00200)"
 107 write by owner
 108 .TP
 109 .BR S_IXUSR "  (00100)"
 110 execute/search by owner ("search" applies for directories,
 111 and means that entries within the directory can be accessed)
 112 .TP
 113 .BR S_IRGRP "  (00040)"
 114 read by group
 115 .TP
 116 .BR S_IWGRP "  (00020)"
 117 write by group
 118 .TP
 119 .BR S_IXGRP "  (00010)"
 120 execute/search by group
 121 .TP
 122 .BR S_IROTH "  (00004)"
 123 read by others
 124 .TP
 125 .BR S_IWOTH "  (00002)"
 126 write by others
 127 .TP
 128 .BR S_IXOTH "  (00001)"
 129 execute/search by others
 130 .PP
 131 The effective UID of the calling process must match the owner of the file,
 132 or the process must be privileged (Linux: it must have the
 133 .B CAP_FOWNER
 134 capability).
 135 .PP
 136 If the calling process is not privileged (Linux: does not have the
 137 .B CAP_FSETID
 138 capability), and the group of the file does not match
 139 the effective group ID of the process or one of its
 140 supplementary group IDs, the
 141 .B S_ISGID
 142 bit will be turned off,
 143 but this will not cause an error to be returned.
 144 .PP
 145 As a security measure, depending on the filesystem,
 146 the set-user-ID and set-group-ID execution bits
 147 may be turned off if a file is written.
 148 (On Linux, this occurs if the writing process does not have the
 149 .B CAP_FSETID
 150 capability.)
 151 On some filesystems, only the superuser can set the sticky bit,
 152 which may have a special meaning.
 153 For the sticky bit, and for set-user-ID and set-group-ID bits on
 154 directories, see
 155 .BR inode (7).
 156 .PP
 157 On NFS filesystems, restricting the permissions will immediately influence
 158 already open files, because the access control is done on the server, but
 159 open files are maintained by the client.
 160 Widening the permissions may be
 161 delayed for other clients if attribute caching is enabled on them.
 162 .\"
 163 .\"
 164 .SS fchmodat()
 165 The
 166 .BR fchmodat ()
 167 system call operates in exactly the same way as
 168 .BR chmod (),
 169 except for the differences described here.
 170 .PP
 171 If the pathname given in
 172 .I pathname
 173 is relative, then it is interpreted relative to the directory
 174 referred to by the file descriptor
 175 .I dirfd
 176 (rather than relative to the current working directory of
 177 the calling process, as is done by
 178 .BR chmod ()
 179 for a relative pathname).
 180 .PP
 181 If
 182 .I pathname
 183 is relative and
 184 .I dirfd
 185 is the special value
 186 .BR AT_FDCWD ,
 187 then
 188 .I pathname
 189 is interpreted relative to the current working
 190 directory of the calling process (like
 191 .BR chmod ()).
 192 .PP
 193 If
 194 .I pathname
 195 is absolute, then
 196 .I dirfd
 197 is ignored.
 198 .PP
 199 .I flags
 200 can either be 0, or include the following flag:
 201 .TP
 202 .B AT_SYMLINK_NOFOLLOW
 203 If
 204 .I pathname
 205 is a symbolic link, do not dereference it:
 206 instead operate on the link itself.
 207 This flag is not currently implemented.
 208 .PP
 209 See
 210 .BR openat (2)
 211 for an explanation of the need for
 212 .BR fchmodat ().
 213 .SH RETURN VALUE
 214 On success, zero is returned.
 215 On error, \-1 is returned, and
 216 .I errno
 217 is set to indicate the error.
 218 .SH ERRORS
 219 Depending on the filesystem,
 220 errors other than those listed below can be returned.
 221 .PP
 222 The more general errors for
 223 .BR chmod ()
 224 are listed below:
 225 .TP
 226 .B EACCES
 227 Search permission is denied on a component of the path prefix.
 228 (See also
 229 .BR path_resolution (7).)
 230 .TP
 231 .B EBADF
 232 .RB ( fchmod ())
 233 The file descriptor
 234 .I fd
 235 is not valid.
 236 .TP
 237 .B EBADF
 238 .RB ( fchmodat ())
 239 .I pathname
 240 is relative but
 241 .I dirfd
 242 is neither
 243 .B AT_FDCWD
 244 nor a valid file descriptor.
 245 .TP
 246 .B EFAULT
 247 .I pathname
 248 points outside your accessible address space.
 249 .TP
 250 .B EINVAL
 251 .RB ( fchmodat ())
 252 Invalid flag specified in
 253 .IR flags .
 254 .TP
 255 .B EIO
 256 An I/O error occurred.
 257 .TP
 258 .B ELOOP
 259 Too many symbolic links were encountered in resolving
 260 .IR pathname .
 261 .TP
 262 .B ENAMETOOLONG
 263 .I pathname
 264 is too long.
 265 .TP
 266 .B ENOENT
 267 The file does not exist.
 268 .TP
 269 .B ENOMEM
 270 Insufficient kernel memory was available.
 271 .TP
 272 .B ENOTDIR
 273 A component of the path prefix is not a directory.
 274 .TP
 275 .B ENOTDIR
 276 .RB ( fchmodat ())
 277 .I pathname
 278 is relative and
 279 .I dirfd
 280 is a file descriptor referring to a file other than a directory.
 281 .TP
 282 .B ENOTSUP
 283 .RB ( fchmodat ())
 284 .I flags
 285 specified
 286 .BR AT_SYMLINK_NOFOLLOW ,
 287 which is not supported.
 288 .TP
 289 .B EPERM
 290 The effective UID does not match the owner of the file,
 291 and the process is not privileged (Linux: it does not have the
 292 .B CAP_FOWNER
 293 capability).
 294 .TP
 295 .B EPERM
 296 The file is marked immutable or append-only.
 297 (See
 298 .BR ioctl_iflags (2).)
 299 .TP
 300 .B EROFS
 301 The named file resides on a read-only filesystem.
 302 .SH VERSIONS
 303 .BR fchmodat ()
 304 was added to Linux in kernel 2.6.16;
 305 library support was added to glibc in version 2.4.
 306 .SH STANDARDS
 307 .BR chmod (),
 308 .BR fchmod ():
 309 4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008.
 310 .PP
 311 .BR fchmodat ():
 312 POSIX.1-2008.
 313 .SH NOTES
 314 .SS C library/kernel differences
 315 The GNU C library
 316 .BR fchmodat ()
 317 wrapper function implements the POSIX-specified
 318 interface described in this page.
 319 This interface differs from the underlying Linux system call, which does
 320 .I not
 321 have a
 322 .I flags
 323 argument.
 324 .SS Glibc notes
 325 On older kernels where
 326 .BR fchmodat ()
 327 is unavailable, the glibc wrapper function falls back to the use of
 328 .BR chmod ().
 329 When
 330 .I pathname
 331 is a relative pathname,
 332 glibc constructs a pathname based on the symbolic link in
 333 .I /proc/self/fd
 334 that corresponds to the
 335 .I dirfd
 336 argument.
 337 .SH SEE ALSO
 338 .BR chmod (1),
 339 .BR chown (2),
 340 .BR execve (2),
 341 .BR open (2),
 342 .BR stat (2),
 343 .BR inode (7),
 344 .BR path_resolution (7),
 345 .BR symlink (7)