mirror of
https://github.com/9fans/plan9port.git
synced 2025-01-12 11:10:07 +00:00
168 lines
3 KiB
Text
168 lines
3 KiB
Text
.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)
|