Skip to content

man: Correct and clarify things about openfd #692

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

man: Correct and clarify things about openfd #692

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b3ca0e9
man: openfd returns an AF_UNIX socket, not a pipe
LukeShu Jan 2, 2025
23bf350
man: describe how Ropenfd sends the file descriptor
LukeShu Jan 2, 2025
e784648
man: Copy the BUG about version strings from 9pclient(3) to openfd(9p)
LukeShu Jan 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions man/man3/9pclient.3
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -418,11 +418,11 @@ opens a file on the 9P server
for reading or writing but returns a Unix file descriptor
instead of a fid structure.
The file descriptor is actually one end of a
.MR pipe (2) .
.MR socketpair (2) .
A proxy process on the other end is ferrying data
between the pipe and the 9P fid.
Because of the implementation as a pipe,
the only signal of a read or write error is the closing of the pipe.
between the socket and the 9P fid.
Because of the implementation as a socket,
the only signal of a read or write error is the closing of the socket.
The file descriptor remains valid even after the
.B CFsys
is unmounted.
Expand Down
41 changes: 29 additions & 12 deletions man/man9/openfd.9p
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,18 +28,16 @@ transaction,
is considered by the client to have been clunked
and can be reused.
.PP
The returned Unix file descriptor is one end of a Unix pipe.
A proxy process at the other end transfers data between
the pipe and the 9P server.
Because it is a pipe, errors on reads and writes are discarded
and
.I mode
must be
.B OREAD
or
.BR OWRITE ;
it cannot be
.BR ORDWR .
In addition to sending a
.B Ropenfd
response, the server also sends an out-of-band control-message
containing a Unix file descriptor (an
.BR SCM_RIGHTS
message; this requires that the 9P transport be a Unix domain socket).
This returned Unix file descriptor is one end of a Unix domain socket;
a proxy process at the other end transfers data between
the socket and the 9P server.
Because it is a socket, errors on reads and writes are discarded.
.PP
.I Openfd
is implemented by
Expand All @@ -58,3 +56,22 @@ message.
generates an
.B openfd
message.
.SH BUGS
The returned
.I unixfd
field nominally refers to the file descriptor that has been sent in
the control-message. However, the file descriptor in the client
process will not necessarily have the same number as in the server
process, so clients should ignore this field and instead trust the
file descriptor number from the control-message.
.MR 9pclient (3)
accomplishes this by having
.B \*9/src/lib9pclient/fs.c
.IR _fsrecv
rewrite the field to the value from the control-message before
returning the R-message.
.PP
There is not a special version string to distinguish between servers
that support
.I openfd
and servers that do not.