Add a Unicode table to a Linux console font with psfaddtable

You will produce a PSF console font with an embedded Unicode character table, then extract that table to check the result. This is useful when a font's glyph slots exist but the console has no mapping for the characters they represent. Allow about fifteen minutes if you already have the font and mapping file. The examples use kbd 2.6.4-2ubuntu2, installed on this machine.

This command changes no running console and needs no elevated privilege when you read a font and write the result in a directory you own. Keep the original font until the new file has passed verification. Loading the finished font with setfont is a separate, service-affecting step and is deliberately not part of this workflow.

1. Check the installed tool and font

Confirm which executable you will run and record the package version. The version matters here because the installed parser's practical input format is more specific than the old wording in the local manual page.

$ command -v psfaddtable
/usr/bin/psfaddtable
$ dpkg-query -W -f='${Package} ${Version}\n' kbd
kbd 2.6.4-2ubuntu2
$ psfaddtable
Usage: psfaddtable infont intable outfont

You need an uncompressed .psf or .psfu input. A compressed file such as font.psf.gz must be decompressed to a working copy first. Do not overwrite a packaged font under /usr/share/consolefonts; write a separate output file and copy it into an appropriate local font directory only after testing.

2. Create the table in the installed syntax

Make one line per glyph slot. The first value is the slot number, followed by one or more Unicode values. Blank lines and lines beginning with # are ignored. Slots run from 0 through 0xff for a 256-character font, or through 0x1ff for a 512-character font.

The local manual describes decimal, octal and hexadecimal numbers. With this installed kbd release, use the notation produced by psfgettable: a hexadecimal slot such as 0x041 and Unicode values written as U+0041. This avoids the installed parser treating a bare Unicode number as trailing junk. A comma joins values that describe one composed symbol; separate values map several characters to the same slot.

# glyph slot 0 represents NUL
0x000 U+0000
# slot 0x041 represents A and also the composed A mapping
0x041 U+0041,U+0061

Do not assume the slot number is the Unicode code point. A slot identifies a glyph position in the font. The values after it identify the characters that should select that glyph.

3. Add the table to a new font

For a compressed distribution font, make an uncompressed temporary input and send output to a new filename. Substitute a real installed font path if Lat2-Terminus16.psf.gz is not present on your system.

$ mkdir -p "$HOME/font-work"
$ gzip -dc /usr/share/consolefonts/Lat2-Terminus16.psf.gz > "$HOME/font-work/input.psf"
$ psfaddtable "$HOME/font-work/input.psf" "$HOME/font-work/table.txt" "$HOME/font-work/output.psf"
$ test -s "$HOME/font-work/output.psf" && echo 'output font written'
output font written

The three positional arguments are input font, table file and output font. A filename of - means standard input or standard output, so a pipeline is also possible:

$ gzip -dc /usr/share/consolefonts/Lat2-Terminus16.psf.gz |
  psfaddtable - "$HOME/font-work/table.txt" "$HOME/font-work/output-from-stdin.psf"
$ test -s "$HOME/font-work/output-from-stdin.psf" && echo 'stdin input worked'
stdin input worked

These examples create new files. Shell redirection and a directly named output can still replace an existing destination, so do not use an important font as the output path until verification is complete. If a command fails, discard the new output and keep the original input.

4. Verify the embedded mappings

Use psfgettable to inspect the table rather than trusting only the exit status. The output is human-readable and is also the most reliable template for a later edit.

$ psfgettable "$HOME/font-work/output.psf" | sed -n '1,12p'
#
# Character table extracted from font
#
0x000 U+0000
0x001
0x002
0x003
0x004
0x005
0x006
0x007
0x008

Search for a particular slot when it is outside the first lines:

$ psfgettable "$HOME/font-work/output.psf" | grep '^0x041[[:space:]]'
0x041 U+0041 U+0061

Output formatting can vary slightly, but the important check is that the expected slot contains the expected Unicode values. If it is blank, the table syntax or slot number is wrong. If the tool reports trailing junk, replace bare values such as 0x0041 after the slot with the installed form U+0041, and use the format emitted by psfgettable.

5. Handle an existing table safely

If the input font already contains a Unicode table, psfaddtable ignores that embedded table when it reads the explicit table file. The table file you supply therefore becomes the mapping in the output. Start from psfgettable output if you want to preserve existing mappings, edit it, and pass the edited copy as the table input.

$ psfgettable "$HOME/font-work/input.psf" > "$HOME/font-work/original-table.txt"
$ cp "$HOME/font-work/original-table.txt" "$HOME/font-work/edited-table.txt"
$ editor "$HOME/font-work/edited-table.txt"
$ psfaddtable "$HOME/font-work/input.psf" "$HOME/font-work/edited-table.txt" "$HOME/font-work/output.psf"
$ psfgettable "$HOME/font-work/output.psf" > "$HOME/font-work/verified-table.txt"
$ cmp "$HOME/font-work/edited-table.txt" "$HOME/font-work/verified-table.txt" || true

The last comparison can differ in comments, empty slots or formatting. Inspect any difference rather than assuming it is harmless. If you need to undo the operation, simply use the untouched input font or regenerate the output from the original font and the original table. Nothing in this workflow changes the input.

Common traps

• A compressed font is not automatically decompressed by psfaddtable. Feed it a real PSF file.
• The three arguments are positional. Swapping the table and output paths can produce confusing parse errors or an unusable file.
• A 256-glyph font cannot use a slot above 0xff. Use the limit appropriate to the font, not the Unicode value you want to represent.
• Adding a mapping does not add a glyph. If the slot contains the wrong bitmap, the console will display the wrong shape even when the table is valid.
• Do not run the command as root just because console fonts are commonly installed by root. Build and inspect a user-owned copy first.