aryal/coreutils
1
0
Fork 0
forked from bonsai/harakit
Code Pull Requests Activity

all: formatting; mm(1): fixes speed, simplicity; docs/dj.1: grammar, typos, etc.

Browse Source
This commit is contained in:
Emma Tebibyte
2025-10-26 16:58:13 -06:00
parent 8eece4cf84
commit 8d8df711d9
47 changed files with 719 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/dj.1
View File

@@ -1,5 +1,5 @@
.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2024 Emma Tebibyte <emma@tebibyte.media>
.\" Copyright (c) 2024–2025 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/>.
@@ -28,45 +28,44 @@ dj
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
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.
specification in \*(Px and used here to decrease ambiguity.
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.
with a skip offset of 1 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.
.\"
.SH OPTIONS
.IP \fB-i\fP\ \fIfile\fP
Takes a file path as an argument and opens it for use as an input.
.IP \fB-b\fP\ \fIblock_size\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 size in bytes of the input buffer. If this
option is not specified, the size is 1024 bytes.
.IP \fB-s\fP \fIoffset\fP
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.
.IP \fB-o\fP
commence; the program \(lqskips\(rq that number of \fIbytes\fP. If the standard
input is used, bytes read to this point are discarded.
.IP \fB-o\fP \fIfile\fP
Takes a file path as an argument and opens it for use as an output.
.IP \fB-B\fP\ \fIblock_size\fP
Takes a numeric argument as the size in bytes of the output buffer, the default
being 1024. Note that this option only affects the size of output writes and not
the amount of output data itself. See the CAVEATS section.
.IP \fB-S\fP
Takes a numeric argument as the size in bytes of the output buffer. The default
size is 1024. Note that this option only affects the size of output writes and
not the amount of output data itself. See the CAVEATS section.
.IP \fB-S\fP \fIoffset\fP
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.
commence; the program \(lqseeks\(rq that number of bytes. If the standard
output is used, null characters are first printed this many times.
.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. If the option argument is empty, the
null byte is used.
Accepts a single literal byte with which the input buffer is padded in the
event of an incomplete read from the input file. If the option argument is
empty, the null byte is used.
.IP \fB-c\fP
Specifies a number of blocks to read. The default is 0, in which case the input
is read until a partial or empty read is made.
@@ -78,12 +77,12 @@ Retries failed reads once before exiting.
.\"
.SH STANDARD INPUT
The standard input shall be used as an input if no inputs are specified or if
The standard input shall be used as an input if none are specified or if the
input file is \(lq-\(rq.
.\"
.SH STANDARD OUTPUT
The standard output shall be used as an output if no inputs are specified or if
the output file is \(lq-\(rq.
The standard output shall be used as an output if none are specified or if the
output file is \(lq-\(rq.
.\"
.SH EXAMPLES
@@ -135,13 +134,12 @@ invocation.
.\"
.SH DIAGNOSTICS
On a partial or empty read, a diagnostic message is printed. Then, the program
exits unless the
On a partial or empty read, a diagnostic message is printed. Then, unless the
.B -n
option is specified.
option is specified, the program exits.
By default, statistics are printed for input and output to the standard error in
the following format:
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}
@@ -172,8 +170,8 @@ 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
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
option is specified, this could make written data nonsensical.
.\"
@@ -202,12 +200,15 @@ The skipped or sought bytes while processing irregular files, such as streams,
are reported in the diagnostic output, because they were actually read or
written. This is as opposed to bytes skipped while processing regular files,
which are not reported.
Much of this program shares its functionality with
.BR mm (1).
.\"
.SH RATIONALE
This program was based on the
.BR dd (1p)
utility as specified in POSIX. While character conversion may have been the
utility as specified in \*(Px. 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
@@ -215,12 +216,18 @@ 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 AUTHOR
Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT
Copyright \(co 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
.BR mm (1)
.BR dd (1p)
.BR lseek (3p)
.BR mm (1)