libxkbcommon  1.11.0
Library implementing the XKB specification for parsing keyboard descriptions and handling keyboard state
Macros | Enumerations | Functions
Keymap Creation

Macros

#define XKB_KEYMAP_USE_ORIGINAL_FORMAT   ((enum xkb_keymap_format) -1)
 

Enumerations

enum  xkb_keymap_compile_flags { XKB_KEYMAP_COMPILE_NO_FLAGS = 0 }
 
enum  xkb_keymap_format {
  XKB_KEYMAP_FORMAT_TEXT_V1 = 1 ,
  XKB_KEYMAP_FORMAT_TEXT_V2 = 2
}
 

Functions

XKB_EXPORT struct xkb_keymapxkb_keymap::xkb_keymap_new_from_rmlvo (const struct xkb_rmlvo_builder *rmlvo, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
 
XKB_EXPORT struct xkb_keymapxkb_keymap::xkb_keymap_new_from_names (struct xkb_context *context, const struct xkb_rule_names *names, enum xkb_keymap_compile_flags flags)
 
XKB_EXPORT struct xkb_keymapxkb_keymap::xkb_keymap_new_from_names2 (struct xkb_context *context, const struct xkb_rule_names *names, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
 
XKB_EXPORT struct xkb_keymapxkb_keymap::xkb_keymap_new_from_file (struct xkb_context *context, FILE *file, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
 
XKB_EXPORT struct xkb_keymapxkb_keymap::xkb_keymap_new_from_string (struct xkb_context *context, const char *string, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
 
XKB_EXPORT struct xkb_keymapxkb_keymap::xkb_keymap_new_from_buffer (struct xkb_context *context, const char *buffer, size_t length, enum xkb_keymap_format format, enum xkb_keymap_compile_flags flags)
 
XKB_EXPORT struct xkb_keymapxkb_keymap::xkb_keymap_ref (struct xkb_keymap *keymap)
 
XKB_EXPORT void xkb_keymap::xkb_keymap_unref (struct xkb_keymap *keymap)
 
XKB_EXPORT char * xkb_keymap::xkb_keymap_get_as_string (struct xkb_keymap *keymap, enum xkb_keymap_format format)
 

Detailed Description

Creating and destroying keymaps.

Macro Definition Documentation

◆ XKB_KEYMAP_USE_ORIGINAL_FORMAT

#define XKB_KEYMAP_USE_ORIGINAL_FORMAT   ((enum xkb_keymap_format) -1)

Get the keymap as a string in the format from which it was created.

See also
xkb_keymap::xkb_keymap_get_as_string()

Enumeration Type Documentation

◆ xkb_keymap_compile_flags

Flags for keymap compilation.

Enumerator
XKB_KEYMAP_COMPILE_NO_FLAGS 

Do not apply any flags.

◆ xkb_keymap_format

The possible keymap formats.

See The XKB keymap text format, V1 and V2 for the complete description of the formats and Keymap support for detailed differences between the formats.

Remarks
A keymap can be parsed in one format and serialized in another, thanks to automatic fallback mechanisms.
Keymap format to use depending on the target protocol

Protocol

libxkbcommon keymap format

Name

Keymap format

Parsing

Serialization </thead> <tbody>

X11

XKB

XKB_KEYMAP_FORMAT_TEXT_V1

Always use XKB_KEYMAP_FORMAT_TEXT_V1, since the other formats are incompatible.

Wayland

xkb_v1

Wayland compositors
The format depends on the keyboard layout database (usually xkeyboard-config). Note that since v2 is a superset of v1, compositors are encouraged to use XKB_KEYMAP_FORMAT_TEXT_V2 whenever possible.
Client apps
Clients should use XKB_KEYMAP_FORMAT_TEXT_V1 to parse the keymap sent by a Wayland compositor, at least until XKB_KEYMAP_FORMAT_TEXT_V2 stabilizes.

At the time of writing (July 2025), the Wayland xkb_v1 keymap format is only defined as “libxkbcommon compatible”. In theory it enables flexibility, but the set of supported features varies depending on the libxkbcommon version and libxkbcommon keymap format used. Unfortunately there is currently no Wayland API for keymap format negotiation.

Therefore the recommended serialization format is XKB_KEYMAP_FORMAT_TEXT_V1, in order to ensure maximum compatibility for interchange.

Serializing using XKB_KEYMAP_FORMAT_TEXT_V2 should be considered experimental, as some clients may fail to parse the resulting string. </tbody>

Enumerator
XKB_KEYMAP_FORMAT_TEXT_V1 

The classic XKB text format, as generated by xkbcomp -xkb.

@important This format should always be used when serializing a keymap for X11.

@important For the Wayland xkb_v1 format, it is advised to use this format as well for serializing, in order to ensure maximum compatibility for interchange.

XKB_KEYMAP_FORMAT_TEXT_V2 

Xkbcommon extensions of the classic XKB text format, incompatible with X11.

@important Do not use when serializing a keymap for X11 (incompatible).

@important Considered experimental when serializing for Wayland: at the time of writing (July 2025), there is only one XKB keymap format xkb_v1 in Wayland and no Wayland API for keymap format negotiation, so the clients may not be able to parse the keymap if it uses v2-specific features. Therefore a compositor may parse keymaps using XKB_KEYMAP_FORMAT_TEXT_V2 but it should serialize them using XKB_KEYMAP_FORMAT_TEXT_V1 and rely on the automatic fallback mechanisms.

Since
1.11.0

Function Documentation

◆ xkb_keymap_new_from_rmlvo()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_rmlvo ( const struct xkb_rmlvo_builder rmlvo,
enum xkb_keymap_format  format,
enum xkb_keymap_compile_flags  flags 
)

Create a keymap from a RMLVO builder.

The primary keymap entry point: creates a new XKB keymap from a set of RMLVO (Rules + Model + Layouts + Variants + Options) names.

Parameters
rmlvoThe RMLVO builder to use. See xkb_rmlvo_builder.
formatThe text format of the keymap file to compile.
flagsOptional flags for the keymap, or 0.
Returns
A keymap compiled according to the RMLVO names, or NULL if the compilation failed.
Since
1.11.0
See also
xkb_keymap_new_from_names2()
xkb_rmlvo_builder

◆ xkb_keymap_new_from_names()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_names ( struct xkb_context context,
const struct xkb_rule_names names,
enum xkb_keymap_compile_flags  flags 
)

Create a keymap from RMLVO names.

Same as xkb_keymap_new_from_names2(), but with the keymap format fixed to: XKB_KEYMAP_FORMAT_TEXT_V2.

Deprecated:
Use xkb_keymap_new_from_names2() instead.
Since
1.11.0: Deprecated
1.11.0: Use internally XKB_KEYMAP_FORMAT_TEXT_V2 instead of XKB_KEYMAP_FORMAT_TEXT_V1
See also
xkb_keymap_new_from_names2()
xkb_rule_names
xkb_keymap_new_from_rmlvo()

◆ xkb_keymap_new_from_names2()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_names2 ( struct xkb_context context,
const struct xkb_rule_names names,
enum xkb_keymap_format  format,
enum xkb_keymap_compile_flags  flags 
)

Create a keymap from RMLVO names.

The primary keymap entry point: creates a new XKB keymap from a set of RMLVO (Rules + Model + Layouts + Variants + Options) names.

Parameters
contextThe context in which to create the keymap.
namesThe RMLVO names to use. See xkb_rule_names.
formatThe text format of the keymap file to compile.
flagsOptional flags for the keymap, or 0.
Returns
A keymap compiled according to the RMLVO names, or NULL if the compilation failed.
See also
xkb_rule_names
xkb_keymap_new_from_rmlvo()
Since
1.11.0

◆ xkb_keymap_new_from_file()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_file ( struct xkb_context context,
FILE *  file,
enum xkb_keymap_format  format,
enum xkb_keymap_compile_flags  flags 
)

Create a keymap from a keymap file.

Parameters
contextThe context in which to create the keymap.
fileThe keymap file to compile.
formatThe text format of the keymap file to compile.
flagsOptional flags for the keymap, or 0.
Returns
A keymap compiled from the given XKB keymap file, or NULL if the compilation failed.

The file must contain a complete keymap. For example, in the XKB_KEYMAP_FORMAT_TEXT_V1 format, this means the file must contain one top level xkb_keymap section, which in turn contains other required sections.

◆ xkb_keymap_new_from_string()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_string ( struct xkb_context context,
const char *  string,
enum xkb_keymap_format  format,
enum xkb_keymap_compile_flags  flags 
)

Create a keymap from a keymap string.

This is just like xkb_keymap_new_from_file(), but instead of a file, gets the keymap as one enormous string.

See also
xkb_keymap_new_from_file()

◆ xkb_keymap_new_from_buffer()

XKB_EXPORT struct xkb_keymap * xkb_keymap_new_from_buffer ( struct xkb_context context,
const char *  buffer,
size_t  length,
enum xkb_keymap_format  format,
enum xkb_keymap_compile_flags  flags 
)

Create a keymap from a memory buffer.

This is just like xkb_keymap_new_from_string(), but takes a length argument so the input string does not have to be zero-terminated.

See also
xkb_keymap_new_from_string()
Since
0.3.0

◆ xkb_keymap_ref()

XKB_EXPORT struct xkb_keymap * xkb_keymap_ref ( struct xkb_keymap keymap)

Take a new reference on a keymap.

Returns
The passed in keymap.

◆ xkb_keymap_unref()

XKB_EXPORT void xkb_keymap_unref ( struct xkb_keymap keymap)

Release a reference on a keymap, and possibly free it.

Parameters
keymapThe keymap. If it is NULL, this function does nothing.

◆ xkb_keymap_get_as_string()

XKB_EXPORT char * xkb_keymap_get_as_string ( struct xkb_keymap keymap,
enum xkb_keymap_format  format 
)

Get the compiled keymap as a string.

Parameters
keymapThe keymap to get as a string.
formatThe keymap format to use for the string. You can pass in the special value XKB_KEYMAP_USE_ORIGINAL_FORMAT to use the format from which the keymap was originally created. When used as an interchange format such as Wayland xkb_v1, the format should be explicit.
Returns
The keymap as a NULL-terminated string, or NULL if unsuccessful.

The returned string may be fed back into xkb_keymap_new_from_string() to get the exact same keymap (possibly in another process, etc.).

The returned string is dynamically allocated and should be freed by the caller.