Load a Linux Console Screen Map Safely with mapscrn

A console full of boxes instead of letters is what sends most people looking for mapscrn in the first place. This guide loads a character mapping table into a Linux virtual console, checks which map file you actually picked, and keeps a copy of the old one so you can put it back. Allow about fifteen minutes, plus time to test the display on the real console. The examples use mapscrn from kbd 2.6.4, installed here as /usr/bin/mapscrn.

This is a console-driver setting, not a terminal-emulator one. It changes how bytes are displayed on a virtual console, and the effect can be visible to anyone else using that console. Do not test it on a production console during an active session. The command normally needs elevated privileges because it writes to the console driver.

1. Check the installed command

Start with read-only checks. The installed command reports its version and lists what options exist on this machine:

$ command -v mapscrn
/usr/bin/mapscrn
$ mapscrn -V
mapscrn from kbd 2.6.4
$ mapscrn --help
Usage: mapscrn [option...] [map-file]

Here is the surprising bit: the manual calls mapscrn obsolete, because its job is now built into setfont. It only survives for backwards compatibility. So before adding a second, competing configuration, check whether your console setup already uses setfont or a startup script for this.

2. Choose a map from the installed directory

The manual names /usr/share/consoletrans as the default directory for screen mappings. On this installation it holds compressed mappings such as ISO-8859-1.acm.gz and ISO-8859-2.acm.gz:

$ find /usr/share/consoletrans -maxdepth 1 -type f -printf '%f\n' | sort | head
ARMSCII-8.acm.gz
CP1251.acm.gz
CP1255.acm.gz
CP1256.acm.gz
GEORGIAN-ACADEMY.acm.gz
GEORGIAN-PS.acm.gz
IBM1133.acm.gz
ISIRI-3342.acm.gz
ISO-8859-1.acm.gz
ISO-8859-10.acm.gz

• Your listing can differ. Pick a table that matches the byte encoding used by the program whose output you need to display.
• A map is not a Unicode converter. It tells the console driver how to interpret user bytes once the user-defined mapping mode is selected, nothing more.
• Do not guess from the locale. Check the encoding the application expects and the font loaded on the console as two separate pieces of configuration.

Use an exact path when scripting this:

$ MAPFILE=/usr/share/consoletrans/ISO-8859-2.acm.gz
$ test -r "$MAPFILE" && printf 'map is readable: %s\n' "$MAPFILE"
map is readable: /usr/share/consoletrans/ISO-8859-2.acm.gz

3. Save the old map before loading a replacement

$ install -d -m 700 "$HOME/console-map-backups"
$ sudo mapscrn -o "$HOME/console-map-backups/before-mapscrn.map" "$MAPFILE"
$ ls -l "$HOME/console-map-backups/before-mapscrn.map"
-rw------- 1 alice alice 512 Sep 25 12:00 /home/alice/console-map-backups/before-mapscrn.map

The ownership, size and timestamp shown are machine-specific. What matters is that the backup exists after the command exits cleanly. If sudo is not available to you, stop and sort out the access you need rather than redirecting the operation somewhere odd.

Some systems store the map as 256 or 512 bytes of binary data, so a saved file can look opaque. Do not open it in a text editor. Keep the backup until you have tested the replacement and confirmed your normal console configuration will not silently overwrite it at the next login or reboot.

4. Load the selected map

With the backup in place, load the map using the same explicit path:

$ sudo mapscrn "$MAPFILE"
$ printf 'mapscrn status: %s\n' "$?"
mapscrn status: 0

A successful exit status only means the command accepted and loaded the table. It does not prove your application's bytes now look right. The console driver uses the table once the relevant escape sequence selects user-defined mapping mode: ESC ( K selects the G0 set and ESC ) K selects the G1 set.

5. Understand custom text maps before writing one

mapscrn accepts a 256-byte or 512-byte binary table, or a two-column text file: the first column is a table offset, the second is the value stored there. A value above 255, or one written in Unicode notation such as U+03A9, marks the table as user-to-Unicode; otherwise it is treated as direct-to-font.

• Value forms accepted: decimal, octal with a leading zero, hexadecimal with 0x, Unicode with U+, a quoted single character, or a quoted UTF-8 character.
• What quoted single characters cannot express: blank, comma, tab and #.
• What you cannot remap at all: control characters below 32, because the console driver reserves their special meanings.

For a small, reviewable text map, use explicit numeric values and keep the source file under version control. This example maps byte 65 to Unicode U+03A9:

$ cat > /tmp/example-screen-map.txt <<'EOF'
65 U+03A9
EOF
$ sudo mapscrn -o "$HOME/console-map-backups/before-example.map" /tmp/example-screen-map.txt

This deliberately changes one entry and is fit only for a disposable console test. The shell writes the temporary source file; mapscrn loads it. Do not treat a one-entry table as a stand-in for a complete encoding map unless that is exactly what you want.

6. Restore the previous map if the result is wrong

Restoring is just another load. If the display becomes unusable, switch to another virtual console with the usual key combination, or use an out-of-band administrator session. Then load the backup you made earlier:

$ sudo mapscrn "$HOME/console-map-backups/before-mapscrn.map"
$ printf 'restore status: %s\n' "$?"
restore status: 0

Do not delete the backup straight away. A later console-initialisation step may reload a different map and make the fix look temporary. Search the existing startup configuration for mapscrn and setfont before touching anything persistent. Changing boot or login configuration is outside this command's job and deserves its own reviewable change.

Common traps

• Testing the wrong terminal. A virtual console and a graphical terminal emulator do not share the same display path.
• Choosing the wrong encoding. A visibly wrong result can be a mismatch between application bytes, map table and font, not a failed load.
• Forgetting the mode switch. Loading a table does not mean every output path uses it immediately; the console driver only switches on the documented escape sequence.
• Overwriting the only recovery copy. Give every experiment a new backup name and keep the known-good copy until testing is finished.
• Reaching for root too early. command -v, find and test -r are ordinary read-only checks. Save sudo for the actual console-driver operation.