bonsai/harakit
5
4
Fork 3
Code Issues 38 Pull Requests 7 Projects 1 Releases 21 Activity

peek.1: updates to be more consistent with current documentation

Browse Source
This commit is contained in:
Emma Tebibyte 2024-06-17 22:28:41 -06:00
parent 6d3f084d9c
commit 3db83fd79c
Signed by: emma
GPG Key ID: 06FA419A1698C270
1 changed files with 72 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
docs/peek.1
View File

@ -1,90 +1,110 @@
.\" Copyright (c) 2023-2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
.\"
.\" 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
.\"
.TH PEEK 1 2024-06-09 "Bonsai Core Utilites 0.13.9"
.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.
Read 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
.IP \fB-i\fP
Allows input to come from sources other than terminals (i.e., a pipe).
.\"
.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.
In the event of an error, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
In order to ensure the user\(cqs terminal is still usable after premature
termination, the program attempts to handle the SIGINT signal; if it cannot,
an error message is printed and execution continues. If the program 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).
This tool was originally written to accept passwords in shell scripts as an
extremely simple alternative to the GNU Privacy Guard project\(cqs
.BR pinentry (1)
utility.
Accepting input without showing what is being typed is useful when keying in
secrets in public settings or places with installed surveillance cameras.
secrets in public settings or in places where surveillance cameras are
installed.
.\"
.SH CAVEATS
.SH BUGS
This program does nothing to prevent others from seeing the key presses input to
a keyboard. It also does not protect against the sound of typing being analyzed
to determine what was inputted without needing to see screen or keyboard.
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.
Accepting secrets in shell scripts is probably not advisable.
On systems that support it, the
.BR ioctl (2)
command TIOCSTI can be used to insert characters into the standard input. 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:
This is an
.BR sh (1p)
command line that hashes a given password. It uses
.BR head (1p)
to only accept one line of input,
.BR xargs (1p)
and
.BR printf (1p)
to strip the trailing newline,
.BR htpasswd (1)
from Apache\(cqs utilities to hash the input with the bcrypt algorithm, and
.BR cut (1p)
to print only the resulting hash:
.RS
.R $ peek | head -n 1 | xargs printf '%s' | htpasswd -nBi _ | cut -d : -f 2
$ 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.
This is an
.BR sh (1p)
command line that allows a user to write blindly into a text file but displaying
only written lines. Some writers have the habit of prematurely revising their
work and use tools with functionality similar to this to prevent it.
It uses
.BR mm (1)
to pipe the output of the program to both the standard error and the regular
file writing.txt:
.RS
.R $ echo Input ^D to quit. && peek | mm -eo - >writing.txt
$ echo Input ^D to quit. && peek | mm -eo - >writing.txt
.RE
.\"
.SH AUTHOR
Written by DTB <trinity@trinity.moe>.
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT
Copyright (c) 2023-2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
Copyright \(co 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)
.BR ioctl (2),
.BR ioctl_tty (2),
.BR read (1),
.BR sh (1)