man2/open.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   4 .\"                               1993 Michael Haardt, Ian Jackson.
   5 .\"                               2008 Greg Banks
   6 .\"
   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 .\"
  27 .\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
  28 .\" Modified 1994-08-21 by Michael Haardt
  29 .\" Modified 1996-04-13 by Andries Brouwer <aeb@cwi.nl>
  30 .\" Modified 1996-05-13 by Thomas Koenig
  31 .\" Modified 1996-12-20 by Michael Haardt
  32 .\" Modified 1999-02-19 by Andries Brouwer <aeb@cwi.nl>
  33 .\" Modified 1998-11-28 by Joseph S. Myers <jsm28@hermes.cam.ac.uk>
  34 .\" Modified 1999-06-03 by Michael Haardt
  35 .\" Modified 2002-05-07 by Michael Kerrisk <mtk.manpages@gmail.com>
  36 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  37 .\" 2004-12-08, mtk, reordered flags list alphabetically
  38 .\" 2004-12-08, Martin Pool <mbp@sourcefrog.net> (& mtk), added O_NOATIME
  39 .\" 2007-09-18, mtk, Added description of O_CLOEXEC + other minor edits
  40 .\" 2008-01-03, mtk, with input from Trond Myklebust
  41 .\"     <trond.myklebust@fys.uio.no> and Timo Sirainen <tss@iki.fi>
  42 .\"     Rewrite description of O_EXCL.
  43 .\" 2008-01-11, Greg Banks <gnb@melbourne.sgi.com>: add more detail
  44 .\"     on O_DIRECT.
  45 .\" 2008-02-26, Michael Haardt: Reorganized text for O_CREAT and mode
  46 .\"
  47 .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
  48 .\" O_TTYINIT.  Eventually these may need to be documented.  --mtk
  49 .\" FIXME Linux 2.6.33 has O_DSYNC, and a hidden __O_SYNC.
  50 .\" FIXME: Linux 2.6.39 added O_PATH
  51 .\"
  52 .TH OPEN 2 2013-01-27 "Linux" "Linux Programmer's Manual"
  53 .SH NAME
  54 open, creat \- open and possibly create a file or device
  55 .SH SYNOPSIS
  56 .nf
  57 .B #include <sys/types.h>
  58 .B #include <sys/stat.h>
  59 .B #include <fcntl.h>
  60 .sp
  61 .BI "int open(const char *" pathname ", int " flags );
  62 .BI "int open(const char *" pathname ", int " flags ", mode_t " mode );
  63
  64 .BI "int creat(const char *" pathname ", mode_t " mode );
  65 .fi
  66 .SH DESCRIPTION
  67 Given a
  68 .I pathname
  69 for a file,
  70 .BR open ()
  71 returns a file descriptor, a small, nonnegative integer
  72 for use in subsequent system calls
  73 .RB ( read "(2), " write "(2), " lseek "(2), " fcntl "(2), etc.)."
  74 The file descriptor returned by a successful call will be
  75 the lowest-numbered file descriptor not currently open for the process.
  76 .PP
  77 By default, the new file descriptor is set to remain open across an
  78 .BR execve (2)
  79 (i.e., the
  80 .B FD_CLOEXEC
  81 file descriptor flag described in
  82 .BR fcntl (2)
  83 is initially disabled; the
  84 .B O_CLOEXEC
  85 flag, described below, can be used to change this default).
  86 The file offset is set to the beginning of the file (see
  87 .BR lseek (2)).
  88 .PP
  89 A call to
  90 .BR open ()
  91 creates a new
  92 .IR "open file description" ,
  93 an entry in the system-wide table of open files.
  94 This entry records the file offset and the file status flags
  95 (modifiable via the
  96 .BR fcntl (2)
  97 .B F_SETFL
  98 operation).
  99 A file descriptor is a reference to one of these entries;
 100 this reference is unaffected if
 101 .I pathname
 102 is subsequently removed or modified to refer to a different file.
 103 The new open file description is initially not shared
 104 with any other process,
 105 but sharing may arise via
 106 .BR fork (2).
 107 .PP
 108 The argument
 109 .I flags
 110 must include one of the following
 111 .IR "access modes" :
 112 .BR O_RDONLY ", " O_WRONLY ", or " O_RDWR .
 113 These request opening the file read-only, write-only, or read/write,
 114 respectively.
 115
 116 In addition, zero or more file creation flags and file status flags
 117 can be
 118 .RI bitwise- or 'd
 119 in
 120 .IR flags .
 121 The
 122 .I file creation flags
 123 are
 124 .BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", and " O_TRUNC .
 125 The
 126 .I file status flags
 127 are all of the remaining flags listed below.
 128 .\" FIXME . Actually is it true that the "file status flags" are all of the
 129 .\" remaining flags listed below?  SUSv4 divides the flags into:
 130 .\" * Access mode
 131 .\" * File creation
 132 .\" * File status
 133 .\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
 134 .\" though it's not clear what the difference between "other" and
 135 .\" "File creation" flags is.  (I've raised an Aardvark to see if this
 136 .\" can be clarified in SUSv4; 10 Oct 2008.)
 137 The distinction between these two groups of flags is that
 138 the file status flags can be retrieved and (in some cases)
 139 modified using
 140 .BR fcntl (2).
 141 The full list of file creation flags and file status flags is as follows:
 142 .TP
 143 .B O_APPEND
 144 The file is opened in append mode.
 145 Before each
 146 .BR write (2),
 147 the file offset is positioned at the end of the file,
 148 as if with
 149 .BR lseek (2).
 150 .B O_APPEND
 151 may lead to corrupted files on NFS file systems if more than one process
 152 appends data to a file at once.
 153 .\" For more background, see
 154 .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
 155 .\" http://nfs.sourceforge.net/
 156 This is because NFS does not support
 157 appending to a file, so the client kernel has to simulate it, which
 158 can't be done without a race condition.
 159 .TP
 160 .B O_ASYNC
 161 Enable signal-driven I/O:
 162 generate a signal
 163 .RB ( SIGIO
 164 by default, but this can be changed via
 165 .BR fcntl (2))
 166 when input or output becomes possible on this file descriptor.
 167 This feature is only available for terminals, pseudoterminals,
 168 sockets, and (since Linux 2.6) pipes and FIFOs.
 169 See
 170 .BR fcntl (2)
 171 for further details.
 172 .TP
 173 .BR O_CLOEXEC " (Since Linux 2.6.23)"
 174 Enable the close-on-exec flag for the new file descriptor.
 175 Specifying this flag permits a program to avoid additional
 176 .BR fcntl (2)
 177 .B F_SETFD
 178 operations to set the
 179 .B FD_CLOEXEC
 180 flag.
 181 Additionally,
 182 use of this flag is essential in some multithreaded programs
 183 since using a separate
 184 .BR fcntl (2)
 185 .B F_SETFD
 186 operation to set the
 187 .B FD_CLOEXEC
 188 flag does not suffice to avoid race conditions
 189 where one thread opens a file descriptor at the same
 190 time as another thread does a
 191 .BR fork (2)
 192 plus
 193 .BR execve (2).
 194 .\" This flag fixes only one form of the race condition;
 195 .\" The race can also occur with, for example, descriptors
 196 .\" returned by accept(), pipe(), etc.
 197 .TP
 198 .B O_CREAT
 199 If the file does not exist it will be created.
 200 The owner (user ID) of the file is set to the effective user ID
 201 of the process.
 202 The group ownership (group ID) is set either to
 203 the effective group ID of the process or to the group ID of the
 204 parent directory (depending on file system type and mount options,
 205 and the mode of the parent directory, see the mount options
 206 .I bsdgroups
 207 and
 208 .I sysvgroups
 209 described in
 210 .BR mount (8)).
 211 .\" As at 2.6.25, bsdgroups is supported by ext2, ext3, ext4, and
 212 .\" XFS (since 2.6.14).
 213 .RS
 214 .PP
 215 .I mode
 216 specifies the permissions to use in case a new file is created.
 217 This argument must be supplied when
 218 .B O_CREAT
 219 is specified in
 220 .IR flags ;
 221 if
 222 .B O_CREAT
 223 is not specified, then
 224 .I mode
 225 is ignored.
 226 The effective permissions are modified by
 227 the process's
 228 .I umask
 229 in the usual way: The permissions of the created file are
 230 .IR "(mode\ &\ ~umask)" .
 231 Note that this mode only applies to future accesses of the
 232 newly created file; the
 233 .BR open ()
 234 call that creates a read-only file may well return a read/write
 235 file descriptor.
 236 .PP
 237 The following symbolic constants are provided for
 238 .IR mode :
 239 .TP 9
 240 .B S_IRWXU
 241 00700 user (file owner) has read, write and execute permission
 242 .TP
 243 .B S_IRUSR
 244 00400 user has read permission
 245 .TP
 246 .B S_IWUSR
 247 00200 user has write permission
 248 .TP
 249 .B S_IXUSR
 250 00100 user has execute permission
 251 .TP
 252 .B S_IRWXG
 253 00070 group has read, write and execute permission
 254 .TP
 255 .B S_IRGRP
 256 00040 group has read permission
 257 .TP
 258 .B S_IWGRP
 259 00020 group has write permission
 260 .TP
 261 .B S_IXGRP
 262 00010 group has execute permission
 263 .TP
 264 .B S_IRWXO
 265 00007 others have read, write and execute permission
 266 .TP
 267 .B S_IROTH
 268 00004 others have read permission
 269 .TP
 270 .B S_IWOTH
 271 00002 others have write permission
 272 .TP
 273 .B S_IXOTH
 274 00001 others have execute permission
 275 .RE
 276 .TP
 277 .BR O_DIRECT " (Since Linux 2.4.10)"
 278 Try to minimize cache effects of the I/O to and from this file.
 279 In general this will degrade performance, but it is useful in
 280 special situations, such as when applications do their own caching.
 281 File I/O is done directly to/from user space buffers.
 282 The
 283 .B O_DIRECT
 284 flag on its own makes an effort to transfer data synchronously,
 285 but does not give the guarantees of the
 286 .B O_SYNC
 287 flag that data and necessary metadata are transferred.
 288 To guarantee synchronous I/O,
 289 .B O_SYNC
 290 must be used in addition to
 291 .BR O_DIRECT .
 292 See NOTES below for further discussion.
 293 .sp
 294 A semantically similar (but deprecated) interface for block devices
 295 is described in
 296 .BR raw (8).
 297 .TP
 298 .B O_DIRECTORY
 299 If \fIpathname\fP is not a directory, cause the open to fail.
 300 .\" But see the following and its replies:
 301 .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
 302 .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
 303 .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
 304 This flag is Linux-specific, and was added in kernel version 2.1.126, to
 305 avoid denial-of-service problems if
 306 .BR opendir (3)
 307 is called on a
 308 FIFO or tape device, but should not be used outside of the
 309 implementation of
 310 .BR opendir (3).
 311 .TP
 312 .B O_EXCL
 313 Ensure that this call creates the file:
 314 if this flag is specified in conjunction with
 315 .BR O_CREAT ,
 316 and
 317 .I pathname
 318 already exists, then
 319 .BR open ()
 320 will fail.
 321
 322 When these two flags are specified, symbolic links are not followed:
 323 .\" POSIX.1-2001 explicitly requires this behavior.
 324 if
 325 .I pathname
 326 is a symbolic link, then
 327 .BR open ()
 328 fails regardless of where the symbolic link points to.
 329
 330 In general, the behavior of
 331 .B O_EXCL
 332 is undefined if it is used without
 333 .BR O_CREAT .
 334 There is one exception: on Linux 2.6 and later,
 335 .B O_EXCL
 336 can be used without
 337 .B O_CREAT
 338 if
 339 .I pathname
 340 refers to a block device.
 341 If the block device is in use by the system (e.g., mounted),
 342 .BR open ()
 343 fails with the error
 344 .BR EBUSY .
 345
 346 On NFS,
 347 .B O_EXCL
 348 is only supported when using NFSv3 or later on kernel 2.6 or later.
 349 In NFS environments where
 350 .B O_EXCL
 351 support is not provided, programs that rely on it
 352 for performing locking tasks will contain a race condition.
 353 Portable programs that want to perform atomic file locking using a lockfile,
 354 and need to avoid reliance on NFS support for
 355 .BR O_EXCL ,
 356 can create a unique file on
 357 the same file system (e.g., incorporating hostname and PID), and use
 358 .BR link (2)
 359 to make a link to the lockfile.
 360 If
 361 .BR link (2)
 362 returns 0, the lock is successful.
 363 Otherwise, use
 364 .BR stat (2)
 365 on the unique file to check if its link count has increased to 2,
 366 in which case the lock is also successful.
 367 .TP
 368 .B O_LARGEFILE
 369 (LFS)
 370 Allow files whose sizes cannot be represented in an
 371 .I off_t
 372 (but can be represented in an
 373 .IR off64_t )
 374 to be opened.
 375 The
 376 .B _LARGEFILE64_SOURCE
 377 macro must be defined
 378 (before including
 379 .I any
 380 header files)
 381 in order to obtain this definition.
 382 Setting the
 383 .B _FILE_OFFSET_BITS
 384 feature test macro to 64 (rather than using
 385 .BR O_LARGEFILE )
 386 is the preferred
 387 method of accessing large files on 32-bit systems (see
 388 .BR feature_test_macros (7)).
 389 .TP
 390 .BR O_NOATIME " (Since Linux 2.6.8)"
 391 Do not update the file last access time (st_atime in the inode)
 392 when the file is
 393 .BR read (2).
 394 This flag is intended for use by indexing or backup programs,
 395 where its use can significantly reduce the amount of disk activity.
 396 This flag may not be effective on all file systems.
 397 One example is NFS, where the server maintains the access time.
 398 .\" The O_NOATIME flag also affects the treatment of st_atime
 399 .\" by mmap() and readdir(2), MTK, Dec 04.
 400 .TP
 401 .B O_NOCTTY
 402 If
 403 .I pathname
 404 refers to a terminal device\(emsee
 405 .BR tty (4)\(em
 406 it will not become the process's controlling terminal even if the
 407 process does not have one.
 408 .TP
 409 .B O_NOFOLLOW
 410 If \fIpathname\fP is a symbolic link, then the open fails.
 411 This is a FreeBSD extension, which was added to Linux in version 2.1.126.
 412 Symbolic links in earlier components of the pathname will still be
 413 followed.
 414 .\" The headers from glibc 2.0.100 and later include a
 415 .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
 416 .\" used\fP.
 417 .TP
 418 .BR O_NONBLOCK " or " O_NDELAY
 419 When possible, the file is opened in nonblocking mode.
 420 Neither the
 421 .BR open ()
 422 nor any subsequent operations on the file descriptor which is
 423 returned will cause the calling process to wait.
 424 For the handling of FIFOs (named pipes), see also
 425 .BR fifo (7).
 426 For a discussion of the effect of
 427 .B O_NONBLOCK
 428 in conjunction with mandatory file locks and with file leases, see
 429 .BR fcntl (2).
 430 .TP
 431 .B O_SYNC
 432 The file is opened for synchronous I/O.
 433 Any
 434 .BR write (2)s
 435 on the resulting file descriptor will block the calling process until
 436 the data has been physically written to the underlying hardware.
 437 .IR "But see NOTES below" .
 438 .TP
 439 .B O_TRUNC
 440 If the file already exists and is a regular file and the open mode allows
 441 writing (i.e., is
 442 .B O_RDWR
 443 or
 444 .BR O_WRONLY )
 445 it will be truncated to length 0.
 446 If the file is a FIFO or terminal device file, the
 447 .B O_TRUNC
 448 flag is ignored.
 449 Otherwise the effect of
 450 .B O_TRUNC
 451 is unspecified.
 452 .PP
 453 Some of these optional flags can be altered using
 454 .BR fcntl (2)
 455 after the file has been opened.
 456
 457 .BR creat ()
 458 is equivalent to
 459 .BR open ()
 460 with
 461 .I flags
 462 equal to
 463 .BR O_CREAT|O_WRONLY|O_TRUNC .
 464 .SH "RETURN VALUE"
 465 .BR open ()
 466 and
 467 .BR creat ()
 468 return the new file descriptor, or \-1 if an error occurred
 469 (in which case,
 470 .I errno
 471 is set appropriately).
 472 .SH ERRORS
 473 .TP
 474 .B EACCES
 475 The requested access to the file is not allowed, or search permission
 476 is denied for one of the directories in the path prefix of
 477 .IR pathname ,
 478 or the file did not exist yet and write access to the parent directory
 479 is not allowed.
 480 (See also
 481 .BR path_resolution (7).)
 482 .TP
 483 .B EDQUOT
 484 Where
 485 .B O_CREAT
 486 is specified, the file does not exist, and the user's quota of disk
 487 blocks or inodes on the file system has been exhausted.
 488 .TP
 489 .B EEXIST
 490 .I pathname
 491 already exists and
 492 .BR O_CREAT " and " O_EXCL
 493 were used.
 494 .TP
 495 .B EFAULT
 496 .I pathname
 497 points outside your accessible address space.
 498 .TP
 499 .B EFBIG
 500 See
 501 .BR EOVERFLOW .
 502 .TP
 503 .B EINTR
 504 While blocked waiting to complete an open of a slow device
 505 (e.g., a FIFO; see
 506 .BR fifo (7)),
 507 the call was interrupted by a signal handler; see
 508 .BR signal (7).
 509 .TP
 510 .B EISDIR
 511 .I pathname
 512 refers to a directory and the access requested involved writing
 513 (that is,
 514 .B O_WRONLY
 515 or
 516 .B O_RDWR
 517 is set).
 518 .TP
 519 .B ELOOP
 520 Too many symbolic links were encountered in resolving
 521 .IR pathname ,
 522 or \fBO_NOFOLLOW\fP was specified but
 523 .I pathname
 524 was a symbolic link.
 525 .TP
 526 .B EMFILE
 527 The process already has the maximum number of files open.
 528 .TP
 529 .B ENAMETOOLONG
 530 .I pathname
 531 was too long.
 532 .TP
 533 .B ENFILE
 534 The system limit on the total number of open files has been reached.
 535 .TP
 536 .B ENODEV
 537 .I pathname
 538 refers to a device special file and no corresponding device exists.
 539 (This is a Linux kernel bug; in this situation
 540 .B ENXIO
 541 must be returned.)
 542 .TP
 543 .B ENOENT
 544 .B O_CREAT
 545 is not set and the named file does not exist.
 546 Or, a directory component in
 547 .I pathname
 548 does not exist or is a dangling symbolic link.
 549 .TP
 550 .B ENOMEM
 551 Insufficient kernel memory was available.
 552 .TP
 553 .B ENOSPC
 554 .I pathname
 555 was to be created but the device containing
 556 .I pathname
 557 has no room for the new file.
 558 .TP
 559 .B ENOTDIR
 560 A component used as a directory in
 561 .I pathname
 562 is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and
 563 .I pathname
 564 was not a directory.
 565 .TP
 566 .B ENXIO
 567 .BR O_NONBLOCK " | " O_WRONLY
 568 is set, the named file is a FIFO and
 569 no process has the file open for reading.
 570 Or, the file is a device special file and no corresponding device exists.
 571 .TP
 572 .B EOVERFLOW
 573 .I pathname
 574 refers to a regular file that is too large to be opened.
 575 The usual scenario here is that an application compiled
 576 on a 32-bit platform without
 577 .I -D_FILE_OFFSET_BITS=64
 578 tried to open a file whose size exceeds
 579 .I (2<<31)-1
 580 bits;
 581 see also
 582 .B O_LARGEFILE
 583 above.
 584 This is the error specified by POSIX.1-2001;
 585 in kernels before 2.6.24, Linux gave the error
 586 .B EFBIG
 587 for this case.
 588 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=7253
 589 .\" "Open of a large file on 32-bit fails with EFBIG, should be EOVERFLOW"
 590 .\" Reported 2006-10-03
 591 .TP
 592 .B EPERM
 593 The
 594 .B O_NOATIME
 595 flag was specified, but the effective user ID of the caller
 596 .\" Strictly speaking, it's the file system UID... (MTK)
 597 did not match the owner of the file and the caller was not privileged
 598 .RB ( CAP_FOWNER ).
 599 .TP
 600 .B EROFS
 601 .I pathname
 602 refers to a file on a read-only file system and write access was
 603 requested.
 604 .TP
 605 .B ETXTBSY
 606 .I pathname
 607 refers to an executable image which is currently being executed and
 608 write access was requested.
 609 .TP
 610 .B EWOULDBLOCK
 611 The
 612 .B O_NONBLOCK
 613 flag was specified, and an incompatible lease was held on the file
 614 (see
 615 .BR fcntl (2)).
 616 .SH "CONFORMING TO"
 617 SVr4, 4.3BSD, POSIX.1-2001.
 618 The
 619 .BR O_DIRECTORY ,
 620 .BR O_NOATIME ,
 621 and
 622 .B O_NOFOLLOW
 623 flags are Linux-specific, and one may need to define
 624 .B _GNU_SOURCE
 625 (before including
 626 .I any
 627 header files)
 628 to obtain their definitions.
 629
 630 The
 631 .BR O_CLOEXEC
 632 flag is not specified in POSIX.1-2001,
 633 but is specified in POSIX.1-2008.
 634
 635 .B O_DIRECT
 636 is not specified in POSIX; one has to define
 637 .B _GNU_SOURCE
 638 (before including
 639 .I any
 640 header files)
 641 to get its definition.
 642 .SH NOTES
 643 Under Linux, the
 644 .B O_NONBLOCK
 645 flag indicates that one wants to open
 646 but does not necessarily have the intention to read or write.
 647 This is typically used to open devices in order to get a file descriptor
 648 for use with
 649 .BR ioctl (2).
 650
 651 Unlike the other values that can be specified in
 652 .IR flags ,
 653 the
 654 .I "access mode"
 655 values
 656 .BR O_RDONLY ", " O_WRONLY ", and " O_RDWR ,
 657 do not specify individual bits.
 658 Rather, they define the low order two bits of
 659 .IR flags ,
 660 and are defined respectively as 0, 1, and 2.
 661 In other words, the combination
 662 .B "O_RDONLY | O_WRONLY"
 663 is a logical error, and certainly does not have the same meaning as
 664 .BR O_RDWR .
 665 Linux reserves the special, nonstandard access mode 3 (binary 11) in
 666 .I flags
 667 to mean:
 668 check for read and write permission on the file and return a descriptor
 669 that can't be used for reading or writing.
 670 This nonstandard access mode is used by some Linux drivers to return a
 671 descriptor that is only to be used for device-specific
 672 .BR ioctl (2)
 673 operations.
 674 .\" See for example util-linux's disk-utils/setfdprm.c
 675 .\" For some background on access mode 3, see
 676 .\" http://thread.gmane.org/gmane.linux.kernel/653123
 677 .\" "[RFC] correct flags to f_mode conversion in __dentry_open"
 678 .\" LKML, 12 Mar 2008
 679 .LP
 680 The (undefined) effect of
 681 .B O_RDONLY | O_TRUNC
 682 varies among implementations.
 683 On many systems the file is actually truncated.
 684 .\" Linux 2.0, 2.5: truncate
 685 .\" Solaris 5.7, 5.8: truncate
 686 .\" Irix 6.5: truncate
 687 .\" Tru64 5.1B: truncate
 688 .\" HP-UX 11.22: truncate
 689 .\" FreeBSD 4.7: truncate
 690 .PP
 691 There are many infelicities in the protocol underlying NFS, affecting
 692 amongst others
 693 .BR O_SYNC " and " O_NDELAY .
 694
 695 POSIX provides for three different variants of synchronized I/O,
 696 corresponding to the flags
 697 .BR O_SYNC ,
 698 .BR O_DSYNC ,
 699 and
 700 .BR O_RSYNC .
 701 Currently (2.6.31), Linux only implements
 702 .BR O_SYNC ,
 703 but glibc maps
 704 .B O_DSYNC
 705 and
 706 .B O_RSYNC
 707 to the same numerical value as
 708 .BR O_SYNC .
 709 Most Linux file systems don't actually implement the POSIX
 710 .B O_SYNC
 711 semantics, which require all metadata updates of a write
 712 to be on disk on returning to user space, but only the
 713 .B O_DSYNC
 714 semantics, which require only actual file data and metadata necessary
 715 to retrieve it to be on disk by the time the system call returns.
 716
 717 Note that
 718 .BR open ()
 719 can open device special files, but
 720 .BR creat ()
 721 cannot create them; use
 722 .BR mknod (2)
 723 instead.
 724 .LP
 725 On NFS file systems with UID mapping enabled,
 726 .BR open ()
 727 may
 728 return a file descriptor but, for example,
 729 .BR read (2)
 730 requests are denied
 731 with \fBEACCES\fP.
 732 This is because the client performs
 733 .BR open ()
 734 by checking the
 735 permissions, but UID mapping is performed by the server upon
 736 read and write requests.
 737
 738 If the file is newly created, its
 739 .IR st_atime ,
 740 .IR st_ctime ,
 741 .I st_mtime
 742 fields
 743 (respectively, time of last access, time of last status change, and
 744 time of last modification; see
 745 .BR stat (2))
 746 are set
 747 to the current time, and so are the
 748 .I st_ctime
 749 and
 750 .I st_mtime
 751 fields of the
 752 parent directory.
 753 Otherwise, if the file is modified because of the
 754 .B O_TRUNC
 755 flag, its st_ctime and st_mtime fields are set to the current time.
 756 .SS O_DIRECT
 757 .LP
 758 The
 759 .B O_DIRECT
 760 flag may impose alignment restrictions on the length and address
 761 of user-space buffers and the file offset of I/Os.
 762 In Linux alignment
 763 restrictions vary by file system and kernel version and might be
 764 absent entirely.
 765 However there is currently no file system\-independent
 766 interface for an application to discover these restrictions for a given
 767 file or file system.
 768 Some file systems provide their own interfaces
 769 for doing so, for example the
 770 .B XFS_IOC_DIOINFO
 771 operation in
 772 .BR xfsctl (3).
 773 .LP
 774 Under Linux 2.4, transfer sizes, and the alignment of the user buffer
 775 and the file offset must all be multiples of the logical block size
 776 of the file system.
 777 Under Linux 2.6, alignment to 512-byte boundaries suffices.
 778 .LP
 779 .B O_DIRECT
 780 I/Os should never be run concurrently with the
 781 .BR fork (2)
 782 system call,
 783 if the memory buffer is a private mapping
 784 (i.e., any mapping created with the
 785 .BR mmap (2)
 786 .BR MAP_PRIVATE
 787 flag;
 788 this includes memory allocated on the heap and statically allocated buffers).
 789 Any such I/Os, whether submitted via an asynchronous I/O interface or from
 790 another thread in the process,
 791 should be completed before
 792 .BR fork (2)
 793 is called.
 794 Failure to do so can result in data corruption and undefined behavior in
 795 parent and child processes.
 796 This restriction does not apply when the memory buffer for the
 797 .B O_DIRECT
 798 I/Os was created using
 799 .BR shmat (2)
 800 or
 801 .BR mmap (2)
 802 with the
 803 .B MAP_SHARED
 804 flag.
 805 Nor does this restriction apply when the memory buffer has been advised as
 806 .B MADV_DONTFORK
 807 with
 808 .BR madvise (2),
 809 ensuring that it will not be available
 810 to the child after
 811 .BR fork (2).
 812 .LP
 813 The
 814 .B O_DIRECT
 815 flag was introduced in SGI IRIX, where it has alignment
 816 restrictions similar to those of Linux 2.4.
 817 IRIX has also a
 818 .BR fcntl (2)
 819 call to query appropriate alignments, and sizes.
 820 FreeBSD 4.x introduced
 821 a flag of the same name, but without alignment restrictions.
 822 .LP
 823 .B O_DIRECT
 824 support was added under Linux in kernel version 2.4.10.
 825 Older Linux kernels simply ignore this flag.
 826 Some file systems may not implement the flag and
 827 .BR open ()
 828 will fail with
 829 .B EINVAL
 830 if it is used.
 831 .LP
 832 Applications should avoid mixing
 833 .B O_DIRECT
 834 and normal I/O to the same file,
 835 and especially to overlapping byte regions in the same file.
 836 Even when the file system correctly handles the coherency issues in
 837 this situation, overall I/O throughput is likely to be slower than
 838 using either mode alone.
 839 Likewise, applications should avoid mixing
 840 .BR mmap (2)
 841 of files with direct I/O to the same files.
 842 .LP
 843 The behaviour of
 844 .B O_DIRECT
 845 with NFS will differ from local file systems.
 846 Older kernels, or
 847 kernels configured in certain ways, may not support this combination.
 848 The NFS protocol does not support passing the flag to the server, so
 849 .B O_DIRECT
 850 I/O will only bypass the page cache on the client; the server may
 851 still cache the I/O.
 852 The client asks the server to make the I/O
 853 synchronous to preserve the synchronous semantics of
 854 .BR O_DIRECT .
 855 Some servers will perform poorly under these circumstances, especially
 856 if the I/O size is small.
 857 Some servers may also be configured to
 858 lie to clients about the I/O having reached stable storage; this
 859 will avoid the performance penalty at some risk to data integrity
 860 in the event of server power failure.
 861 The Linux NFS client places no alignment restrictions on
 862 .B O_DIRECT
 863 I/O.
 864 .PP
 865 In summary,
 866 .B O_DIRECT
 867 is a potentially powerful tool that should be used with caution.
 868 It is recommended that applications treat use of
 869 .B O_DIRECT
 870 as a performance option which is disabled by default.
 871 .PP
 872 .RS
 873 "The thing that has always disturbed me about O_DIRECT is that the whole
 874 interface is just stupid, and was probably designed by a deranged monkey
 875 on some serious mind-controlling substances."\(emLinus
 876 .RE
 877 .SH BUGS
 878 Currently, it is not possible to enable signal-driven
 879 I/O by specifying
 880 .B O_ASYNC
 881 when calling
 882 .BR open ();
 883 use
 884 .BR fcntl (2)
 885 to enable this flag.
 886 .\" FIXME . Check bugzilla report on open(O_ASYNC)
 887 .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
 888 .SH "SEE ALSO"
 889 .BR chmod (2),
 890 .BR chown (2),
 891 .BR close (2),
 892 .BR dup (2),
 893 .BR fcntl (2),
 894 .BR link (2),
 895 .BR lseek (2),
 896 .BR mknod (2),
 897 .BR mmap (2),
 898 .BR mount (2),
 899 .BR openat (2),
 900 .BR read (2),
 901 .BR socket (2),
 902 .BR stat (2),
 903 .BR umask (2),
 904 .BR unlink (2),
 905 .BR write (2),
 906 .BR fopen (3),
 907 .BR fifo (7),
 908 .BR path_resolution (7),
 909 .BR symlink (7)