setkeycodes

setkeycodes [scancode] [keycode] ...

scancode
    The raw hexadecimal value (e.g., 0x00-0x7f) generated by a key press on the keyboard hardware. Use showkey --scancodes to identify these values for unknown keys.

keycode
    The decimal integer value (1-255) that the Linux kernel will associate with the given scancode. This internal representation is then used for further keymap translations.

setkeycodes is a low-level Linux utility used to manually assign a specific kernel keycode to a raw keyboard scancode. Scancodes are the raw hexadecimal values sent by the keyboard hardware when a key is pressed. Keycodes, on the other hand, are the internal numeric representations that the Linux kernel uses to identify keys.

This command is essential for configuring non-standard keyboards, adjusting for hardware quirks, or remapping keys that are not recognized by default. It allows system administrators or users to establish the fundamental mapping between a physical key's output and its logical representation within the operating system. Once a scancode is mapped to a keycode using setkeycodes, other utilities like loadkeys can then be used to associate these keycodes with specific characters, functions, or actions (e.g., 'A', 'Shift', 'Ctrl').

Changes made by setkeycodes are typically effective immediately but are not persistent across reboots unless saved in appropriate system configuration files, often found in udev rules or init scripts.

Persistence: Changes made by setkeycodes are typically not persistent across reboots. They must be added to system configuration files (e.g., udev rules, /etc/rc.local, or custom init scripts) to apply permanently.

Low-level Operation: This command operates at a very low level of the input subsystem. Incorrect mappings can potentially render parts of the keyboard unusable or lead to unexpected behavior.

Kernel Dependencies: Its functionality is tightly integrated with the kernel's keyboard driver. Behavior might slightly vary across different Linux kernel versions.

The showkey --scancodes command is an invaluable tool for determining the raw scancodes produced by unknown or non-functioning keys on a physical keyboard. These identified scancodes can then be precisely used as input for setkeycodes to establish proper mappings.

For permanent application of keycode mappings, setkeycodes commands are often integrated into udev rules. Specifically, these mappings can be defined in files like /etc/udev/hwdb.d/60-keyboard.hwdb or similar, which allows the system to automatically apply the custom scancode-to-keycode associations whenever the specific keyboard device is detected.

setkeycodes is a core component of the kbd package, which provides console keyboard tools for Linux. Its functionality has been fundamental since the early days of Linux to allow flexible keyboard configuration. It addresses the need to support diverse PC hardware, different keyboard layouts, and non-standard keys by providing a direct way to map hardware scancodes to kernel-recognized keycodes. It has remained a stable and essential utility for low-level keyboard mapping and troubleshooting.

loadkeys(1), showkey(1), dumpkeys(1), xmodmap(1)