60 How to read a declaration — two readings and typedef

60.1 The two readings

One rule suffices to begin. The three symbols attaching beside the name in a declaration have different strengths.

• [] (array) and () (function) attach to the right of the name, and * (pointer) attaches to the left.
• The two on the right are stronger than the one on the left. So int *a[3] is “an array of pointers”, not “a pointer to an array”.
• To reverse the order, bind with parentheses — int (*a)[3].

On this difference of strength the two readings arise.

Reading ① — from the innermost name outward (the right-left rule). Find the identifier, start there, and go outward alternately, looking right first and then left. On meeting a parenthesis, read all of its inside and then step out. The charm of this method is that what you say as you read connects in English word order.

Reading ② — from the outside in. Start from the type name (the leftmost thing, such as int or char) and wrap your way in asking “this is a what of a what”. In a declaration with no identifier at all — the abstract declarator written in a cast or in sizeof — there is no name to start from, so this is the only road.

The two readings arrive at the same conclusion. Use whichever suits the occasion.

60.2 Reading ① in practice — connecting it in English word order

/* The two ways of reading a declaration, confirmed with the eyes.
   Whether the type built up out of typedefs really is the original one is
   checked too. */
#include <stdio.h>

/* (1) the difference of one star ──────────────────────── */
int  *pa[3];      /* pa: array[3] of pointer to int   */
int (*ap)[3];     /* ap: pointer to array[3] of int   */

/* (2) when a function joins in ─────────────────────────── */
int  *f(void);    /* f: function(void) returning pointer to int */
int (*g)(void);   /* g: pointer to function(void) returning int */

/* (3) the notorious shape: array[4] of pointer to function(int) returning pointer to char */
char *(*table[4])(int);

/* (4) the same type, built one typedef layer at a time */
typedef char           *charptr;        /* pointer to char                  */
typedef charptr         handler(int);   /* function(int) returning charptr  */
typedef handler        *handler_ptr;    /* pointer to that function         */
typedef handler_ptr     table4[4];      /* array[4] of that pointer         */

/* whether the types built by the two roads really match, checked at compile time */
static_assert(sizeof(table4) == sizeof(table), "they must be the same type");

static char *shout(int n)  { (void)n; return "shout"; }
static char *quiet(int n)  { (void)n; return "quiet"; }

int main(void)
{
    printf("int  *pa[3]  : whole %zu, element %zu  -> %zu pointers\n",
           sizeof pa, sizeof pa[0], sizeof pa / sizeof pa[0]);
    printf("int (*ap)[3] : whole %zu, what it points to %zu\n",
           sizeof ap, sizeof *ap);

    /* (3) actually filled in and used */
    table[0] = shout;
    table[1] = quiet;
    printf("table[0](1) = %s, table[1](2) = %s\n", table[0](1), table[1](2));

    /* a variable made with (4)'s typedefs fits the same slot as it is */
    table4 other = { quiet, shout };
    printf("other[0](3) = %s   (the same type, built with typedefs)\n", other[0](3));

    /* the form without an identifier (an abstract declarator): used in casts and sizeof */
    printf("sizeof(char *(*)(int)) = %zu   (a nameless function pointer type)\n",
           sizeof(char *(*)(int)));
    return 0;
}

int  *pa[3]  : whole 24, element 8  -> 3 pointers
int (*ap)[3] : whole 8, what it points to 12
table[0](1) = shout, table[1](2) = quiet
other[0](3) = quiet   (the same type, built with typedefs)
sizeof(char *(*)(int)) = 8   (a nameless function pointer type)

We read the example’s declarations one at a time. What you say is most natural strung together in English — because C’s declaration syntax was designed to follow English word order.

int *pa[3];

1. Start from the identifier pa — “pa is”
2. Look right: [3] — “array 3 of”
3. The right is finished, so look left: * — “pointer to”
4. What remains: int — “int”

Read through: “pa is array 3 of pointer to int” — an array of three pointers. The example confirmed it with 24 bytes in total and 8 bytes per element.

int (*ap)[3];

1. Start from ap — “ap is”
2. To the right is the end of the parenthesis, so we cannot go. Look left: * — “pointer to”
3. Step out of the parenthesis. Right again: [3] — “array 3 of”
4. What remains: int

“ap is pointer to array 3 of int” — one pointer (8 bytes), and what it points at is a 12-byte array. That is the example’s second line.

char *(*table[4])(int); — this chapter’s protagonist.

1. Start from table — “table is”
2. Right: [4] — “array 4 of”
3. Left: * — “pointer to”
4. Outside the parenthesis, right: (int) — “function (int) returning”
5. Left: * — “pointer to”
6. What remains: char

“table is array 4 of pointer to function (int) returning pointer to char” — a table of functions taking one integer and giving back a string. The example actually put two functions in and called them.

60.2.1 This reading has a name — boustrophedon

Look again at what we just did: the eye traced a zigzag, right → left → right. That movement has an old name. It is boustrophedon, from the Greek βοῦς (ox) and στρέφειν (to turn) — the shape an ox makes drawing a plough to the end of a field, then turning back the other way. Ancient Greek inscriptions were sometimes cut this way, one line left-to-right and the next right-to-left, and that is called boustrophedonic writing.

The person who first called C declarations this was Peter van der Linden. He wrote — “Declarations in C are read boustrophedonically, i.e. alternating right-to-left with left-to-right. And who’d have thought there would be a special word to describe that!”¹

There is one good reason to know the name. It carries the fact that reading ① is not an arbitrary knack but a procedure with a shape. The same book compresses that procedure into a precedence rule. It is what we spelled out in sentences above, except that the third item has not come up yet.

★ Clause C causes the most accidents in practice, because where the const lands flips the meaning completely.

/* 우경식(牛耕式) 읽기의 우선순위 규칙을 눈으로 확인한다.
   특히 const/volatile 이 「왼쪽의 별표에 붙는가, 타입에 붙는가」를 실물로 가른다. */
#include <stdio.h>

static int one = 1, two = 2;

int main(void)
{
    /* ① const 가 타입 지정자 옆에 있다 → 타입에 붙는다(가리키는 것이 읽기 전용) */
    const int *pci  = &one;     /* 「int const 를 가리키는 포인터」 */
    int const *pci2 = &one;     /* 위와 완전히 같다 — 순서만 다르다 */

    /* ② const 가 타입 지정자 옆이 아니다 → 바로 왼쪽의 별표에 붙는다 */
    int *const cpi = &one;      /* 「int 를 가리키는, 읽기 전용 포인터」 */

    /* ③ 둘 다 */
    const int *const cpci = &one;

    /* ①은 가리키는 곳을 바꿀 수 있다.  *pci = 9; 는 오류다. */
    pci = &two;
    pci2 = &two;
    printf("(1) *pci=%d  *pci2=%d   <- the pointer itself can move\n", *pci, *pci2);

    /* ②는 반대다.  cpi = &two; 는 오류이고, 가리키는 값은 바꿀 수 있다. */
    *cpi = 42;
    printf("(2) *cpi=%d   one=%d      <- the value can be changed\n", *cpi, one);

    printf("(3) *cpci=%d              <- read-only on both sides\n", *cpci);

    /* ④ 우경식으로 읽는 실물: 오른쪽 먼저, 막히면 왼쪽 */
    char *const *next = NULL;   /* next 는 「char 를 가리키는 읽기 전용 포인터」를
                                   가리키는 포인터 */
    printf("(4) sizeof next = %zu   (one pointer)\n", sizeof next);

    /* ⑤ 태그를 붙여 두었기에 자기 자신을 가리킬 수 있다 */
    struct node_tag { int datum; struct node_tag *next; };
    struct node_tag b = { 2, NULL };
    struct node_tag a = { 1, &b };
    printf("(5) a.datum=%d -> a.next->datum=%d\n", a.datum, a.next->datum);

    return 0;
}

(1) *pci=2  *pci2=2   <- the pointer itself can move
(2) *cpi=42   one=42      <- the value can be changed
(3) *cpci=42              <- read-only on both sides
(4) sizeof next = 8   (one pointer)
(5) a.datum=1 -> a.next->datum=2

The example’s first three lines are that fork.

The example split these apart for real. const int *pci can be moved with pci = &two;, and int *const cpi can change the value with *cpi = 42;. The other way round is a compile error in each case: assignment of read-only location '*pci' and assignment of read-only variable 'cpi'.

60.2.2 Reading by erasing

The same book recommends one more knack: erase what you have read. Skimming with the eye alone loses track of how far you have got; erase each piece as you handle it and what remains is exactly the next job. That is why reading with pen on paper almost never goes wrong.

Read char *const *(*next)(); that way. The bold piece is the one in hand.

Joined up: “next is a pointer to a function returning a pointer to a read-only pointer to char.” This declaration is not invented — it comes from the source of telnet.

60.3 Reading ② — when there is no name

Casts and sizeof take a type written without a name. The last line of the example, sizeof(char *(*)(int)), is that. Such a form is called an abstract declarator, and the way to read it is simple — find the place where the name ought to be, lay a name there, and read by reading ①.

char *(*)(int)        /* there is no name */
char *(*x)(int)       /* put x in the empty place and */
                      /* "x is pointer to function (int) returning pointer to char" */

The empty place is usually after the star of (*), or before [] or (). Thanks to this knack, reading ①′s muscle can be used as it is.

Then when is reading ② used. When the shells are several layers deep — as in a declaration taking a function pointer as an argument — and you want to know first which is the outermost.

void qsort(void *base, size_t n, size_t size,
           int (*cmp)(const void *, const void *));

Reading from the outside in, the skeleton is grasped first: “this is a function qsort, returning void, with four arguments of which the last is a function pointer.” The details are then confirmed with reading ①. When reading somebody else’s header in the field this order is the comfortable one.

60.4 typedef — dividing into layers and naming them

The most practical answer to a rough declaration is dividing it into layers by naming them. The example’s ④ is that demonstration.

typedef char       *charptr;        /* pointer to char           */
typedef charptr     handler(int);   /* function(int) returning charptr */
typedef handler    *handler_ptr;    /* pointer to that function  */
typedef handler_ptr table4[4];      /* array[4] of that pointer  */

Each of the four lines lays on just one layer. The final table4 is exactly the same type as the example ③′s char *(*table[4])(int), and the example’s static_assert confirms it at compile time. In the field it is more common to name only one or two layers than to slice this finely.

typedef char *(*handler_fn)(int);   /* when one layer is enough */
handler_fn table[4];

60.4.1 Where to use it and where not to

We know how to divide into layers; the question is when. On that there is a rule of thumb that has been quoted for over thirty years — the three items van der Linden put in a box called “Tips for Working with Typedefs”.²

Take them one at a time against today.

① still holds. It is exactly the antipattern box above — hiding a struct behind a typedef blurs where the const attaches, and that is the price of the hiding. The Linux kernel’s coding conventions reach the same conclusion. The one exception is the opaque type, where hiding is the design.

② is what we are already doing, with one of today’s facts to add. “Make it a typedef when you need at least 20 bits” was, in 1994, something you had to build yourself. Today the standard does it for you — <stdint.h>‘s int32_t, int_least32_t and int_fast32_t are typedefs made for precisely that purpose (chapter 27). ★ So today’s version reads: look first for one the standard already has. Build one only when there is none.

③ turns out to be right for two reasons. One is van der Linden’s “it will be later.” The other is that there are cases where it is needed right now — a struct that points at itself.

typedef struct { int datum; node *next; } node;   /* does not work */

The name node does not exist until the ;, so it cannot be used inside. Compile it and you get error: unknown type name 'node'. With a tag the problem goes away, because the tag exists the moment struct is followed by it.

typedef struct node_tag { int datum; struct node_tag *next; } node;   /* works */

The example’s ⑤ chains two nodes in this form. This is also why we have suffixed struct tags with _tag throughout the earlier chapters — so as not to use one name for two different things (chapter 55′s name spaces).

typedef struct node *node;      /* that it is a pointer vanishes from the name */
void f(const node n);           /* what is the const attaching to? */

typedef int meters;
typedef int seconds;
meters  d = 10;
seconds t = 5;
d = t;              /* no warning — both are just int */

60.5 The real thing — declarations that actually shipped

What follows is not exercise material. These are declarations from libraries that really shipped, read by the procedure. The point of the section is to confirm there is nothing to be afraid of.

/* Gnarly declarations that really shipped — and how a procedure unravels them. */
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>

/* -- (1) the standard's signal — exactly as it stands in C §7.14.1.1:
      void (*signal(int sig, void (*func)(int)))(int);
   Split into layers with typedef it becomes this. */
typedef void handler_t(int);          /* name the function type itself */
static void on_int(int sig) { (void)sig; }

/* -- (2) the shape of X11's XSetErrorHandler:
      int (*XSetErrorHandler(int (*handler)(Display *, XErrorEvent *)))();
   Copied as is, with stand-in types for Display and XErrorEvent. */
typedef struct { int dummy; } Display;
typedef struct { int code; } XErrorEvent;

static int my_error_handler(Display *d, XErrorEvent *e)
{ (void)d; printf("  error handler: code=%d\n", e->code); return 0; }

/* Raw: "a function taking a handler and returning the previous handler" */
static int (*set_error_handler(int (*handler)(Display *, XErrorEvent *)))
           (Display *, XErrorEvent *)
{
    static int (*current)(Display *, XErrorEvent *);
    int (*prev)(Display *, XErrorEvent *) = current;
    current = handler;
    return prev;
}

/* The same with typedef — one line becomes three, and all three read */
typedef int error_handler_t(Display *, XErrorEvent *);
static error_handler_t *set_error_handler2(error_handler_t *handler)
{ return set_error_handler(handler); }

/* -- (3) an array of pointers to functions — a dispatch table ---------- */
static int cmd_add(int a, int b) { return a + b; }
static int cmd_mul(int a, int b) { return a * b; }

/* int (*table[2])(int, int) — an array of "pointer to function taking two
   ints and returning int". Read by the procedure, that is what comes out. */
static int (*table[2])(int, int) = { cmd_add, cmd_mul };

/* -- (4) a function returning a pointer to an array -------------------- */
static int (*rows(void))[4]            /* "function returning pointer to int[4]" */
{
    static int grid[3][4] = { {1,2,3,4}, {5,6,7,8}, {9,10,11,12} };
    return grid;                        /* decays to int (*)[4] */
}

int main(void)
{
    /* (1) signal returns the *previous* handler — hence the function-pointer return */
    handler_t *old = signal(SIGINT, on_int);
    printf("signal returns the previous handler: %s\n",
           old == SIG_ERR ? "SIG_ERR" : "a previous value");
    (void)signal(SIGINT, old == SIG_ERR ? SIG_DFL : old);

    /* (2) the same pattern — install, and get the previous one back */
    puts("\ninstalling an X11-style error handler:");
    int (*prev)(Display *, XErrorEvent *) = set_error_handler(my_error_handler);
    printf("  previous handler: %s\n", prev ? "present" : "none (first install)");
    Display d = { 0 };
    XErrorEvent e = { .code = 42 };
    error_handler_t *prev2 = set_error_handler2(my_error_handler);  /* typedef form */
    printf("  the typedef version does the same: previous handler %s\n",
           prev2 == my_error_handler ? "identical" : "different");
    my_error_handler(&d, &e);

    /* (3) the dispatch table */
    printf("\ndispatch table: add(3,4)=%d, mul(3,4)=%d\n", table[0](3, 4), table[1](3, 4));

    /* (4) a pointer to an array */
    int (*g)[4] = rows();
    printf("pointer to array: g[2][1] = %d (one step is %zu bytes)\n",
           g[2][1], sizeof *g);
    return 0;
}

signal returns the previous handler: a previous value

installing an X11-style error handler:
  previous handler: none (first install)
  the typedef version does the same: previous handler identical
  error handler: code=42

dispatch table: add(3,4)=7, mul(3,4)=12
pointer to array: g[2][1] = 10 (one step is 16 bytes)

60.5.1 ① The monster the standard itself produced — signal

This declaration stands in the standard’s <signal.h> exactly as written (§7.14.1.1).

void (*signal(int sig, void (*func)(int)))(int);

At first sight it is a forest of parentheses, but following the procedure of the previous section it takes five steps. Start at the name, look right first, and go left when the right is exhausted.

In one sentence: “signal takes a signal number and a handler, and returnsthe previous handler.” That also explains why the return type is so rough — installing must hand back the previous one so it can be restored later. The first line of the demonstration actually takes that previous handler and restores it.

One typedef makes the declaration ordinary.

typedef void handler_t(int);          /* name the function type */
handler_t *signal(int sig, handler_t *func);

The standard does not write it that way for historical reasons — this function existed long before layering with typedef became the habit.

60.5.2 ② Rougher in the wild — X11′s error handler

From the X Window System’s manual:

int (*XSetErrorHandler(int (*handler)(Display *, XErrorEvent *)))();

The pattern is identical to signal: take a handler, return the previous one. The only difference is that the handler takes two arguments, so a layer of parentheses looks thicker. By the procedure, the number of steps is the same.

The second block of the demonstration transplants the pattern and runs it — a raw set_error_handler and a set_error_handler2 layered with typedef do the same work. The latter shows that this rough declaration is really the one line “a function taking a handler and returning a handler.”

typedef int error_handler_t(Display *, XErrorEvent *);
error_handler_t *XSetErrorHandler(error_handler_t *handler);

60.5.3 ③ And the genuinely pointless ones

Declaration quizzes on the internet have their regulars.

char *(*(**foo[][8])())[];      /* an example from cdecl's own documentation */
int (*(*bar[10])(void))(int);

The procedure works on these too. The first is “an array of arrays of 8 of pointer to pointer to function returning pointer to array of pointer to char”. More important than having read it is the judgement that follows: do not put such a declaration in your code.

The difference between these and the two above is this chapter’s point. The first two are declarations worth untangling — they are really used and the pattern carries meaning. The last has no meaning; it only shows what the grammar permits.

60.6 Leaving it to a tool — cdecl

A program that does this reading for you has existed for a long time. It is cdecl, which appeared in the 1980s and is still maintained (its current maintainer is Paul J. Lucas, GPLv3). Give it a declaration and it unfolds it into English; speak English and it builds the declaration.

cdecl> explain char *(*table[4])(int)
cdecl> declare table as array 4 of pointer to function (int) returning pointer to char

The first line does what we did by hand above, and the second is the opposite direction — it builds a C declaration from what was said in English. It can be installed as a package on Linux distributions (cdecl), and there is cdecl.org for using it in a browser without installing.

We have gained the muscle for reading declarations. From the next chapter we enter the terrain of the standard library — the part where, on top of the language learned so far, we see what contracts and traps the functions the world has piled up over half a century carry.