lib/libc/sys/chmod.2

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd March 30, 2021
  29 .Dt CHMOD 2
  30 .Os
  31 .Sh NAME
  32 .Nm chmod ,
  33 .Nm fchmod ,
  34 .Nm lchmod ,
  35 .Nm fchmodat
  36 .Nd change mode of file
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/stat.h
  41 .Ft int
  42 .Fn chmod "const char *path" "mode_t mode"
  43 .Ft int
  44 .Fn fchmod "int fd" "mode_t mode"
  45 .Ft int
  46 .Fn lchmod "const char *path" "mode_t mode"
  47 .Ft int
  48 .Fn fchmodat "int fd" "const char *path" "mode_t mode" "int flag"
  49 .Sh DESCRIPTION
  50 The file permission bits of the file named specified by
  51 .Fa path
  52 or referenced by the file descriptor
  53 .Fa fd
  54 are changed to
  55 .Fa mode .
  56 The
  57 .Fn chmod
  58 system call verifies that the process owner (user) either owns
  59 the file specified by
  60 .Fa path
  61 (or
  62 .Fa fd ) ,
  63 or
  64 is the super-user.
  65 The
  66 .Fn chmod
  67 system call follows symbolic links to operate on the target of the link
  68 rather than the link itself.
  69 .Pp
  70 The
  71 .Fn lchmod
  72 system call is similar to
  73 .Fn chmod
  74 but does not follow symbolic links.
  75 .Pp
  76 The
  77 .Fn fchmodat
  78 is equivalent to either
  79 .Fn chmod
  80 or
  81 .Fn lchmod
  82 depending on the
  83 .Fa flag
  84 except in the case where
  85 .Fa path
  86 specifies a relative path.
  87 In this case the file to be changed is determined relative to the directory
  88 associated with the file descriptor
  89 .Fa fd
  90 instead of the current working directory.
  91 The values for the
  92 .Fa flag
  93 are constructed by a bitwise-inclusive OR of flags from the following list, defined
  94 in
  95 .In fcntl.h :
  96 .Bl -tag -width indent
  97 .It Dv AT_SYMLINK_NOFOLLOW
  98 If
  99 .Fa path
 100 names a symbolic link, then the mode of the symbolic link is changed.
 101 .It Dv AT_RESOLVE_BENEATH
 102 Only walk paths below the directory specified by the
 103 .Ar fd
 104 descriptor.
 105 See the description of the
 106 .Dv O_RESOLVE_BENEATH
 107 flag in the
 108 .Xr open 2
 109 manual page.
 110 .It Dv AT_EMPTY_PATH
 111 If the
 112 .Fa path
 113 argument is an empty string, operate on the file or directory
 114 referenced by the descriptor
 115 .Fa fd .
 116 If
 117 .Fa fd
 118 is equal to
 119 .Dv AT_FDCWD ,
 120 operate on the current working directory.
 121 .El
 122 .Pp
 123 If
 124 .Fn fchmodat
 125 is passed the special value
 126 .Dv AT_FDCWD
 127 in the
 128 .Fa fd
 129 parameter, the current working directory is used.
 130 If also
 131 .Fa flag
 132 is zero, the behavior is identical to a call to
 133 .Fn chmod .
 134 .Pp
 135 A mode is created from
 136 .Em or'd
 137 permission bit masks
 138 defined in
 139 .In sys/stat.h :
 140 .Pp
 141 .Bd -literal -offset indent -compact
 142 #define S_IRWXU 0000700    /* RWX mask for owner */
 143 #define S_IRUSR 0000400    /* R for owner */
 144 #define S_IWUSR 0000200    /* W for owner */
 145 #define S_IXUSR 0000100    /* X for owner */
 146
 147 #define S_IRWXG 0000070    /* RWX mask for group */
 148 #define S_IRGRP 0000040    /* R for group */
 149 #define S_IWGRP 0000020    /* W for group */
 150 #define S_IXGRP 0000010    /* X for group */
 151
 152 #define S_IRWXO 0000007    /* RWX mask for other */
 153 #define S_IROTH 0000004    /* R for other */
 154 #define S_IWOTH 0000002    /* W for other */
 155 #define S_IXOTH 0000001    /* X for other */
 156
 157 #define S_ISUID 0004000    /* set user id on execution */
 158 #define S_ISGID 0002000    /* set group id on execution */
 159 #define S_ISVTX 0001000    /* sticky bit */
 160 .Ed
 161 .Pp
 162 The non-standard
 163 .Dv S_ISTXT
 164 is a synonym for
 165 .Dv S_ISVTX .
 166 .Pp
 167 The
 168 .Fx
 169 VM system totally ignores the sticky bit
 170 .Pq Dv S_ISVTX
 171 for executables.
 172 On UFS-based file systems (FFS, LFS) the sticky
 173 bit may only be set upon directories.
 174 .Pp
 175 If mode
 176 .Dv S_ISVTX
 177 (the `sticky bit') is set on a directory,
 178 an unprivileged user may not delete or rename
 179 files of other users in that directory.
 180 The sticky bit may be
 181 set by any user on a directory which the user owns or has appropriate
 182 permissions.
 183 For more details of the properties of the sticky bit, see
 184 .Xr sticky 7 .
 185 .Pp
 186 If mode ISUID (set UID) is set on a directory,
 187 and the MNT_SUIDDIR option was used in the mount of the file system,
 188 then the owner of any new files and sub-directories
 189 created within this directory are set
 190 to be the same as the owner of that directory.
 191 If this function is enabled, new directories will inherit
 192 the bit from their parents.
 193 Execute bits are removed from
 194 the file, and it will not be given to root.
 195 This behavior does not change the
 196 requirements for the user to be allowed to write the file, but only the eventual
 197 owner after it has been created.
 198 Group inheritance is not affected.
 199 .Pp
 200 This feature is designed for use on fileservers serving PC users via
 201 ftp, SAMBA, or netatalk.
 202 It provides security holes for shell users and as
 203 such should not be used on shell machines, especially on home directories.
 204 This option requires the SUIDDIR
 205 option in the kernel to work.
 206 Only UFS file systems support this option.
 207 For more details of the suiddir mount option, see
 208 .Xr mount 8 .
 209 .Pp
 210 Writing or changing the owner of a file
 211 turns off the set-user-id and set-group-id bits
 212 unless the user is the super-user.
 213 This makes the system somewhat more secure
 214 by protecting set-user-id (set-group-id) files
 215 from remaining set-user-id (set-group-id) if they are modified,
 216 at the expense of a degree of compatibility.
 217 .Sh RETURN VALUES
 218 .Rv -std
 219 .Sh ERRORS
 220 The
 221 .Fn chmod
 222 system call
 223 will fail and the file mode will be unchanged if:
 224 .Bl -tag -width Er
 225 .It Bq Er ENOTDIR
 226 A component of the path prefix is not a directory.
 227 .It Bq Er ENAMETOOLONG
 228 A component of a pathname exceeded 255 characters,
 229 or an entire path name exceeded 1023 characters.
 230 .It Bq Er ENOENT
 231 The named file does not exist.
 232 .It Bq Er EACCES
 233 Search permission is denied for a component of the path prefix.
 234 .It Bq Er ELOOP
 235 Too many symbolic links were encountered in translating the pathname.
 236 .It Bq Er EPERM
 237 The effective user ID does not match the owner of the file and
 238 the effective user ID is not the super-user.
 239 .It Bq Er EPERM
 240 The effective user ID is not the super-user, the effective user ID do match the
 241 owner of the file, but the group ID of the file does not match the effective
 242 group ID nor one of the supplementary group IDs.
 243 .It Bq Er EPERM
 244 The named file has its immutable or append-only flag set, see the
 245 .Xr chflags 2
 246 manual page for more information.
 247 .It Bq Er EROFS
 248 The named file resides on a read-only file system.
 249 .It Bq Er EFAULT
 250 The
 251 .Fa path
 252 argument
 253 points outside the process's allocated address space.
 254 .It Bq Er EIO
 255 An I/O error occurred while reading from or writing to the file system.
 256 .It Bq Er EINTEGRITY
 257 Corrupted data was detected while reading from the file system.
 258 .It Bq Er EFTYPE
 259 The effective user ID is not the super-user, the mode includes the sticky bit
 260 .Dv ( S_ISVTX ) ,
 261 and path does not refer to a directory.
 262 .El
 263 .Pp
 264 The
 265 .Fn fchmod
 266 system call will fail if:
 267 .Bl -tag -width Er
 268 .It Bq Er EBADF
 269 The descriptor is not valid.
 270 .It Bq Er EINVAL
 271 The
 272 .Fa fd
 273 argument
 274 refers to a socket, not to a file.
 275 .It Bq Er EROFS
 276 The file resides on a read-only file system.
 277 .It Bq Er EIO
 278 An I/O error occurred while reading from or writing to the file system.
 279 .It Bq Er EINTEGRITY
 280 Corrupted data was detected while reading from the file system.
 281 .El
 282 .Pp
 283 In addition to the
 284 .Fn chmod
 285 errors,
 286 .Fn fchmodat
 287 fails if:
 288 .Bl -tag -width Er
 289 .It Bq Er EBADF
 290 The
 291 .Fa path
 292 argument does not specify an absolute path and the
 293 .Fa fd
 294 argument is neither
 295 .Fa AT_FDCWD
 296 nor a valid file descriptor open for searching.
 297 .It Bq Er EINVAL
 298 The value of the
 299 .Fa flag
 300 argument is not valid.
 301 .It Bq Er ENOTDIR
 302 The
 303 .Fa path
 304 argument is not an absolute path and
 305 .Fa fd
 306 is neither
 307 .Dv AT_FDCWD
 308 nor a file descriptor associated with a directory.
 309 .It Bq Er ENOTCAPABLE
 310 .Fa path
 311 is an absolute path,
 312 or contained a ".." component leading to a
 313 directory outside of the directory hierarchy specified by
 314 .Fa fd ,
 315 and the process is in capability mode or the
 316 .Dv AT_RESOLVE_BENEATH
 317 flag was specified.
 318 .El
 319 .Sh SEE ALSO
 320 .Xr chmod 1 ,
 321 .Xr chflags 2 ,
 322 .Xr chown 2 ,
 323 .Xr open 2 ,
 324 .Xr stat 2 ,
 325 .Xr sticky 7
 326 .Sh STANDARDS
 327 The
 328 .Fn chmod
 329 system call is expected to conform to
 330 .St -p1003.1-90 ,
 331 except for the return of
 332 .Er EFTYPE .
 333 The
 334 .Dv S_ISVTX
 335 bit on directories is expected to conform to
 336 .St -susv3 .
 337 The
 338 .Fn fchmodat
 339 system call is expected to conform to
 340 .St -p1003.1-2008 .
 341 .Sh HISTORY
 342 The
 343 .Fn chmod
 344 function appeared in
 345 .At v1 .
 346 The
 347 .Fn fchmod
 348 system call appeared in
 349 .Bx 4.2 .
 350 The
 351 .Fn lchmod
 352 system call appeared in
 353 .Fx 3.0 .
 354 The
 355 .Fn fchmodat
 356 system call appeared in
 357 .Fx 8.0 .