VENTI-CONN(2)                                       VENTI-CONN(2)

     NAME
          VtConn, vtconn, vtdial, vtfreeconn, vtsend, vtrecv,
          vtversion, vtdebug, vthangup - Venti network connections

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <venti.h>

          typedef struct VtConn {
              int  debug;
              char *version;
              char *uid;
              char *sid;
              char addr[256];
              ...
          } VtConn;

          VtConn*    vtconn(int infd, int outfd)

          VtConn*    vtdial(char *addr)

          int        vtversion(VtConn *z)

          int        vtsend(VtConn *z, Packet *p)

          Packet*    vtrecv(VtConn *z)

          void       vtrecvproc(void *z)

          void       vtsendproc(void *z)

          void       vtdebug(VtConn *z, char *fmt, ...)

          void       vthangup(VtConn *z)

          void       vtfreeconn(VtConn *z)

          extern int chattyventi;/* default 0 */

     DESCRIPTION
          A 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:
          debug, a flag enabling debugging prints; version, the proto-
          col version in use; uid, the (unverified) name of the
          client; sid, the (unverified) name of the server; and addr,
          the network address of the remote side.

          Vtconn initializes a new connection structure using file

     VENTI-CONN(2)                                       VENTI-CONN(2)

          descriptors infd and outfd (which may be the same) for read-
          ing and writing.  Vtdial dials the given network address
          (see dial(2)) and returns a corresponding connection.  It
          returns nil if the connection cannot be established.

          Vtversion exchanges version information with the remote side
          as described in venti(6). The negotiated version is stored
          in z->version.

          Vtsend writes a packet (see venti-packet(2)) on the connec-
          tion z. The packet p should be a formatted Venti message as
          might be returned by vtfcallpack; vtsend will add the two-
          byte length field (see venti(6)) at the begnning.  Vtsend
          frees p, even on error.

          Vtrecv reads a packet from the connection z. Analogous to
          vtsend, the data read from the connection must start with a
          two-byte length, but the returned packet will omit them.

          By default, vtsend and vtrecv block until the packet can be
          written or read from the network.  In a threaded program
          (see thread(2)), this may not be desirable.  If the caller
          arranges for vtsendproc and vtrecvproc to run in their own
          procs (typically by calling proccreate), then vtsend and
          vtrecv will yield the proc in which they are run to other
          threads when waiting on the network.  The void* argument to
          vtsendproc and vtrecvproc must be the connection structure
          z.

          Vtdebug prints the formatted message to standard error when
          z->debug is set.  Otherwise it is a no-op.

          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 vtrecv or vtsend
          will return errors.  Additional calls to vthangup will have
          no effect.

          Vtfreeconn frees the connection structure, hanging it up
          first if necessary.

          If the global variable chattyventi is set, the library
          prints all Venti RPCs to standard error as they are sent or
          received.

     SOURCE
          /sys/src/libventi

     SEE ALSO
          venti(1), venti(2), venti-client(2), venti-packet(2),
          venti-server(2), venti(6)

     VENTI-CONN(2)                                       VENTI-CONN(2)

     DIAGNOSTICS
          Routines that return pointers return nil on error.  Routines
          returning integers return 0 on success, -1 on error.  All
          routines set errstr on error.