[man-pages/f20] new man page for open.2 removing openat as it is part of open.2
Jan Chaloupka
jchaloup at fedoraproject.org
Wed Jul 23 08:36:28 UTC 2014
commit 9826fe5b946d4345e5123f5aa59791155a006c57
Author: Jan Chaloupka <jchaloup at redhat.com>
Date: Wed Jul 23 10:26:38 2014 +0200
new man page for open.2
removing openat as it is part of open.2
- resolves: #1099453
man-pages-3.57-open.2.patch | 1397 +++++++++++++++++++++++++++++++++++++++++++
man-pages.spec | 11 +-
2 files changed, 1406 insertions(+), 2 deletions(-)
---
diff --git a/man-pages-3.57-open.2.patch b/man-pages-3.57-open.2.patch
new file mode 100644
index 0000000..5c0d7ba
--- /dev/null
+++ b/man-pages-3.57-open.2.patch
@@ -0,0 +1,1397 @@
+From 998f8f81add81546a634f799a4c079ad58e8c33c Mon Sep 17 00:00:00 2001
+From: Jan Chaloupka <jchaloup at redhat.com>
+Date: Wed, 23 Jul 2014 10:23:16 +0200
+Subject: [PATCH] open.2
+
+---
+ man2/open.2 | 813 ++++++++++++++++++++++++++++++++++++++++++++++------------
+ man2/openat.2 | 188 +-------------
+ 2 files changed, 648 insertions(+), 353 deletions(-)
+
+diff --git a/man2/open.2 b/man2/open.2
+index 84331c6..c413d96 100644
+--- a/man2/open.2
++++ b/man2/open.2
+@@ -1,6 +1,7 @@
+ .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
+-.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
+-.\" and Copyright (C) 2008 Greg Banks
++.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
++.\" and Copyright (C) 2008 Greg Banks
++.\" and Copyright (C) 2006, 2008, 2013, 2014 Michael Kerrisk <mtk.manpages at gmail.com>
+ .\"
+ .\" %%%LICENSE_START(VERBATIM)
+ .\" Permission is granted to make and distribute verbatim copies of this
+@@ -46,11 +47,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 hidden __O_SYNC.
+ .\"
+-.TH OPEN 2 2013-07-21 "Linux" "Linux Programmer's Manual"
++.TH OPEN 2 2014-07-08 "Linux" "Linux Programmer's Manual"
+ .SH NAME
+-open, creat \- open and possibly create a file or device
++open, openat, creat \- open and possibly create a file
+ .SH SYNOPSIS
+ .nf
+ .B #include <sys/types.h>
+@@ -61,7 +61,30 @@ open, creat \- open and possibly create a file or device
+ .BI "int open(const char *" pathname ", int " flags ", mode_t " mode );
+
+ .BI "int creat(const char *" pathname ", mode_t " mode );
++.sp
++.BI "int openat(int " dirfd ", const char *" pathname ", int " flags );
++.BI "int openat(int " dirfd ", const char *" pathname ", int " flags \
++", mode_t " mode );
+ .fi
++.sp
++.in -4n
++Feature Test Macro Requirements for glibc (see
++.BR feature_test_macros (7)):
++.in
++.sp
++.BR openat ():
++.PD 0
++.ad l
++.RS 4
++.TP 4
++Since glibc 2.10:
++_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
++.TP
++Before glibc 2.10:
++_ATFILE_SOURCE
++.RE
++.ad
++.PD
+ .SH DESCRIPTION
+ Given a
+ .I pathname
+@@ -78,10 +101,10 @@ By default, the new file descriptor is set to remain open across an
+ (i.e., the
+ .B FD_CLOEXEC
+ file descriptor flag described in
+-.BR fcntl (2)
++.BR fcntl (2))
+ is initially disabled; the
+ .B O_CLOEXEC
+-flag, described below, can be used to change this default).
++flag, described below, can be used to change this default.
+ The file offset is set to the beginning of the file (see
+ .BR lseek (2)).
+ .PP
+@@ -90,19 +113,13 @@ A call to
+ creates a new
+ .IR "open file description" ,
+ an entry in the system-wide table of open files.
+-This entry records the file offset and the file status flags
+-(modifiable via the
+-.BR fcntl (2)
+-.B F_SETFL
+-operation).
+-A file descriptor is a reference to one of these entries;
++The open file description records the file offset and the file status flags
++(see below).
++A file descriptor is a reference to an open file description;
+ this reference is unaffected if
+ .I pathname
+ is subsequently removed or modified to refer to a different file.
+-The new open file description is initially not shared
+-with any other process,
+-but sharing may arise via
+-.BR fork (2).
++For further details on open file descriptions, see NOTES.
+ .PP
+ The argument
+ .I flags
+@@ -126,6 +143,7 @@ are
+ .BR O_EXCL ,
+ .BR O_NOCTTY ,
+ .BR O_NOFOLLOW ,
++.BR O_TMPFILE ,
+ .BR O_TRUNC ,
+ and
+ .BR O_TTY_INIT .
+@@ -146,8 +164,10 @@ are all of the remaining flags listed below.
+ .\"
+ The distinction between these two groups of flags is that
+ the file status flags can be retrieved and (in some cases)
+-modified using
+-.BR fcntl (2).
++modified; see
++.BR fcntl (2)
++for details.
++
+ The full list of file creation flags and file status flags is as follows:
+ .TP
+ .B O_APPEND
+@@ -158,7 +178,7 @@ the file offset is positioned at the end of the file,
+ as if with
+ .BR lseek (2).
+ .B O_APPEND
+-may lead to corrupted files on NFS file systems if more than one process
++may lead to corrupted files on NFS filesystems if more than one process
+ appends data to a file at once.
+ .\" For more background, see
+ .\" http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=453946
+@@ -179,8 +199,10 @@ sockets, and (since Linux 2.6) pipes and FIFOs.
+ See
+ .BR fcntl (2)
+ for further details.
++See also BUGS, below.
+ .TP
+-.BR O_CLOEXEC " (Since Linux 2.6.23)"
++.BR O_CLOEXEC " (since Linux 2.6.23)"
++.\" NOTE! several other man pages refer to this text
+ Enable the close-on-exec flag for the new file descriptor.
+ Specifying this flag permits a program to avoid additional
+ .BR fcntl (2)
+@@ -188,31 +210,44 @@ Specifying this flag permits a program to avoid additional
+ operations to set the
+ .B FD_CLOEXEC
+ flag.
+-Additionally,
+-use of this flag is essential in some multithreaded programs
+-since using a separate
++
++Note that the use of this flag is essential in some multithreaded programs,
++because using a separate
+ .BR fcntl (2)
+ .B F_SETFD
+ operation to set the
+ .B FD_CLOEXEC
+ flag does not suffice to avoid race conditions
+-where one thread opens a file descriptor at the same
+-time as another thread does a
++where one thread opens a file descriptor and
++attempts to set its close-on-exec flag using
++.BR fcntl (2)
++at the same time as another thread does a
+ .BR fork (2)
+ plus
+ .BR execve (2).
++Depending on the order of execution,
++the race may lead to the file descriptor returned by
++.BR open ()
++being unintentionally leaked to the program executed by the child process
++created by
++.BR fork (2).
++(This kind of race is in principle possible for any system call
++that creates a file descriptor whose close-on-exec flag should be set,
++and various other Linux system calls provide an equivalent of the
++.BR O_CLOEXEC
++flag to deal with this problem.)
+ .\" This flag fixes only one form of the race condition;
+ .\" The race can also occur with, for example, descriptors
+ .\" returned by accept(), pipe(), etc.
+ .TP
+ .B O_CREAT
+-If the file does not exist it will be created.
++If the file does not exist, it will be created.
+ The owner (user ID) of the file is set to the effective user ID
+ of the process.
+ The group ownership (group ID) is set either to
+ the effective group ID of the process or to the group ID of the
+-parent directory (depending on file system type and mount options,
+-and the mode of the parent directory, see the mount options
++parent directory (depending on filesystem type and mount options,
++and the mode of the parent directory; see the mount options
+ .I bsdgroups
+ and
+ .I sysvgroups
+@@ -226,11 +261,15 @@ described in
+ specifies the permissions to use in case a new file is created.
+ This argument must be supplied when
+ .B O_CREAT
++or
++.B O_TMPFILE
+ is specified in
+ .IR flags ;
+-if
++if neither
+ .B O_CREAT
+-is not specified, then
++nor
++.B O_TMPFILE
++is specified, then
+ .I mode
+ is ignored.
+ The effective permissions are modified by
+@@ -284,7 +323,7 @@ The following symbolic constants are provided for
+ 00001 others have execute permission
+ .RE
+ .TP
+-.BR O_DIRECT " (Since Linux 2.4.10)"
++.BR O_DIRECT " (since Linux 2.4.10)"
+ 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.
+@@ -311,12 +350,30 @@ If \fIpathname\fP is not a directory, cause the open to fail.
+ .\" http://marc.theaimsgroup.com/?t=112748702800001&r=1&w=2
+ .\" [PATCH] open: O_DIRECTORY and O_CREAT together should fail
+ .\" O_DIRECTORY | O_CREAT causes O_DIRECTORY to be ignored.
+-This flag is Linux-specific, and was added in kernel version 2.1.126, to
++This flag was added in kernel version 2.1.126, to
+ avoid denial-of-service problems if
+ .BR opendir (3)
+ is called on a
+ FIFO or tape device.
+ .TP
++.B O_DSYNC
++Write operations on the file will complete according to the requirements of
++synchronized I/O
++.I data
++integrity completion.
++
++By the time
++.BR write (2)
++(and similar)
++return, the output data
++has been transferred to the underlying hardware,
++along with any file metadata that would be required to retrieve that data
++(i.e., as though each
++.BR write (2)
++was followed by a call to
++.BR fdatasync (2)).
++.IR "See NOTES below" .
++.TP
+ .B O_EXCL
+ Ensure that this call creates the file:
+ if this flag is specified in conjunction with
+@@ -362,7 +419,7 @@ Portable programs that want to perform atomic file locking using a lockfile,
+ and need to avoid reliance on NFS support for
+ .BR O_EXCL ,
+ can create a unique file on
+-the same file system (e.g., incorporating hostname and PID), and use
++the same filesystem (e.g., incorporating hostname and PID), and use
+ .BR link (2)
+ to make a link to the lockfile.
+ If
+@@ -395,7 +452,7 @@ is the preferred
+ method of accessing large files on 32-bit systems (see
+ .BR feature_test_macros (7)).
+ .TP
+-.BR O_NOATIME " (Since Linux 2.6.8)"
++.BR O_NOATIME " (since Linux 2.6.8)"
+ Do not update the file last access time
+ .RI ( st_atime
+ in the inode)
+@@ -403,7 +460,7 @@ when the file is
+ .BR read (2).
+ This flag is intended for use by indexing or backup programs,
+ where its use can significantly reduce the amount of disk activity.
+-This flag may not be effective on all file systems.
++This flag may not be effective on all filesystems.
+ One example is NFS, where the server maintains the access time.
+ .\" The O_NOATIME flag also affects the treatment of st_atime
+ .\" by mmap() and readdir(2), MTK, Dec 04.
+@@ -422,7 +479,7 @@ This is a FreeBSD extension, which was added to Linux in version 2.1.126.
+ Symbolic links in earlier components of the pathname will still be
+ followed.
+ See also
+-.BR O_NOPATH
++.BR O_PATH
+ below.
+ .\" The headers from glibc 2.0.100 and later include a
+ .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if
+@@ -451,14 +508,15 @@ in conjunction with mandatory file locks and with file leases, see
+ .\" Newsgroups: gmane.linux.man, gmane.linux.kernel
+ .\"
+ Obtain a file descriptor that can be used for two purposes:
+-to indicate a location in the file-system tree and
++to indicate a location in the filesystem tree and
+ to perform operations that act purely at the file descriptor level.
+ The file itself is not opened, and other file operations (e.g.,
+ .BR read (2),
+ .BR write (2),
+ .BR fchmod (2),
+ .BR fchown (2),
+-.BR fgetxattr (2))
++.BR fgetxattr (2),
++.BR mmap (2))
+ fail with the error
+ .BR EBADF .
+
+@@ -492,13 +550,19 @@ Retrieving open file status flags using the
+ .BR F_GETFL
+ operation: the returned flags will include the bit
+ .BR O_PATH .
+-
+ .IP *
+ Passing the file descriptor as the
+ .IR dirfd
+ argument of
+ .BR openat (2)
+ and the other "*at()" system calls.
++This includes
++.BR linkat (2)
++with
++.BR AT_EMPTY_PATH
++(or via procfs using
++.BR AT_SYMLINK_FOLLOW )
++even if the file is not a directory.
+ .IP *
+ Passing the file descriptor to another process via a UNIX domain socket
+ (see
+@@ -512,12 +576,15 @@ When
+ is specified in
+ .IR flags ,
+ flag bits other than
+-.BR O_DIRECTORY
++.BR O_CLOEXEC ,
++.BR O_DIRECTORY ,
+ and
+ .BR O_NOFOLLOW
+ are ignored.
+
+-If the
++If
++.I pathname
++is a symbolic link and the
+ .BR O_NOFOLLOW
+ flag is also specified,
+ then the call returns a file descriptor referring to the symbolic link.
+@@ -532,15 +599,125 @@ and
+ with an empty pathname to have the calls operate on the symbolic link.
+ .TP
+ .B O_SYNC
+-The file is opened for synchronous I/O.
+-Any
+-.BR write (2)s
+-on the resulting file descriptor will block the calling process until
+-the data has been physically written to the underlying hardware.
+-.IR "But see NOTES below" .
++Write operations on the file will complete according to the requirements of
++synchronized I/O
++.I file
++integrity completion
++(by contrast with contrast with the
++synchronized I/O
++.I data
++integrity completion
++provided by
++.BR O_DSYNC .)
++
++By the time
++.BR write (2)
++(and similar)
++return, the output data and associated file metadata
++have been transferred to the underlying hardware
++(i.e., as though each
++.BR write (2)
++was followed by a call to
++.BR fsync (2)).
++.IR "See NOTES below" .
++.TP
++.BR O_TMPFILE " (since Linux 3.11)"
++.\" commit 60545d0d4610b02e55f65d141c95b18ccf855b6e
++.\" commit f4e0c30c191f87851c4a53454abb55ee276f4a7e
++.\" commit bb458c644a59dbba3a1fe59b27106c5e68e1c4bd
++Create an unnamed temporary file.
++The
++.I pathname
++argument specifies a directory;
++an unnamed inode will be created in that directory's filesystem.
++Anything written to the resulting file will be lost when
++the last file descriptor is closed, unless the file is given a name.
++
++.B O_TMPFILE
++must be specified with one of
++.B O_RDWR
++or
++.B O_WRONLY
++and, optionally,
++.BR O_EXCL .
++If
++.B O_EXCL
++is not specified, then
++.BR linkat (2)
++can be used to link the temporary file into the filesystem, making it
++permanent, using code like the following:
++
++.in +4n
++.nf
++char path[PATH_MAX];
++fd = open("/path/to/dir", O_TMPFILE | O_RDWR,
++ S_IRUSR | S_IWUSR);
++
++/* File I/O on 'fd'... */
++
++snprintf(path, PATH_MAX, "/proc/self/fd/%d", fd);
++linkat(AT_FDCWD, path, AT_FDCWD, "/path/for/file",
++ AT_SYMLINK_FOLLOW);
++.fi
++.in
++
++In this case,
++the
++.BR open ()
++.I mode
++argument determines the file permission mode, as with
++.BR O_CREAT .
++
++Specifying
++.B O_EXCL
++in conjunction with
++.B O_TMPFILE
++prevents a temporary file from being linked into the filesystem
++in the above manner.
++(Note that the meaning of
++.B O_EXCL
++in this case is different from the meaning of
++.B O_EXCL
++otherwise.)
++
++
++There are two main use cases for
++.\" Inspired by http://lwn.net/Articles/559147/
++.BR O_TMPFILE :
++.RS
++.IP * 3
++Improved
++.BR tmpfile (3)
++functionality: race-free creation of temporary files that
++(1) are automatically deleted when closed;
++(2) can never be reached via any pathname;
++(3) are not subject to symlink attacks; and
++(4) do not require the caller to devise unique names.
++.IP *
++Creating a file that is initially invisible, which is then populated
++with data and adjusted to have appropriate filesystem attributes
++.RB ( chown (2),
++.BR chmod (2),
++.BR fsetxattr (2),
++etc.)
++before being atomically linked into the filesystem
++in a fully formed state (using
++.BR linkat (2)
++as described above).
++.RE
++.IP
++.B O_TMPFILE
++requires support by the underlying filesystem;
++only a subset of Linux filesystems provide that support.
++In the initial implementation, support was provided in
++the ext2, ext3, ext4, UDF, Minix, and shmem filesystems.
++XFS support was added
++.\" commit 99b6436bc29e4f10e4388c27a3e4810191cc4788
++.\" commit ab29743117f9f4c22ac44c13c1647fb24fb2bafe
++in Linux 3.15.
+ .TP
+ .B O_TRUNC
+-If the file already exists and is a regular file and the open mode allows
++If the file already exists and is a regular file and the access mode allows
+ writing (i.e., is
+ .B O_RDWR
+ or
+@@ -549,14 +726,10 @@ it will be truncated to length 0.
+ If the file is a FIFO or terminal device file, the
+ .B O_TRUNC
+ flag is ignored.
+-Otherwise the effect of
++Otherwise, the effect of
+ .B O_TRUNC
+ is unspecified.
+-.PP
+-Some of these optional flags can be altered using
+-.BR fcntl (2)
+-after the file has been opened.
+-
++.SS creat()
+ .BR creat ()
+ is equivalent to
+ .BR open ()
+@@ -564,8 +737,43 @@ with
+ .I flags
+ equal to
+ .BR O_CREAT|O_WRONLY|O_TRUNC .
+-.SH RETURN VALUE
++.SS openat()
++The
++.BR openat ()
++system call operates in exactly the same way as
++.BR open (),
++except for the differences described here.
++
++If the pathname given in
++.I pathname
++is relative, then it is interpreted relative to the directory
++referred to by the file descriptor
++.I dirfd
++(rather than relative to the current working directory of
++the calling process, as is done by
+ .BR open ()
++for a relative pathname).
++
++If
++.I pathname
++is relative and
++.I dirfd
++is the special value
++.BR AT_FDCWD ,
++then
++.I pathname
++is interpreted relative to the current working
++directory of the calling process (like
++.BR open ()).
++
++If
++.I pathname
++is absolute, then
++.I dirfd
++is ignored.
++.SH RETURN VALUE
++.BR open (),
++.BR openat (),
+ and
+ .BR creat ()
+ return the new file descriptor, or \-1 if an error occurred
+@@ -573,6 +781,11 @@ return the new file descriptor, or \-1 if an error occurred
+ .I errno
+ is set appropriately).
+ .SH ERRORS
++.BR open (),
++.BR openat (),
++and
++.BR creat ()
++can fail with the following errors:
+ .TP
+ .B EACCES
+ The requested access to the file is not allowed, or search permission
+@@ -587,7 +800,7 @@ is not allowed.
+ 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.
++blocks or inodes on the filesystem has been exhausted.
+ .TP
+ .B EEXIST
+ .I pathname
+@@ -610,6 +823,29 @@ While blocked waiting to complete an open of a slow device
+ the call was interrupted by a signal handler; see
+ .BR signal (7).
+ .TP
++.B EINVAL
++The filesystem does not support the
++.BR O_DIRECT
++flag.
++See
++.BR NOTES
++for more information.
++.TP
++.B EINVAL
++Invalid value in
++.\" In particular, __O_TMPFILE instead of O_TMPFILE
++.IR flags .
++.TP
++.B EINVAL
++.B O_TMPFILE
++was specified in
++.IR flags ,
++but neither
++.B O_WRONLY
++nor
++.B O_RDWR
++was specified.
++.TP
+ .B EISDIR
+ .I pathname
+ refers to a directory and the access requested involved writing
+@@ -619,12 +855,32 @@ or
+ .B O_RDWR
+ is set).
+ .TP
++.B EISDIR
++.I pathname
++refers to an existing directory,
++.B O_TMPFILE
++and one of
++.B O_WRONLY
++or
++.B O_RDWR
++were specified in
++.IR flags ,
++but this kernel version does not provide the
++.B O_TMPFILE
++functionality.
++.TP
+ .B ELOOP
+ Too many symbolic links were encountered in resolving
+-.IR pathname ,
+-or \fBO_NOFOLLOW\fP was specified but
++.IR pathname .
++.TP
++.B ELOOP
+ .I pathname
+-was a symbolic link.
++was a symbolic link, and
++.I flags
++specified
++.BR O_NOFOLLOW
++but not
++.BR O_PATH .
+ .TP
+ .B EMFILE
+ The process already has the maximum number of files open.
+@@ -650,6 +906,20 @@ Or, a directory component in
+ .I pathname
+ does not exist or is a dangling symbolic link.
+ .TP
++.B ENOENT
++.I pathname
++refers to a nonexistent directory,
++.B O_TMPFILE
++and one of
++.B O_WRONLY
++or
++.B O_RDWR
++were specified in
++.IR flags ,
++but this kernel version does not provide the
++.B O_TMPFILE
++functionality.
++.TP
+ .B ENOMEM
+ Insufficient kernel memory was available.
+ .TP
+@@ -668,10 +938,16 @@ was not a directory.
+ .TP
+ .B ENXIO
+ .BR O_NONBLOCK " | " O_WRONLY
+-is set, the named file is a FIFO and
+-no process has the file open for reading.
++is set, the named file is a FIFO, and
++no process has the FIFO open for reading.
+ Or, the file is a device special file and no corresponding device exists.
+ .TP
++.BR EOPNOTSUPP
++The filesystem containing
++.I pathname
++does not support
++.BR O_TMPFILE .
++.TP
+ .B EOVERFLOW
+ .I pathname
+ refers to a regular file that is too large to be opened.
+@@ -696,13 +972,13 @@ for this case.
+ The
+ .B O_NOATIME
+ flag was specified, but the effective user ID of the caller
+-.\" Strictly speaking, it's the file system UID... (MTK)
++.\" Strictly speaking, it's the filesystem UID... (MTK)
+ did not match the owner of the file and the caller was not privileged
+ .RB ( CAP_FOWNER ).
+ .TP
+ .B EROFS
+ .I pathname
+-refers to a file on a read-only file system and write access was
++refers to a file on a read-only filesystem and write access was
+ requested.
+ .TP
+ .B ETXTBSY
+@@ -716,33 +992,67 @@ The
+ flag was specified, and an incompatible lease was held on the file
+ (see
+ .BR fcntl (2)).
++.PP
++The following additional errors can occur for
++.BR openat ():
++.TP
++.B EBADF
++.I dirfd
++is not a valid file descriptor.
++.TP
++.B ENOTDIR
++.I pathname
++is a relative pathname and
++.I dirfd
++is a file descriptor referring to a file other than a directory.
++.SH VERSIONS
++.BR openat ()
++was added to Linux in kernel 2.6.16;
++library support was added to glibc in version 2.4.
+ .SH CONFORMING TO
+-SVr4, 4.3BSD, POSIX.1-2001.
++.BR open (),
++.BR creat ()
++SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.
++
++.BR openat ():
++POSIX.1-2008.
++
+ The
+-.BR O_DIRECTORY ,
++.BR O_DIRECT ,
+ .BR O_NOATIME ,
+-.BR O_NOFOLLOW ,
++.BR O_PATH ,
+ and
+-.BR O_PATH
+-flags are Linux-specific, and one may need to define
++.BR O_TMPFILE
++flags are Linux-specific.
++One must define
+ .B _GNU_SOURCE
+-(before including
+-.I any
+-header files)
+ to obtain their definitions.
+
+ The
+-.BR O_CLOEXEC
+-flag is not specified in POSIX.1-2001,
+-but is specified in POSIX.1-2008.
++.BR O_CLOEXEC ,
++.BR O_DIRECTORY ,
++and
++.BR O_NOFOLLOW
++flags are not specified in POSIX.1-2001,
++but are specified in POSIX.1-2008.
++Since glibc 2.12, one can obtain their definitions by defining either
++.B _POSIX_C_SOURCE
++with a value greater than or equal to 200809L or
++.BR _XOPEN_SOURCE
++with a value greater than or equal to 700.
++In glibc 2.11 and earlier, one obtains the definitions by defining
++.BR _GNU_SOURCE .
+
+-.B O_DIRECT
+-is not specified in POSIX; one has to define
++As noted in
++.BR feature_test_macros (7),
++feature test macros such as
++.BR _POSIX_C_SOURCE ,
++.BR _XOPEN_SOURCE ,
++and
+ .B _GNU_SOURCE
+-(before including
++must be defined before including
+ .I any
+-header files)
+-to get its definition.
++header files.
+ .SH NOTES
+ Under Linux, the
+ .B O_NONBLOCK
+@@ -752,34 +1062,6 @@ This is typically used to open devices in order to get a file descriptor
+ for use with
+ .BR ioctl (2).
+
+-Unlike the other values that can be specified in
+-.IR flags ,
+-the
+-.I "access mode"
+-values
+-.BR O_RDONLY ", " O_WRONLY ", and " O_RDWR ,
+-do not specify individual bits.
+-Rather, they define the low order two bits of
+-.IR flags ,
+-and are defined respectively as 0, 1, and 2.
+-In other words, the combination
+-.B "O_RDONLY | O_WRONLY"
+-is a logical error, and certainly does not have the same meaning as
+-.BR O_RDWR .
+-Linux reserves the special, nonstandard access mode 3 (binary 11) in
+-.I flags
+-to mean:
+-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 to be used only for device-specific
+-.BR ioctl (2)
+-operations.
+-.\" See for example util-linux's disk-utils/setfdprm.c
+-.\" For some background on access mode 3, see
+-.\" http://thread.gmane.org/gmane.linux.kernel/653123
+-.\" "[RFC] correct flags to f_mode conversion in __dentry_open"
+-.\" LKML, 12 Mar 2008
+ .LP
+ The (undefined) effect of
+ .B O_RDONLY | O_TRUNC
+@@ -791,32 +1073,6 @@ On many systems the file is actually truncated.
+ .\" Tru64 5.1B: truncate
+ .\" HP-UX 11.22: truncate
+ .\" FreeBSD 4.7: truncate
+-.PP
+-There are many infelicities in the protocol underlying NFS, affecting
+-amongst others
+-.BR O_SYNC " and " O_NDELAY .
+-
+-POSIX provides for three different variants of synchronized I/O,
+-corresponding to the flags
+-.BR O_SYNC ,
+-.BR O_DSYNC ,
+-and
+-.BR O_RSYNC .
+-Currently (2.6.31), Linux implements only
+-.BR O_SYNC ,
+-but glibc maps
+-.B O_DSYNC
+-and
+-.B O_RSYNC
+-to the same numerical value as
+-.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 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.
+
+ Note that
+ .BR open ()
+@@ -825,19 +1081,6 @@ can open device special files, but
+ cannot create them; use
+ .BR mknod (2)
+ instead.
+-.LP
+-On NFS file systems with UID mapping enabled,
+-.BR open ()
+-may
+-return a file descriptor but, for example,
+-.BR read (2)
+-requests are denied
+-with \fBEACCES\fP.
+-This is because the client performs
+-.BR open ()
+-by checking the
+-permissions, but UID mapping is performed by the server upon
+-read and write requests.
+
+ If the file is newly created, its
+ .IR st_atime ,
+@@ -857,6 +1100,237 @@ parent directory.
+ Otherwise, if the file is modified because of the
+ .B O_TRUNC
+ flag, its st_ctime and st_mtime fields are set to the current time.
++.\"
++.\"
++.SS Open file descriptions
++The term open file description is the one used by POSIX to refer to the
++entries in the system-wide table of open files.
++In other contexts, this object is
++variously also called an "open file object",
++a "file handle", an "open file table entry",
++or\(emin kernel-developer parlance\(ema
++.IR "struct file" .
++
++When a file descriptor is duplicated (using
++.BR dup (2)
++or similar),
++the duplicate refers to the same open file description
++as the original file descriptor,
++and the two file descriptors consequently share
++the file offset and file status flags.
++Such sharing can also occur between processes:
++a child process created via
++.BR fork (2)
++inherits duplicates of its parent's file descriptors,
++and those duplicates refer to the same open file descriptions.
++
++Each
++.BR open (2)
++of a file creates a new open file description;
++thus, there may be multiple open file descriptions
++corresponding to a file inode.
++.\"
++.\"
++.SS Synchronized I/O
++The POSIX.1-2008 "synchronized I/O" option
++specifies different variants of synchronized I/O,
++and specifies the
++.BR open ()
++flags
++.BR O_SYNC ,
++.BR O_DSYNC ,
++and
++.BR O_RSYNC
++for controlling the behavior.
++Regardless of whether an implementation supports this option,
++it must at least support the use of
++.BR O_SYNC
++for regular files.
++
++Linux implements
++.BR O_SYNC
++and
++.BR O_DSYNC ,
++but not
++.BR O_RSYNC .
++(Somewhat incorrectly, glibc defines
++.BR O_RSYNC
++to have the same value as
++.BR O_SYNC .)
++
++.BR O_SYNC
++provides synchronized I/O
++.I file
++integrity completion,
++meaning write operations will flush data and all associated metadata
++to the underlying hardware.
++.BR O_DSYNC
++provides synchronized I/O
++.I data
++integrity completion,
++meaning write operations will flush data
++to the underlying hardware,
++but will only flush metadata updates that are required
++to allow a subsequent read operation to complete successfully.
++Data integrity completion can reduce the number of disk operations
++that are required for applications that don't need the guarantees
++of file integrity completion.
++
++To understand the difference between the the two types of completion,
++consider two pieces of file metadata:
++the file last modification timestamp
++.RI ( st_mtime )
++and the file length.
++All write operations will update the last file modification timestamp,
++but only writes that add data to the end of the
++file will change the file length.
++The last modification timestamp is not needed to ensure that
++a read completes successfully, but the file length is.
++Thus,
++.BR O_DSYNC
++would only guarantee to flush updates to the file length metadata
++(whereas
++.BR O_SYNC
++would also always flush the last modification timestamp metadata).
++
++Before Linux 2.6.33, Linux implemented only the
++.BR O_SYNC
++flag for
++.BR open ().
++However, when that flag was specified,
++most filesystems actually provided the equivalent of synchronized I/O
++.I data
++integrity completion (i.e.,
++.BR O_SYNC
++was actually implemented as the equivalent of
++.BR O_DSYNC ).
++
++Since Linux 2.6.33, proper
++.BR O_SYNC
++support is provided.
++However, to ensure backward binary compatibility,
++.BR O_DSYNC
++was defined with the same value as the historical
++.BR O_SYNC ,
++and
++.BR O_SYNC
++was defined as a new (two-bit) flag value that includes the
++.BR O_DSYNC
++flag value.
++This ensures that applications compiled against
++new headers get at least
++.BR O_DSYNC
++semantics on pre-2.6.33 kernels.
++.\"
++.\"
++.SS NFS
++There are many infelicities in the protocol underlying NFS, affecting
++amongst others
++.BR O_SYNC " and " O_NDELAY .
++
++On NFS filesystems with UID mapping enabled,
++.BR open ()
++may
++return a file descriptor but, for example,
++.BR read (2)
++requests are denied
++with \fBEACCES\fP.
++This is because the client performs
++.BR open ()
++by checking the
++permissions, but UID mapping is performed by the server upon
++read and write requests.
++.\"
++.\"
++.SS File access mode
++Unlike the other values that can be specified in
++.IR flags ,
++the
++.I "access mode"
++values
++.BR O_RDONLY ", " O_WRONLY ", and " O_RDWR
++do not specify individual bits.
++Rather, they define the low order two bits of
++.IR flags ,
++and are defined respectively as 0, 1, and 2.
++In other words, the combination
++.B "O_RDONLY | O_WRONLY"
++is a logical error, and certainly does not have the same meaning as
++.BR O_RDWR .
++
++Linux reserves the special, nonstandard access mode 3 (binary 11) in
++.I flags
++to mean:
++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 to be used only for device-specific
++.BR ioctl (2)
++operations.
++.\" See for example util-linux's disk-utils/setfdprm.c
++.\" For some background on access mode 3, see
++.\" http://thread.gmane.org/gmane.linux.kernel/653123
++.\" "[RFC] correct flags to f_mode conversion in __dentry_open"
++.\" LKML, 12 Mar 2008
++.\"
++.\"
++.SS Rationale for openat() and other "directory file descriptor" APIs
++.BR openat ()
++and the other system calls and library functions that take
++a directory file descriptor argument
++(i.e.,
++.BR faccessat (2),
++.BR fanotify_mark (2),
++.BR fchmodat (2),
++.BR fchownat (2),
++.BR fstatat (2),
++.BR futimesat (2),
++.BR linkat (2),
++.BR mkdirat (2),
++.BR mknodat (2),
++.BR name_to_handle_at (2),
++.BR readlinkat (2),
++.BR renameat (2),
++.BR symlinkat (2),
++.BR unlinkat (2),
++.BR utimensat (2)
++.BR mkfifoat (3),
++and
++.BR scandirat (3))
++are supported
++for two reasons.
++Here, the explanation is in terms of the
++.BR openat ()
++call, but the rationale is analogous for the other interfaces.
++
++First,
++.BR openat ()
++allows an application to avoid race conditions that could
++occur when using
++.BR open ()
++to open files in directories other than the current working directory.
++These race conditions result from the fact that some component
++of the directory prefix given to
++.BR open ()
++could be changed in parallel with the call to
++.BR open ().
++Such races can be avoided by
++opening a file descriptor for the target directory,
++and then specifying that file descriptor as the
++.I dirfd
++argument of
++.BR openat ().
++
++Second,
++.BR openat ()
++allows the implementation of a per-thread "current working
++directory", via file descriptor(s) maintained by the application.
++(This functionality can also be obtained by tricks based
++on the use of
++.IR /proc/self/fd/ dirfd,
++but less efficiently.)
++.\"
++.\"
+ .SS O_DIRECT
+ .LP
+ The
+@@ -864,12 +1338,12 @@ The
+ flag may impose alignment restrictions on the length and address
+ 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
++restrictions vary by filesystem and kernel version and might be
+ absent entirely.
+-However there is currently no file system\-independent
++However there is currently no filesystem\-independent
+ interface for an application to discover these restrictions for a given
+-file or file system.
+-Some file systems provide their own interfaces
++file or filesystem.
++Some filesystems provide their own interfaces
+ for doing so, for example the
+ .B XFS_IOC_DIOINFO
+ operation in
+@@ -877,8 +1351,15 @@ operation in
+ .LP
+ 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.
++of the filesystem.
++Since Linux 2.6.0, alignment to the logical block size of the
++underlying storage (typically 512 bytes) suffices.
++The logical block size can be determined using the
++.BR ioctl (2)
++.B BLKSSZGET
++operation or from the shell using the command:
++
++ blockdev \-\-getss
+ .LP
+ .B O_DIRECT
+ I/Os should never be run concurrently with the
+@@ -927,7 +1408,7 @@ a flag of the same name, but without alignment restrictions.
+ .B O_DIRECT
+ support was added under Linux in kernel version 2.4.10.
+ Older Linux kernels simply ignore this flag.
+-Some file systems may not implement the flag and
++Some filesystems may not implement the flag and
+ .BR open ()
+ will fail with
+ .B EINVAL
+@@ -937,16 +1418,16 @@ Applications should avoid mixing
+ .B O_DIRECT
+ and normal I/O to the same file,
+ and especially to overlapping byte regions in the same file.
+-Even when the file system correctly handles the coherency issues in
++Even when the filesystem correctly handles the coherency issues in
+ this situation, overall I/O throughput is likely to be slower than
+ using either mode alone.
+ Likewise, applications should avoid mixing
+ .BR mmap (2)
+ of files with direct I/O to the same files.
+ .LP
+-The behaviour of
++The behavior of
+ .B O_DIRECT
+-with NFS will differ from local file systems.
++with NFS will differ from local filesystems.
+ Older kernels, or
+ kernels configured in certain ways, may not support this combination.
+ The NFS protocol does not support passing the flag to the server, so
+@@ -989,6 +1470,14 @@ use
+ to enable this flag.
+ .\" FIXME . Check bugzilla report on open(O_ASYNC)
+ .\" See http://bugzilla.kernel.org/show_bug.cgi?id=5993
++
++One must check for two different error codes,
++.B EISDIR
++and
++.BR ENOENT ,
++when trying to determine whether the kernel supports
++.B O_TMPFILE
++functionality.
+ .SH SEE ALSO
+ .BR chmod (2),
+ .BR chown (2),
+@@ -1000,7 +1489,7 @@ to enable this flag.
+ .BR mknod (2),
+ .BR mmap (2),
+ .BR mount (2),
+-.BR openat (2),
++.BR open_by_handle_at (2),
+ .BR read (2),
+ .BR socket (2),
+ .BR stat (2),
+@@ -1011,11 +1500,3 @@ to enable this flag.
+ .BR fifo (7),
+ .BR path_resolution (7),
+ .BR symlink (7)
+-.SH COLOPHON
+-This page is part of release 3.53 of the Linux
+-.I man-pages
+-project.
+-A description of the project,
+-and information about reporting bugs,
+-can be found at
+-\%http://www.kernel.org/doc/man\-pages/.
+diff --git a/man2/openat.2 b/man2/openat.2
+index dae94d8..604e121 100644
+--- a/man2/openat.2
++++ b/man2/openat.2
+@@ -1,187 +1 @@
+-.\" This manpage is Copyright (C) 2006, Michael Kerrisk
+-.\"
+-.\" %%%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.
+-.\"
+-.\" Permission is granted to copy and distribute modified versions of this
+-.\" manual under the conditions for verbatim copying, provided that the
+-.\" entire resulting derived work is distributed under the terms of a
+-.\" permission notice identical to this one.
+-.\"
+-.\" Since the Linux kernel and libraries are constantly changing, this
+-.\" manual page may be incorrect or out-of-date. The author(s) assume no
+-.\" responsibility for errors or omissions, or for damages resulting from
+-.\" the use of the information contained herein. The author(s) may not
+-.\" have taken the same level of care in the production of this manual,
+-.\" which is licensed free of charge, as they might when working
+-.\" professionally.
+-.\"
+-.\" Formatted or processed versions of this manual, if unaccompanied by
+-.\" the source, must acknowledge the copyright and authors of this work.
+-.\" %%%LICENSE_END
+-.\"
+-.TH OPENAT 2 2012-05-04 "Linux" "Linux Programmer's Manual"
+-.SH NAME
+-openat \- open a file relative to a directory file descriptor
+-.SH SYNOPSIS
+-.nf
+-.B #include <fcntl.h>
+-.sp
+-.BI "int openat(int " dirfd ", const char *" pathname ", int " flags );
+-.BI "int openat(int " dirfd ", const char *" pathname ", int " flags \
+-", mode_t " mode );
+-.fi
+-.sp
+-.in -4n
+-Feature Test Macro Requirements for glibc (see
+-.BR feature_test_macros (7)):
+-.in
+-.sp
+-.BR openat ():
+-.PD 0
+-.ad l
+-.RS 4
+-.TP 4
+-Since glibc 2.10:
+-_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
+-.TP
+-Before glibc 2.10:
+-_ATFILE_SOURCE
+-.RE
+-.ad
+-.PD
+-.SH DESCRIPTION
+-The
+-.BR openat ()
+-system call operates in exactly the same way as
+-.BR open (2),
+-except for the differences described in this manual page.
+-
+-If the pathname given in
+-.I pathname
+-is relative, then it is interpreted relative to the directory
+-referred to by the file descriptor
+-.I dirfd
+-(rather than relative to the current working directory of
+-the calling process, as is done by
+-.BR open (2)
+-for a relative pathname).
+-
+-If
+-.I pathname
+-is relative and
+-.I dirfd
+-is the special value
+-.BR AT_FDCWD ,
+-then
+-.I pathname
+-is interpreted relative to the current working
+-directory of the calling process (like
+-.BR open (2)).
+-
+-If
+-.I pathname
+-is absolute, then
+-.I dirfd
+-is ignored.
+-.SH RETURN VALUE
+-On success,
+-.BR openat ()
+-returns a new file descriptor.
+-On error, \-1 is returned and
+-.I errno
+-is set to indicate the error.
+-.SH ERRORS
+-The same errors that occur for
+-.BR open (2)
+-can also occur for
+-.BR openat ().
+-The following additional errors can occur for
+-.BR openat ():
+-.TP
+-.B EBADF
+-.I dirfd
+-is not a valid file descriptor.
+-.TP
+-.B ENOTDIR
+-.I pathname
+-is relative and
+-.I dirfd
+-is a file descriptor referring to a file other than a directory.
+-.SH VERSIONS
+-.BR openat ()
+-was added to Linux in kernel 2.6.16;
+-library support was added to glibc in version 2.4.
+-.SH CONFORMING TO
+-POSIX.1-2008.
+-A similar system call exists on Solaris.
+-.\" The 'at' suffix in Solaris is actually double sensed. It
+-.\" primarily referred to "extended *at*tributes", which are
+-.\" handled by Solaris' O_XATTR flag, but was also intended
+-.\" to refer to the notion of "at a relative location".
+-.\"
+-.\" See the following for a discussion of the inconsistent
+-.\" naming of the *at() functions:
+-.\" http://www.opengroup.org/austin/mailarchives/ag/msg09103.html
+-.\" Subject: RE: The naming of at()s is a difficult matter
+-.\" From: Don Cragun
+-.\" Date: Tue, 14 Feb 2006 14:56:50 -0800 (PST)
+-.\"
+-.SH NOTES
+-.BR openat ()
+-and other similar system calls suffixed "at" are supported
+-for two reasons.
+-
+-First,
+-.BR openat ()
+-allows an application to avoid race conditions that could
+-occur when using
+-.BR open (2)
+-to open files in directories other than the current working directory.
+-These race conditions result from the fact that some component
+-of the directory prefix given to
+-.BR open (2)
+-could be changed in parallel with the call to
+-.BR open (2).
+-Such races can be avoided by
+-opening a file descriptor for the target directory,
+-and then specifying that file descriptor as the
+-.I dirfd
+-argument of
+-.BR openat ().
+-
+-Second,
+-.BR openat ()
+-allows the implementation of a per-thread "current working
+-directory", via file descriptor(s) maintained by the application.
+-(This functionality can also be obtained by tricks based
+-on the use of
+-.IR /proc/self/fd/ dirfd,
+-but less efficiently.)
+-.SH SEE ALSO
+-.BR faccessat (2),
+-.BR fchmodat (2),
+-.BR fchownat (2),
+-.BR fstatat (2),
+-.BR futimesat (2),
+-.BR linkat (2),
+-.BR mkdirat (2),
+-.BR mknodat (2),
+-.BR open (2),
+-.BR readlinkat (2),
+-.BR renameat (2),
+-.BR symlinkat (2),
+-.BR unlinkat (2),
+-.BR utimensat (2),
+-.BR mkfifoat (3),
+-.BR path_resolution (7)
+-.SH COLOPHON
+-This page is part of release 3.53 of the Linux
+-.I man-pages
+-project.
+-A description of the project,
+-and information about reporting bugs,
+-can be found at
+-\%http://www.kernel.org/doc/man\-pages/.
++.so man2/open.2
+--
+1.9.3
+
diff --git a/man-pages.spec b/man-pages.spec
index e929038..c7126ce 100644
--- a/man-pages.spec
+++ b/man-pages.spec
@@ -7,7 +7,7 @@
Summary: Man (manual) pages from the Linux Documentation Project
Name: man-pages
Version: 3.53
-Release: 2%{?dist}
+Release: 3%{?dist}
License: GPL+ and GPLv2+ and BSD and MIT and Copyright only and IEEE
Group: Documentation
URL: http://www.kernel.org/doc/man-pages/
@@ -35,7 +35,8 @@ Patch21: man-pages-3.42-close.patch
Patch22: man-pages-3.42-connect.patch
# resolves: #771540
Patch23: man-pages-3.43-tcp-congestion.patch
-
+# resolves: #1099453
+Patch24: man-pages-3.57-open.2.patch
Autoreq: false
BuildArch: noarch
@@ -58,6 +59,7 @@ Documentation Project (LDP).
%patch21 -p1
%patch22 -p1
%patch23 -p1
+%patch24 -p1
## Remove man pages we are not going to use ##
@@ -120,6 +122,11 @@ cd ..
%lang(en) %{_mandir}/en/man*/*
%changelog
+* Wed Jul 23 2014 jchaloup <jchaloup at redhat.com> - 3.53-3
+- resolves: #1099453
+ new man page for open.2
+ removing openat as it is part of open.2
+
* Wed Dec 4 2013 Peter Schiffer <pschiffe at redhat.com> - 3.53-2
- resolves: #1031703
removed pt_chown(5) man page
More information about the scm-commits
mailing list