1 XKM File Format Description
6 The XKM file format is the exchange format for XKB keyboard descriptions
7 between the server and xkbcomp. Usually, the server forks off xkbcomp,
8 xkbcomp compiles the XKM format from the given parameters.
9 The resulting XKM file is put into a directory readable by the server and
12 The XKM format is little more than a binary dump of various XKB-specific
13 structures and hence tied to the ABI of the server.
17 1.1 About this file format description
19 This description was produced by analyzing the XKM parsing code. Parts of
20 the file description present in the original format specification may be
21 missing. This description thus cannot be a reference document for XKM
24 No description of the meaning of the various fields is given here. Refer to
25 the XKB protocol specification for more details.
28 2. Notations used in this document
30 Notation for structures:
34 name of field: type or fixed value of field
35 name of field: type or fixed value of field
38 Data types are identical to those used in the X Protocol specification
39 except where noted otherwise. Structs specific to XKM are prefixed with XKM,
40 defines specific to the XKB protocol specification are prefixed with Xkb and
41 their value is equivalent to that in the protocol specification.
43 Multiple instances of a given type are denoted in the following form:
44 name of field: LISTofFIELDTYPE
46 Length specifiers for such fields are usually prefixed with num_. For
47 example, a struct containing a num_foo of 8 and a 'foo' field contains 8
48 structures of type 'foo'.
50 Variable length padding is specified as pad(x), where x is the length of the
51 data to be padded out to a multiple of 4 bytes. For example, given an x of
52 10, pad(x) would be the remaining 2 bytes to pad the whole struct to 12
55 A special notation is a variable content struct. In this case, the contents
56 of the struct depend on the value of one or more specific fields.
59 field: type or fixed value of field
60 field: type or fixed value of field
72 This notation denotes that if field is of value 1, this struct contains the
73 specific fields listed underneath value 1.
79 The XKM format is a binary format with structs usually being padded to a
80 multiple of 4 bytes. No provisions for endianess are provided, the parser is
81 left to guess the endianess of the XKM file.
93 XKMCountedString is used for user-readable identifiers. Prime example are
94 the level names and the section names ("complete", "evdev(inet)", etc.)
106 3.2 Header and Table of Contents
116 The XKM file format has a 4 byte header identifying the file and the XKM
117 version. The header is followed by the table of contents indicating the
118 sections present in this file.
125 num_sectioninfo: CARD8
128 sectioninfo: LISTofXKMSectionInfo
131 min_keycode and max_keycode specify the keycode range for this keyboard
132 descriptions. The core protocol requires min_keycode always be equal to or
144 XkmVirtualModsIndex 6
150 Describes the section found in a chunk of a file. This struct is found
151 _twice_ in the file per section, once as part of the XKMFileInfo, once at
152 the beginning of the actual section (see offset).
153 The type specifies the type of the section, the section is to be parsed
154 according to this type.
155 Size and offset specify the size in bytes and the offset into the file in
160 Each section resides at the offset specified in the XKMFileInfo sectioninfo.
166 An XKMTypes section describes the key types defined in a layout. Roughly
167 speaking, a key type defines how many levels a given key has and which
168 modifiers change to a particular level.
172 section_info: XKMSectionInfo
173 name: XKMCountedString
176 types: LISTofXKMKeyType
184 num_map_entries: CARD8
185 num_level_names: CARD8
188 map_entries: LISTofXKMKTMapEntry
189 name: XKMCountedString
190 mods: LISTofXKMModsDesc
191 level_names: LISXTofXKMCountedString
194 The num_map_entries specifies the number of structs in both map_entries and mods. mods is only present if preserve is TRUE.
213 An XKMCompatMap section describes the actions a keyboard may trigger. This
214 ranges from the TerminateServer action to simple modifier bits.
218 section_info: XKMSectionInfo
219 name: XKMCountedString
221 group_mask: XKMGroupBits
223 si: LISTofXKMSymInterpreterDesc
224 groups: LISTofXKMModsDesc
227 One XKMModsDesc is present for each bit set in group_mask.
237 action_data: XKMActionData
240 Where the action is 7 bytes of CARD8 whose content is determined by
249 action_type ⇒ XkbSA_SetMods ||
250 action_type ⇒ XkbSA_LatchMods ||
251 action_type ⇒ XkbSA_LockMods
260 action_type ⇒ XkbSA_SetGroup ||
261 action_type ⇒ XkbSA_LatchGroup ||
262 action_type ⇒ XkbSA_LockGroup
269 action_type ⇒ XkbSA_MovePtr
278 action_type ⇒ XkbSA_PtrBtn ||
279 action_type ⇒ XkbSA_LockPtrBtn
286 action_type ⇒ XkbSA_DeviceBtn ||
287 action_type ⇒ XkbSA_LockLockPtrBtn
296 action_type ⇒ XkbSA_SetPtrDflt
303 action_type ⇒ XkbSA_ISOLock
313 action_type ⇒ XkbSA_SwitchScreen
320 action_type ⇒ XkbSA_SetControls ||
321 action_type ⇒ XkbSA_LockControls
330 action_type ⇒ XkbSA_RedirectKey
340 action_type ⇒ XkbSA_DeviceValuator
351 action_type ⇒ XkbSA_XFree86Private ||
352 action_type ⇒ XkbSA_Terminate
358 action_type ⇒ XkbSA_ActionMessage
366 Note: XkbSA_ActionMessage is currently unsupported and the contents are
372 The symbols in a keymap define the actual keysyms each key may produce.
376 section_info: XKMSectionInfo
377 name: XKMCountedString
380 group_names_mask: XKMGroupBits
382 group_names: LISTofXKMCountedString
383 keysyms: XKMKeysymMapDesc
384 vmod_maps: XKMVModMapDesc
386 One group_name is present for each bit set in group_names_mask.
387 The number of keysyms present is max_keycode - min_keycode + 1.
395 names: LISTofXKMCountedString
397 behavior: XKMBehaviorDesc
400 Presence of names is conditional on the XkmKeyHasTypes flag. The number of
401 strings is equal to the number of group bits in group_names_mask in the
402 preceeding XKMSymbols section.
403 The number of elements in syms is equal to width * num_groups.
404 Presence of behavior is conditional on the XkmKeyHasBehavior flag.
426 section_info: XKMSectionInfo
427 name: XKMCountedString
428 num_indicators: CARD8
431 indicators: LISTofXKMIndicatorMapDesc
436 name: XKMCountedString
452 section_info: XKMSectionInfo
453 name: XKMCountedString
458 keynames: LISTofXKMKeyname
459 aliases: LISTofXKMKeyAlias
462 keynames contains max_keycode - min_keycode + 1 entries.
481 section_info: XKMSectionInfo
482 name: XKMCountedString
485 base_color_ndx: CARD8
486 label_color_ndx: CARD8
487 num_properties: CARD16
492 num_key_aliases: CARD16
494 label_font: XKMCountedString
495 properties: LISTofXKMGeomProperty
496 colors: LISTofXKMCountedString
497 shapes: LISTofXKMGeomShape
498 sections: LISTofXKMGeomSection
499 doodads: LISTofXKMGeomDoodad
500 key_aliases: LISTofXKMKeyAlias
505 name: XKMCountedString
506 value: XKMCountedString
512 name: XKMCountedString
517 outlines: LISTofXKMOutlineDesc
525 points: LISTofXKMPointDesc
536 name: XKMCountedString
547 rows: LISTofXKMRowDesc
548 doodads: LISTofXKMGeomDoodad
549 overlays: LISTofXKMGeomOverlay
572 name: XKMCountedString
581 type ⇒ XkbOutlineDoodad ||
582 type ⇒ XkbSolideDoodad
606 text: XKMCountedString
607 font: XKMCountedString
609 type ⇒ XkbIndicatorDoodad
633 logo_name: XKMCountedString
636 WARNING: XKMGeomDoodad has variable length depending on the type.
637 NOTE: The current server implementation does not use all fields of all
642 name: XKMCountedString
646 rows: LISTofXKMOverlayRowDesc
651 name: XKMCountedString
655 keys: LISTofXKMOverlayKeyDesc
670 section_info: XKMSectionInfo
671 name: XKMCountedString
672 bound_mask: SETofVMODBITS
673 named_mask: SETofVMODBITS
676 names: LISTofXKMCountedString
681 Number of elements in vmods is equal to the number of bits set in
682 bound_mask. The padding completes vmods to a multiple of 4 byte units.
683 Number of elements in names is equal to the number of bits set in