NAME
ask_password - prompt user for a password and read it from stdin
SYNOPSIS
#include <limb/term.h>
ssize_t ask_password(char *dst, size_t dlen, const char *prompt)
DESCRIPTION
The ask_password() function will read data from stdin up to a newline (\n)
and store it into the memory area pointed by dst, up to dlen bytes.
First, it will ensure that the current process is in the foreground process
group of its controlling terminal if said terminal is referred to by stdin,
then make sure input character echoing is disabled for stdin for the duration
on the password input, and finally drop any data that might remain in
buffer_0.
If prompt is not NULL, it will be written to stderr before attempting to
read from stdin, unless it begins with > in which case it is written (past
this leading character) into stdout instead.
If prompt begins with a backslash (\) then it is skipped, to notably allow
to use a prompt beginning with a > whilst remaining in stderr.
All data read will be placed into dst (up to dlen bytes), reading stops as
soon as a newline is read. It will not write said newline in dst but instead
NUL-terminate the string.
Though not checked, it is assumed that no other NUL byte will be present.
Once done, character echoing is restored for stdin, and a newline printed on
stderr (or stdout) if prompt is not NULL.
The prompt value will be printed using the err(3) family of functions,
with an output level of OLVL_NORMAL, and as such written not only to
obuffer_2 (or obuffer_1) but duplicated on any an all attached buffers as
well. Refer to output.h(0) for more.
RETURN VALUE
On success the ask_password() function returns the length of the password read
and placed into dst. Note that said password is NUL-terminated when written to
dst, meaning that the password (and returned value) can only be up to
dlen - 1.
Otherwise it returns -1 and sets errno to indicate the error.
ERRORS
The ask_password() function may fail and set errno for any of the errors
described for term_ensurefg(3), term_echo(3) and buffer_getuptoc(3), with
the following exceptions :
EINVAL
The argument for buffer_getuptoc(3) cannot be invalid.
ENOTTY
If term_ensurefg(3) or term_echo(3) fails with ENOTTY ask_password()
simply ignores it and attempts to proceed as normal.
EPIPE
If buffer_getuptoc(3) fails with EPIPE it means end of file was reached, in which case anything that was read is used/returned as password.
These exceptions allow redirection of stdin which might only contain the password itself.