man2/open.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\" and Copyright (C) 2008 Greg Banks
   4 .\" and Copyright (C) 2006, 2008, 2013, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   7 .\"
   8 .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
   9 .\" Modified 1994-08-21 by Michael Haardt
  10 .\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl>
  11 .\" Modified 1996-05-13 by Thomas Koenig
  12 .\" Modified 1996-12-20 by Michael Haardt
  13 .\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl>
  14 .\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk>
  15 .\" Modified 1999-06-03 by Michael Haardt
  16 .\" Modified 2002-05-07 by Michael Kerrisk <mtk.manpages@gmail.com>
  17 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  18 .\" 2004-12-08, mtk, reordered flags list alphabetically
  19 .\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME
  20 .\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits
  21 .\" 2008-01-03, mtk, with input from Trond Myklebust
  22 .\"     <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi>
  23 .\"     Rewrite description of O_EXCL.
  24 .\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail
  25 .\"     on O_DIRECT.
  26 .\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode
  27 .\"
  28 .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
  29 .\" O_TTYINIT.  Eventually these may need to be documented.  --mtk
  30 .\"
  31 .TH open 2 (date) "Linux man-pages (unreleased)"
  32 .SH NAME
  33 open, openat, creat \- open and possibly create a file
  34 .SH LIBRARY
  35 Standard C library
  36 .RI ( libc ", " \-lc )
  37 .SH SYNOPSIS
  38 .nf
  39 .B #include <fcntl.h>
  40 .P
  41 .BI "int open(const char *" pathname ", int " flags ", ..."
  42 .BI "           \fR/*\fP mode_t " mode " \fR*/\fP );"
  43 .P
  44 .BI "int creat(const char *" pathname ", mode_t " mode );
  45 .P
  46 .BI "int openat(int " dirfd ", const char *" pathname ", int " flags ", ..."
  47 .BI "           \fR/*\fP mode_t " mode " \fR*/\fP );"
  48 .P
  49 /* Documented separately, in \c
  50 .BR openat2 (2):\c
  51 \& */
  52 .BI "int openat2(int " dirfd ", const char *" pathname ,
  53 .BI "           const struct open_how *" how ", size_t " size );
  54 .fi
  55 .P
  56 .RS -4
  57 Feature Test Macro Requirements for glibc (see
  58 .BR feature_test_macros (7)):
  59 .RE
  60 .P
  61 .BR openat ():
  62 .nf
  63     Since glibc 2.10:
  64         _POSIX_C_SOURCE >= 200809L
  65     Before glibc 2.10:
  66         _ATFILE_SOURCE
  67 .fi
  68 .SH DESCRIPTION
  69 The
  70 .BR open ()
  71 system call opens the file specified by
  72 .IR pathname .
  73 If the specified file does not exist,
  74 it may optionally (if
  75 .B O_CREAT
  76 is specified in
  77 .IR flags )
  78 be created by
  79 .BR open ().
  80 .P
  81 The return value of
  82 .BR open ()
  83 is a file descriptor, a small, nonnegative integer that is an index
  84 to an entry in the process's table of open file descriptors.
  85 The file descriptor is used
  86 in subsequent system calls
  87 (\c
  88 .BR read (2),
  89 .BR write (2),
  90 .BR lseek (2),
  91 .BR fcntl (2),
  92 etc.)
  93 to refer to the open file.
  94 The file descriptor returned by a successful call will be
  95 the lowest-numbered file descriptor not currently open for the process.
  96 .P
  97 By default, the new file descriptor is set to remain open across an
  98 .BR execve (2)
  99 (i.e., the
 100 .B FD_CLOEXEC
 101 file descriptor flag described in
 102 .BR fcntl (2)
 103 is initially disabled); the
 104 .B O_CLOEXEC
 105 flag, described below, can be used to change this default.
 106 The file offset is set to the beginning of the file (see
 107 .BR lseek (2)).
 108 .P
 109 A call to
 110 .BR open ()
 111 creates a new
 112 .IR "open file description" ,
 113 an entry in the system-wide table of open files.
 114 The open file description records the file offset and the file status flags
 115 (see below).
 116 A file descriptor is a reference to an open file description;
 117 this reference is unaffected if
 118 .I pathname
 119 is subsequently removed or modified to refer to a different file.
 120 For further details on open file descriptions, see NOTES.
 121 .P
 122 The argument
 123 .I flags
 124 must include one of the following
 125 .IR "access modes" :
 126 .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
 127 These request opening the file read-only, write-only, or read/write,
 128 respectively.
 129 .P
 130 In addition, zero or more file creation flags and file status flags
 131 can be
 132 bitwise ORed
 133 in
 134 .IR flags .
 135 The
 136 .I file creation flags
 137 are
 138 .BR O_CLOEXEC ,
 139 .BR O_CREAT ,
 140 .BR O_DIRECTORY ,
 141 .BR O_EXCL ,
 142 .BR O_NOCTTY ,
 143 .BR O_NOFOLLOW ,
 144 .BR O_TMPFILE ,
 145 and
 146 .BR O_TRUNC .
 147 The
 148 .I file status flags
 149 are all of the remaining flags listed below.
 150 .\" SUSv4 divides the flags into:
 151 .\" * Access mode
 152 .\" * File creation
 153 .\" * File status
 154 .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
 155 .\" though it's not clear what the difference between "other" and
 156 .\" "File creation" flags is.  I raised an Aardvark to see if this
 157 .\" can be clarified in SUSv4; 10 Oct 2008.
 158 .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
 159 .\" TC1 (balloted in 2013), resolved this, so that those three constants
 160 .\" are also categorized" as file status flags.
 161 .\"
 162 The distinction between these two groups of flags is that
 163 the file creation flags affect the semantics of the open operation itself,
 164 while the file status flags affect the semantics of subsequent I/O operations.
 165 The file status flags can be retrieved and (in some cases)
 166 modified; see
 167 .BR fcntl (2)
 168 for details.
 169 .P
 170 The full list of file creation flags and file status flags is as follows:
 171 .TP
 172 .B O_APPEND
 173 The file is opened in append mode.
 174 Before each
 175 .BR write (2),
 176 the file offset is positioned at the end of the file,
 177 as if with
 178 .BR lseek (2).
 179 The modification of the file offset and the write operation
 180 are performed as a single atomic step.
 181 .IP
 182 .B O_APPEND
 183 may lead to corrupted files on NFS filesystems if more than one process
 184 appends data to a file at once.
 185 .\" For more background, see
 186 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
 187 .\" http://nfs.sourceforge.net/
 188 This is because NFS does not support
 189 appending to a file, so the client kernel has to simulate it, which
 190 can't be done without a race condition.
 191 .TP
 192 .B O_ASYNC
 193 Enable signal-driven I/O:
 194 generate a signal
 195 .RB ( SIGIO
 196 by default, but this can be changed via
 197 .BR fcntl (2))
 198 when input or output becomes possible on this file descriptor.
 199 This feature is available only for terminals, pseudoterminals,
 200 sockets, and (since Linux 2.6) pipes and FIFOs.
 201 See
 202 .BR fcntl (2)
 203 for further details.
 204 See also BUGS, below.
 205 .TP
 206 .BR O_CLOEXEC " (since Linux 2.6.23)"
 207 .\" NOTE! several other man pages refer to this text
 208 Enable the close-on-exec flag for the new file descriptor.
 209 .\" FIXME . for later review when Issue 8 is one day released...
 210 .\" POSIX proposes to fix many APIs that provide hidden FDs
 211 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
 212 .\" http://austingroupbugs.net/view.php?id=368
 213 Specifying this flag permits a program to avoid additional
 214 .BR fcntl (2)
 215 .B F_SETFD
 216 operations to set the
 217 .B FD_CLOEXEC
 218 flag.
 219 .IP
 220 Note that the use of this flag is essential in some multithreaded programs,
 221 because using a separate
 222 .BR fcntl (2)
 223 .B F_SETFD
 224 operation to set the
 225 .B FD_CLOEXEC
 226 flag does not suffice to avoid race conditions
 227 where one thread opens a file descriptor and
 228 attempts to set its close-on-exec flag using
 229 .BR fcntl (2)
 230 at the same time as another thread does a
 231 .BR fork (2)
 232 plus
 233 .BR execve (2).
 234 Depending on the order of execution,
 235 the race may lead to the file descriptor returned by
 236 .BR open ()
 237 being unintentionally leaked to the program executed by the child process
 238 created by
 239 .BR fork (2).
 240 (This kind of race is in principle possible for any system call
 241 that creates a file descriptor whose close-on-exec flag should be set,
 242 and various other Linux system calls provide an equivalent of the
 243 .B O_CLOEXEC
 244 flag to deal with this problem.)
 245 .\" This flag fixes only one form of the race condition;
 246 .\" The race can also occur with, for example, file descriptors
 247 .\" returned by accept(), pipe(), etc.
 248 .TP
 249 .B O_CREAT
 250 If
 251 .I pathname
 252 does not exist, create it as a regular file.
 253 .IP
 254 The owner (user ID) of the new file is set to the effective user ID
 255 of the process.
 256 .IP
 257 The group ownership (group ID) of the new file is set either to
 258 the effective group ID of the process (System V semantics)
 259 or to the group ID of the parent directory (BSD semantics).
 260 On Linux, the behavior depends on whether the
 261 set-group-ID mode bit is set on the parent directory:
 262 if that bit is set, then BSD semantics apply;
 263 otherwise, System V semantics apply.
 264 For some filesystems, the behavior also depends on the
 265 .I bsdgroups
 266 and
 267 .I sysvgroups
 268 mount options described in
 269 .BR mount (8).
 270 .\" As at Linux 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
 271 .\" XFS (since Linux 2.6.14).
 272 .IP
 273 The
 274 .I mode
 275 argument specifies the file mode bits to be applied when a new file is created.
 276 If neither
 277 .B O_CREAT
 278 nor
 279 .B O_TMPFILE
 280 is specified in
 281 .IR flags ,
 282 then
 283 .I mode
 284 is ignored (and can thus be specified as 0, or simply omitted).
 285 The
 286 .I mode
 287 argument
 288 .B must
 289 be supplied if
 290 .B O_CREAT
 291 or
 292 .B O_TMPFILE
 293 is specified in
 294 .IR flags ;
 295 if it is not supplied,
 296 some arbitrary bytes from the stack will be applied as the file mode.
 297 .IP
 298 The effective mode is modified by the process's
 299 .I umask
 300 in the usual way: in the absence of a default ACL, the mode of the
 301 created file is
 302 .IR "(mode\ &\ \[ti]umask)" .
 303 .IP
 304 Note that
 305 .I mode
 306 applies only to future accesses of the
 307 newly created file; the
 308 .BR open ()
 309 call that creates a read-only file may well return a read/write
 310 file descriptor.
 311 .IP
 312 The following symbolic constants are provided for
 313 .IR mode :
 314 .RS
 315 .TP 9
 316 .B S_IRWXU
 317 00700 user (file owner) has read, write, and execute permission
 318 .TP
 319 .B S_IRUSR
 320 00400 user has read permission
 321 .TP
 322 .B S_IWUSR
 323 00200 user has write permission
 324 .TP
 325 .B S_IXUSR
 326 00100 user has execute permission
 327 .TP
 328 .B S_IRWXG
 329 00070 group has read, write, and execute permission
 330 .TP
 331 .B S_IRGRP
 332 00040 group has read permission
 333 .TP
 334 .B S_IWGRP
 335 00020 group has write permission
 336 .TP
 337 .B S_IXGRP
 338 00010 group has execute permission
 339 .TP
 340 .B S_IRWXO
 341 00007 others have read, write, and execute permission
 342 .TP
 343 .B S_IROTH
 344 00004 others have read permission
 345 .TP
 346 .B S_IWOTH
 347 00002 others have write permission
 348 .TP
 349 .B S_IXOTH
 350 00001 others have execute permission
 351 .RE
 352 .IP
 353 According to POSIX, the effect when other bits are set in
 354 .I mode
 355 is unspecified.
 356 On Linux, the following bits are also honored in
 357 .IR mode :
 358 .RS
 359 .TP 9
 360 .B S_ISUID
 361 0004000 set-user-ID bit
 362 .TP
 363 .B S_ISGID
 364 0002000 set-group-ID bit (see
 365 .BR inode (7)).
 366 .TP
 367 .B S_ISVTX
 368 0001000 sticky bit (see
 369 .BR inode (7)).
 370 .RE
 371 .TP
 372 .BR O_DIRECT " (since Linux 2.4.10)"
 373 Try to minimize cache effects of the I/O to and from this file.
 374 In general this will degrade performance, but it is useful in
 375 special situations, such as when applications do their own caching.
 376 File I/O is done directly to/from user-space buffers.
 377 The
 378 .B O_DIRECT
 379 flag on its own makes an effort to transfer data synchronously,
 380 but does not give the guarantees of the
 381 .B O_SYNC
 382 flag that data and necessary metadata are transferred.
 383 To guarantee synchronous I/O,
 384 .B O_SYNC
 385 must be used in addition to
 386 .BR O_DIRECT .
 387 See NOTES below for further discussion.
 388 .IP
 389 A semantically similar (but deprecated) interface for block devices
 390 is described in
 391 .BR raw (8).
 392 .TP
 393 .B O_DIRECTORY
 394 If \fIpathname\fP is not a directory, cause the open to fail.
 395 .\" But see the following and its replies:
 396 .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
 397 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
 398 .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
 399 This flag was added in Linux 2.1.126, to
 400 avoid denial-of-service problems if
 401 .BR opendir (3)
 402 is called on a
 403 FIFO or tape device.
 404 .TP
 405 .B O_DSYNC
 406 Write operations on the file will complete according to the requirements of
 407 synchronized I/O
 408 .I data
 409 integrity completion.
 410 .IP
 411 By the time
 412 .BR write (2)
 413 (and similar)
 414 return, the output data
 415 has been transferred to the underlying hardware,
 416 along with any file metadata that would be required to retrieve that data
 417 (i.e., as though each
 418 .BR write (2)
 419 was followed by a call to
 420 .BR fdatasync (2)).
 421 .IR "See NOTES below" .
 422 .TP
 423 .B O_EXCL
 424 Ensure that this call creates the file:
 425 if this flag is specified in conjunction with
 426 .BR O_CREAT ,
 427 and
 428 .I pathname
 429 already exists, then
 430 .BR open ()
 431 fails with the error
 432 .BR EEXIST .
 433 .IP
 434 When these two flags are specified, symbolic links are not followed:
 435 .\" POSIX.1-2001 explicitly requires this behavior.
 436 if
 437 .I pathname
 438 is a symbolic link, then
 439 .BR open ()
 440 fails regardless of where the symbolic link points.
 441 .IP
 442 In general, the behavior of
 443 .B O_EXCL
 444 is undefined if it is used without
 445 .BR O_CREAT .
 446 There is one exception: on Linux 2.6 and later,
 447 .B O_EXCL
 448 can be used without
 449 .B O_CREAT
 450 if
 451 .I pathname
 452 refers to a block device.
 453 If the block device is in use by the system (e.g., mounted),
 454 .BR open ()
 455 fails with the error
 456 .BR EBUSY .
 457 .IP
 458 On NFS,
 459 .B O_EXCL
 460 is supported only when using NFSv3 or later on kernel 2.6 or later.
 461 In NFS environments where
 462 .B O_EXCL
 463 support is not provided, programs that rely on it
 464 for performing locking tasks will contain a race condition.
 465 Portable programs that want to perform atomic file locking using a lockfile,
 466 and need to avoid reliance on NFS support for
 467 .BR O_EXCL ,
 468 can create a unique file on
 469 the same filesystem (e.g., incorporating hostname and PID), and use
 470 .BR link (2)
 471 to make a link to the lockfile.
 472 If
 473 .BR link (2)
 474 returns 0, the lock is successful.
 475 Otherwise, use
 476 .BR stat (2)
 477 on the unique file to check if its link count has increased to 2,
 478 in which case the lock is also successful.
 479 .TP
 480 .B O_LARGEFILE
 481 (LFS)
 482 Allow files whose sizes cannot be represented in an
 483 .I off_t
 484 (but can be represented in an
 485 .IR off64_t )
 486 to be opened.
 487 The
 488 .B _LARGEFILE64_SOURCE
 489 macro must be defined
 490 (before including
 491 .I any
 492 header files)
 493 in order to obtain this definition.
 494 Setting the
 495 .B _FILE_OFFSET_BITS
 496 feature test macro to 64 (rather than using
 497 .BR O_LARGEFILE )
 498 is the preferred
 499 method of accessing large files on 32-bit systems (see
 500 .BR feature_test_macros (7)).
 501 .TP
 502 .BR O_NOATIME " (since Linux 2.6.8)"
 503 Do not update the file last access time
 504 .RI ( st_atime
 505 in the inode)
 506 when the file is
 507 .BR read (2).
 508 .IP
 509 This flag can be employed only if one of the following conditions is true:
 510 .RS
 511 .IP \[bu] 3
 512 The effective UID of the process
 513 .\" Strictly speaking: the filesystem UID
 514 matches the owner UID of the file.
 515 .IP \[bu]
 516 The calling process has the
 517 .B CAP_FOWNER
 518 capability in its user namespace and
 519 the owner UID of the file has a mapping in the namespace.
 520 .RE
 521 .IP
 522 This flag is intended for use by indexing or backup programs,
 523 where its use can significantly reduce the amount of disk activity.
 524 This flag may not be effective on all filesystems.
 525 One example is NFS, where the server maintains the access time.
 526 .\" The O_NOATIME flag also affects the treatment of st_atime
 527 .\" by mmap() and readdir(2), MTK, Dec 04.
 528 .TP
 529 .B O_NOCTTY
 530 If
 531 .I pathname
 532 refers to a terminal device\[em]see
 533 .BR tty (4)\[em]it
 534 will not become the process's controlling terminal even if the
 535 process does not have one.
 536 .TP
 537 .B O_NOFOLLOW
 538 If the trailing component (i.e., basename) of
 539 .I pathname
 540 is a symbolic link, then the open fails, with the error
 541 .BR ELOOP .
 542 Symbolic links in earlier components of the pathname will still be
 543 followed.
 544 (Note that the
 545 .B ELOOP
 546 error that can occur in this case is indistinguishable from the case where
 547 an open fails because there are too many symbolic links found
 548 while resolving components in the prefix part of the pathname.)
 549 .IP
 550 This flag is a FreeBSD extension, which was added in Linux 2.1.126,
 551 and has subsequently been standardized in POSIX.1-2008.
 552 .IP
 553 See also
 554 .B O_PATH
 555 below.
 556 .\" The headers from glibc 2.0.100 and later include a
 557 .\" definition of this flag; \fIkernels before Linux 2.1.126 will ignore it if
 558 .\" used\fP.
 559 .TP
 560 .BR O_NONBLOCK " or " O_NDELAY
 561 When possible, the file is opened in nonblocking mode.
 562 Neither the
 563 .BR open ()
 564 nor any subsequent I/O operations on the file descriptor which is
 565 returned will cause the calling process to wait.
 566 .IP
 567 Note that the setting of this flag has no effect on the operation of
 568 .BR poll (2),
 569 .BR select (2),
 570 .BR epoll (7),
 571 and similar,
 572 since those interfaces merely inform the caller about whether
 573 a file descriptor is "ready",
 574 meaning that an I/O operation performed on
 575 the file descriptor with the
 576 .B O_NONBLOCK
 577 flag
 578 .I clear
 579 would not block.
 580 .IP
 581 Note that this flag has no effect for regular files and block devices;
 582 that is, I/O operations will (briefly) block when device activity
 583 is required, regardless of whether
 584 .B O_NONBLOCK
 585 is set.
 586 Since
 587 .B O_NONBLOCK
 588 semantics might eventually be implemented,
 589 applications should not depend upon blocking behavior
 590 when specifying this flag for regular files and block devices.
 591 .IP
 592 For the handling of FIFOs (named pipes), see also
 593 .BR fifo (7).
 594 For a discussion of the effect of
 595 .B O_NONBLOCK
 596 in conjunction with mandatory file locks and with file leases, see
 597 .BR fcntl (2).
 598 .TP
 599 .BR O_PATH " (since Linux 2.6.39)"
 600 .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
 601 .\" commit 326be7b484843988afe57566b627fb7a70beac56
 602 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 603 .\"
 604 .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
 605 .\"     Subject: Re: [PATCH] open(2): document O_PATH
 606 .\"     Newsgroups: gmane.linux.man, gmane.linux.kernel
 607 .\"
 608 Obtain a file descriptor that can be used for two purposes:
 609 to indicate a location in the filesystem tree and
 610 to perform operations that act purely at the file descriptor level.
 611 The file itself is not opened, and other file operations (e.g.,
 612 .BR read (2),
 613 .BR write (2),
 614 .BR fchmod (2),
 615 .BR fchown (2),
 616 .BR fgetxattr (2),
 617 .BR ioctl (2),
 618 .BR mmap (2))
 619 fail with the error
 620 .BR EBADF .
 621 .IP
 622 The following operations
 623 .I can
 624 be performed on the resulting file descriptor:
 625 .RS
 626 .IP \[bu] 3
 627 .BR close (2).
 628 .IP \[bu]
 629 .BR fchdir (2),
 630 if the file descriptor refers to a directory
 631 (since Linux 3.5).
 632 .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
 633 .IP \[bu]
 634 .BR fstat (2)
 635 (since Linux 3.6).
 636 .IP \[bu]
 637 .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
 638 .BR fstatfs (2)
 639 (since Linux 3.12).
 640 .\" fstatfs(): commit 9d05746e7b16d8565dddbe3200faa1e669d23bbf
 641 .IP \[bu]
 642 Duplicating the file descriptor
 643 .RB ( dup (2),
 644 .BR fcntl (2)
 645 .BR F_DUPFD ,
 646 etc.).
 647 .IP \[bu]
 648 Getting and setting file descriptor flags
 649 .RB ( fcntl (2)
 650 .B F_GETFD
 651 and
 652 .BR F_SETFD ).
 653 .IP \[bu]
 654 Retrieving open file status flags using the
 655 .BR fcntl (2)
 656 .B F_GETFL
 657 operation: the returned flags will include the bit
 658 .BR O_PATH .
 659 .IP \[bu]
 660 Passing the file descriptor as the
 661 .I dirfd
 662 argument of
 663 .BR openat ()
 664 and the other "*at()" system calls.
 665 This includes
 666 .BR linkat (2)
 667 with
 668 .B AT_EMPTY_PATH
 669 (or via procfs using
 670 .BR AT_SYMLINK_FOLLOW )
 671 even if the file is not a directory.
 672 .IP \[bu]
 673 Passing the file descriptor to another process via a UNIX domain socket
 674 (see
 675 .B SCM_RIGHTS
 676 in
 677 .BR unix (7)).
 678 .RE
 679 .IP
 680 When
 681 .B O_PATH
 682 is specified in
 683 .IR flags ,
 684 flag bits other than
 685 .BR O_CLOEXEC ,
 686 .BR O_DIRECTORY ,
 687 and
 688 .B O_NOFOLLOW
 689 are ignored.
 690 .IP
 691 Opening a file or directory with the
 692 .B O_PATH
 693 flag requires no permissions on the object itself
 694 (but does require execute permission on the directories in the path prefix).
 695 Depending on the subsequent operation,
 696 a check for suitable file permissions may be performed (e.g.,
 697 .BR fchdir (2)
 698 requires execute permission on the directory referred to
 699 by its file descriptor argument).
 700 By contrast,
 701 obtaining a reference to a filesystem object by opening it with the
 702 .B O_RDONLY
 703 flag requires that the caller have read permission on the object,
 704 even when the subsequent operation (e.g.,
 705 .BR fchdir (2),
 706 .BR fstat (2))
 707 does not require read permission on the object.
 708 .IP
 709 If
 710 .I pathname
 711 is a symbolic link and the
 712 .B O_NOFOLLOW
 713 flag is also specified,
 714 then the call returns a file descriptor referring to the symbolic link.
 715 This file descriptor can be used as the
 716 .I dirfd
 717 argument in calls to
 718 .BR fchownat (2),
 719 .BR fstatat (2),
 720 .BR linkat (2),
 721 and
 722 .BR readlinkat (2)
 723 with an empty pathname to have the calls operate on the symbolic link.
 724 .IP
 725 If
 726 .I pathname
 727 refers to an automount point that has not yet been triggered, so no
 728 other filesystem is mounted on it, then the call returns a file
 729 descriptor referring to the automount directory without triggering a mount.
 730 .BR fstatfs (2)
 731 can then be used to determine if it is, in fact, an untriggered
 732 automount point
 733 .RB ( ".f_type == AUTOFS_SUPER_MAGIC" ).
 734 .IP
 735 One use of
 736 .B O_PATH
 737 for regular files is to provide the equivalent of POSIX.1's
 738 .B O_EXEC
 739 functionality.
 740 This permits us to open a file for which we have execute
 741 permission but not read permission, and then execute that file,
 742 with steps something like the following:
 743 .IP
 744 .in +4n
 745 .EX
 746 char buf[PATH_MAX];
 747 fd = open("some_prog", O_PATH);
 748 snprintf(buf, PATH_MAX, "/proc/self/fd/%d", fd);
 749 execl(buf, "some_prog", (char *) NULL);
 750 .EE
 751 .in
 752 .IP
 753 An
 754 .B O_PATH
 755 file descriptor can also be passed as the argument of
 756 .BR fexecve (3).
 757 .TP
 758 .B O_SYNC
 759 Write operations on the file will complete according to the requirements of
 760 synchronized I/O
 761 .I file
 762 integrity completion
 763 (by contrast with the
 764 synchronized I/O
 765 .I data
 766 integrity completion
 767 provided by
 768 .BR O_DSYNC .)
 769 .IP
 770 By the time
 771 .BR write (2)
 772 (or similar)
 773 returns, the output data and associated file metadata
 774 have been transferred to the underlying hardware
 775 (i.e., as though each
 776 .BR write (2)
 777 was followed by a call to
 778 .BR fsync (2)).
 779 .IR "See NOTES below" .
 780 .TP
 781 .BR O_TMPFILE " (since Linux 3.11)"
 782 .\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
 783 .\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
 784 .\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
 785 Create an unnamed temporary regular file.
 786 The
 787 .I pathname
 788 argument specifies a directory;
 789 an unnamed inode will be created in that directory's filesystem.
 790 Anything written to the resulting file will be lost when
 791 the last file descriptor is closed, unless the file is given a name.
 792 .IP
 793 .B O_TMPFILE
 794 must be specified with one of
 795 .B O_RDWR
 796 or
 797 .B O_WRONLY
 798 and, optionally,
 799 .BR O_EXCL .
 800 If
 801 .B O_EXCL
 802 is not specified, then
 803 .BR linkat (2)
 804 can be used to link the temporary file into the filesystem, making it
 805 permanent, using code like the following:
 806 .IP
 807 .in +4n
 808 .EX
 809 char path[PATH_MAX];
 810 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
 811                         S_IRUSR | S_IWUSR);
 812 \&
 813 /* File I/O on \[aq]fd\[aq]... */
 814 \&
 815 linkat(fd, "", AT_FDCWD, "/path/for/file", AT_EMPTY_PATH);
 816 \&
 817 /* If the caller doesn\[aq]t have the CAP_DAC_READ_SEARCH
 818    capability (needed to use AT_EMPTY_PATH with linkat(2)),
 819    and there is a proc(5) filesystem mounted, then the
 820    linkat(2) call above can be replaced with:
 821 \&
 822 snprintf(path, PATH_MAX,  "/proc/self/fd/%d", fd);
 823 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
 824                         AT_SYMLINK_FOLLOW);
 825 */
 826 .EE
 827 .in
 828 .IP
 829 In this case,
 830 the
 831 .BR open ()
 832 .I mode
 833 argument determines the file permission mode, as with
 834 .BR O_CREAT .
 835 .IP
 836 Specifying
 837 .B O_EXCL
 838 in conjunction with
 839 .B O_TMPFILE
 840 prevents a temporary file from being linked into the filesystem
 841 in the above manner.
 842 (Note that the meaning of
 843 .B O_EXCL
 844 in this case is different from the meaning of
 845 .B O_EXCL
 846 otherwise.)
 847 .IP
 848 There are two main use cases for
 849 .\" Inspired by http://lwn.net/Articles/559147/
 850 .BR O_TMPFILE :
 851 .RS
 852 .IP \[bu] 3
 853 Improved
 854 .BR tmpfile (3)
 855 functionality: race-free creation of temporary files that
 856 (1) are automatically deleted when closed;
 857 (2) can never be reached via any pathname;
 858 (3) are not subject to symlink attacks; and
 859 (4) do not require the caller to devise unique names.
 860 .IP \[bu]
 861 Creating a file that is initially invisible, which is then populated
 862 with data and adjusted to have appropriate filesystem attributes
 863 .RB ( fchown (2),
 864 .BR fchmod (2),
 865 .BR fsetxattr (2),
 866 etc.)
 867 before being atomically linked into the filesystem
 868 in a fully formed state (using
 869 .BR linkat (2)
 870 as described above).
 871 .RE
 872 .IP
 873 .B O_TMPFILE
 874 requires support by the underlying filesystem;
 875 only a subset of Linux filesystems provide that support.
 876 In the initial implementation, support was provided in
 877 the ext2, ext3, ext4, UDF, Minix, and tmpfs filesystems.
 878 .\" To check for support, grep for "tmpfile" in kernel sources
 879 Support for other filesystems has subsequently been added as follows:
 880 XFS (Linux 3.15);
 881 .\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
 882 .\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
 883 Btrfs (Linux 3.16);
 884 .\" commit ef3b9af50bfa6a1f02cd7b3f5124b712b1ba3e3c
 885 F2FS (Linux 3.16);
 886 .\" commit 50732df02eefb39ab414ef655979c2c9b64ad21c
 887 and ubifs (Linux 4.9)
 888 .TP
 889 .B O_TRUNC
 890 If the file already exists and is a regular file and the access mode allows
 891 writing (i.e., is
 892 .B O_RDWR
 893 or
 894 .BR O_WRONLY )
 895 it will be truncated to length 0.
 896 If the file is a FIFO or terminal device file, the
 897 .B O_TRUNC
 898 flag is ignored.
 899 Otherwise, the effect of
 900 .B O_TRUNC
 901 is unspecified.
 902 .SS creat()
 903 A call to
 904 .BR creat ()
 905 is equivalent to calling
 906 .BR open ()
 907 with
 908 .I flags
 909 equal to
 910 .BR O_CREAT|O_WRONLY|O_TRUNC .
 911 .SS openat()
 912 The
 913 .BR openat ()
 914 system call operates in exactly the same way as
 915 .BR open (),
 916 except for the differences described here.
 917 .P
 918 The
 919 .I dirfd
 920 argument is used in conjunction with the
 921 .I pathname
 922 argument as follows:
 923 .IP \[bu] 3
 924 If the pathname given in
 925 .I pathname
 926 is absolute, then
 927 .I dirfd
 928 is ignored.
 929 .IP \[bu]
 930 If the pathname given in
 931 .I pathname
 932 is relative and
 933 .I dirfd
 934 is the special value
 935 .BR AT_FDCWD ,
 936 then
 937 .I pathname
 938 is interpreted relative to the current working
 939 directory of the calling process (like
 940 .BR open ()).
 941 .IP \[bu]
 942 If the pathname given in
 943 .I pathname
 944 is relative, then it is interpreted relative to the directory
 945 referred to by the file descriptor
 946 .I dirfd
 947 (rather than relative to the current working directory of
 948 the calling process, as is done by
 949 .BR open ()
 950 for a relative pathname).
 951 In this case,
 952 .I dirfd
 953 must be a directory that was opened for reading
 954 .RB ( O_RDONLY )
 955 or using the
 956 .B O_PATH
 957 flag.
 958 .P
 959 If the pathname given in
 960 .I pathname
 961 is relative, and
 962 .I dirfd
 963 is not a valid file descriptor, an error
 964 .RB ( EBADF )
 965 results.
 966 (Specifying an invalid file descriptor number in
 967 .I dirfd
 968 can be used as a means to ensure that
 969 .I pathname
 970 is absolute.)
 971 .\"
 972 .SS openat2(2)
 973 The
 974 .BR openat2 (2)
 975 system call is an extension of
 976 .BR openat (),
 977 and provides a superset of the features of
 978 .BR openat ().
 979 It is documented separately, in
 980 .BR openat2 (2).
 981 .SH RETURN VALUE
 982 On success,
 983 .BR open (),
 984 .BR openat (),
 985 and
 986 .BR creat ()
 987 return the new file descriptor (a nonnegative integer).
 988 On error, \-1 is returned and
 989 .I errno
 990 is set to indicate the error.
 991 .SH ERRORS
 992 .BR open (),
 993 .BR openat (),
 994 and
 995 .BR creat ()
 996 can fail with the following errors:
 997 .TP
 998 .B EACCES
 999 The requested access to the file is not allowed, or search permission
1000 is denied for one of the directories in the path prefix of
1001 .IR pathname ,
1002 or the file did not exist yet and write access to the parent directory
1003 is not allowed.
1004 (See also
1005 .BR path_resolution (7).)
1006 .TP
1007 .B EACCES
1008 .\" commit 30aba6656f61ed44cba445a3c0d38b296fa9e8f5
1009 Where
1010 .B O_CREAT
1011 is specified, the
1012 .I protected_fifos
1013 or
1014 .I protected_regular
1015 sysctl is enabled, the file already exists and is a FIFO or regular file, the
1016 owner of the file is neither the current user nor the owner of the
1017 containing directory, and the containing directory is both world- or
1018 group-writable and sticky.
1019 For details, see the descriptions of
1020 .I /proc/sys/fs/protected_fifos
1021 and
1022 .I /proc/sys/fs/protected_regular
1023 in
1024 .BR proc_sys_fs (5).
1025 .TP
1026 .B EBADF
1027 .RB ( openat ())
1028 .I pathname
1029 is relative but
1030 .I dirfd
1031 is neither
1032 .B AT_FDCWD
1033 nor a valid file descriptor.
1034 .TP
1035 .B EBUSY
1036 .B O_EXCL
1037 was specified in
1038 .I flags
1039 and
1040 .I pathname
1041 refers to a block device that is in use by the system (e.g., it is mounted).
1042 .TP
1043 .B EDQUOT
1044 Where
1045 .B O_CREAT
1046 is specified, the file does not exist, and the user's quota of disk
1047 blocks or inodes on the filesystem has been exhausted.
1048 .TP
1049 .B EEXIST
1050 .I pathname
1051 already exists and
1052 .BR O_CREAT " and " O_EXCL
1053 were used.
1054 .TP
1055 .B EFAULT
1056 .I pathname
1057 points outside your accessible address space.
1058 .TP
1059 .B EFBIG
1060 See
1061 .BR EOVERFLOW .
1062 .TP
1063 .B EINTR
1064 While blocked waiting to complete an open of a slow device
1065 (e.g., a FIFO; see
1066 .BR fifo (7)),
1067 the call was interrupted by a signal handler; see
1068 .BR signal (7).
1069 .TP
1070 .B EINVAL
1071 The filesystem does not support the
1072 .B O_DIRECT
1073 flag.
1074 See
1075 .B NOTES
1076 for more information.
1077 .TP
1078 .B EINVAL
1079 Invalid value in
1080 .\" In particular, __O_TMPFILE instead of O_TMPFILE
1081 .IR flags .
1082 .TP
1083 .B EINVAL
1084 .B O_TMPFILE
1085 was specified in
1086 .IR flags ,
1087 but neither
1088 .B O_WRONLY
1089 nor
1090 .B O_RDWR
1091 was specified.
1092 .TP
1093 .B EINVAL
1094 .B O_CREAT
1095 was specified in
1096 .I flags
1097 and the final component ("basename") of the new file's
1098 .I pathname
1099 is invalid
1100 (e.g., it contains characters not permitted by the underlying filesystem).
1101 .TP
1102 .B EINVAL
1103 The final component ("basename") of
1104 .I pathname
1105 is invalid
1106 (e.g., it contains characters not permitted by the underlying filesystem).
1107 .TP
1108 .B EISDIR
1109 .I pathname
1110 refers to a directory and the access requested involved writing
1111 (that is,
1112 .B O_WRONLY
1113 or
1114 .B O_RDWR
1115 is set).
1116 .TP
1117 .B EISDIR
1118 .I pathname
1119 refers to an existing directory,
1120 .B O_TMPFILE
1121 and one of
1122 .B O_WRONLY
1123 or
1124 .B O_RDWR
1125 were specified in
1126 .IR flags ,
1127 but this kernel version does not provide the
1128 .B O_TMPFILE
1129 functionality.
1130 .TP
1131 .B ELOOP
1132 Too many symbolic links were encountered in resolving
1133 .IR pathname .
1134 .TP
1135 .B ELOOP
1136 .I pathname
1137 was a symbolic link, and
1138 .I flags
1139 specified
1140 .B O_NOFOLLOW
1141 but not
1142 .BR O_PATH .
1143 .TP
1144 .B EMFILE
1145 The per-process limit on the number of open file descriptors has been reached
1146 (see the description of
1147 .B RLIMIT_NOFILE
1148 in
1149 .BR getrlimit (2)).
1150 .TP
1151 .B ENAMETOOLONG
1152 .I pathname
1153 was too long.
1154 .TP
1155 .B ENFILE
1156 The system-wide limit on the total number of open files has been reached.
1157 .TP
1158 .B ENODEV
1159 .I pathname
1160 refers to a device special file and no corresponding device exists.
1161 (This is a Linux kernel bug; in this situation
1162 .B ENXIO
1163 must be returned.)
1164 .TP
1165 .B ENOENT
1166 .B O_CREAT
1167 is not set and the named file does not exist.
1168 .TP
1169 .B ENOENT
1170 A directory component in
1171 .I pathname
1172 does not exist or is a dangling symbolic link.
1173 .TP
1174 .B ENOENT
1175 .I pathname
1176 refers to a nonexistent directory,
1177 .B O_TMPFILE
1178 and one of
1179 .B O_WRONLY
1180 or
1181 .B O_RDWR
1182 were specified in
1183 .IR flags ,
1184 but this kernel version does not provide the
1185 .B O_TMPFILE
1186 functionality.
1187 .TP
1188 .B ENOMEM
1189 The named file is a FIFO,
1190 but memory for the FIFO buffer can't be allocated because
1191 the per-user hard limit on memory allocation for pipes has been reached
1192 and the caller is not privileged; see
1193 .BR pipe (7).
1194 .TP
1195 .B ENOMEM
1196 Insufficient kernel memory was available.
1197 .TP
1198 .B ENOSPC
1199 .I pathname
1200 was to be created but the device containing
1201 .I pathname
1202 has no room for the new file.
1203 .TP
1204 .B ENOTDIR
1205 A component used as a directory in
1206 .I pathname
1207 is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
1208 .I pathname
1209 was not a directory.
1210 .TP
1211 .B ENOTDIR
1212 .RB ( openat ())
1213 .I pathname
1214 is a relative pathname and
1215 .I dirfd
1216 is a file descriptor referring to a file other than a directory.
1217 .TP
1218 .B ENXIO
1219 .BR O_NONBLOCK " | " O_WRONLY
1220 is set, the named file is a FIFO, and
1221 no process has the FIFO open for reading.
1222 .TP
1223 .B ENXIO
1224 The file is a device special file and no corresponding device exists.
1225 .TP
1226 .B ENXIO
1227 The file is a UNIX domain socket.
1228 .TP
1229 .B EOPNOTSUPP
1230 The filesystem containing
1231 .I pathname
1232 does not support
1233 .BR O_TMPFILE .
1234 .TP
1235 .B EOVERFLOW
1236 .I pathname
1237 refers to a regular file that is too large to be opened.
1238 The usual scenario here is that an application compiled
1239 on a 32-bit platform without
1240 .I \-D_FILE_OFFSET_BITS=64
1241 tried to open a file whose size exceeds
1242 .I (1<<31)\-1
1243 bytes;
1244 see also
1245 .B O_LARGEFILE
1246 above.
1247 This is the error specified by POSIX.1;
1248 before Linux 2.6.24, Linux gave the error
1249 .B EFBIG
1250 for this case.
1251 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
1252 .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
1253 .\" Reported 2006-10-03
1254 .TP
1255 .B EPERM
1256 The
1257 .B O_NOATIME
1258 flag was specified, but the effective user ID of the caller
1259 .\" Strictly speaking, it's the filesystem UID... (MTK)
1260 did not match the owner of the file and the caller was not privileged.
1261 .TP
1262 .B EPERM
1263 The operation was prevented by a file seal; see
1264 .BR fcntl (2).
1265 .TP
1266 .B EROFS
1267 .I pathname
1268 refers to a file on a read-only filesystem and write access was
1269 requested.
1270 .TP
1271 .B ETXTBSY
1272 .I pathname
1273 refers to an executable image which is currently being executed and
1274 write access was requested.
1275 .TP
1276 .B ETXTBSY
1277 .I pathname
1278 refers to a file that is currently in use as a swap file, and the
1279 .B O_TRUNC
1280 flag was specified.
1281 .TP
1282 .B ETXTBSY
1283 .I pathname
1284 refers to a file that is currently being read by the kernel (e.g., for
1285 module/firmware loading), and write access was requested.
1286 .TP
1287 .B EWOULDBLOCK
1288 The
1289 .B O_NONBLOCK
1290 flag was specified, and an incompatible lease was held on the file
1291 (see
1292 .BR fcntl (2)).
1293 .SH VERSIONS
1294 The (undefined) effect of
1295 .B O_RDONLY | O_TRUNC
1296 varies among implementations.
1297 On many systems the file is actually truncated.
1298 .\" Linux 2.0, 2.5: truncate
1299 .\" Solaris 5.7, 5.8: truncate
1300 .\" Irix 6.5: truncate
1301 .\" Tru64 5.1B: truncate
1302 .\" HP-UX 11.22: truncate
1303 .\" FreeBSD 4.7: truncate
1304 .SS Synchronized I/O
1305 The POSIX.1-2008 "synchronized I/O" option
1306 specifies different variants of synchronized I/O,
1307 and specifies the
1308 .BR open ()
1309 flags
1310 .BR O_SYNC ,
1311 .BR O_DSYNC ,
1312 and
1313 .B O_RSYNC
1314 for controlling the behavior.
1315 Regardless of whether an implementation supports this option,
1316 it must at least support the use of
1317 .B O_SYNC
1318 for regular files.
1319 .P
1320 Linux implements
1321 .B O_SYNC
1322 and
1323 .BR O_DSYNC ,
1324 but not
1325 .BR O_RSYNC .
1326 Somewhat incorrectly, glibc defines
1327 .B O_RSYNC
1328 to have the same value as
1329 .BR O_SYNC .
1330 .RB ( O_RSYNC
1331 is defined in the Linux header file
1332 .I <asm/fcntl.h>
1333 on HP PA-RISC, but it is not used.)
1334 .P
1335 .B O_SYNC
1336 provides synchronized I/O
1337 .I file
1338 integrity completion,
1339 meaning write operations will flush data and all associated metadata
1340 to the underlying hardware.
1341 .B O_DSYNC
1342 provides synchronized I/O
1343 .I data
1344 integrity completion,
1345 meaning write operations will flush data
1346 to the underlying hardware,
1347 but will only flush metadata updates that are required
1348 to allow a subsequent read operation to complete successfully.
1349 Data integrity completion can reduce the number of disk operations
1350 that are required for applications that don't need the guarantees
1351 of file integrity completion.
1352 .P
1353 To understand the difference between the two types of completion,
1354 consider two pieces of file metadata:
1355 the file last modification timestamp
1356 .RI ( st_mtime )
1357 and the file length.
1358 All write operations will update the last file modification timestamp,
1359 but only writes that add data to the end of the
1360 file will change the file length.
1361 The last modification timestamp is not needed to ensure that
1362 a read completes successfully, but the file length is.
1363 Thus,
1364 .B O_DSYNC
1365 would only guarantee to flush updates to the file length metadata
1366 (whereas
1367 .B O_SYNC
1368 would also always flush the last modification timestamp metadata).
1369 .P
1370 Before Linux 2.6.33, Linux implemented only the
1371 .B O_SYNC
1372 flag for
1373 .BR open ().
1374 However, when that flag was specified,
1375 most filesystems actually provided the equivalent of synchronized I/O
1376 .I data
1377 integrity completion (i.e.,
1378 .B O_SYNC
1379 was actually implemented as the equivalent of
1380 .BR O_DSYNC ).
1381 .P
1382 Since Linux 2.6.33, proper
1383 .B O_SYNC
1384 support is provided.
1385 However, to ensure backward binary compatibility,
1386 .B O_DSYNC
1387 was defined with the same value as the historical
1388 .BR O_SYNC ,
1389 and
1390 .B O_SYNC
1391 was defined as a new (two-bit) flag value that includes the
1392 .B O_DSYNC
1393 flag value.
1394 This ensures that applications compiled against
1395 new headers get at least
1396 .B O_DSYNC
1397 semantics before Linux 2.6.33.
1398 .\"
1399 .SS C library/kernel differences
1400 Since glibc 2.26,
1401 the glibc wrapper function for
1402 .BR open ()
1403 employs the
1404 .BR openat ()
1405 system call, rather than the kernel's
1406 .BR open ()
1407 system call.
1408 For certain architectures, this is also true before glibc 2.26.
1409 .\"
1410 .SH STANDARDS
1411 .TP
1412 .BR open ()
1413 .TQ
1414 .BR creat ()
1415 .TQ
1416 .BR openat ()
1417 POSIX.1-2008.
1418 .P
1419 .BR openat2 (2)
1420 Linux.
1421 .P
1422 The
1423 .BR O_DIRECT ,
1424 .BR O_NOATIME ,
1425 .BR O_PATH ,
1426 and
1427 .B O_TMPFILE
1428 flags are Linux-specific.
1429 One must define
1430 .B _GNU_SOURCE
1431 to obtain their definitions.
1432 .P
1433 The
1434 .BR O_CLOEXEC ,
1435 .BR O_DIRECTORY ,
1436 and
1437 .B O_NOFOLLOW
1438 flags are not specified in POSIX.1-2001,
1439 but are specified in POSIX.1-2008.
1440 Since glibc 2.12, one can obtain their definitions by defining either
1441 .B _POSIX_C_SOURCE
1442 with a value greater than or equal to 200809L or
1443 .B _XOPEN_SOURCE
1444 with a value greater than or equal to 700.
1445 In glibc 2.11 and earlier, one obtains the definitions by defining
1446 .BR _GNU_SOURCE .
1447 .SH HISTORY
1448 .TP
1449 .BR open ()
1450 .TQ
1451 .BR creat ()
1452 SVr4, 4.3BSD, POSIX.1-2001.
1453 .TP
1454 .BR openat ()
1455 POSIX.1-2008.
1456 Linux 2.6.16,
1457 glibc 2.4.
1458 .SH NOTES
1459 Under Linux, the
1460 .B O_NONBLOCK
1461 flag is sometimes used in cases where one wants to open
1462 but does not necessarily have the intention to read or write.
1463 For example,
1464 this may be used to open a device in order to get a file descriptor
1465 for use with
1466 .BR ioctl (2).
1467 .P
1468 Note that
1469 .BR open ()
1470 can open device special files, but
1471 .BR creat ()
1472 cannot create them; use
1473 .BR mknod (2)
1474 instead.
1475 .P
1476 If the file is newly created, its
1477 .IR st_atime ,
1478 .IR st_ctime ,
1479 .I st_mtime
1480 fields
1481 (respectively, time of last access, time of last status change, and
1482 time of last modification; see
1483 .BR stat (2))
1484 are set
1485 to the current time, and so are the
1486 .I st_ctime
1487 and
1488 .I st_mtime
1489 fields of the
1490 parent directory.
1491 Otherwise, if the file is modified because of the
1492 .B O_TRUNC
1493 flag, its
1494 .I st_ctime
1495 and
1496 .I st_mtime
1497 fields are set to the current time.
1498 .P
1499 The files in the
1500 .IR /proc/ pid /fd
1501 directory show the open file descriptors of the process with the PID
1502 .IR pid .
1503 The files in the
1504 .IR /proc/ pid /fdinfo
1505 directory show even more information about these file descriptors.
1506 See
1507 .BR proc (5)
1508 for further details of both of these directories.
1509 .P
1510 The Linux header file
1511 .B <asm/fcntl.h>
1512 doesn't define
1513 .BR O_ASYNC ;
1514 the (BSD-derived)
1515 .B FASYNC
1516 synonym is defined instead.
1517 .\"
1518 .\"
1519 .SS Open file descriptions
1520 The term open file description is the one used by POSIX to refer to the
1521 entries in the system-wide table of open files.
1522 In other contexts, this object is
1523 variously also called an "open file object",
1524 a "file handle", an "open file table entry",
1525 or\[em]in kernel-developer parlance\[em]a
1526 .IR "struct file" .
1527 .P
1528 When a file descriptor is duplicated (using
1529 .BR dup (2)
1530 or similar),
1531 the duplicate refers to the same open file description
1532 as the original file descriptor,
1533 and the two file descriptors consequently share
1534 the file offset and file status flags.
1535 Such sharing can also occur between processes:
1536 a child process created via
1537 .BR fork (2)
1538 inherits duplicates of its parent's file descriptors,
1539 and those duplicates refer to the same open file descriptions.
1540 .P
1541 Each
1542 .BR open ()
1543 of a file creates a new open file description;
1544 thus, there may be multiple open file descriptions
1545 corresponding to a file inode.
1546 .P
1547 On Linux, one can use the
1548 .BR kcmp (2)
1549 .B KCMP_FILE
1550 operation to test whether two file descriptors
1551 (in the same process or in two different processes)
1552 refer to the same open file description.
1553 .\"
1554 .SS NFS
1555 There are many infelicities in the protocol underlying NFS, affecting
1556 amongst others
1557 .BR O_SYNC " and " O_NDELAY .
1558 .P
1559 On NFS filesystems with UID mapping enabled,
1560 .BR open ()
1561 may
1562 return a file descriptor but, for example,
1563 .BR read (2)
1564 requests are denied
1565 with
1566 .BR EACCES .
1567 This is because the client performs
1568 .BR open ()
1569 by checking the
1570 permissions, but UID mapping is performed by the server upon
1571 read and write requests.
1572 .\"
1573 .\"
1574 .SS FIFOs
1575 Opening the read or write end of a FIFO blocks until the other
1576 end is also opened (by another process or thread).
1577 See
1578 .BR fifo (7)
1579 for further details.
1580 .\"
1581 .\"
1582 .SS File access mode
1583 Unlike the other values that can be specified in
1584 .IR flags ,
1585 the
1586 .I "access mode"
1587 values
1588 .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR
1589 do not specify individual bits.
1590 Rather, they define the low order two bits of
1591 .IR flags ,
1592 and are defined respectively as 0, 1, and 2.
1593 In other words, the combination
1594 .B "O_RDONLY | O_WRONLY"
1595 is a logical error, and certainly does not have the same meaning as
1596 .BR O_RDWR .
1597 .P
1598 Linux reserves the special, nonstandard access mode 3 (binary 11) in
1599 .I flags
1600 to mean:
1601 check for read and write permission on the file and return a file descriptor
1602 that can't be used for reading or writing.
1603 This nonstandard access mode is used by some Linux drivers to return a
1604 file descriptor that is to be used only for device-specific
1605 .BR ioctl (2)
1606 operations.
1607 .\" See for example util-linux's disk-utils/setfdprm.c
1608 .\" For some background on access mode 3, see
1609 .\" http://thread.gmane.org/gmane.linux.kernel/653123
1610 .\" "[RFC] correct flags to f_mode conversion in __dentry_open"
1611 .\" LKML, 12 Mar 2008
1612 .\"
1613 .\"
1614 .SS Rationale for openat() and other "directory file descriptor" APIs
1615 .BR openat ()
1616 and the other system calls and library functions that take
1617 a directory file descriptor argument
1618 (i.e.,
1619 .BR execveat (2),
1620 .BR faccessat (2),
1621 .BR fanotify_mark (2),
1622 .BR fchmodat (2),
1623 .BR fchownat (2),
1624 .BR fspick (2),
1625 .BR fstatat (2),
1626 .BR futimesat (2),
1627 .BR linkat (2),
1628 .BR mkdirat (2),
1629 .BR mknodat (2),
1630 .BR mount_setattr (2),
1631 .BR move_mount (2),
1632 .BR name_to_handle_at (2),
1633 .BR open_tree (2),
1634 .BR openat2 (2),
1635 .BR readlinkat (2),
1636 .BR renameat (2),
1637 .BR renameat2 (2),
1638 .BR statx (2),
1639 .BR symlinkat (2),
1640 .BR unlinkat (2),
1641 .BR utimensat (2),
1642 .BR mkfifoat (3),
1643 and
1644 .BR scandirat (3))
1645 address two problems with the older interfaces that preceded them.
1646 Here, the explanation is in terms of the
1647 .BR openat ()
1648 call, but the rationale is analogous for the other interfaces.
1649 .P
1650 First,
1651 .BR openat ()
1652 allows an application to avoid race conditions that could
1653 occur when using
1654 .BR open ()
1655 to open files in directories other than the current working directory.
1656 These race conditions result from the fact that some component
1657 of the directory prefix given to
1658 .BR open ()
1659 could be changed in parallel with the call to
1660 .BR open ().
1661 Suppose, for example, that we wish to create the file
1662 .I dir1/dir2/xxx.dep
1663 if the file
1664 .I dir1/dir2/xxx
1665 exists.
1666 The problem is that between the existence check and the file-creation step,
1667 .I dir1
1668 or
1669 .I dir2
1670 (which might be symbolic links)
1671 could be modified to point to a different location.
1672 Such races can be avoided by
1673 opening a file descriptor for the target directory,
1674 and then specifying that file descriptor as the
1675 .I dirfd
1676 argument of (say)
1677 .BR fstatat (2)
1678 and
1679 .BR openat ().
1680 The use of the
1681 .I dirfd
1682 file descriptor also has other benefits:
1683 .IP \[bu] 3
1684 the file descriptor is a stable reference to the directory,
1685 even if the directory is renamed; and
1686 .IP \[bu]
1687 the open file descriptor prevents the underlying filesystem from
1688 being dismounted,
1689 just as when a process has a current working directory on a filesystem.
1690 .P
1691 Second,
1692 .BR openat ()
1693 allows the implementation of a per-thread "current working
1694 directory", via file descriptor(s) maintained by the application.
1695 (This functionality can also be obtained by tricks based
1696 on the use of
1697 .IR /proc/self/fd/ dirfd,
1698 but less efficiently.)
1699 .P
1700 The
1701 .I dirfd
1702 argument for these APIs can be obtained by using
1703 .BR open ()
1704 or
1705 .BR openat ()
1706 to open a directory (with either the
1707 .B O_RDONLY
1708 or the
1709 .B O_PATH
1710 flag).
1711 Alternatively, such a file descriptor can be obtained by applying
1712 .BR dirfd (3)
1713 to a directory stream created using
1714 .BR opendir (3).
1715 .P
1716 When these APIs are given a
1717 .I dirfd
1718 argument of
1719 .B AT_FDCWD
1720 or the specified pathname is absolute,
1721 then they handle their pathname argument in the same way as
1722 the corresponding conventional APIs.
1723 However, in this case, several of the APIs have a
1724 .I flags
1725 argument that provides access to functionality that is not available with
1726 the corresponding conventional APIs.
1727 .\"
1728 .\"
1729 .SS O_DIRECT
1730 The
1731 .B O_DIRECT
1732 flag may impose alignment restrictions on the length and address
1733 of user-space buffers and the file offset of I/Os.
1734 In Linux alignment
1735 restrictions vary by filesystem and kernel version and might be
1736 absent entirely.
1737 The handling of misaligned
1738 .B O_DIRECT
1739 I/Os also varies;
1740 they can either fail with
1741 .B EINVAL
1742 or fall back to buffered I/O.
1743 .P
1744 Since Linux 6.1,
1745 .B O_DIRECT
1746 support and alignment restrictions for a file can be queried using
1747 .BR statx (2),
1748 using the
1749 .B STATX_DIOALIGN
1750 flag.
1751 Support for
1752 .B STATX_DIOALIGN
1753 varies by filesystem;
1754 see
1755 .BR statx (2).
1756 .P
1757 Some filesystems provide their own interfaces for querying
1758 .B O_DIRECT
1759 alignment restrictions,
1760 for example the
1761 .B XFS_IOC_DIOINFO
1762 operation in
1763 .BR xfsctl (3).
1764 .B STATX_DIOALIGN
1765 should be used instead when it is available.
1766 .P
1767 If none of the above is available,
1768 then direct I/O support and alignment restrictions
1769 can only be assumed from known characteristics of the filesystem,
1770 the individual file,
1771 the underlying storage device(s),
1772 and the kernel version.
1773 In Linux 2.4,
1774 most filesystems based on block devices require that
1775 the file offset and the length and memory address of all I/O segments
1776 be multiples of the filesystem block size
1777 (typically 4096 bytes).
1778 In Linux 2.6.0,
1779 this was relaxed to the logical block size of the block device
1780 (typically 512 bytes).
1781 A block device's logical block size can be determined using the
1782 .BR ioctl (2)
1783 .B BLKSSZGET
1784 operation or from the shell using the command:
1785 .P
1786 .in +4n
1787 .EX
1788 blockdev \-\-getss
1789 .EE
1790 .in
1791 .P
1792 .B O_DIRECT
1793 I/Os should never be run concurrently with the
1794 .BR fork (2)
1795 system call,
1796 if the memory buffer is a private mapping
1797 (i.e., any mapping created with the
1798 .BR mmap (2)
1799 .B MAP_PRIVATE
1800 flag;
1801 this includes memory allocated on the heap and statically allocated buffers).
1802 Any such I/Os, whether submitted via an asynchronous I/O interface or from
1803 another thread in the process,
1804 should be completed before
1805 .BR fork (2)
1806 is called.
1807 Failure to do so can result in data corruption and undefined behavior in
1808 parent and child processes.
1809 This restriction does not apply when the memory buffer for the
1810 .B O_DIRECT
1811 I/Os was created using
1812 .BR shmat (2)
1813 or
1814 .BR mmap (2)
1815 with the
1816 .B MAP_SHARED
1817 flag.
1818 Nor does this restriction apply when the memory buffer has been advised as
1819 .B MADV_DONTFORK
1820 with
1821 .BR madvise (2),
1822 ensuring that it will not be available
1823 to the child after
1824 .BR fork (2).
1825 .P
1826 The
1827 .B O_DIRECT
1828 flag was introduced in SGI IRIX, where it has alignment
1829 restrictions similar to those of Linux 2.4.
1830 IRIX has also a
1831 .BR fcntl (2)
1832 call to query appropriate alignments, and sizes.
1833 FreeBSD 4.x introduced
1834 a flag of the same name, but without alignment restrictions.
1835 .P
1836 .B O_DIRECT
1837 support was added in Linux 2.4.10.
1838 Older Linux kernels simply ignore this flag.
1839 Some filesystems may not implement the flag, in which case
1840 .BR open ()
1841 fails with the error
1842 .B EINVAL
1843 if it is used.
1844 .P
1845 Applications should avoid mixing
1846 .B O_DIRECT
1847 and normal I/O to the same file,
1848 and especially to overlapping byte regions in the same file.
1849 Even when the filesystem correctly handles the coherency issues in
1850 this situation, overall I/O throughput is likely to be slower than
1851 using either mode alone.
1852 Likewise, applications should avoid mixing
1853 .BR mmap (2)
1854 of files with direct I/O to the same files.
1855 .P
1856 The behavior of
1857 .B O_DIRECT
1858 with NFS will differ from local filesystems.
1859 Older kernels, or
1860 kernels configured in certain ways, may not support this combination.
1861 The NFS protocol does not support passing the flag to the server, so
1862 .B O_DIRECT
1863 I/O will bypass the page cache only on the client; the server may
1864 still cache the I/O.
1865 The client asks the server to make the I/O
1866 synchronous to preserve the synchronous semantics of
1867 .BR O_DIRECT .
1868 Some servers will perform poorly under these circumstances, especially
1869 if the I/O size is small.
1870 Some servers may also be configured to
1871 lie to clients about the I/O having reached stable storage; this
1872 will avoid the performance penalty at some risk to data integrity
1873 in the event of server power failure.
1874 The Linux NFS client places no alignment restrictions on
1875 .B O_DIRECT
1876 I/O.
1877 .P
1878 In summary,
1879 .B O_DIRECT
1880 is a potentially powerful tool that should be used with caution.
1881 It is recommended that applications treat use of
1882 .B O_DIRECT
1883 as a performance option which is disabled by default.
1884 .SH BUGS
1885 Currently, it is not possible to enable signal-driven
1886 I/O by specifying
1887 .B O_ASYNC
1888 when calling
1889 .BR open ();
1890 use
1891 .BR fcntl (2)
1892 to enable this flag.
1893 .\" FIXME . Check bugzilla report on open(O_ASYNC)
1894 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
1895 .P
1896 One must check for two different error codes,
1897 .B EISDIR
1898 and
1899 .BR ENOENT ,
1900 when trying to determine whether the kernel supports
1901 .B O_TMPFILE
1902 functionality.
1903 .P
1904 When both
1905 .B O_CREAT
1906 and
1907 .B O_DIRECTORY
1908 are specified in
1909 .I flags
1910 and the file specified by
1911 .I pathname
1912 does not exist,
1913 .BR open ()
1914 will create a regular file (i.e.,
1915 .B O_DIRECTORY
1916 is ignored).
1917 .SH SEE ALSO
1918 .BR chmod (2),
1919 .BR chown (2),
1920 .BR close (2),
1921 .BR dup (2),
1922 .BR fcntl (2),
1923 .BR link (2),
1924 .BR lseek (2),
1925 .BR mknod (2),
1926 .BR mmap (2),
1927 .BR mount (2),
1928 .BR open_by_handle_at (2),
1929 .BR openat2 (2),
1930 .BR read (2),
1931 .BR socket (2),
1932 .BR stat (2),
1933 .BR umask (2),
1934 .BR unlink (2),
1935 .BR write (2),
1936 .BR fopen (3),
1937 .BR acl (5),
1938 .BR fifo (7),
1939 .BR inode (7),
1940 .BR path_resolution (7),
1941 .BR symlink (7)