attach 2.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159
  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)