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