Skip to content

Case 54: Used Reserved Field

Field Value
Verdict 🟢 COMPATIBLE
Category Quality (Compatible)
Platforms Linux, macOS
Flags —
Detected ChangeKinds used_reserved_field
Source files browse on GitHub

Category: Type Layout | Verdict: COMPATIBLE

What this case is about

v1 has a struct Config with __reserved1 and __reserved2 placeholder fields. v2 renames them to priority and max_retries at the same offsets with the same types. The struct size and layout are unchanged.

This is the correct way to evolve a struct: reserve padding fields upfront, then activate them in later versions without breaking ABI.

What abicheck detects

  • USED_RESERVED_FIELD: abicheck has a dedicated detector (_diff_reserved_fields) that recognizes patterns like __reserved, _reserved, __pad, _unused being renamed to meaningful names at the same offset. This is classified as COMPATIBLE.

Overall verdict: COMPATIBLE (layout unchanged, reserved slots activated as intended).

How to reproduce

gcc -shared -fPIC -g bad.c  -include bad.h  -o libbad.so
gcc -shared -fPIC -g good.c -include good.h -o libgood.so

python3 -m abicheck.cli dump libbad.so  -o /tmp/v1.json
python3 -m abicheck.cli dump libgood.so -o /tmp/v2.json
python3 -m abicheck.cli compare /tmp/v1.json /tmp/v2.json
# → COMPATIBLE + USED_RESERVED_FIELD note

Design pattern

/* v1: reserve slots for future use */
typedef struct {
    int version;
    int __reserved1;  /* ← will become priority */
    int __reserved2;  /* ← will become max_retries */
    int flags;
} Config;

/* v2: activate reserved slots */
typedef struct {
    int version;
    int priority;       /* was __reserved1 */
    int max_retries;    /* was __reserved2 */
    int flags;
} Config;

Real-world examples

  • Linux kernel's struct stat uses __unused / __st_ino fields
  • glibc's pthread_attr_t has reserved space for future extensions
  • Wayland protocol structs use __padding fields

References

Source files

See also: Examples overview · All COMPATIBLE cases · Category: Quality (Compatible).