1 files changed, 168 insertions, 0 deletions
diff --git a/man/man9/attach.9p b/man/man9/attach.9p
new file mode 100644
index 00000000..ddcf7476
--- /dev/null
+++ b/man/man9/attach.9p
@@ -0,0 +1,168 @@
+.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)