Convert a Sun Icon to PBM with icontopbm

icontopbm is a name that outlived the command it once was: it is now just an alias for sunicontopnm. Knowing that saves you chasing phantom differences between the two. Allow about ten minutes. You need a readable Sun icon, a shell, and the Netpbm tools, and none of it needs sudo. Keep the original icon until you have inspected the converted image.

1. Check the installed command

The name icontopbm is kept for compatibility but is obsolete: Netpbm 10.53 renamed the implementation to sunicontopnm, the old name became an alias, and the newer command gained support for more Sun icon variants.

$ command -v icontopbm
/usr/bin/icontopbm
$ icontopbm --version
icontopbm: Using libnetpbm from Netpbm Version: Netpbm 11.5.2
$ dpkg-query -W -f='${Package} ${Version}\n' netpbm
netpbm 2:11.05.02-1.1build1

The exact build lines differ between distributions. The useful checkpoint is that the command resolves to an installed binary and reports a Netpbm version. There are no icontopbm-specific options: the only optional positional argument is the icon file.

2. Check the input before converting

Confirm the path is correct and readable. This changes nothing:

$ ICON='/path/to/icon-file'
$ test -r "$ICON" && echo 'input is readable'
input is readable
$ ls -l -- "$ICON"
-rw-r--r-- 1 you you 1234 Sep 24 10:15 /path/to/icon-file

Replace the placeholder with the real path, and quote it so spaces and shell metacharacters in the file name do not bite you. A readable file is not necessarily a Sun icon, so treat a successful permission check as only an input checkpoint. If you do not know the format, renaming the file will not make it suitable: this converter expects Sun icon format specifically. XPM and XBM files need their own converters, such as xpmtoppm or xbmtopbm.

3. Convert to a new PBM file

Write to a new path first. That way an interrupted command or an invalid input does not destroy an existing output:

$ icontopbm "$ICON" > icon.pbm
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ test -s icon.pbm && echo 'PBM output is non-empty'
PBM output is non-empty

The output goes to standard output, so shell redirection is what actually creates icon.pbm. A zero exit status means the conversion completed, not that the dimensions or appearance are what you wanted. If icon.pbm already exists, this command replaces it: use a fresh name or make a backup before rerunning it.

There is no persistent configuration to undo here. To abandon the result, stop using icon.pbm and remove it only after checking it is not the only copy. Do not delete the source icon as part of a conversion script.

4. Verify the PBM header and dimensions

Use file for a quick independent check, then read the first two lines of the output directly:

$ file icon.pbm
icon.pbm: Netpbm image data, size 16 x 4, rawbits, bitmap
$ head -n 2 icon.pbm
P4
16 4

Your dimensions will depend on the icon. P4 identifies the raw, packed PBM form. Do not expect one line of text per row: the pixels after the header are binary, so printing more than the header can dump control characters into your terminal.

For a more Netpbm-specific check, use pamfile if it is installed:

$ pamfile icon.pbm
icon.pbm: PBM raw, 16 by 4

These tools verify the container and dimensions, not whether the icon actually looks right. Open the PBM in an image viewer that supports it, or convert it to a format your normal review tool handles, and keep the original beside the result while you compare them.

5. Know the replacement command and where it differs

$ sunicontopnm "$ICON" > icon.pnm
$ head -n 2 icon.pnm
P4
16 4

• A normal monochrome Sun icon produces PBM output.
• A Depth=8 icon produces PGM instead, because the newer converter can retain greyscale values.
• Colour Sun icons still produce PGM: the converter does not reconstruct a colour palette. If you know the palette, Netpbm's pamlookup can be used in a separate, deliberate step.

That output difference is the main reason the old name is misleading. A script that requires PBM should check the actual output type rather than trusting the command name: use pamfile, or inspect the magic number, before passing the result to another program.

6. Diagnose failures without changing the host

If the command cannot open the file, check the path and permissions again rather than reaching for elevated privileges over a guessed path:

$ test -e "$ICON" || echo 'path does not exist'
$ test -r "$ICON" || echo 'current user cannot read it'
$ icontopbm "$ICON" > icon.pbm
icontopbm: ...
$ printf 'exit status: %s\n' "$?"
exit status: 1

The diagnostic wording and exact status can vary with the Netpbm build. A non-zero status means inspect the error before trusting the output, and because shell redirection happens before the program starts, a failed command may still leave an empty or partial icon.pbm behind: check its size and use a new output path on the next attempt.

If the input turns out to be a different icon format, find the right converter rather than repeatedly retrying this one. If a pipeline consumes the output, make its failure visible with shell options or by checking each command's status, otherwise a later command can hide an earlier conversion error.