C Reference ยท Functions and Scope
Opaque types in C
Reference for opaque types in C: incomplete struct declarations, create and destroy functions, hiding fields behind a header, handles and trade-offs.
An opaque type is a type whose name is public but whose contents are hidden. The header declares struct stack; without a body (an incomplete type), and code outside the module can only hold pointers to it. Only the module's own source file defines the fields. Callers cannot read or change members, and cannot even take sizeof of it.
This is how C gets encapsulation. The standard library's FILE is used this way: you pass FILE * around but never touch what is inside. Opaque types let you change the structure later without recompiling or breaking callers, and they stop users from corrupting invariants.
/* stack.h */ typedef struct stack stack; /* incomplete type */ stack *stack_create(void); void stack_destroy(stack *s);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
The real benefit appears when the interface and implementation live in separate files. These two listings are read-only. Code in main.c that writes s->size would not compile:
/* stack.h */ typedef struct stack stack; stack *stack_create(void); /* main.c */ #include "stack.h" int main(void) { stack *s = stack_create(); /* s->size = 5; error: invalid use of incomplete type 'struct stack' */ /* stack t; error: storage size of 't' isn't known */ return s == 0; }
Syntax
struct name; /* declare an incomplete struct type */ typedef struct name name; /* optional alias */ name *create(void); /* only pointers can be used outside the module */ struct name { /* members */ }; /* completed in exactly one .c file */
| Part | Description |
|---|---|
| incomplete type | A type declared but not defined. You may form pointers to it and declare functions using those pointers, but not access members, create objects or use sizeof. |
| constructor | A function (create, open, new) that allocates and initializes the object and returns a pointer. |
| destructor | A function (destroy, close, free) that releases the object and everything it owns. |
Errors / undefined behavior: using the type after destroy is a use-after-free. Forgetting to call destroy leaks memory. Casting a pointer to an unrelated type to peek inside is a strict aliasing violation. Calling functions with NULL is undefined unless the interface says it is allowed.
Usage notes
- Why it helps. The compiler enforces that callers cannot touch fields, so you can rearrange them, add members, or change the layout without breaking callers (a stable binary interface for shared libraries).
- The cost is an allocation per object and an indirect access for every operation. Callers cannot put the object on their stack or in an array of values. If you need that, expose a struct with a documented size, or provide a function that tells the needed size and accepts caller memory.
- Be consistent about ownership. Document that
createreturns an owned pointer, whetherdestroy(NULL)is allowed (mirroringfree(NULL)), and what happens to child objects. - Hiding the star.
typedef struct impl *handle;makes code shorter but hides that the value is a pointer, and preventsconst handlefrom meaning a pointer to const data. Many style guides prefer to typedef the struct and keep*visible. - Names. Prefix all functions with the module name (
stack_), because C has no namespaces. Do not use names ending in_t, which POSIX reserves. - Testing. Opaque types make mocking by link-time replacement easier: tests link a different
stack.c. - Errors in constructors. Return
NULLon failure and make sure partially created resources are freed. - Shared libraries. For a stable ABI, never change the layout of publicly visible structs; opaque ones are the way out.