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 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified by Michael Haardt <michael@moria.de>
  27 .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
  28 .\" Modified 1997-01-12 by Michael Haardt
  29 .\"   <michael@cantor.informatik.rwth-aachen.de>: NFS details
  30 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\"
  32 .TH CHMOD 2 2016-03-15 "Linux" "Linux Programmer's Manual"
  33 .SH NAME
  34 chmod, fchmod, fchmodat \- change permissions of a file
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <sys/stat.h>
  38 .sp
  39 .BI "int chmod(const char *" pathname ", mode_t " mode );
  40 .br
  41 .BI "int fchmod(int " fd ", mode_t " mode );
  42 .sp
  43 .BR "#include <fcntl.h>" "           /* Definition of AT_* constants */"
  44 .B #include <sys/stat.h>
  45 .sp
  46 .BI "int fchmodat(int " dirfd ", const char *" pathname ", mode_t " \
  47 mode ", int " flags );
  48 .fi
  49 .sp
  50 .in -4n
  51 Feature Test Macro Requirements for glibc (see
  52 .BR feature_test_macros (7)):
  53 .in
  54 .sp
  55 .ad l
  56 .PD 0
  57 .BR fchmod ():
  58 .RS 4
  59 /* Since glibc 2.16: */ _POSIX_C_SOURCE
  60     || /* Glibc versions <= 2.19: */ _BSD_SOURCE
  61     || /* Glibc versions <= 2.15: */ _XOPEN_SOURCE\ >=\ 500
  62 .\"    || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  63     || /* Glibc 2.12 to 2.15: */ _POSIX_C_SOURCE\ >=\ 200809L
  64 .RE
  65 .PD
  66 .sp
  67 .BR fchmodat ():
  68 .PD 0
  69 .ad l
  70 .RS 4
  71 .TP 4
  72 Since glibc 2.10:
  73 _POSIX_C_SOURCE\ >=\ 200809L
  74 .TP
  75 Before glibc 2.10:
  76 _ATFILE_SOURCE
  77 .RE
  78 .ad
  79 .PD
  80 .ad
  81 .SH DESCRIPTION
  82 The
  83 .BR chmod ()
  84 and
  85 .BR fchmod ()
  86 system calls change a files mode bits.
  87 (The file mode consists of the file permission bits plus the set-user-ID,
  88 set-group-ID, and sticky bits.)
  89 These system calls differ only in how the file is specified:
  90 .IP * 2
  91 .BR chmod ()
  92 changes the mode of the file specified whose pathname is given in
  93 .IR pathname ,
  94 which is dereferenced if it is a symbolic link.
  95 .IP *
  96 .BR fchmod ()
  97 changes the mode of the file referred to by the open file descriptor
  98 .IR fd .
  99 .PP
 100 The new file mode is specified in
 101 .IR mode ,
 102 which is a bit mask created by ORing together zero or
 103 more of the following:
 104 .TP 18
 105 .BR S_ISUID "  (04000)"
 106 set-user-ID (set process effective user ID on
 107 .BR execve (2))
 108 .TP
 109 .BR S_ISGID "  (02000)"
 110 set-group-ID (set process effective group ID on
 111 .BR execve (2);
 112 mandatory locking, as described in
 113 .BR fcntl (2);
 114 take a new file's group from parent directory, as described in
 115 .BR chown (2)
 116 and
 117 .BR mkdir (2))
 118 .TP
 119 .BR S_ISVTX "  (01000)"
 120 sticky bit (restricted deletion flag, as described in
 121 .BR unlink (2))
 122 .TP
 123 .BR S_IRUSR "  (00400)"
 124 read by owner
 125 .TP
 126 .BR S_IWUSR "  (00200)"
 127 write by owner
 128 .TP
 129 .BR S_IXUSR "  (00100)"
 130 execute/search by owner ("search" applies for directories,
 131 and means that entries within the directory can be accessed)
 132 .TP
 133 .BR S_IRGRP "  (00040)"
 134 read by group
 135 .TP
 136 .BR S_IWGRP "  (00020)"
 137 write by group
 138 .TP
 139 .BR S_IXGRP "  (00010)"
 140 execute/search by group
 141 .TP
 142 .BR S_IROTH "  (00004)"
 143 read by others
 144 .TP
 145 .BR S_IWOTH "  (00002)"
 146 write by others
 147 .TP
 148 .BR S_IXOTH "  (00001)"
 149 execute/search by others
 150 .PP
 151 The effective UID of the calling process must match the owner of the file,
 152 or the process must be privileged (Linux: it must have the
 153 .B CAP_FOWNER
 154 capability).
 155
 156 If the calling process is not privileged (Linux: does not have the
 157 .B CAP_FSETID
 158 capability), and the group of the file does not match
 159 the effective group ID of the process or one of its
 160 supplementary group IDs, the
 161 .B S_ISGID
 162 bit will be turned off,
 163 but this will not cause an error to be returned.
 164
 165 As a security measure, depending on the filesystem,
 166 the set-user-ID and set-group-ID execution bits
 167 may be turned off if a file is written.
 168 (On Linux, this occurs if the writing process does not have the
 169 .B CAP_FSETID
 170 capability.)
 171 On some filesystems, only the superuser can set the sticky bit,
 172 which may have a special meaning.
 173 For the sticky bit, and for set-user-ID and set-group-ID bits on
 174 directories, see
 175 .BR stat (2).
 176
 177 On NFS filesystems, restricting the permissions will immediately influence
 178 already open files, because the access control is done on the server, but
 179 open files are maintained by the client.
 180 Widening the permissions may be
 181 delayed for other clients if attribute caching is enabled on them.
 182 .\"
 183 .\"
 184 .SS fchmodat()
 185 The
 186 .BR fchmodat ()
 187 system call operates in exactly the same way as
 188 .BR chmod (),
 189 except for the differences described here.
 190
 191 If the pathname given in
 192 .I pathname
 193 is relative, then it is interpreted relative to the directory
 194 referred to by the file descriptor
 195 .I dirfd
 196 (rather than relative to the current working directory of
 197 the calling process, as is done by
 198 .BR chmod ()
 199 for a relative pathname).
 200
 201 If
 202 .I pathname
 203 is relative and
 204 .I dirfd
 205 is the special value
 206 .BR AT_FDCWD ,
 207 then
 208 .I pathname
 209 is interpreted relative to the current working
 210 directory of the calling process (like
 211 .BR chmod ()).
 212
 213 If
 214 .I pathname
 215 is absolute, then
 216 .I dirfd
 217 is ignored.
 218
 219 .I flags
 220 can either be 0, or include the following flag:
 221 .TP
 222 .B AT_SYMLINK_NOFOLLOW
 223 If
 224 .I pathname
 225 is a symbolic link, do not dereference it:
 226 instead operate on the link itself.
 227 This flag is not currently implemented.
 228 .PP
 229 See
 230 .BR openat (2)
 231 for an explanation of the need for
 232 .BR fchmodat ().
 233 .SH RETURN VALUE
 234 On success, zero is returned.
 235 On error, \-1 is returned, and
 236 .I errno
 237 is set appropriately.
 238 .SH ERRORS
 239 Depending on the filesystem,
 240 errors other than those listed below can be returned.
 241
 242 The more general errors for
 243 .BR chmod ()
 244 are listed below:
 245 .TP
 246 .B EACCES
 247 Search permission is denied on a component of the path prefix.
 248 (See also
 249 .BR path_resolution (7).)
 250 .TP
 251 .B EFAULT
 252 .I pathname
 253 points outside your accessible address space.
 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 EPERM
 276 The effective UID does not match the owner of the file,
 277 and the process is not privileged (Linux: it does not have the
 278 .B CAP_FOWNER
 279 capability).
 280 .TP
 281 .B EROFS
 282 The named file resides on a read-only filesystem.
 283 .PP
 284 The general errors for
 285 .BR fchmod ()
 286 are listed below:
 287 .TP
 288 .B EBADF
 289 The file descriptor
 290 .I fd
 291 is not valid.
 292 .TP
 293 .B EIO
 294 See above.
 295 .TP
 296 .B EPERM
 297 See above.
 298 .TP
 299 .B EROFS
 300 See above.
 301 .PP
 302 The same errors that occur for
 303 .BR chmod ()
 304 can also occur for
 305 .BR fchmodat ().
 306 The following additional errors can occur for
 307 .BR fchmodat ():
 308 .TP
 309 .B EBADF
 310 .I dirfd
 311 is not a valid file descriptor.
 312 .TP
 313 .B EINVAL
 314 Invalid flag specified in
 315 .IR flags .
 316 .TP
 317 .B ENOTDIR
 318 .I pathname
 319 is relative and
 320 .I dirfd
 321 is a file descriptor referring to a file other than a directory.
 322 .TP
 323 .B ENOTSUP
 324 .I flags
 325 specified
 326 .BR AT_SYMLINK_NOFOLLOW ,
 327 which is not supported.
 328 .SH VERSIONS
 329 .BR fchmodat ()
 330 was added to Linux in kernel 2.6.16;
 331 library support was added to glibc in version 2.4.
 332 .SH CONFORMING TO
 333 .BR chmod (),
 334 .BR fchmod ():
 335 4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008.
 336
 337 .BR fchmodat ():
 338 POSIX.1-2008.
 339 .SH NOTES
 340 .SS C library/kernel differences
 341 The GNU C library
 342 .BR fchmodat ()
 343 wrapper function implements the POSIX-specified
 344 interface described in this page.
 345 This interface differs from the underlying Linux system call, which does
 346 .I not
 347 have a
 348 .I flags
 349 argument.
 350 .SS Glibc notes
 351 On older kernels where
 352 .BR fchmodat ()
 353 is unavailable, the glibc wrapper function falls back to the use of
 354 .BR chmod ().
 355 When
 356 .I pathname
 357 is a relative pathname,
 358 glibc constructs a pathname based on the symbolic link in
 359 .IR /proc/self/fd
 360 that corresponds to the
 361 .IR dirfd
 362 argument.
 363 .SH SEE ALSO
 364 .BR chmod (1),
 365 .BR chown (2),
 366 .BR execve (2),
 367 .BR open (2),
 368 .BR stat (2),
 369 .BR path_resolution (7),
 370 .BR symlink (7)