20060303-partial

1 files changed, 159 insertions, 0 deletions

diff --git a/man/5/attach b/man/5/attach
new file mode 100644
index 00000000..ae561d7b
--- /dev/null
+++ b/man/5/attach
@@ -0,0 +1,159 @@
+.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)