overgrown/docs/dj.1

.\" 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

.SH NAME

dj \(en disk jockey

.SH SYNOPSIS

dj
.RB ( -AdHnq )
.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 OPTIONS

.B -A
.RS
If the output is a stream, nul bytes are printed. In other words, it does what
.B -a
does but with null bytes instead.
.RE

.B -B
.RS
Does the same as
.B -b
but for the output buffer.
.RE

.B -H
.RS
Prints diagnostics messages in a human-readable manner as described in the
DIAGNOSTICS section below.
.RE

.B -S
.RS
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.
.RE

.B -a
.RS
Takes one argument of one byte in length and pads the input buffer with it in
the event of an incomplete read from the input file.
.RE

.B -b
.RS
Takes a numeric argument as the size in bytes of the input buffer, with the
default being 1024 bytes or one kibibyte (KiB).
.RE

.B -c
.RS
Specifies an amount of reads to make, and if 0 (the default) dj will
continue reading until a partial or empty read.
.RE

.B -d
.RS
Prints all debug information, user-specified or otherwise, before program
execution. Each invocation increments the debug level of the program.
.RE

.B -i
.RS
Takes a file path as an argument to open and use as an input.
.RE

.B -n
.RS
Retries failed reads once more before exiting.
.RE

.B -o
.RS
Takes a file path as an argument to open and use as an output.
.RE

.B -s
.RS
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.
.RE

.B -q
.RS
Suppresses error messages which print when a read or write is partial or
empty. Each invocation decrements the debug level of the program.
.RE

.SH STANDARD INPUT

The standard input shall be used as an input if one or more of the input files
is “-”.

.SH DIAGNOSTICS

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.

By default statistics are printed for input and output to the standard error in
the following format:

.RS
.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}
.RE

If the
.B -H
option is specified, the following format is used instead:

.RS
.R {records read} '+' {partial records read} '>' {records written}
.R '+' {partial records written} ';' {bytes read} '>' {bytes written}
.R {ASCII line feed}
.RE

In non-recoverable errors that don’t pertain to the read-write cycle, a
diagnostic message is printed and the program exits with the appropriate
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
.B -a
or
.B -A
options are used this could make data written nonsensical.

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 CAVEATS

Existing files are not truncated on ouput and are instead overwritten.

.SH RATIONALE

This program was based on the dd(1p) utility as specified in POSIX. While
character conversion may have been the original intent of dd(1p), it is
irrelevant to its modern use. Because of this, it 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’s easy to parse for machines.

.SH COPYRIGHT

Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.

.SH SEE ALSO

dd(1p)