CODEGROUP(1)

💖 codegroup — General Commands Manual 💖

okay bestie, sit DOWN, because today we're talking about codegroup(1) and it is genuinely the most spy-movie thing in your whole /usr/bin. no cap. 🕵️♀️✨

---

✨ NAME ✨

codegroup — encode / decode binary file as five letter codegroups 🎀

---

🌸 SYNOPSIS 🌸

codegroup -d|-e [ -u ] [ infile [ outfile ] ]

---

🦋 DESCRIPTION 🦋

so for literal decades, spies have been writing their encoded messages in groups of five letters. iconic behavior. 💅

codegroup encodes any binary file into this exact form, which means you can yeet it through any medium you want, and it also decodes files that contain codegroups back into the original input. the encoded files carry a 16-bit cyclical redundancy check (CRC) plus the file size, so when you decode, you can verify that the message came through complete and correct. and here's the cute part — files you're decoding are allowed to have other stuff before and after the codegroups, so you can totally include in-the-clear annotations. 🫶

now, real talk: codegroup makes no attempt, on its own, to prevent your message from being read. like, none. it is not a lock, bestie, it's a cute little envelope. if you want actual cryptographic security, delegate that to a package that's built for it, such as pgp. then you just run codegroup on the encrypted binary output and boom — it becomes easily transmitted text. text made by codegroup uses only upper case ASCII letters and spaces. and unlike files encoded with uuencode or pgp's ASCII armour facility, the output of codegroup can be easily (albeit tediously) read over the telephone, broadcast on shortwave radio to agents in the field, or sent by telegram, telex, or Morse code. it's giving field-agent chic. 📻✉️

to illustrate the difference, here are the first few lines of a binary file encoded by:

base64:

H4sICFJ9MzYAA2EudGFyAOxba3faSNKer+lf0SezO3YmgLnY2I6TyQIGgwOGBTtOYjuJEMJo
DJFGF1+ys//9rarulpqLHRi/mdk9G84JIKGuqq579eNkNn745q9sNru9tcXhs5gtFPAzm83l
xad88WyxmNssbhe3sps8m8ttZ/M/8K1vL9oPP0RBaPggypU1vrad+59zosj0HqAj9xF//pe8
WsaVNbTH1rfkAfoobm7ea//cZn4rtv/mNtq/kM9t/cCz31Io9foftz9nnW77oMdfcdMdWJe+

uuencode:

begin 644 data.bin
M'XL("&7._R\  VUO;V\ /9U+FN2XSF3G6H5OA1(?HOB<=/<7__X7TN<PJ[L&
M=?-&1;I+) B8 0;P?_Z'?WY_-=7Q"T_JSZ_6)X9?&"$\OU9[N'\A[A%^L^6=
M?^M[OOV+:9=UM9J^] MAS_ ;X0O]U];(Z?<WWE9_\^[/]ZMM\OO[CG'^2M\M
M_G(+,US/LWKZE1#C^YO?D_;O#G[7][2R^+0>XJ^&PI/\[?7-7U]KU=]SSWQ?

pgp:

-----BEGIN PGP MESSAGE-----
Version: 2.6.2i

hIwCCb8iTku3pBUBA/9oSDlfk/On9bwjmTnB98Eejr6agkPSi3n6hd8JkAtJd33f
kzFq18Jo0xzRUWZ7Di6Jq/FXpeI1yztVDqispbcYOP0aDv4JZOSF1kRsmJ9xK9Bo
Cv4a967IXPkkRsjIAkx0B39dYxCzf8kHUn4THmyV/b2qLUZ0cc+mr8hxFfFpuYSM

codegroup:

ZZZZZ YBPIL AIAIG FMOPP CPAAA DGNGP GPGPA ADNJN ELJKO ELIMO
GEOHF KIFGP IFBCB PKCPI YJMHE PHBHP PPOBH NCOHD AKLLL AGHFP
DEGEF LKELC EAIJI ABAGP AHPPO IHHPH OHPDF YNFPB ALEPO KMPKP
NGCHI GFPBI CBDML PFGHL LIHPC BOOBB HOLDO FJNHP OLHLL OPNIL

see how only codegroup conforms to the telegraphic convention of all upper case letters, and passes the "telephone test" of being readable without any modifiers such as "capital" and "lower-case"? avoiding punctuation marks and lower case letters makes the output of codegroup much easier to transmit over a voice or traditional telegraphic link. that's the whole vibe. 👑

---

💅 OPTIONS 💅

• -decode — decodes the input (which was previously created by codegroup) to recover the original input file, and verifies it so it can detect truncation or corruption of the contents. 🔍
• -encode — encodes the input into an output text file containing five letter code groups. this is the default, bestie, it's the main character. ✨
• -usage — print how-to-call information. the "help me, bestie" button. 🫶

All options may be abbreviated to a single letter. (short girl summer, literally — one letter and you're done. 💀)

---

🌈 APPLICATION NOTES 🌈

okay so encoding a binary file as ASCII characters inevitably increases its size, that's just math, no getting around it. but when you use it in conjunction with existing compression and encryption tools, the resulting growth in file size is usually acceptable. 🧚

for example: a random extract of electronic mail 32768 bytes in length was chosen as a test sample. compression with gzip compacted the file to 15062 bytes. it was then encrypted for transmission to a single recipient with pgp, which resulted in a 15233 byte file. (even though pgp has its own compression, smaller files usually result from initial compression with gzip. in this case, pgp alone would have produced a file of 15420 bytes.) 🍓

then codegroup transforms the encrypted file into a 37296 byte text file. so, thanks to compression, the code groups for the encrypted file are only a little larger than the original cleartext. slay. 💜

but ngl, restricting the character set and including spaces between groups results in substantially larger output files than those produced by uuencode and pgp. files encoded with codegroup are about 2.5 times the size of the input file, while uuencode and pgp expand the file only about 35%. so codegroup is thus preferable only for applications where its limited character set is an advantage. (basically: pick it for the vibe, not for the file size. 🫠)

---

🎀 FILES 🎀

if no infile is specified, or infile is a single '-', codegroup reads from standard input. if no outfile is given, or outfile is a single '-', output is sent to standard output. 📥📤

the input and output are processed strictly serially — consequently codegroup may be used in pipelines. so yes, you can pipe it, bestie, go off. 🔗

---

💀 BUGS 💀

when a CRC error is detected, no indication is given of the location in the file where the error(s) occurred. 😭 when sending large files, you may want to break them into pieces with the splits utility (available from the Web page cited below) so, in case of error, only the erroneous pieces have to be re-sent. chunk it like a responsible agent. 🧩

it might be nice to embed the original file name and modes in the encoded output, but this opens the door to all kinds of system-dependent problems. 🙈 you can always include this information as text before the first codegroup, or send an archive created with tar or zip. (we do it manually around here, bestie, it's called ✨craft✨.)

---

🔥 SEE ALSO 🔥

base64(1), gzip(1), pgp(1), splits(1), tar(1), uuencode(1), zip(1)

---

⭐ EXIT STATUS ⭐

1. codegroup returns status 0 if processing was completed without errors. 🎉
2. status 1 if errors were detected in decoding a file which indicate the output is incorrect or incomplete. 😬
3. status 2 if processing could not be performed at all due, for example, to a nonexistent input file or no codegroups found in the input. 💀

---

👑 AUTHOR 👑

• John Walker
• http://www.fourmilab.ch/

this software is in the public domain. permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, without any conditions or restrictions. this software is provided as is without express or implied warranty. generous king behavior, fr fr. 🫶✨

---

and that's the whole page, bestie — brought to you by the codegroup(1) page from the General Commands Manual, dated 7 SEP 2008. go encode something cute and remember: the CRC is not a vibe check, it's a fact check. 💅🌈🦋