original/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 2014-08-19 "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 _BSD_SOURCE ||
  60 _XOPEN_SOURCE\ >=\ 500 ||
  61 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  62 .br
  63 || /* Since glibc 2.12: */ _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 _XOPEN_SOURCE\ >=\ 700 || _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 the permissions of a file.
  87 They differ only in how the file is specified:
  88 .IP * 2
  89 .BR chmod ()
  90 changes the permissions of the file specified whose pathname is given in
  91 .IR pathname ,
  92 which is dereferenced if it is a symbolic link.
  93 .IP *
  94 .BR fchmod ()
  95 changes the permissions of the file referred to by the open file descriptor
  96 .IR fd .
  97 .PP
  98 The new file permissions are specified in
  99 .IR mode ,
 100 which is a bit mask created by ORing together zero or
 101 more of the following:
 102 .TP 18
 103 .BR S_ISUID "  (04000)"
 104 set-user-ID (set process effective user ID on
 105 .BR execve (2))
 106 .TP
 107 .BR S_ISGID "  (02000)"
 108 set-group-ID (set process effective group ID on
 109 .BR execve (2);
 110 mandatory locking, as described in
 111 .BR fcntl (2);
 112 take a new file's group from parent directory, as described in
 113 .BR chown (2)
 114 and
 115 .BR mkdir (2))
 116 .TP
 117 .BR S_ISVTX "  (01000)"
 118 sticky bit (restricted deletion flag, as described in
 119 .BR unlink (2))
 120 .TP
 121 .BR S_IRUSR "  (00400)"
 122 read by owner
 123 .TP
 124 .BR S_IWUSR "  (00200)"
 125 write by owner
 126 .TP
 127 .BR S_IXUSR "  (00100)"
 128 execute/search by owner ("search" applies for directories,
 129 and means that entries within the directory can be accessed)
 130 .TP
 131 .BR S_IRGRP "  (00040)"
 132 read by group
 133 .TP
 134 .BR S_IWGRP "  (00020)"
 135 write by group
 136 .TP
 137 .BR S_IXGRP "  (00010)"
 138 execute/search by group
 139 .TP
 140 .BR S_IROTH "  (00004)"
 141 read by others
 142 .TP
 143 .BR S_IWOTH "  (00002)"
 144 write by others
 145 .TP
 146 .BR S_IXOTH "  (00001)"
 147 execute/search by others
 148 .PP
 149 The effective UID of the calling process must match the owner of the file,
 150 or the process must be privileged (Linux: it must have the
 151 .B CAP_FOWNER
 152 capability).
 153
 154 If the calling process is not privileged (Linux: does not have the
 155 .B CAP_FSETID
 156 capability), and the group of the file does not match
 157 the effective group ID of the process or one of its
 158 supplementary group IDs, the
 159 .B S_ISGID
 160 bit will be turned off,
 161 but this will not cause an error to be returned.
 162
 163 As a security measure, depending on the filesystem,
 164 the set-user-ID and set-group-ID execution bits
 165 may be turned off if a file is written.
 166 (On Linux this occurs if the writing process does not have the
 167 .B CAP_FSETID
 168 capability.)
 169 On some filesystems, only the superuser can set the sticky bit,
 170 which may have a special meaning.
 171 For the sticky bit, and for set-user-ID and set-group-ID bits on
 172 directories, see
 173 .BR stat (2).
 174
 175 On NFS filesystems, restricting the permissions will immediately influence
 176 already open files, because the access control is done on the server, but
 177 open files are maintained by the client.
 178 Widening the permissions may be
 179 delayed for other clients if attribute caching is enabled on them.
 180 .\"
 181 .\"
 182 .SS fchmodat()
 183 The
 184 .BR fchmodat ()
 185 system call operates in exactly the same way as
 186 .BR chmod (),
 187 except for the differences described here.
 188
 189 If the pathname given in
 190 .I pathname
 191 is relative, then it is interpreted relative to the directory
 192 referred to by the file descriptor
 193 .I dirfd
 194 (rather than relative to the current working directory of
 195 the calling process, as is done by
 196 .BR chmod ()
 197 for a relative pathname).
 198
 199 If
 200 .I pathname
 201 is relative and
 202 .I dirfd
 203 is the special value
 204 .BR AT_FDCWD ,
 205 then
 206 .I pathname
 207 is interpreted relative to the current working
 208 directory of the calling process (like
 209 .BR chmod ()).
 210
 211 If
 212 .I pathname
 213 is absolute, then
 214 .I dirfd
 215 is ignored.
 216
 217 .I flags
 218 can either be 0, or include the following flag:
 219 .TP
 220 .B AT_SYMLINK_NOFOLLOW
 221 If
 222 .I pathname
 223 is a symbolic link, do not dereference it:
 224 instead operate on the link itself.
 225 This flag is not currently implemented.
 226 .PP
 227 See
 228 .BR openat (2)
 229 for an explanation of the need for
 230 .BR fchmodat ().
 231 .SH RETURN VALUE
 232 On success, zero is returned.
 233 On error, \-1 is returned, and
 234 .I errno
 235 is set appropriately.
 236 .SH ERRORS
 237 Depending on the filesystem,
 238 errors other than those listed below can be returned.
 239
 240 The more general errors for
 241 .BR chmod ()
 242 are listed below:
 243 .TP
 244 .B EACCES
 245 Search permission is denied on a component of the path prefix.
 246 (See also
 247 .BR path_resolution (7).)
 248 .TP
 249 .B EFAULT
 250 .I pathname
 251 points outside your accessible address space.
 252 .TP
 253 .B EIO
 254 An I/O error occurred.
 255 .TP
 256 .B ELOOP
 257 Too many symbolic links were encountered in resolving
 258 .IR pathname .
 259 .TP
 260 .B ENAMETOOLONG
 261 .I pathname
 262 is too long.
 263 .TP
 264 .B ENOENT
 265 The file does not exist.
 266 .TP
 267 .B ENOMEM
 268 Insufficient kernel memory was available.
 269 .TP
 270 .B ENOTDIR
 271 A component of the path prefix is not a directory.
 272 .TP
 273 .B EPERM
 274 The effective UID does not match the owner of the file,
 275 and the process is not privileged (Linux: it does not have the
 276 .B CAP_FOWNER
 277 capability).
 278 .TP
 279 .B EROFS
 280 The named file resides on a read-only filesystem.
 281 .PP
 282 The general errors for
 283 .BR fchmod ()
 284 are listed below:
 285 .TP
 286 .B EBADF
 287 The file descriptor
 288 .I fd
 289 is not valid.
 290 .TP
 291 .B EIO
 292 See above.
 293 .TP
 294 .B EPERM
 295 See above.
 296 .TP
 297 .B EROFS
 298 See above.
 299 .PP
 300 The same errors that occur for
 301 .BR chmod ()
 302 can also occur for
 303 .BR fchmodat ().
 304 The following additional errors can occur for
 305 .BR fchmodat ():
 306 .TP
 307 .B EBADF
 308 .I dirfd
 309 is not a valid file descriptor.
 310 .TP
 311 .B EINVAL
 312 Invalid flag specified in
 313 .IR flags .
 314 .TP
 315 .B ENOTDIR
 316 .I pathname
 317 is relative and
 318 .I dirfd
 319 is a file descriptor referring to a file other than a directory.
 320 .TP
 321 .B ENOTSUP
 322 .I flags
 323 specified
 324 .BR AT_SYMLINK_NOFOLLOW ,
 325 which is not supported.
 326 .SH VERSIONS
 327 .BR fchmodat ()
 328 was added to Linux in kernel 2.6.16;
 329 library support was added to glibc in version 2.4.
 330 .SH CONFORMING TO
 331 .BR chmod (),
 332 .BR fchmod ():
 333 4.4BSD, SVr4, POSIX.1-2001i, POSIX.1-2008.
 334
 335 .BR fchmodat ():
 336 POSIX.1-2008.
 337 .SH NOTES
 338 .SS C library/kernel ABI differences
 339 The GNU C library
 340 .BR fchmodat ()
 341 wrapper function implements the POSIX-specified
 342 interface described in this page.
 343 This interface differs from the underlying Linux system call, which does
 344 .I not
 345 have a
 346 .I flags
 347 argument.
 348 .SS Glibc notes
 349 On older kernels where
 350 .BR fchmodat ()
 351 is unavailable, the glibc wrapper function falls back to the use of
 352 .BR chmod ().
 353 When
 354 .I pathname
 355 is a relative pathname,
 356 glibc constructs a pathname based on the symbolic link in
 357 .IR /proc/self/fd
 358 that corresponds to the
 359 .IR dirfd
 360 argument.
 361 .SH SEE ALSO
 362 .BR chown (2),
 363 .BR execve (2),
 364 .BR open (2),
 365 .BR stat (2),
 366 .BR path_resolution (7),
 367 .BR symlink (7)
 368 .SH COLOPHON
 369 This page is part of release 3.79 of the Linux
 370 .I man-pages
 371 project.
 372 A description of the project,
 373 information about reporting bugs,
 374 and the latest version of this page,
 375 can be found at
 376 \%http://www.kernel.org/doc/man\-pages/.