10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
191 lines
3.3 KiB
Groff
191 lines
3.3 KiB
Groff
.TH VENTI-CLIENT 3
|
|
.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
|
|
.MR venti 7
|
|
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
|
|
.MR venti-conn 3 )
|
|
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
|
|
.MR venti-conn 3 .
|
|
.SH SOURCE
|
|
.B \*9/src/libventi
|
|
.SH SEE ALSO
|
|
.MR venti 3 ,
|
|
.MR venti-conn 3 ,
|
|
.MR venti-packet 3 ,
|
|
.MR venti 7
|
|
.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.
|