Subversion Repositories planix.SVN

.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.