Blob
1 .TH ATTACH 9P2 .SH NAME3 attach, auth \- messages to establish a connection4 .SH SYNOPSIS5 .ta \w'\fLTauth 'u6 .IR size [4]7 .B Tauth8 .IR tag [2]9 .IR afid [4]10 .IR uname [ s ]11 .IR aname [ s ]12 .br13 .IR size [4]14 .B Rauth15 .IR tag [2]16 .IR aqid [13]17 .PP18 .IR size [4]19 .B Tattach20 .IR tag [2]21 .IR fid [4]22 .IR afid [4]23 .IR uname [ s ]24 .IR aname [ s ]25 .br26 .IR size [4]27 .B Rattach28 .IR tag [2]29 .IR qid [13]30 .SH DESCRIPTION31 .PP32 The33 .B attach34 message serves as a fresh introduction from a user on35 the client machine to the server.36 The message identifies the user37 .RI ( uname )38 and may select39 the file tree to access40 .RI ( aname ).41 The42 .I afid43 argument specifies a fid previously established by an44 .B auth45 message, as described below.46 .PP47 As a result of the48 .B attach49 transaction, the client will have a connection to the root50 directory of the desired file tree,51 represented by52 .IR fid .53 An error is returned if54 .I fid55 is already in use.56 The server's idea of the root of the file tree is represented by the returned57 .IR qid .58 .PP59 If the client does not wish to authenticate the connection, or knows that60 authentication is not required, the61 .I afid62 field in the63 .B attach64 message should be set to65 .BR NOFID ,66 defined as67 .B (u32int)~068 in69 .BR <fcall.h> .70 If the client does wish to authenticate, it must acquire and validate an71 .I afid72 using an73 .B auth74 message before doing the75 .BR attach .76 .PP77 The78 .B auth79 message contains80 .IR afid ,81 a new fid to be established for authentication, and the82 .I uname83 and84 .I aname85 that will be those of the following86 .B attach87 message.88 If the server does not require authentication, it returns89 .B Rerror90 to the91 .B Tauth92 message.93 .PP94 If the server does require authentication, it returns95 .I aqid96 defining a file of type97 .B QTAUTH98 (see99 .IR intro (9P))100 that may be read and written (using101 .B read102 and103 .B write104 messages in the usual way) to execute an authentication protocol.105 That protocol's definition is not part of 9P itself.106 .PP107 Once the protocol is complete, the same108 .I afid109 is presented in the110 .B attach111 message for the user, granting entry.112 The same validated113 .I afid114 may be used for multiple115 .B attach116 messages with the same117 .I uname118 and119 .IR aname .120 .SH ENTRY POINTS121 .I Fsmount122 and123 .I fsauth124 (see125 .IR 9pclient (3))126 generate127 .B attach128 and129 .B auth130 transactions.131 .\" An132 .\" .B attach133 .\" transaction will be generated for kernel devices134 .\" (see135 .\" .IR intro (3))136 .\" when a system call evaluates a file name137 .\" beginning with138 .\" .LR # .139 .\" .IR Pipe (2)140 .\" generates an attach on the kernel device141 .\" .IR pipe (3).142 .\" The143 .\" .I mount144 .\" system call145 .\" (see146 .\" .IR bind (2))147 .\" generates an148 .\" .B attach149 .\" message to the remote file server.150 .\" When the kernel boots, an151 .\" .I attach152 .\" is made to the root device,153 .\" .IR root (3),154 .\" and then an155 .\" .B attach156 .\" is made to the requested file server machine.157 .\" .PP158 .\" An159 .\" .B auth160 .\" transaction is generated by the161 .\" .IR fauth (2)162 .\" system call or by the first163 .\" .B mount164 .\" system call on an uninitialized connection.165 .SH SEE ALSO166 .IR 9pclient (3),167 .IR version (9P),168 Plan 9's \fIauthsrv\fR(6)