.TH ATTACH 5 .SH NAMEattach, 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.PPThe.B attachmessage serves as a fresh introduction from a user onthe client machine to the server.The message identifies the user.RI ( uname )and may selectthe file tree to access.RI ( aname ).The.I afidargument specifies a fid previously established by an.B authmessage, as described below..PPAs a result of the.B attachtransaction, the client will have a connection to the rootdirectory of the desired file tree,represented by.IR fid .An error is returned if.I fidis already in use.The server's idea of the root of the file tree is represented by the returned.IR qid ..PPIf the client does not wish to authenticate the connection, or knows thatauthentication is not required, the.I afidfield in the.B attachmessage should be set to.BR NOFID ,defined as.B (u32int)~0in.BR <fcall.h> .If the client does wish to authenticate, it must acquire and validate an.I afidusing an.B authmessage before doing the.BR attach ..PPThe.B authmessage contains.IR afid ,a new fid to be established for authentication, and the.I unameand.I anamethat will be those of the following.B attachmessage.If the server does not require authentication, it returns.B Rerrorto the.B Tauthmessage..PPIf the server does require authentication, it returns.I aqiddefining a file of type.B QTAUTH(see.IR intro (5))that may be read and written (using.B readand.B writemessages in the usual way) to execute an authentication protocol.That protocol's definition is not part of Styx itself..PPOnce the protocol is complete, the same.I afidis presented in the.B attachmessage for the user, granting entry.The same validated.I afidmay be used for multiple.B attachmessages with the same.I unameand.IR aname ..SH ENTRY POINTSAn.B attachtransaction will be generated for kernel devices(see.IR intro (3))when a system call evaluates a file namebeginning with.LR # ..IR Sys-pipe (2)generates an attach on the kernel device.IR pipe (3).The.B mountcall (see.IR sys-bind (2))generates an.B attachmessage to the remote file server.When the kernel boots, an.I attachis made to the root device,.IR root (3),and then an.B attachis made to the requested file server machine..PPAn.B authtransaction is generated by the.IR fauth (2)system call or by the first.B mountsystem call on an uninitialized connection..SH SEE ALSO.IR sys-bind (2),.IR sys-fauth (2),.IR intro (3),.IR root (3),.IR version (5)
.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 Styx 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 Sys-pipe (2)
generates an attach on the kernel device
.IR pipe (3).
The
.B mount
call (see
.IR sys-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 sys-bind (2),
.IR sys-fauth (2),
.IR intro (3),
.IR root (3),
.IR version (5)