bonsai/harakit
4
4
Fork 3
Code Issues 41 Pull Requests 2 Projects 1 Releases 35 Activity

dj.1: elaborate on skip/seek behavior, provide another example

Browse Source
This commit is contained in:
dtb 2024-07-03 18:30:54 -06:00
parent 2167f35f58
commit adda0d9580
Signed by: trinity
GPG Key ID: 34C0543BBB6AF81B
1 changed files with 60 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
docs/dj.1
View File

@ -4,7 +4,7 @@
.\" 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-29 "Harakit X.X.X"
.TH DJ 1 2024-07-03 "Harakit X.X.X"
.SH NAME
dj \(en disk jockey
.\"
@ -34,10 +34,17 @@ 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. Seeks and skips aren\(cqt counted
in the output statistics because they're guaranteed to succeed (or the utility
will exit unsuccessfully).
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.
Seeks and skips aren\(cqt counted in the output statistics because they're
guaranteed to succeed (or the utility will exit unsuccessfully, before it has
written any data).
.\"
.SH OPTIONS
@ -82,6 +89,54 @@ input file is \(lq-\(rq.
The standard output shall be used as an output if no inputs are specified or if
the output file is \(lq-\(rq.
.\"
.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.
.\"
.SH DIAGNOSTICS
On a partial or empty read, a diagnostic message is printed. Then, the program