.\" 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 USAGE .B -A .RS Takes no arguments and pads with nuls. .RE .B -B .RS Does the same as .B -b but for the output buffer. .RE .B -H .RS Prints diagnostics messages in an alternate manner as described in the DIAGNOSTICS section below. .RE .B -S .RS Skips a number of bytes through the output before starting to write from the input. If the input is a stream the bytes are read and discarded. If the output is a stream, nul characters are printed. .RE .B -a .RS Takes one argument of one byte in length and pads the input buffer with that byte in the event that a read doesn’t fill the input buffer, and the .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 -c .RS Specifies an amount of reads to make, and if 0 (the default) dj will continue reading until a partial or empty read. .RE .B -d .RS Prints all debug information, user-specified or otherwise, before program execution. .RE .B -i .RS Takes a path as an argument to open and use in place of standard input. .RE .B -n .RS Causes dj to exit on two consecutive empty reads instead of one. .RE .B -o .RS Does the same as .B -i but in place of standard output. Dj does not truncate output files and instead writes over the bytes in the existing file. .RE .B -s .RS Takes a numeric argument as the number of bytes to skip into the input before starting to read. .RE .B -q .RS Suppresses error messages which print when a read or write is partial or empty. When .B -q is specified twice suppresses diagnostic output entirely. .RE .SH DIAGNOSTICS On a partial or empty read, dj prints a diagnostic message (unless the .B -q option is specified) and 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 If the .B -H option is specified, dj instead uses the following format: .RS .R {records read} '+' {partial records read} '>' {records written} .R '+' {partial records written} ';' {bytes read} '>' {bytes written} .R {ASCII line feed} .RE In non-recoverable errors that don’t pertain to dj’s read-write cycle, a diagnostic message is printed and dj 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 RATIONALE Dj was modeled after the dd utility specified in POSIX but adds additional features: 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. It also neglects character conversion, which may be dd’s original intent but is irrelevant to its modern use. .SH COPYRIGHT Copyright © 2023 DTB. License AGPLv3+: GNU AGPL version 3 or later . .SH SEE ALSO dd(1p)