.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
.IR 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
.IR 9pclient (3),
.IR version (9P),
Plan 9's \fIauthsrv\fR(6)