.\" Copyright (c) 2023-2024 DTB <trinity@trinity.moe>
.\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license,
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.

.TH PEEK 1

.SH NAME

peek \(en read from the standard input, furtively

.SH SYNOPSIS

peek
.RB ( -i )

.SH DESCRIPTION

Peek reads input from the standard input with terminal echo disabled.

.SH OPTIONS

.B -i
.RS
Allows input to come from sources other than terminals (i.e. a pipe).
.RE

.SH DIAGNOSTICS

Peek prints an error message and exits with the appropriate status from
sysexits.h(3) if it encounters an unrecoverable error.

Peek tries to handle the signal SIGINT (^C) to ensure the user's terminal is
still usable after premature termination; if the signal can't be handled, it
prints an error message and continues. If peek is interrupted, it exits
unsuccessfully, without an error message.

.SH RATIONALE

This tool was originally written to accept passwords in shell scripts, as an
extremely simple alternative to the GNU Privacy Guard project's pinentry(1).
Accepting input without showing what is being typed is useful when keying in
secrets in public settings or places with installed surveillance cameras.

.SH BUGS

This does nothing to prevent others seeing the keyboard being used to input
secrets or mask the sound of typing. Audio or video recordings of typing can be
used to determine what was input without needing to see the characters appear
on the screen.

Accepting secrets in shell scripts is probably not adviseable.

On systems that support it, the ioctl(2) command TIOCSTI can be used to insert
characters into the standard input going to peek. This doesn't allow snooping
but can be used for general mischief.

.SH EXAMPLES

This is an sh(1p) command line that hashes a given password. It uses head(1p)
to only accept one line of input, xargs(1p) and printf(1p) to strip the
trailing newline, htpasswd(1) from Apache's utilities to hash the input with
the bcrypt algorithm, and cut(1p) to print only the resulting hash:

.RS
.R $ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2
.RE

This is an sh(1p) command line that lets a user blindly write into a text file,
only able to see written lines. Some writers have the habit of prematurely
revising their work and use tools like this to prevent it. It uses mm(1) to
pipe the output of peek to both the standard error and the regular file
writing.txt.

.RS
.R $ echo Input ^D to quit. && peek | mm -eo - >writing.txt
.RE

.SH AUTHOR

Written by DTB <trinity@trinity.moe>.

.SH COPYRIGHT

Copyright (c) 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>.

.SH SEE ALSO

ioctl(2), ioctl_tty(2), read(1), sh(1)