Home / Alt manpages / unicode_start(1)

  • unicode_start(1)
  • User command
  • linux

Put a Linux Virtual Console into UTF-8 Mode with unicode_start

You will switch the current Linux virtual console and its keyboard to UTF-8 mode, check what changed, and return to the earlier keyboard state when needed. The guide uses unicode_start from kbd 2.6.4-2ubuntu2, the version installed on this machine.

Allow about ten minutes. You need a local virtual console such as /dev/tty1, /dev/tty2 or /dev/console, the kbd package, and permission to change that console. A terminal emulator, SSH session and most pseudo-terminals are not virtual consoles, so the command deliberately skips them.

Checkpoint

The first command below is read-only. The second changes the current console, so run it only from the virtual console you mean to change.

1. Confirm the installed command

Check the executable and package version before relying on examples. These commands do not change console state:

$ command -v unicode_start
/usr/bin/unicode_start
$ dpkg-query -W -f='${Package} ${Version}\n' kbd
kbd 2.6.4-2ubuntu2

The installed interface is unicode_start [font [unicode map]]. It has no switch for choosing a console. It operates on the console attached to standard input, and the script refuses non-console devices.

2. Check which console you are using

Run this ordinary diagnostic before changing anything:

$ tty
/dev/tty2

Your device number will differ. A path beginning with /dev/pts/, or output such as not a tty, means you are not in the target virtual console. Do not try to force the operation through an SSH or terminal-emulator session. Switch to a real Linux virtual console first, commonly with Ctrl+Alt+F2, subject to your desktop and hardware.

On this machine, running the command from a non-console context produces this harmless result:

$ unicode_start
unicode_start skipped on not a tty
$ printf 'exit status: %s\n' "$?"
exit status: 0

Status 0 here means the script skipped the unsuitable terminal. It does not mean that the console is now in Unicode mode.

3. Enable UTF-8 mode on the virtual console

From the intended virtual console, run:

$ unicode_start

No normal success message is printed. The command sets the keyboard driver to UTF-8 mode, changes the console output driver to expect UTF-8, enables the terminal's UTF-8 input setting, and leaves the current font alone when no font argument is supplied.

Some of those operations need access to the console device. Use the least privilege that works. Root also gets an extra keymap step: unicode_start saves the current keymap under $HOME/.kbd/.keymap_sv when it can, then reloads a Unicode-capable copy. That backup is used by unicode_stop. Non-root users can change their console's Unicode mode, but do not get the global keymap reload.

Checkpoint

Test a non-ASCII character rather than trusting a blank prompt:

$ printf '%s\n' 'café £ 日本'
café £ 日本

The exact glyphs depend on the console font. Garbled output can mean that the font lacks a Unicode map, not that keyboard mode failed.

4. Load a font only when the current one is unsuitable

Pass a font file as the first argument when the console needs a different font:

$ unicode_start /path/to/console-font.psf

The path is a placeholder. Replace it with a font that exists on your system; do not invent a file name. The font should contain a built-in Unicode map. If it does not, supply the map as the second argument:

$ unicode_start /path/to/console-font.psf /path/to/unicode-map

This reloads the font with setfont. It does not install a font or make the change permanent across boots. To find local font files, inspect the directories configured by your distribution, then verify the chosen path before running the command.

5. Verify the keyboard and output modes

Ask kbd_mode to report the keyboard mode, using the same virtual console:

$ kbd_mode
UTF-8

Then print representative UTF-8 data again. This checks the path from the shell to the console, but it cannot prove that every application or font will render every character.

If /proc is not mounted, unicode_start cannot determine the console type and exits with an error. If the command says that the terminal is not a VT, return to step 2. Neither message is fixed by adding sudo while staying in an SSH or pseudo-terminal session.

6. Return to the earlier mode

Unicode mode is per virtual console, and the state is not automatically undone when you close a shell. When you need to restore the traditional ASCII keyboard and console settings, run the companion command on that same console:

$ unicode_stop
$ kbd_mode
ASCII

For a root-run unicode_start, unicode_stop also reloads the saved keymap from $HOME/.kbd/.keymap_sv when that file is readable. If no backup was created, the keyboard mapping cannot be reconstructed by this command. Do not delete that file until you have finished testing and no longer need recovery.

After stopping Unicode mode, run a small ASCII test and switch back with unicode_start if the console is still needed for UTF-8 work. The font change itself may remain, because unicode_stop changes the modes and restores the saved keymap, not necessarily the previous font.

Done means

  • You confirmed that the session is a real virtual console.
  • unicode_start completed on the intended console.
  • kbd_mode reports UTF-8 and representative text displays correctly.
  • You used a verified font and Unicode map path only when the current font needed replacing.
  • You know to use unicode_stop on the same console to leave Unicode mode.