XGETDEVICEKEYMAPPING(3)

💅 XGETDEVICEKEYMAPPING(3) — query or change device key mappings ✨

okay so bestie, welcome to section 3 of the manual, this is the XGetDeviceKeyMapping / XChangeDeviceKeyMapping page and it is lowkey one of the most useful little gremlins in the XInput toolbox 🎀 if you've ever wanted to peek at a device's key mapping or straight up rewrite it, this is your moment. periodt.

---

📖 NAME 📖

XGetDeviceKeyMapping, XChangeDeviceKeyMapping — query or change device key mappings 💖

---

🌸 SYNOPSIS 🌸

#include <X11/extensions/XInput.h>

KeySym *XGetDeviceKeyMapping( Display *display,
                              XDevice *device,
                              KeyCode first_keycode,
                              int keycode_count,
                              int *keysyms_per_keycode_return);

and here's who's who in the cast 🫶:

• display — the connection to the X server. your lil phone line to the server, basically.
• device — the device whose key mapping is gonna be queried or modified. main character energy right here 👑
• first_keycode — the first KeyCode to be returned.
• keycode_count — how many KeyCodes to return or modify.
• keysyms_per_keycode — the number of KeySyms per KeyCode.
• keysyms_per_keycode_return — the address of a variable where the number of KeySyms per KeyCode gets handed back to you. it's giving "here's your receipt" 🧾
• keysyms — the address of an array of KeySyms.

---

✨ DESCRIPTION ✨

so for the device you picked, the XGetDeviceKeyMapping request returns the symbols for the specified number of KeyCodes starting with first_keycode. easy. but there's a rule, bestie: the value you put in first_keycode must be greater than or equal to min_keycode as returned by XListInputDevices, or a BadValue error results 😭 no cap. and also this expression has to be less than or equal to max_keycode as returned by XListInputDevices:

first_keycode + keycode_count - 1

if that's not the case, BadValue error, again. sorry, them's the rules 💀

the number of elements in the KeySyms list is:

keycode_count * keysyms_per_keycode_return

and KeySym number N, counting from zero, for KeyCode K has the following index in the list, counting from zero:

(K - first_code) * keysyms_per_code_return + N

the X server arbitrarily chooses the keysyms_per_keycode_return value to be large enough to report all requested symbols (server does what it wants, honestly, we respect it 💅). a special KeySym value of NoSymbol is used to fill in unused elements for individual KeyCodes. and to free the storage returned by XGetDeviceKeyMapping, use XFree. do NOT forget to free it, leaking memory is not the vibe 🚫

if the specified device does not support input class keys, a BadMatch error will result.

XGetDeviceKeyMapping can generate a BadDevice, BadMatch, or BadValue error.

---

okay now the other one, the spicy one 🔥

for the specified device, the XChangeDeviceKeyMapping request defines the symbols for the specified number of KeyCodes starting with first_keycode. the symbols for KeyCodes outside this range stay exactly as they were — untouched, unbothered, living their truth 🌸. the number of elements in keysyms must be:

num_codes * keysyms_per_keycode

the specified first_keycode must be greater than or equal to min_keycode returned by XListInputDevices, or a BadValue error results. and in addition, this next expression must be less than or equal to max_keycode as returned by XListInputDevices, or a BadValue error results:

first_keycode + num_codes - 1

KeySym number N, counting from zero, for KeyCode K has the following index in keysyms, counting from zero:

(K - first_keycode) * keysyms_per_keycode + N

the keysyms_per_keycode you specify can be chosen arbitrarily by the client, as long as it's large enough to hold all the desired symbols. a special KeySym value of NoSymbol should be used to fill in unused elements for individual KeyCodes. and here's a fun fact: it is legal for NoSymbol to appear in nontrailing positions of the effective list for a KeyCode 👀 (yes, really, in the middle and everything, iconic). XChangeDeviceKeyMapping generates a DeviceMappingNotify event that gets sent to all clients that have selected that type of event. everybody finds out, it's a group chat notification fr fr 📣

there is no requirement that the X server interpret this mapping. it is merely stored for reading and writing by clients. the server is just the storage unit here, not a hater, not a translator, just vibes 🧚

if the specified device does not support input class keys, a BadMatch error results.

XChangeDeviceKeyMapping can generate a BadDevice, BadMatch, BadAlloc, or BadValue error.

---

🩺 DIAGNOSTICS 🩺

• BadDevice — an invalid device was specified. the specified device does not exist, or has not been opened by this client via XOpenInputDevice. this error may also occur if the specified device is the X keyboard or X pointer device. (rude, but okay 🙈)
• BadMatch — this error may occur if an XGetDeviceKeyMapping or XChangeDeviceKeyMapping request was made specifying a device that has no keys. no keys, no mapping, no service 💀
• BadValue — some numeric value falls outside the range of values accepted by the request. unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. any argument defined as a set of alternatives can generate this error.
• BadAlloc — the server failed to allocate the requested resource or server memory. the server is tired, bestie, it needs a nap 😭

---

👀 SEE ALSO 👀

• XSetDeviceButtonMapping(3)
• XSetDeviceModifierMapping(__3_)

go read those next, they're the sibling pages and they also ate 💅

---

and that's the whole page, bestie 🫶 go forth and map those keys responsibly.

this was the XGetDeviceKeyMapping(3) page from the XInput manual, dated 05/18/2026, and honestly? she served. mwah 💖✨🎀🦋