Structs, Unions, Enums & Bitfields

A struct is a named collection of fields stored contiguously in memory, in declaration order. Each field has a type, a name, and — critically — a position determined by both the field order and alignment rules.

Declare and initialize a struct like this:

struct Point {
    int x;
    int y;
};

struct Point p1 = {3, 4};           // positional
struct Point p2 = {.x = 3, .y = 4}; // designated (preferred)

Access fields with . for a value and -> for a pointer:

struct Point *pp = &p1;
printf("%d %d\n", pp->x, pp->y);  // same as (*pp).x, (*pp).y

Structs are value types in C: assignment copies all fields. This is both a feature (no aliasing surprises) and a footgun (accidentally copying a 4 KB struct on every function call). Use pointers for large structs.

The key insight is that struct Point above will be exactly 8 bytes on any platform where int is 4 bytes, because both fields happen to have the same size and alignment. But change the field types and the layout can become surprising — that is the subject of the next concept.

#include <stdio.h>
#include <stddef.h>

struct Point { int x; int y; };

int main(void) {
    struct Point p = {.x = 10, .y = 20};
    printf("size=%zu  x@%zu  y@%zu\n",
           sizeof(struct Point),
           offsetof(struct Point, x),
           offsetof(struct Point, y));
    // Output: size=8  x@0  y@4
    return 0;
}

Every type has an alignment requirement: the address where a value of that type may be stored must be a multiple of its alignment. On most platforms char has alignment 1, short alignment 2, int and float alignment 4, and double/long long alignment 8. (These come from the ABI, not the C standard itself.)

When the compiler lays out a struct, it inserts padding bytes between fields (and sometimes at the end) to ensure each field starts at a properly aligned address.

Imagine memory as a number line. An int must sit at an address divisible by 4. If the previous field ended at an odd address, the compiler inserts silent padding bytes to push the int to the next multiple of 4.

struct Bad {
    char  a;   // 1 byte  @ offset 0
    // 3 bytes padding
    int   b;   // 4 bytes @ offset 4
    char  c;   // 1 byte  @ offset 8
    // 3 bytes padding (tail padding to align the struct itself)
};  // sizeof = 12, not 6!

The tail padding rule: a struct's total size is rounded up to a multiple of its largest field's alignment. This ensures that an array of structs keeps every element properly aligned.

Reordering fields saves memory: put the largest (most aligned) fields first:

struct Good {
    int   b;   // 4 bytes @ offset 0
    char  a;   // 1 byte  @ offset 4
    char  c;   // 1 byte  @ offset 5
    // 2 bytes tail padding
};  // sizeof = 8, not 12

Use offsetof(type, member) from <stddef.h> to inspect layout at compile time. Never hardcode byte offsets — they are platform-dependent.

#include <stdio.h>
#include <stddef.h>

struct Bad  { char a; int b; char c; };
struct Good { int b; char a; char c; };

int main(void) {
    printf("Bad:  size=%zu  b@%zu\n",
           sizeof(struct Bad),  offsetof(struct Bad,  b));
    printf("Good: size=%zu  b@%zu\n",
           sizeof(struct Good), offsetof(struct Good, b));
    // Bad:  size=12  b@4
    // Good: size=8   b@0
    return 0;
}

Sometimes you need a struct with no padding — most commonly when describing a binary protocol header (Ethernet frame, IP packet, USB descriptor) or a memory-mapped hardware register block where every byte has a precise meaning dictated by the spec.

GCC and Clang provide __attribute__((packed)) (and the equivalent #pragma pack(1)) to disable padding:

struct __attribute__((packed)) EthernetHeader {
    uint8_t  dst[6];
    uint8_t  src[6];
    uint16_t ethertype;
};
// sizeof = 14 exactly, matching the wire format

The cost: On architectures that require aligned access (ARM Cortex-M, older MIPS), reading a multi-byte field at an unaligned address will cause a bus fault (hardware exception) or, worse, silently read the wrong bytes. x86 allows unaligned access but pays a performance penalty.

The kernel solves this by using get_unaligned_le16() / get_unaligned_be32() helpers from <asm/unaligned.h> whenever it reads fields from packed structs. These emit memcpy-based loads that the compiler can optimize correctly for each architecture.

Rule of thumb: Use packed only at the boundary between your C code and a wire/storage format. Unpack into a normal struct immediately for internal use.

#include <stdint.h>
#include <stdio.h>
#include <stddef.h>

struct __attribute__((packed)) UsbSetup {
    uint8_t  bmRequestType;
    uint8_t  bRequest;
    uint16_t wValue;
    uint16_t wIndex;
    uint16_t wLength;
};

int main(void) {
    printf("size=%zu (expect 8)\n", sizeof(struct UsbSetup));
    printf("wValue@%zu (expect 2)\n", offsetof(struct UsbSetup, wValue));
    return 0;
}

A union is like a struct where all fields share the same memory. The union's size is the size of its largest member. Only one field is "valid" at a time — writing through one member and reading through another is called type punning.

The classic use case: represent a 32-bit IP address either as a single uint32_t or as four individual bytes:

union IPv4 {
    uint32_t addr;
    uint8_t  bytes[4];
};

Writing u.addr = 0xC0A80101 and reading u.bytes[0] gives you the first byte — but which byte depends on the endianness of the CPU. On a little-endian x86 machine bytes[0] is the least-significant byte (1), on big-endian it is the most-significant (192 = 0xC0).

Type punning via unions is defined behavior in C (C99 onward). The C standard explicitly allows reading a union member other than the last one written. This is not true in C++, which is why the kernel stays in C.

The aliasing trap: many C programmers try to type-pun via pointer casts:

float f = 1.0f;
uint32_t bits = *(uint32_t *)&f;  // UNDEFINED BEHAVIOR

The compiler is allowed to assume that a float* and a uint32_t* never alias the same memory (strict aliasing rule) and may optimize this to nonsense. Use a union or memcpy instead:

memcpy(&bits, &f, sizeof(bits));  // correct and optimizes to a register move

Unions are also used in the kernel for variant records — a struct that can hold one of several sub-structs depending on a tag field (a tagged union, the C equivalent of a Rust enum with data).

#include <stdint.h>
#include <stdio.h>
#include <string.h>

// Safe float-to-bits via union (C99 defined behavior)
union FloatBits {
    float    f;
    uint32_t u;
};

int main(void) {
    union FloatBits fb = { .f = 1.0f };
    printf("1.0f bits = 0x%08X\n", fb.u);  // 0x3F800000

    // Equivalent using memcpy (also defined, preferred in C++)
    float    val  = -0.0f;
    uint32_t bits;
    memcpy(&bits, &val, sizeof bits);
    printf("-0.0f bits = 0x%08X\n", bits);  // 0x80000000
    return 0;
}

An enum (enumeration) gives symbolic names to integer constants. The underlying type is int by default on most compilers.

enum Direction { NORTH, EAST, SOUTH, WEST };  // 0, 1, 2, 3
enum Color { RED = 1, GREEN = 2, BLUE = 4 };  // explicit powers of 2 for flags

Enums as type documentation: Using an enum parameter instead of a bare int tells readers (and linters) what values are legal. Many modern compilers warn on unhandled enum cases in switch statements, giving you free coverage analysis.

Enums as bit flags: the idiom of assigning powers of 2 to enum values lets you OR them together:

unsigned flags = RED | BLUE;  // 0x05

The kernel's approach: the kernel does not use C enums as much as you might expect. The reason is that enum's underlying storage type is implementation-defined (it is int by default, but the compiler may choose something else), making it fragile in packed binary interfaces. The kernel prefers explicit #define constants or fixed-width uint32_t flags instead. You will still see enums used for internal state machines and function arguments where the storage size does not matter.

Typedef enums: the kernel coding style avoids typedef for most types (it hides what something really is), but you will see the pattern typedef enum { ... } MyEnum; in userspace code to avoid writing enum every time.

#include <stdio.h>

enum State { IDLE = 0, RUNNING, SLEEPING, ZOMBIE };

const char *state_name(enum State s) {
    switch (s) {
    case IDLE:     return "idle";
    case RUNNING:  return "running";
    case SLEEPING: return "sleeping";
    case ZOMBIE:   return "zombie";
    }
    return "unknown";  // compiler warns if a case is missing with -Wall
}

int main(void) {
    enum State s = RUNNING;
    printf("state=%s  value=%d  sizeof=%zu\n",
           state_name(s), (int)s, sizeof(s));
    return 0;
}

A bitfield lets you declare a struct member that occupies a specific number of bits rather than whole bytes:

struct IPv4Header {
    unsigned int version  : 4;  // bits 0-3
    unsigned int ihl      : 4;  // bits 4-7
    unsigned int dscp     : 6;
    unsigned int ecn      : 2;
    unsigned int tot_len  : 16;
    // ...
};

Bitfields are appealing for hardware register maps and protocol headers because the code reads like the hardware datasheet. The compiler generates the bit-masking and shifting code automatically.

The portability minefield: The C standard leaves several things about bitfields implementation-defined:

• The order in which bits are packed within a storage unit (MSB-first or LSB-first)
• Whether int bitfields are signed or unsigned
• Whether bitfields can span a storage-unit boundary
• The size of the underlying storage unit

This means a struct IPv4Header with bitfields will have a different byte layout on GCC x86 (little-endian, LSB-first packing) versus a big-endian network processor. The IPv4 header on the wire is big-endian, but x86 is little-endian — so the bitfield layout will be backwards.

The kernel's verdict: the Linux kernel explicitly avoids bitfields in protocol header structs for exactly this reason. Instead it uses whole-byte fields and manual bit manipulation via macros:

#define IP_IHL(iph)  (((iph)->version_ihl) & 0x0F)
#define IP_VER(iph)  (((iph)->version_ihl) >> 4)

Bitfields are used in the kernel for internal flags structures where portability across endianness is not a concern (e.g., struct page flags, struct task_struct flags).

Unnamed zero-width bitfield: unsigned : 0; forces the next bitfield to begin at the start of a new storage unit — useful to explicitly pad or align bitfield groups.

#include <stdint.h>
#include <stdio.h>

// Hardware register (CPU-internal, no wire-format endianness issue)
struct ControlReg {
    uint32_t enable   : 1;
    uint32_t mode     : 2;
    uint32_t irq_mask : 4;
    uint32_t          : 25;  // reserved, unnamed
};

int main(void) {
    struct ControlReg r = {0};
    r.enable   = 1;
    r.mode     = 2;
    r.irq_mask = 0xF;

    // Peek at the raw bits
    uint32_t raw;
    __builtin_memcpy(&raw, &r, sizeof raw);
    printf("raw = 0x%08X  sizeof=%zu\n", raw, sizeof r);
    // raw = 0x0000007D  (enable=1, mode=10, irq_mask=1111 packed LSB-first on x86)
    return 0;
}

Designated initializers let you initialize struct fields by name instead of position. Introduced in C99, they are essential for readable kernel code.

struct task_config {
    int   priority;
    int   cpu_affinity;
    char *name;
    int   flags;
};

// Without designated initializers — fragile, breaks on reordering fields:
struct task_config tc1 = {5, 0, "worker", 0};

// With designated initializers — self-documenting, order-independent:
struct task_config tc2 = {
    .priority     = 5,
    .name         = "worker",
    // cpu_affinity and flags default to 0
};

Unspecified fields are zero-initialized (to 0 for integers, NULL for pointers, 0.0 for floats). This is a guarantee of C99, not a compiler extension.

Designated initializers also work for arrays:

int days[12] = {[0]=31, [1]=28, [2]=31, /* ... */ [11]=31};

The kernel uses them pervasively. When a struct has 20 fields and you only need to set 3, designated initializers keep the code readable and protect against bugs when fields are added or reordered. You will see patterns like:

static const struct file_operations mydev_fops = {
    .owner   = THIS_MODULE,
    .read    = mydev_read,
    .write   = mydev_write,
    .open    = mydev_open,
    .release = mydev_release,
};

This is the canonical way to fill a file_operations struct in a Linux device driver.

#include <stdio.h>

struct Rect {
    int x, y, w, h;
    int color;
    int z_order;
};

void print_rect(const struct Rect *r) {
    printf("Rect @ (%d,%d) %dx%d color=%d z=%d\n",
           r->x, r->y, r->w, r->h, r->color, r->z_order);
}

int main(void) {
    // Only set what matters; rest defaults to 0
    struct Rect r = {
        .x = 10,
        .y = 20,
        .w = 100,
        .h = 50,
        // color=0, z_order=0
    };
    print_rect(&r);
    return 0;
}

This is one of the most beautiful macros in any codebase. It solves a fundamental problem: the kernel's generic linked list (struct list_head) embeds a pair of next/prev pointers inside a containing struct. When the list walker hands you a struct list_head *, how do you get back to the struct that contains it?

Answer: pointer arithmetic. If you know:

1. The address of the embedded field (ptr)
2. The type of the outer struct (type)
3. The name of the embedded field within that struct (member)

...then the address of the outer struct is ptr minus the byte offset of member within type.

The kernel defines this as:

#define container_of(ptr, type, member) ({		\
    void *__mptr = (void *)(ptr);			\
    ((type *)(__mptr - offsetof(type, member))); })

Example:

struct process {
    int   pid;
    char  name[16];
    struct list_head tasks;   // embedded node
    long  vsize;
};

// The list walker has:
struct list_head *node = ...;

// Recover the containing struct:
struct process *p = container_of(node, struct process, tasks);
printf("pid=%d\n", p->pid);

This is intrusive linking: the link node lives inside the object, not outside it. The advantage is zero extra allocation, perfect cache locality (the node and the data are in the same cache line), and the ability to embed multiple list_head fields to participate in multiple lists simultaneously.

The subtraction ptr - offsetof(type, member) is just pointer arithmetic: offsetof returns the byte distance from the start of the struct to the tasks field. Subtracting that from the address of tasks gives the address of the start of the struct.

Notice how offsetof is doing real work here — it is not just a debugging tool. This is why understanding struct layout is prerequisite to reading any kernel list-manipulation code.

#include <stdio.h>
#include <stddef.h>

// Minimal list_head mimic
struct list_head {
    struct list_head *next, *prev;
};

#define container_of(ptr, type, member) \
    ((type *)((char *)(ptr) - offsetof(type, member)))

struct process {
    int             pid;
    char            name[16];
    struct list_head tasks;   // embedded list node
};

int main(void) {
    struct process proc = {.pid = 42, .name = "bash"};
    struct list_head *node = &proc.tasks;

    // Recover the container from only the node pointer
    struct process *recovered = container_of(node, struct process, tasks);
    printf("Recovered: pid=%d name=%s\n",
           recovered->pid, recovered->name);
    // Recovered: pid=42 name=bash
    return 0;
}

Nested structs are straightforward — a struct field can itself be a struct:

struct Address { char city[32]; int zip; };
struct Person  { char name[32]; struct Address addr; };

Access is chained: person.addr.zip.

Anonymous structs and unions (C11) let you omit the inner type name so fields are accessed as if they belonged to the outer type:

struct Vector3 {
    union {
        struct { float x, y, z; };  // anonymous struct inside anonymous union
        float v[3];
    };
};
struct Vector3 u = {.v = {1, 2, 3}};
printf("%f\n", u.x);  // access 'x' directly, not u.unnamed.x
printf("%f\n", u.v[0]); // same bytes, different view

The kernel uses this pattern in architecture-specific register save areas.

Flexible array members (C99) allow the last member of a struct to be an array of unspecified size:

struct Packet {
    uint32_t len;
    uint8_t  data[];  // flexible array member — takes zero space in sizeof
};
// Allocate: malloc(sizeof(struct Packet) + payload_len)

sizeof(struct Packet) gives you just the header size (4 bytes + any padding). You allocate enough extra bytes for the actual data. This is how the kernel allocates variable-length objects (sk_buff, bio, etc.) in a single contiguous allocation. Note: a struct with a flexible array member may not be used as a field inside another struct or as an array element.

#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>

struct Packet {
    uint32_t len;
    uint8_t  data[];  // zero bytes in sizeof
};

int main(void) {
    printf("sizeof(struct Packet) = %zu\n", sizeof(struct Packet)); // 4

    const char *msg = "hello, kernel";
    size_t mlen = strlen(msg);
    struct Packet *pkt = malloc(sizeof *pkt + mlen + 1);
    pkt->len = (uint32_t)mlen;
    memcpy(pkt->data, msg, mlen + 1);
    printf("pkt len=%u data='%s'\n", pkt->len, pkt->data);
    free(pkt);
    return 0;
}