Merge branch 'main' into stris
This commit is contained in:
328
docs/dj.1
328
docs/dj.1
@@ -1,160 +1,226 @@
|
||||
.\" 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 dj 1
|
||||
|
||||
.\"
|
||||
.TH DJ 1 2024-07-14 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
dj \(en disk jockey
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
dj
|
||||
.RB ( -AdHnq )
|
||||
.RB ( -a
|
||||
.RB [ byte ])
|
||||
.RB ( -c
|
||||
.RB [ count ])
|
||||
.RB [ -Hn ]
|
||||
.RB [ -a\ byte ]
|
||||
.RB [ -c\ count ]
|
||||
|
||||
.RB ( -i
|
||||
.R [
|
||||
.B input file
|
||||
.R ])
|
||||
.RB ( -b
|
||||
.R [
|
||||
.B input block size
|
||||
.R ])
|
||||
.RB ( -s
|
||||
.R [
|
||||
.B input offset
|
||||
.R ])
|
||||
.RB [ -i\ file ]
|
||||
.RB [ -b\ block_size ]
|
||||
.RB [ -s\ offset ]
|
||||
|
||||
.RB ( -o
|
||||
.R [
|
||||
.B output file
|
||||
.R ])
|
||||
.RB ( -B
|
||||
.R [
|
||||
.B output block size
|
||||
.R ])
|
||||
.RB ( -S
|
||||
.R [
|
||||
.B output offset
|
||||
.R ])
|
||||
.RB [ -o\ file ]
|
||||
.RB [ -B\ block_size ]
|
||||
.RB [ -S\ offset ]
|
||||
.\"
|
||||
.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.
|
||||
|
||||
The
|
||||
.B -i
|
||||
option takes a path as an argument to open and use in place of standard input.
|
||||
The
|
||||
.B -o
|
||||
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.
|
||||
.PP
|
||||
The
|
||||
.B -b
|
||||
option takes a numeric argument as the size in bytes of the input buffer and
|
||||
the
|
||||
.B -B
|
||||
option does the same for the output buffer, the default for both being 1024
|
||||
bytes, or one kibibyte (KiB).
|
||||
.PP
|
||||
The
|
||||
.B -s
|
||||
option takes a numeric argument as the number of bytes to skip into the input
|
||||
before starting to read, and the
|
||||
.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
|
||||
option takes one argument of one byte in length and pads the input buffer with
|
||||
that byte in the event that a read doesn't fill the input buffer, and the
|
||||
.B -A
|
||||
option takes no arguments and pads with nuls.
|
||||
The
|
||||
.B -c
|
||||
option specifies an amount of reads to make, and if 0 (the default) dj will
|
||||
continue reading until a partial or empty read.
|
||||
.PP
|
||||
On a partial or empty read, dj prints a diagnostic message (unless the
|
||||
.B -q
|
||||
option is specified) and exits (unless the
|
||||
.B -n
|
||||
option is specified, in which case only two consecutive empty reads will cause
|
||||
dj to exit).
|
||||
At exit, usage statistics are printed unless the option
|
||||
.B -q
|
||||
is specified a second time. The
|
||||
.B -H
|
||||
option will make these diagnostics human-readable.
|
||||
This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
|
||||
to a specified byte by index in the input and output of the program
|
||||
respectively. This language is inherited from the
|
||||
.BR dd (1p)
|
||||
utility and used here to decrease ambiguity.
|
||||
|
||||
The offset used when skipping or seeking refers to how many bytes are skipped
|
||||
or sought. Running
|
||||
.BR dj (1)
|
||||
with a skip offset of 1 skips one byte into the input and reads from the second
|
||||
byte onwards. A programmer may think of a file as a zero-indexed array of
|
||||
bytes; in this analogy, the offset given is the index of the byte at which to
|
||||
start reading or writing.
|
||||
.\"
|
||||
.SH OPTIONS
|
||||
|
||||
.IP \fB-i\fP\ \fIfile\fP
|
||||
Takes a file path as an argument and opens it for use as an input.
|
||||
.IP \fB-b\fP\ \fIblock_size\fP
|
||||
Takes a numeric argument as the size in bytes of the input buffer, the default
|
||||
being 1024.
|
||||
.IP \fB-s\fP
|
||||
Takes a numeric argument as the index of the byte at which reading will
|
||||
commence; \(lqskips\(rq that number of bytes. 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\ \fIblock_size\fP
|
||||
Takes a numeric argument as the size in bytes of the output buffer, the default
|
||||
being 1024. Note that this option only affects the size of output writes and not
|
||||
the amount of output data itself. See the CAVEATS section.
|
||||
.IP \fB-S\fP
|
||||
Takes a numeric argument as the index of the byte at which writing will
|
||||
commence; \(lqseeks\(rq that number of bytes. If the standard output is used,
|
||||
null characters are printed.
|
||||
.IP \fB-a\fP
|
||||
Accepts a single literal byte with which the input buffer is padded in the event
|
||||
of an incomplete read from the input file. If the option argument is empty, the
|
||||
null byte is used.
|
||||
.IP \fB-c\fP
|
||||
Specifies a number of blocks to read. The default is 0, in which case the input
|
||||
is read until a partial or empty read is made.
|
||||
.IP \fB-H\fP
|
||||
Prints diagnostic messages in a human-readable manner as described in the
|
||||
DIAGNOSTICS section.
|
||||
.IP \fB-n\fP
|
||||
Retries failed reads once before exiting.
|
||||
.\"
|
||||
.SH STANDARD INPUT
|
||||
|
||||
The standard input shall be used as an input if no inputs are specified or if
|
||||
input file is \(lq-\(rq.
|
||||
.\"
|
||||
.SH STANDARD OUTPUT
|
||||
The standard output shall be used as an output if no inputs are specified or if
|
||||
the output file is \(lq-\(rq.
|
||||
.\"
|
||||
.SH EXAMPLES
|
||||
|
||||
The following
|
||||
.BR sh (1p)
|
||||
line:
|
||||
|
||||
.RS
|
||||
printf 'Hello, world!\(rsn' | dj -c 1 -b 7 -s 7 2>/dev/null
|
||||
.RE
|
||||
|
||||
Produces the following output:
|
||||
|
||||
.RS
|
||||
world!
|
||||
.RE
|
||||
|
||||
The following
|
||||
.BR sh (1p)
|
||||
lines run sequentially:
|
||||
|
||||
.RS
|
||||
tr '\(rs0' 0 </dev/zero | dj -c 1 -b 6 -o hello.txt
|
||||
|
||||
tr '\(rs0' H </dev/zero | dj -c 1 -b 1 -o hello.txt
|
||||
|
||||
tr '\(rs0' e </dev/zero | dj -c 1 -b 1 -o hello.txt -S 1
|
||||
|
||||
tr '\(rs0' l </dev/zero | dj -c 1 -b 2 -o hello.txt -S 2
|
||||
|
||||
tr '\(rs0' o </dev/zero | dj -c 1 -b 1 -o hello.txt -S 4
|
||||
|
||||
tr '\(rs0' '\(rsn' </dev/zero | dj -c 1 -b 1 -o hello.txt -S 5
|
||||
|
||||
dj -i hello.txt
|
||||
.RE
|
||||
|
||||
Produce the following output:
|
||||
|
||||
.RS
|
||||
Hello
|
||||
.RE
|
||||
|
||||
It may be particularly illuminating to print the contents of the example
|
||||
.B hello.txt
|
||||
after each
|
||||
.BR dj (1)
|
||||
invocation.
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
The
|
||||
.B -d
|
||||
option prints all information, user-specified or otherwise, before program
|
||||
execution.
|
||||
.PP
|
||||
When dj exits, by default statistics are printed for input and output to
|
||||
standard error in the following format:
|
||||
.PP
|
||||
.R {records read} {ASCII unit separator} {partial records read}
|
||||
.R {ASCII record separator} {records written} {ASCII unit separator}
|
||||
.R {partial records written} {ASCII group separator} {bytes read}
|
||||
.R {ASCII record separator} {bytes written} {ASCII file separator}
|
||||
.PP
|
||||
If the
|
||||
.B -H
|
||||
option is specified dj instead uses this following format:
|
||||
.PP
|
||||
.R {records read} '+' {partial records read} '>' {records written}
|
||||
.R '+' {partial records written} ';' {bytes read} '>' {bytes written}
|
||||
.R {ASCII line feed}
|
||||
.PP
|
||||
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.
|
||||
On a partial or empty read, a diagnostic message is printed. Then, the program
|
||||
exits unless the
|
||||
.B -n
|
||||
option is specified.
|
||||
|
||||
By default, statistics are printed for input and output to the standard error in
|
||||
the following format:
|
||||
|
||||
.RS
|
||||
{records read} {ASCII unit separator} {partial records read}
|
||||
{ASCII record separator} {records written} {ASCII unit separator}
|
||||
{partial records written} {ASCII group separator} {bytes read}
|
||||
{ASCII record separator} {bytes written} {ASCII file separator}
|
||||
.RE
|
||||
|
||||
This format for diagnostic output is designed to be machine-parseable for
|
||||
convenience. For a more human-readable format, the
|
||||
.B -H
|
||||
option may be specified. In this event, the following format is used instead:
|
||||
|
||||
.RS
|
||||
{records read} '+' {partial records read} '>' {records written}
|
||||
'+' {partial records written} ';' {bytes read} '>' {bytes written}
|
||||
{ASCII line feed}
|
||||
.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
|
||||
|
||||
If
|
||||
.B -n
|
||||
is specified along with a specified count, actual byte output may be lower than
|
||||
expected (the product of the count multiplied by the input block size). If the
|
||||
is specified along with the
|
||||
.B -c
|
||||
option and a count, actual byte output is the product of the count and the input
|
||||
block size and therefore may be lower than expected. If the
|
||||
.B -a
|
||||
or
|
||||
.B -A
|
||||
options are used this could make data written nonsensical.
|
||||
.PP
|
||||
Many lowercase options have capitalized variants and vice-versa which can be
|
||||
confusing. Capitalized options tend to affect output or are more intense
|
||||
versions of lowercase options.
|
||||
option is specified, this could make written data nonsensical.
|
||||
.\"
|
||||
.SH CAVEATS
|
||||
|
||||
Existing files are not truncated on ouput and are instead overwritten.
|
||||
|
||||
Option variants that have lowercase and uppercase forms could be confused for
|
||||
each other. The former affects input and the latter affects output.
|
||||
|
||||
The
|
||||
.B -B
|
||||
option could be mistaken for the count in bytes of data written to the output.
|
||||
This conception is intuitive but incorrect, as the
|
||||
.B -c
|
||||
option controls the number of blocks to read and the
|
||||
.B -b
|
||||
option sets the size of the blocks. The
|
||||
.B -B
|
||||
option is similar to the latter but sets the size of blocks to be written,
|
||||
regardless of the amount of data that will actually be written. In practice,
|
||||
this means the input buffer should be very large to make use of modern hardware
|
||||
input and output speeds.
|
||||
|
||||
The skipped or sought bytes while processing irregular files, such as streams,
|
||||
are reported in the diagnostic output, because they were actually read or
|
||||
written. This is as opposed to bytes skipped while processing regular files,
|
||||
which are not reported.
|
||||
.\"
|
||||
.SH RATIONALE
|
||||
|
||||
Dj was modeled after the dd utility specified in POSIX but adds additional
|
||||
features: 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's easy to parse for machines. It also neglects character
|
||||
conversion, which may be dd's original intent but is irrelevant to its modern
|
||||
use.
|
||||
|
||||
This program was based on the
|
||||
.BR dd (1p)
|
||||
utility as specified in POSIX. While character conversion may have been the
|
||||
original intent of
|
||||
.BR dd (1p),
|
||||
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
|
||||
|
||||
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>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
dd(1)
|
||||
.BR dd (1p)
|
||||
.BR lseek (3p)
|
||||
.BR mm (1)
|
||||
|
||||
36
docs/false.1
36
docs/false.1
@@ -1,35 +1,35 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
|
||||
.TH FALSE 1
|
||||
|
||||
.\"
|
||||
.TH FALSE 1 2024-06-06 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
false \(en do nothing, unsuccessfully
|
||||
|
||||
.\"
|
||||
.SH DESCRIPTION
|
||||
|
||||
False does nothing regardless of operands or standard input.
|
||||
False will always return an exit code of 1.
|
||||
|
||||
Do nothing regardless of operands or standard input. An exit code of 1 will
|
||||
always be returned.
|
||||
.\"
|
||||
.SH RATIONALE
|
||||
|
||||
False exists for the construction of control flow and loops based on a failure.
|
||||
|
||||
False functions as described in POSIX.1-2017.
|
||||
|
||||
In POSIX.1-2017,
|
||||
.BR false (1p)
|
||||
exists for the construction of control flow and loops based on a failure. This
|
||||
implementation functions as described in that standard.
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by Emma Tebibyte <emma@tebibyte.media>.
|
||||
|
||||
Written by Emma Tebibyte
|
||||
.MT emma@tebibyte.media
|
||||
.ME .
|
||||
.\"
|
||||
.SH COPYRIGHT
|
||||
|
||||
This work is marked with CC0 1.0. To see a copy of this license, visit
|
||||
<http://creativecommons.org/publicdomain/zero/1.0>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
true(1p)
|
||||
.BR true (1p)
|
||||
|
||||
62
docs/fop.1
Normal file
62
docs/fop.1
Normal file
@@ -0,0 +1,62 @@
|
||||
.\" 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 2024-06-17 "Harakit X.X.X"
|
||||
.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 data read from the standard input.
|
||||
.\"
|
||||
.SH OPTIONS
|
||||
|
||||
.IP \fB-d\fP\ \fIdelimiter\fP
|
||||
Sets a delimiter by which the input data will be split into fields. The default
|
||||
is an ASCII record separator.
|
||||
.\"
|
||||
.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 AUTHOR
|
||||
|
||||
Written by Emma Tebibyte
|
||||
.MT emma@tebibyte.media
|
||||
.ME .
|
||||
.\"
|
||||
.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)
|
||||
74
docs/hru.1
74
docs/hru.1
@@ -2,56 +2,68 @@
|
||||
.\"
|
||||
.\" 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 rpn 1
|
||||
|
||||
.\"
|
||||
.TH HRU 1 2024-06-17 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
hru \(en human readable units
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
hru
|
||||
|
||||
.\"
|
||||
.SH DESCRIPTION
|
||||
|
||||
Hru reads byte counts in the form of whole numbers from the standard input and
|
||||
writes to the standard output the same number converted one of the units of data
|
||||
defined by the International System of Units.
|
||||
Convert counts to higher units.
|
||||
|
||||
Byte counts will be read in the form of whole numbers from the standard input
|
||||
and be written to the standard output the same number converted to a higher unit
|
||||
of data as defined by the \fIInternational System of Units\fP.
|
||||
|
||||
The program will convert the byte count to the highest unit possible where the
|
||||
value is greater than one.
|
||||
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
If encountering non-integer characters in the standard input, hru will exit with
|
||||
the appropriate error code as defined by sysexits.h(3) and print an error
|
||||
message.
|
||||
|
||||
If encountering non-integer characters in the standard input, the program will
|
||||
exit with the appropriate error code as defined by
|
||||
.BR sysexits.h (3)
|
||||
and print an error message.
|
||||
.\"
|
||||
.SH RATIONALE
|
||||
|
||||
The GNU project’s ls(1) implementation contains a human-readable option (-h)
|
||||
that, when specified, makes the tool print size information in a format more
|
||||
immediately readable. This functionality is useful not only in the context of
|
||||
ls(1) so the decision was made to split it into a new tool. The original
|
||||
functionality in GNU’s ls(1) can be emulated with fop(1) combined with this
|
||||
program.
|
||||
|
||||
The GNU project\(cqs
|
||||
.BR ls (1)
|
||||
implementation contains a human-readable option (\fB-h\fP) that, when specified,
|
||||
makes the tool print size information in a format more immediately
|
||||
readable. This functionality is useful not only in this context, so the decision
|
||||
was made to split it into a new tool. The original functionality from GNU\(cqs
|
||||
.BR ls (1)
|
||||
can be emulated with
|
||||
.BR fop (1)
|
||||
combined with this program.
|
||||
.\"
|
||||
.SH STANDARDS
|
||||
|
||||
Hru follows the standard unit prefixes as specified by the Bureau International
|
||||
des Poids et Mesures (BIPM) in the ninth edition of The International System of
|
||||
Units (SI).
|
||||
|
||||
The standard unit prefixes as specified by the
|
||||
.I Bureau International des Poids et Mesures
|
||||
.RI ( BIPM )
|
||||
in the ninth edition of
|
||||
.I The International System of Units
|
||||
.RI ( SI )
|
||||
are utilized for the ouput of conversions.
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by Emma Tebibyte <emma@tebibyte.media>.
|
||||
|
||||
Written by Emma Tebibyte
|
||||
.MT emma@tebibyte.media
|
||||
.ME .
|
||||
.\"
|
||||
.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>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
GNU ls(1), The International System of Units (SI) 9th Edition
|
||||
GNU
|
||||
.BR ls (1),
|
||||
.I The International System of Units (SI) 9th Edition
|
||||
|
||||
127
docs/intcmp.1
127
docs/intcmp.1
@@ -1,78 +1,103 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
|
||||
.TH intcmp 1
|
||||
|
||||
.\"
|
||||
.TH INTCMP 1 2024-06-06 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
intcmp \(en compare integers
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
intcmp
|
||||
.RB ( -eghl )
|
||||
.RB [ integer ]
|
||||
.RB [ integer... ]
|
||||
|
||||
.RB [ -egl ]\ integer\ integer...
|
||||
.SH DESCRIPTION
|
||||
Compare integers to each other.
|
||||
.\"
|
||||
.SH OPTIONS
|
||||
|
||||
Intcmp compares integers.
|
||||
|
||||
.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
|
||||
infix algebraic “=”, “>”, and “<” operators respectively, with each option
|
||||
putting its symbol between every given integer. For example,
|
||||
.R intcmp -l 1 2 3
|
||||
is equivalent to evaluating "1 < 2 < 3".
|
||||
.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
|
||||
|
||||
It may help to think of the
|
||||
.BR -e ,
|
||||
.BR -g ,
|
||||
and
|
||||
.B -l
|
||||
options as equivalent to the infix algebraic \(lq=\(rq, \(lq>\(rq, and \(lq<\(rq
|
||||
operators respectively, with each option putting its symbol between every given
|
||||
integer. The following example is equivalent to evaluating \(lq1 < 2 < 3\(rq:
|
||||
\"
|
||||
.RS
|
||||
intcmp -l 1 2 3
|
||||
.RE
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
Intcmp exits 0 for a valid expression and 1 for an invalid expression.
|
||||
.PP
|
||||
Intcmp prints a debug message and exits with the appropriate sysexits(3) error
|
||||
code in the event of an error.
|
||||
The program will exit with a successfully for a valid expression and with an
|
||||
error code of 1 for an invalid expression.
|
||||
|
||||
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
|
||||
|
||||
There are multiple ways to express compound comparisons; “less than or equal
|
||||
to” can be -le or -el, for example.
|
||||
.PP
|
||||
The inequality comparison is -gl or -lg for “less than or greater than”; this
|
||||
is elegant but unintuitive.
|
||||
.PP
|
||||
-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.
|
||||
.BR -egl ,
|
||||
\(lqequal to or less than or greater than\(rq, always exits successfully for
|
||||
valid program usage and may be abused to function as an integer validator. Use
|
||||
.BR str (1)
|
||||
instead.
|
||||
.\"
|
||||
.SH CAVEATS
|
||||
|
||||
There are multiple ways to express compound comparisons; \(lqless than or equal
|
||||
to\(rq can be
|
||||
.B -le
|
||||
or
|
||||
.BR -el ,
|
||||
for example.
|
||||
|
||||
The inequality comparison is
|
||||
.B -gl
|
||||
.B or
|
||||
.B -lg
|
||||
for \(lqless than or greater than\(rq;
|
||||
this is elegant but unintuitive.
|
||||
.\"
|
||||
.SH RATIONALE
|
||||
|
||||
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.
|
||||
These parts of its functionality have been broken out into multiple utilities.
|
||||
|
||||
Strcmp’s functionality may be performed on a POSIX-compliant system with
|
||||
test(1p).
|
||||
been
|
||||
.BR test (1).
|
||||
This tool also handles string comparisons and file scrutiny. These parts of its
|
||||
functionality have been broken out into multiple utilities.
|
||||
|
||||
This program\(cqs functionality may be performed on a POSIX-compliant system
|
||||
with
|
||||
.BR test (1p).
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
Written by DTB
|
||||
.MT trinity@trinity.moe
|
||||
.ME .
|
||||
.\"
|
||||
.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>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
strcmp(1), scrut(1), str(1), test(1p)
|
||||
.BR scrut (1),
|
||||
.BR strcmp (1),
|
||||
.BR str (1),
|
||||
.BR test (1p)
|
||||
|
||||
103
docs/mm.1
103
docs/mm.1
@@ -2,75 +2,72 @@
|
||||
.\"
|
||||
.\" 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 mm 1
|
||||
|
||||
.\"
|
||||
.TH MM 1 2024-07-14 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
mm \(en middleman
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
mm
|
||||
.RB ( -aenu )
|
||||
.RB ( -i
|
||||
.RB [ input ])
|
||||
.RB ( -o
|
||||
.RB [ output ])
|
||||
|
||||
.RB [ -aetu ]
|
||||
.RB [ -i\ input ]
|
||||
.RB [ -o\ output ]
|
||||
.\"
|
||||
.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
|
||||
|
||||
Mm, upon receiving the
|
||||
.B -a
|
||||
option, will open subsequent outputs for appending rather than updating.
|
||||
.PP
|
||||
The
|
||||
.B -i
|
||||
option opens a path as an input. Without any inputs specified mm will use
|
||||
standard input. Standard input itself can be specified by giving the path '-'.
|
||||
.PP
|
||||
The
|
||||
.B -o
|
||||
option opens a path as an output. Without any outputs specified mm will use
|
||||
standard output. Standard output itself can be specified by giving the
|
||||
path '-'. Standard error itself can be specified with the
|
||||
.IP \fB-a\fP
|
||||
Opens outputs for appending rather than updating.
|
||||
.IP \fB-e\fP
|
||||
Use the standard error as an output.
|
||||
.IP \fB-t\fP
|
||||
Causes outputs to be overwritten instead of being truncated.
|
||||
.IP \fB-u\fP
|
||||
Ensures neither input or output will be buffered.
|
||||
.IP \fB-i\fP\ \fIinput\fP
|
||||
Opens a path as an input. If one or more of the input files is \(lq-\(rq or if
|
||||
no inputs are specified, the standard input shall be used. If specified as the
|
||||
last option and if there are trailing arguments to the program, they shall be
|
||||
appended to the list of files to use as inputs.
|
||||
.IP \fB-o\fP\ \fIoutput\fP
|
||||
Opens a path as an output. If one or more of the output files is \(lq-\(rq or if
|
||||
no outputs are specified and the
|
||||
.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.
|
||||
|
||||
option is not specified, the standard output shall be used. If specified as the
|
||||
last option and if there are trailing arguments to the program, they shall be
|
||||
appended to the list of files to use as outputs.
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
If an output can no longer be written mm prints a diagnostic message, ceases
|
||||
writing to that particular output, and if there are more outputs specified,
|
||||
continues, eventually exiting unsuccessfully.
|
||||
.PP
|
||||
On error mm prints a diagnostic message and exits with the appropriate
|
||||
sysexits.h(3) status.
|
||||
|
||||
.SH BUGS
|
||||
|
||||
Mm does not truncate existing files, which may lead to unexpected results.
|
||||
If an output cannot be written to, an error occurs; however, exiting will be
|
||||
deferred until writing to any other specified outputs completes.
|
||||
|
||||
When an error is encountered, a diagnostic message is printed and the program
|
||||
exits with the appropriate
|
||||
.BR sysexits.h (3)
|
||||
status.
|
||||
.\"
|
||||
.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
|
||||
|
||||
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>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
cat(1p), dd(1), dj(1), tee(1p)
|
||||
.BR cat (1p),
|
||||
.BR dd (1),
|
||||
.BR dj (1),
|
||||
.BR tee (1p)
|
||||
|
||||
80
docs/npc.1
80
docs/npc.1
@@ -1,68 +1,74 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
|
||||
.TH npc 1
|
||||
|
||||
.\"
|
||||
.TH NPC 1 2024-06-17 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
npc \(en show non-printing characters
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
npc
|
||||
.RB ( -eht )
|
||||
|
||||
.RB [ -et ]
|
||||
.\"
|
||||
.SH DESCRIPTION
|
||||
|
||||
Npc reads from standard input and writes to standard output, replacing non-
|
||||
printing characters with printable equivalents. Control characters print as 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-"
|
||||
Print normally non-printing characters.
|
||||
|
||||
The program reads from standard input and writes to standard output, replacing
|
||||
non-printing characters with printable equivalents. Control characters print as
|
||||
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
|
||||
high bit set.
|
||||
.PP
|
||||
The
|
||||
.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.
|
||||
.\"
|
||||
.SH OPTIONS
|
||||
|
||||
.IP \fB-e\fP
|
||||
Prints a dollar sign ('$') before each newline.
|
||||
.IP \fB-t\fP
|
||||
Prints tab characters as '^I' rather than a literal horizontal tab.
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
Npc prints a debug message and exits with the appropriate sysexits(3) error
|
||||
code in the event of an error, otherwise it exits successfully.
|
||||
|
||||
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
|
||||
|
||||
Npc operates in single-byte chunks regardless of intended encoding.
|
||||
|
||||
The program operates in single-byte chunks regardless of intended encoding.
|
||||
.\"
|
||||
.SH RATIONALE
|
||||
|
||||
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
|
||||
bandage solution GNU and other software suites use.
|
||||
|
||||
This functionality should be a separate tool because its usefulness extends
|
||||
beyond that of cat(1p).
|
||||
using a standard tool. A popular extension to
|
||||
.BR cat (1p),
|
||||
the
|
||||
.B -v
|
||||
option, is the bandage solution GNU and other software suites use.
|
||||
|
||||
This functionality is included in a separate tool because its usefulness extends
|
||||
beyond that of
|
||||
.BR cat (1p).
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
Written by DTB
|
||||
.MT trinity@trinity.moe
|
||||
.ME .
|
||||
.\"
|
||||
.SH COPYRIGHT
|
||||
|
||||
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
||||
<https://gnu.org/licenses/agpl.html>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
cat(1p), cat-v(1)
|
||||
|
||||
.BR cat (1p),
|
||||
.BR cat-v (1),
|
||||
.I UNIX Style, or cat -v Considered Harmful
|
||||
by Rob Pike
|
||||
|
||||
92
docs/rpn.1
92
docs/rpn.1
@@ -3,68 +3,84 @@
|
||||
.\"
|
||||
.\" 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 rpn 1
|
||||
|
||||
.\"
|
||||
.TH RPN 1 2024-06-17 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
rpn \(en reverse polish notation evaluation
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
rpn
|
||||
.RB [numbers...]\ [operators...]
|
||||
|
||||
.RB [ numbers... ]
|
||||
.RB [ operators... ]
|
||||
.\"
|
||||
.SH DESCRIPTION
|
||||
|
||||
Rpn evaluates reverse polish notation expressions either read from the standard
|
||||
input or parsed from provided arguments. See the STANDARD INPUT section.
|
||||
Evaluate reverse polish notation.
|
||||
|
||||
Upon evaluation, rpn will print the resulting number on the stack to the
|
||||
standard output. Any further specified numbers will be placed at the end of the
|
||||
The program evaluates reverse polish notation expressions read either from the
|
||||
standard input or parsed from provided arguments. See the STANDARD INPUT
|
||||
section.
|
||||
|
||||
Upon evaluation, the resulting number on the stack will be printed to the
|
||||
standard output. Any further numbers specified will be placed at the end of the
|
||||
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
|
||||
|
||||
If arguments are passed to rpn, it interprets them as an expression to be
|
||||
evaluated. Otherwise, it reads whitespace-delimited numbers and operations from
|
||||
If arguments are specified, they are interpreted as an expression to be
|
||||
evaluated. Otherwise, whitespace-delimited numbers and operations are read from
|
||||
the standard input.
|
||||
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
If encountering a syntax error, rpn will exit with the appropriate error code
|
||||
as defined by sysexits.h(3) and print 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; however, in the event of a syntax error, the program will print an
|
||||
error message and continue accepting input.
|
||||
.\"
|
||||
.SH CAVEATS
|
||||
|
||||
Due to precision constraints and the way floats are represented in accordance
|
||||
with the IEEE Standard for Floating Point Arithmetic (IEEE 754), floating-point
|
||||
arithmetic has rounding errors. This is somewhat curbed by using 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
|
||||
rpn can handle based on the platform and hardware of any given machine.
|
||||
|
||||
with the
|
||||
.I IEEE Standard for Floating Point Arithmetic
|
||||
(\fIIEEE 754\fP), floating-point arithmetic has rounding errors. This is
|
||||
somewhat curbed by using the machine epsilon as provided by the Rust standard
|
||||
library to which numbers are rounded. Because of this, variation is expected in
|
||||
the number of decimal places the program can handle based on the platform and
|
||||
hardware of any given machine.
|
||||
.\"
|
||||
.SH RATIONALE
|
||||
|
||||
An infix notation calculation utility, bc(1p), is included in the POSIX
|
||||
standard, but does not accept expressions as arguments; in scripts, any
|
||||
predefined, non-interactive input must be piped into the program. A dc(1)
|
||||
pre-dates the standardized 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.
|
||||
|
||||
An infix notation calculation utility,
|
||||
.BR bc (1p),
|
||||
is included in the POSIX standard, but does not accept expressions as arguments;
|
||||
in scripts, any predefined, non-interactive input must be piped into the
|
||||
program. A
|
||||
.BR dc (1)
|
||||
pre-dates the standardized
|
||||
.BR bc (1p),
|
||||
the latter originally being a preprocessor for the former, and was included in
|
||||
Second Edition UNIX and onward. While it implements reverse polish notation, it
|
||||
still suffers from being unable to accept an expression as an argument.
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by Emma Tebibyte <emma@tebibyte.media>.
|
||||
|
||||
Written by Emma Tebibyte
|
||||
.MT emma@tebibyte.media
|
||||
.ME .
|
||||
.\"
|
||||
.SH COPYRIGHT
|
||||
|
||||
Copyright (c) 2024 Emma Tebibyte. License AGPLv3+: GNU AGPL version 3 or later
|
||||
<https://gnu.org/licenses/agpl.html>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
bc(1p), dc(1), rpn(7), IEEE 754
|
||||
.BR bc (1p),
|
||||
.BR dc (1),
|
||||
.BR rpn (7),
|
||||
.I IEEE 754
|
||||
|
||||
127
docs/scrut.1
127
docs/scrut.1
@@ -1,93 +1,86 @@
|
||||
.\" 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 scrut 1
|
||||
|
||||
.\"
|
||||
.TH SCRUT 1 2024-06-06 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
scrut \(en scrutinize file properties
|
||||
|
||||
.SH SYNOPSIS
|
||||
|
||||
scrut
|
||||
.RB ( -bcdefgkprsuwxLS )
|
||||
.RB [ file... ]
|
||||
|
||||
.RB [ -LSbcdefgkprsuwx ]
|
||||
.B file...
|
||||
.\"
|
||||
.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
|
||||
|
||||
.B -b
|
||||
requires the given files to exist and be block special files.
|
||||
.PP
|
||||
.B -c
|
||||
requires the given files to exist and be character special files.
|
||||
.PP
|
||||
.B -d
|
||||
requires the given files to exist and be directories.
|
||||
.PP
|
||||
.B -e
|
||||
requires the given files to exist, and is redundant to any other option.
|
||||
.PP
|
||||
.B -e
|
||||
requires the given files to exist and be regular files.
|
||||
.PP
|
||||
.B -g
|
||||
requires the given files to exist and have their set group ID flags set.
|
||||
.PP
|
||||
.B -k
|
||||
requires the given files to exist and have their sticky bit set.
|
||||
.PP
|
||||
.B -p
|
||||
requires the given files to exist and be named pipes.
|
||||
.PP
|
||||
.B -r
|
||||
requires the given files to exist and be readable.
|
||||
.PP
|
||||
.B -u
|
||||
requires the given files to exist and have their set user ID flags set.
|
||||
.PP
|
||||
.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.
|
||||
.IP \fB-L\fB
|
||||
Requires the given files to exist and be symbolic links.
|
||||
.IP \fB-S\fP
|
||||
Requires the given files to exist and be sockets.
|
||||
.IP \fB-b\fP
|
||||
Requires the given files to exist and be block special files.
|
||||
.IP \fB-c\fP
|
||||
Requires the given files to exist and be character special files.
|
||||
.IP \fB-d\fP
|
||||
Requires the given files to exist and be directories.
|
||||
.IP \fB-e\fP
|
||||
Requires the given files to exist, and is redundant to any other option.
|
||||
.IP \fB-f\fP
|
||||
Requires the given files to exist and be regular files.
|
||||
.IP \fB-g\fP
|
||||
Requires the given files to exist and have their set group ID flags set.
|
||||
.IP \fB-k\fP
|
||||
Requires the given files to exist and have their sticky bit set.
|
||||
.IP \fB-p\fP
|
||||
Requires the given files to exist and be named pipes.
|
||||
.IP \fB-r\fP
|
||||
Requires the given files to exist and be readable.
|
||||
.IP \fB-u\fP
|
||||
Requires the given files to exist and have their set user ID flags set.
|
||||
.IP \fB-w\fP
|
||||
Requires the given files to exist and be writable.
|
||||
.IP \fB-x\fP
|
||||
Requires the given files to exist and be executable.
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
.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
|
||||
sysexits.h(3) error code if invoked incorrectly. Scrut exits successfully if
|
||||
the given files comply with their requirements and unsuccessfully otherwise.
|
||||
|
||||
.SH STANDARDS
|
||||
|
||||
Scrut is nearly compatible with POSIX's test utility though it is narrower in
|
||||
scope. Notably, the
|
||||
The
|
||||
.BR test (1p)
|
||||
utility contains functionality that was broken out into separate programs. Thus,
|
||||
the scope of this program is narrower than it. Notably, the
|
||||
.B -h
|
||||
option is now invalid and therefore shows usage information instead of being an
|
||||
alias to the modern
|
||||
.B -L
|
||||
option.
|
||||
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
Written by DTB
|
||||
.MT trinity@trinity.moe
|
||||
.ME .
|
||||
.\"
|
||||
.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>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
access(3p), lstat(3p), test(1p)
|
||||
.BR access (3p),
|
||||
.BR lstat (3p),
|
||||
.BR test (1p)
|
||||
|
||||
@@ -1,62 +1,75 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
|
||||
.TH STRCMP 1
|
||||
|
||||
.\"
|
||||
.TH STRCMP 1 2024-07-15 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
strcmp \(en compare strings
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
strcmp
|
||||
.RM [ string ]
|
||||
.RB [ strings... ]
|
||||
|
||||
.B string string...
|
||||
.\"
|
||||
.SH DESCRIPTION
|
||||
|
||||
Strcmp checks whether the given strings 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
|
||||
).
|
||||
|
||||
Check whether string arguments are the same.
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
Strcmp will print an error message and exit unsuccessfully with a status
|
||||
described in sysexits(3) if used incorrectly (given less than two operands).
|
||||
The program will exit successfully if the strings are identical. Otherwise, it
|
||||
will exit with an error code less than 128 if a string passed has a lesser byte
|
||||
value than one of the prior strings:
|
||||
|
||||
.SH UNICODE
|
||||
.RS
|
||||
strcmp b a
|
||||
.RE
|
||||
|
||||
Strcmp will exit unsuccessfully if the given strings are not identical;
|
||||
Unicode strings may need to be normalized if the intent is to check visual
|
||||
similarity and not byte similarity.
|
||||
or with an error code greater than 128 if it has a greater byte value than one
|
||||
of the prior strings:
|
||||
|
||||
.RS
|
||||
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
|
||||
|
||||
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.
|
||||
These parts of its functionality have been broken out into multiple utilities.
|
||||
|
||||
Strcmp’s functionality may be performed on a POSIX-compliant system with
|
||||
test(1p).
|
||||
been
|
||||
.BR test (1).
|
||||
This tool also handles integer comparisons and file scrutiny. These parts of its
|
||||
functionality have been broken out into multiple utilities.
|
||||
|
||||
This program\(cqs functionality may be performed on a POSIX-compliant system
|
||||
with
|
||||
.BR test (1p).
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB <trinity@trinity.moe>.
|
||||
|
||||
Written by DTB
|
||||
.MT trinity@trinity.moe
|
||||
.ME .
|
||||
.\"
|
||||
.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>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
strcmp(3), intcmp(1), scrut(1), test(1p)
|
||||
.BR strcmp (3),
|
||||
.BR intcmp (1),
|
||||
.BR scrut (1),
|
||||
.BR test (1p)
|
||||
|
||||
94
docs/swab.1
94
docs/swab.1
@@ -1,71 +1,75 @@
|
||||
.\" 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 swab 1
|
||||
|
||||
.\"
|
||||
.TH SWAB 1 2024-06-17 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
swab \(en swap bytes
|
||||
|
||||
.\"
|
||||
.SH SYNOPSIS
|
||||
|
||||
swab
|
||||
.RB ( -f )
|
||||
.RB ( -w
|
||||
.R [
|
||||
.B word size
|
||||
.R ])
|
||||
.RB [ -w\ word_size ]
|
||||
.\"
|
||||
.SH DESCRIPTION
|
||||
|
||||
.SH USAGE
|
||||
|
||||
Swab swaps the latter and former halves of a block of bytes.
|
||||
Swap the latter and former halves of a block of bytes.
|
||||
.\"
|
||||
.SH OPTIONS
|
||||
|
||||
.IP \fB-w\fP\ \fIword_size\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
|
||||
|
||||
The following sh(1p) line:
|
||||
The following
|
||||
.BR sh (1p)
|
||||
line:
|
||||
|
||||
.R printf 'hello world!\n' | swab
|
||||
.RS
|
||||
printf 'hello world!\(rsn' | swab
|
||||
.RE
|
||||
.\" If you change this, make sure to change it in tests/bonsai/swab.mk too.
|
||||
|
||||
Produces the following output:
|
||||
|
||||
.R ehll oowlr!d
|
||||
|
||||
.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.
|
||||
|
||||
.RS
|
||||
ehll oowlr!d
|
||||
.RE
|
||||
.\"
|
||||
.SH DIAGNOSTICS
|
||||
|
||||
If an error is encountered in input, output, or invocation, a diagnostic
|
||||
message will be written to standard error and swab will exit with the
|
||||
appropriate status from sysexits.h(3).
|
||||
|
||||
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 RATIONALE
|
||||
|
||||
Swab was modeled after the
|
||||
.R conv=swab
|
||||
functionality specified in the POSIX dd utility but additionally allows the
|
||||
word size to be configured.
|
||||
.PP
|
||||
Swab is useful for fixing the endianness of binary files produced on other
|
||||
machines.
|
||||
This program was modeled and named after the
|
||||
.B conv=swab
|
||||
functionality specified
|
||||
in the
|
||||
.BR dd (1p)
|
||||
utility. It additionally allows the word size to be configured.
|
||||
|
||||
This functionality is useful for fixing the endianness of binary files produced
|
||||
on other machines.
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by DTB
|
||||
.MT trinity@trinity.moe
|
||||
.ME .
|
||||
.\"
|
||||
.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>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
dd(1p)
|
||||
.BR dd (1p)
|
||||
|
||||
37
docs/true.1
37
docs/true.1
@@ -1,35 +1,36 @@
|
||||
.\" 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,
|
||||
.\" visit <http://creativecommons.org/licenses/by-sa/4.0/>.
|
||||
|
||||
.TH TRUE 1
|
||||
|
||||
.\"
|
||||
.TH TRUE 1 2024-06-06 "Harakit X.X.X"
|
||||
.SH NAME
|
||||
|
||||
true \(en do nothing, successfully
|
||||
|
||||
.\"
|
||||
.SH DESCRIPTION
|
||||
|
||||
True does nothing regardless of operands or standard input.
|
||||
True will always return an exit code of 0.
|
||||
|
||||
Do nothing regardless of operands or standard input. An exit code of 0 will
|
||||
always be returned.
|
||||
.\"
|
||||
.SH RATIONALE
|
||||
|
||||
True exists for the construction of control flow and loops based on a success.
|
||||
|
||||
True functions as described in POSIX.1-2017.
|
||||
|
||||
In \fIPOSIX.1-2017\fP,
|
||||
.BR true (1p)
|
||||
exists for the construction of control flow and loops based on a success. This
|
||||
implementation functions as described in that standard.
|
||||
.\"
|
||||
.SH AUTHOR
|
||||
|
||||
Written by Emma Tebibyte <emma@tebibyte.media>.
|
||||
|
||||
Written by Emma Tebibyte
|
||||
.MT emma@tebibyte.media
|
||||
.ME .
|
||||
.\"
|
||||
.SH COPYRIGHT
|
||||
|
||||
This work is marked with CC0 1.0. To see a copy of this license, visit
|
||||
<http://creativecommons.org/publicdomain/zero/1.0>.
|
||||
|
||||
.\"
|
||||
.SH SEE ALSO
|
||||
|
||||
false(1p)
|
||||
.BR false (1p),
|
||||
.BR true (1p)
|
||||
|
||||
Reference in New Issue
Block a user