1
0

venti-conn 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211
  1. .TH VENTI-CONN 2
  2. .SH NAME
  3. VtConn, vtconn, vtdial, vtfreeconn, vtsend, vtrecv, vtversion,
  4. vtdebug, vthangup \- Venti network connections
  5. .SH SYNOPSIS
  6. .PP
  7. .ft L
  8. #include <u.h>
  9. .br
  10. #include <libc.h>
  11. .br
  12. #include <venti.h>
  13. .PP
  14. .ft L
  15. .nf
  16. .ta +\w'\fL 'u
  17. typedef struct VtConn {
  18. int debug;
  19. char *version;
  20. char *uid;
  21. char *sid;
  22. char addr[256];
  23. ...
  24. } VtConn;
  25. .PP
  26. .ta \w'\fLextern int 'u
  27. .B
  28. VtConn* vtconn(int infd, int outfd)
  29. .PP
  30. .B
  31. VtConn* vtdial(char *addr)
  32. .PP
  33. .B
  34. int vtversion(VtConn *z)
  35. .PP
  36. .B
  37. int vtsend(VtConn *z, Packet *p)
  38. .PP
  39. .B
  40. Packet* vtrecv(VtConn *z)
  41. .PP
  42. .B
  43. void vtrecvproc(void *z)
  44. .PP
  45. .B
  46. void vtsendproc(void *z)
  47. .PP
  48. .B
  49. void vtdebug(VtConn *z, char *fmt, ...)
  50. .PP
  51. .B
  52. void vthangup(VtConn *z)
  53. .PP
  54. .B
  55. void vtfreeconn(VtConn *z)
  56. .PP
  57. .B
  58. extern int chattyventi; /* default 0 */
  59. .SH DESCRIPTION
  60. A
  61. .B VtConn
  62. structure represents a connection to a Venti server
  63. (when used by a client) or to a client (when used by a server).
  64. It contains the following user-visible fields:
  65. .BR debug ,
  66. a flag enabling debugging prints;
  67. .BR version ,
  68. the protocol version in use;
  69. .BR uid ,
  70. the (unverified) name of the client;
  71. .BR sid ,
  72. the (unverified) name of the server;
  73. and
  74. .BR addr ,
  75. the network address of the remote side.
  76. .PP
  77. .I Vtconn
  78. initializes a new connection structure using file descriptors
  79. .I infd
  80. and
  81. .I outfd
  82. (which may be the same)
  83. for reading and writing.
  84. .I Vtdial
  85. dials the given network address
  86. (see
  87. .IR dial (2))
  88. and returns a corresponding connection.
  89. If
  90. .I addr
  91. is
  92. .BR nil ,
  93. the environment variable
  94. .B venti
  95. will be used if set; if not, the address
  96. .B tcp!$venti!venti
  97. will be used.
  98. It returns
  99. .B nil
  100. if the connection cannot be established.
  101. .PP
  102. .I Vtversion
  103. exchanges version information with the remote side
  104. as described in
  105. .IR venti (6).
  106. The negotiated version is stored in
  107. .IB z ->version \fR.
  108. .PP
  109. .I Vtsend
  110. writes a packet
  111. (see
  112. .IR venti-packet (2))
  113. on the connection
  114. .IR z .
  115. The packet
  116. .I p
  117. should be a formatted Venti message as might
  118. be returned by
  119. .IR vtfcallpack ;
  120. .I vtsend
  121. will add the two-byte length field
  122. (see
  123. .IR venti (6))
  124. at the begnning.
  125. .I Vtsend
  126. frees
  127. .IR p ,
  128. even on error.
  129. .PP
  130. .I Vtrecv
  131. reads a packet from the connection
  132. .IR z .
  133. Analogous to
  134. .IR vtsend ,
  135. the data read from the connection must start with
  136. a two-byte length, but the returned packet will omit them.
  137. .PP
  138. By default,
  139. .I vtsend
  140. and
  141. .I vtrecv
  142. block until the packet can be written or read from the network.
  143. In a threaded program
  144. (see
  145. .IR thread (2)),
  146. this may not be desirable.
  147. If the caller arranges for
  148. .IR vtsendproc
  149. and
  150. .IR vtrecvproc
  151. to run in their own procs
  152. (typically by calling
  153. .IR proccreate ),
  154. then
  155. .I vtsend
  156. and
  157. .I vtrecv
  158. will yield the proc in which they are run
  159. to other threads when waiting on the network.
  160. The
  161. .B void*
  162. argument to
  163. .I vtsendproc
  164. and
  165. .I vtrecvproc
  166. must be the connection structure
  167. .IR z .
  168. .PP
  169. .I Vtdebug
  170. prints the formatted message to standard error
  171. when
  172. .IB z ->debug
  173. is set. Otherwise it is a no-op.
  174. .PP
  175. .I Vthangup
  176. hangs up a connection.
  177. It closes the associated file descriptors
  178. and shuts down send and receive procs if they have been
  179. started.
  180. Future calls to
  181. .IR vtrecv
  182. or
  183. .IR vtsend
  184. will return errors.
  185. Additional calls to
  186. .I vthangup
  187. will have no effect.
  188. .PP
  189. .I Vtfreeconn
  190. frees the connection structure, hanging it up first
  191. if necessary.
  192. .PP
  193. If the global variable
  194. .I chattyventi
  195. is set, the library prints all Venti RPCs to standard error
  196. as they are sent or received.
  197. .SH SOURCE
  198. .B /sys/src/libventi
  199. .SH SEE ALSO
  200. .IR venti (1),
  201. .IR venti (2),
  202. .IR venti-client (2),
  203. .IR venti-packet (2),
  204. .IR venti-server (2),
  205. .IR venti (6)
  206. .SH DIAGNOSTICS
  207. Routines that return pointers return nil on error.
  208. Routines returning integers return 0 on success, \-1 on error.
  209. All routines set
  210. .I errstr
  211. on error.