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.
276 lines
4.6 KiB
Groff
276 lines
4.6 KiB
Groff
.TH VENTI-FCALL 3
|
|
.SH NAME
|
|
VtEntry, VtFcall, VtRoot,
|
|
vtentrypack,
|
|
vtentryunpack,
|
|
vtfcallclear,
|
|
vtfcallfmt,
|
|
vtfcallpack,
|
|
vtfcallunpack,
|
|
vtfromdisktype,
|
|
vttodisktype,
|
|
vtgetstring,
|
|
vtputstring,
|
|
vtrootpack,
|
|
vtrootunpack,
|
|
vtparsescore,
|
|
vtscorefmt \- venti data formats
|
|
.SH SYNOPSIS
|
|
.PP
|
|
.ft L
|
|
#include <u.h>
|
|
.br
|
|
#include <libc.h>
|
|
.br
|
|
#include <venti.h>
|
|
.ta +\w'\fLxxxx'u
|
|
.PP
|
|
.ft L
|
|
.nf
|
|
enum
|
|
{
|
|
VtEntrySize = 40,
|
|
VtRootSize = 300,
|
|
VtScoreSize = 20,
|
|
};
|
|
.PP
|
|
.ft L
|
|
.nf
|
|
typedef struct VtEntry
|
|
{
|
|
ulong gen; /* generation number */
|
|
ushort psize; /* pointer block size */
|
|
ushort dsize; /* data block size */
|
|
uchar type;
|
|
uchar flags;
|
|
uvlong size;
|
|
uchar score[VtScoreSize];
|
|
} VtEntry;
|
|
.PP
|
|
.ft L
|
|
.nf
|
|
typedef struct VtRoot
|
|
{
|
|
char name[128];
|
|
char type[128];
|
|
uchar score[VtScoreSize]; /* to a Dir block */
|
|
ushort blocksize; /* maximum block size */
|
|
uchar prev[VtScoreSize]; /* previous root block */
|
|
} VtRoot;
|
|
.ta +\w'\fLPacket* 'u
|
|
.PP
|
|
.B
|
|
void vtentrypack(VtEntry *e, uchar *buf, int index)
|
|
.br
|
|
.B
|
|
int vtentryunpack(VtEntry *e, uchar *buf, int index)
|
|
.PP
|
|
.B
|
|
Packet* vtfcallpack(VtFcall *f)
|
|
.br
|
|
.B
|
|
int vtfcallunpack(VtFcall *f, Packet *p)
|
|
.PP
|
|
.B
|
|
void vtfcallclear(VtFcall *f)
|
|
.PP
|
|
.B
|
|
uint vttodisktype(uint type)
|
|
.br
|
|
.B
|
|
uint vtfromdisktype(uint type)
|
|
.PP
|
|
.B
|
|
int vtputstring(Packet *p, char *s)
|
|
.br
|
|
.B
|
|
int vtgetstring(Packet *p, char **s)
|
|
.PP
|
|
.B
|
|
void vtrootpack(VtRoot *r, uchar *buf)
|
|
.br
|
|
.B
|
|
int vtrootunpack(VtRoot *r, uchar *buf)
|
|
.PP
|
|
.B
|
|
int vtparsescore(char *s, char **prefix, uchar score[VtScoreSize])
|
|
.PP
|
|
.B
|
|
int vtfcallfmt(Fmt *fmt)
|
|
.B
|
|
int vtscorefmt(Fmt *fmt)
|
|
.SH DESCRIPTION
|
|
These routines convert between C representations of Venti
|
|
structures and serialized representations used on disk and
|
|
on the network.
|
|
.PP
|
|
.I Vtentrypack
|
|
converts a
|
|
.B VtEntry
|
|
structure describing a Venti file
|
|
(see
|
|
.MR venti 7 )
|
|
into a 40-byte
|
|
.RB ( VtEntrySize )
|
|
structure at
|
|
.IB buf + index *40 \fR.
|
|
Vtentryunpack
|
|
does the reverse conversion.
|
|
.PP
|
|
.I Vtfcallpack
|
|
converts a
|
|
.B VtFcall
|
|
structure describing a Venti protocol message
|
|
(see
|
|
.MR venti 7 )
|
|
into a packet.
|
|
.I Vtfcallunpack
|
|
does the reverse conversion.
|
|
.PP
|
|
The fields in a
|
|
.B VtFcall
|
|
are named after the protocol fields described in
|
|
.MR venti 7 ,
|
|
except that the
|
|
.B type
|
|
field is renamed
|
|
.BR blocktype .
|
|
The
|
|
.B msgtype
|
|
field holds the one-byte message type:
|
|
.BR VtThello ,
|
|
.BR VtRhello ,
|
|
and so on.
|
|
.PP
|
|
.I Vtfcallclear
|
|
frees the strings
|
|
.IB f ->error \fR,
|
|
.IB f ->version \fR,
|
|
.IB f ->uid \fR,
|
|
.IB f ->sid \fR,
|
|
the buffers
|
|
.IB f ->crypto
|
|
and
|
|
.IB f ->codec \fR,
|
|
and the packet
|
|
.IB f ->data \fR.
|
|
.PP
|
|
The block type enumeration defined in
|
|
.B <venti.h>
|
|
(presented in
|
|
.MR venti 7 )
|
|
differs from the one used on disk and in the network
|
|
protocol.
|
|
The disk and network representation uses different
|
|
constants and does not distinguish between
|
|
.BI VtDataType+ n
|
|
and
|
|
.BI VtDirType+ n
|
|
blocks.
|
|
.I Vttodisktype
|
|
converts a
|
|
.B <venti.h>
|
|
enumeration value to the disk value;
|
|
.I vtfromdisktype
|
|
converts a disk value to the enumeration value,
|
|
always using the
|
|
.B VtDirType
|
|
pointers.
|
|
The
|
|
.B VtFcall
|
|
field
|
|
.B blocktype
|
|
is an enumeration value
|
|
.RI ( vtfcallpack
|
|
and
|
|
.I vtfcallunpack
|
|
convert to and from the disk values used in packets
|
|
automatically),
|
|
so most programs will not need to call these functions.
|
|
.PP
|
|
.I Vtputstring
|
|
appends the Venti protocol representation of the string
|
|
.I s
|
|
to the packet
|
|
.IR p .
|
|
.I Vtgetstring
|
|
reads a string from the packet, returning a pointer to a copy
|
|
of the string in
|
|
.BI * s \fR.
|
|
The copy must be freed by the caller.
|
|
These functions are used by
|
|
.I vtfcallpack
|
|
and
|
|
.IR vtfcallunpack ;
|
|
most programs will not need to call them directly.
|
|
.PP
|
|
.I Vtrootpack
|
|
converts a
|
|
.B VtRoot
|
|
structure describing a Venti file tree
|
|
into the 300-byte
|
|
.RB ( VtRootSize )
|
|
buffer pointed to by
|
|
.IR buf .
|
|
.I Vtrootunpack does the reverse conversion.
|
|
.PP
|
|
.I Vtparsescore
|
|
parses the 40-digit hexadecimal string
|
|
.IR s ,
|
|
writing its value
|
|
into
|
|
.IR score .
|
|
If the hexadecimal string is prefixed with
|
|
a text label followed by a colon, a copy of that
|
|
label is returned in
|
|
.BI * prefix \fR.
|
|
If
|
|
.I prefix
|
|
is nil, the label is ignored.
|
|
.PP
|
|
.I Vtfcallfmt
|
|
and
|
|
.I vtscorefmt
|
|
are
|
|
.MR print 3
|
|
formatters to print
|
|
.B VtFcall
|
|
structures and scores.
|
|
.I Vtfcallfmt
|
|
assumes that
|
|
.I vtscorefmt
|
|
is installed as
|
|
.BR %V .
|
|
.SH SOURCE
|
|
.B \*9/src/libventi
|
|
.SH SEE ALSO
|
|
.MR venti 1 ,
|
|
.MR venti 3 ,
|
|
.MR venti 7
|
|
.SH DIAGNOSTICS
|
|
.IR Vtentrypack ,
|
|
.IR vtfcallpack ,
|
|
.IR vtrootpack ,
|
|
and
|
|
.I vtfcallclear
|
|
cannot fail.
|
|
.PP
|
|
.IR Vtentryunpack ,
|
|
.IR vtrootunpack ,
|
|
.IR vtputstring ,
|
|
.IR vtgetstring ,
|
|
and
|
|
.I vtparsescore
|
|
return 0 on success, \-1 on error.
|
|
.PP
|
|
.I Vtfcallpack
|
|
returns a packet on success, nil on error.
|
|
.PP
|
|
.I Vttodisktype
|
|
and
|
|
.I vtfromdisktype
|
|
return
|
|
.B VtCorruptType
|
|
(255)
|
|
when presented with invalid input.
|