Some of the wording around empty paths in path_resolution(7) also needed to be reworked since it's now legal (if you pass O_EMPTYPATH). Signed-off-by: Aleksa Sarai <cyphar@xxxxxxxxxx> --- man2/open.2 | 42 +++++++++++++++++++++++++++++++++++++++++- man7/path_resolution.7 | 17 ++++++++++++++++- 2 files changed, 57 insertions(+), 2 deletions(-) diff --git a/man2/open.2 b/man2/open.2 index b0f485b41589..7217fe056e5e 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -48,7 +48,7 @@ .\" FIXME . Apr 08: The next POSIX revision has O_EXEC, O_SEARCH, and .\" O_TTYINIT. Eventually these may need to be documented. --mtk .\" -.TH OPEN 2 2018-04-30 "Linux" "Linux Programmer's Manual" +.TH OPEN 2 2019-10-03 "Linux" "Linux Programmer's Manual" .SH NAME open, openat, creat \- open and possibly create a file .SH SYNOPSIS @@ -421,6 +421,21 @@ was followed by a call to .BR fdatasync (2)). .IR "See NOTES below" . .TP +.BR O_EMPTYPATH " (since Linux 5.FOO)" +If \fIpathname\fP is an empty string, re-open the the file descriptor given as +the \fIdirfd\fP argument to +.BR openat (2). +This can be used with both ordinary (file and directory) and \fBO_PATH\fP file +descriptors, but cannot be used with +.BR AT_FDCWD +(or as an argument to plain +.BR open (2).) When re-opening an \fBO_PATH\fP file descriptor, the same "link +mode" restrictions apply as with re-opening through +.BR proc (5) +(see +.BR path_resolution "(7) and " symlink (7) +for more details.) +.TP .B O_EXCL Ensure that this call creates the file: if this flag is specified in conjunction with @@ -668,6 +683,13 @@ with (or via procfs using .BR AT_SYMLINK_FOLLOW ) even if the file is not a directory. +You can even "re-open" (or upgrade) an +.BR O_PATH +file descriptor by using +.BR O_EMPTYPATH +(see the section for +.BR O_EMPTYPATH +for more details.) .IP * Passing the file descriptor to another process via a UNIX domain socket (see @@ -958,6 +980,15 @@ is not allowed. (See also .BR path_resolution (7).) .TP +.B EBADF +.I pathname +was an empty string (and +.B O_EMPTYPATH +was passed) with +.BR open (2) +(instead of +.BR openat (2).) +.TP .B EDQUOT Where .B O_CREAT @@ -1203,6 +1234,15 @@ The following additional errors can occur for .I dirfd is not a valid file descriptor. .TP +.B EBADF +.I pathname +was an empty string (and +.B O_EMPTYPATH +was passed), but the provided +.I dirfd +was an invalid file descriptor (or was +.BR AT_FDCWD .) +.TP .B ENOTDIR .I pathname is a relative pathname and diff --git a/man7/path_resolution.7 b/man7/path_resolution.7 index 46f25ec4cdfa..85dd354e9a93 100644 --- a/man7/path_resolution.7 +++ b/man7/path_resolution.7 @@ -22,7 +22,7 @@ .\" the source, must acknowledge the copyright and authors of this work. .\" %%%LICENSE_END .\" -.TH PATH_RESOLUTION 7 2017-11-26 "Linux" "Linux Programmer's Manual" +.TH PATH_RESOLUTION 7 2019-10-03 "Linux" "Linux Programmer's Manual" .SH NAME path_resolution \- how a pathname is resolved to a file .SH DESCRIPTION @@ -198,6 +198,21 @@ successfully. Linux returns .B ENOENT in this case. +.PP +As of Linux 5.FOO, an empty path argument can be used to indicate the "re-open" +an existing file descriptor if +.B O_EMPTYPATH +is passed as a flag argument to +.BR openat (2), +with the +.I dfd +argument indicating which file descriptor to "re-open". This is approximately +equivalent to opening +.I /proc/self/fd/$fd +where +.I $fd +is the open file descriptor to be "re-opened". + .SS Permissions The permission bits of a file consist of three groups of three bits; see .BR chmod (1) -- 2.23.0
