.TH LIBKECCAK_UPDATE 3 LIBKECCAK-%VERSION%
.SH NAME
libkeccak_update - Partially hash a message with erasure
.SH SYNOPSIS
.LP
.nf
#include <libkeccak.h>
.P
int libkeccak_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, size_t \fImsglen\fP);
.fi
.P
Link with \fI-lkeccak\fP.
.SH DESCRIPTION
The
.BR libkeccak_update ()
function continues (or starts) hashing a message.
The current state of the hashing is stored in \fI*state\fP,
and will be updated. The message specified by the \fImsg\fP
parameter with the byte-size specified by the \fImsglen\fP
parameter, will be hashed.
.PP
The
.BR libkeccak_update ()
function may reallocate the state's message chunk buffer.
When doing so, it attempts to do so as securely as possible,
rather than as fast as possible.
.SH RETURN VALUES
The
.BR libkeccak_update ()
function returns 0 upon successful completion. On error,
-1 is returned and \fIerrno\fP is set to describe the error.
.SH ERRORS
The
.BR libkeccak_update ()
function may fail for any reason specified by the function
.BR malloc (3).
.SH NOTES
Neither parameter by be \fINULL\fP or 0.
.SH EXAMPLE
This example calculates the Keccak[b = 1024, c = 576, n = 256]
hash of the input from stdin, and prints the hash, in hexadecimal
form, to stdout.
.LP
.nf
libkeccak_state_t state;
libkeccak_spec_t spec;
char binhash[256 / 8];
char hexhash[256 / 8 * 2 + 1];
char chunk[4 << 10];
ssize_t len;

spec.bitrate = 1024;
spec.capacity = 576;
spec.output = 256;
if (libkeccak_state_initialise(&state, &spec) < 0)
    goto fail;

for (;;) {
    len = read(STDIN_FILENO, chunk, sizeof(chunk));

    if ((len < 0) && (errno == EINTR))
        continue;
    if (len < 0)
        goto fail;
    if (len == 0)
        break;

    if (libkeccak_update(&state, chunk, (size_t)len) < 0)
        goto fail;
}
if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0)
    goto fail;

libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\\n", hexhash);
libkeccak_state_destroy(&state);
.fi
.SH SEE ALSO
.BR libkeccak_state_initialise (3),
.BR libkeccak_fast_update (3),
.BR libkeccak_fast_digest (3),
.BR libkeccak_digest (3)
.SH AUTHORS
Principal author, Mattias Andrée.  See the LICENSE file for the full
list of authors.
.SH BUGS
Please report bugs to https://github.com/maandree/libkeccak/issues or to
maandree@kth.se