---
name: "XGetDeviceKeyMapping"
section: "3x"
platform: "linux"
package: "libxi-dev"
version: "4.3.0.dfsg.1-14sarge7"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/XGetDeviceKeyMapping/3x"
---

# XGetDeviceKeyMapping(3x)

query or change device key mappings

## NAME

XGetDeviceKeyMapping, XChangeDeviceKeyMapping - query or change device key mappings

## SYNTAX

**int XChangeDeviceKeyMapping(Display \****display***, XDevice** **\****device***, int** *first\_keycode***, int** *keysyms\_per\_keycode***,** **KeySym \****keysyms***, int** *keycode\_count***);**

**KeySym \*XGetDeviceKeyMapping(Display \****display***, XDevice** **\****device***, KeyCode** *first\_keycode***, int** *keycode\_count***, int** **\****keysyms\_per\_keycode\_return***);**

## ARGUMENTS

- *display*

  *Specifies the connection to the X server.*

- *device*

  *Specifies the device whose key mapping is to be queried or modified.*

- *first\_keycode*

  *Specifies the first KeyCode to be returned.*

- *keycode\_count*

  *Specifies the number of KeyCodes to be returned or modified.*

- *keysyms\_per\_keycode*

  *Specifies the number of KeySyms per KeyCode.*

- *keysyms\_per\_keycode\_return*

  *Specifies the address of a variable into which the number of KeySyms per KeyCode* *will be returned.*

- *keysyms*

  *Specifies the address of an array of KeySyms.*

## DESCRIPTION

*For the specified device,* *the XGetDeviceKeyMapping request returns* *the symbols for the specified number of KeyCodes* *starting with first\_keycode.* *The value specified in first\_keycode must be greater than*  *or equal to min\_keycode as returned by* *XListInputDevices,*  *or a* *BadValue* *error results.* *In addition, the following expression must be less than or equal*  *to max\_keycode as returned by* *XListInputDevices:*

*first\_keycode + keycode\_count - 1*

*If this is not the case, a*  *BadValue* *error results.*  *The number of elements in the KeySyms list is:*

*keycode\_count \* keysyms\_per\_keycode\_return*

*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.*  *A special KeySym value of*  *NoSymbol* *is used to fill in unused elements for* *individual KeyCodes.* *To free the storage returned by*  *XGetDeviceKeyMapping,* *use* *XFree.*

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

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

*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 remain unchanged.*   *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.* *In addition, the following 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 specified keysyms\_per\_keycode can be chosen arbitrarily by the client* *to be large enough to hold all desired symbols.*  *A special KeySym value of*  *NoSymbol* *should be used to fill in unused elements*  *for individual KeyCodes.*   *It is legal for*  *NoSymbol*  *to appear in nontrailing positions* *of the effective list for a KeyCode.* *XChangeDeviceKeyMapping generates a DeviceMappingNotify* *event that is sent to all clients that have selected that type of event.*

*There is no requirement that the X server interpret this mapping.*  *It is merely stored for reading and writing by clients.*

*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.*

- *BadMatch*

  *This error may occur if an XGetDeviceKeyMapping or*  *XChangeDeviceKeyMapping request was made*  *specifying* *a device that has no keys.*

- *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.*

## SEE ALSO

*XSetDeviceButtonMapping(3X11)* \
 *XSetDeviceModifierMapping(3X11)* \
 *Programming with Xlib*