(split) LDP: Update original to LDP v3.38.

[linuxjm/LDP_man-pages.git] / original / man2 / open.2

diff --git a/original/man2/open.2 b/original/man2/open.2
index 11bd65e..a655fae 100644 (file)
--- a/original/man2/open.2
+++ b/original/man2/open.2
@@ -46,9 +46,10 @@
 .\"
 .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and
 .\" O_TTYINIT.  Eventually these may need to be documented.  --mtk
-.\" FIXME Linux 2.6.33 has O_DSYNC, and a hiddden __O_SYNC.
+.\" FIXME Linux 2.6.33 has O_DSYNC, and a hidden __O_SYNC.
+.\" FIXME: Linux 2.6.39 added O_PATH
 .\"
-.TH OPEN 2 2009-09-20 "Linux" "Linux Programmer's Manual"
+.TH OPEN 2 2012-02-27 "Linux" "Linux Programmer's Manual"
 .SH NAME
 open, creat \- open and possibly create a file or device
 .SH SYNOPSIS
@@ -79,7 +80,7 @@ By default, the new file descriptor is set to remain open across an
 .B FD_CLOEXEC
 file descriptor flag described in
 .BR fcntl (2)
-is initially disabled; the Linux-specific
+is initially disabled; the
 .B O_CLOEXEC
 flag, described below, can be used to change this default).
 The file offset is set to the beginning of the file (see
@@ -163,7 +164,7 @@ generate a signal
 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, pseudo-terminals,
+This feature is only available for terminals, pseudoterminals,
 sockets, and (since Linux 2.6) pipes and FIFOs.
 See
 .BR fcntl (2)
@@ -280,17 +281,15 @@ special situations, such as when applications do their own caching.
 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
@@ -319,11 +318,6 @@ and
 already exists, then
 .BR open ()
 will fail.
-The behavior of
-.B O_EXCL
-is undefined if
-.B O_CREAT
-is not specified.
 
 When these two flags are specified, symbolic links are not followed:
 .\" POSIX.1-2001 explicitly requires this behavior.
@@ -333,9 +327,26 @@ is a symbolic link, then
 .BR open ()
 fails regardless of where the symbolic link points to.
 
+In general, the behavior of
+.B O_EXCL
+is undefined if it is used without
+.BR O_CREAT .
+There is one exception: on Linux 2.6 and later,
+.B O_EXCL
+can be used without
+.B O_CREAT
+if
+.I pathname
+refers to a block device.
+If the block device is in use by the system (e.g., mounted),
+.BR open ()
+fails with the error
+.BR EBUSY .
+
+On NFS,
 .B O_EXCL
-is only supported on NFS when using NFSv3 or later on kernel 2.6 or later.
-In environments where NFS
+is only supported 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
 for performing locking tasks will contain a race condition.
@@ -363,12 +374,16 @@ Allow files whose sizes cannot be represented in an
 to be opened.
 The
 .B _LARGEFILE64_SOURCE
-macro must be defined in order to obtain this definition.
+macro must be defined
+(before including
+.I any
+header files)
+in order to obtain this definition.
 Setting the
 .B _FILE_OFFSET_BITS
 feature test macro to 64 (rather than using
 .BR O_LARGEFILE )
-is the preferred method of obtaining
+is the preferred
 method of accessing large files on 32-bit systems (see
 .BR feature_test_macros (7)).
 .TP
@@ -386,9 +401,9 @@ One example is NFS, where the server maintains the access time.
 .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)\(em
+it will not become the process's controlling terminal even if the
 process does not have one.
 .TP
 .B O_NOFOLLOW
@@ -601,6 +616,9 @@ and
 .B O_NOFOLLOW
 flags are Linux-specific, and one may need to define
 .B _GNU_SOURCE
+(before including
+.I any
+header files)
 to obtain their definitions.
 
 The
@@ -611,6 +629,9 @@ but is specified in POSIX.1-2008.
 .B O_DIRECT
 is not specified in POSIX; one has to define
 .B _GNU_SOURCE
+(before including
+.I any
+header files)
 to get its definition.
 .SH NOTES
 Under Linux, the
@@ -678,8 +699,8 @@ but glibc maps
 and
 .B O_RSYNC
 to the same numerical value as
-.BR O_SYNC
-Most Linux filesystems don't actually implement the POSIX
+.BR O_SYNC .
+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
@@ -812,7 +833,7 @@ as a performance option which is disabled by default.
 .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
@@ -844,7 +865,6 @@ to enable this flag.
 .BR unlink (2),
 .BR write (2),
 .BR fopen (3),
-.BR feature_test_macros (7),
 .BR fifo (7),
 .BR path_resolution (7),
 .BR symlink (7)