plan9fox/sys/man/2/venti-client

.TH VENTI-CLIENT 2
.SH NAME
vtconnect, vthello, vtread, vtwrite, vtreadpacket, vtwritepacket, vtsync, vtping, vtrpc, ventidoublechecksha1 \- Venti client
.SH SYNOPSIS
.ft L
#include <u.h>
.br
#include <libc.h>
.br
#include <venti.h>
.ta +\w'\fLPacket* 'u +\w'\fLxxxxxxxx'u
.PP
.B
Packet*	vtrpc(VtConn *z, Packet *p)
.PP
.B
int	vthello(VtConn *z)
.PP
.B
int	vtconnect(VtConn *z)
.PP
.B
int	vtread(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, uchar *buf, int n)
.PP
.B
int	vtwrite(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, uchar *buf, int n)
.PP
.B
Packet*	vtreadpacket(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, int n)
.PP
.B
int	vtwritepacket(VtConn *z, uchar score[VtScoreSize],
.br
.B
		uint type, Packet *p)
.PP
.B
int	vtsync(VtConn *z)
.PP
.B
int	vtping(VtConn *z)
.PP
.B
extern int ventidoublechecksha1;  /* default 1 */
.SH DESCRIPTION
These routines execute the client side of the 
.IR venti (6)
protocol.
.PP
.I Vtrpc
executes a single Venti RPC transaction, sending the request 
packet
.IR p
and then waiting for and returning the response packet.
.I Vtrpc
will set the tag in the packet.
.I Vtrpc
frees
.IR p ,
even on error.
.I Vtrpc
is typically called only indirectly, via the functions below.
.PP
.I Vthello
executes a
.B hello
transaction, setting
.IB z ->sid
to the name used by the server.
.I Vthello
is typically called only indirectly, via
.IR vtconnect .
.PP
.I Vtconnect
calls
.I vtversion
(see
.IR venti-conn (2))
and
.IR vthello ,
in that order, returning success only
if both succeed.
This sequence (calling 
.I vtversion
and then
.IR vthello )
must be done before the functions below can be called.
.PP
.I Vtread
reads the block with the given
.I score
and
.I type
from the server,
stores the returned data
in memory at
.IR buf ,
and returns the number of bytes read.
If the server's block has size larger than
.IR n ,
.I vtread 
does not modify
.I buf
and
returns an error.
.PP
.I Vtwrite
writes the
.I n
bytes in 
.I buf
as a block of the given
.IR type ,
setting 
.IR score .
.PP
.I Vtreadpacket
and
.I vtwritepacket
are like
.I vtread
and
.I vtwrite
but return or accept the block contents in the
form of a
.BR Packet .
They avoid making a copy of the data.
.PP
.I Vtsync
causes the server to flush all pending write requests
to disk before returning.
.PP
.I Vtping
executes a ping transaction with the server.
.PP
By default,
.I vtread
and
.I vtreadpacket
check that the SHA1 hash of the returned data 
matches the requested
.IR score ,
and
.I vtwrite
and
.I vtwritepacket
check that the returned
.I score
matches the SHA1 hash of the written data.
Setting
.I ventidoublechecksha1
to zero disables these extra checks,
mainly for benchmarking purposes.
Doing so in production code is not recommended.
.PP
These functions can be called from multiple threads
or procs simultaneously to issue requests 
in parallel.
Programs that issue requests from multiple threads
in the same proc should start separate procs running
.I vtsendproc
and
.I vtrecvproc
as described in
.IR venti-conn (2).
.SH SOURCE
.B /sys/src/libventi
.SH SEE ALSO
.IR venti (2),
.IR venti-conn (2),
.IR venti-packet (2),
.IR venti (6)
.SH DIAGNOSTICS
.I Vtrpc
and
.I vtpacket
return nil on error.
The other routines return \-1 on error.
.PP
.I Vtwrite
returns 0 on success: there are no partial writes.