Extensible structure ABI contract

Collaboration diagram for Extensible structure ABI contract:

Data Structures
struct	xkb_keymap_serialize_config
struct	xkb_keymap_serialize_result
struct	xkb_keymap_key_iterator_config
struct	xkb_event_components
struct	xkb_event_pointer_motion
struct	xkb_event_pointer_button
struct	xkb_events_config
struct	xkb_machine_builder_config
struct	xkb_machine_builder_a11y_update
struct	xkb_machine_builder_mods_remap_update
struct	xkb_machine_builder_shortcut_override_update
struct	xkb_state_components_update
struct	xkb_layout_policy_update
struct	xkb_state_update

Detailed Description

Explains how extensible structures maintain ABI compatibility across library releases.

To guarantee long-term backward and forward compatibility of the ABI, functions across this library accept extensible structures that share a common ABI contract.

Layout

Every extensible structure begins with a mandatory uint32_t size first field and must not contain any implicit padding: every alignment gap is filled explicitly with a reserved field, each sized for the platform with the strictest alignment requirements and verified via static_assert.

struct Example {
    uint32_t size;
    uint8_t a;
    uint8_t reserved0[3];
    char *b;
    uint32_t c;
    uint32_t reserved1; // padding for 64-bit platforms
};

size specifies the byte size of the structure, as provided by the caller. It has a fixed-width type uint32_t so that its representation is independent of the platform’s native size_t width.

A structure’s reserved fields (reserved0, reserved1, …) either fill an alignment gap or pre-allocate space for a future field. They are numbered in declaration order; when one is later repurposed (see Compatibility guarantees), remaining reserved fields keep their names.

Structure initialization

When initializing an extensible structure, callers must:

• Set size to sizeof() of the structure.
• Zero every reserved field, e.g. by omitting them from a designated initializer (structures are padded explicitly) or using memset().

Example with omitted initializer

struct Example example = {
    .size = sizeof(example),
    .a = …,
    // .reserved0 is zeroed automatically
    .b = …,
    .c = …,
    // .reserved1 is zeroed automatically
};

Example with memset()

struct Example example;
memset(&example, 0, sizeof(example));
example.size = sizeof(example);
example.a = …;

Version resolution

When a function receives an extensible structure, it uses the caller- provided size to determine which fields are present, and validates any reserved field covered by that size:

Backward compatibility

The caller was built against an older header: caller’s size < library’s. Only the fields covered by size are read; the library never accesses memory past that boundary. Fields beyond it are treated as unset and fall back to their default behavior.

In the unlikely case that a missing field has no safe default for the requested operation, the call fails with XKB_ERROR_ABI_BACKWARD_COMPAT.

Forward compatibility

The caller was built against a header identical to or newer than the library: *caller’s size \≥ library’s* (note that equal size does not imply same version: Reserved fields below). Only the fields known to this version of the library are read. The trailing, unrecognized bytes (if any) are inspected only to check they are zero. If they are all zero, they are silently ignored: the caller is requesting default behavior for fields this library predates. If any are non-zero, the caller is explicitly requesting behavior this library version cannot provide, and the call fails with XKB_ERROR_ABI_FORWARD_COMPAT.

Reserved fields

Independently of the above, every reserved field covered by size must be zero. A non-zero value means the caller was built against a header where that field has since been given meaning — behavior this library version cannot honor — and the call fails with XKB_ERROR_ABI_FORWARD_COMPAT, the same code used for non-zero trailing bytes beyond size.

Invalid

If size is smaller than the very first released version of the struct (e.g. left uninitialized) or excessively big (e.g. corrupted), the call fails safely with XKB_ERROR_ABI_INVALID_STRUCT_SIZE.

Compatibility guarantees

This contract holds as long as fields are only ever appended to an extensible structure: never removed, reordered, or resized. A reserved field may later be repurposed by renaming it and giving it a new ABI-compatible type, so that the structure’s layout is unchanged. Under these rules:

• A binary built against an older header keeps working against a newer library.
• A binary built against a newer header keeps working against an older library, as long as it does not set any field the library predates — including any reserved field — to a non-default value.
• When a reserved field is repurposed, older callers that correctly zero-initialized it continue to work unmodified: zero was already the only value the contract allowed, and the new release simply defines that value as the field’s default.

Since

1.14.0