.\" 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 standard input, furtively

.SH SYNOPSIS

peek
.RB ( -1enot )
.RB ( -p
.RB [ program
.RB [ arguments... ]])

.SH DESCRIPTION

Peek reads input from standard input with terminal echo disabled, which may be
useful to prevent secrets being spied upon by adversaries watching a user's
screen.

.SH OPTIONS

.B -1
.RS
Limits input to a single line (stopping when the newline character is read).
.RE

.B -e
.RS
Configures peek to output to standard error.
.RE

.B -n
.RS
Prints ("iNcludes") the terminating character in outputs. This is nonsensical
if not combined with the
.B -1
option.
.RE

.B -o
.RS
Configures peek to output to standard output.
.RE

.B -p
.RS
Configures peek to pipe output to an executed child program, e.g. a password
hashing utility. This is provided as a convenience and to avoid potential
insecurities resulting from programmer error in scripts.
.RE

.B -t
.RS
Makes peek exit if not run within a terminal.
.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 BUGS

Accepting secrets in shell scripts is not adviseable in any context.

If used in a safety-critical application it must be ensured that the
environment with which peek is used is not compromised.

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.

Peek will happily run without outputs, slurping input and doing nothing with
it.

.SH EXAMPLES

This is a command line for POSIX sh(1), using POSIX env(1) to discard the
environment except for PATH, and htpassword(1) from Apache's utilities to hash
the input with the bcrypt algorithm, printing the resulting hash:

.RS
.R $ env -i PATH="$PATH" peek -1tp htpasswd -nBi _ | cut -d : -f 2
.RE

This is a POSIX sh(1) 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:

.RS
.R $ echo Input ^D to quit. && peek -eot >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

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