2024-01-18 04:03:09 +00:00
|
|
|
|
.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
|
2024-01-18 04:03:09 +00:00
|
|
|
|
.\"
|
|
|
|
|
.\" 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/>.
|
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.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 ])
|
|
|
|
|
|
2024-03-27 05:58:00 +00:00
|
|
|
|
.SH OPTIONS
|
2024-01-10 06:43:45 +00:00
|
|
|
|
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.B -A
|
|
|
|
|
.RS
|
2024-03-29 22:17:48 +00:00
|
|
|
|
If the output is a stream, null bytes are printed. In other words, it does what
|
2024-03-27 05:58:00 +00:00
|
|
|
|
.B -a
|
|
|
|
|
does but with null bytes instead.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.B -B
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RS
|
|
|
|
|
Does the same as
|
|
|
|
|
.B -b
|
|
|
|
|
but for the output buffer.
|
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.B -H
|
|
|
|
|
.RS
|
2024-03-27 06:09:17 +00:00
|
|
|
|
Prints diagnostics messages in a human-readable manner as described in the
|
2024-03-27 00:26:51 +00:00
|
|
|
|
DIAGNOSTICS section below.
|
|
|
|
|
.RE
|
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.B -S
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RS
|
|
|
|
|
Skips a number of bytes through the output before starting to write from
|
2024-01-10 06:43:45 +00:00
|
|
|
|
the input. If the input is a stream the bytes are read and discarded. If the
|
2024-03-29 22:17:48 +00:00
|
|
|
|
output is a stream, null characters are printed.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.B -a
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RS
|
2024-03-27 05:58:00 +00:00
|
|
|
|
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.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.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
|
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.B -c
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RS
|
|
|
|
|
Specifies an amount of reads to make, and if 0 (the default) dj will
|
2024-01-10 06:43:45 +00:00
|
|
|
|
continue reading until a partial or empty read.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.B -d
|
|
|
|
|
.RS
|
2024-03-29 22:14:27 +00:00
|
|
|
|
Prints invocation information before program execution as described in the
|
|
|
|
|
DIAGNOSTICS section below. Each invocation increments the debug level of the
|
|
|
|
|
program.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.B -i
|
|
|
|
|
.RS
|
2024-03-27 06:08:43 +00:00
|
|
|
|
Takes a file path as an argument to open and use as an input.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.B -n
|
|
|
|
|
.RS
|
2024-03-27 06:08:43 +00:00
|
|
|
|
Retries failed reads once more before exiting.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.B -o
|
|
|
|
|
.RS
|
2024-03-27 06:08:43 +00:00
|
|
|
|
Takes a file path as an argument to open and use as an output.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.B -s
|
|
|
|
|
.RS
|
|
|
|
|
Takes a numeric argument as the number of bytes to skip into the input
|
2024-03-27 06:08:43 +00:00
|
|
|
|
before starting to read. If the standard input is used, bytes read to this point
|
|
|
|
|
are discarded.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.B -q
|
|
|
|
|
.RS
|
|
|
|
|
Suppresses error messages which print when a read or write is partial or
|
2024-03-27 06:08:43 +00:00
|
|
|
|
empty. Each invocation decrements the debug level of the program.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
2024-03-27 06:08:43 +00:00
|
|
|
|
.SH STANDARD INPUT
|
|
|
|
|
|
2024-03-29 22:21:02 +00:00
|
|
|
|
The standard input shall be used as an input if no inputs are specified one or
|
|
|
|
|
more of the input files is “-”.
|
2024-03-27 06:08:43 +00:00
|
|
|
|
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.SH DIAGNOSTICS
|
|
|
|
|
|
2024-03-29 22:14:27 +00:00
|
|
|
|
On a partial or empty read, a diagnostic message is printed (unless the
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.B -q
|
2024-03-29 22:14:27 +00:00
|
|
|
|
option is specified) and the program exits (unless the
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.B -n
|
2024-03-27 00:26:51 +00:00
|
|
|
|
option is specified.
|
2024-01-10 06:43:45 +00:00
|
|
|
|
|
2024-03-27 00:26:51 +00:00
|
|
|
|
By default statistics are printed for input and output to the standard error in
|
|
|
|
|
the following format:
|
2024-01-10 06:43:45 +00:00
|
|
|
|
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RS
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.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}
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
If the
|
|
|
|
|
.B -H
|
2024-03-27 01:22:30 +00:00
|
|
|
|
option is specified, the following format is used instead:
|
2024-03-27 00:26:51 +00:00
|
|
|
|
|
|
|
|
|
.RS
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.R {records read} '+' {partial records read} '>' {records written}
|
|
|
|
|
.R '+' {partial records written} ';' {bytes read} '>' {bytes written}
|
|
|
|
|
.R {ASCII line feed}
|
2024-03-27 00:26:51 +00:00
|
|
|
|
.RE
|
|
|
|
|
|
2024-03-29 22:14:27 +00:00
|
|
|
|
If the
|
|
|
|
|
.B -d
|
|
|
|
|
option is specified, debug output will be printed at the beginning of execution.
|
|
|
|
|
This debug information contains information regarding how the program was
|
|
|
|
|
invoked. The following example is the result of running the program with
|
|
|
|
|
.B -d
|
|
|
|
|
as the only argument:
|
|
|
|
|
|
|
|
|
|
.RS
|
|
|
|
|
.R argv0=dj
|
|
|
|
|
.R in=<stdin> ibs=1024 skip=0 align=ff count=0
|
|
|
|
|
.R out=<stdout> obs=1024 seek=0 debug= 3 noerror=0
|
|
|
|
|
.RE
|
|
|
|
|
|
2024-03-27 01:22:30 +00:00
|
|
|
|
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.
|
2024-01-10 06:43:45 +00:00
|
|
|
|
|
|
|
|
|
.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.
|
2024-03-27 00:26:51 +00:00
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
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.
|
|
|
|
|
|
2024-03-27 06:08:43 +00:00
|
|
|
|
.SH CAVEATS
|
|
|
|
|
|
2024-03-27 06:14:02 +00:00
|
|
|
|
Existing files are not truncated on ouput and are instead overwritten.
|
2024-03-27 06:08:43 +00:00
|
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
|
.SH RATIONALE
|
|
|
|
|
|
2024-03-27 05:53:10 +00:00
|
|
|
|
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.
|
2024-01-10 06:43:45 +00:00
|
|
|
|
|
|
|
|
|
.SH COPYRIGHT
|
|
|
|
|
|
2024-03-27 00:26:51 +00:00
|
|
|
|
Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
2024-01-10 06:43:45 +00:00
|
|
|
|
<https://gnu.org/licenses/agpl.html>.
|
|
|
|
|
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
|
|
2024-03-27 00:26:51 +00:00
|
|
|
|
dd(1p)
|