.\" Copyright (c) 2024 DTB .\" Copyright (c) 2024 Emma Tebibyte .\" .\" This work is licensed under CC BY-SA 4.0. To see a copy of this license, .\" visit . .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 ]) .SH OPTIONS .B -i .RS Takes a file path as an argument to open and use as an input. .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 .B -s .RS 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. .RE .B -o .RS Takes a file path as an argument to open and use as an output. .RE .B -B .RS Does the same as .B -b but for the output buffer. .RE .B -S .RS Skips a number of bytes through the output before starting to write from the input. If the output is a stream, null characters are printed. .RE .B -a .RS Accepts a single literal byte with which input buffer is padded in the event of an incomplete read from the input file. .RE .B -c .RS Specifies a number of reads to make. If set to zero (the default), reading will continue until a partial or empty read is encountered. .RE .B -A .RS If the output is a stream, null bytes are printed. This option is equivalent to specifying .B -a with a null byte instead of a character. .RE .B -d .RS Prints invocation information before program execution as described in the DIAGNOSTICS section below. Each invocation increments the debug level of the program. .RE .B -H .RS Prints diagnostics messages in a human-readable manner as described in the DIAGNOSTICS section below. .RE .B -n .RS Retries failed reads once more before exiting. .RE .B -q .RS Suppresses error messages which print when a read or write is partial or empty. Each invocation decrements the debug level of the program. .RE .SH STANDARD INPUT The standard input shall be used as an input if no inputs are specified one or more of the input files is “-”. .SH DIAGNOSTICS On a partial or empty read, a diagnostic message is printed (unless the .B -q option is specified) and 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 .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} .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 .R {records read} '+' {partial records read} '>' {records written} .R '+' {partial records written} ';' {bytes read} '>' {bytes written} .R {ASCII line feed} .RE 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= ibs=1024 skip=0 align=ff count=0 .R out= obs=1024 seek=0 debug= 3 noerror=0 .RE 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. .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. 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 CAVEATS Existing files are not truncated on ouput and are instead overwritten. .SH RATIONALE 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. .SH COPYRIGHT Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . .SH SEE ALSO dd(1p)