1 .TH ATTACH 9P 
2 .SH NAME
3 attach, auth \- messages to establish a connection
4 .SH SYNOPSIS
5 .ta \w'\fLTauth 'u
6 .IR size [4]
7 .B Tauth
8 .IR tag [2]
9 .IR afid [4]
10 .IR uname [ s ]
11 .IR aname [ s ]
12 .br
13 .IR size [4]
14 .B Rauth
15 .IR tag [2]
16 .IR aqid [13]
17 .PP
18 .IR size [4]
19 .B Tattach
20 .IR tag [2]
21 .IR fid [4]
22 .IR afid [4]
23 .IR uname [ s ]
24 .IR aname [ s ]
25 .br
26 .IR size [4]
27 .B Rattach
28 .IR tag [2]
29 .IR qid [13]
30 .SH DESCRIPTION
31 .PP
32 The
33 .B attach
34 message serves as a fresh introduction from a user on
35 the client machine to the server.
36 The message identifies the user
37 .RI ( uname )
38 and may select
39 the file tree to access
40 .RI ( aname ).
41 The
42 .I afid
43 argument specifies a fid previously established by an
44 .B auth
45 message, as described below.
46 .PP
47 As a result of the
48 .B attach
49 transaction, the client will have a connection to the root
50 directory of the desired file tree,
51 represented by
52 .IR fid .
53 An error is returned if
54 .I fid
55 is already in use.
56 The server's idea of the root of the file tree is represented by the returned
57 .IR qid .
58 .PP
59 If the client does not wish to authenticate the connection, or knows that
60 authentication is not required, the
61 .I afid
62 field in the
63 .B attach
64 message should be set to
65 .BR NOFID ,
66 defined as
67 .B (u32int)~0
68 in
69 .BR <fcall.h> .
70 If the client does wish to authenticate, it must acquire and validate an
71 .I afid
72 using an
73 .B auth
74 message before doing the
75 .BR attach .
76 .PP
77 The
78 .B auth
79 message contains
80 .IR afid ,
81 a new fid to be established for authentication, and the
82 .I uname
83 and
84 .I aname
85 that will be those of the following
86 .B attach
87 message.
88 If the server does not require authentication, it returns
89 .B Rerror
90 to the
91 .B Tauth
92 message.
93 .PP
94 If the server does require authentication, it returns
95 .I aqid
96 defining a file of type
97 .B QTAUTH
98 (see
99 .IR intro (9P))
100 that may be read and written (using
101 .B read
102 and
103 .B write
104 messages in the usual way) to execute an authentication protocol.
105 That protocol's definition is not part of 9P itself.
106 .PP
107 Once the protocol is complete, the same
108 .I afid
109 is presented in the
110 .B attach
111 message for the user, granting entry.
112 The same validated
113 .I afid
114 may be used for multiple
115 .B attach
116 messages with the same
117 .I uname
118 and
119 .IR aname .
120 .SH ENTRY POINTS
121 .I Fsmount
122 and
123 .I fsauth
124 (see
125 .MR 9pclient (3) )
126 generate
127 .B attach
128 and
129 .B auth
130 transactions.
131 .\" An
132 .\" .B attach
133 .\" transaction will be generated for kernel devices
134 .\" (see
135 .\" .IR intro (3))
136 .\" when a system call evaluates a file name
137 .\" beginning with
138 .\" .LR # .
139 .\" .IR Pipe (2)
140 .\" generates an attach on the kernel device
141 .\" .IR pipe (3).
142 .\" The
143 .\" .I mount
144 .\" system call
145 .\" (see
146 .\" .IR bind (2))
147 .\" generates an
148 .\" .B attach
149 .\" message to the remote file server.
150 .\" When the kernel boots, an
151 .\" .I attach
152 .\" is made to the root device,
153 .\" .IR root (3),
154 .\" and then an
155 .\" .B attach
156 .\" is made to the requested file server machine.
157 .\" .PP
158 .\" An
159 .\" .B auth
160 .\" transaction is generated by the
161 .\" .IR fauth (2)
162 .\" system call or by the first
163 .\" .B mount
164 .\" system call on an uninitialized connection.
165 .SH SEE ALSO
166 .MR 9pclient (3) ,
167 .IR version (9P),
168 Plan 9's \fIauthsrv\fR(6)