.TH MTREE_DIFF_SUBTREE 3 2023-06-20 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
mtree_diff_subtree \- compare two subtrees and return bitmap
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/mtree.h>
.PP
.BI "unsigned char *mtree_diff_subtree(mtree_t " *t1 ", mtree_t " *t2 ", size_t " root ", unsigned " bits ");"
.BI "unsigned char *mtree_diff_map(mtree_t " *t1 ", mtree_t " *t2 ");"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
The
.BR mtree_diff_subtree
function performs a bredth-first comparison of the merkle trees
.IR t1
and
.IR t2
and returns a pointer to a bitmap, setting
.IR bits
bits for any chunks that differ.
.IR bits
should be set to the number of packets required to to transport each chunk. When bits > 1, chunks will be fragmented into multiple packets, and the bitmap will represent the packets required.
.PP
Checking the popcount (Hamming Weight) of the returned bitmap gives the number of packets required to patch the differences.
.PP
The returned bitmap must be freed by the caller when no longer needed by passing to
.BR free (3).
.PP
.BR mtree_diff_map ()
is a convenience wrapper that is the same as calling
.BR mtree_diff_subtree ()
with
.IR root
set to zero (whole tree)
and
.IR bits
set to one. Thus, it returns a bitmap of the entire tree with a single bit per
chunk.
.PP
.SH RETURN VALUE
.BR mtree_verify ()
returns zero if the tree is valid, or NULL on error, with
.IR errno
set to indicate the error.
.SH ERRORS
.TP
.BR ENOMEM
Not enough space/cannot allocate memory (POSIX.1-2001).
.PP
.SH SEE ALSO
.BR mtree_init (3),
.BR mtree_free (3),
.BR mtree_build (3),
.BR free (3)