201 lines
3.5 KiB
Plaintext
201 lines
3.5 KiB
Plaintext
.TH VENTI-CONN 2
|
|
.SH NAME
|
|
VtConn, vtconn, vtdial, vtfreeconn, vtsend, vtrecv, vtversion,
|
|
vtdebug, vthangup \- Venti network connections
|
|
.SH SYNOPSIS
|
|
.PP
|
|
.ft L
|
|
#include <u.h>
|
|
.br
|
|
#include <libc.h>
|
|
.br
|
|
#include <venti.h>
|
|
.PP
|
|
.ft L
|
|
.nf
|
|
.ta +\w'\fL 'u
|
|
typedef struct VtConn {
|
|
int debug;
|
|
char *version;
|
|
char *uid;
|
|
char *sid;
|
|
char addr[256];
|
|
...
|
|
} VtConn;
|
|
.PP
|
|
.ta \w'\fLextern int 'u
|
|
.B
|
|
VtConn* vtconn(int infd, int outfd)
|
|
.PP
|
|
.B
|
|
VtConn* vtdial(char *addr)
|
|
.PP
|
|
.B
|
|
int vtversion(VtConn *z)
|
|
.PP
|
|
.B
|
|
int vtsend(VtConn *z, Packet *p)
|
|
.PP
|
|
.B
|
|
Packet* vtrecv(VtConn *z)
|
|
.PP
|
|
.B
|
|
void vtrecvproc(void *z)
|
|
.PP
|
|
.B
|
|
void vtsendproc(void *z)
|
|
.PP
|
|
.B
|
|
void vtdebug(VtConn *z, char *fmt, ...)
|
|
.PP
|
|
.B
|
|
void vthangup(VtConn *z)
|
|
.PP
|
|
.B
|
|
void vtfreeconn(VtConn *z)
|
|
.PP
|
|
.B
|
|
extern int chattyventi; /* default 0 */
|
|
.SH DESCRIPTION
|
|
A
|
|
.B VtConn
|
|
structure represents a connection to a Venti server
|
|
(when used by a client) or to a client (when used by a server).
|
|
It contains the following user-visible fields:
|
|
.BR debug ,
|
|
a flag enabling debugging prints;
|
|
.BR version ,
|
|
the protocol version in use;
|
|
.BR uid ,
|
|
the (unverified) name of the client;
|
|
.BR sid ,
|
|
the (unverified) name of the server;
|
|
and
|
|
.BR addr ,
|
|
the network address of the remote side.
|
|
.PP
|
|
.I Vtconn
|
|
initializes a new connection structure using file descriptors
|
|
.I infd
|
|
and
|
|
.I outfd
|
|
(which may be the same)
|
|
for reading and writing.
|
|
.I Vtdial
|
|
dials the given network address
|
|
(see
|
|
.IR dial (2))
|
|
and returns a corresponding connection.
|
|
It returns nil if the connection cannot be established.
|
|
.PP
|
|
.I Vtversion
|
|
exchanges version information with the remote side
|
|
as described in
|
|
.IR venti (6).
|
|
The negotiated version is stored in
|
|
.IB z ->version \fR.
|
|
.PP
|
|
.I Vtsend
|
|
writes a packet
|
|
(see
|
|
.IR venti-packet (2))
|
|
on the connection
|
|
.IR z .
|
|
The packet
|
|
.IR p
|
|
should be a formatted Venti message as might
|
|
be returned by
|
|
.IR vtfcallpack ;
|
|
.I vtsend
|
|
will add the two-byte length field
|
|
(see
|
|
.IR venti (6))
|
|
at the begnning.
|
|
.I Vtsend
|
|
frees
|
|
.IR p ,
|
|
even on error.
|
|
.PP
|
|
.I Vtrecv
|
|
reads a packet from the connection
|
|
.IR z .
|
|
Analogous to
|
|
.IR vtsend ,
|
|
the data read from the connection must start with
|
|
a two-byte length, but the returned packet will omit them.
|
|
.PP
|
|
By default,
|
|
.I vtsend
|
|
and
|
|
.I vtrecv
|
|
block until the packet can be written or read from the network.
|
|
In a threaded program
|
|
(see
|
|
.IR thread (2)),
|
|
this may not be desirable.
|
|
If the caller arranges for
|
|
.IR vtsendproc
|
|
and
|
|
.IR vtrecvproc
|
|
to run in their own procs
|
|
(typically by calling
|
|
.IR proccreate ),
|
|
then
|
|
.I vtsend
|
|
and
|
|
.I vtrecv
|
|
will yield the proc in which they are run
|
|
to other threads when waiting on the network.
|
|
The
|
|
.B void*
|
|
argument to
|
|
.I vtsendproc
|
|
and
|
|
.I vtrecvproc
|
|
must be the connection structure
|
|
.IR z .
|
|
.PP
|
|
.I Vtdebug
|
|
prints the formatted message to standard error
|
|
when
|
|
.IB z ->debug
|
|
is set. Otherwise it is a no-op.
|
|
.PP
|
|
.I Vthangup
|
|
hangs up a connection.
|
|
It closes the associated file descriptors
|
|
and shuts down send and receive procs if they have been
|
|
started.
|
|
Future calls to
|
|
.IR vtrecv
|
|
or
|
|
.IR vtsend
|
|
will return errors.
|
|
Additional calls to
|
|
.I vthangup
|
|
will have no effect.
|
|
.PP
|
|
.I Vtfreeconn
|
|
frees the connection structure, hanging it up first
|
|
if necessary.
|
|
.PP
|
|
If the global variable
|
|
.I chattyventi
|
|
is set, the library prints all Venti RPCs to standard error
|
|
as they are sent or received.
|
|
.SH SOURCE
|
|
.B /sys/src/libventi
|
|
.SH SEE ALSO
|
|
.IR venti (1),
|
|
.IR venti (2),
|
|
.IR venti-client (2),
|
|
.IR venti-packet (2),
|
|
.IR venti-server (2),
|
|
.IR venti (6)
|
|
.SH DIAGNOSTICS
|
|
Routines that return pointers return nil on error.
|
|
Routines returning integers return 0 on success, \-1 on error.
|
|
All routines set
|
|
.I errstr
|
|
on error.
|