.Dd September 1, 1996
.Dt BTOA 5
.Os NetBSD 1.2BETA
.Sh NAME
.Nm btoa
.Nd format of btoa output
.Sh DESCRIPTION
Files output by
.Xr btoa 1
consist of zero or more body lines, bracketed by a header line and a
trailer line.
.Xr atob 1
will ignore any lines preceding the header and does not even read past
the trailer.  Lines preceding a header must not, of course, look like a
header.
.Pp
The header line is simply a line that consists, in its entirety, of the
12 characters (including the newline)
.Dl xbtoa Begin
Following this are body lines, consisting of zero or more characters
from the set
.\" Why does .Bd/.Ed generate a blank line before but not after?  Ick.
.Bd -literal -offset indent
!"#$%&'()*+,-./01
23456789:;<=>?@AB
CDEFGHIJKLMNOPQRS
TUVWXYZ[\e]^_`abcd
efghijklmnopqrstu

.Ed
possibly with some
.Sq z
characters among them.  Finally, the end line matches the
.Xr printf 3
format
.Dl xbtoa End N %ld %lx E %lx S %lx R %lx
where the first two numbers are the byte count of the encoded binary
data (written in decimal and then again in hex), followed by three
checksums, all computed over the binary data stream: first
.Pf ( Sq E )
the exclusive-OR of all bytes, then
.Pf ( Sq S )
the sum of all bytes, then
.Pf ( Sq R )
a checksum computed in a 32-bit variable starting with zero and, for
each byte of data, rotating it one bit left and then adding the byte
(ignoring any overflow in the addition).
.Pp
The binary data stream is padded to a 32-bit boundary with trailing
zero bytes if necessary, then each 32-bit chunk is converted to five
encoded bytes by expressing it as a number in base 85, with the digits
being the 85 characters listed above.  32-bit zero is encoded as the
single character
.Sq z
rather than
.Sq !!!!! ,
since it occurs commonly enough to be worth optimizing.
.Sh SEE ALSO
.Xr btoa 1 ,
.Xr uuencode 5
.Sh BUGS
The checksums are rather weak (note for example that leading zero bytes
do not affect any of the checksums), but probably sufficient for
detecting accidental corruption.
.Pp
Some of the characters used not uncommonly get mangled by conversion of
text to other character sets such as EBCDIC and back.  The conversion
programs will compile and run in any environment that has the 85
characters that fall between
.Sq !
and
.Sq u
in ASCII, plus
.Sq x
and
.Sq z ,
but if the converted data doesn't have those characters
preserved by whatever translation it goes through, it almost certainly
won't decode either successfully or correctly.
.Pp
Note that there are no restrictions on where newlines appear, except
that one must appear after the beginning line and immediately before
the trailing line.