ref: a5cb451b299b03f44154fac5780b6a57ca130ce0
dir: /man/5/attach/
.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 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 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 sys-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)