lib/libc/sys/open.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 .\"     @(#)open.2      8.2 (Berkeley) 11/16/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 23, 2020
  32 .Dt OPEN 2
  33 .Os
  34 .Sh NAME
  35 .Nm open , openat
  36 .Nd open or create a file for reading, writing or executing
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In fcntl.h
  41 .Ft int
  42 .Fn open "const char *path" "int flags" "..."
  43 .Ft int
  44 .Fn openat "int fd" "const char *path" "int flags" "..."
  45 .Sh DESCRIPTION
  46 The file name specified by
  47 .Fa path
  48 is opened
  49 for either execution or reading and/or writing as specified by the
  50 argument
  51 .Fa flags
  52 and the file descriptor returned to the calling process.
  53 The
  54 .Fa flags
  55 argument may indicate the file is to be
  56 created if it does not exist (by specifying the
  57 .Dv O_CREAT
  58 flag).
  59 In this case
  60 .Fn open
  61 and
  62 .Fn openat
  63 require an additional argument
  64 .Fa "mode_t mode" ,
  65 and the file is created with mode
  66 .Fa mode
  67 as described in
  68 .Xr chmod 2
  69 and modified by the process' umask value (see
  70 .Xr umask 2 ) .
  71 .Pp
  72 The
  73 .Fn openat
  74 function is equivalent to the
  75 .Fn open
  76 function except in the case where the
  77 .Fa path
  78 specifies a relative path, or the
  79 .Dv O_BENEATH
  80 flag is provided.
  81 For
  82 .Fn openat
  83 and relative
  84 .Fa path ,
  85 the file to be opened is determined relative to the directory
  86 associated with the file descriptor
  87 .Fa fd
  88 instead of the current working directory.
  89 The
  90 .Fa flag
  91 parameter and the optional fourth parameter correspond exactly to
  92 the parameters of
  93 .Fn open .
  94 If
  95 .Fn openat
  96 is passed the special value
  97 .Dv AT_FDCWD
  98 in the
  99 .Fa fd
 100 parameter, the current working directory is used
 101 and the behavior is identical to a call to
 102 .Fn open .
 103 .Pp
 104 When
 105 .Fn openat
 106 is called with an absolute
 107 .Fa path
 108 without the
 109 .Dv O_BENEATH
 110 flag, it ignores the
 111 .Fa fd
 112 argument.
 113 When
 114 .Dv O_BENEATH
 115 is specified with an absolute
 116 .Fa path ,
 117 a directory passed by the
 118 .Fa fd
 119 argument is used as the topping point for the resolution.
 120 When
 121 .Dv O_BENEATH
 122 is specified with a relative path, the
 123 .Fa fd
 124 argument is used both as the starting point, and as the topping point
 125 for the resolution.
 126 See the definition of the
 127 .Dv O_BENEATH
 128 flag below.
 129 .Pp
 130 In
 131 .Xr capsicum 4
 132 capability mode,
 133 .Fn open
 134 is not permitted.
 135 The
 136 .Fa path
 137 argument to
 138 .Fn openat
 139 must be strictly relative to a file descriptor
 140 .Fa fd ,
 141 as defined in
 142 .Pa sys/kern/vfs_lookup.c .
 143 .Fa path
 144 must not be an absolute path and must not contain ".." components
 145 which cause the path resolution to escape the directory hierarchy
 146 starting at
 147 .Fa fd .
 148 Additionally, no symbolic link in
 149 .Fa path
 150 may target absolute path or contain escaping ".." components.
 151 .Fa fd
 152 must not be
 153 .Dv AT_FDCWD .
 154 .Pp
 155 If the
 156 .Dv vfs.lookup_cap_dotdot
 157 .Xr sysctl 3
 158 MIB is set to zero, ".." components in the paths,
 159 used in capability mode, or with the
 160 .Dv O_BENEATH
 161 flag, are completely disabled.
 162 If the
 163 .Dv vfs.lookup_cap_dotdot_nonlocal
 164 MIB is set to zero, ".." is not allowed if found on non-local filesystem.
 165 .Pp
 166 The flags specified are formed by
 167 .Em or Ns 'ing
 168 the following values
 169 .Pp
 170 .Bd -literal -offset indent -compact
 171 O_RDONLY        open for reading only
 172 O_WRONLY        open for writing only
 173 O_RDWR          open for reading and writing
 174 O_EXEC          open for execute only
 175 O_SEARCH        open for search only, an alias for O_EXEC
 176 O_NONBLOCK      do not block on open
 177 O_APPEND        append on each write
 178 O_CREAT         create file if it does not exist
 179 O_TRUNC         truncate size to 0
 180 O_EXCL          error if create and file exists
 181 O_SHLOCK        atomically obtain a shared lock
 182 O_EXLOCK        atomically obtain an exclusive lock
 183 O_DIRECT        eliminate or reduce cache effects
 184 O_FSYNC         synchronous writes
 185 O_SYNC          synchronous writes
 186 O_NOFOLLOW      do not follow symlinks
 187 O_NOCTTY        ignored
 188 O_TTY_INIT      ignored
 189 O_DIRECTORY     error if file is not a directory
 190 O_CLOEXEC       set FD_CLOEXEC upon open
 191 O_VERIFY        verify the contents of the file
 192 O_BENEATH       require resolved path to be strictly relative to topping directory
 193 O_RESOLVE_BENEATH       require walked path to be strictly relative to topping directory
 194 .Ed
 195 .Pp
 196 Opening a file with
 197 .Dv O_APPEND
 198 set causes each write on the file
 199 to be appended to the end.
 200 If
 201 .Dv O_TRUNC
 202 is specified and the
 203 file exists, the file is truncated to zero length.
 204 If
 205 .Dv O_EXCL
 206 is set with
 207 .Dv O_CREAT
 208 and the file already
 209 exists,
 210 .Fn open
 211 returns an error.
 212 This may be used to
 213 implement a simple exclusive access locking mechanism.
 214 If
 215 .Dv O_EXCL
 216 is set and the last component of the pathname is
 217 a symbolic link,
 218 .Fn open
 219 will fail even if the symbolic
 220 link points to a non-existent name.
 221 If the
 222 .Dv O_NONBLOCK
 223 flag is specified and the
 224 .Fn open
 225 system call would result
 226 in the process being blocked for some reason (e.g., waiting for
 227 carrier on a dialup line),
 228 .Fn open
 229 returns immediately.
 230 The descriptor remains in non-blocking mode for subsequent operations.
 231 .Pp
 232 If
 233 .Dv O_FSYNC
 234 is used in the mask, all writes will
 235 immediately and synchronously be written to disk.
 236 .Pp
 237 .Dv O_SYNC
 238 is a synonym for
 239 .Dv O_FSYNC
 240 required by
 241 .Tn POSIX .
 242 .Pp
 243 If
 244 .Dv O_NOFOLLOW
 245 is used in the mask and the target file passed to
 246 .Fn open
 247 is a symbolic link then the
 248 .Fn open
 249 will fail.
 250 .Pp
 251 When opening a file, a lock with
 252 .Xr flock 2
 253 semantics can be obtained by setting
 254 .Dv O_SHLOCK
 255 for a shared lock, or
 256 .Dv O_EXLOCK
 257 for an exclusive lock.
 258 If creating a file with
 259 .Dv O_CREAT ,
 260 the request for the lock will never fail
 261 (provided that the underlying file system supports locking).
 262 .Pp
 263 .Dv O_DIRECT
 264 may be used to minimize or eliminate the cache effects of reading and writing.
 265 The system will attempt to avoid caching the data you read or write.
 266 If it cannot avoid caching the data,
 267 it will minimize the impact the data has on the cache.
 268 Use of this flag can drastically reduce performance if not used with care.
 269 .Pp
 270 .Dv O_NOCTTY
 271 may be used to ensure the OS does not assign this file as the
 272 controlling terminal when it opens a tty device.
 273 This is the default on
 274 .Fx ,
 275 but is present for
 276 .Tn POSIX
 277 compatibility.
 278 The
 279 .Fn open
 280 system call will not assign controlling terminals on
 281 .Fx .
 282 .Pp
 283 .Dv O_TTY_INIT
 284 may be used to ensure the OS restores the terminal attributes when
 285 initially opening a TTY.
 286 This is the default on
 287 .Fx ,
 288 but is present for
 289 .Tn POSIX
 290 compatibility.
 291 The initial call to
 292 .Fn open
 293 on a TTY will always restore default terminal attributes on
 294 .Fx .
 295 .Pp
 296 .Dv O_DIRECTORY
 297 may be used to ensure the resulting file descriptor refers to a
 298 directory.
 299 This flag can be used to prevent applications with elevated privileges
 300 from opening files which are even unsafe to open with
 301 .Dv O_RDONLY ,
 302 such as device nodes.
 303 .Pp
 304 .Dv O_CLOEXEC
 305 may be used to set
 306 .Dv FD_CLOEXEC
 307 flag for the newly returned file descriptor.
 308 .Pp
 309 .Dv O_VERIFY
 310 may be used to indicate to the kernel that the contents of the file should
 311 be verified before allowing the open to proceed.
 312 The details of what
 313 .Dq verified
 314 means is implementation specific.
 315 The run-time linker (rtld) uses this flag to ensure shared objects have
 316 been verified before operating on them.
 317 .Pp
 318 .Dv O_BENEATH
 319 returns
 320 .Er ENOTCAPABLE
 321 if the specified path, after resolving all symlinks and ".."
 322 references, does not end up with tail residing in the directory hierarchy of
 323 children beneath the topping directory.
 324 Topping directory is the process current directory if relative
 325 .Fa path
 326 is used for
 327 .Fn open ,
 328 and the directory referenced by the
 329 .Fa fd
 330 argument when using
 331 .Fn openat .
 332 .Dv O_BENEATH
 333 allows arbitrary prefix that ends up at the topping directory,
 334 after which all further resolved components must be under it.
 335 .Pp
 336 .Dv O_RESOLVE_BENEATH
 337 returns
 338 .Er ENOTCAPABLE
 339 if any intermediate component of the specified relative path does not
 340 reside in the directory hierarchy beneath the topping directory.
 341 Comparing to
 342 .Dv O_BENEATH ,
 343 absolute paths or even the temporal escape from beneath of the topping
 344 directory is not allowed.
 345 .Pp
 346 When
 347 .Fa fd
 348 is opened with
 349 .Dv O_SEARCH ,
 350 execute permissions are checked at open time.
 351 The
 352 .Fa fd
 353 may not be used for any read operations like
 354 .Xr getdirentries 2 .
 355 The primary use for this descriptor will be as the lookup descriptor for the
 356 .Fn *at
 357 family of functions.
 358 .Pp
 359 If successful,
 360 .Fn open
 361 returns a non-negative integer, termed a file descriptor.
 362 It returns \-1 on failure.
 363 The file pointer used to mark the current position within the
 364 file is set to the beginning of the file.
 365 .Pp
 366 If a sleeping open of a device node from
 367 .Xr devfs 5
 368 is interrupted by a signal, the call always fails with
 369 .Er EINTR ,
 370 even if the
 371 .Dv SA_RESTART
 372 flag is set for the signal.
 373 A sleeping open of a fifo (see
 374 .Xr mkfifo 2 )
 375 is restarted as normal.
 376 .Pp
 377 When a new file is created it is given the group of the directory
 378 which contains it.
 379 .Pp
 380 Unless
 381 .Dv O_CLOEXEC
 382 flag was specified,
 383 the new descriptor is set to remain open across
 384 .Xr execve 2
 385 system calls; see
 386 .Xr close 2 ,
 387 .Xr fcntl 2
 388 and
 389 .Dv O_CLOEXEC
 390 description.
 391 .Pp
 392 The system imposes a limit on the number of file descriptors
 393 open simultaneously by one process.
 394 The
 395 .Xr getdtablesize 2
 396 system call returns the current system limit.
 397 .Sh RETURN VALUES
 398 If successful,
 399 .Fn open
 400 and
 401 .Fn openat
 402 return a non-negative integer, termed a file descriptor.
 403 They return \-1 on failure, and set
 404 .Va errno
 405 to indicate the error.
 406 .Sh ERRORS
 407 The named file is opened unless:
 408 .Bl -tag -width Er
 409 .It Bq Er ENOTDIR
 410 A component of the path prefix is not a directory.
 411 .It Bq Er ENAMETOOLONG
 412 A component of a pathname exceeded 255 characters,
 413 or an entire path name exceeded 1023 characters.
 414 .It Bq Er ENOENT
 415 .Dv O_CREAT
 416 is not set and the named file does not exist.
 417 .It Bq Er ENOENT
 418 A component of the path name that must exist does not exist.
 419 .It Bq Er EACCES
 420 Search permission is denied for a component of the path prefix.
 421 .It Bq Er EACCES
 422 The required permissions (for reading and/or writing)
 423 are denied for the given flags.
 424 .It Bq Er EACCES
 425 .Dv O_TRUNC
 426 is specified and write permission is denied.
 427 .It Bq Er EACCES
 428 .Dv O_CREAT
 429 is specified,
 430 the file does not exist,
 431 and the directory in which it is to be created
 432 does not permit writing.
 433 .It Bq Er EPERM
 434 .Dv O_CREAT
 435 is specified, the file does not exist, and the directory in which it is to be
 436 created has its immutable flag set, see the
 437 .Xr chflags 2
 438 manual page for more information.
 439 .It Bq Er EPERM
 440 The named file has its immutable flag set and the file is to be modified.
 441 .It Bq Er EPERM
 442 The named file has its append-only flag set, the file is to be modified, and
 443 .Dv O_TRUNC
 444 is specified or
 445 .Dv O_APPEND
 446 is not specified.
 447 .It Bq Er ELOOP
 448 Too many symbolic links were encountered in translating the pathname.
 449 .It Bq Er EISDIR
 450 The named file is a directory, and the arguments specify
 451 it is to be modified.
 452 .It Bq Er EISDIR
 453 The named file is a directory, and the flags specified
 454 .Dv O_CREAT
 455 without
 456 .Dv O_DIRECTORY .
 457 .It Bq Er EROFS
 458 The named file resides on a read-only file system,
 459 and the file is to be modified.
 460 .It Bq Er EROFS
 461 .Dv O_CREAT
 462 is specified and the named file would reside on a read-only file system.
 463 .It Bq Er EMFILE
 464 The process has already reached its limit for open file descriptors.
 465 .It Bq Er ENFILE
 466 The system file table is full.
 467 .It Bq Er EMLINK
 468 .Dv O_NOFOLLOW
 469 was specified and the target is a symbolic link.
 470 .It Bq Er ENXIO
 471 The named file is a character special or block
 472 special file, and the device associated with this special file
 473 does not exist.
 474 .It Bq Er ENXIO
 475 .Dv O_NONBLOCK
 476 is set, the named file is a fifo,
 477 .Dv O_WRONLY
 478 is set, and no process has the file open for reading.
 479 .It Bq Er EINTR
 480 The
 481 .Fn open
 482 operation was interrupted by a signal.
 483 .It Bq Er EOPNOTSUPP
 484 .Dv O_SHLOCK
 485 or
 486 .Dv O_EXLOCK
 487 is specified but the underlying file system does not support locking.
 488 .It Bq Er EOPNOTSUPP
 489 The named file is a special file mounted through a file system that
 490 does not support access to it (e.g.\& NFS).
 491 .It Bq Er EWOULDBLOCK
 492 .Dv O_NONBLOCK
 493 and one of
 494 .Dv O_SHLOCK
 495 or
 496 .Dv O_EXLOCK
 497 is specified and the file is locked.
 498 .It Bq Er ENOSPC
 499 .Dv O_CREAT
 500 is specified,
 501 the file does not exist,
 502 and the directory in which the entry for the new file is being placed
 503 cannot be extended because there is no space left on the file
 504 system containing the directory.
 505 .It Bq Er ENOSPC
 506 .Dv O_CREAT
 507 is specified,
 508 the file does not exist,
 509 and there are no free inodes on the file system on which the
 510 file is being created.
 511 .It Bq Er EDQUOT
 512 .Dv O_CREAT
 513 is specified,
 514 the file does not exist,
 515 and the directory in which the entry for the new file
 516 is being placed cannot be extended because the
 517 user's quota of disk blocks on the file system
 518 containing the directory has been exhausted.
 519 .It Bq Er EDQUOT
 520 .Dv O_CREAT
 521 is specified,
 522 the file does not exist,
 523 and the user's quota of inodes on the file system on
 524 which the file is being created has been exhausted.
 525 .It Bq Er EIO
 526 An I/O error occurred while making the directory entry or
 527 allocating the inode for
 528 .Dv O_CREAT .
 529 .It Bq Er EINTEGRITY
 530 Corrupted data was detected while reading from the file system.
 531 .It Bq Er ETXTBSY
 532 The file is a pure procedure (shared text) file that is being
 533 executed and the
 534 .Fn open
 535 system call requests write access.
 536 .It Bq Er EFAULT
 537 The
 538 .Fa path
 539 argument
 540 points outside the process's allocated address space.
 541 .It Bq Er EEXIST
 542 .Dv O_CREAT
 543 and
 544 .Dv O_EXCL
 545 were specified and the file exists.
 546 .It Bq Er EOPNOTSUPP
 547 An attempt was made to open a socket (not currently implemented).
 548 .It Bq Er EINVAL
 549 An attempt was made to open a descriptor with an illegal combination
 550 of
 551 .Dv O_RDONLY ,
 552 .Dv O_WRONLY ,
 553 or
 554 .Dv O_RDWR ,
 555 and
 556 .Dv O_EXEC
 557 or
 558 .Dv O_SEARCH .
 559 .It Bq Er EINVAL
 560 The
 561 .Dv O_RESOLVE_BENEATH
 562 flag is specified and
 563 .Dv path
 564 is absolute.
 565 .It Bq Er EBADF
 566 The
 567 .Fa path
 568 argument does not specify an absolute path and the
 569 .Fa fd
 570 argument is
 571 neither
 572 .Dv AT_FDCWD
 573 nor a valid file descriptor open for searching.
 574 .It Bq Er ENOTDIR
 575 The
 576 .Fa path
 577 argument is not an absolute path and
 578 .Fa fd
 579 is neither
 580 .Dv AT_FDCWD
 581 nor a file descriptor associated with a directory.
 582 .It Bq Er ENOTDIR
 583 .Dv O_DIRECTORY
 584 is specified and the file is not a directory.
 585 .It Bq Er ECAPMODE
 586 .Dv AT_FDCWD
 587 is specified and the process is in capability mode.
 588 .It Bq Er ECAPMODE
 589 .Fn open
 590 was called and the process is in capability mode.
 591 .It Bq Er ENOTCAPABLE
 592 .Fa path
 593 is an absolute path,
 594 or contained a ".." component leading to a
 595 directory outside of the directory hierarchy specified by
 596 .Fa fd ,
 597 and the process is in capability mode.
 598 .It Bq Er ENOTCAPABLE
 599 The
 600 .Dv O_BENEATH
 601 flag was provided, and the absolute
 602 .Fa path
 603 does not have its tail fully contained under the topping directory,
 604 or the relative
 605 .Fa path
 606 escapes it.
 607 .It Bq Er ENOTCAPABLE
 608 The
 609 .Dv O_RESOLVE_BENEATH
 610 flag was provided, and the relative
 611 .Fa path
 612 escapes topping directory.
 613 .El
 614 .Sh SEE ALSO
 615 .Xr chmod 2 ,
 616 .Xr close 2 ,
 617 .Xr dup 2 ,
 618 .Xr fexecve 2 ,
 619 .Xr fhopen 2 ,
 620 .Xr getdtablesize 2 ,
 621 .Xr getfh 2 ,
 622 .Xr lgetfh 2 ,
 623 .Xr lseek 2 ,
 624 .Xr read 2 ,
 625 .Xr umask 2 ,
 626 .Xr write 2 ,
 627 .Xr fopen 3 ,
 628 .Xr capsicum 4
 629 .Sh STANDARDS
 630 These functions are specified by
 631 .St -p1003.1-2008 .
 632 .Fx
 633 sets
 634 .Va errno
 635 to
 636 .Er EMLINK instead of
 637 .Er ELOOP
 638 as specified by
 639 .Tn POSIX
 640 when
 641 .Dv O_NOFOLLOW
 642 is set in flags and the final component of pathname is a symbolic link
 643 to distinguish it from the case of too many symbolic link traversals
 644 in one of its non-final components.
 645 .Sh HISTORY
 646 The
 647 .Fn open
 648 function appeared in
 649 .At v1 .
 650 The
 651 .Fn openat
 652 function was introduced in
 653 .Fx 8.0 .
 654 .Sh BUGS
 655 The Open Group Extended API Set 2 specification requires that the test
 656 for whether
 657 .Fa fd
 658 is searchable is based on whether
 659 .Fa fd
 660 is open for searching, not whether the underlying directory currently
 661 permits searches.
 662 The present implementation of the
 663 .Fa openat
 664 checks the current permissions of directory instead.
 665 .Pp
 666 The
 667 .Fa mode
 668 argument is variadic and may result in different calling conventions
 669 than might otherwise be expected.