document

dj/dj.1

@@ -0,0 +1,158 @@
+.TH dj 1
+
+.SH NAME
+
+dj \(en disk jockey
+
+.SH SYNOPSIS
+
+dj
+.RB ( -AfHqQ )
+.RB ( -a
+.RB [ byte ])
+.RB ( -c
+.RB [ count ])
+
+.RB ( -i
+.R [
+.B input file
+.R ])
+.RB ( -b
+.R [
+.B input block size
+.R ])
+.RB ( -s
+.R [
+.B input offset
+.R ])
+
+.RB ( -o
+.R [
+.B output file
+.R ])
+.RB ( -B
+.R [
+.B output block size
+.R ])
+.RB ( -S
+.R [
+.B output offset
+.R ])
+
+.SH USAGE
+
+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
+or
+.B -Q
+options are specified) and exits (unless the
+.B -f
+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. The
+.B -H
+option will make these diagnostics human-readable.
+
+.SH DIAGNOSTICS
+
+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 this output entirely.
+.PP
+The
+.B -q
+and
+.B -Q
+options suppress error messages which print when a read or write is partial or
+empty.
+.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.
+
+.SH BUGS
+
+If
+.B -f
+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
+.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.
+
+.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.
+
+.SH COPYRIGHT
+
+Copyright (C) 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
+<https://gnu.org/licenses/agpl.html>.
+
+.SH SEE ALSO
+
+dd(1)