open.2: Document O_PATH

See also https://bugzilla.redhat.com/show_bug.cgi?id=885740

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 100 insertions, 2 deletions

diff --git a/man2/open.2 b/man2/open.2
index abfa0ad0..ee97fca6 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -47,7 +47,6 @@
 .\" 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.
-.\" FIXME: Linux 2.6.39 added O_PATH
 .\"
 .TH OPEN 2 2013-02-18 "Linux" "Linux Programmer's Manual"
 .SH NAME
@@ -424,6 +423,9 @@ If \fIpathname\fP is a symbolic link, then the open fails.
 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
+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
 .\" used\fP.
@@ -441,6 +443,101 @@ For a discussion of the effect of
 in conjunction with mandatory file locks and with file leases, see
 .BR fcntl (2).
 .TP
+.BR O_PATH " (since Linux 2.6.39)"
+.\" commit 1abf0c718f15a56a0a435588d1b104c7a37dc9bd
+.\" commit 326be7b484843988afe57566b627fb7a70beac56
+.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
+.\"
+.\" http://thread.gmane.org/gmane.linux.man/2790/focus=3496
+.\"	Subject: Re: [PATCH] open(2): document O_PATH
+.\"	Newsgroups: gmane.linux.man, gmane.linux.kernel
+.\"
+.\" FIXME: The following needs to be documented somewhere
+.\" commit bcda76524cd1fa32af748536f27f674a13e56700
+.\"     Allow O_PATH for symlinks
+.\"     ...
+.\"     We will be able to do useful things with them after the next commit...
+.\"     readlinkat() and fchownat() will be possible to use with dfd being an
+.\"     O_PATH-opened symlink and empty relative pathname.  Combined with
+.\"     open_by_handle() it'll give us a way to do realink-by-handle and
+.\"     lchown-by-handle without messing with more redundant syscalls.
+.\"     ....
+.\"	See also commit 1fa1e7f615f4d3ae436fa319af6e4eebdd4026a8
+.\"
+Obtain a file descriptor that can be used for two purposes:
+to indicate a location in the file-system 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))
+fail with the error
+.BR EBADF .
+
+The following operations
+.I can
+be performed on the resulting file descriptor:
+.RS
+.IP * 3
+.BR close (2);
+.BR fchdir (2)
+(since Linux 3.5);
+.\" commit 332a2e1244bd08b9e3ecd378028513396a004a24
+.BR fstat (2)
+(since Linux 3.6).
+.\" fstat(): commit 55815f70147dcfa3ead5738fd56d3574e2e3c1c2
+.IP *
+Duplicating the file descriptor
+.RB ( dup (2),
+.BR fcntl (2)
+.BR F_DUPFD ,
+etc.).
+.IP *
+Getting and setting file descriptor flags
+.RB ( fcntl (2)
+.BR F_GETFD
+and
+.BR F_SETFD ).
+.IP *
+Passing the file descriptor as the
+.IR dirfd
+argument of
+.BR openat (2)
+and the other "*at()" system calls.
+.IP *
+Passing the file descriptor to another process via a UNIX domain socket
+(see
+.BR SCM_RIGHTS
+in
+.BR unix (7)).
+.RE
+.IP
+When
+.B O_PATH
+is specified in
+.IR flags ,
+flag bits other than
+.BR O_DIRECTORY
+and
+.BR O_NOFOLLOW
+are ignored.
+
+If the
+.BR O_NOFOLLOW
+flag is also specified,
+then the call returns a file descriptor referring to the symbolic link.
+This file descriptor can be used as the
+.I dirfd
+argument in calls to
+.BR fchownat (2),
+.BR fstatat (2),
+.BR linkat (2),
+and
+.BR readlinkat (2)
+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
@@ -631,8 +728,9 @@ SVr4, 4.3BSD, POSIX.1-2001.
 The
 .BR O_DIRECTORY ,
 .BR O_NOATIME ,
+.BR O_NOFOLLOW ,
 and
-.B O_NOFOLLOW
+.BR O_PATH
 flags are Linux-specific, and one may need to define
 .B _GNU_SOURCE
 (before including