trinity/bonsix
1
0
Fork 0
forked from bonsai/harakit
Code Pull Requests Activity

Merge branch 'docs' (closes #81)

Browse Source
This commit is contained in:
Emma Tebibyte 2024-06-05 23:22:57 -06:00
commit 28823206bd
Signed by untrusted user: emma
GPG Key ID: 06FA419A1698C270
13 changed files with 633 additions and 485 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
docs/dj.1
View File

@ -1,14 +1,13 @@
.\" Copyright (c) 2024 DTB <trinity@trinity.moe> .\" Copyright (c) 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, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH dj 1 .TH DJ 1
.SH NAME .SH NAME
dj \(en disk jockey dj \(en disk jockey
.\"
.SH SYNOPSIS .SH SYNOPSIS
dj dj
@ -43,118 +42,155 @@ dj
.R [ .R [
.B output offset .B output offset
.R ]) .R ])
.\"
.SH DESCRIPTION
.SH USAGE Perform precise read and write operations on files. This utility is useful for
reading and writing binary data to and from disks, hence the name.
The This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
.B -i to a specified byte by index in the input and output of the program
option takes a path as an argument to open and use in place of standard input. respectively. This language is inherited from the
The .BR dd (1p)
.B -o utility and is used here to decrease ambiguity.
option does the same in place of standard output. Dj does not truncate output
files and instead writes over the bytes in the existing file. When seeking or skipping to a byte, writing or reading starts at the byte
.PP immediately subsequent to the specified byte.
The .\"
.SH OPTIONS
.IP \fB-i\fP
Takes a file path as an argument and opens it for use as an input.
.IP \fB-b\fP
Takes a numeric argument as the size in bytes of the input buffer, with the
default being 1024.
.IP \fB-s\fP
Takes a numeric argument as the number of bytes to skip into the input
before starting to read. If the standard input is used, bytes read to this point
are discarded.
.IP \fB-o\fP
Takes a file path as an argument and opens it for use as an output.
.IP \fB-B\fP
Does the same as
.B -b .B -b
option takes a numeric argument as the size in bytes of the input buffer and but for the output buffer.
the .IP \fB-S\fP
.B -B Seeks a number of bytes through the output before starting to write from
option does the same for the output buffer, the default for both being 1024 the input. If the output is a stream, null characters are printed.
bytes, or one kibibyte (KiB). .IP \fB-a\fP
.PP Accepts a single literal byte with which input buffer is padded in the event
The of an incomplete read from the input file.
.B -s .IP \fB-A\fP
option takes a numeric argument as the number of bytes to skip into the input Specifying this option pads the input buffer with null bytes in the event of an
before starting to read, and the incomplete read. Equivalent to specifying
.B -S
option skips a number of bytes through the output before starting to write from
the input. If the input is a stream the bytes are read and discarded. If the
output is a stream, nul characters are printed.
.PP
The
.B -a .B -a
option takes one argument of one byte in length and pads the input buffer with with a null byte instead of a character.
that byte in the event that a read doesn't fill the input buffer, and the .IP \fB-c\fP
.B -A Specifies a number of reads to make. The default is zero, in which case the
option takes no arguments and pads with nuls. input is read until a partial or empty read is made.
The .IP \fB-d\fP
.B -c Prints invocation information before program execution as described in the
option specifies an amount of reads to make, and if 0 (the default) dj will DIAGNOSTICS section below. Each invocation increments the debug level of the
continue reading until a partial or empty read. program.
.PP .IP \fB-H\fP
On a partial or empty read, dj prints a diagnostic message (unless the Prints diagnostics messages in a human-readable manner as described in the
.B -q DIAGNOSTICS section below.
option is specified) and exits (unless the .IP \fB-n\fP
.B -n Retries failed reads once more before exiting.
option is specified, in which case only two consecutive empty reads will cause .IP \fB-q\fP
dj to exit). Suppresses error messages which print when a read or write is partial or
At exit, usage statistics are printed unless the option empty. Each invocation decrements the debug level of the program.
.B -q .\"
is specified a second time. The .SH STANDARD INPUT
.B -H
option will make these diagnostics human-readable.
The standard input shall be used as an input if no inputs are specified or if
one or more of the input files is \(lq-\(rq.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
The On a partial or empty read, a diagnostic message is printed (unless the
.B -d .B -q
option prints all information, user-specified or otherwise, before program option is specified) and the program exits (unless the
execution. .B -n
.PP option is specified).
When dj exits, by default statistics are printed for input and output to
standard error in the following format: By default, statistics are printed for input and output to the standard error in
.PP the following format:
.RS
.R {records read} {ASCII unit separator} {partial records read} .R {records read} {ASCII unit separator} {partial records read}
.R {ASCII record separator} {records written} {ASCII unit separator} .R {ASCII record separator} {records written} {ASCII unit separator}
.R {partial records written} {ASCII group separator} {bytes read} .R {partial records written} {ASCII group separator} {bytes read}
.R {ASCII record separator} {bytes written} {ASCII file separator} .R {ASCII record separator} {bytes written} {ASCII file separator}
.PP .RE
If the
This format for diagnostic output is designed to be machine-parseable for
convenience. For a more human-readable format, the
.B -H .B -H
option is specified dj instead uses this following format: option may be specified. In this event, the following format is used instead:
.PP
.RS
.R {records read} '+' {partial records read} '>' {records written} .R {records read} '+' {partial records read} '>' {records written}
.R '+' {partial records written} ';' {bytes read} '>' {bytes written} .R '+' {partial records written} ';' {bytes read} '>' {bytes written}
.R {ASCII line feed} .R {ASCII line feed}
.PP .RE
The
.B -q
option suppresses error messages which print when a read or write is partial or
empty and when used twice suppresses diagnostic output entirely.
.PP
In non-recoverable errors that don't pertain to dj's read-write cycle, a
diagnostic message is printed and dj exits with the appropriate sysexits(3)
status.
If the
.B -d
option is specified, debug output will be printed at the beginning of
execution. This debug information contains information regarding how the program
was invoked. The following example is the result of running the program with
.B -d
as the only argument:
.RS
.R argv0=dj
.R in=<stdin> ibs=1024 skip=0 align=ff count=0
.R out=<stdout> obs=1024 seek=0 debug= 3 noerror=0
.RE
In non-recoverable errors that don\(cqt pertain to the read-write cycle, a
diagnostic message is printed and the program exits with the appropriate
.BR sysexits.h (3)
status.
.\"
.SH BUGS .SH BUGS
If If
.B -n .B -n
is specified along with a specified count, actual byte output may be lower than is specified along with the
expected (the product of the count multiplied by the input block size). If the .B -c
option and a count, actual byte output may be lower than expected (the product
of the count and the input block size). If the
.B -a .B -a
or or
.B -A .B -A
options are used this could make data written nonsensical. options are used, this could make data written nonsensical.
.PP .\"
.SH CAVEATS
Existing files are not truncated on ouput and are instead overwritten.
Many lowercase options have capitalized variants and vice-versa which can be Many lowercase options have capitalized variants and vice-versa which can be
confusing. Capitalized options tend to affect output or are more intense confusing. Capitalized options tend to affect output or are more intense
versions of lowercase options. versions of lowercase options.
.\"
.SH RATIONALE .SH RATIONALE
Dj was modeled after the dd utility specified in POSIX but adds additional This program was based on the
features: typical option formatting, allowing seeks to be specified in bytes .BR dd (1p)
rather than in blocks, allowing arbitrary bytes as padding, and printing in a utility as specified in POSIX. While character conversion may have been the
format that's easy to parse for machines. It also neglects character original intent of
conversion, which may be dd's original intent but is irrelevant to its modern .BR dd (1p),
use. it is irrelevant to its modern use. Because of this, this program eschews
character conversion and adds typical option formatting, allowing seeks to be
specified in bytes rather than in blocks, allowing arbitrary bytes as padding,
and printing in a format that\(cqs easy for machines to parse.
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR dd (1p)
dd(1)

34
docs/false.1
View File

@ -1,35 +1,35 @@
.\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH FALSE 1 .TH FALSE 1
.SH NAME .SH NAME
false \(en do nothing, unsuccessfully false \(en do nothing, unsuccessfully
.\"
.SH DESCRIPTION .SH DESCRIPTION
False does nothing regardless of operands or standard input. Do nothing regardless of operands or standard input. An exit code of 1 will
False will always return an exit code of 1. always be returned.
.\"
.SH RATIONALE .SH RATIONALE
False exists for the construction of control flow and loops based on a failure. In POSIX.1-2017,
.BR false (1p)
False functions as described in POSIX.1-2017. exists for the construction of control flow and loops based on a failure. This
implementation functions as described in that standard.
.\"
.SH AUTHOR .SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
This work is marked with CC0 1.0. To see a copy of this license, visit This work is marked with CC0 1.0. To see a copy of this license, visit
<http://creativecommons.org/publicdomain/zero/1.0>. <http://creativecommons.org/publicdomain/zero/1.0>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR true (1p)
true(1p)

60
docs/fop.1 Normal file
View File

@ -0,0 +1,60 @@
.\" Copyright (c) 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 fop 1
.SH NAME
fop \(en field operator
.\"
.SH SYNOPSIS
fop
.RB ( -d )
.RB [ delimiter ]
.RB index
.RB program...
.\"
.SH DESCRIPTION
Performs operations on specified fields in input data.
.\"
.SH OPTIONS
.IP \fB-d\fP
Sets a delimiter by which the input data will be split into fields. The default
is an ASCII record separator.
.\"
.SH STANDARD INPUT
Data will be read from the standard input.
.\"
.SH CAVEATS
Field indices are zero-indexed, which may be unexpected behavior for some users.
.\"
.SH RATIONALE
With the assumption that tools will output data separated with ASCII field
separators, there is a need for the ability to modify select fields in this data
easily and quickly.
The idea for this utility originated in the fact that the GNU
.BR ls (1)
utility contains a
.B -h
option which enables human-readable units in file size outputs. This
functionality was broken out into
.BR hru (1),
but there was no easy way to modify the field in the ouput of
.BR ls (1p)
without creating a new tool.
.\"
.SH COPYRIGHT
Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
.BR sed (1p)

72
docs/hru.1
View File

@ -2,56 +2,66 @@
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH rpn 1 .TH HRU 1
.SH NAME .SH NAME
hru \(en human readable units hru \(en human readable units
.\"
.SH SYNOPSIS .SH SYNOPSIS
hru hru
.\"
.SH DESCRIPTION .SH DESCRIPTION
Hru reads byte counts in the form of whole numbers from the standard input and Convert counts to higher units.
writes to the standard output the same number converted one of the units of data
defined by the International System of Units. The program will read byte counts in the form of whole numbers from the standard
input and write to the standard output the same number converted to a higher
unit of data as defined by the International System of Units.
The program will convert the byte count to the highest unit possible where the The program will convert the byte count to the highest unit possible where the
value is greater than one. value is greater than one.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
If encountering non-integer characters in the standard input, hru will exit with If encountering non-integer characters in the standard input, the program will
the appropriate error code as defined by sysexits.h(3) and print an error exit with the appropriate error code as defined by
message. .BR sysexits.h (3)
and print an error message.
.\"
.SH RATIONALE .SH RATIONALE
The GNU project’s ls(1) implementation contains a human-readable option (-h) The GNU project\(cqs
that, when specified, makes the tool print size information in a format more .BR ls (1)
immediately readable. This functionality is useful not only in the context of implementation contains a human-readable option (\fB-h\fP) that, when specified,
ls(1) so the decision was made to split it into a new tool. The original makes the tool print size information in a format more immediately
functionality in GNU’s ls(1) can be emulated with fop(1) combined with this readable. This functionality is useful not only in the context of
program. .BR ls (1)
so the decision was made to split it into a new tool. The original functionality
in GNU\(cqs
.BR ls (1)
can be emulated with
.BR fop (1)
combined with this program.
.\"
.SH STANDARDS .SH STANDARDS
Hru follows the standard unit prefixes as specified by the Bureau International The standard unit prefixes as specified by the Bureau International des Poids
des Poids et Mesures (BIPM) in the ninth edition of The International System of et Mesures (BIPM) in the ninth edition of The International System of Units (SI)
Units (SI). are utilized for the ouput of conversions.
.\"
.SH AUTHOR .SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
GNU
GNU ls(1), The International System of Units (SI) 9th Edition .BR ls (1),
The International System of Units (SI) 9th Edition

108
docs/intcmp.1
View File

@ -1,78 +1,92 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH intcmp 1 .TH INTCMP 1
.SH NAME .SH NAME
intcmp \(en compare integers intcmp \(en compare integers
.\"
.SH SYNOPSIS .SH SYNOPSIS
intcmp intcmp
.RB ( -eghl ) .RB ( -egl )
.RB [ integer ] .RB [ integer ]
.RB [ integer... ] .RB [ integer... ]
.SH DESCRIPTION .SH DESCRIPTION
Compare integers to each other.
.\"
.SH OPTIONS
Intcmp compares integers. .IP \fB-e\fP
Permits given integers to be equal to each other.
.IP \fB-g\fP
Permits a given integer to be greater than the following integer.
.IP \fB-l\fP
Permits a given integer to be less than the following integer.
.\"
.SH EXAMPLES
.SH USAGE
The -e option permits given integers to be equal to each other. If combined
with -g or -l, only adjacent integers in the argument sequence can be equal.
.PP
The -g option permits a given integer to be greater than the following integer.
.PP
The -l option permits a given integer to be less than the following integer.
.PP
It may help to think of the -e, -g, and -l options as equivalent to the It may help to think of the -e, -g, and -l options as equivalent to the
infix algebraic “=”, “>”, and “<” operators respectively, with each option infix algebraic \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq operators respectively, with
putting its symbol between every given integer. For example, each option putting its symbol between every given integer. The following
example is equivalent to evaluating \(lq1 < 2 < 3\(rq:
\"
.RS
.R intcmp -l 1 2 3 .R intcmp -l 1 2 3
is equivalent to evaluating "1 < 2 < 3". .RE
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
Intcmp exits 0 for a valid expression and 1 for an invalid expression. The program will exit with a status code of 0 for a valid expression and with a
.PP code of 1 for an invalid expression.
Intcmp prints a debug message and exits with the appropriate sysexits(3) error
code in the event of an error.
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.
.\"
.SH BUGS .SH BUGS
There are multiple ways to express compound comparisons; “less than or equal -egl, \(lqequal to or less than or greater than\(rq, exits 0 no matter what for
to” can be -le or -el, for example. valid program usage and may be abused to function as an integer validator. Use
.PP .BR str (1)
The inequality comparison is -gl or -lg for “less than or greater than”; this instead.
is elegant but unintuitive. .\"
.PP .SH CAVEATS
-egl, "equal to or less than or greater than", exits 0 no matter what for valid
program usage and may be abused to function as an integer validator.
Use str(1) instead.
There are multiple ways to express compound comparisons; \(lqless than or equal
to\(rq can be -le or -el, for example.
The inequality comparison is -gl or -lg for \(lqless than or greater than\(rq;
this is elegant but unintuitive.
.\"
.SH RATIONALE .SH RATIONALE
The traditional tool for integer comparisons in POSIX and other Unix shells has The traditional tool for integer comparisons in POSIX and other Unix shells has
been test(1). This tool also handles string comparisons and file scrutiny. been
These parts of its functionality have been broken out into multiple utilities. .BR test (1).
This tool also handles string comparisons and file scrutiny. These parts of its
Strcmp’s functionality may be performed on a POSIX-compliant system with functionality have been broken out into multiple utilities.
test(1p).
This program\(cqs functionality may be performed on a POSIX-compliant system
with
.BR test (1p).
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
.\"
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR scrut (1),
strcmp(1), scrut(1), str(1), test(1p) .BR strcmp (1),
.BR str (1),
.BR test (1p)

91
docs/mm.1
View File

@ -2,13 +2,11 @@
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH mm 1 .TH mm 1
.SH NAME .SH NAME
mm \(en middleman mm \(en middleman
.\"
.SH SYNOPSIS .SH SYNOPSIS
mm mm
@ -17,60 +15,59 @@ mm
.RB [ input ]) .RB [ input ])
.RB ( -o .RB ( -o
.RB [ output ]) .RB [ output ])
.\"
.SH DESCRIPTION .SH DESCRIPTION
Mm catenates input files and writes them to the start of each output file. Catenate input files and write them to the start of each output file or stream.
.\"
.SH OPTIONS .SH OPTIONS
Mm, upon receiving the .IP \fB-a\fP
.B -a Opens subsequent outputs for appending rather than updating.
option, will open subsequent outputs for appending rather than updating. .IP \fB-e\fP
.PP Use the standard error as an output.
The .IP \fB-i\fP
.B -i Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
option opens a path as an input. Without any inputs specified mm will use no inputs are specified, the standard input shall be used.
standard input. Standard input itself can be specified by giving the path '-'. .IP \fB-o\fP
.PP Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
The no outputs are specified, the standard output shall be used.
.B -o .IP \fB-u\fP
option opens a path as an output. Without any outputs specified mm will use Ensures neither input or output will be buffered.
standard output. Standard output itself can be specified by giving the .IP \fB-n\fP
path '-'. Standard error itself can be specified with the Causes SIGINT signals to be ignored.
.B -e .\"
option.
.PP
The
.B -u
option ensures neither input or output will be buffered.
.PP
The
.B -n
option tells mm to ignore SIGINT signals.
.SH DIAGNOSTICS .SH DIAGNOSTICS
If an output can no longer be written mm prints a diagnostic message, ceases If an output cannot be written to, an error occurs. Additional outputs are not
writing to that particular output, and if there are more outputs specified, affected and writing to them continues.
continues, eventually exiting unsuccessfully.
.PP
On error mm prints a diagnostic message and exits with the appropriate
sysexits.h(3) status.
.SH BUGS When an error is encountered, a diagnostic message is printed and the program
exits with the appropriate
Mm does not truncate existing files, which may lead to unexpected results. .BR sysexits.h (3)
status.
.\"
.SH CAVEATS
Existing files are not truncated on ouput and are instead overwritten.
.\"
.SH RATIONALE .SH RATIONALE
Mm was modeled after the cat and tee utilities specified in POSIX. The
.BR cat (1p)
and
.BR tee (1p)
programs specified in POSIX together provide similar functionality. The
separation of the two sets of functionality into separate APIs seemed
unncessary.
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR cat (1p),
cat(1p), dd(1), dj(1), tee(1p) .BR dd (1),
.BR dj (1),
.BR tee (1p)

80
docs/npc.1
View File

@ -1,68 +1,74 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH npc 1 .TH NPC 1
.SH NAME .SH NAME
npc \(en show non-printing characters npc \(en show non-printing characters
.\"
.SH SYNOPSIS .SH SYNOPSIS
npc npc
.RB ( -eht ) .RB ( -et )
.\"
.SH DESCRIPTION .SH DESCRIPTION
Npc reads from standard input and writes to standard output, replacing non- Print normally non-printing characters.
printing characters with printable equivalents. Control characters print as a
carat ('^') followed by the character '@' through '_' corresponding to the The program reads from standard input and writes to standard output, replacing
character replaced (e.g. control-X becomes "^X"). The delete character (0x7F) non-printing characters with printable equivalents. Control characters print as
becomes "^?". Characters with the high bit set (>127) are printed as "M-" a carat ('^') followed by the character '@' through '_' corresponding to the
character replaced (e.g. control-X becomes '^X'). The delete character (0x7F)
becomes '^?'. Characters with the high bit set (>127) are printed as 'M-'
followed by the graphical representation for the same character without the followed by the graphical representation for the same character without the
high bit set. high bit set.
.PP .\"
The .SH USAGE
.B -e
option prints a currency sign ('$') before each line ending.
.PP
The
.B -t
option prints tab characters as "^I" rather than a literal horizontal tab.
.IP \fB-e\fP
Prints a dollar sign ('$') before each line ending.
.IP \fB-t\fP
Prints tab characters as '^I' rather than a literal horizontal tab.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
Npc prints a debug message and exits with the appropriate sysexits(3) error In the event of an error, a debug message will be printed and the program will
code in the event of an error, otherwise it exits successfully. exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH BUGS .SH BUGS
Npc operates in single-byte chunks regardless of intended encoding. The program operates in single-byte chunks regardless of intended encoding.
.\"
.SH RATIONALE .SH RATIONALE
POSIX currently lacks a way to display non-printing characters in the terminal POSIX currently lacks a way to display non-printing characters in the terminal
using a standard tool. A popular extension to cat(1p), the -v option, is the using a standard tool. A popular extension to
bandage solution GNU and other software suites use. .BR cat (1p),
the
This functionality should be a separate tool because its usefulness extends .B -v
beyond that of cat(1p). option, is the bandage solution GNU and other software suites use.
This functionality is a separate tool because its usefulness extends beyond that
of
.BR cat (1p).
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR cat (1p),
cat(1p), cat-v(1) .BR cat-v (1),
.I UNIX Style, or cat -v Considered Harmful .I UNIX Style, or cat -v Considered Harmful
by Rob Pike by Rob Pike

82
docs/rpn.1
View File

@ -3,68 +3,82 @@
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH rpn 1 .TH rpn 1
.SH NAME .SH NAME
rpn \(en reverse polish notation evaluation rpn \(en reverse polish notation evaluation
.\"
.SH SYNOPSIS .SH SYNOPSIS
rpn rpn
.RB [numbers...]\ [operators...] .RB [ numbers... ]
.RB [ operators... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
Rpn evaluates reverse polish notation expressions either read from the standard Evaluate reverse polish notation.
input or parsed from provided arguments. See the STANDARD INPUT section.
Upon evaluation, rpn will print the resulting number on the stack to the The program evaluates reverse polish notation expressions either read from the
standard input or parsed from provided arguments. See the STANDARD INPUT
section.
Upon evaluation, the program will print the resulting number on the stack to the
standard output. Any further specified numbers will be placed at the end of the standard output. Any further specified numbers will be placed at the end of the
stack. stack.
For information on for reverse polish notation syntax, see rpn(7). For information on for reverse polish notation syntax, see
.BR rpn (7).
.\"
.SH STANDARD INPUT .SH STANDARD INPUT
If arguments are passed to rpn, it interprets them as an expression to be If arguments are passed, they are interpreted as an expression to be
evaluated. Otherwise, it reads whitespace-delimited numbers and operations from evaluated. Otherwise, it reads whitespace-delimited numbers and operations from
the standard input. the standard input.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
If encountering a syntax error, rpn will exit with the appropriate error code In the event of an error, a debug message will be printed and the program will
as defined by sysexits.h(3) and print an error message. exit with the appropriate
.BR sysexits.h (3)
error code; however, in the event of a syntax error, the program will print an
error message and continue accepting input.
.\"
.SH CAVEATS .SH CAVEATS
Due to precision constraints and the way floats are represented in accordance Due to precision constraints and the way floats are represented in accordance
with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point with the IEEE Standard for Floating Point Arithmetic (\fIIEEE 754\fP),
arithmetic has rounding errors. This is somewhat curbed by using the floating-point arithmetic has rounding errors. This is somewhat curbed by using
machine epsilon as provided by the Rust standard library to which to round the machine epsilon as provided by the Rust standard library to which to round
numbers. Because of this, variation is expected in the number of decimal places numbers. Because of this, variation is expected in the number of decimal places
rpn can handle based on the platform and hardware of any given machine. the program can handle based on the platform and hardware of any given machine.
.\"
.SH RATIONALE .SH RATIONALE
An infix notation calculation utility, bc(1p), is included in the POSIX An infix notation calculation utility,
standard, but does not accept expressions as arguments; in scripts, any .BR bc (1p),
predefined, non-interactive input must be piped into the program. A dc(1) is included in the POSIX standard, but does not accept expressions as arguments;
pre-dates the standardized bc(1p), the latter originally being a preprocessor in scripts, any predefined, non-interactive input must be piped into the
for the former, and was included in UNIX v2 onward. While it implements reverse program. A
polish notation, it still suffers from being unable to accept an expression as .BR dc (1)
an argument. pre-dates the standardized
.BR bc (1p),
the latter originally being a preprocessor for the former, and was included in
UNIX v2 onward. While it implements reverse polish notation, it still suffers
from being unable to accept an expression as an argument.
.\"
.SH AUTHOR .SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR bc (1p),
bc(1p), dc(1), rpn(7), IEEE 754 .BR dc (1),
.BR rpn (7),
.I IEEE 754

123
docs/scrut.1
View File

@ -1,93 +1,86 @@
.\" Copyright (c) 2024 DTB <trinity@trinity.moe> .\" Copyright (c) 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, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH scrut 1 .TH scrut 1
.SH NAME .SH NAME
scrut \(en scrutinize file properties scrut \(en scrutinize file properties
.SH SYNOPSIS .SH SYNOPSIS
scrut scrut
.RB ( -bcdefgkprsuwxLS ) .RB ( -LSbcdefgkprsuwx )
.RB [ file... ] .RB [ file... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
Scrut determines if given files comply with the opted requirements. Determine if files comply with requirements. If the given files comply with the
specified requirements, the program will exit successfully. Otherwise, it exits
unsuccessfully.
.\"
.SH OPTIONS .SH OPTIONS
.B -b .IP \fB-L\fB
requires the given files to exist and be block special files. Requires the given files to exist and be symbolic links.
.PP .IP \fB-S\fP
.B -c Requires the given files to exist and be sockets.
requires the given files to exist and be character special files. .IP \fB-b\fP
.PP Requires the given files to exist and be block special files.
.B -d .IP \fB-c\fP
requires the given files to exist and be directories. Requires the given files to exist and be character special files.
.PP .IP \fB-d\fP
.B -e Requires the given files to exist and be directories.
requires the given files to exist, and is redundant to any other option. .IP \fB-e\fP
.PP Requires the given files to exist, and is redundant to any other option.
.B -e .IP \fB-f\fP
requires the given files to exist and be regular files. Requires the given files to exist and be regular files.
.PP .IP \fB-g\fP
.B -g Requires the given files to exist and have their set group ID flags set.
requires the given files to exist and have their set group ID flags set. .IP \fB-k\fP
.PP Requires the given files to exist and have their sticky bit set.
.B -k .IP \fB-p\fP
requires the given files to exist and have their sticky bit set. Requires the given files to exist and be named pipes.
.PP .IP \fB-r\fP
.B -p Requires the given files to exist and be readable.
requires the given files to exist and be named pipes. .IP \fB-u\fP
.PP Requires the given files to exist and have their set user ID flags set.
.B -r .IP \fB-w\fP
requires the given files to exist and be readable. Requires the given files to exist and be writable.
.PP .IP \fB-x\fP
.B -u Requires the given files to exist and be executable.
requires the given files to exist and have their set user ID flags set. .\"
.PP .SH DIAGNOSTICS
.B -w
requires the given files to exist and be writable.
.PP
.B -x
requires the given files to exist and be executable.
.PP
.B -L
requires the given files to exist and be symbolic links.
.PP
.B -S
requires the given files to exist and be sockets.
.SH EXIT STATUS When invoked incorrectly, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH RATIONALE
Scrut prints a debug message and exits unsuccessfully with the appropriate The
sysexits.h(3) error code if invoked incorrectly. Scrut exits successfully if .BR test (1p)
the given files comply with their requirements and unsuccessfully otherwise. utility contains functionality that was broken out into separate programs. Thus,
the scope of this program is narrower than it. Notably, the
.SH STANDARDS
Scrut is nearly compatible with POSIX's test utility though it is narrower in
scope. Notably, the
.B -h .B -h
option is now invalid and therefore shows usage information instead of being an option is now invalid and therefore shows usage information instead of being an
alias to the modern alias to the modern
.B -L .B -L
option. option.
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright © 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR access (3p),
access(3p), lstat(3p), test(1p) .BR lstat (3p),
.BR test (1p)

62
docs/str.1
View File

@ -1,58 +1,60 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH STR 1 .TH STR 1
.SH NAME .SH NAME
str \(en test the character types of string arguments str \(en test the character types of string arguments
.\"
.SH SYNOPSIS .SH SYNOPSIS
str str
.RB [ type ] .RB [ type ]
.RB [ string... ] .RB [ string... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
Str tests each character in an arbitrary quantity of string arguments against Test string arguments.
the function of the same name within ctype(3).
The tests in this program are equivalent to the functions with the same names in
.BR ctype.h (0p)
and are the methods by which string arguments are tested.
.\"
.SH DIAGNOSTICS .SH DIAGNOSTICS
Str exits successfully if all tests pass and unsuccessfully if a test failed. If all tests pass, the program will exit with an exit code of 0. If any of the
.PP tests fail, the program will exit unsuccessfully with an error code of 1.
Str will exit unsuccessfully if a string is empty, as none of its contents
passed the test.
.PP
Str will print a message to standard error and exit unsuccessfully if used
improperly.
.SH DEPRECATED FEATURES An empty string will cause an unsuccessful exit as none of its contents pass any
tests.
Str used to have an "isvalue" type as an extension to ctype(3). This was When invoked incorrectly, a debug message will be printed and the program will
removed in favor of using strcmp(1) to compare strings against the empty string exit with the appropriate
(''). .BR sysexits.h (3)
error code.
.\"
.SH CAVEATS
.SH BUGS There\(cqs no way of knowing which argument failed the test without re-testing
There's no way of knowing which argument failed the test without re-testing
arguments individually. arguments individually.
.PP
If a character in a string isn't valid ASCII str will exit unsuccessfully.
If a character in a string isn\(cqt valid ASCII, the program will exit
unsuccessfully.
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR ctype (3p),
ctype(3p), strcmp(1), ascii(7) .BR strcmp(1),
.BR ascii(7)

79
docs/strcmp.1
View File

@ -1,62 +1,75 @@
.\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2023–2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH STRCMP 1 .TH STRCMP 1
.SH NAME .SH NAME
strcmp \(en compare strings strcmp \(en compare strings
.\"
.SH SYNOPSIS .SH SYNOPSIS
strcmp strcmp
.RM [ string ] .RM [ string ]
.RB [ strings... ] .RB [ strings... ]
.\"
.SH DESCRIPTION .SH DESCRIPTION
Strcmp checks whether the given strings are the same. Check whether string arguments are the same.
Strcmp exits successfully if the strings are identical. Otherwise, strcmp exits .\"
with the value 1 if an earlier string has a greater byte value than a later
string (e.g.
.R strcmp b a
)
and 255 if an earlier string has a lesser byte value (e.g.
.R strcmp a b
).
.SH DIAGNOSTICS .SH DIAGNOSTICS
Strcmp will print an error message and exit unsuccessfully with a status The program will exit successfully if the strings are identical. Otherwise, it
described in sysexits(3) if used incorrectly (given less than two operands). will exit with an error code of 1 if a string passed has a lesser byte value
than one of the prior strings:
.SH UNICODE .RS
.R strcmp b a
.RE
Strcmp will exit unsuccessfully if the given strings are not identical; and with an error code of 255 if it has a greater byte value than one of the
Unicode strings may need to be normalized if the intent is to check visual prior strings:
similarity and not byte similarity.
.RS
.R strcmp a b
.RE
When invoked incorrectly, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH CAVEATS
The program will exit unsuccessfully if the given strings are not identical;
therefore, Unicode strings may need to be normalized if the intent is to check
visual similarity and not byte similarity.
.\"
.SH RATIONALE .SH RATIONALE
The traditional tool for string comparisons in POSIX and other Unix shells has The traditional tool for string comparisons in POSIX and other Unix shells has
been test(1). This tool also handles integer comparisons and file scrutiny. been
These parts of its functionality have been broken out into multiple utilities. .BR test (1).
This tool also handles integer comparisons and file scrutiny. These parts of its
Strcmp’s functionality may be performed on a POSIX-compliant system with functionality have been broken out into multiple utilities.
test(1p).
This program\(cqs functionality may be performed on a POSIX-compliant system with
.BR test (1p).
.\"
.SH AUTHOR .SH AUTHOR
Written by DTB <trinity@trinity.moe>. Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/gpl.html>. <https://gnu.org/licenses/gpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR strcmp (3),
strcmp(3), intcmp(1), scrut(1), test(1p) .BR intcmp (1),
.BR scrut (1),
.BR test (1p)

80
docs/swab.1
View File

@ -1,14 +1,13 @@
.\" Copyright (c) 2024 DTB <trinity@trinity.moe> .\" Copyright (c) 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, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH swab 1 .TH SWAB 1
.SH NAME .SH NAME
swab \(en swap bytes swab \(en swap bytes
.\"
.SH SYNOPSIS .SH SYNOPSIS
swab swab
@ -17,55 +16,58 @@ swab
.R [ .R [
.B word size .B word size
.R ]) .R ])
.\"
.SH DESCRIPTION
.SH USAGE Swap the latter and former halves of a block of bytes.
.\"
Swab swaps the latter and former halves of a block of bytes. .SH OPTIONS
.IP \fB-f\fP
Ignore SIGINT signal.
.IP \fB-w\fP
Configures the word size; that is, the size in bytes of the block size
on which to operate. The default word size is 2. The word size must be
cleanly divisible by 2, otherwise the block of bytes being processed can\(cqt be
halved.
.\"
.SH EXAMPLES .SH EXAMPLES
The following sh(1p) line: The following
.BR sh (1p)
line:
.R printf 'hello world!\n' | swab .RS
.R printf 'hello world!\(rsn' | swab
.RE
Produces the following output: Produces the following output:
.RS
.R ehll oowlr!d .R ehll oowlr!d
.RE
.SH OPTIONS .\"
The
.B -f
option ignores system call interruptions.
.PP
The
.B -w
option configures the word size; that is, the size in bytes of the block size
on which to operate. By default the word size is 2. The word size must be
cleanly divisible by 2, otherwise the block of bytes being processed can't be
halved.
.SH DIAGNOSTICS .SH DIAGNOSTICS
If an error is encountered in input, output, or invocation, a diagnostic In the event of an error, a debug message will be printed and the program will
message will be written to standard error and swab will exit with the exit with the appropriate
appropriate status from sysexits.h(3). .BR sysexits.h (3)
error code.
.\"
.SH RATIONALE .SH RATIONALE
Swab was modeled after the This program was modeled and named after the conv=swab functionality specified
.R conv=swab in the
functionality specified in the POSIX dd utility but additionally allows the .BR dd (1p)
word size to be configured. utility. It additionally allows the word size to be configured.
.PP
Swab is useful for fixing the endianness of binary files produced on other
machines.
This functionality is useful for fixing the endianness of binary files produced
on other machines.
.\"
.SH COPYRIGHT .SH COPYRIGHT
Copyright (c) 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>. <https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR dd (1p)
dd(1p)

35
docs/true.1
View File

@ -1,35 +1,36 @@
.\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe> .\" Copyright (c) 2022, 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2023 Emma Tebibyte <emma@tebibyte.media> .\" Copyright (c) 2023–2024 Emma Tebibyte <emma@tebibyte.media>
.\" .\"
.\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" 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/>. .\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
.\"
.TH TRUE 1 .TH TRUE 1
.SH NAME .SH NAME
true \(en do nothing, successfully true \(en do nothing, successfully
.\"
.SH DESCRIPTION .SH DESCRIPTION
True does nothing regardless of operands or standard input. Do nothing regardless of operands or standard input. An exit code of 0 will
True will always return an exit code of 0. always be returned.
.\"
.SH RATIONALE .SH RATIONALE
True exists for the construction of control flow and loops based on a success. In \fIPOSIX.1-2017\fP,
.BR true (1p)
True functions as described in POSIX.1-2017. exists for the construction of control flow and loops based on a success. This
implementation functions as described in that standard.
.\"
.SH AUTHOR .SH AUTHOR
Written by Emma Tebibyte <emma@tebibyte.media>. Written by Emma Tebibyte
.MT emma@tebibyte.media
.ME .
.\"
.SH COPYRIGHT .SH COPYRIGHT
This work is marked with CC0 1.0. To see a copy of this license, visit This work is marked with CC0 1.0. To see a copy of this license, visit
<http://creativecommons.org/publicdomain/zero/1.0>. <http://creativecommons.org/publicdomain/zero/1.0>.
.\"
.SH SEE ALSO .SH SEE ALSO
.BR false (1p),
false(1p) .BR true (1p)