Inspect Linux Keyboard Tables Safely with dumpkeys

dumpkeys inspects the Linux console keyboard tables, separates key bindings from function strings, and shows when it cannot reach a real console. The examples use dumpkeys from kbd 2.6.4, installed here as package version 2.6.4-2ubuntu2. Allow about fifteen minutes, plus time to log in on a local virtual console if your current shell has no console device.

This is a read-only guide. dumpkeys prints the kernel's current translation tables; it does not load a keymap or change the keyboard. You need the kbd package and a shell. Most inspection commands do not need elevated privileges when the console device is readable, but access to a protected device depends on the host's permissions.

1. Confirm the installed command

Start with version and help output. These checks are ordinary commands and do not need sudo:

$ dumpkeys --version
dumpkeys from kbd 2.6.4
$ dumpkeys --help
Usage: dumpkeys [option...]

Options:
  -i, --short-info         display information about keyboard driver.
  -l, -s, --long-info      display above and symbols known to loadkeys.
  -n, --numeric            display keytable in hexadecimal notation.
  -f, --full-table         don't use short-hand notations, one row per keycode.
  -1, --separate-lines     one line per (modifier,keycode) pair.
  -S, --shape={2|4|8|16}
  -t, --funcs-only         display only the function key strings.
  -k, --keys-only          display only key bindings.
  -d, --compose-only       display only compose key combinations.
  -c, --charset=CHARSET    interpret character action codes to be from the specified character set.
  -C, --console=DEV        the console device to be used.
  -v, --verbose            be more verbose.
  -V, --version            print version number.
  -h, --help               print this usage message.

Checkpoint: the version line identifies the kbd release, while the help text confirms the options available on this installation. Do not copy an option from a different kbd release without checking this output first.

2. Check that the shell can reach a Linux console

The normal table dump reads the active console keyboard driver. It is not a generic keyboard listing and it is not a report of a desktop environment's input settings. Run the default command from a local virtual console, often reached with Ctrl + Alt + F3 or another function key:

$ dumpkeys

On a usable virtual console, expect a keymap-style stream containing lines such as keymaps, keycode and possibly function-string definitions. Exact keycodes and symbols depend on the host's active map, so do not treat another machine's output as a universal expected result.

If you run it in a terminal, container, SSH session or this non-console shell, the command may fail before printing a table:

Couldn't get a file descriptor referring to the console.

That message describes the environment, not an empty keymap. First retry from a local virtual console. If you intentionally need another console device, pass exactly one device name with --console or -C:

$ dumpkeys --console /dev/console

Do not guess a device path or use elevated privileges as a first response. Check the device and its permissions, then use the privilege required by your system policy only if the diagnostic indicates an access problem:

$ ls -l /dev/console
$ id

There is no undo step for these commands. They only read the selected console state.

3. Read the kernel capability summary

Once the command can reach the console, request the short information listing:

$ dumpkeys --short-info

The output reports the kernel's keycode range, the number of actions bindable to one key, supported action-code ranges, the number of function keys, and the current function strings. These values describe what this kernel and console driver expose. They are useful before writing a keytable, because a symbol understood by your loadkeys program may not be supported by the running kernel.

For the action symbols and their numeric values, use the longer form:

$ dumpkeys --long-info

Use this as a compatibility check, not as a way to change anything. Numeric action codes can vary between kernels, which is why symbolic names are normally easier to maintain.

4. Isolate the part you need

A complete dump normally contains both key bindings and function-string definitions. Narrow the output when investigating one area:

$ dumpkeys --keys-only
$ dumpkeys --funcs-only

Use --compose-only for compose combinations when the kernel has compose-key support. If that feature is unavailable, the command cannot manufacture compose data. These options remain read-only; the corresponding changes belong to loadkeys, which is outside this guide.

If a parser needs a predictable, expanded representation, choose a shape explicitly:

$ dumpkeys --full-table
$ dumpkeys --separate-lines
$ dumpkeys --shape=4

--full-table avoids shorthand and emits one row per keycode. --separate-lines emits one line per modifier and keycode pair. The shape values are 2, 4, 8 and 16; they control how bindings are laid out. Pick one format for a script and keep it fixed, because the default output is designed for humans and can use shorthand.

5. Make numeric and character output deliberate

For troubleshooting action-code values, request hexadecimal output:

$ dumpkeys --numeric

This bypasses symbolic action names. It can help compare raw values, but it is less portable than symbolic output because action-code support is kernel-dependent.

Character names are interpreted as ISO-8859-1 unless you choose another supported ISO-8859 character set:

$ dumpkeys --charset=iso-8859-8 --keys-only

Use this only when the keymap's character encoding requires it. The output includes a charset line so a later keymap reader knows how to interpret the values. Do not add the option merely because a terminal displays unexpected text; first establish the encoding used by the keymap.

6. Capture output without overwriting evidence

When you need to compare a keymap before and after a maintenance change, redirect to a new, clearly named file in a directory you control:

$ dumpkeys --full-table > "$HOME/keymap-before.txt"
$ test -s "$HOME/keymap-before.txt" && printf '%s\n' 'capture written'
capture written

The redirection creates or truncates the destination before dumpkeys runs. The test check therefore does not prove that the table is correct; it only confirms that some output was written. Use a new filename for each capture, or check that an existing file is disposable before redirecting. If the command fails, the shell may still have created an empty file. Remove that empty diagnostic file manually if it is not useful:

$ test -s "$HOME/keymap-before.txt" || rm -- "$HOME/keymap-before.txt"

That removal is the only state-changing command in this guide. Confirm the path first, and never replace $HOME with a broad system path or a wildcard.

Done means