Welcome to little lamb

Code » limb » release » tree

[release] / src / doc / term.h / ask_password.3.md 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
% limb manual
% ask_password(3)
% limb 0.1.0
% 2023-07-24

# NAME

ask\_password - prompt user for a password and read it from *stdin*

# SYNOPSIS

    #include <limb/term.h>

```pre hl
ssize_t ask_password(char *<em>dst</em>, size_t <em>dlen</em>, const char *<em>prompt</em>)
```

# 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.

! INFO:
! 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.