portable-hexdump

A portable, POSIX-compliant Bourne shell hex dumper designed for restricted environments and recovery shells.

Shell · MIT License · GitHub

Why

Minimal rescue shells -- initramfs, recovery partitions, stripped-down containers -- often lack od or xxd entirely. portable-hexdump reads from standard input and prints a canonical hex+ASCII dump using nothing but sed, tr, dd, and printf, so it works anywhere a POSIX shell does, with no compiled binary and no package to install.

Features

POSIX-compliant -- uses only standard utilities (sed, tr, dd, printf); no Bash-isms (arrays, [[ ]]) and no GNU-specific extensions.
Zero dependencies -- runs under sh, dash, bash, zsh, or ksh.
Customizable output -- adjust column width, skip an offset, or limit the number of bytes read.
Explicit color support -- ANSI color output with "light" and "dark" themes, opt-in via --color.

Quick start

git clone https://github.com/hackagadget/portable-hexdump.git
cd portable-hexdump
sudo make install

portable-hexdump < file.bin

00000000  4d 49 54 20 4c 69 63 65 6e 73 65 0a 0a 43 6f 70   |MIT License..Cop|
00000010  79 72 69 67 68 74 20 28 63 29 20 32 30 32 34 2d   |yright (c) 2024-|

Usage

portable-hexdump [-C] [-h | --help] [--man] [--version]
                 [-w width] [-s offset] [-n length]
                 [--color[=light|dark]]

Option	Description	Default
`-C`	Canonical hex+ASCII display (for compatibility)	on
`-w width`	Bytes per line	`16`
`-s offset`	Bytes to skip	`0`
`-n length`	Bytes to read	EOF
`--color[=theme]`	Enable ANSI color output (`dark` or `light`)	off
`--version`	Display version information and exit

Installation

The GNUmakefile and BSDmakefile both drive the same make install target, so the same command works on GNU/Linux and BSD systems:

sudo make install

This installs portable-hexdump to /usr/local/bin and portable-hexdump.1 to /usr/local/share/man/man1. Since it's a single shell script, it can also be dropped straight into a PATH directory without building anything:

curl -O https://raw.githubusercontent.com/hackagadget/portable-hexdump/main/portable-hexdump
chmod +x portable-hexdump
mv portable-hexdump ~/bin/

Portability notes

To stay functional in rescue shells, the script deliberately avoids Bash-isms, GNU-specific sed/tr extensions, and external tools like od, xxd, or awk. The tradeoff is performance -- reading byte-by-byte through dd to stay POSIX-compliant makes it far slower than a native C implementation like xxd. It's built as a survival tool for when nothing else is available, not a high-volume data processor. Currently it only reads from stdin; file arguments are planned for a future release.