Case 62: Type Field Added (Compatible — Opaque Struct)¶

Field	Value
Verdict	🟢 COMPATIBLE
Category	Addition (Compatible)
Platforms	Linux, macOS
Flags	—
Detected `ChangeKind`s	`func_added`
Source files	browse on GitHub

Category: Type Layout | Verdict: COMPATIBLE

What this case is about¶

v1 defines Session as an opaque struct with name and timeout fields. v2 adds a priority field at the end. Because callers only use Session* (never allocate, embed, or sizeof the struct), the change is ABI-compatible.

This is the correct design pattern for extensible C APIs: opaque handles + accessor functions allow adding fields without breaking existing consumers.

Why this is compatible¶

Callers never see the layout: Session is forward-declared in the header. All allocation is done by session_open() inside the library.
Existing field offsets unchanged: name and timeout are at the same offsets. Only a new field is appended.
Existing functions unchanged: session_get_name() and session_get_timeout() work identically.

Contrast with case07 (breaking)¶

Case 07 adds a field to a non-opaque struct that callers sizeof and embed — that's breaking. This case demonstrates the safe pattern.

What abicheck detects¶

TYPE_FIELD_ADDED: A new field was added to the struct.
FUNC_ADDED: session_get_priority() is a new symbol.

Overall verdict: COMPATIBLE

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: TYPE_FIELD_ADDED, FUNC_ADDED

Design pattern¶

/* PUBLIC HEADER — opaque pointer */
typedef struct Widget Widget;
Widget* widget_new(void);
void widget_free(Widget *w);

/* PRIVATE IMPLEMENTATION — can grow freely */
struct Widget {
    int x, y;
    int new_field;  /* ← safe to add */
};