1. Home
2. Academy
3. Embedded C from Zero
4. Volume 07

7.1 What a pointer really is

A pointer is a variable that holds an address. That is the whole idea. Everything else in this volume follows from it.

Memory is a row of numbered boxes, as Volume 02 showed. A normal variable holds a value. A pointer holds the number of a box - and that lets you reach the value in it from somewhere else.

reading  = 42
*p       = 42   (follow the pointer)
the two addresses match: yes
an int takes 4 bytes, a pointer takes 8

after *p = 77, reading = 77
  inside try_to_change, the copy is now 99
after try_to_change, reading = 77
after really_change, reading = 99

after swap(&a, &b): a = 2, b = 1

7.2 & and *

& takes an address. * follows one. Those two symbols are the whole of pointer syntax.

The reason pointers exist

Volume 01 showed that a function cannot change its caller's variable, because it gets a copy. Give it the address instead, and it can:

void try_to_change(int value)     /* gets a copy      */
{
    value = 99;                   /* changes the copy */
}

void really_change(int *value)    /* gets an address  */
{
    *value = 99;                  /* changes the original */
}

int reading = 77;
try_to_change(reading);           /* reading is still 77 */
really_change(&reading);          /* reading is now 99   */

That is why scanf needs an &, and why the classic swap works only with pointers:

void swap(int *a, int *b)
{
    int temp = *a;
    *a = *b;
    *b = temp;
}

swap(&x, &y);

int *p;          /* p holds whatever rubbish was in that memory */
*p = 5;          /* writes 5 to a random address */

7.3 Pointers and arrays

An array name is the address of its first element. Pass an array to a function and it decays into a pointer - which is why the function needs a count as well.

in main, sizeof(data) = 16   (the whole array)
inside the function, sizeof(values) = 8   (a pointer, not the array)
so a function must be told the count: 4

data == &data[0]? yes

data[2]      = 30
*(data + 2)  = 30
p[2]         = 30
*(p + 2)     = 30

total = 100

Those four lines print the same value, because a[i] is defined as *(a + i). Indexing is pointer arithmetic with friendlier syntax.

uint32_t total_of(const uint32_t *values, unsigned count);

7.4 Pointer arithmetic

Pointer arithmetic counts elements, not bytes. Adding 1 to a uint32_t * moves four bytes; adding 1 to a uint8_t * moves one.

a uint32_t pointer steps 4 bytes at a time
a uint8_t  pointer steps 1 byte at a time

walking the words: 0x11111111 0x22222222 0x33333333 0x44444444

stop - start = 3 elements
after cursor++, *cursor = 0x22222222

words + 4 is a legal pointer to compare against, but *end is not allowed
that is why loops are written: it != end
end - words = 4

Walking with a pointer

for (const uint32_t *it = words; it != words + 4; it++) {
    use(*it);
}

This is how driver code walks a receive buffer. The pointer one past the end is allowed to exist - that is what makes the != test legal - but following it is not.

7.5 const with pointers

const can lock the thing pointed at, the pointer itself, or both. Read the declaration outwards from the name and it is never ambiguous.

const char *text     -> can move, cannot write. now "two"
char * const fixed   -> cannot move, can write. now "One"
const char * const   -> neither. still "two"

Try to break any of those promises and the compiler refuses:

error: assignment of read-only location '*text'
error: assignment of read-only variable 'fixed'
error: assignment of read-only location '*both'

Which one you will write most

const char * - a pointer to data you promise not to change - by a long way. It is the standard way to pass a buffer *into* a function:

void uart_send(const uint8_t *data, uint16_t length);    /* will not change your data */
uint16_t uart_receive(uint8_t *buffer, uint16_t size);   /* will fill your buffer     */

The difference between those two lines tells a reader exactly which way the data flows, before they read a word of the implementation.

7.6 void pointers, NULL and double pointers

A void pointer is an address with no type attached. NULL is an address that deliberately points at nothing. And a pointer to a pointer is how a function changes where your pointer points.

void copy_bytes(void *dst, const void *src, size_t count)
{
    uint8_t *d = dst;             /* a void * converts with no cast, in C */
    const uint8_t *s = src;
    while (count-- > 0u) {
        *d++ = *s++;
    }
}

A void * can hold the address of anything, which is what makes memcpy work for every type. It cannot be followed directly: you convert it to a real pointer type first, because the compiler has to know how many bytes to read.

NULL: the pointer that points nowhere

if (buffer != NULL) {
    use(buffer);
}

Following a NULL pointer is undefined behaviour. On a desktop it is a crash with a clear message. On a microcontroller address 0 is often real memory - the start of flash, or the vector table - so the read quietly succeeds and returns nonsense.

char *make_label(void)
{
    char buffer[16];        /* lives on the stack */
    ...
    return buffer;          /* gone the moment this function returns */
}

Pointer to a pointer

To change where a caller's pointer points, you need its address - a uint8_t **:

copy_bytes moved 0xDEADBEEF into a uint32_t: 0xDEADBEEF

maybe is NULL
checking for NULL first is what stops a crash

cursor points at 1
after point_at_second, cursor points at 2

It is the same rule as before, one level up. To change an int, pass int *. To change an int *, pass int **.

7.7 Function pointers and callbacks

A function pointer holds the address of code instead of data. It lets a program decide, while it is running, which function to call.

void led_on(void);

void (*what)(void) = led_on;      /* a pointer to a function taking nothing, returning nothing */
what();                           /* calls led_on */

typedef void (*action_fn)(void);  /* a name for that type, so the rest stays readable */
action_fn next = led_on;

A table of commands

struct command {
    const char *name;
    action_fn   run;
};

static const struct command table[] = {
    { "on",   led_on  },
    { "off",  led_off },
    { "beep", beep    },
};

for (unsigned i = 0; i < ARRAY_SIZE(table); i++) {
    if (strcmp(word, table[i].name) == 0) {
        table[i].run();
    }
}

through a function pointer:
  led on
  beep

running every command in the table:
on ->
  led on
off ->
  led off
beep ->
  beep

the callback added the bytes up to 100

sizeof(action_fn) = 8 bytes on this machine

Adding a new command means adding a row to the table - no new if, no new case. This is how command shells, protocol handlers and menu systems are written in C.

Callbacks

A callback is a function you hand to someone else, to be called when something happens:

void uart_on_byte(void (*handler)(uint8_t));      /* register it once */

...
uart_on_byte(add_to_checksum);                    /* now every byte goes there */

What you learned

• A pointer is a variable that holds an address; its own size is the same for every type.
• & takes an address, * follows one, and *p = x writes into the original variable.
• Pass an address when a function must change something of yours.
• An array decays to a pointer when passed, so functions take a count as well.
• a[i] is exactly *(a + i), and pointer arithmetic counts elements, not bytes.
• const before the type locks the data; const after the star locks the pointer.
• void * is an address with no type; NULL must be checked before it is followed.
• A function pointer holds the address of code, which is how tables and callbacks work.

Key words from this volume

Every word below has a plain-English entry in the glossary.

• Pointer
• Address-of (&)
• Dereference
• Array decay
• Pointer arithmetic
• void pointer
• NULL
• Dangling pointer
• Function pointer
• Callback

Practice

uint8_t *a;
const uint8_t *b;
uint8_t * const c = &value;
uint8_t **d;

uint8_t largest(const uint8_t *data, unsigned count)
{
    uint8_t best = 0u;
    for (unsigned i = 0; i < count; i++) {
        if (data[i] > best) {
            best = data[i];
        }
    }
    return best;
}

uint8_t data[4] = { 5u, 10u, 15u, 20u };
const uint8_t *p = data + 1;

printf("%u %u %u\n", *p, p[1], *(data + 3));

const char *status_text(uint8_t code)
{
    char text[16];
    snprintf(text, sizeof text, "code %u", code);
    return text;
}

void status_text(uint8_t code, char *out, size_t size)
{
    snprintf(out, size, "code %u", code);
}

const char *status_name(uint8_t code)
{
    static const char *names[] = { "idle", "busy", "error" };
    return (code < 3u) ? names[code] : "unknown";     /* string literals live for ever */
}

Interview corner

Next, Volume 08 groups data together: structs, the padding the compiler inserts between members, unions that read the same bytes two ways, and enums that give numbers names.