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-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-07-04 00:30:54 +00:00
|
|
|
.TH DJ 1 2024-07-03 "Harakit X.X.X"
|
2024-01-10 06:43:45 +00:00
|
|
|
.SH NAME
|
|
|
|
dj \(en disk jockey
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-01-10 06:43:45 +00:00
|
|
|
.SH SYNOPSIS
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
dj
|
2024-06-30 01:23:03 +00:00
|
|
|
.RB [ -Hn ]
|
2024-06-29 11:18:20 +00:00
|
|
|
.RB [ -a\ byte ]
|
|
|
|
.RB [ -c\ count ]
|
2024-01-10 06:43:45 +00:00
|
|
|
|
2024-06-29 11:28:23 +00:00
|
|
|
.RB [ -i\ file ]
|
|
|
|
.RB [ -b\ block_size ]
|
|
|
|
.RB [ -s\ offset ]
|
2024-01-10 06:43:45 +00:00
|
|
|
|
2024-06-29 11:28:23 +00:00
|
|
|
.RB [ -o\ file ]
|
|
|
|
.RB [ -B\ block_size ]
|
|
|
|
.RB [ -S\ offset ]
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-06-05 23:15:42 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
|
|
|
|
Perform precise read and write operations on files. This utility is useful for
|
2024-06-18 05:36:52 +00:00
|
|
|
reading and writing binary data to and from disks.
|
2024-06-05 23:15:42 +00:00
|
|
|
|
|
|
|
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)
|
2024-06-18 05:36:52 +00:00
|
|
|
utility and used here to decrease ambiguity.
|
2024-06-05 23:18:21 +00:00
|
|
|
|
2024-07-04 00:30:54 +00:00
|
|
|
The offset used when skipping or seeking refers to how many bytes are skipped
|
|
|
|
or sought. Running
|
|
|
|
.BR dj (1)
|
|
|
|
with a skip offset of 1 skips one byte into the input and reads from the second
|
|
|
|
byte onwards. A programmer may think of a file as a zero-indexed array of
|
|
|
|
bytes; in this analogy, the offset given is the index of the byte at which to
|
|
|
|
start reading or writing.
|
|
|
|
|
2024-07-05 03:05:15 +00:00
|
|
|
Seeks aren\(cqt counted in the output statistics because they\(cqre guaranteed
|
|
|
|
to succeed (or the utility will exit unsuccessfully, before it has written any
|
|
|
|
data).
|
2024-06-05 23:15:42 +00:00
|
|
|
.\"
|
2024-03-27 05:58:00 +00:00
|
|
|
.SH OPTIONS
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-06-29 11:28:23 +00:00
|
|
|
.IP \fB-i\fP\ \fIfile\fP
|
2024-05-24 16:03:52 +00:00
|
|
|
Takes a file path as an argument and opens it for use as an input.
|
2024-06-29 11:28:23 +00:00
|
|
|
.IP \fB-b\fP\ \fIblock_size\fP
|
2024-06-18 05:36:52 +00:00
|
|
|
Takes a numeric argument as the size in bytes of the input buffer, the default
|
|
|
|
being 1024.
|
2024-06-03 00:47:14 +00:00
|
|
|
.IP \fB-s\fP
|
2024-06-30 01:14:08 +00:00
|
|
|
Takes a numeric argument as the index of the byte at which reading will
|
|
|
|
commence; \(lqskips\(rq that number of bytes. If the standard input is used,
|
|
|
|
bytes read to this point are discarded.
|
2024-06-03 00:47:14 +00:00
|
|
|
.IP \fB-o\fP
|
2024-05-24 16:06:15 +00:00
|
|
|
Takes a file path as an argument and opens it for use as an output.
|
2024-06-29 11:28:23 +00:00
|
|
|
.IP \fB-B\fP\ \fIblock_size\fP
|
2024-03-27 00:26:51 +00:00
|
|
|
Does the same as
|
|
|
|
.B -b
|
|
|
|
but for the output buffer.
|
2024-06-03 00:47:14 +00:00
|
|
|
.IP \fB-S\fP
|
2024-06-30 01:14:08 +00:00
|
|
|
Takes a numeric argument as the index of the byte at which writing will
|
|
|
|
commence; \(lqseeks\(rq that number of bytes. If the standard output is used,
|
|
|
|
null characters are printed.
|
2024-06-03 00:47:14 +00:00
|
|
|
.IP \fB-a\fP
|
2024-06-18 05:36:52 +00:00
|
|
|
Accepts a single literal byte with which the input buffer is padded in the event
|
2024-06-26 19:45:36 +00:00
|
|
|
of an incomplete read from the input file. If the option argument is empty, the
|
|
|
|
null byte is used.
|
2024-06-03 00:47:14 +00:00
|
|
|
.IP \fB-c\fP
|
2024-06-18 05:36:52 +00:00
|
|
|
Specifies a number of reads to make. The default is 0, in which case the
|
2024-05-24 16:13:59 +00:00
|
|
|
input is read until a partial or empty read is made.
|
2024-06-03 00:47:14 +00:00
|
|
|
.IP \fB-H\fP
|
2024-06-29 11:55:29 +00:00
|
|
|
Prints diagnostic messages in a human-readable manner as described in the
|
2024-06-18 05:36:52 +00:00
|
|
|
DIAGNOSTICS section.
|
2024-06-03 00:47:14 +00:00
|
|
|
.IP \fB-n\fP
|
2024-06-18 05:36:52 +00:00
|
|
|
Retries failed reads once before exiting.
|
2024-06-05 23:15:42 +00:00
|
|
|
.\"
|
2024-03-27 06:08:43 +00:00
|
|
|
.SH STANDARD INPUT
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-05-24 16:14:53 +00:00
|
|
|
The standard input shall be used as an input if no inputs are specified or if
|
2024-06-30 01:14:08 +00:00
|
|
|
input file is \(lq-\(rq.
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-06-18 05:36:52 +00:00
|
|
|
.SH STANDARD OUTPUT
|
|
|
|
The standard output shall be used as an output if no inputs are specified or if
|
2024-06-30 01:14:08 +00:00
|
|
|
the output file is \(lq-\(rq.
|
2024-06-18 05:36:52 +00:00
|
|
|
.\"
|
2024-07-04 00:30:54 +00:00
|
|
|
.SH EXAMPLES
|
|
|
|
|
|
|
|
The following
|
|
|
|
.BR sh (1p)
|
|
|
|
line:
|
|
|
|
|
|
|
|
.RS
|
|
|
|
printf 'Hello, world!\(rsn' | dj -c 1 -b 7 -s 7 2>/dev/null
|
|
|
|
.RE
|
|
|
|
|
|
|
|
Produces the following output:
|
|
|
|
|
|
|
|
.RS
|
|
|
|
world!
|
|
|
|
.RE
|
|
|
|
|
|
|
|
The following
|
|
|
|
.BR sh (1p)
|
|
|
|
lines run sequentially:
|
|
|
|
|
|
|
|
.RS
|
|
|
|
tr '\(rs0' 0 </dev/zero | dj -c 1 -b 6 -o hello.txt
|
|
|
|
|
|
|
|
tr '\(rs0' H </dev/zero | dj -c 1 -b 1 -o hello.txt
|
|
|
|
|
|
|
|
tr '\(rs0' e </dev/zero | dj -c 1 -b 1 -o hello.txt -S 1
|
|
|
|
|
|
|
|
tr '\(rs0' l </dev/zero | dj -c 1 -b 2 -o hello.txt -S 2
|
|
|
|
|
|
|
|
tr '\(rs0' o </dev/zero | dj -c 1 -b 1 -o hello.txt -S 4
|
|
|
|
|
|
|
|
tr '\(rs0' '\(rsn' </dev/zero | dj -c 1 -b 1 -o hello.txt -S 5
|
|
|
|
|
|
|
|
dj -i hello.txt
|
|
|
|
.RE
|
|
|
|
|
|
|
|
Produce the following output:
|
|
|
|
|
|
|
|
.RS
|
|
|
|
Hello
|
|
|
|
.RE
|
|
|
|
|
|
|
|
It may be particularly illuminating to print the contents of the example
|
|
|
|
.B hello.txt
|
|
|
|
after each
|
|
|
|
.BR dj (1)
|
|
|
|
invocation.
|
|
|
|
.\"
|
2024-03-27 00:26:51 +00:00
|
|
|
.SH DIAGNOSTICS
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-06-29 11:55:29 +00:00
|
|
|
On a partial or empty read, a diagnostic message is printed. Then, the program
|
2024-06-26 17:36:52 +00:00
|
|
|
exits unless the
|
2024-01-10 06:43:45 +00:00
|
|
|
.B -n
|
2024-06-18 05:36:52 +00:00
|
|
|
option is specified.
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-05-24 16:21:06 +00:00
|
|
|
By default, statistics are printed for input and output to the standard error in
|
2024-03-27 00:26:51 +00:00
|
|
|
the following format:
|
2024-01-10 06:43:45 +00:00
|
|
|
|
2024-03-27 00:26:51 +00:00
|
|
|
.RS
|
2024-06-06 06:14:55 +00:00
|
|
|
{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}
|
2024-03-27 00:26:51 +00:00
|
|
|
.RE
|
|
|
|
|
2024-04-18 14:44:44 +00:00
|
|
|
This format for diagnostic output is designed to be machine-parseable for
|
|
|
|
convenience. For a more human-readable format, the
|
2024-01-10 06:43:45 +00:00
|
|
|
.B -H
|
2024-04-18 14:44:44 +00:00
|
|
|
option may be specified. In this event, the following format is used instead:
|
2024-03-27 00:26:51 +00:00
|
|
|
|
|
|
|
.RS
|
2024-06-06 06:14:55 +00:00
|
|
|
{records read} '+' {partial records read} '>' {records written}
|
|
|
|
'+' {partial records written} ';' {bytes read} '>' {bytes written}
|
|
|
|
{ASCII line feed}
|
2024-03-27 00:26:51 +00:00
|
|
|
.RE
|
|
|
|
|
2024-06-03 00:47:14 +00:00
|
|
|
In non-recoverable errors that don\(cqt pertain to the read-write cycle, a
|
2024-03-27 01:22:30 +00:00
|
|
|
diagnostic message is printed and the program exits with the appropriate
|
2024-06-06 02:39:37 +00:00
|
|
|
.BR sysexits.h (3)
|
|
|
|
status.
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-01-10 06:43:45 +00:00
|
|
|
.SH BUGS
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-01-10 06:43:45 +00:00
|
|
|
If
|
|
|
|
.B -n
|
2024-05-24 16:21:06 +00:00
|
|
|
is specified along with the
|
|
|
|
.B -c
|
2024-06-18 05:36:52 +00:00
|
|
|
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
|
2024-01-10 06:43:45 +00:00
|
|
|
.B -a
|
2024-06-30 01:14:08 +00:00
|
|
|
option is specified, this could make written data nonsensical.
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-03-27 06:08:43 +00:00
|
|
|
.SH CAVEATS
|
2024-06-04 05:07:19 +00:00
|
|
|
|
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-07-05 03:05:15 +00:00
|
|
|
The options
|
|
|
|
.B -b
|
|
|
|
and
|
|
|
|
.B -B
|
|
|
|
could be confused for each other, and so could
|
|
|
|
.B -s
|
|
|
|
and
|
|
|
|
.BR -S .
|
|
|
|
The lowercase option affects input and the capitalized option affects output.
|
|
|
|
|
|
|
|
The discarded but read bytes skipped while processing irregular files, such as
|
|
|
|
streams, are reported in the diagnostic output. Bytes skipped while processing
|
|
|
|
regular files are not reported, as the bytes weren\(cqt read.
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-01-10 06:43:45 +00:00
|
|
|
.SH RATIONALE
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-06-04 05:21:00 +00:00
|
|
|
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.
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-01-10 06:43:45 +00:00
|
|
|
.SH COPYRIGHT
|
2024-06-04 05:07:19 +00:00
|
|
|
|
2024-06-03 00:47:14 +00:00
|
|
|
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
|
2024-01-10 06:43:45 +00:00
|
|
|
<https://gnu.org/licenses/agpl.html>.
|
2024-06-03 00:47:14 +00:00
|
|
|
.\"
|
2024-01-10 06:43:45 +00:00
|
|
|
.SH SEE ALSO
|
2024-06-03 00:47:14 +00:00
|
|
|
.BR dd (1p)
|
2024-07-05 03:05:15 +00:00
|
|
|
.BR lseek (3p)
|