XGetDeviceKeyMapping(3X11)

NAME
       XGetDeviceKeyMapping,  XChangeDeviceKeyMapping  - query or
       change device key mappings

SYNTAX
       XChangeDeviceKeyMapping(display,  device,   first_keycode,
       keysyms_per_keycode, keysyms, keycode_count)
             Display *display;
             XDevice *device;
             int first_keycode;
             int keysyms_per_keycode;
             KeySym *keysyms;
             int keycode_count;

       KeySym *XGetDeviceKeyMapping(display, device, first_keycode, keycode_count,
       keysyms_per_keycode_return)
             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_key-
       code_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  Bad-
       Value  error  results.  In addition, the following expres-
       sion 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  arbitrar-
       ily  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  posi-
       tions  of  the  effective  list for a KeyCode.  XChangeDe-
       viceKeyMapping 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, Bad-
       Match, BadAlloc, or BadValue  error.

DIAGNOSTICS
       BadDevice   An invalid device was specified.   The  speci-
                   fied  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 XGetDeviceKeyMap-
                   ping 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 spe-
                   cific  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