Linux-man Archive on
 help / color / Atom feed
From: Aleksa Sarai <>
To: Al Viro <>,
	Michael Kerrisk <>
Cc: Aleksa Sarai <>,
	Christian Brauner <>,
	Aleksa Sarai <>,,,
Subject: [PATCH RFC 2/3] open.2: add O_EMPTYPATH documentation
Date: Fri,  4 Oct 2019 00:55:40 +1000
Message-ID: <> (raw)
In-Reply-To: <>

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 <>
 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"
 open, openat, creat \- open and possibly create a file
@@ -421,6 +421,21 @@ was followed by a call to
 .BR fdatasync (2)).
 .IR "See NOTES below" .
+.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
+(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)
+.BR path_resolution "(7) and " symlink (7)
+for more details.)
 Ensure that this call creates the file:
 if this flag is specified in conjunction with
@@ -668,6 +683,13 @@ with
 (or via procfs using
 even if the file is not a directory.
+You can even "re-open" (or upgrade) an
+file descriptor by using
+(see the section for
+for more details.)
 .IP *
 Passing the file descriptor to another process via a UNIX domain socket
@@ -958,6 +980,15 @@ is not allowed.
 (See also
 .BR path_resolution (7).)
+.I pathname
+was an empty string (and
+was passed) with
+.BR open (2)
+(instead of
+.BR openat (2).)
@@ -1203,6 +1234,15 @@ The following additional errors can occur for
 .I dirfd
 is not a valid file descriptor.
+.I pathname
+was an empty string (and
+was passed), but the provided
+.I dirfd
+was an invalid file descriptor (or was
 .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.
-.TH PATH_RESOLUTION 7 2017-11-26 "Linux" "Linux Programmer's Manual"
+.TH PATH_RESOLUTION 7 2019-10-03 "Linux" "Linux Programmer's Manual"
 path_resolution \- how a pathname is resolved to a file
@@ -198,6 +198,21 @@ successfully.
 Linux returns
 in this case.
+As of Linux 5.FOO, an empty path argument can be used to indicate the "re-open"
+an existing file descriptor if
+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
+.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)

  parent reply index

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-10-03 14:55 [PATCH RFC 0/3] document openat2(2) patch series Aleksa Sarai
2019-10-03 14:55 ` [PATCH RFC 1/3] symlink.7: document magic-links more completely Aleksa Sarai
2019-10-07 16:36   ` Jann Horn
2019-10-08  1:33     ` Aleksa Sarai
2019-10-09  7:55   ` Michael Kerrisk (man-pages)
2019-10-09  9:57     ` Aleksa Sarai
2019-10-03 14:55 ` Aleksa Sarai [this message]
2019-10-09  8:01   ` [PATCH RFC 2/3] open.2: add O_EMPTYPATH documentation Michael Kerrisk (man-pages)
2019-10-09 10:00     ` Aleksa Sarai
2019-10-03 14:55 ` [PATCH RFC 3/3] openat2.2: document new openat2(2) syscall Aleksa Sarai
2019-10-09  8:36   ` Michael Kerrisk (man-pages)
2019-10-09 10:17     ` Aleksa Sarai
2019-10-09 10:32       ` Michael Kerrisk (man-pages)
2019-10-03 14:55 ` [PATCH RFC 3/3] openat2.2: document new syscall Aleksa Sarai
2019-10-03 15:00   ` Aleksa Sarai

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Linux-man Archive on

Archives are clonable:
	git clone --mirror linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ \
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:

AGPL code for this site: git clone