sys/man/5/attach

   1 .TH ATTACH 5
   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 (5))
 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 An
 122 .B attach
 123 transaction will be generated for kernel devices
 124 (see
 125 .IR intro (3))
 126 when a system call evaluates a file name
 127 beginning with
 128 .LR # .
 129 .IR Pipe (2)
 130 generates an attach on the kernel device
 131 .IR pipe (3).
 132 The
 133 .I mount
 134 system call
 135 (see
 136 .IR bind (2))
 137 generates an
 138 .B attach
 139 message to the remote file server.
 140 When the kernel boots, an
 141 .I attach
 142 is made to the root device,
 143 .IR root (3),
 144 and then an
 145 .B attach
 146 is made to the requested file server machine.
 147 .PP
 148 An
 149 .B auth
 150 transaction is generated by the
 151 .IR fauth (2)
 152 system call or by the first
 153 .B mount
 154 system call on an uninitialized connection.
 155 .SH SEE ALSO
 156 .IR auth (2),
 157 .IR fauth (2),
 158 .IR version (5),
 159 .IR authsrv (6)