61 The terrain of the standard library

61.1 The landscape — the toolboxes

Group the headers you meet often into families and the terrain comes into view at a glance.

Two things stand out in this list. First, it is thin — there are no data structures (lists, hash tables), no regular expressions, no networking, no graphics. Second, it is old — most of it was in C89, and what has newly entered can be counted on the fingers.

61.2 Why it is thin — design and history

The reason lies where C grew up. C was born as a language for making operating systems (chapter 4), and it had to write in the same language not only programs running on top of an operating system but the operating system itself and embedded firmware too. In such places there may be no file system, no dynamic allocation, not even an operating system — so the standard library was narrowed to “the minimum that can exist anywhere” (the reason the standard separately defines a freestanding environment). Abundance was given up and portability gained.

And the thinness came at a price — the world made what it needed in the end, and the result is the forest of platform-specific APIs and third-party libraries. That is the background of the saying “in C, choosing libraries is half the work” — chapter 43′s five disciplines are about what to demand of that choice.

61.3 An anatomy of the output format string

This is the place to take apart head on the function used most. In chapter 22 we learned only the minimal set (%d, %s, %%), but printf’s format is in fact a small language of five pieces.

Reading from the back is quicker to understand. The conversion settles “as what shall it be printed” — this alone is required — and the rest is decoration laid on top.

• flag: - left-align, 0 fill the spare places with zeros, + a sign even on positives, space a space before positives, # alternative form (%#x attaches 0x).
• width: the minimum number of characters. If short it fills, if over it does not cut — width is a lower bound, not an upper one.
• precision: begins with .. For reals it is decimal places, for strings the maximum length, for integers the minimum number of digits.
• length modifier: tells the width of the argument. l (long), ll (long long), z (size_t), h (interpret narrowed to short).

Write * in the width or precision place and that value can be passed as an argument. When printing a string that travels as “pointer and length”, like chapter 10′s view, %.*s comes in handy.

#include <stdio.h>

int main(void) {
    int n = 42;
    unsigned u = 255;
    double x = 3.14159265;
    const char *s = "proven";
    size_t sz = 1234;
    long long big = 9000000000LL;

    /* flags and width: right alignment by default, - for left, 0 to fill with zeros */
    printf("[%d] [%6d] [%-6d] [%06d] [%+d]\n", n, n, n, n, n);

    /* precision: decimal places for reals, a maximum length for strings */
    printf("[%f] [%.2f] [%10.3f] [%e] [%g]\n", x, x, x, x, x);
    printf("[%s] [%10s] [%-10s] [%.3s]\n", s, s, s, s);

    /* bases and characters */
    printf("[%c] [%x] [%X] [%#x] [%o] [%u]\n", 'A', u, u, u, u, u);

    /* length modifiers: they tell the format the width of the argument */
    printf("[%zu] [%lld]\n", sz, big);

    /* passing the width and precision as arguments */
    printf("[%.*s] [%*d]\n", 4, s, 6, n);

    /* the percent character itself */
    printf("100%%\n");
    return 0;
}

[42] [    42] [42    ] [000042] [+42]
[3.141593] [3.14] [     3.142] [3.141593e+00] [3.14159]
[proven] [    proven] [proven    ] [pro]
[A] [ff] [FF] [0xff] [377] [255]
[1234] [9000000000]
[prov] [    42]
100%

There are several things to read here. %06d becoming 000042 is because the 0 flag fills with zeros instead of spaces, and %.3s stopping at pro is because for strings precision is maximum length. The 0x of %#x was attached by the #. %g shortening to 3.14159 is because that conversion automatically chooses the shorter of %e and %f.

The length modifier is not decoration but a contract. As chapter 58 showed, type information does not ride along into variadic arguments, so printf reads the stack at exactly the width the format stated. That is why code printing a size_t with %d quietly goes out of step on 64-bit — 8 bytes were put in and only 4 are taken out.

61.4 The input format string — what differs

The formats of the scanf family overlap in their letters with output and so look like the same language, but what they do is the opposite and their rules differ. Five points of difference.

First, the argument is not a value but the address of a place to hold it. Leave out the & and it mistakes an integer for an address and tries to write at that address — the reason the & met in chapter 25 is compulsory here.

Second, whitespace in the format means “any number of whitespace characters (none is fine too)”. In output a space is simply one space, but in input it is an instruction to skip. Most conversions skip leading whitespace by themselves — the exceptions are %c and %[, which read whitespace as characters too.

Third, ordinary characters in the format must match the input exactly. "x=%d" requires the input to begin with x=. If it does not match it stops with a matching failure.

Fourth, the return value is not the number of characters printed but the number of items successfully assigned. So when three were to be read and 2 comes back, one was not filled, and that argument is left untouched. If there was no input at all, EOF (a negative value) comes back — it must be distinguished from 0.

Fifth, always give %s a maximum width. A %s without a width writes without knowing the destination’s size, the same danger as chapter 43′s gets.

#include <stdio.h>

int main(void) {
    int a = 0, b = 0, k;
    double d = 0.0;
    char word[8] = {0};
    char rest[16] = {0};

    /* one space in the format means "any number of whitespace characters" */
    k = sscanf("  12   34", "%d %d", &a, &b);
    printf("ints    : k=%d a=%d b=%d\n", k, a, b);

    /* %s stops at whitespace. A width protects the buffer */
    k = sscanf("hello world", "%7s", word);
    printf("bounded : k=%d word=[%s]\n", k, word);

    /* an ordinary character in the format must match the input exactly */
    k = sscanf("x=5", "x=%d", &a);
    printf("literal : k=%d a=%d\n", k, a);

    /* if it does not match it is a matching failure — 0 is returned and the argument is untouched */
    k = sscanf("y=5", "x=%d", &a);
    printf("mismatch: k=%d (a stays %d)\n", k, a);

    /* a conversion failure is 0 as well — not a number, so nothing is read */
    k = sscanf("abc", "%d", &b);
    printf("nonnum  : k=%d (b stays %d)\n", k, b);

    /* an empty input gives EOF (a negative value) — it must be told apart from 0 */
    k = sscanf("", "%d", &b);
    printf("empty   : k=%d\n", k);

    /* partial success: the front is read and it stops further on */
    k = sscanf("7 oops", "%d %lf", &a, &d);
    printf("partial : k=%d a=%d\n", k, a);

    /* the set specifier: it gathers characters that are not a comma */
    k = sscanf("name,42", "%15[^,],%d", rest, &b);
    printf("set     : k=%d rest=[%s] b=%d\n", k, rest, b);

    /* reals and the length modifier: a double is %lf */
    k = sscanf("3.5", "%lf", &d);
    printf("double  : k=%d d=%.2f\n", k, d);
    return 0;
}

ints    : k=2 a=12 b=34
bounded : k=1 word=[hello]
literal : k=1 a=5
mismatch: k=0 (a stays 5)
nonnum  : k=0 (b stays 34)
empty   : k=-1
partial : k=1 a=7
set     : k=2 rest=[name] b=42
double  : k=1 d=3.50

Going through the output line by line makes the rules visible. mismatch and nonnum both have k=0, and what matters is that the argument remains as it was — use it without checking the value and you mistake the previous value for new input. empty’s -1 means “the input has ended”, not “the format was wrong”. partial is the case where only the leading integer was read and it stopped after. set’s %15[^,] means “at most 15 characters that are not a comma”, used for cutting a line with separators.

61.5 The places to beware

Gathering the traps this book has met along the way, from the library’s point of view, gives this.

• Functions that do not take a size — the strcpy, strcat and sprintf families do not know the size of the destination vessel (chapter 43′s gets was the extreme). The alternatives are the editions that take a size (snprintf) or components that manage the boundary.
• Functions whose return value reports failure — malloc, fopen and fgets give null on failure (chapter 51′s discipline: do not use without checking).
• The global state called errno — many functions leave the reason for failure in a global variable. Some do not clear it even on success, so the convention of “set it to 0 just before the call and read it just after” must be kept — a textbook case showing the inconvenience of global mutable state (chapter 44).
• Locale- and culture-dependent functions — character functions such as toupper and strtod’s interpretation of the decimal point behave differently according to the locale setting. When handling a data format it is safer to use locale-independent processing (the same grain as chapter 9′s “do not guess the encoding”).
• Functions that return a static buffer — the asctime and strtok families reuse a fixed place inside, so the next call overwrites the previous result. It is especially dangerous in a program running along several strands (chapter 12′s multicore).

The landscape is spread out. The next part (Part XI) walks the regions of this landscape one by one and faces head on the places where accidents really happen in each header — streams and files, strings, conversion and allocation, characters and locales, numbers and time, and diagnosis and control.