Hello Al et al, Documenting O_PATH fell by the wayside last year (http://thread.gmane.org/gmane.linux.man/2790) as I got distracted with other tasks. A recent prod or two have reminded me restart this. I have the following patch queued to document O_PATH.
Could you please review. I've provided the O_PATH doc both as
formatted text, for ease of reviewing, and as a patch and entire file
(attached).
Thanks,
Michael
O_PATH (since Linux 2.6.39)
Obtain a file descriptor that can be used for two pur‐
poses: 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., read(2), write(2), fch‐
mod(2), fchown(2), fgetxattr(2)) fail with the error
EBADF.
The following operations can be performed on the result‐
ing file descriptor:
* close(2); fchdir(2) (since Linux 3.5); fstat(2)
(since Linux 3.6).
* Duplicating the file descriptor (dup(2), fcntl(2)
F_DUPFD, etc.).
* Getting and setting file descriptor flags (fcntl(2)
F_GETFD and F_SETFD).
* Passing the file descriptor as the dirfd argument of
openat(2) and the other "*at()" system calls.
* Passing the file descriptor to another process via a
UNIX domain socket (see SCM_RIGHTS in unix(7)).
When O_PATH is specified in flags, flag bits other than
O_DIRECTORY and O_NOFOLLOW are ignored.
If the 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 dirfd
argument in calls to fchownat(2), fstatat(2), linkat(2),
and readlinkat(2) with an empty pathname to have the
calls operate on the symbolic link.
diff --git a/man2/open.2 b/man2/open.2
index e518c1f..c27be8f 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -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,89 @@ 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
+.\"
+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 +716,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
open.2
Description: Binary data
