Load a Linux Console Screen Map Safely with mapscrn

You will load a character mapping table into a Linux virtual console, verify which map file you selected, and keep a copy of the previous table so you can restore it. Allow about fifteen minutes, plus time to test the display on the actual console. The examples use mapscrn from kbd 2.6.4, installed here as /usr/bin/mapscrn.

This is a console-driver operation, not a terminal-emulator setting. It can change how bytes are displayed on a virtual console, and the effect may be visible to other users of that console. Do not test it in 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 documents the options available on this machine:

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

The manual describes mapscrn as obsolete because its function is built into setfont. It remains available for backwards compatibility. That matters when you are following an older console setup: first check whether the existing system uses setfont or a startup script, rather than adding a second competing configuration.

Checkpoint: confirm that the version and path are the ones you intend to operate. This guide does not change anything in this step.

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 contains 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. Select a table that matches the byte encoding used by the program whose output you need to display. A map does not convert arbitrary text into Unicode; it tells the console driver how to interpret user bytes when the user-defined mapping mode is selected.

Use an exact path when preparing a script. For example:

$ 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

Do not guess a file name from the locale. Check the encoding expected by the application and the font loaded on the console as separate pieces of configuration.

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 andy andy 512 Sep 25 12:00 /home/you/console-map-backups/before-mapscrn.map

The displayed ownership, size and timestamps are machine-specific. The useful check is that the backup exists after the command returns successfully. If you cannot use sudo, stop and arrange the required access rather than redirecting the operation to an arbitrary device.

Some systems expose the map as 256 or 512 bytes of binary data; a saved file may therefore look opaque. Do not edit it in a text editor. Keep the backup until you have tested the replacement and confirmed that your normal console configuration does not 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 means that the command accepted the input and loaded the table. It does not prove that the bytes produced by your application now look correct. The table is used by the console driver after the relevant escape sequence selects the user-defined mapping mode: ESC ( K selects the G0 set and ESC ) K selects the G1 set.

Checkpoint: switch to the intended virtual console, run the application that emits the target byte encoding, and inspect representative text. If you are connected through a terminal emulator or SSH, you may be looking at a different terminal path and may not see the effect at all.

5. Understand custom text maps before writing one

mapscrn accepts either a 256-byte or 512-byte binary table, or a two-column text file. In the text form, the first column is a table offset and the second is the value to store at that offset. A table containing values above 255, or values written in Unicode notation such as U+03A9, is treated as a user-to-Unicode table. Otherwise it is treated as a direct-to-font table.

The documented value forms are decimal, octal with a leading zero, hexadecimal with 0x, Unicode with U+, a quoted single character, and a quoted UTF-8 character. Blank, comma, tab and # cannot be represented by the quoted single-character form. Control characters below 32 cannot be remapped because the console driver reserves their special meanings.

For a small, reviewable text map, use explicit numeric values and keep the original 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 suitable only for a disposable console test. The shell writes the temporary source file; mapscrn loads it. Do not use a one-entry table as a general replacement for a complete encoding map unless that is exactly what you intend.

6. Restore the previous map if the result is wrong

Restoration is another load operation. If the display becomes unusable, move to another virtual console with the usual console-switching key combination or use an out-of-band administrator session. Then load the backup you created before the change:

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

Do not delete the backup immediately. A later console initialisation command may reload a different map, making the apparent fix temporary. Search the system's existing startup configuration for mapscrn and setfont before making persistent changes. Changing boot or login configuration is outside this command and should be reviewed as a separate, reversible 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 visually incorrect 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 immediately uses it. The console driver selects the G0 or G1 user-defined set through the documented escape sequence.
• Overwriting the only recovery copy: use a new backup name for each experiment and retain the known-good copy until the test is complete.
• Using root for inspection: command -v, find and test -r are ordinary read-only checks. Reserve sudo for the console-driver operation when the system requires it.