document
This commit is contained in:
parent
428a56eaad
commit
3bc4e01b35
158
dj/dj.1
Normal file
158
dj/dj.1
Normal file
@ -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)
|
Loading…
Reference in New Issue
Block a user