10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
169 lines
3.0 KiB
Plaintext
169 lines
3.0 KiB
Plaintext
.TH ATTACH 9P
|
|
.SH NAME
|
|
attach, auth \- messages to establish a connection
|
|
.SH SYNOPSIS
|
|
.ta \w'\fLTauth 'u
|
|
.IR size [4]
|
|
.B Tauth
|
|
.IR tag [2]
|
|
.IR afid [4]
|
|
.IR uname [ s ]
|
|
.IR aname [ s ]
|
|
.br
|
|
.IR size [4]
|
|
.B Rauth
|
|
.IR tag [2]
|
|
.IR aqid [13]
|
|
.PP
|
|
.IR size [4]
|
|
.B Tattach
|
|
.IR tag [2]
|
|
.IR fid [4]
|
|
.IR afid [4]
|
|
.IR uname [ s ]
|
|
.IR aname [ s ]
|
|
.br
|
|
.IR size [4]
|
|
.B Rattach
|
|
.IR tag [2]
|
|
.IR qid [13]
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The
|
|
.B attach
|
|
message serves as a fresh introduction from a user on
|
|
the client machine to the server.
|
|
The message identifies the user
|
|
.RI ( uname )
|
|
and may select
|
|
the file tree to access
|
|
.RI ( aname ).
|
|
The
|
|
.I afid
|
|
argument specifies a fid previously established by an
|
|
.B auth
|
|
message, as described below.
|
|
.PP
|
|
As a result of the
|
|
.B attach
|
|
transaction, the client will have a connection to the root
|
|
directory of the desired file tree,
|
|
represented by
|
|
.IR fid .
|
|
An error is returned if
|
|
.I fid
|
|
is already in use.
|
|
The server's idea of the root of the file tree is represented by the returned
|
|
.IR qid .
|
|
.PP
|
|
If the client does not wish to authenticate the connection, or knows that
|
|
authentication is not required, the
|
|
.I afid
|
|
field in the
|
|
.B attach
|
|
message should be set to
|
|
.BR NOFID ,
|
|
defined as
|
|
.B (u32int)~0
|
|
in
|
|
.BR <fcall.h> .
|
|
If the client does wish to authenticate, it must acquire and validate an
|
|
.I afid
|
|
using an
|
|
.B auth
|
|
message before doing the
|
|
.BR attach .
|
|
.PP
|
|
The
|
|
.B auth
|
|
message contains
|
|
.IR afid ,
|
|
a new fid to be established for authentication, and the
|
|
.I uname
|
|
and
|
|
.I aname
|
|
that will be those of the following
|
|
.B attach
|
|
message.
|
|
If the server does not require authentication, it returns
|
|
.B Rerror
|
|
to the
|
|
.B Tauth
|
|
message.
|
|
.PP
|
|
If the server does require authentication, it returns
|
|
.I aqid
|
|
defining a file of type
|
|
.B QTAUTH
|
|
(see
|
|
.IR intro (9P))
|
|
that may be read and written (using
|
|
.B read
|
|
and
|
|
.B write
|
|
messages in the usual way) to execute an authentication protocol.
|
|
That protocol's definition is not part of 9P itself.
|
|
.PP
|
|
Once the protocol is complete, the same
|
|
.I afid
|
|
is presented in the
|
|
.B attach
|
|
message for the user, granting entry.
|
|
The same validated
|
|
.I afid
|
|
may be used for multiple
|
|
.B attach
|
|
messages with the same
|
|
.I uname
|
|
and
|
|
.IR aname .
|
|
.SH ENTRY POINTS
|
|
.I Fsmount
|
|
and
|
|
.I fsauth
|
|
(see
|
|
.MR 9pclient 3 )
|
|
generate
|
|
.B attach
|
|
and
|
|
.B auth
|
|
transactions.
|
|
.\" An
|
|
.\" .B attach
|
|
.\" transaction will be generated for kernel devices
|
|
.\" (see
|
|
.\" .IR intro (3))
|
|
.\" when a system call evaluates a file name
|
|
.\" beginning with
|
|
.\" .LR # .
|
|
.\" .IR Pipe (2)
|
|
.\" generates an attach on the kernel device
|
|
.\" .IR pipe (3).
|
|
.\" The
|
|
.\" .I mount
|
|
.\" system call
|
|
.\" (see
|
|
.\" .IR bind (2))
|
|
.\" generates an
|
|
.\" .B attach
|
|
.\" message to the remote file server.
|
|
.\" When the kernel boots, an
|
|
.\" .I attach
|
|
.\" is made to the root device,
|
|
.\" .IR root (3),
|
|
.\" and then an
|
|
.\" .B attach
|
|
.\" is made to the requested file server machine.
|
|
.\" .PP
|
|
.\" An
|
|
.\" .B auth
|
|
.\" transaction is generated by the
|
|
.\" .IR fauth (2)
|
|
.\" system call or by the first
|
|
.\" .B mount
|
|
.\" system call on an uninitialized connection.
|
|
.SH SEE ALSO
|
|
.MR 9pclient 3 ,
|
|
.IR version (9P),
|
|
Plan 9's \fIauthsrv\fR(6)
|