Date:	Thu, 14 Mar 2013 10:35:59 +0100
From:	"Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To:	Al Viro <viro@...iv.linux.org.uk>
Cc:	lkml <linux-kernel@...r.kernel.org>,
	Mike Frysinger <vapier@...too.org>,
	"Theodore Ts'o" <tytso@....edu>,
	Peter Schiffer <pschiffe@...hat.com>,
	"Aneesh Kumar K.V" <aneesh.kumar@...ux.vnet.ibm.com>,
	linux-man <linux-man@...r.kernel.org>, benjamin@...hon.org
Subject: [PATCH] open(2): document O_PATH

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

Download attachment "open.2" of type "application/octet-stream" (27453 bytes)

Powered by blists - more mailing lists