overgrown/docs/swab.1

.\" Copyright (c) 2024 DTB <trinity@trinity.moe>
.\" Copyright (c) 2024 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/>.
.\"
.TH SWAB 1 2024-06-17 "Harakit X.X.X"
.SH NAME
swab \(en swap bytes
.\"
.SH SYNOPSIS

swab
.RB [ -w\ word_size ]
.\"
.SH DESCRIPTION

Swap the latter and former halves of a block of bytes.
.\"
.SH OPTIONS

.IP \fB-w\fP\ \fIword_size\fP
Configures the word size; that is, the size in bytes of the block size on which
to operate. The default word size is 2. The word size must be cleanly divisible
by 2, otherwise the block of bytes being processed can\(cqt be halved.
.\"
.SH EXAMPLES

The following
.BR sh (1p)
line:

.RS
printf 'hello world!\(rsn' | swab
.RE

Produces the following output:

.RS
ehll oowlr!d
.RE
.\"
.SH DIAGNOSTICS

In the event of an error, a debug message will be printed and the program will
exit with the appropriate
.BR sysexits.h (3)
error code.
.\"
.SH RATIONALE

This program was modeled and named after the
.B conv=swab
functionality specified
in the
.BR dd (1p)
utility. It additionally allows the word size to be configured.

This functionality is useful for fixing the endianness of binary files produced
on other machines.
.\"
.SH AUTHOR

Written by DTB
.MT trinity@trinity.moe
.ME .
.\"
.SH COPYRIGHT

Copyright \(co 2024 DTB. License AGPLv3+: GNU AGPL version 3 or later
<https://gnu.org/licenses/agpl.html>.
.\"
.SH SEE ALSO
.BR dd (1p)