195 lines
4.0 KiB
Groff
195 lines
4.0 KiB
Groff
.\" 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 USAGE
|
||
|
||
.B -A
|
||
.RS
|
||
Takes no arguments and pads with nuls.
|
||
.RE
|
||
|
||
.B -B
|
||
.RS
|
||
Does the same as
|
||
.B -b
|
||
but for the output buffer.
|
||
.RE
|
||
|
||
.B -H
|
||
.RS
|
||
Prints diagnostics messages in an alternate 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
|
||
that byte in the event that a read doesn’t fill the input buffer, and the
|
||
.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.
|
||
.RE
|
||
|
||
.B -i
|
||
.RS
|
||
Takes a path as an argument to open and use in place of standard input.
|
||
.RE
|
||
|
||
.B -n
|
||
.RS
|
||
Causes dj to exit on two consecutive empty reads instead of one.
|
||
.RE
|
||
|
||
.B -o
|
||
.RS
|
||
Does the same as
|
||
.B -i
|
||
but in place of standard output. Dj does not truncate output
|
||
files and instead writes over the bytes in the existing file.
|
||
.RE
|
||
|
||
.B -s
|
||
.RS
|
||
Takes a numeric argument as the number of bytes to skip into the input
|
||
before starting to read.
|
||
.RE
|
||
|
||
.B -q
|
||
.RS
|
||
Suppresses error messages which print when a read or write is partial or
|
||
empty. When
|
||
.B -q
|
||
is specified twice suppresses diagnostic output entirely.
|
||
.RE
|
||
|
||
.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, dj instead uses the following format:
|
||
|
||
.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 dj’s read-write cycle, a
|
||
diagnostic message is printed and dj 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 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 © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
||
<https://gnu.org/licenses/agpl.html>.
|
||
|
||
.SH SEE ALSO
|
||
|
||
dd(1p)
|