atob/btoa: Q&D ASCII-binary-ASCII converters by Sean Dwyer <ewe@can.org.au>
----------------------------------------------------------------------------

handy little c progs (hopefully), they are designed for situations where you
may not have access to a screen editor, or just want to do some quick hacking
on a binary file. no printable output is included or desired: if you want
that, you'll probably have bvi or hextype or hexdump etc. I recommend hextype
especially redirected to a file so you can compare printable bytes.

They were inspired by a real unix horror story, and the recognition that on
some systems (old and new), screen-oriented editors may not be an option.

THEY ARE QUICK and DIRTY, but USEFUL. Endianess is not considered (after all,
even od on intel systems doesnt swap the bytes), nor is memory malloc'd to
speed up work on large files: you're better off with a proper editor for that.

Rename them if you wish, make printouts and memorize for the day when you may
have to recreate them!!

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> NOTE <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
They have _nothing_ to do with the atob/btoa kludges to send binary files
through email!! (use uudeview/uuenview and MIME instead).
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> NOTE <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<


Both are hacked from the handy old hdump-1.1 last authored by Mike Haaland
<mikeh@hypertech.com>, and are copyrighted freeware as far as i can see, see
COPYING for details. Mike, if you're reading, contact me if you have problems
with this.

------------
usage:
------------

these are q&d stdin/stdout, each can take the other's input/output:

atob: atob < textfile > hex-binary
btoa: btoa < hex-binary > textfile

try atob <textfile | btoa > textfile !

neither of these can take stdin/stdout (they also have usage/arg stuff):

atob1: atob1 textfile hex-binary (the kinder safer atob :))
btoa1: btoa1 hex-binary textfile (the kinder safer btoa :))

----------------
textfile format:
----------------

(a good textfile)

0701aabbc90011ff0000001122bade00aabbccddeeff00112233445566778899

lines can be up to 64 chars in length. shorter lines are ok, as long as they
are even. Both complain
if there's no hex chars, and neither version complains if the textfile is
badly formatted as below:

(a bad textfile)

0701aabbc9
ff
899abcffffff55ffff00f2020f204d0daf0faccef0abcdef0123456789ff2234AABB

here, all both atob's do is take everything up to 34 in the third line and
ignores the rest, because the line is over long. In any case, it would reject
the AABB because they wont process uppercase ASCII!

so technically you can have

0701aabbc9
ff
899abcffffff55ffff00f2020f204d0d
af0faccef0
abcdef01
23456789

AS LONG as characters/line are even. an uneven line is a "bad hex value"
error, and the resulting binary will be truncated where the error occurred.
Also be careful to avoid control-characters (eg tab) in the file or you may
get unusual errors (bad hex value is all the utils will say).


070100002c0000000000000000000000
00000000000000000000000000000000
0000dd8fff010000dd8f27000000fb02
ef07000000fb01ef070000000000bc8f
8800040000bc012f65746300

This is createetc, the ASCII hex that saved one sysadmin's system from
destruction. Converted to createetc.bin, it can create an /etc directory on
old UNIX systems. From the hex, it looks older than the system described
(4.3BSD on a VAX, which had 08010000000C headers, but it _is_ VAX assembler),
but obviously worked.

This hex was the sole reason for writing the utils, even though they don't
support the original line length.
