.TH LIBRECRYPT_SETTINGS_PREFIX 3 LIBRECRYPT
.SH NAME
librecrypt_settings_prefix - Get length of settings prefix in a password hash string

.SH SYNOPSIS
.nf
#include <librecrypt.h>

size_t \fBlibrecrypt_settings_prefix\fP(const char *\fIhash\fP, size_t *\fIhashsize_out\fP);
.fi
.PP
Link with
.IR -lrecrypt .

.SH DESCRIPTION
The
.BR librecrypt_settings_prefix ()
function returns the number of bytes, from the front of
.IR hash ,
that make up the algorithm configuration.
.PP
Unless
.I hashsize_out
is
.IR NULL ,
the value 0
is stored in
.I *hashsize_out
if the output hash size is fixed for the last algorithm in
.I hash
or if the output hash size is not specified (either because
.IR &hash[r] ,
where
.I r
is the return value, is the null byte, and so the default
hash size shall be used or because the information is
malformatted), otherwise a positive value is stored in
.IR *hashsize_out ,
specifying the number of bytes in the binary output hash,
as determined by the text in
.I hash
beyond the settings prefix.
See the
.B EXTENDED DESCRIPTION
section for more information.
.PP
.I hash
must not be
.IR NULL .

.SH RETURN VALUES
The
.BR librecrypt_settings_prefix ()
function returns the number of bytes that make up the
settings prefix. The return value may be 0, which shall
be treated as any other valid return value.
.PP
.IR &hash[r] ,
where
.I r
is the return value, points to the hash result proper.

.SH ERRORS
The
.BR librecrypt_settings_prefix ()
function cannot fail.

.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.PP
.TS
allbox;
lb lb lb
l l l.
Interface	Attribute	Value
T{
.BR librecrypt_settings_prefix ()
T}	Thread safety	MT-Safe
T{
.BR librecrypt_settings_prefix ()
T}	Async-signal safety	AS-Safe
.TE
.sp

.SH EXTENDED DESCRIPTION
Some algorithms have flexible hash size which
is encoded either with an actual hash (its
length after decoding to binary is checked)
or using asterisk-notation in place of the
result (that is, as an asterisk
.RI (\(aq * \(aq)
followed by an unsigned, decimal integer,
which may have leading zeroes). This part
is always excluded (from the last algorithm
in the algorithm chain in
.IR hash )
in the return value of the
.BR librecrypt_settings_prefix ()
function.

.SH HISTORY
The
.BR librecrypt_settings_prefix ()
function was introduced in version 1.0 of
.BR librecrypt .

.SH SEE ALSO
.BR librecrypt (7),
.BR librecrypt_chain_length (3)