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