GopherProxy

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