From 590d98d7f73f351091e5c0ad9ef5835a26aad4d7 Mon Sep 17 00:00:00 2001 From: emma Date: Mon, 17 Jun 2024 22:28:41 -0600 Subject: [PATCH] peek.1: updates to be more consistent with current documentation --- docs/peek.1 | 124 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 72 insertions(+), 52 deletions(-) diff --git a/docs/peek.1 b/docs/peek.1 index 1c482a2..c9cb6ed 100644 --- a/docs/peek.1 +++ b/docs/peek.1 @@ -1,90 +1,110 @@ .\" Copyright (c) 2023-2024 DTB +.\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . - -.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 . - +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 . - +.\" .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)