26 The families of types — how the standard divides them

26.1 The four things a type settles

Given the same eight bytes, reading them as a double gives 3.14 and as a long gives 4614253070214989087 (exactly as chapter 8 showed). Bytes do not know what they are; only the type knows.

So “knowing a type” is not knowing syntax but knowing those four. And the standard settles those four branch by branch.

26.2 The first division — object types and function types

The topmost division is in two.

This division shows itself in practice. sizeof cannot be applied to a function type, and being no object it has neither size nor alignment. That is why treating a function as a value means turning it into a pointer to a function (chapter 59).

26.2.1 Complete and incomplete types

Object types divide again — is the size known?

An incomplete type is not a defect but a tool. It can express “I know this type exists and nothing of its insides”, which is what makes an opaque type possible — hiding the insides in a header and passing only pointers (FILE * is the archetype). Hiding the insides means callers cannot depend on them, and that is the design gain (chapter 47).

26.3 The basic types

What the standard calls the basic types is exactly these three groups together.

Enumerated types are not basic types. They are integer types, but they do not appear in the list of basic types — a commonly confused spot.

The standard nails down one more sentence about them: “even if the implementation defines two or more basic types to have the same representation, they are nevertheless distinct types.” The character types of the next section are the example of that sentence.

26.3.1 There are three character types

The heart of it is the sentence a footnote nails down — whichever choice was made, char is a separate type from the other two and is compatible with neither. There are three, not two.

_Generic((i), int: "a", signed int: "b")   /* error: two compatible types */

char c;  take_signed_char(&c);   /* warning: … differ in signedness */
int  i;  take_signed_int(&i);    /* not a word --- they are the same type */

char c = 0xFF;
if (c == 0xFF) { … }      /* does not hold with a signed char */

26.4 Integer, real, arithmetic — the collective names

From here comes the source of the vocabulary this book has been using. These names are not branches of the tree but words that gather several branches.

In chapter 49′s tables of operator contracts you will meet cells such as “operand: a real type or a pointer”, and now they can be read exactly.

Figure 26.1 — How the standard divides types. A dashed box is a name that gathers several branches.

26.5 Derived types — made out of what is there

New types can be constructed from object and function types, and what is so constructed is a derived type.

These constructions apply recursively. “An array of 10 pointers to int” and “a pointer to a function returning int” are both built that way. That recursion is exactly why chapter 60, “Reading declarations”, is hard, and the standard gathers three of them — array, function and pointer — under the name derived declarator types. Those three are precisely what must be unwrapped from the inside out when reading a declaration.

26.6 Qualifiers — a qualified edition of the same type

A type qualifier does not make a new type; it makes a qualified version. C23 fixes the list at four, and that is all of them.

26.6.1 A qualified edition is the same size as the original

A qualified type and an unqualified one have the same size, representation and alignment — what changes is only what may be done.

/* See all four type qualifiers in one place.
   The point: a qualified type is another edition of the same type - neither
   its size nor its alignment changes. */
#include <stdio.h>
#include <stdalign.h>

struct big { char a[9]; };

int main(void)
{
    puts("(1) a qualifier changes neither size nor alignment");
    printf("  int            : %zu / %zu\n", sizeof(int), alignof(int));
    printf("  const int      : %zu / %zu\n", sizeof(const int), alignof(const int));
    printf("  volatile int   : %zu / %zu\n", sizeof(volatile int), alignof(volatile int));
    printf("  struct big     : %zu / %zu\n", sizeof(struct big), alignof(struct big));
    printf("  _Atomic big    : %zu / %zu   <- unchanged on this implementation\n",
           sizeof(_Atomic struct big), alignof(_Atomic struct big));

    puts("\n(2) the order is free and they may be combined");
    const volatile int a = 1;
    volatile const int b = 2;      /* exactly the same type as above */
    printf("  const volatile int a = %d,  volatile const int b = %d\n", a, b);

    puts("\n(3) _Atomic has two faces");
    _Atomic int   c = 3;           /* written as a qualifier */
    _Atomic(int)  d = 4;           /* written as a type specifier - same type */
    printf("  _Atomic int c = %d,  _Atomic(int) d = %d\n", c, d);
    /* typedef int A[3];  _Atomic A x;   <- cannot qualify an array: compile error */

    puts("\n(4) const only says \"not through this name\"");
    int  x  = 10;
    const int *p = &x;             /* cannot change it through p */
    x = 20;                        /* but x itself still can */
    printf("  changed x directly, so *p = %d  <- const is a promise about the route, not the value\n", *p);
    /* *p = 30;  <- error: assignment of read-only location */

    puts("\n(5) a qualifier may be added silently, never removed");
    const int ci = 7;
    const int *q = &ci;            /* adding: allowed */
    printf("  int * -> const int * passes; the reverse warns (-Wdiscarded-qualifiers), *q = %d\n", *q);
    /* int *bad = &ci;  <- warning: initialization discards 'const' qualifier */

    return 0;
}

(1) a qualifier changes neither size nor alignment
  int            : 4 / 4
  const int      : 4 / 4
  volatile int   : 4 / 4
  struct big     : 9 / 1
  _Atomic big    : 9 / 1   <- unchanged on this implementation

(2) the order is free and they may be combined
  const volatile int a = 1,  volatile const int b = 2

(3) _Atomic has two faces
  _Atomic int c = 3,  _Atomic(int) d = 4

(4) const only says "not through this name"
  changed x directly, so *p = 20  <- const is a promise about the route, not the value

(5) a qualifier may be added silently, never removed
  int * -> const int * passes; the reverse warns (-Wdiscarded-qualifiers), *q = 7

Output ① confirms it. const int and volatile int are both four bytes, aligned the same.

★ One caveat belongs on _Atomic. The standard does not require an atomic type to have the same size and alignment as its corresponding non-atomic type. If an implementation has to hide a lock inside, it may grow. The nine-byte struct in the example was unchanged here, but it need not be — that is the contract. Which is why atomic types come with a separate question, atomic_is_lock_free (chapter 80).

26.6.2 The order is free and they may be combined

As output ② shows, const volatile int and volatile const int are the same type. A qualifier may go before or after the type specifier, and all four may be used together.

Writing the same qualifier twice is allowed in C23 as well — it counts as appearing once. Going through a typedef makes that easy to do by accident.

typedef const int ci;
const ci x = 1;        /* const twice - legal, counts as once */

The compiler kindly says so (GCC’s -Wduplicate-decl-specifier). Nobody writes it on purpose, but the rule saves programs where macros and typedefs meet.

26.6.3 Only _Atomic has two faces

Of the four, only _Atomic serves both as a qualifier and as a type specifier.

_Atomic int  c;      /* written as a qualifier */
_Atomic(int) d;      /* written as a type specifier - the same type */

Output ③ shows the two are the same. The parenthesised form exists because it is needed to wrap a complicated type — _Atomic(int *) is “an atomic pointer”, and int * _Atomic says the same thing but reads badly.

★ There is also one restriction peculiar to _Atomic: it cannot be applied to arrays or functions. There is no way to make a whole array untearable at once (measured: '_Atomic'-qualified array type). _Atomic int a[3]; is fine, but that means each element is atomic, not the array.

26.6.4 A qualifier is a property of the route, not of the value

Output ④ is this section’s point. Even with const int *p = &x;, x itself can still be changed. const does not say “this value is constant”; it says “I will not change it through this name.”

26.6.5 It may be added silently, never removed

Output ⑤ shows the direction. Passing an int * where a const int * is wanted is legal; the reverse warns (-Wdiscarded-qualifiers). Only the direction that increases qualification is allowed quietly.

★ There is a famous trap in this rule, though. Passing a char ** where a const char ** is wanted is not allowed: pointer compatibility does not carry one level down. Chapter 60 follows the standard’s clauses through that argument.

26.6.6 Where it attaches flips the meaning

The place a qualifier most often causes accidents is the pointer.

One line separates them: a qualifier qualifies the thing immediately to its left; if there is nothing to its left, the thing to its right. That is clause C of chapter 60′s precedence rule, and it is split apart there by running it.

26.7 Types with their width in the name — <stdint.h>

That was the types the language gives; now the ones the standard library names for us. They are the direct answer to the problem that int’s size differs by implementation (the next chapter).

/* The three families of <stdint.h>, and the traps of uint8_t. */
#include <inttypes.h>
#include <limits.h>
#include <stdint.h>
#include <stdio.h>

int main(void)
{
    puts("[three families — they demand different things]");
    printf("  %-16s %-6s %s\n", "type", "size", "what it guarantees");
    printf("  %-16s %-6zu %s\n", "uint8_t",       sizeof(uint8_t),
           "exactly 8 bits, no padding (optional)");
    printf("  %-16s %-6zu %s\n", "uint_least8_t", sizeof(uint_least8_t),
           "smallest with at least 8 bits (required)");
    printf("  %-16s %-6zu %s\n", "uint_fast8_t",  sizeof(uint_fast8_t),
           "usually fastest with at least 8 bits (required)");
    printf("  %-16s %-6zu %s\n", "uint_least32_t", sizeof(uint_least32_t), "at least 32 bits");
    printf("  %-16s %-6zu %s\n", "uint_fast32_t",  sizeof(uint_fast32_t),  "at least 32 bits, speed first");
    printf("  %-16s %-6zu %s\n", "uintmax_t",      sizeof(uintmax_t),      "the widest integer (required)");
    printf("  %-16s %-6zu %s\n", "uintptr_t",      sizeof(uintptr_t),      "void* round trip (optional)");

    puts("\n[trap 1: uint8_t is usually unsigned char, so it leaks as a character]");
    uint8_t age = 65;
    printf("  with %%u: %u\n", age);
    printf("  with %%c: %c   <- 'A' comes out, not 65\n", age);
    printf("  putchar(age) is the same trap\n");

    puts("\n[trap 2: arithmetic promotes to int — this is not 8-bit arithmetic]");
    uint8_t a = 200, b = 100;
    printf("  a + b        = %d   <- computed as int: 300, it did not wrap\n", a + b);
    printf("  (uint8_t)(a+b) = %u   <- put it back to make it wrap\n", (uint8_t)(a + b));
    printf("  sizeof(a + b) = %zu  <- the result is 4 bytes\n", sizeof(a + b));

    puts("\n[trap 3: being an alias, the format must follow the alias]");
    printf("  with PRIu8: %" PRIu8 "\n", age);
    printf("  UINT8_C(200) is %u, UINT8_MAX is %u\n", UINT8_C(200), UINT8_MAX);

    puts("\n[which to use when]");
    puts("  protocols, file formats, registers -> exact width (uint32_t)");
    puts("  portability first, width at least -> minimum width (uint_least16_t)");
    puts("  loop counters, local sums          -> fastest (uint_fast32_t)");
    puts("  sizes, indices, byte counts        -> size_t (<stddef.h>)");
    return 0;
}

[three families — they demand different things]
  type             size   what it guarantees
  uint8_t          1      exactly 8 bits, no padding (optional)
  uint_least8_t    1      smallest with at least 8 bits (required)
  uint_fast8_t     1      usually fastest with at least 8 bits (required)
  uint_least32_t   4      at least 32 bits
  uint_fast32_t    8      at least 32 bits, speed first
  uintmax_t        8      the widest integer (required)
  uintptr_t        8      void* round trip (optional)

[trap 1: uint8_t is usually unsigned char, so it leaks as a character]
  with %u: 65
  with %c: A   <- 'A' comes out, not 65
  putchar(age) is the same trap

[trap 2: arithmetic promotes to int — this is not 8-bit arithmetic]
  a + b        = 300   <- computed as int: 300, it did not wrap
  (uint8_t)(a+b) = 44   <- put it back to make it wrap
  sizeof(a + b) = 4  <- the result is 4 bytes

[trap 3: being an alias, the format must follow the alias]
  with PRIu8: 65
  UINT8_C(200) is 200, UINT8_MAX is 255

[which to use when]
  protocols, file formats, registers -> exact width (uint32_t)
  portability first, width at least -> minimum width (uint_least16_t)
  loop counters, local sums          -> fastest (uint_fast32_t)
  sizes, indices, byte counts        -> size_t (<stddef.h>)

26.7.1 What separates the three families is “what they demand”

The measurement shows the difference — on this machine uint_fast32_t was eight bytes. Thirty-two bits would have sufficed and it took sixty-four; that is what “fast” means (matching the register width is faster). It is not a type for saving space.

26.7.2 The three traps of uint8_t

The most used, and the most injuring, so it gets its own treatment.

uint8_t age = 65;
printf("%c\n", age);      /* 'A' comes out */
putchar(age);             /* the same trap */

uint8_t a = 200, b = 100;
a + b     /* 300, not 44 */

void send(uint8_t port, uint8_t value);
send(value, port);        /* swapped, and it stays silent */

26.7.3 So which do you use

Emphasise that last row as practice’s default. With no particular reason, use int. The types with a width in their name are a tool for places where the width is the contract, not something good to sprinkle about for thrift.

26.8 Summary — the standard’s words and this book’s chapters

The families are laid out. From the next chapter we dig into its cells one at a time — first integers. The family passed over here in the single phrase “the signed and unsigned integer types” gets its insides, its ranges, its representation and its accidents.