Table of Contents

Definition

A union declaration defines a composite type where all members share the exact same memory address. Unlike structures, which allocate contiguous storage for each field, unions overlay their members, meaning only one member can hold a meaningful value at any given time. The declaration establishes the memory footprint, alignment requirements, and member types, serving as a blueprint for variable instantiation.

Syntax & Declaration Patterns

Pattern	Syntax	Characteristics
Standard Tagged	`union Color { uint32_t hex; uint8_t rgba[4]; };`	Requires tag for reuse. Members share offset `0`.
Typedef Alias	`typedef union Data { int i; float f; } Data;`	Declares type and alias simultaneously. Outside uses `Data var;`. Inside still requires `union Data` for recursive pointers.
Anonymous (C11)	`struct { int type; union { int count; float ratio; }; } msg;`	Members promoted to enclosing scope. Accessed as `msg.count`, not `msg.union.count`.
Pointer/Array	`union Config *cfg;` / `union Buffer pool[10];`	Declares variables, not types. Array elements are contiguous unions, not contiguous members.
Forward Declaration	`union Token;`	Incomplete type. Only usable for pointers (`union Token *ptr;`) until fully defined.

Memory Layout & Initialization Rules

Property	Behavior
Size	`sizeof(union) == max(sizeof(member)) + alignment_padding`
Alignment	Equals the strictest `alignof()` among all members
Default Init	Only the first member is zero-initialized if no explicit initializer is provided
Designated Init (C99+)	`union Data d = { .f = 3.14f };` initializes `f`, zeroes remaining storage, sets `f` as active
Partial Init	Omitted members are zero-initialized if at least one preceding member is explicitly set

union Value {
int i;
double d;
char tag;
};
// Variable declarations
union Value v1;                 // Uninitialized (indeterminate)
union Value v2 = { 42 };        // Initializes i (first member)
union Value v3 = { .d = 2.71 }; // Initializes d, zeroes others

Rules & Constraints

Single Active Member: Writing to one member overwrites all others. Only the most recently written member is guaranteed to hold valid data.
No Simultaneous Values: Initializing or assigning multiple members is illegal. The compiler uses only the last specified initializer.
Strict Aliasing Exemption: In C, accessing union members for type-punning is explicitly exempt from strict aliasing rules. This differs from C++, where it invokes undefined behavior.
C23 Inactive Member Access: Reading a non-active union member is now well-defined. It reinterprets the object representation of the active member according to the accessed type's rules.
Scope & Linkage: Follows standard C rules. File-scope declarations have external linkage by default. static restricts to internal linkage. Block-scope has no linkage.
Incomplete Type Restriction: Direct members must be fully defined. Pointers to incomplete union types are allowed for forward references.

Best Practices

Pair with enum discriminant: Track the active member explicitly to prevent misinterpretation.

   typedef enum { TYPE_INT, TYPE_FLOAT } VariantTag;
typedef struct { VariantTag tag; union { int i; float f; } data; } SafeVariant;

Use designated initializers: Clearly state which member is active and zero the rest: union U u = { .active_field = val };
Validate layout statically: _Static_assert(sizeof(union U) == expected, "Unexpected padding");
Prefer anonymous unions in structs: Flattens namespace for cleaner API access while preserving memory efficiency.
Document endianness & padding: When mapping unions to hardware or networks, explicitly state byte-order expectations and provide conversion helpers.
Avoid in cross-language APIs: C++ treats inactive member access as undefined. Use explicit serialization or memcpy for interoperability.

Common Pitfalls

🔴 Assuming independent storage: Modifying u.i changes u.f's underlying bytes. Treating them as separate fields corrupts data.
🔴 Size confusion: sizeof(union) != Σ sizeof(member). Misallocating memory for union arrays causes truncation or overflow.
🔴 Uninitialized active member: Accessing u.i without prior assignment reads indeterminate stack/heap data.
🔴 Ignoring padding in serialization: Unions may contain compiler-inserted padding. Direct fwrite(&u) breaks across toolchains.
🔴 Endianness dependence: union { uint32_t w; uint8_t b[4]; } yields reversed bytes on big-endian systems. Fails without explicit conversion.
🔴 Mixing with bitfields unpredictably: Bitfield layout inside unions is implementation-defined. Order, packing, and alignment vary by compiler.
🔴 Assuming C++ compatibility: Union type-punning is well-defined in C but undefined in C++. Cross-language code must avoid it.

Standards & Tooling Evolution

C89/C90: Introduced union declaration syntax and overlapping storage semantics. Inactive member access left implementation-defined.
C99: Added designated initializers, improving clarity and safety for union instantiation.
C11: Introduced anonymous unions, enabling flattened variant structs and cleaner composite APIs.
C17: Maintained semantics. Clarified alignment and padding rules for complex union layouts.
C23: Major clarification. Reading inactive members is explicitly well-defined as object representation reinterpretation. Eliminates historical type-punning ambiguity.
Compiler Diagnostics:
-Wmissing-field-initializers: Catches partially initialized unions
-Wpadded: Warns when compiler inserts padding due to member order
-fplan9-extensions: GCC/Clang enable anonymous union extensions for legacy compatibility
Static Analysis: clang-tidy, cppcheck, and Coverity flag untagged unions, unsafe inactive member access, and missing discriminant tracking.
Debugging Support: GDB/LLDB display all union members simultaneously. Use ptype union_name to inspect layout, and print u.member to verify active state during step-through.

Union declaration in C provides precise, low-overhead memory overlapping. When paired with explicit state tracking, standardized initialization, and careful layout verification, it enables efficient variant modeling, hardware interfacing, and protocol parsing while avoiding common aliasing and padding pitfalls.

Complete C Programming Guide + Compilers Collection

1. C srand() Function – Understanding Seed Initialization

https://macronepal.com/understanding-the-c-srand-function
Explains how srand() initializes the pseudo-random number generator in C by setting a seed value. Using the same seed produces the same sequence, while time(NULL) gives different results each run.

2. C rand() Function Mechanics and Limitations

https://macronepal.com/c-rand-function-mechanics-and-limitations
Explains how rand() generates pseudo-random numbers between 0 and RAND_MAX, its deterministic nature, and limitations for security use cases.

3. C log() Function

https://macronepal.com/c-log-function-2
Covers natural logarithm calculation using <math.h> and its applications.

4. Mastering Date and Time in C

https://macronepal.com/mastering-date-and-time-in-c
Explains <time.h> functions like time(), clock(), difftime(), and struct tm.

5. Mastering time_t Type in C

https://macronepal.com/mastering-the-c-time_t-type-for-time-management
Explains time representation as seconds since Unix epoch and conversion functions.

6. C exp() Function

https://macronepal.com/c-exp-function-mechanics-and-implementation
Explains exponential function exp(x) and its scientific applications.

7. C log() Function (Alternate Guide)

https://macronepal.com/c-log-function
Comparison of log() and log10() with usage examples.

8. C log10() Function

https://macronepal.com/mastering-the-log10-function-in-c
Explains base-10 logarithm for engineering and scientific applications.

9. C tan() Function

https://macronepal.com/understanding-the-c-tan-function
Explains tangent function and radian-based calculations.

10. Random Numbers in C (Secure vs Predictable)

https://macronepal.com/mastering-c-random-numbers-for-secure-and-predictable-applications
Explains difference between rand() and secure randomness methods.

11. Free Online C Compiler

https://macronepal.com/free-online-c-code-compiler-2
Browser-based compiler for testing C programs instantly.

C Functions, Arguments, Parameters & Flow

Mastering Functions in C – Complete Guide

https://macronepal.com/c/mastering-functions-in-c-a-complete-guide/
Covers function structure, modular programming, and real-world usage.

Function Arguments in C

https://macronepal.com/c-function-arguments/
Explains how arguments are passed and used in function calls.

Function Parameters in C

https://macronepal.com/c-function-parameters/
Explains defining inputs for functions and matching them with arguments.

Function Declarations in C

https://macronepal.com/c-function-declarations-syntax-rules-and-best-practices/
Covers prototypes, syntax rules, and best practices.

Function Calls in C

https://macronepal.com/understanding-function-calls-in-c-syntax-mechanics-and-best-practices/
Explains execution flow and parameter handling during function calls.

Void Functions in C

https://macronepal.com/understanding-void-functions-in-c-syntax-patterns-and-best-practices/
Explains functions that do not return values.

Return Values in C

https://macronepal.com/c-return-values-mechanics-types-and-best-practices/
Explains different return types and how functions return results.

Pass-by-Value in C

https://macronepal.com/aws/understanding-pass-by-value-in-c-mechanics-implications-and-best-practices/
Explains how copies of variables are passed into functions.

Pass-by-Reference in C

https://macronepal.com/c/understanding-pass-by-reference-in-c-pointers-semantics-and-safe-practices/
Explains using pointers to modify original variables.

C strstr() Function

https://macronepal.com/aws/c-strstr-function/
Explains substring search inside strings in C.

C Preprocessor & Macros

C Structures, Memory, Scope & Linkage

C Scope, Storage Classes & Typedef

Extra Articles

https://macronepal.com/13757-2/
https://macronepal.com/13748-2/
https://macronepal.com/13747-2/
https://macronepal.com/13746-2/
https://macronepal.com/13745-2/
https://macronepal.com/13708-2/
https://macronepal.com/13707-2/
https://macronepal.com/13702-2/

Online Compilers