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 2014-06-13 "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/types.h>
  57 .B #include <sys/stat.h>
  58 .B #include <fcntl.h>
  59 .sp
  60 .BI "int open(const char *" pathname ", int " flags );
  61 .BI "int open(const char *" pathname ", int " flags ", mode_t " mode );
  62
  63 .BI "int creat(const char *" pathname ", mode_t " mode );
  64 .sp
  65 .BI "int openat(int " dirfd ", const char *" pathname ", int " flags );
  66 .BI "int openat(int " dirfd ", const char *" pathname ", int " flags \
  67 ", mode_t " mode );
  68 .fi
  69 .sp
  70 .in -4n
  71 Feature Test Macro Requirements for glibc (see
  72 .BR feature_test_macros (7)):
  73 .in
  74 .sp
  75 .BR openat ():
  76 .PD 0
  77 .ad l
  78 .RS 4
  79 .TP 4
  80 Since glibc 2.10:
  81 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  82 .TP
  83 Before glibc 2.10:
  84 _ATFILE_SOURCE
  85 .RE
  86 .ad
  87 .PD
  88 .SH DESCRIPTION
  89 Given a
  90 .I pathname
  91 for a file,
  92 .BR open ()
  93 returns a file descriptor, a small, nonnegative integer
  94 for use in subsequent system calls
  95 .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)."
  96 The file descriptor returned by a successful call will be
  97 the lowest-numbered file descriptor not currently open for the process.
  98 .PP
  99 By default, the new file descriptor is set to remain open across an
 100 .BR execve (2)
 101 (i.e., the
 102 .B FD_CLOEXEC
 103 file descriptor flag described in
 104 .BR fcntl (2))
 105 is initially disabled; the
 106 .B O_CLOEXEC
 107 flag, described below, can be used to change this default.
 108 The file offset is set to the beginning of the file (see
 109 .BR lseek (2)).
 110 .PP
 111 A call to
 112 .BR open ()
 113 creates a new
 114 .IR "open file description" ,
 115 an entry in the system-wide table of open files.
 116 The open file description records the file offset and the file status flags
 117 (see below).
 118 A file descriptor is a reference to an open file description;
 119 this reference is unaffected if
 120 .I pathname
 121 is subsequently removed or modified to refer to a different file.
 122 For further details on open file descriptions, see NOTES.
 123 .PP
 124 The argument
 125 .I flags
 126 must include one of the following
 127 .IR "access modes" :
 128 .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
 129 These request opening the file read-only, write-only, or read/write,
 130 respectively.
 131
 132 In addition, zero or more file creation flags and file status flags
 133 can be
 134 .RI bitwise- or 'd
 135 in
 136 .IR flags .
 137 The
 138 .I file creation flags
 139 are
 140 .BR O_CLOEXEC ,
 141 .BR O_CREAT ,
 142 .BR O_DIRECTORY ,
 143 .BR O_EXCL ,
 144 .BR O_NOCTTY ,
 145 .BR O_NOFOLLOW ,
 146 .BR O_TMPFILE ,
 147 .BR O_TRUNC ,
 148 and
 149 .BR O_TTY_INIT .
 150 The
 151 .I file status flags
 152 are all of the remaining flags listed below.
 153 .\" SUSv4 divides the flags into:
 154 .\" * Access mode
 155 .\" * File creation
 156 .\" * File status
 157 .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
 158 .\" though it's not clear what the difference between "other" and
 159 .\" "File creation" flags is.  I raised an Aardvark to see if this
 160 .\" can be clarified in SUSv4; 10 Oct 2008.
 161 .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
 162 .\" TC1 (balloted in 2013), resolved this, so that those three constants
 163 .\" are also categorized" as file status flags.
 164 .\"
 165 The distinction between these two groups of flags is that
 166 the file status flags can be retrieved and (in some cases)
 167 modified; see
 168 .BR fcntl (2)
 169 for details.
 170
 171 The full list of file creation flags and file status flags is as follows:
 172 .TP
 173 .B O_APPEND
 174 The file is opened in append mode.
 175 Before each
 176 .BR write (2),
 177 the file offset is positioned at the end of the file,
 178 as if with
 179 .BR lseek (2).
 180 .B O_APPEND
 181 may lead to corrupted files on NFS filesystems if more than one process
 182 appends data to a file at once.
 183 .\" For more background, see
 184 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
 185 .\" http://nfs.sourceforge.net/
 186 This is because NFS does not support
 187 appending to a file, so the client kernel has to simulate it, which
 188 can't be done without a race condition.
 189 .TP
 190 .B O_ASYNC
 191 Enable signal-driven I/O:
 192 generate a signal
 193 .RB ( SIGIO
 194 by default, but this can be changed via
 195 .BR fcntl (2))
 196 when input or output becomes possible on this file descriptor.
 197 This feature is available only for terminals, pseudoterminals,
 198 sockets, and (since Linux 2.6) pipes and FIFOs.
 199 See
 200 .BR fcntl (2)
 201 for further details.
 202 See also BUGS, below.
 203 .TP
 204 .BR O_CLOEXEC " (since Linux 2.6.23)"
 205 .\" NOTE! several other man pages refer to this text
 206 Enable the close-on-exec flag for the new file descriptor.
 207 Specifying this flag permits a program to avoid additional
 208 .BR fcntl (2)
 209 .B F_SETFD
 210 operations to set the
 211 .B FD_CLOEXEC
 212 flag.
 213
 214 Note that the use of this flag is essential in some multithreaded programs,
 215 because using a separate
 216 .BR fcntl (2)
 217 .B F_SETFD
 218 operation to set the
 219 .B FD_CLOEXEC
 220 flag does not suffice to avoid race conditions
 221 where one thread opens a file descriptor and
 222 attempts to set its close-on-exec flag using
 223 .BR fcntl (2)
 224 at the same time as another thread does a
 225 .BR fork (2)
 226 plus
 227 .BR execve (2).
 228 Depending on the order of execution,
 229 the race may lead to the file descriptor returned by
 230 .BR open ()
 231 being unintentionally leaked to the program executed by the child process
 232 created by
 233 .BR fork (2).
 234 (This kind of race is in principle possible for any system call
 235 that creates a file descriptor whose close-on-exec flag should be set,
 236 and various other Linux system calls provide an equivalent of the
 237 .BR O_CLOEXEC
 238 flag to deal with this problem.)
 239 .\" This flag fixes only one form of the race condition;
 240 .\" The race can also occur with, for example, descriptors
 241 .\" returned by accept(), pipe(), etc.
 242 .TP
 243 .B O_CREAT
 244 If the file does not exist, it will be created.
 245 The owner (user ID) of the file is set to the effective user ID
 246 of the process.
 247 The group ownership (group ID) is set either to
 248 the effective group ID of the process or to the group ID of the
 249 parent directory (depending on filesystem type and mount options,
 250 and the mode of the parent directory; see the mount options
 251 .I bsdgroups
 252 and
 253 .I sysvgroups
 254 described in
 255 .BR mount (8)).
 256 .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
 257 .\" XFS (since 2.6.14).
 258 .RS
 259 .PP
 260 .I mode
 261 specifies the permissions to use in case a new file is created.
 262 This argument must be supplied when
 263 .B O_CREAT
 264 or
 265 .B O_TMPFILE
 266 is specified in
 267 .IR flags ;
 268 if neither
 269 .B O_CREAT
 270 nor
 271 .B O_TMPFILE
 272 is specified, then
 273 .I mode
 274 is ignored.
 275 The effective permissions are modified by
 276 the process's
 277 .I umask
 278 in the usual way: The permissions of the created file are
 279 .IR "(mode\ &\ ~umask)" .
 280 Note that this mode applies only to future accesses of the
 281 newly created file; the
 282 .BR open ()
 283 call that creates a read-only file may well return a read/write
 284 file descriptor.
 285 .PP
 286 The following symbolic constants are provided for
 287 .IR mode :
 288 .TP 9
 289 .B S_IRWXU
 290 00700 user (file owner) has read, write and execute permission
 291 .TP
 292 .B S_IRUSR
 293 00400 user has read permission
 294 .TP
 295 .B S_IWUSR
 296 00200 user has write permission
 297 .TP
 298 .B S_IXUSR
 299 00100 user has execute permission
 300 .TP
 301 .B S_IRWXG
 302 00070 group has read, write and execute permission
 303 .TP
 304 .B S_IRGRP
 305 00040 group has read permission
 306 .TP
 307 .B S_IWGRP
 308 00020 group has write permission
 309 .TP
 310 .B S_IXGRP
 311 00010 group has execute permission
 312 .TP
 313 .B S_IRWXO
 314 00007 others have read, write and execute permission
 315 .TP
 316 .B S_IROTH
 317 00004 others have read permission
 318 .TP
 319 .B S_IWOTH
 320 00002 others have write permission
 321 .TP
 322 .B S_IXOTH
 323 00001 others have execute permission
 324 .RE
 325 .TP
 326 .BR O_DIRECT " (since Linux 2.4.10)"
 327 Try to minimize cache effects of the I/O to and from this file.
 328 In general this will degrade performance, but it is useful in
 329 special situations, such as when applications do their own caching.
 330 File I/O is done directly to/from user-space buffers.
 331 The
 332 .B O_DIRECT
 333 flag on its own makes an effort to transfer data synchronously,
 334 but does not give the guarantees of the
 335 .B O_SYNC
 336 flag that data and necessary metadata are transferred.
 337 To guarantee synchronous I/O,
 338 .B O_SYNC
 339 must be used in addition to
 340 .BR O_DIRECT .
 341 See NOTES below for further discussion.
 342 .sp
 343 A semantically similar (but deprecated) interface for block devices
 344 is described in
 345 .BR raw (8).
 346 .TP
 347 .B O_DIRECTORY
 348 If \fIpathname\fP is not a directory, cause the open to fail.
 349 .\" But see the following and its replies:
 350 .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
 351 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
 352 .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
 353 This flag was added in kernel version 2.1.126, to
 354 avoid denial-of-service problems if
 355 .BR opendir (3)
 356 is called on a
 357 FIFO or tape device.
 358 .TP
 359 .B O_DSYNC
 360 Write operations on the file will complete according to the requirements of
 361 synchronized I/O
 362 .I data
 363 integrity completion.
 364
 365 By the time
 366 .BR write (2)
 367 (and similar)
 368 return, the output data
 369 has been transferred to the underlying hardware,
 370 along with any file metadata that would be required to retrieve that data
 371 (i.e., as though each
 372 .BR write (2)
 373 was followed by a call to
 374 .BR fdatasync (2)).
 375 .IR "See NOTES below" .
 376 .TP
 377 .B O_EXCL
 378 Ensure that this call creates the file:
 379 if this flag is specified in conjunction with
 380 .BR O_CREAT ,
 381 and
 382 .I pathname
 383 already exists, then
 384 .BR open ()
 385 will fail.
 386
 387 When these two flags are specified, symbolic links are not followed:
 388 .\" POSIX.1-2001 explicitly requires this behavior.
 389 if
 390 .I pathname
 391 is a symbolic link, then
 392 .BR open ()
 393 fails regardless of where the symbolic link points to.
 394
 395 In general, the behavior of
 396 .B O_EXCL
 397 is undefined if it is used without
 398 .BR O_CREAT .
 399 There is one exception: on Linux 2.6 and later,
 400 .B O_EXCL
 401 can be used without
 402 .B O_CREAT
 403 if
 404 .I pathname
 405 refers to a block device.
 406 If the block device is in use by the system (e.g., mounted),
 407 .BR open ()
 408 fails with the error
 409 .BR EBUSY .
 410
 411 On NFS,
 412 .B O_EXCL
 413 is supported only when using NFSv3 or later on kernel 2.6 or later.
 414 In NFS environments where
 415 .B O_EXCL
 416 support is not provided, programs that rely on it
 417 for performing locking tasks will contain a race condition.
 418 Portable programs that want to perform atomic file locking using a lockfile,
 419 and need to avoid reliance on NFS support for
 420 .BR O_EXCL ,
 421 can create a unique file on
 422 the same filesystem (e.g., incorporating hostname and PID), and use
 423 .BR link (2)
 424 to make a link to the lockfile.
 425 If
 426 .BR link (2)
 427 returns 0, the lock is successful.
 428 Otherwise, use
 429 .BR stat (2)
 430 on the unique file to check if its link count has increased to 2,
 431 in which case the lock is also successful.
 432 .TP
 433 .B O_LARGEFILE
 434 (LFS)
 435 Allow files whose sizes cannot be represented in an
 436 .I off_t
 437 (but can be represented in an
 438 .IR off64_t )
 439 to be opened.
 440 The
 441 .B _LARGEFILE64_SOURCE
 442 macro must be defined
 443 (before including
 444 .I any
 445 header files)
 446 in order to obtain this definition.
 447 Setting the
 448 .B _FILE_OFFSET_BITS
 449 feature test macro to 64 (rather than using
 450 .BR O_LARGEFILE )
 451 is the preferred
 452 method of accessing large files on 32-bit systems (see
 453 .BR feature_test_macros (7)).
 454 .TP
 455 .BR O_NOATIME " (since Linux 2.6.8)"
 456 Do not update the file last access time
 457 .RI ( st_atime
 458 in the inode)
 459 when the file is
 460 .BR read (2).
 461 This flag is intended for use by indexing or backup programs,
 462 where its use can significantly reduce the amount of disk activity.
 463 This flag may not be effective on all filesystems.
 464 One example is NFS, where the server maintains the access time.
 465 .\" The O_NOATIME flag also affects the treatment of st_atime
 466 .\" by mmap() and readdir(2), MTK, Dec 04.
 467 .TP
 468 .B O_NOCTTY
 469 If
 470 .I pathname
 471 refers to a terminal device\(emsee
 472 .BR tty (4)\(emit
 473 will not become the process's controlling terminal even if the
 474 process does not have one.
 475 .TP
 476 .B O_NOFOLLOW
 477 If \fIpathname\fP is a symbolic link, then the open fails.
 478 This is a FreeBSD extension, which was added to Linux in version 2.1.126.
 479 Symbolic links in earlier components of the pathname will still be
 480 followed.
 481 See also
 482 .BR O_PATH
 483 below.
 484 .\" The headers from glibc 2.0.100 and later include a
 485 .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
 486 .\" used\fP.
 487 .TP
 488 .BR O_NONBLOCK " or " O_NDELAY
 489 When possible, the file is opened in nonblocking mode.
 490 Neither the
 491 .BR open ()
 492 nor any subsequent operations on the file descriptor which is
 493 returned will cause the calling process to wait.
 494 For the handling of FIFOs (named pipes), see also
 495 .BR fifo (7).
 496 For a discussion of the effect of
 497 .B O_NONBLOCK
 498 in conjunction with mandatory file locks and with file leases, see
 499 .BR fcntl (2).
 500 .TP
 501 .BR O_PATH " (since Linux 2.6.39)"
 502 .\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
 503 .\" commit 326be7b484843988afe57566b627fb7a70beac56
 504 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
 505 .\"
 506 .\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
 507 .\"     Subject: Re: [PATCH] open(2): document O_PATH
 508 .\"     Newsgroups: gmane.linux.man, gmane.linux.kernel
 509 .\"
 510 Obtain a file descriptor that can be used for two purposes:
 511 to indicate a location in the filesystem tree and
 512 to perform operations that act purely at the file descriptor level.
 513 The file itself is not opened, and other file operations (e.g.,
 514 .BR read (2),
 515 .BR write (2),
 516 .BR fchmod (2),
 517 .BR fchown (2),
 518 .BR fgetxattr (2),
 519 .BR mmap (2))
 520 fail with the error
 521 .BR EBADF .
 522
 523 The following operations
 524 .I can
 525 be performed on the resulting file descriptor:
 526 .RS
 527 .IP * 3
 528 .BR close (2);
 529 .BR fchdir (2)
 530 (since Linux 3.5);
 531 .\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
 532 .BR fstat (2)
 533 (since Linux 3.6).
 534 .\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
 535 .IP *
 536 Duplicating the file descriptor
 537 .RB ( dup (2),
 538 .BR fcntl (2)
 539 .BR F_DUPFD ,
 540 etc.).
 541 .IP *
 542 Getting and setting file descriptor flags
 543 .RB ( fcntl (2)
 544 .BR F_GETFD
 545 and
 546 .BR F_SETFD ).
 547 .IP *
 548 Retrieving open file status flags using the
 549 .BR fcntl (2)
 550 .BR F_GETFL
 551 operation: the returned flags will include the bit
 552 .BR O_PATH .
 553 .IP *
 554 Passing the file descriptor as the
 555 .IR dirfd
 556 argument of
 557 .BR openat (2)
 558 and the other "*at()" system calls.
 559 This includes
 560 .BR linkat (2)
 561 with
 562 .BR AT_EMPTY_PATH
 563 (or via procfs using
 564 .BR AT_SYMLINK_FOLLOW )
 565 even if the file is not a directory.
 566 .IP *
 567 Passing the file descriptor to another process via a UNIX domain socket
 568 (see
 569 .BR SCM_RIGHTS
 570 in
 571 .BR unix (7)).
 572 .RE
 573 .IP
 574 When
 575 .B O_PATH
 576 is specified in
 577 .IR flags ,
 578 flag bits other than
 579 .BR O_DIRECTORY
 580 and
 581 .BR O_NOFOLLOW
 582 are ignored.
 583
 584 If
 585 .I pathname
 586 is a symbolic link and the
 587 .BR O_NOFOLLOW
 588 flag is also specified,
 589 then the call returns a file descriptor referring to the symbolic link.
 590 This file descriptor can be used as the
 591 .I dirfd
 592 argument in calls to
 593 .BR fchownat (2),
 594 .BR fstatat (2),
 595 .BR linkat (2),
 596 and
 597 .BR readlinkat (2)
 598 with an empty pathname to have the calls operate on the symbolic link.
 599 .TP
 600 .B O_SYNC
 601 Write operations on the file will complete according to the requirements of
 602 synchronized I/O
 603 .I file
 604 integrity completion
 605 (by contrast with contrast with the
 606 synchronized I/O
 607 .I data
 608 integrity completion
 609 provided by
 610 .BR O_DSYNC .)
 611
 612 By the time
 613 .BR write (2)
 614 (and similar)
 615 return, the output data and associated file metadata
 616 have been transferred to the underlying hardware
 617 (i.e., as though each
 618 .BR write (2)
 619 was followed by a call to
 620 .BR fsync (2)).
 621 .IR "See NOTES below" .
 622 .TP
 623 .BR O_TMPFILE " (since Linux 3.11)"
 624 .\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
 625 .\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
 626 .\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
 627 Create an unnamed temporary file.
 628 The
 629 .I pathname
 630 argument specifies a directory;
 631 an unnamed inode will be created in that directory's filesystem.
 632 Anything written to the resulting file will be lost when
 633 the last file descriptor is closed, unless the file is given a name.
 634
 635 .B O_TMPFILE
 636 must be specified with one of
 637 .B O_RDWR
 638 or
 639 .B O_WRONLY
 640 and, optionally,
 641 .BR O_EXCL .
 642 If
 643 .B O_EXCL
 644 is not specified, then
 645 .BR linkat (2)
 646 can be used to link the temporary file into the filesystem, making it
 647 permanent, using code like the following:
 648
 649 .in +4n
 650 .nf
 651 char path[PATH_MAX];
 652 fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
 653                         S_IRUSR | S_IWUSR);
 654
 655 /* File I/O on 'fd'... */
 656
 657 snprintf(path, PATH_MAX,  "/proc/self/fd/%d", fd);
 658 linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
 659                         AT_SYMLINK_FOLLOW);
 660 .fi
 661 .in
 662
 663 In this case,
 664 the
 665 .BR open ()
 666 .I mode
 667 argument determines the file permission mode, as with
 668 .BR O_CREAT .
 669
 670 Specifying
 671 .B O_EXCL
 672 in conjunction with
 673 .B O_TMPFILE
 674 prevents a temporary file from being linked into the filesystem
 675 in the above manner.
 676 (Note that the meaning of
 677 .B O_EXCL
 678 in this case is different from the meaning of
 679 .B O_EXCL
 680 otherwise.)
 681
 682
 683 There are two main use cases for
 684 .\" Inspired by http://lwn.net/Articles/559147/
 685 .BR O_TMPFILE :
 686 .RS
 687 .IP * 3
 688 Improved
 689 .BR tmpfile (3)
 690 functionality: race-free creation of temporary files that
 691 (1) are automatically deleted when closed;
 692 (2) can never be reached via any pathname;
 693 (3) are not subject to symlink attacks; and
 694 (4) do not require the caller to devise unique names.
 695 .IP *
 696 Creating a file that is initially invisible, which is then populated
 697 with data and adjusted to have appropriate filesystem attributes
 698 .RB ( chown (2),
 699 .BR chmod (2),
 700 .BR fsetxattr (2),
 701 etc.)
 702 before being atomically linked into the filesystem
 703 in a fully formed state (using
 704 .BR linkat (2)
 705 as described above).
 706 .RE
 707 .IP
 708 .B O_TMPFILE
 709 requires support by the underlying filesystem;
 710 only a subset of Linux filesystems provide that support.
 711 In the initial implementation, support was provided in
 712 the ext2, ext3, ext4, UDF, Minix, and shmem filesystems.
 713 XFS support was added
 714 .\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
 715 .\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
 716 in Linux 3.15.
 717 .TP
 718 .B O_TRUNC
 719 If the file already exists and is a regular file and the access mode allows
 720 writing (i.e., is
 721 .B O_RDWR
 722 or
 723 .BR O_WRONLY )
 724 it will be truncated to length 0.
 725 If the file is a FIFO or terminal device file, the
 726 .B O_TRUNC
 727 flag is ignored.
 728 Otherwise, the effect of
 729 .B O_TRUNC
 730 is unspecified.
 731 .SS creat()
 732 .BR creat ()
 733 is equivalent to
 734 .BR open ()
 735 with
 736 .I flags
 737 equal to
 738 .BR O_CREAT|O_WRONLY|O_TRUNC .
 739 .SS openat()
 740 The
 741 .BR openat ()
 742 system call operates in exactly the same way as
 743 .BR open (),
 744 except for the differences described here.
 745
 746 If the pathname given in
 747 .I pathname
 748 is relative, then it is interpreted relative to the directory
 749 referred to by the file descriptor
 750 .I dirfd
 751 (rather than relative to the current working directory of
 752 the calling process, as is done by
 753 .BR open ()
 754 for a relative pathname).
 755
 756 If
 757 .I pathname
 758 is relative and
 759 .I dirfd
 760 is the special value
 761 .BR AT_FDCWD ,
 762 then
 763 .I pathname
 764 is interpreted relative to the current working
 765 directory of the calling process (like
 766 .BR open ()).
 767
 768 If
 769 .I pathname
 770 is absolute, then
 771 .I dirfd
 772 is ignored.
 773 .SH RETURN VALUE
 774 .BR open (),
 775 .BR openat (),
 776 and
 777 .BR creat ()
 778 return the new file descriptor, or \-1 if an error occurred
 779 (in which case,
 780 .I errno
 781 is set appropriately).
 782 .SH ERRORS
 783 .BR open (),
 784 .BR openat (),
 785 and
 786 .BR creat ()
 787 can fail with the following errors:
 788 .TP
 789 .B EACCES
 790 The requested access to the file is not allowed, or search permission
 791 is denied for one of the directories in the path prefix of
 792 .IR pathname ,
 793 or the file did not exist yet and write access to the parent directory
 794 is not allowed.
 795 (See also
 796 .BR path_resolution (7).)
 797 .TP
 798 .B EDQUOT
 799 Where
 800 .B O_CREAT
 801 is specified, the file does not exist, and the user's quota of disk
 802 blocks or inodes on the filesystem has been exhausted.
 803 .TP
 804 .B EEXIST
 805 .I pathname
 806 already exists and
 807 .BR O_CREAT " and " O_EXCL
 808 were used.
 809 .TP
 810 .B EFAULT
 811 .I pathname
 812 points outside your accessible address space.
 813 .TP
 814 .B EFBIG
 815 See
 816 .BR EOVERFLOW .
 817 .TP
 818 .B EINTR
 819 While blocked waiting to complete an open of a slow device
 820 (e.g., a FIFO; see
 821 .BR fifo (7)),
 822 the call was interrupted by a signal handler; see
 823 .BR signal (7).
 824 .TP
 825 .B EINVAL
 826 The filesystem does not support the
 827 .BR O_DIRECT
 828 flag.
 829 See
 830 .BR NOTES
 831 for more information.
 832 .TP
 833 .B EINVAL
 834 Invalid value in
 835 .\" In particular, __O_TMPFILE instead of O_TMPFILE
 836 .IR flags .
 837 .TP
 838 .B EINVAL
 839 .B O_TMPFILE
 840 was specified in
 841 .IR flags ,
 842 but neither
 843 .B O_WRONLY
 844 nor
 845 .B O_RDWR
 846 was specified.
 847 .TP
 848 .B EISDIR
 849 .I pathname
 850 refers to a directory and the access requested involved writing
 851 (that is,
 852 .B O_WRONLY
 853 or
 854 .B O_RDWR
 855 is set).
 856 .TP
 857 .B EISDIR
 858 .I pathname
 859 refers to an existing directory,
 860 .B O_TMPFILE
 861 and one of
 862 .B O_WRONLY
 863 or
 864 .B O_RDWR
 865 were specified in
 866 .IR flags ,
 867 but this kernel version does not provide the
 868 .B O_TMPFILE
 869 functionality.
 870 .TP
 871 .B ELOOP
 872 Too many symbolic links were encountered in resolving
 873 .IR pathname .
 874 .TP
 875 .B ELOOP
 876 .I pathname
 877 was a symbolic link, and
 878 .I flags
 879 specified
 880 .BR O_NOFOLLOW
 881 but not
 882 .BR O_PATH .
 883 .TP
 884 .B EMFILE
 885 The process already has the maximum number of files open.
 886 .TP
 887 .B ENAMETOOLONG
 888 .I pathname
 889 was too long.
 890 .TP
 891 .B ENFILE
 892 The system limit on the total number of open files has been reached.
 893 .TP
 894 .B ENODEV
 895 .I pathname
 896 refers to a device special file and no corresponding device exists.
 897 (This is a Linux kernel bug; in this situation
 898 .B ENXIO
 899 must be returned.)
 900 .TP
 901 .B ENOENT
 902 .B O_CREAT
 903 is not set and the named file does not exist.
 904 Or, a directory component in
 905 .I pathname
 906 does not exist or is a dangling symbolic link.
 907 .TP
 908 .B ENOENT
 909 .I pathname
 910 refers to a nonexistent directory,
 911 .B O_TMPFILE
 912 and one of
 913 .B O_WRONLY
 914 or
 915 .B O_RDWR
 916 were specified in
 917 .IR flags ,
 918 but this kernel version does not provide the
 919 .B O_TMPFILE
 920 functionality.
 921 .TP
 922 .B ENOMEM
 923 Insufficient kernel memory was available.
 924 .TP
 925 .B ENOSPC
 926 .I pathname
 927 was to be created but the device containing
 928 .I pathname
 929 has no room for the new file.
 930 .TP
 931 .B ENOTDIR
 932 A component used as a directory in
 933 .I pathname
 934 is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
 935 .I pathname
 936 was not a directory.
 937 .TP
 938 .B ENXIO
 939 .BR O_NONBLOCK " | " O_WRONLY
 940 is set, the named file is a FIFO, and
 941 no process has the FIFO open for reading.
 942 Or, the file is a device special file and no corresponding device exists.
 943 .TP
 944 .BR EOPNOTSUPP
 945 The filesystem containing
 946 .I pathname
 947 does not support
 948 .BR O_TMPFILE .
 949 .TP
 950 .B EOVERFLOW
 951 .I pathname
 952 refers to a regular file that is too large to be opened.
 953 The usual scenario here is that an application compiled
 954 on a 32-bit platform without
 955 .I -D_FILE_OFFSET_BITS=64
 956 tried to open a file whose size exceeds
 957 .I (2<<31)-1
 958 bits;
 959 see also
 960 .B O_LARGEFILE
 961 above.
 962 This is the error specified by POSIX.1-2001;
 963 in kernels before 2.6.24, Linux gave the error
 964 .B EFBIG
 965 for this case.
 966 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
 967 .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
 968 .\" Reported 2006-10-03
 969 .TP
 970 .B EPERM
 971 The
 972 .B O_NOATIME
 973 flag was specified, but the effective user ID of the caller
 974 .\" Strictly speaking, it's the filesystem UID... (MTK)
 975 did not match the owner of the file and the caller was not privileged
 976 .RB ( CAP_FOWNER ).
 977 .TP
 978 .B EROFS
 979 .I pathname
 980 refers to a file on a read-only filesystem and write access was
 981 requested.
 982 .TP
 983 .B ETXTBSY
 984 .I pathname
 985 refers to an executable image which is currently being executed and
 986 write access was requested.
 987 .TP
 988 .B EWOULDBLOCK
 989 The
 990 .B O_NONBLOCK
 991 flag was specified, and an incompatible lease was held on the file
 992 (see
 993 .BR fcntl (2)).
 994 .PP
 995 The following additional errors can occur for
 996 .BR openat ():
 997 .TP
 998 .B EBADF
 999 .I dirfd
1000 is not a valid file descriptor.
1001 .TP
1002 .B ENOTDIR
1003 .I pathname
1004 is a relative pathname and
1005 .I dirfd
1006 is a file descriptor referring to a file other than a directory.
1007 .SH VERSIONS
1008 .BR openat ()
1009 was added to Linux in kernel 2.6.16;
1010 library support was added to glibc in version 2.4.
1011 .SH CONFORMING TO
1012 .BR open (),
1013 .BR creat ()
1014 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
1015
1016 .BR openat ():
1017 POSIX.1-2008.
1018
1019 The
1020 .BR O_DIRECT ,
1021 .BR O_NOATIME ,
1022 .BR O_PATH ,
1023 and
1024 .BR O_TMPFILE
1025 flags are Linux-specific.
1026 One must define
1027 .B _GNU_SOURCE
1028 to obtain their definitions.
1029
1030 The
1031 .BR O_CLOEXEC ,
1032 .BR O_DIRECTORY ,
1033 and
1034 .BR O_NOFOLLOW
1035 flags are not specified in POSIX.1-2001,
1036 but are specified in POSIX.1-2008.
1037 Since glibc 2.12, one can obtain their definitions by defining either
1038 .B _POSIX_C_SOURCE
1039 with a value greater than or equal to 200809L or
1040 .BR _XOPEN_SOURCE
1041 with a value greater than or equal to 700.
1042 In glibc 2.11 and earlier, one obtains the definitions by defining
1043 .BR _GNU_SOURCE .
1044
1045 As noted in
1046 .BR feature_test_macros (7),
1047 feature test macros such as
1048 .BR _POSIX_C_SOURCE ,
1049 .BR _XOPEN_SOURCE ,
1050 and
1051 .B _GNU_SOURCE
1052 must be defined before including
1053 .I any
1054 header files.
1055 .SH NOTES
1056 Under Linux, the
1057 .B O_NONBLOCK
1058 flag indicates that one wants to open
1059 but does not necessarily have the intention to read or write.
1060 This is typically used to open devices in order to get a file descriptor
1061 for use with
1062 .BR ioctl (2).
1063
1064 .LP
1065 The (undefined) effect of
1066 .B O_RDONLY | O_TRUNC
1067 varies among implementations.
1068 On many systems the file is actually truncated.
1069 .\" Linux 2.0, 2.5: truncate
1070 .\" Solaris 5.7, 5.8: truncate
1071 .\" Irix 6.5: truncate
1072 .\" Tru64 5.1B: truncate
1073 .\" HP-UX 11.22: truncate
1074 .\" FreeBSD 4.7: truncate
1075
1076 Note that
1077 .BR open ()
1078 can open device special files, but
1079 .BR creat ()
1080 cannot create them; use
1081 .BR mknod (2)
1082 instead.
1083
1084 If the file is newly created, its
1085 .IR st_atime ,
1086 .IR st_ctime ,
1087 .I st_mtime
1088 fields
1089 (respectively, time of last access, time of last status change, and
1090 time of last modification; see
1091 .BR stat (2))
1092 are set
1093 to the current time, and so are the
1094 .I st_ctime
1095 and
1096 .I st_mtime
1097 fields of the
1098 parent directory.
1099 Otherwise, if the file is modified because of the
1100 .B O_TRUNC
1101 flag, its st_ctime and st_mtime fields are set to the current time.
1102 .\"
1103 .\"
1104 .SS Open file descriptions
1105 The term open file description is the one used by POSIX to refer to the
1106 entries in the system-wide table of open files.
1107 In other contexts, this object is
1108 variously also called an "open file object",
1109 a "file handle", an "open file table entry",
1110 or\(emin kernel-developer parlance\(ema
1111 .IR "struct file" .
1112
1113 When a file descriptor is duplicated (using
1114 .BR dup (2)
1115 or similar),
1116 the duplicate refers to the same open file description
1117 as the original file descriptor,
1118 and the two file descriptors consequently share
1119 the file offset and file status flags.
1120 Such sharing can also occur between processes:
1121 a child process created via
1122 .BR fork (2)
1123 inherits duplicates of its parent's file descriptors,
1124 and those duplicates refer to the same open file descriptions.
1125
1126 Each
1127 .BR open (2)
1128 of a file creates a new open file description;
1129 thus, there may be multiple open file descriptions
1130 corresponding to a file inode.
1131 .\"
1132 .\"
1133 .SS Synchronized I/O
1134 The POSIX.1-2008 "synchronized I/O" option
1135 specifies different variants of synchronized I/O,
1136 and specifies the
1137 .BR open ()
1138 flags
1139 .BR O_SYNC ,
1140 .BR O_DSYNC ,
1141 and
1142 .BR O_RSYNC
1143 for controlling the behavior.
1144 Regardless of whether an implementation supports this option,
1145 it must at least support the use of
1146 .BR O_SYNC
1147 for regular files.
1148
1149 Linux implements
1150 .BR O_SYNC
1151 and
1152 .BR O_DSYNC ,
1153 but not
1154 .BR O_RSYNC .
1155 (Somewhat incorrectly, glibc defines
1156 .BR O_RSYNC
1157 to have the same value as
1158 .BR O_SYNC .)
1159
1160 .BR O_SYNC
1161 provides synchronized I/O
1162 .I file
1163 integrity completion,
1164 meaning write operations will flush data and all associated metadata
1165 to the underlying hardware.
1166 .BR O_DSYNC
1167 provides synchronized I/O
1168 .I data
1169 integrity completion,
1170 meaning write operations will flush data
1171 to the underlying hardware,
1172 but will only flush metadata updates that are required
1173 to allow a subsequent read operation to complete successfully.
1174 Data integrity completion can reduce the number of disk operations
1175 that are required for applications that don't need the guarantees
1176 of file integrity completion.
1177
1178 To understand the difference between the the two types of completion,
1179 consider two pieces of file metadata:
1180 the file last modification timestamp
1181 .RI ( st_mtime )
1182 and the file length.
1183 All write operations will update the last file modification timestamp,
1184 but only writes that add data to the end of the
1185 file will change the file length.
1186 The last modification timestamp is not needed to ensure that
1187 a read completes successfully, but the file length is.
1188 Thus,
1189 .BR O_DSYNC
1190 would only guarantee to flush updates to the file length metadata
1191 (whereas
1192 .BR O_SYNC
1193 would also always flush the last modification timestamp metadata).
1194
1195 Before Linux 2.6.33, Linux implemented only the
1196 .BR O_SYNC
1197 flag for
1198 .BR open ().
1199 However, when that flag was specified,
1200 most filesystems actually provided the equivalent of synchronized I/O
1201 .I data
1202 integrity completion (i.e.,
1203 .BR O_SYNC
1204 was actually implemented as the equivalent of
1205 .BR O_DSYNC ).
1206
1207 Since Linux 2.6.33, proper
1208 .BR O_SYNC
1209 support is provided.
1210 However, to ensure backward binary compatibility,
1211 .BR O_DSYNC
1212 was defined with the same value as the historical
1213 .BR O_SYNC ,
1214 and
1215 .BR O_SYNC
1216 was defined as a new (two-bit) flag value that includes the
1217 .BR O_DSYNC
1218 flag value.
1219 This ensures that applications compiled against
1220 new headers get at least
1221 .BR O_DSYNC
1222 semantics on pre-2.6.33 kernels.
1223 .\"
1224 .\"
1225 .SS NFS
1226 There are many infelicities in the protocol underlying NFS, affecting
1227 amongst others
1228 .BR O_SYNC " and " O_NDELAY .
1229
1230 On NFS filesystems with UID mapping enabled,
1231 .BR open ()
1232 may
1233 return a file descriptor but, for example,
1234 .BR read (2)
1235 requests are denied
1236 with \fBEACCES\fP.
1237 This is because the client performs
1238 .BR open ()
1239 by checking the
1240 permissions, but UID mapping is performed by the server upon
1241 read and write requests.
1242 .\"
1243 .\"
1244 .SS File access mode
1245 Unlike the other values that can be specified in
1246 .IR flags ,
1247 the
1248 .I "access mode"
1249 values
1250 .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR
1251 do not specify individual bits.
1252 Rather, they define the low order two bits of
1253 .IR flags ,
1254 and are defined respectively as 0, 1, and 2.
1255 In other words, the combination
1256 .B "O_RDONLY | O_WRONLY"
1257 is a logical error, and certainly does not have the same meaning as
1258 .BR O_RDWR .
1259
1260 Linux reserves the special, nonstandard access mode 3 (binary 11) in
1261 .I flags
1262 to mean:
1263 check for read and write permission on the file and return a descriptor
1264 that can't be used for reading or writing.
1265 This nonstandard access mode is used by some Linux drivers to return a
1266 descriptor that is to be used only for device-specific
1267 .BR ioctl (2)
1268 operations.
1269 .\" See for example util-linux's disk-utils/setfdprm.c
1270 .\" For some background on access mode 3, see
1271 .\" http://thread.gmane.org/gmane.linux.kernel/653123
1272 .\" "[RFC] correct flags to f_mode conversion in __dentry_open"
1273 .\" LKML, 12 Mar 2008
1274 .\"
1275 .\"
1276 .SS Rationale for openat() and other "directory file descriptor" APIs
1277 .BR openat ()
1278 and the other system calls and library functions that take
1279 a directory file descriptor argument
1280 (i.e.,
1281 .BR faccessat (2),
1282 .BR fanotify_mark (2),
1283 .BR fchmodat (2),
1284 .BR fchownat (2),
1285 .BR fstatat (2),
1286 .BR futimesat (2),
1287 .BR linkat (2),
1288 .BR mkdirat (2),
1289 .BR mknodat (2),
1290 .BR name_to_handle_at (2),
1291 .BR readlinkat (2),
1292 .BR renameat (2),
1293 .BR symlinkat (2),
1294 .BR unlinkat (2),
1295 .BR utimensat (2)
1296 .BR mkfifoat (3),
1297 and
1298 .BR scandirat (3))
1299 are supported
1300 for two reasons.
1301 Here, the explanation is in terms of the
1302 .BR openat ()
1303 call, but the rationale is analogous for the other interfaces.
1304
1305 First,
1306 .BR openat ()
1307 allows an application to avoid race conditions that could
1308 occur when using
1309 .BR open ()
1310 to open files in directories other than the current working directory.
1311 These race conditions result from the fact that some component
1312 of the directory prefix given to
1313 .BR open ()
1314 could be changed in parallel with the call to
1315 .BR open ().
1316 Such races can be avoided by
1317 opening a file descriptor for the target directory,
1318 and then specifying that file descriptor as the
1319 .I dirfd
1320 argument of
1321 .BR openat ().
1322
1323 Second,
1324 .BR openat ()
1325 allows the implementation of a per-thread "current working
1326 directory", via file descriptor(s) maintained by the application.
1327 (This functionality can also be obtained by tricks based
1328 on the use of
1329 .IR /proc/self/fd/ dirfd,
1330 but less efficiently.)
1331 .\"
1332 .\"
1333 .SS O_DIRECT
1334 .LP
1335 The
1336 .B O_DIRECT
1337 flag may impose alignment restrictions on the length and address
1338 of user-space buffers and the file offset of I/Os.
1339 In Linux alignment
1340 restrictions vary by filesystem and kernel version and might be
1341 absent entirely.
1342 However there is currently no filesystem\-independent
1343 interface for an application to discover these restrictions for a given
1344 file or filesystem.
1345 Some filesystems provide their own interfaces
1346 for doing so, for example the
1347 .B XFS_IOC_DIOINFO
1348 operation in
1349 .BR xfsctl (3).
1350 .LP
1351 Under Linux 2.4, transfer sizes, and the alignment of the user buffer
1352 and the file offset must all be multiples of the logical block size
1353 of the filesystem.
1354 Since Linux 2.6.0, alignment to the logical block size of the
1355 underlying storage (typically 512 bytes) suffices.
1356 The logical block size can be determined using the
1357 .BR ioctl (2)
1358 .B BLKSSZGET
1359 operation or from the shell using the command:
1360
1361     blockdev \-\-getss
1362 .LP
1363 .B O_DIRECT
1364 I/Os should never be run concurrently with the
1365 .BR fork (2)
1366 system call,
1367 if the memory buffer is a private mapping
1368 (i.e., any mapping created with the
1369 .BR mmap (2)
1370 .BR MAP_PRIVATE
1371 flag;
1372 this includes memory allocated on the heap and statically allocated buffers).
1373 Any such I/Os, whether submitted via an asynchronous I/O interface or from
1374 another thread in the process,
1375 should be completed before
1376 .BR fork (2)
1377 is called.
1378 Failure to do so can result in data corruption and undefined behavior in
1379 parent and child processes.
1380 This restriction does not apply when the memory buffer for the
1381 .B O_DIRECT
1382 I/Os was created using
1383 .BR shmat (2)
1384 or
1385 .BR mmap (2)
1386 with the
1387 .B MAP_SHARED
1388 flag.
1389 Nor does this restriction apply when the memory buffer has been advised as
1390 .B MADV_DONTFORK
1391 with
1392 .BR madvise (2),
1393 ensuring that it will not be available
1394 to the child after
1395 .BR fork (2).
1396 .LP
1397 The
1398 .B O_DIRECT
1399 flag was introduced in SGI IRIX, where it has alignment
1400 restrictions similar to those of Linux 2.4.
1401 IRIX has also a
1402 .BR fcntl (2)
1403 call to query appropriate alignments, and sizes.
1404 FreeBSD 4.x introduced
1405 a flag of the same name, but without alignment restrictions.
1406 .LP
1407 .B O_DIRECT
1408 support was added under Linux in kernel version 2.4.10.
1409 Older Linux kernels simply ignore this flag.
1410 Some filesystems may not implement the flag and
1411 .BR open ()
1412 will fail with
1413 .B EINVAL
1414 if it is used.
1415 .LP
1416 Applications should avoid mixing
1417 .B O_DIRECT
1418 and normal I/O to the same file,
1419 and especially to overlapping byte regions in the same file.
1420 Even when the filesystem correctly handles the coherency issues in
1421 this situation, overall I/O throughput is likely to be slower than
1422 using either mode alone.
1423 Likewise, applications should avoid mixing
1424 .BR mmap (2)
1425 of files with direct I/O to the same files.
1426 .LP
1427 The behavior of
1428 .B O_DIRECT
1429 with NFS will differ from local filesystems.
1430 Older kernels, or
1431 kernels configured in certain ways, may not support this combination.
1432 The NFS protocol does not support passing the flag to the server, so
1433 .B O_DIRECT
1434 I/O will bypass the page cache only on the client; the server may
1435 still cache the I/O.
1436 The client asks the server to make the I/O
1437 synchronous to preserve the synchronous semantics of
1438 .BR O_DIRECT .
1439 Some servers will perform poorly under these circumstances, especially
1440 if the I/O size is small.
1441 Some servers may also be configured to
1442 lie to clients about the I/O having reached stable storage; this
1443 will avoid the performance penalty at some risk to data integrity
1444 in the event of server power failure.
1445 The Linux NFS client places no alignment restrictions on
1446 .B O_DIRECT
1447 I/O.
1448 .PP
1449 In summary,
1450 .B O_DIRECT
1451 is a potentially powerful tool that should be used with caution.
1452 It is recommended that applications treat use of
1453 .B O_DIRECT
1454 as a performance option which is disabled by default.
1455 .PP
1456 .RS
1457 "The thing that has always disturbed me about O_DIRECT is that the whole
1458 interface is just stupid, and was probably designed by a deranged monkey
1459 on some serious mind-controlling substances."\(emLinus
1460 .RE
1461 .SH BUGS
1462 Currently, it is not possible to enable signal-driven
1463 I/O by specifying
1464 .B O_ASYNC
1465 when calling
1466 .BR open ();
1467 use
1468 .BR fcntl (2)
1469 to enable this flag.
1470 .\" FIXME . Check bugzilla report on open(O_ASYNC)
1471 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
1472
1473 One must check for two different error codes,
1474 .B EISDIR
1475 and
1476 .BR ENOENT ,
1477 when trying to determine whether the kernel supports
1478 .B O_TMPFILE
1479 functionality.
1480 .SH SEE ALSO
1481 .BR chmod (2),
1482 .BR chown (2),
1483 .BR close (2),
1484 .BR dup (2),
1485 .BR fcntl (2),
1486 .BR link (2),
1487 .BR lseek (2),
1488 .BR mknod (2),
1489 .BR mmap (2),
1490 .BR mount (2),
1491 .BR open_by_handle_at (2),
1492 .BR read (2),
1493 .BR socket (2),
1494 .BR stat (2),
1495 .BR umask (2),
1496 .BR unlink (2),
1497 .BR write (2),
1498 .BR fopen (3),
1499 .BR fifo (7),
1500 .BR path_resolution (7),
1501 .BR symlink (7)