160 lines
2.8 KiB
Plaintext
160 lines
2.8 KiB
Plaintext
.TH ATTACH 5
|
|
.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 (5))
|
|
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
|
|
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
|
|
.IR auth (2),
|
|
.IR fauth (2),
|
|
.IR version (5),
|
|
.IR authsrv (6)
|