190 lines
5.6 KiB
Groff
190 lines
5.6 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 2024-06-17 "Bonsai Core Utilites 0.13.11"
|
|
.SH NAME
|
|
dj \(en disk jockey
|
|
.\"
|
|
.SH SYNOPSIS
|
|
|
|
dj
|
|
.RB ( -AdHnq )
|
|
.RB ( -a
|
|
.RB [ byte ])
|
|
.RB ( -c
|
|
.RB [ count ])
|
|
|
|
.RB ( -i
|
|
[\fBinput file\fP])
|
|
.RB ( -b
|
|
[\fBinput block size\fP])
|
|
.RB ( -s
|
|
[\fBinput offset\fP])
|
|
|
|
.RB ( -o
|
|
[\fBoutput file\fP])
|
|
.RB ( -B
|
|
[\fBoutput block size\fP])
|
|
.RB ( -S
|
|
[\fBoutput offset\fP])
|
|
.\"
|
|
.SH DESCRIPTION
|
|
|
|
Perform precise read and write operations on files. This utility is useful for
|
|
reading and writing binary data to and from disks.
|
|
|
|
This manual page uses the terms \(lqskip\(rq and \(lqseek\(rq to refer to moving
|
|
to a specified byte by index in the input and output of the program
|
|
respectively. This language is inherited from the
|
|
.BR dd (1p)
|
|
utility and used here to decrease ambiguity.
|
|
|
|
When seeking or skipping to a byte, writing or reading starts at the byte
|
|
immediately subsequent to the specified byte.
|
|
.\"
|
|
.SH OPTIONS
|
|
|
|
.IP \fB-i\fP
|
|
Takes a file path as an argument and opens it for use as an input.
|
|
.IP \fB-b\fP
|
|
Takes a numeric argument as the size in bytes of the input buffer, the default
|
|
being 1024.
|
|
.IP \fB-s\fP
|
|
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.
|
|
.IP \fB-o\fP
|
|
Takes a file path as an argument and opens it for use as an output.
|
|
.IP \fB-B\fP
|
|
Does the same as
|
|
.B -b
|
|
but for the output buffer.
|
|
.IP \fB-S\fP
|
|
Seeks a number of bytes through the output before starting to write from
|
|
the input. If the output is a stream, null characters are printed.
|
|
.IP \fB-a\fP
|
|
Accepts a single literal byte with which the input buffer is padded in the event
|
|
of an incomplete read from the input file.
|
|
.IP \fB-A\fP
|
|
Specifying this option pads the input buffer with null bytes in the event of an
|
|
incomplete read. This is equivalent to specifying
|
|
.B -a
|
|
with a null byte instead of a character.
|
|
.IP \fB-c\fP
|
|
Specifies a number of reads to make. The default is 0, in which case the
|
|
input is read until a partial or empty read is made.
|
|
.IP \fB-d\fP
|
|
Prints invocation information before program execution as described in the
|
|
DIAGNOSTICS section. Each invocation increments the debug level of the
|
|
program.
|
|
.IP \fB-H\fP
|
|
Prints diagnostics messages in a human-readable manner as described in the
|
|
DIAGNOSTICS section.
|
|
.IP \fB-n\fP
|
|
Retries failed reads once before exiting.
|
|
.IP \fB-q\fP
|
|
Suppresses error messages which print when a read or write is partial or
|
|
empty. Each invocation decrements the debug level of the program.
|
|
.\"
|
|
.SH STANDARD INPUT
|
|
|
|
The standard input shall be used as an input if no inputs are specified or if
|
|
one or more of the input files is \(lq-\(rq.
|
|
.\"
|
|
.SH STANDARD OUTPUT
|
|
The standard output shall be used as an output if no inputs are specified or if
|
|
one or more of the input files is \(lq-\(rq.
|
|
.\"
|
|
.SH DIAGNOSTICS
|
|
|
|
On a partial or empty read, unless the
|
|
.B -q
|
|
option is specified, a diagnostic message is printed. Then, the program 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
|
|
{records read} {ASCII unit separator} {partial records read}
|
|
{ASCII record separator} {records written} {ASCII unit separator}
|
|
{partial records written} {ASCII group separator} {bytes read}
|
|
{ASCII record separator} {bytes written} {ASCII file separator}
|
|
.RE
|
|
|
|
This format for diagnostic output is designed to be machine-parseable for
|
|
convenience. For a more human-readable format, the
|
|
.B -H
|
|
option may be specified. In this event, the following format is used instead:
|
|
|
|
.RS
|
|
{records read} '+' {partial records read} '>' {records written}
|
|
'+' {partial records written} ';' {bytes read} '>' {bytes written}
|
|
{ASCII line feed}
|
|
.RE
|
|
|
|
If the
|
|
.B -d
|
|
option is specified, debug information will be printed at the beginning of
|
|
execution. This output 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
|
|
argv0=dj
|
|
in=<stdin> ibs=1024 skip=0 align=ff count=0
|
|
out=<stdout> obs=1024 seek=0 debug= 3 noerror=0
|
|
.RE
|
|
|
|
In non-recoverable errors that don\(cqt pertain to the read-write cycle, a
|
|
diagnostic message is printed and the program exits with the appropriate
|
|
.BR sysexits.h (3)
|
|
status.
|
|
.\"
|
|
.SH BUGS
|
|
|
|
If
|
|
.B -n
|
|
is specified along with the
|
|
.B -c
|
|
option and a count, actual byte output is the product of the count and the input
|
|
block size and therefore may be lower than expected. If the
|
|
.B -a
|
|
or
|
|
.B -A
|
|
options are specified, this could make written data nonsensical.
|
|
.\"
|
|
.SH CAVEATS
|
|
|
|
Existing files are not truncated on ouput and are instead overwritten.
|
|
|
|
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
|
|
|
|
This program was based on the
|
|
.BR dd (1p)
|
|
utility as specified in POSIX. While character conversion may have been the
|
|
original intent of
|
|
.BR dd (1p),
|
|
it is irrelevant to its modern use. Because of this, this program 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\(cqs easy for machines to parse.
|
|
.\"
|
|
.SH COPYRIGHT
|
|
|
|
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
|
<https://gnu.org/licenses/agpl.html>.
|
|
.\"
|
|
.SH SEE ALSO
|
|
.BR dd (1p)
|