attach.9p (3090B)
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)