117 lines
2.8 KiB
Groff
117 lines
2.8 KiB
Groff
|
.\" 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)
|