-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
-.\" 1993 Michael Haardt, Ian Jackson.
-.\" 2008 Greg Banks
+.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
+.\" and Copyright (C) 2008 Greg Banks
.\"
+.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
.\"
.\" Modified 1993-07-21 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1994-08-21 by Michael Haardt
.\" FIXME Linux 2.6.33 has O_DSYNC, and a hidden __O_SYNC.
.\" FIXME: Linux 2.6.39 added O_PATH
.\"
-.TH OPEN 2 2011-09-08 "Linux" "Linux Programmer's Manual"
+.TH OPEN 2 2013-02-18 "Linux" "Linux Programmer's Manual"
.SH NAME
open, creat \- open and possibly create a file or device
.SH SYNOPSIS
The
.I file creation flags
are
-.BR O_CREAT ", " O_EXCL ", " O_NOCTTY ", and " O_TRUNC .
+.BR O_CLOEXEC ,
+.BR O_CREAT ,
+.BR O_DIRECTORY ,
+.BR O_EXCL ,
+.BR O_NOCTTY ,
+.BR O_NOFOLLOW ,
+.BR O_TRUNC ,
+and
+.BR O_TTY_INIT .
The
.I file status flags
are all of the remaining flags listed below.
-.\" FIXME . Actually is it true that the "file status flags" are all of the
-.\" remaining flags listed below? SUSv4 divides the flags into:
+.\" SUSv4 divides the flags into:
.\" * Access mode
.\" * File creation
.\" * File status
.\" * Other (O_CLOEXEC, O_DIRECTORY, O_NOFOLLOW)
.\" though it's not clear what the difference between "other" and
-.\" "File creation" flags is. (I've raised an Aardvark to see if this
-.\" can be clarified in SUSv4; 10 Oct 2008.)
+.\" "File creation" flags is. I raised an Aardvark to see if this
+.\" can be clarified in SUSv4; 10 Oct 2008.
+.\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/64/focus=67
+.\" TC1 (balloted in 2013), resolved this, so that those three constants
+.\" are also categorized" as file status flags.
+.\"
The distinction between these two groups of flags is that
the file status flags can be retrieved and (in some cases)
modified using
by default, but this can be changed via
.BR fcntl (2))
when input or output becomes possible on this file descriptor.
-This feature is only available for terminals, pseudoterminals,
+This feature is available only for terminals, pseudoterminals,
sockets, and (since Linux 2.6) pipes and FIFOs.
See
.BR fcntl (2)
.I umask
in the usual way: The permissions of the created file are
.IR "(mode\ &\ ~umask)" .
-Note that this mode only applies to future accesses of the
+Note that this mode applies only to future accesses of the
newly created file; the
.BR open ()
call that creates a read-only file may well return a read/write
Try to minimize cache effects of the I/O to and from this file.
In general this will degrade performance, but it is useful in
special situations, such as when applications do their own caching.
-File I/O is done directly to/from user space buffers.
+File I/O is done directly to/from user-space buffers.
The
.B O_DIRECT
-flag on its own makes at an effort to transfer data synchronously,
+flag on its own makes an effort to transfer data synchronously,
but does not give the guarantees of the
.B O_SYNC
-that data and necessary metadata are transferred.
-To guarantee synchronous I/O the
+flag that data and necessary metadata are transferred.
+To guarantee synchronous I/O,
.B O_SYNC
must be used in addition to
.BR O_DIRECT .
-See
-.B NOTES
-below for further discussion.
+See NOTES below for further discussion.
.sp
A semantically similar (but deprecated) interface for block devices
is described in
On NFS,
.B O_EXCL
-is only supported when using NFSv3 or later on kernel 2.6 or later.
+is supported only when using NFSv3 or later on kernel 2.6 or later.
In NFS environments where
.B O_EXCL
support is not provided, programs that rely on it
.BR feature_test_macros (7)).
.TP
.BR O_NOATIME " (Since Linux 2.6.8)"
-Do not update the file last access time (st_atime in the inode)
+Do not update the file last access time
+.RI ( st_atime
+in the inode)
when the file is
.BR read (2).
This flag is intended for use by indexing or backup programs,
.B O_NOCTTY
If
.I pathname
-refers to a terminal device \(em see
-.BR tty (4)
-\(em it will not become the process's controlling terminal even if the
+refers to a terminal device\(emsee
+.BR tty (4)\(emit
+will not become the process's controlling terminal even if the
process does not have one.
.TP
.B O_NOFOLLOW
.I flags
equal to
.BR O_CREAT|O_WRONLY|O_TRUNC .
-.SH "RETURN VALUE"
+.SH RETURN VALUE
.BR open ()
and
.BR creat ()
(See also
.BR path_resolution (7).)
.TP
+.B EDQUOT
+Where
+.B O_CREAT
+is specified, the file does not exist, and the user's quota of disk
+blocks or inodes on the file system has been exhausted.
+.TP
.B EEXIST
.I pathname
already exists and
flag was specified, and an incompatible lease was held on the file
(see
.BR fcntl (2)).
-.SH "CONFORMING TO"
+.SH CONFORMING TO
SVr4, 4.3BSD, POSIX.1-2001.
The
.BR O_DIRECTORY ,
check for read and write permission on the file and return a descriptor
that can't be used for reading or writing.
This nonstandard access mode is used by some Linux drivers to return a
-descriptor that is only to be used for device-specific
+descriptor that is to be used only for device-specific
.BR ioctl (2)
operations.
.\" See for example util-linux's disk-utils/setfdprm.c
.BR O_DSYNC ,
and
.BR O_RSYNC .
-Currently (2.6.31), Linux only implements
+Currently (2.6.31), Linux implements only
.BR O_SYNC ,
but glibc maps
.B O_DSYNC
Most Linux file systems don't actually implement the POSIX
.B O_SYNC
semantics, which require all metadata updates of a write
-to be on disk on returning to userspace, but only the
+to be on disk on returning to user space, but only the
.B O_DSYNC
semantics, which require only actual file data and metadata necessary
to retrieve it to be on disk by the time the system call returns.
The
.B O_DIRECT
flag may impose alignment restrictions on the length and address
-of userspace buffers and the file offset of I/Os.
+of user-space buffers and the file offset of I/Os.
In Linux alignment
restrictions vary by file system and kernel version and might be
absent entirely.
Under Linux 2.4, transfer sizes, and the alignment of the user buffer
and the file offset must all be multiples of the logical block size
of the file system.
-Under Linux 2.6, alignment to 512-byte boundaries
-suffices.
+Under Linux 2.6, alignment to 512-byte boundaries suffices.
+.LP
+.B O_DIRECT
+I/Os should never be run concurrently with the
+.BR fork (2)
+system call,
+if the memory buffer is a private mapping
+(i.e., any mapping created with the
+.BR mmap (2)
+.BR MAP_PRIVATE
+flag;
+this includes memory allocated on the heap and statically allocated buffers).
+Any such I/Os, whether submitted via an asynchronous I/O interface or from
+another thread in the process,
+should be completed before
+.BR fork (2)
+is called.
+Failure to do so can result in data corruption and undefined behavior in
+parent and child processes.
+This restriction does not apply when the memory buffer for the
+.B O_DIRECT
+I/Os was created using
+.BR shmat (2)
+or
+.BR mmap (2)
+with the
+.B MAP_SHARED
+flag.
+Nor does this restriction apply when the memory buffer has been advised as
+.B MADV_DONTFORK
+with
+.BR madvise (2),
+ensuring that it will not be available
+to the child after
+.BR fork (2).
.LP
The
.B O_DIRECT
kernels configured in certain ways, may not support this combination.
The NFS protocol does not support passing the flag to the server, so
.B O_DIRECT
-I/O will only bypass the page cache on the client; the server may
+I/O will bypass the page cache only on the client; the server may
still cache the I/O.
The client asks the server to make the I/O
synchronous to preserve the synchronous semantics of
.RS
"The thing that has always disturbed me about O_DIRECT is that the whole
interface is just stupid, and was probably designed by a deranged monkey
-on some serious mind-controlling substances." \(em Linus
+on some serious mind-controlling substances."\(emLinus
.RE
.SH BUGS
Currently, it is not possible to enable signal-driven
to enable this flag.
.\" FIXME . Check bugzilla report on open(O_ASYNC)
.\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR chmod (2),
.BR chown (2),
.BR close (2),