Mirror of Beej's Guide to C Programming

What’s this? You say something’s still not clear about this whole C programming language thing?

Well, to be quite honest, I’m not even sure what the above code does. It’s a snippet from one of the entries in the 2001 International Obfuscated C Code Contest ¹, a wonderful competition wherein the entrants attempt to write the most unreadable C code possible, with often surprising results.

The bad news is that if you’re a beginner in this whole thing, all C code you see probably looks obfuscated! The good news is, it’s not going to be that way for long.

What we’ll try to do over the course of this guide is lead you from complete and utter sheer lost confusion on to the sort of enlightened bliss that can only be obtained though pure C programming. Right on.

1.1 Audience

This guide assumes that you’ve already got some programming knowledge under your belt from another language, such as Python ², JavaScript ³, Java ⁴, Rust ⁵, Go ⁶, Swift ⁷, etc. (Objective-C ⁸ devs will have a particularly easy time of it!)

We’re going to assume you know what variables are, what loops do, how functions work, and so on.

If that’s not you for whatever reason the best I can hope to provide is some pastey entertainment for your reading pleasure. The only thing I can reasonably promise is that this guide won’t end on a cliffhanger…or will it?

1.2 Platform and Compiler

I’ll try to stick to Plain Ol’-Fashioned ISO-standard C ⁹. Well, for the most part. Here and there I might go crazy and start talking about POSIX ¹⁰ or something, but we’ll see.

Unix users (e.g. Linux, BSD, etc.) try running cc or gcc from the command line–you might already have a compiler installed. If you don’t, search your distribution for installing gcc or clang.

Windows users should check out Visual Studio Community ¹¹. Or, if you’re looking for a more Unix-like experience (recommended!), install WSL ¹² and gcc.

Mac users will want to install XCode ¹³, and in particular the command line tools.

There are a lot of compilers out there, and virtually all of them will work for this book. And for those not in the know, a C++ compiler will compile C most code, so it’ll work for the purposes of this guide.

1.3 Official Homepage

This official location of this document is http://beej.us/guide/bgc/¹⁴. Maybe this’ll change in the future, but it’s more likely that all the other guides are migrated off Chico State computers.

1.4 Email Policy

I’m generally available to help out with email questions so feel free to write in, but I can’t guarantee a response. I lead a pretty busy life and there are times when I just can’t answer a question you have. When that’s the case, I usually just delete the message. It’s nothing personal; I just won’t ever have the time to give the detailed answer you require.

As a rule, the more complex the question, the less likely I am to respond. If you can narrow down your question before mailing it and be sure to include any pertinent information (like platform, compiler, error messages you’re getting, and anything else you think might help me troubleshoot), you’re much more likely to get a response.

If you don’t get a response, hack on it some more, try to find the answer, and if it’s still elusive, then write me again with the information you’ve found and hopefully it will be enough for me to help out.

Now that I’ve badgered you about how to write and not write me, I’d just like to let you know that I fully appreciate all the praise the guide has received over the years. It’s a real morale boost, and it gladdens me to hear that it is being used for good! :-) Thank you!

1.5 Mirroring

You are more than welcome to mirror this site, whether publicly or privately. If you publicly mirror the site and want me to link to it from the main page, drop me a line at beej@beej.us.

1.6 Note for Translators

If you want to translate the guide into another language, write me at beej@beej.us and I’ll link to your translation from the main page. Feel free to add your name and contact info to the translation.

Please note the license restrictions in the Copyright and Distribution section, below.

1.7 Copyright and Distribution

With specific exceptions for source code and translations, below, this work is licensed under the Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-nd/3.0/ or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

One specific exception to the “No Derivative Works” portion of the license is as follows: this guide may be freely translated into any language, provided the translation is accurate, and the guide is reprinted in its entirety. The same license restrictions apply to the translation as to the original guide. The translation may also include the name and contact information for the translator.

The C source code presented in this document is hereby granted to the public domain, and is completely free of any license restriction.

Educators are freely encouraged to recommend or supply copies of this guide to their students.

2 Hello, World!

2.1 What to Expect from C

It didn’t used to be. Back in the day when people carved punch cards out of granite, C was an incredible way to be free of the drudgery of lower-level languages like assembly ¹⁵.

But now in these modern times, current-generation languages offer all kinds of features that didn’t exist in 1972 when C was invented. This means C is a pretty basic language with not a lot of features. It can do anything, but it can make you work for it.

If you’re familiar with another language, a lot of things about C are easy. C inspired many other languages, and you’ll see bits of it in Go, Rust, Swift, Python, JavaScript, Java, and all kinds of other languages. Those parts will be familiar.

The one thing about C that hangs people up is pointers. Virtually everything else is familiar, but pointers are the weird one. The concept behind pointers is likely one you already know, but C forces you to be explicit about it, using operators you’ve likely never seen before.

It’s especially insidious because once you grok²⁰ pointers, they’re suddenly easy. But up until that moment, they’re slippery eels.

Everything else in C is just memorizing another way (or sometimes the same way!) of doing something you’ve done already. Pointers are the weird bit.

So get ready for a rollicking adventure as close to the core of the computer as you can get without assembly, in the most influential computer language of all time²¹. Hang on!

2.2 Hello, World!

This is the canonical example of a C program. Everyone uses it. (Note that the numbers to the left are for reader reference only, and are not part of the source code.)

/* Hello world program */

#include <stdio.h>

int main(void)
{
    printf("Hello, World!\n");  // Actually do the work here
}

We’re going to don our long-sleeved heavy-duty rubber gloves, grab a scalpel, and rip into this thing to see what makes it tick. So, scrub up, because here we go. Cutting very gently…

Let’s get the easy thing out of the way: anything between the digraphs /* and */ is a comment and will be completely ignored by the compiler. Same goes for anything on a line after a //. This allows you to leave messages to yourself and others, so that when you come back and read your code in the distant future, you’ll know what the heck it was you were trying to do. Believe me, you will forget; it happens.

Now, what is this #include? GROSS! Well, it tells the C Preprocessor to pull the contents of another file and insert it into the code right there.

Wait—what’s a C Preprocessor? Good question. There are two stages (well, technically there are more than two, but hey, let’s pretend there are two and have a good laugh) to compilation: the preprocessor and the compiler. Anything that starts with pound sign, or “octothorpe”, (#) is something the preprocessor operates on before the compiler even gets started. Common preprocessor directives, as they’re called, are #include and #define. More on that later.

Before we go on, why would I even begin to bother pointing out that a pound sign is called an octothorpe? The answer is simple: I think the word octothorpe is so excellently funny, I have to gratuitously spread its name around whenever I get the opportunity. Octothorpe. Octothorpe, octothorpe, octothorpe.

So anyway. After the C preprocessor has finished preprocessing everything, the results are ready for the compiler to take them and produce assembly code ²², machine code ²³, or whatever it’s about to do. Don’t worry about the technical details of compilation for now; just know that your source runs through the preprocessor, then the output of that runs through the compiler, then that produces an executable for you to run. Octothorpe.

What about the rest of the line? What’s <stdio.h>? That is what is known as a header file. It’s the dot-h at the end that gives it away. In fact it’s the “Standard I/O” (stdio) header file that you will grow to know and love. It contains preprocessor directives and function prototypes (more on that later) for common input and output needs. For our demo program, we’re outputting the string “Hello, World!”, so we in particular need the function prototype for the printf() function from this header file. Basically, if we tried to use printf() without #include <stdio.h>, the compiler would have complained to us about it.

How did I know I needed to #include <stdio.h> for printf()? Answer: it’s in the documentation. If you’re on a Unix system, man printf and it’ll tell you right at the top of the man page what header files are required. Or see the reference section in this book. :-)

Holy moly. That was all to cover the first line! But, let’s face it, it has been completely dissected. No mystery shall remain!

So take a breather…look back over the sample code. Only a couple easy lines to go.

Welcome back from your break! I know you didn’t really take a break; I was just humoring you.

The next line is main(). This is the definition of the function main(); everything between the squirrelly braces ({ and }) is part of the function definition.

How do you call a different function, anyway? The answer lies in the printf() line, but we’ll get to that in a minute.

Now, the main function is a special one in many ways, but one way stands above the rest: it is the function that will be called automatically when your program starts executing. Nothing of yours gets called before main(). In the case of our example, this works fine since all we want to do is print a line and exit.

Oh, that’s another thing: once the program executes past the end of main(), down there at the closing squirrelly brace, the program will exit, and you’ll be back at your command prompt.

So now we know that that program has brought in a header file, stdio.h, and declared a main() function that will execute when the program is started. What are the goodies in main()?

I am so happy you asked. Really! We only have the one goodie: a call to the function printf(). You can tell this is a function call and not a function definition in a number of ways, but one indicator is the lack of squirrelly braces after it. And you end the function call with a semicolon so the compiler knows it’s the end of the expression. You’ll be putting semicolons after most everything, as you’ll see.

You’re passing one parameter to the function printf(): a string to be printed when you call it. Oh, yeah—we’re calling a function! We rock! Wait, wait—don’t get cocky. What’s that crazy \n at the end of the string? Well, most characters in the string look just like they are stored. But there are certain characters that you can’t print on screen well that are embedded as two-character backslash codes. One of the most popular is \n (read “backslash-N”) that corresponds to the newline character. This is the character that causing further printing to continue on the next line instead of the current. It’s like hitting return at the end of the line.

So copy that code into a file called hello.c and build it. On a Unix-like platform (e.g. Linux, BSD, Mac, or WSL), you’ll build with a command like so:

After that’s done, you should have a file called hello that you can run with this command:

2.3 Compilation

Let’s talk a bit more about how to build C programs, and what happens behind the scenes there.

Like other languages, C has source code. But, depending on what language you’re coming from, you might never have had to compile your source code into an executable.

Compilation is the process of taking your C source code and turning it into a program that your operating system can execute.

JavaScript and Python devs aren’t used to a separate compilation step at all–though behind the scenes it’s happening! Python compiles your source code into something called bytecode that the Python virtual machine can execute. Java devs are used to compilation, but that produces bytecode for the Java Virtual Machine.

When compiling C, machine code is generated. This is the 1s and 0s that can be executed directly by the CPU.

As we’ve already said, gcc is a compiler that’s installed on a lot of Unix-like operating systems ²⁴. And it’s commonly run from the command line in a terminal, but not always. You can run it from your IDE, as well.

But we’ll do some command line examples here because there are too many IDEs to cover. Search the Internet for your IDE and “how to compile C” for more information.

2.4 Building with gcc

If you have a source file called hello.c in the current directory, you can build that into a program called hello with this command typed in a terminal:

The -o means “output to this file”²⁵. And there’s hello.c at the end, the name of the file we want to compile.

If your source is broken up into multiple files, you can compile them all together (almost as if they were one file, but the rules are actually more complex than that) by putting all the .c files on the command line:

That’s enough to get started—later we’ll talk details about multiple source files, object files, and all kinds of fun stuff.

2.5 C Versions

C has come a long way over the years, and it had many named version numbers to describe which dialect of the language you’re using.

The most famous are C89, C99, and C11. We’ll focus on the latter in this book.

Version	Description
K&R C	1978, the original. Named after Brian Kernighan and Dennis Ritchie. Ritchie designed and coded the language, and Kernighan co-authored the book on it. You rarely see original K&R code today. If you do, it’ll look odd, like Middle English looks odd to modern English readers.
C89, ANSI C, C90	In 1989, the American National Standards Institute (ANSI) produced a C language specification that set the tone for C that persists to this day. A year later, the reins were handed to the International Organization for Standardization (ISO) that produced the identical C90.
C95	A rarely-mentioned addition to C89 that included wide character support.
C99	The first big overhaul with lots of language additions. The thing most people will rememeber is the addition of `//`-style comments. This is the most popular version of C in use as of this writing.
C11	This major version update includes Unicode support and multi-threading. Be advised that if you start using these language features, you might be sacrificing portability with places that are stuck in C99 land. But, honestly, 1999 is getting to be a while back now.
C17, C18	Bugfix update to C11. C17 seems to be the official name, but the publication was delayed until 2018. As far as I can tell, these two are interchangeable, with C17 being preferred.
C2x	What’s coming next! Expected to eventually become C21.

You can force GCC to use one of these standards with the -std= command line argument. If you want it to be picky about the standard, add -pedantic.

3 Variables and Statements

And for various reasons, it’ll be easier for all of us if we classify some of the types of things you can find in a program, so we can be clear what we’re talking about.

3.1 Variables

It’s said that “variables hold values”. But another way to think about it is that a variable is a human-readable name that refers to some data in memory.

We’re going to take a second here and take a peek down the rabbit hole that is pointers. Don’t worry about it.

You can think of memory as a big array of bytes²⁶ Data is stored in this “array”²⁷. If a number is larger than a single byte, it is stored in multiple bytes. Because memory is like an array, each byte of memory can be referred to by its index. This index into memory is also called an address, or a location, or a pointer.

When you have a variable in C, the value of that variable is in memory somewhere, at some address. Of course. After all, where else would it be? But it’s a pain to refer to a value by its numeric address, so we make a name for it instead, and that’s what the variable is.

So a variable is a name for some data that’s stored in memory at some address.

3.1.1 Variable Names

You can use any characters in the range 0-9, A-Z, a-z, and underscore for variable names, with the following rules:

For Unicode, things get a little different, but the basic idea is that you can start or continue the variable name with one of the characters listed in C11 §D.1, and you can continue but not start a variable name with any of the characters listed in C11 §D.2.

Since those are just number ranges, I’m not going to reproduce them here. If you’re in an environment that supports Unicode, just try it and see if it works.

Just don’t start a variable name with the “Combining Left Harpoon Above” character and you’ll be fine.

3.1.2 Variable Types

Depending on which languages you already have in your toolkit, you might or might not be familiar with the idea of types. But C’s kinda picky about them, so we should do a refresher.

C makes an effort to convert automatically between most numeric types when you ask it to. But other than that, all conversions are manual, notably between string and numeric.

Type	Example	C Type
Integer	`3490`	`int`
Floating point	`3.14159`	`float`
Character (single)	`'c'`	`char`
String	`"Hello, world!"`	`char *`²⁸

Before you can use a variable, you have to declare that variable and tell C what type the variable holds. Once declared, the type of variable cannot be changed later at runtime. What you set it to is what it is until it falls out of scope and is reabsorbed into the universe.

Let’s take our previous “Hello, world” code and add a couple variables to it:

#include <stdio.h>

int main(void)
{
    int i;    /* holds signed integers, e.g. -3, -2, 0, 1, 10 */
    float f;  /* holds signed floating point numbers, e.g. -3.1416 */

    printf("Hello, World!\n"); /* ah, blessed familiarity */
}

There! We’ve declared a couple of variables. We haven’t used them yet, and they’re both uninitialized. One holds an integer number, and the other holds a floating point number (a real number, basically, if you have a math background).

Uninitialized variables have indeterminate value²⁹. They have to be initialized or else you must assume they contain some nonsense number.

int main(void)
{
    int i;

    i = 2; // Assign the value 2 into the variable i

    printf("Hello, World!\n");
}

We’re going to do that by passing two amazing parameters to the printf() function. The first argument is a string that describes what to print and how to print it (called the format string), and the second is the value to print, namely whatever is in the variable i.

printf() hunts through the format string for a variety of special sequences which start with a percent sign (%) that tell it what to print. For example, if it finds a %d, it looks to the next parameter that was passed, and prints it out as an integer. If it finds a %f, it prints the value out as a float. If it finds a %s, it prints a string.

int main(void)
{
    int i = 2;
    float f = 3.14;
    char *s = "Hello, world!";  // char * ("char pointer") is the string type

    printf("%s  i = %d and f = %f!\n", s, i, f);
}

In this way, printf() might be similar to various types of format or parameterized strings in other languages you’re familiar with.

3.1.3 Boolean Types

Historically, C didn’t have a Boolean type, and some might argue it still doesn’t.

    int x = 1;
    
    if (x) {
        printf("x is true!\n");
    }

If you #include <stdbool.h>, you also get access to some symbolic names that might make things look more familiar, namely a bool type and true and false values:

#include <stdio.h>
#include <stdbool.h>

int main(void) {
    bool x = true;

    if (x) {
        printf("x is true!\n");
    }
}

But these are identical to using integer values for true and false. They’re just a facade to make things look nice.

3.2 Operators and Expressions

C operators should be familiar to you from other languages. Let’s blast through some of them here.

(There are a bunch more details than this, but we’re going to do enough in this section to get started.)

3.2.1 The sizeof Operator

This operator tells you the size (in bytes) that a particular variable or data type uses in memory.

More particularly, it tells you the size (in bytes) that the type of a particular expression (which might be just a single variable) uses in memory.

This can be different on different systems, except for char (which is always 1 byte).

And this might not seem very useful now, but we’ll be making reference to it here and there, so it’s worth covering.

    int a = 999;
    
    // %zu is the format specifier for type size_t ("t" is for "type", but
    // it's pronounced "size tee"), which is what is returned by sizeof.
    // More on size_t later.
    
    printf("%zu", sizeof a);      // Prints 4 on my system
    printf("%zu", sizeof(2 + 7)); // Prints 4 on my system
    printf("%zu", sizeof 3.14);   // Prints 8 on my system

Remember: it’s the size in bytes of the type of the expression, not the size of the expression itself. That’s why the size of 2+7 is the same as the size of a—they’re both type int. We’ll revisit this number 4 in the very next block of code…

…Where we’ll see you can take the sizeof a type (note the parentheses are required around a type name, unlike an expression):

    printf("%zu", sizeof(int));   // Prints 4 on my system
    printf("%zu", sizeof(char));  // Prints 1 on all systems

It’s important to note that sizeof is a compile-time operation³⁰. The result of the expression is determined entirely at compiletime, not at runtime.

3.2.2 Arithmetic

    i = i + 3;  // addition (+) and assignment (=) operators, add 3 to i
    i = i - 8;  // subtraction, subtract 8 from i
    i = i * 9;  // multiplication
    i = i / 2;  // division
    i = i % 5;  // modulo (division remainder)

There are shorthand variants for all of the above. Each of those lines could more tersely be written as:

    i += 3;  // Same as "i = i + 3", add 3 to i
    i -= 8;  // Same as "i = i - 8"
    i *= 9;  // Same as "i = i * 9"
    i /= 2;  // Same as "i = i / 2"
    i %= 5;  // Same as "i = i % 5"

There is no exponentiation. You’ll have to use one of the pow() function variants from math.h.

Let’s get into some of the weirder stuff you might not have in your other languages!

3.2.3 Ternary Operator

C also includes the ternary operator. This is an expression whose value depends on the result of a conditional embedded in it.

    // If x > 10, add 17 to y. Otherwise add 37 to y.
    
    y += x > 10? 17: 37;

What a mess! You’ll get used to it the more you read it. To help out a bit, I’ll rewrite the above expression using if statements:

    // This expression:
    
    y += x > 10? 17: 37;
    
    // is equivalent to this non-expression:
    
    if (x > 10)
        y += 17;
    else
        y += 37;

The %s format specifier in printf() means print a string. If the expression x % 2 evaluates to 0, the value of the entire ternary expression evaluates to the string "even". Otherwise it evaluates to the string "odd". Pretty cool!

It’s important to note that the ternary operator isn’t flow control like the if statement is. It’s just an expression that evaluates to a value.

3.2.4 Pre-and-Post Increment-and-Decrement

    i++;        // Add one to i (post-increment)
    i--;        // Subtract one from i (post-decrement)

    i += 1;        // Add one to i
    i -= 1;        // Subtract one from i

    ++i;        // Add one to i (pre-increment)
    --i;        // Subtract one from i (pre-decrement)

With pre-increment and pre-decrement, the value of the variable is incremented or decremented before the expression is evaluated. Then the expression is evaluated with the new value.

With post-increment and post-decrement, the value of the expression is first computed with the value as-is, and then the value is incremented or decremented after the value of the expression has been determined.

    i = 10;
    j = 5 + i++;  // Compute 5 + i, _then_ increment i
    
    printf("%d, %d\n", i, j);  // Prints 11, 15

    i = 10;
    j = 5 + ++i;  // Increment i, _then_ compute 5 + i
    
    printf("%d, %d\n", i, j);  // Prints 11, 16

This technique is used frequently with array and pointer access and manipulation. It gives you a way to use the value in a variable, and also increment or decrement that value before or after it is used.

    for (i = 0; i < 10; i++)
        printf("i is %d\n");

3.2.5 The Comma Operator

This is an uncommonly-used way to separated expressions that will run left to right:

    x = 10, y = 20;  // First assign 10 to x, then 20 to y

Seems a bit silly, since you could just replace the comma with a semicolon, right?

    x = 10; y = 20;  // First assign 10 to x, then 20 to y

But that’s a little different. The latter is two separate expressions, while the former is a single expression!

With the comma operator, the value of the comma expression is the value of the rightmost expression:

    x = 1, 2, 3;
    
    printf("x is %d\n", x);  // Prints 3, because 3 is rightmost in the comma list

But even that’s pretty contrived. One common place the comma operator is used is in for loops to do multiple things in each section of the statement:

    for (i = 0, j = 10; i < 100; i++, j++)
        printf("%d, %d\n", i, j);

3.2.6 Conditional Operators

    a == b;  // True if a is equivalent to b
    a != b;  // True if a is not equivalent to b
    a < b;   // True if a is less than b
    a > b;   // True if a is greater than b
    a <= b;  // True if a is less than or equal to b
    a >= b;  // True if a is greater than or equal to b

Don’t mix up assignment = with comparison ==! Use two equals to compare, one to assign.

3.2.7 Boolean Operators

We can chain together or alter conditional expressions with Boolean operators for and, or, and not.

Operator	Boolean meaning
`&&`	and
`\|\|`	or
`!`	not

    // Do something if x less than 10 and y greater than 20:
    
    if (x < 10 && y > 20)
        printf("Doing something!\n");

    if (!(x < 12))
        printf("x is not less than 12\n");

! has higher precedence than the other Boolean operators, so we have to use parentheses in that case.

    if (x >= 12)
        printf("x is not less than 12\n");

3.3 Flow Control

Booleans are all good, but of course we’re nowhere if we can’t control program flow. Let’s take a look at a number of constructs: if, for, while, and do-while.

First, a general forward-looking note about statements and blocks of statements brought to you by your local friendly C developer:

After something like an if or while statement, you can either put a single statement to be executed, or a block of statements to all be executed in sequence.

    if (x == 10) printf("x is 10");

This is also sometimes written on a separate line. (Whitespace is largely irrelevant in C—it’s not like Python.)

    if (x == 10)
        printf("x is 10\n");

But what if you want multiple things to happen due to the conditional? You can use squirrelly braces to mark a block or compound statement.

    if (x == 10) {
        printf("x is 10\n");
        printf("And also this happens when x is 10\n");
    }

It’s a really common style to always use squirrelly braces even if they aren’t necessary:

    if (x == 10) {
        printf("x is 10\n");
    }

Some devs feel the code is easier to read and avoids errors like this where things visually look like they’re in the if block, but actually they aren’t.

    // BAD ERROR EXAMPLE
    
    if (x == 10)
        printf("x is 10\n");
        printf("And also this happens ALWAYS\n");  // Surprise!! Unconditional!

while and for and the other looping constructs work the same way as the examples above. If you want to do multiple things in a loop or after an if, wrap them up in squirrelly braces.

In other words, the if is going to run the one thing after the if. And that one thing can be a single statement or a block of statements.

3.3.1 The if statement

We’ve already been using if for multiple examples, since it’s likely you’ve seen it in a language before, but here’s another:

    int i = 10;
    
    if (i > 10) {
        printf("Yes, i is greater than 10.\n");
        printf("And this will also print if i is greater than 10.\n");
    }
    
    if (i <= 10) printf("i is less than or equal to 10.\n");

In the example code, the message will print if i is greater than 10, otherwise execution continues to the next line. Notice the squirrley braces after the if statement; if the condition is true, either the first statement or expression right after the if will be executed, or else the collection of code in the squirlley braces after the if will be executed. This sort of code block behavior is common to all statements.

3.3.2 The while statement

while is your average run-of-the-mill looping construct. Do a thing while a condition expression is true.

    // print the following output:
    //
    //   i is now 0!
    //   i is now 1!
    //   [ more of the same between 2 and 7 ]
    //   i is now 8!
    //   i is now 9!
    
    i = 0;
    
    while (i < 10) {
        printf("i is now %d!\n", i);
        i++;
    }
    
    printf("All done!\n");

That gets you a basic loop. C also has a for loop which would have been cleaner for that example.

A not-uncommon use of while is for infinite loops where you repeat while true:

    while (1) {
        printf("1 is always true, so this repeats forever.\n");
    }

3.3.3 The do-while statement

So now that we’ve gotten the while statement under control, let’s take a look at its closely related cousin, do-while.

They are basically the same, except if the loop condition is false on the first pass, do-while will execute once, but while won’t execute at all. Let’s see by example:

    /* using a while statement: */
    
    i = 10;
    
    // this is not executed because i is not less than 10:
    while(i < 10) {
        printf("while: i is %d\n", i);
        i++;
    }
    
    /* using a do-while statement: */
    
    i = 10;
    
    // this is executed once, because the loop condition is not checked until
    // after the body of the loop runs:
    
    do {
        printf("do-while: i is %d\n", i);
        i++;
    } while (i < 10);
    
    printf("All done!\n");

Notice that in both cases, the loop condition is false right away. So in the while, the loop fails, and the following block of code is never executed. With the do-while, however, the condition is checked after the block of code executes, so it always executes at least once. In this case, it prints the message, increments i, then fails the condition, and continues to the “All done!” output.

The moral of the story is this: if you want the loop to execute at least once, no matter what the loop condition, use do-while.

All these examples might have been better done with a for loop. Let’s do something less deterministic—repeat until a certain random number comes up!

#include <stdio.h>   // For printf
#include <stdlib.h>  // For rand

int main(void)
{
    int r;

    do {
        r = rand() % 100; // Get a random number between 0 and 99
        printf("%d\n", r);
    } while (r != 37);    // Repeat until 37 comes up
}

3.3.4 The for statement

This is a great loop if you know the number of times you want to loop in advance.

You could do the same thing using just a while loop, but the for loop can help keep the code cleaner.

Here are two pieces of equivalent code—note how the for loop is just a more compact representation:

    // Print numbers between 0 and 9, inclusive...
    
    // Using a while statement:
    
    i = 0;
    while (i < 10) {
        printf("i is %d\n", i);
        i++;
    }
    
    // Do the exact same thing with a for-loop:
    
    for (i = 0; i < 10; i++) {
        printf("i is %d\n", i);
    }

That’s right, folks—they do exactly the same thing. But you can see how the for statement is a little more compact and easy on the eyes. (JavaScript users will fully appreciate its C origins at this point.)

It’s split into three parts, separated by semicolons. The first is the initialization, the second is the loop condition, and the third is what should happen at the end of the block if the loop condition is true. All three of these parts are optional.

    for (initialize things; loop if this is true; do this after each loop)

Note that the loop will not execute even a single time if the loop condition starts off false.

    for(;;) {  // "forever"
        printf("I will print this again and again and again\n" );
        printf("for all eternity until the cold-death of the universe.\n");
    }

3.3.5 The switch Statement

Depending on what languages you’re coming from, you might or might not be familiar with switch, or C’s version might even be more restrictive than you’re used to. This is a statement that allows you to take a variety of actions depending on the value of an integer expression.

Basically, it evaluates an expression to an integer value, jumps to the case that corresponds to that value. Execution resumes from that point. If a break statement is encountered, then execution jumps out of the switch.

Let’s do an example where the user enters a number of goats and we print out a gut-feel of how many goats that is.

#include <stdio.h>

int main(void)
{
    int goat_count;

    printf("Enter a goat count: ");
    scanf("%d", &goat_count);       // Read an integer from the keyboard

    switch (goat_count) {
        case 0:
            printf("You have no goats.\n");
            break;

        case 1:
            printf("You have a singular goat.\n");
            break;

        case 2:
            printf("You have a brace of goats.\n");
            break;

        default:
            printf("You have a bona fide plethora of goats!\n");
            break;
    }
}

In that example, if the user enters, say, 2, the switch will jump to the case 2 and execute from there. When (if) it hits a break, it jumps out of the switch.

Also, you might see that default label there at the bottom. This is what happens when no cases match.

Every case, including default, is optional. And they can occur in any order, but it’s really typical for default, if any, to be listed last.

    if (goat_count == 0)
        printf("You have no goats.\n");
    else if (goat_count == 1)
        printf("You have a singular goat.\n");
    else if (goat_count == 2)
        printf("You have a brace of goats.\n");
    else:
        printf("You have a bona fide plethora of goats!\n");

There’s one more neat thing about switch that you sometimes see that is quite interesting: fall through.

    switch (x) {
        case 1:
            printf("1\n");
            // fall through!
        case 2:
            printf("2\n");
            break;
        case 3:
            printf("3\n");
            break;
    }

If x == 1, this switch will first hit case 1, it’ll print the 1, but then it just continues on to the next line of code… which prints 2!

ProTip: ALWAYS put a comment in the code where you intend to fall through, like I did above. It will save other programmers from wondering if you meant to do that.

In fact, this is one of the common places to introduce bugs in C programs: forgetting to put a break in your case. You gotta do it if you don’t want to just roll into the next case³¹.

4 Functions

Very much like other languages you’re used to, C has the concept of functions.

Functions can accept a variety of arguments and return a value. One important thing, though: the arguments and return value types are predeclared—because that’s how C likes it!

Let’s take a look at a function. This is a function that takes an int as an argument, and returns an int.

int plus_one(int n)  // The "definition"
{
    return n + 1;
}

The int n indicates that this function takes one int argument, stored in parameter n.

Continuing the program down into main(), we can see the call to the function, where we assign the return value into local variable j:

int main(void)
{
    int i = 10, j;
    
    j = plus_one(i);  // The "call"

    printf("i + 1 is %d\n", j);
}

But what’s this void thing? This is a keyword that’s used to indicate that the function accepts no arguments.

// This function takes no parameters and returns no value:

void hello(void)
{
    printf("Hello, world!\n");
}

int main(void)
{
    hello();  // Prints "Hello, world!"
}

4.1 Passing by Value

When you pass a value to a function, a copy of that value gets made in this magical mystery world known as the stack³². (The stack is just a hunk of memory somewhere that the program allocates memory on. Some of the stack is used to hold the copies of values that are passed to functions.)

For now, the important part is that a copy of the variable or value is being passed to the function. The practical upshot of this is that since the function is operating on a copy of the value, you can’t affect the value back in the calling function directly. Like if you wanted to increment a value by one, this would NOT work:

void increment(int a)
{
    a++;
}

int main(void)
{
    int i = 10;

    increment(i);
}

You might somewhat sensibly think that the value of i after the call would be 11, since that’s what the ++ does, right? This would be incorrect. What is really happening here?

Well, when you pass i to the increment() function, a copy gets made on the stack, right? It’s the copy that increment() works on, not the original; the original i is unaffected. We even gave the copy a name: a, right? It’s right there in the parameter list of the function definition. So we increment a, sure enough, but what good does that do us out in main() ? None! Ha!

That’s why in the previous example with the plus_one() function, we returned the locally modified value so that we could see it again in main().

Seems a little bit restrictive, huh? Like you can only get one piece of data back from a function, is what you’re thinking. There is, however, another way to get data back; C folks call it passing by reference. But no fancy-schmancy name will distract you from the fact that EVERYTHING you pass to a function WITHOUT EXCEPTION is copied onto the stack and the function operates on that local copy, NO MATTER WHAT. Remember that, even when we’re talking about this so-called passing by reference.

4.2 Function Prototypes

So if you recall back in the ice age a few sections ago, I mentioned that you had to define the function before you used it, otherwise the compiler wouldn’t know about it ahead of time, and would bomb out with an error.

This isn’t quite strictly true. You can notify the compiler in advance that you’ll be using a function of a certain type that has a certain parameter list and that way the function can be defined anywhere at all, as long as the function prototype has been declared first.

Fortunately, the function prototype is really quite easy. It’s merely a copy of the first line of the function definition with a semicolon tacked on the end for good measure. For example, this code calls a function that is defined later, because a prototype has been declared first:

int foo(void);  // This is the prototype!

int main(void)
{
    int i;
    
    i = foo();
}

int foo(void)  // this is the definition, just like the prototype!
{
    return 3490;
}

You might notice something about the sample code we’ve been using…that is, we’ve been using the good old printf() function without defining it or declaring a prototype! How do we get away with this lawlessness? We don’t, actually. There is a prototype; it’s in that header file stdio.h that we included with #include, remember? So we’re still legit, officer!

4.3 Empty Parameter Lists

You might see these from time to time in older code, but you shouldn’t ever code one up in new code. Always use void to indicate that a function takes no parameters. There’s never³³ a reason to do this in modern code.

    void foo()  // Should really have a `void` in there
    {
        printf("Hello, world!\n");
    }

While the spec spells out that the behavior in this instance is as-if you’d indicated void (C11 §6.7.6.3¶14), the void type is there for a reason. Use it.

But in the case of a function prototype, there is a significant difference between using void and not:

    void foo();
    void foo(void);  // Not the same!

Leaving void out of the prototype indicates to the compiler that there is no additional information about the parameters to the function. It effectively turns off all that type checking.

With a prototype definitely use void when you have an empty parameter list.

5 Pointers—Cower In Fear!

Pointers are one of the most feared things in the C language. In fact, they are the one thing that makes this language challenging at all. But why?

Because they, quite honestly, can cause electric shocks to come up through the keyboard and physically weld your arms permanently in place, cursing you to a life at the keyboard in this language from the 70s!

Well, not really. But they can cause huge headaches if you don’t know what you’re doing when you try to mess with them.

Depending on what language you came from, you might already understand the concept of references, where a variable refers to an object of some type.

This is very much the same, except we have to be more explicit with C about when we’re talking about the reference or the thing it refers to.

5.1 Memory and Variables

Computer memory holds data of all kinds, right? It’ll hold floats, ints, or whatever you have. To make memory easy to cope with, each byte of memory is identified by an integer. These integers increase sequentially as you move up through memory. You can think of it as a bunch of numbered boxes, where each box holds a byte³⁴ of data. Or like a big array where each element holds a byte, if you come from a language with arrays. The number that represents each box is called its address.

Now, not all data types use just a byte. For instance, an int is often four bytes, as is a float, but it really depends on the system. You can use the sizeof operator to determine how many bytes of memory a certain type uses.

    // %zu is the format specifier for type size_t ("t" is for "type", but
    // it's pronounced "size tee"), which is what is returned by sizeof.
    // More on size_t later.
    
    printf("an int uses %zu bytes of memory\n", sizeof(int));
    
    // That prints "4" for me, but can vary by system.

When you have a data type that uses more than a byte of memory, the bytes that make up the data are always adjacent to one another in memory. Sometimes they’re in order, and sometimes they’re not³⁵, but that’s platform-dependent, and often taken care of for you without you needing to worry about pesky byte orderings.

So anyway, if we can get on with it and get a drum roll and some forboding music playing for the definition of a pointer, a pointer is a variable that holds an address. Imagine the classical score from 2001: A Space Odessey at this point. Ba bum ba bum ba bum BAAAAH!

Ok, so maybe a bit overwrought here, yes? There’s not a lot of mystery about pointers. They are the address of data. Just like an int variable can hold the value 12, a pointer variable can hold the address of data.

This means that all these things mean the same thing, i.e. a number that represents a point in memory:

I’m going to use these interchangeably. And yes, I just threw location in there because you can never have enough words that mean the same thing.

And a pointer variable holds that address number. Just like a float variable might hold 3.14159.

Often, we like to store the address of some data that we have stored in a variable, as opposed to any old random address out in memory wherever.

So if we have an int, say, and we want a pointer to it, what we want is some way to get the address of that int, right? After all, the pointer just holds the address of the data. What operator do you suppose we’d use to find the address of the int?

Well, by a shocking surprise that must come as something of a shock to you, gentle reader, we use the address-of operator (which happens to be an ampersand: “&”) to find the address of the data. Ampersand.

So for a quick example, we’ll introduce a new format specifier for printf() so you can print a pointer. You know already how %d prints a decimal integer, yes? Well, %p prints a pointer. Now, this pointer is going to look like a garbage number (and it might be printed in hexadecimal³⁶ instead of decimal), but it is merely the index into memory the data is stored in. (Or the index into memory that the first byte of data is stored in, if the data is multi-byte.) In virtually all circumstances, including this one, the actual value of the number printed is unimportant to you, and I show it here only for demonstration of the address-of operator.

#include <stdio.h>

int main(void)
{
    int i = 10;

    printf("The value of i is %d, and its address is %p\n", i, &i);
}

If you’re curious, that hexadecimal number is 140,727,326,896,068 in decimal (base 10 just like Grandma used to use). That’s the index into memory where the variable i’s data is stored. It’s the address of i. It’s the location of i. It’s a pointer to i.

It’s a pointer because it lets you know where i is in memory. Like a home address written on a scrap of paper tells you where you can find a particular house, this number indicates to us where in memory we can find the value of i. It points to i.

Again, we don’t really care what the address’s exact number is, generally. We just care that it’s a pointer to i.

5.2 Pointer Types

Well, this is all well and good. You can now successfully take the address of a variable and print it on the screen. There’s a little something for the ol’ resume, right? Here’s where you grab me by the scruff of the neck and ask politely what the frick pointers are good for.

Excellent question, and we’ll get to that right after these messages from our sponsor.

Welcome back to another installment of Beej’s Guide to Whatever. When we met last we were talking about how to make use of pointers. Well, what we’re going to do is store a pointer off in a variable so that we can use it later. You can identify the pointer type because there’s an asterisk (*) before the variable name and after its type:

int main(void)
{
    int i;  // i's type is "int"
    int *p; // p's type is "pointer to an int", or "int-pointer"
}

Hey, so we have here a variable that is a pointer itself, and it can point to other ints. That it, is can hold the address of other ints. We know it points to ints, since it’s of type int* (read “int-pointer”).

When you do an assignment into a pointer variable, the type of the right hand side of the assignment has to be the same type as the pointer variable. Fortunately for us, when you take the address-of a variable, the resultant type is a pointer to that variable type, so assignments like the following are perfect:

    int i;
    int *p;  // p is a pointer, but is uninitialized and points to garbage
    
    p = &i;  // p is assigned the address of i--p now "points to" i

On the left of the assignment, we have a variable of type pointer-to-int (int*), and on the right side, we have expression of type pointer-to-int since i is an int (because address-of int gives you a pointer to int). The address of a thing can be stored in a pointer to that thing.

Get it? I know is still doesn’t quite make much sense since you haven’t seen an actual use for the pointer variable, but we’re taking small steps here so that no one gets lost. So now, let’s introduce you to the anti-address-of, operator. It’s kind of like what address-of would be like in Bizarro World.

5.3 Dereferencing

A pointer variable can be thought of as referring to another variable by pointing to it. It’s rare you’ll hear anyone in C land talking about “referring” or “references”, but I bring it up just so that the name of this operator will make a little more sense.

When you have a pointer to a variable (roughly “a reference to a variable”), you can use the original variable through the pointer by dereferencing the pointer. (You can think of this as “de-pointering” the pointer, but no one ever says “de-pointering”.)

What do I mean by “get access to the original variable”? Well, if you have a variable called i, and you have a pointer to i called p, you can use the dereferenced pointer p exactly as if it were the original variable i!

You almost have enough knowledge to handle an example. The last tidbit you need to know is actually this: what is the dereference operator? It is the asterisk, again: *. Now, don’t get this confused with the asterisk you used in the pointer declaration, earlier. They are the same character, but they have different meanings in different contexts³⁷.

#include <stdio.h>

int main(void)
{
    int i;
    int *p;  // this is NOT a dereference--this is a type "int*"

    p = &i;  // p now points to i, p holds address of i

    i = 10;  // i is now 10
    *p = 20; // i (yes i!) is now 20!!

    printf("i is %d\n", i);   // prints "20"
    printf("i is %d\n", *p);  // "20"! dereference-p is the same as i!
}

Remember that p holds the address of i, as you can see where we did the assignment to p on line 8. What the dereference operator does is tells the computer to use the object the pointer points to instead of using the pointer itself. In this way, we have turned *p into an alias of sorts for i.

5.4 Passing Pointers as Parameters

Right about now, you’re thinking that you have an awful lot of knowledge about pointers, but absolutely zero application, right? I mean, what use is *p if you could just simply say i instead?

Well, my feathered friend, the real power of pointers comes into play when you start passing them to functions. Why is this a big deal? You might recall from before that you could pass all kinds of parameters to functions and they’d be dutifully copied onto the stack, and then you could manipulate local copies of those variables from within the function, and then you could return a single value.

What if you wanted to bring back more than one single piece of data from the function? I mean, you can only return one thing, right? What if I answered that question with another question? …Er, two questions?

What happens when you pass a pointer as a parameter to a function? Does a copy of the pointer get put on the stack? You bet your sweet peas it does. Remember how earlier I rambled on and on about how EVERY SINGLE PARAMETER gets copied onto the stack and the function uses a copy of the parameter? Well, the same is true here. The function will get a copy of the pointer.

But, and this is the clever part: we will have set up the pointer in advance to point at a variable…and then the function can dereference its copy of the pointer to get back to the original variable! The function can’t see the variable itself, but it can certainly dereference a pointer to that variable!

This is analogous to writing a home address on a piece of paper, and then copying that onto another piece of paper. You now have two pointers to that house. In the case of a function call. one of the copies is stored in a pointer variable out in the calling scope, and the other is stored in a pointer variable that is the parameter of the function.

#include <stdio.h>

void increment(int *p)  // note that it accepts a pointer to an int
{
    *p = *p + 1;        // add one to the thing p points to
}

int main(void)
{
    int i = 10;
    int *j = &i;  // note the address-of; turns it into a pointer to i

    printf("i is %d\n", i);        // prints "10"
    printf("i is also %d\n", *j);  // prints "10"

    increment(j);                  // j is an int*--to i

    printf("i is %d\n", i);        // prints "11"!
}

Ok! There are a couple things to see here…not the least of which is that the increment() function takes an int* as a parameter. We pass it an int* in the call by changing the int variable i to an int* using the address-of operator. (Remember, a pointer holds an address, so we make pointers to variables by running them through the address-of operator.)

The increment() function gets a copy of the pointer on the stack. Both the original pointer j (in main()) and the copy of that pointer p (the parameter in increment()) point to the same address, namely the one holding the value i. (Again, by analogy, like two pieces of paper with the same home address written on them.) Dereferencing either will allow you to modify the original variable i! The function can modify a variable in another scope! Rock on!

The above example is often more concisely written in the call just by using address-of right in the argument list:

    printf("i is %d\n", i);  // prints "10"
    increment(&i);
    printf("i is %d\n", i);  // prints "11"!

Pointer enthusiasts will recall from early on in the guide, we used a function to read from the keyboard, scanf()…and, although you might not have recognized it at the time, we used the address-of to pass a pointer to a value to scanf(). We had to pass a pointer, see, because scanf() reads from the keyboard (typically) and stores the result in a variable. The only way it can see that variable that is local to that calling function is if we pass a pointer to that variable:

    int i = 0;
    
    scanf("%d", &i);         // pretend you typed "12"
    printf("i is %d\n", i);  // prints "i is 12"

See, scanf() dereferences the pointer we pass it in order to modify the variable it points to. And now you know why you have to put that pesky ampersand in there!

5.5 The NULL Pointer

Any pointer variable of any pointer type can be set to a special value called NULL. This indicates that this pointer doesn’t point to anything.

Since it doesn’t point to a value, dereferencing it is undefined behavior, and probably will result in a crash:

    int *p = NULL;
    
    *p = 12;  // CRASH or SOMETHING PROBABLY BAD. BEST AVOIDED.

(Of course, the pointer points to garbage unless you explicitly assign it to point to an address or NULL.)

5.6 A Note on Declaring Pointers

The syntax for declaring a pointer can get a little weird. Let’s look at this example:

    int a, b;  // Same thing

The rule is that the * goes in front of any variable that is a pointer type. That is. the * is not part of the int in this example. it’s a part of variable p.

    int a, *p;  // Same thing

It’s important to note that the following line does not declare two pointers:

    int *p, q;  // p is a pointer to an int; q is just an int.

This can be particularly insidious-looking if the programmer writes this following (valid) line of code which is functionally identical to the one above.

    int* p, q;  // p is a pointer to an int; q is just an int.

So take a look at this and determine which variables are pointers and which are not:

    int *a, b, c, *d, e, *f, g, h, *i;

5.7 sizeof and Pointers

Just a little bit of syntax here that might be confusing and you might see from time to time.

    int *p;
    
    sizeof(int); // Returns size of an `int`
    sizeof p     // p is type int*, so returns size of `int*`
    sizeof *p    // *p is type int, so returns size of `int`

You might see code with that last sizeof in there. Just remember that sizeof is all about the type of the expression, not the variables in the expression themselves.

6 Arrays

Luckily, C has arrays. I mean, I know it’s considered a low-level language⁴¹ but it does at least have the concept of arrays built-in. And since a great many languages drew inspiration from C’s syntax, you’re probably already familiar with using [ and ] for declaring and using arrays in C.

But only barely! As we’ll find out later, arrays are just syntactic sugar in C—they’re actually all pointers and stuff deep down. Freak out! But for now, let’s just use them as arrays. Phew.

6.1 Easy Example

#include <stdio.h>

int main(void)
{
    int i;
    float f[4];  // Declare an array of 4 floats

    f[0] = 3.14159;  // Indexing starts at 0, of course.
    f[1] = 1.41421;
    f[2] = 1.61803;
    f[3] = 2.71828;

    // Print them all out:

    for (i = 0; i < 4; i++) {
        printf("%f\n", f[i]);
    }
}

When you declare an array, you have to give it a size. And the size has to be fixed⁴².

In the above example, we made an array of 4 floats. The value in the square brackets in the declaration lets us know that.

Later on in subsequent lines, we access the values in the array, setting them or getting them, again with square brackets.

6.2 Getting the Length of an Array

You can’t…ish. C doesn’t record this information. You have to manage it separately in another variable.

When I say “can’t”, I actually mean there are some circumstances when you can. There is a trick to get the number of elements in an array in the scope in which an array is declared. But, generally speaking, this won’t work the way you want if you pass the array into a function.

Let’s take a look at this trick. The basic idea is that you take the sizeof the array, and then divide that by the size of each element to get the length. For example, if an int is 4 bytes, and the array is 32 bytes long, there must be room for 32/4 or 8 ints in there.

    int x[12];  // 12 ints
    
    printf("%zu\n", sizeof x);     // 48 total bytes
    printf("%zu\n", sizeof(int));  // 4 bytes per int
    
    printf("%zu\n", sizeof x / sizeof(int));  // 48/4 = 12 ints!

If it’s an array of chars, then sizeof the array is the number of elements, since sizeof(char) is defined to be 1. For anything else, you have to divide by the size of each element.

But this trick only works in the scope in which the array was defined. If you pass the array to a function, it doesn’t work. Even if you make it “big” in the function signature:

    void foo(int x[12])
    {
        printf("%zu\n", sizeof x);     // 8?! What happened to 48?
        printf("%zu\n", sizeof(int));  // 4 bytes per int
    
        printf("%zu\n", sizeof x / sizeof(int));  // 8/4 = 2 ints?? WRONG.
    }

This is because when you “pass” arrays to functions, you’re only passing a pointer to the first element, and that’s what sizeof measures. More on this in the Passing Single Dimensional Arrays to Functions section, below.

6.3 Array Initializers

#include <stdio.h>

int main(void)
{
    int i;
    int a[5] = {22, 37, 3490, 18, 95};  // Initialize with these values

    for (i = 0; i < 5; i++) {
        printf("%d\n", a[i]);
    }
}

Catch: initializer values must be constant terms. Can’t throw variables in there. Sorry, Illinois!

You should never have more items in your initializer than there is room for in the array, or the compiler will get cranky:

But (fun fact!) you can have fewer items in your initializer than there is room for in the array. The remaining elements in the array will be automatically initialized with zero.

    int a[5] = {22, 37, 3490};
    
    // is the same as:
    
    int a[5] = {22, 37, 3490, 0, 0};

It’s a common shortcut to see this in an initializer when you want to set an entire array to zero:

Which means, “Make the first element zero, and then automatically make the rest zero, as well.”

Lastly, you can also have C compute the size of the array from the initializer, just by leaving the size off:

    int a[3] = {22, 37, 3490};
    
    // is the same as:
    
    int a[] = {22, 37, 3490};  // Left the size off!

6.4 Out of Bounds!

C doesn’t stop you from accessing arrays out of bounds. It might not even warn you.

Let’s steal the example from above and keep printing off the end of the array. It only has 5 elements, but let’s try to print 10 and see what happens:

#include <stdio.h>

int main(void)
{
    int i;
    int a[5] = {22, 37, 3490, 18, 95};

    for (i = 0; i < 10; i++) {  // BAD NEWS: printing too many elements!
        printf("%d\n", a[i]);
    }
}

Yikes! What’s that? Well, turns out printing off the end of an array results in what C developers call undefined behavior. We’ll talk more about this beast later, but for now it means, “You’ve done something bad, and anything could happen during your program run.”

And by anything, I mean typically things like finding zeroes, finding garbage numbers, or crashing. But really the C spec says in this circumstance the compiler is allowed to emit code that does anything⁴³.

6.5 Multidimensional Arrays

    int a[10];
    int b[2][7];
    int c[4][5][6];

#include <stdio.h>

int main(void)
{
    int row, col;

    int a[2][5] = {      // Initialize a 2D array
        {0, 1, 2, 3, 4},
        {5, 6, 7, 8, 9}
    };

    for (row = 0; row < 2; row++) {
        for (col = 0; col < 5; col++) {
            printf("(%d,%d) = %d\n", row, col, a[row][col]);
        }
    }
}

6.6 Arrays and Pointers

[Casually] So… I kinda might have mentioned up there that arrays were pointers, deep down? We should take a shallow dive into that now so that things aren’t completely confusing. Later on, we’ll look at what the real relationship between arrays and pointers is, but for now I just want to look at passing arrays to functions.

6.6.1 Getting a Pointer to an Array

I want to tell you a secret. Generally speaking, when a C programmer talks about a pointer to an array, they’re talking about a pointer to the first element of the array⁴⁶.

#include <stdio.h>

int main(void)
{
    int a[5] = {11, 22, 33, 44, 55};
    int *p;

    p = &a[0];  // p points to the array
                // Well, to the first element, actually

    printf("%d\n", *p);  // Prints "11"
}

Just referring to the array name in isolation is the same as getting a pointer to the first element of the array! We’re going to use this extensively in the upcoming examples.

But hold on a second–isn’t p an int*? And *p gives us 11, same as a[0]? Yessss. You’re starting to get a glimpe of how arrays and pointers are related in C.

6.6.2 Passing Single Dimensional Arrays to Functions

Let’s do an example with a single dimensional array. I’m going to write a couple functions that we can pass the array to that do different things.

#include <stdio.h>

// Passing as a pointer to the first element
void times2(int *a, int len)
{
    for (int i = 0; i < len; i++)
        printf("%d\n", a[i] * 2);
}

// Same thing, but using array notation
void times3(int a[], int len)
{
    for (int i = 0; i < len; i++)
        printf("%d\n", a[i] * 3);
}

// Same thing, but using array notation with size
void times4(int a[5], int len)
{
    for (int i = 0; i < len; i++)
        printf("%d\n", a[i] * 4);
}

int main(void)
{
    int x[5] = {11, 22, 33, 44, 55};

    times2(x, 5);
    times3(x, 5);
    times4(x, 5);
}

All those methods of listing the array as a parameter in the function are identical.

    void times2(int *a, int len)
    void times3(int a[], int len)
    void times4(int a[5], int len)

And, in fact, in the latter situation, the compiler doesn’t even care what number you pass in (other than it has to be greater than zero⁴⁷). It doesn’t enforce anything at all.

Now that I’ve said that, the size of the array in the function declaration actually does matter when you’re passing multidimensional arrays into functions, but let’s come back to that.

6.6.3 Changing Arrays in Functions

We’ve said that arrays are just pointers in disguise. This means that if you pass an array to a function, you’re likely passing a pointer to the first element in the array.

But if the function has a pointer to the data, it is able to manipulate that data! So changes that a function makes to an array will be visible back out in the caller.

Here’s an example where we pass a pointer to an array into a function, the function manipulates the values in that array, and those changes are visible out in the caller.

#include <stdio.h>

void double_array(int *a, int len)
{
    // Multiple each element by 2
    //
    // This doubles the values in x in main() since x and a both point
    // to the same array in memory!

    for (int i = 0; i < len; i++)
        a[i] *= 2;
}

int main(void)
{
    int x[5] = {1, 2, 3, 4, 5};

    double_array(x, 5);

    for (int i = 0; i < 5; i++)
        printf("%d\n", x[i]);  // 2, 4, 6, 8, 10!
}

Later when we talk about the equivalence between arrays and pointers, we’ll see how this makes a lot more sense. For now, it’s enough to know that functions can make changes to arrays that are visible out in the caller.

6.6.4 Passing Multidimensional Arrays to Functions

The story changes a little when we’re talking about multidimensional arrays. C needs to know all the dimensions (except the first one) so it has enough information to know where in memory to look to find a value.

#include <stdio.h>

void print_2D_array(int a[2][3])
{
    for (int row = 0; row < 2; row++) {
        for (int col = 0; col < 3; col++)
            printf("%d ", a[row][col]);
        printf("\n");
    }
}

int main(void)
{
    int x[2][3] = {
        {1, 2, 3},
        {4, 5, 6}
    };

    print_2D_array(x);
}

    void print_2D_array(int a[2][3])
    void print_2D_array(int a[][3])

The compiler really only needs the second dimension so it can figure out how far in memory to skip for each increment of the first dimension.

Also, the compiler does minimal compile-time bounds checking (if you’re lucky), and C does zero runtime checking of bounds. No seat belts! Don’t crash!

7 Strings

Well, turns out strings aren’t actually strings in C. That’s right! They’re pointers! Of course they are!

7.1 Constant Strings

Before we start, let’s talk about constant strings in C. These are sequences of characters in double quotes ("). (Single quotes enclose characters, and are a different animal entirely.)

    "Hello, world!\n"
    "This is a test."
    "When asked if this string had quotes in it, she replied, \"It does.\""

The last one has quotes embedded within it, but you see each is preceded by (we say “escaped by”) a backslash (\) indicating that a literal quote belongs in the string at this point. This is how the C compiler can tell the difference between printing a double quote and the double quote at the end of the string.

7.2 String Variables

Now that we know how to make a constant string, let’s assign it to a variable so we can do something with it.

    char *s = "Hello, world!";

Check out that type: pointer to a char⁴⁹. The string variable s is actually a pointer to the first character in that string, namely the H.

    char *s = "Hello, world!";
    
    printf("%s\n", s);  // "Hello, world!"

7.3 String Variables as Arrays

    char s[14] = "Hello, world!";
    
    // or, if we were properly lazy:
    
    char s[] = "Hello, world!";

This means you can use array notation to access characters in a string. Let’s do exactly that to print all the characters in a string on the same line:

#include <stdio.h>

int main(void)
{
    char s[] = "Hello, world!";

    for (int i = 0; i < 13; i++)
        printf("%c\n", s[i]);
}

Also, check this out. The program will still work fine if we change the definition of s to be a char* type:

#include <stdio.h>

int main(void)
{
    char *s = "Hello, world!";   // char* here

    for (int i = 0; i < 13; i++)
        printf("%c\n", s[i]);    // But still use arrays here...?
}

And we still can use array notation to get the job done when printing it out! This is surprising, but is still only because we haven’t talked about array/pointer equivalence yet. But this is yet another hint that arrays and pointers are the same thing, deep down.

7.4 String Initializers

We’ve already seen some examples with initializing string variables with constant strings:

    char *s = "Hello, world!";
    char t[] = "Hello, again!";

This one is a pointer to a constant string (i.e. a pointer to the first character in a constant string):

    char *s = "Hello, world!";

The behavior is undefined. Probably, depending on your system, a crash will result.

But declaring it as an array is different. This one is a non-constant, mutable copy of the constant string that we can change at will

    char t[] = "Hello, again!";  // t is an array copy of the string 
    t[0] = 'z'; //  No problem
    
    printf("%s\n", t);  // "zello, again!"

So remember: if you have a pointer to a constant string, don’t try to change it!

7.5 Getting String Length

You can’t, since C doesn’t track it for you. And when I say “can’t”, I actually mean “can”⁵⁰. There’s a function in <string.h> called strlen() that can be used to compute the length of any string.

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

int main(void)
{
    char *s = "Hello, world!";

    printf("The string is %zu characters long.\n", strlen(s));
}

The strlen() function returns type size_t, which is an integer type so you can use it for integer math. We print size_t with %zu.

But… if C doesn’t track the length of the string anywhere, how does it know how long the string is?

7.6 String Termination

C does strings a little differently than many programming languages, and in fact differently than almost every modern programming language.

When you’re making a new language, you have basically two options for storing a string in memory:

If you want strings longer than 255 characters, option 1 requires at least two bytes to store the length. Whereas option 2 only requires one byte to terminate the string. So a bit of savings there.

Of course, these days is seems ridiculous to worry about saving a byte (or 3—lots of languages will happily let you have strings that are 4 gigabytes in length). But back in the day, it was a bigger deal.

So C took approach #2. In C, a “string” is defined by two basic characteristics:

A NUL character can be written in C code as \0, though you don’t often have to do this.

When you include a constant string in your code, the NUL character is automatically, implicitly included.

    char *s = "Hello!";  // Actually "Hello!\0" behind the scenes

So with this in mind, let’s write our own strlen() function that counts characters in a string until it finds a NUL.

The procedure is to look down the string for a single NUL character, counting as we go⁵²:

    int my_strlen(char *s)
    {
        int count = 0;
    
        while (s[count] != '\0')  // Single quotes for single char
            count++;
    
        return count;
    }

7.7 Copying a String

You can’t copy a string through the assignment operator (=). All that does is make a copy of the pointer to the first character… so you end up with two pointers to the same string:

#include <stdio.h>

int main(void)
{
    char s[] = "Hello, world!";
    char *t;

    // This makes a copy of the pointer, not a copy of the string!
    t = s;

    // We modify t
    t[0] = 'z';

    // But printing s shows the modification!
    // Because t and s point to the same string!

    printf("%s\n", s);  // "zello, world!"
}

If you want to make a copy of a string, you have to copy it a byte at a time—but this is made easier with the strcpy() function⁵³.

Before you copy the string, make sure you have room to copy it into, i.e. the destination array that’s going to hold the characters needs to be at least as long as the string you’re copying.

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

int main(void)
{
    char s[] = "Hello, world!";
    char t[100];  // Each char is one byte, so plenty of room

    // This makes a copy of the string!
    strcpy(t, s);

    // We modify t
    t[0] = 'z';

    // And s remains unaffected because it's a different string
    printf("%s\n", s);  // "Hello, world!"

    // But t has been changed
    printf("%s\n", t);  // "zello, world!"
}

Notice with strcpy(), the destination pointer is the first argument, and the source pointer is the second. A mnemonic I use to remember this is that it’s the order you would have put t and s if an assignment = worked for strings.

8 Structs

In C, have something called a struct, which is a user-definable type that holds multiple pieces of data, potentially of different types.

It’s a convenient way to bundle multiple variables into a single one. This can be beneficial for passing variables to functions (so you just have to pass one instead of many), and useful for organizing data and making code more readable.

If you’ve come from another language, you might be familiar with the idea of classes and objects. These don’t exist in C, natively⁵⁴. You can think of a struct as a class with only data members, and no methods.

8.1 Declaring a Struct

    struct car {
        char *name;
        float price;
        int speed;
    };

This is often done at the global scope outside any functions so that the struct is globally available.

When you do this, you’re making a new type. The full type name is struct car. (Not just car—that won’t work.)

    struct car saturn;

We should initialize it! But how do we set the values of those individual fields?

Like in many other languages that stole it from C, we’re going to use the dot operator (.) to access the individual fields.

    saturn.name = "Saturn SL/2";
    saturn.price = 15999.99;
    saturn.speed = 175;
    
    printf("Name:           %s\n", saturn.name);
    printf("Price (USD):    %f\n", saturn.price);
    printf("Top Speed (km): %d\n", saturn.speed);

8.2 Struct Initializers

That example in the previous section was a little unwieldy. There must be a better way to initialize that struct variable!

You can do it with an initializer by putting values in for the fields in the order they appear in the struct when you define the variable. (This won’t work after the variable has been defined—it has to happen in the definition).

    struct car {
        char *name;
        float price;
        int speed;
    };
    
    // Now with an initializer! Same field order as in the struct declaration:
    struct car saturn = {"Saturn SL/2", 16000.99, 175};
    
    printf("Name:      %s\n", saturn.name);
    printf("Price:     %f\n", saturn.price);
    printf("Top Speed: %d km\n", saturn.speed);

The fact that the fields in the initializer need to be in the same order is a little freaky. If someone changes the order in struct car, it could break all the other code!

    struct car saturn = {.speed=172, .name="Saturn SL/2"};

Now it’s independent of the order in the struct declaration. Which is safer code, for sure.

Similar to array initializers, any missing field designators are initialized to zero (in this case, that would be .price, which I’ve omitted).

8.3 Passing Structs to Functions

Recall that when you pass something to a function, a copy of that thing gets made for the function to operate on, whether it’s a copy of a pointer, an int, a struct, or anything.

There are basically two cases when you’d want to pass a pointer to the struct:

For those two reasons, it’s far more common to pass a pointer to a struct to a function.

Let’s try that, making a function that will allow you to set the .price field of the struct car:

struct car {
    char *name;
    float price;
    int speed;
};

int main(void)
{
    struct car saturn = {.speed=175, .name="Saturn SL/2"};

    // Pass a pointer to this struct car, along with a new,
    // more realistic, price:
    set_price(&saturn, 800.00);

    // ... code continues ...

You should be able to come up with the function signature for set_price() just by looking at the types of the arguments we have there.

saturn is a struct car, so &saturn must be the address of the struct car, AKA a pointer to a struct car, namely a struct car*.

    void set_price(struct car *c, float new_price)

    void set_price(struct car *c, float new_price) {
        c.price = new_price;  // ERROR!!
    }

That won’t work because the dot operator only works on structs… it doesn’t work on pointers to structs.

Ok, so we can dereference the struct to de-pointer it to get to the struct itself. Dereferencing a struct car* results in the struct car that the pointer points to, which we should be able to use the dot operator on:

    void set_price(struct car *c, float new_price) {
        (*c).price = new_price;  // Works, but non-idiomatic :(
    }

And that works! But it’s a little clunky to type all those parens and the asterisk. C has some syntactic sugar called the arrow operator that helps with that.

8.4 The Arrow Operator

    void set_price(struct car *c, float new_price) {
        // (*c).price = new_price;  // Works, but non-idiomatic :(
        //
        // The line above is 100% equivalent to the one below:
    
        c->price = new_price;  // That's the one!
    }

8.5 Copying and Returning structs

    struct a, b;
    
    b = a;  // Copy the struct

And returning a struct (as opposed to a pointer to one) from a function also makes a similar copy to the receiving variable.

This is not a “deep copy”. All fields are copied as-is, including pointers to things.

9 File Input/Output

We’ve already seen a couple examples of I/O with scanf() and printf() for doing I/O at the console (screen/keyboard).

9.1 The FILE* Data Type

When we do any kind of I/O in C, we do so though a piece of data that you get in the form of a FILE* type. This FILE* holds all the information needed to communicate with the I/O subsystem about which file you have open, where you are in the file, and so on.

The spec refers to these as streams, i.e. a stream of data from a file or from any source. I’m going to use “files” and “streams” interchangeably, but really you should think of a “file” as a special case of a “stream”. There are other ways to stream data into a program than just reading from a file.

We’ll see in a moment how to go from having a filename to getting an open FILE* for it, but first I want to mention three streams that are already open for you and ready for use.

We’ve actually been using these implicitly already, it turns out. For example, these two calls are the same:

`FILE*` name	Description
`stdin`	Standard Input, generally the keyboard by default
`stdout`	Standard Output, generally the screen by default
`stderr`	Standard Error, generally the screen by default, as well

    printf("Hello, world!\n");
    fprintf(stdout, "Hello, world!\n");  // printf to a file

Also you’ll notice that both stdout and stderr go to the screen. While this seems at first either like an oversight or redundancy, it actually isn’t. Typical operating systems allow you to redirect the output of either of those into different files, and it can be convenient to be able to separate error messages from regular non-error output.

For example, in a POSIX shell (like sh, ksh, bash, zsh, etc.) on a Unix-like system, we could run a program and send just the non-error (stdout) output to one file, and all the error (stderr) output to another file.

For this reason, you should send serious error messages to stderr instead of stdout.

9.2 Reading Text Files

Text streams are allowed to do significant translation of the data, most notably translations of newlines to their different representations⁵⁷. Text files are logically a sequence of lines separated by newlines. To be portable, your input data should always end with a newline.

But the general rule is that if you’re able to edit the file in a regular text editor, it’s a text file. Otherwise, it’s binary. More on binary later.

So let’s get to work—how do we open a file for reading, and pull data out of it?

And let’s write a program to open the file, read a character out of it, and then close the file when we’re done. That’s the game plan!

#include <stdio.h>

int main(void)
{
    FILE *fp;                      // Variable to represent open file

    fp = fopen("hello.txt", "r");  // Open file for reading

    char c = fgetc(fp);            // Read a single character
    printf("%c\n", c);             // Print char to stdout

    fclose(fp);                    // Close the file when done
}

See how when we opened the file with fopen(), it returned the FILE* to us so we could use it later.

(I’m leaving it out for brevity, but fopen() will return NULL if something goes wrong, so you should really error check it!)

Also notice the "r" that we passed in—this means “open a text stream for reading”. (There are various strings we can pass to fopen() with additional meaning, like writing, or appending, and so on.)

Finally, we close the stream when we’re done with it. All streams are automatically closed when the program exits, but it’s good form and good housekeeping to explicitly close any files yourself when done with them.

The FILE* keeps track of our position in the file. So subsequent calls to fgetc() would get the next character in the file, and then the next, until the end.

9.3 End of File: EOF

There is a special character defined as a macro: EOF. This is what fgetc() will return when the end of the file has been reached and you’ve attempted to read another character.

#include <stdio.h>

int main(void)
{
    FILE *fp;

    fp = fopen("hello.txt", "r");
    char c;

    while ((c = fgetc(fp)) != EOF)
        printf("%c", c);

    fclose(fp);
}

(If line 10 is too weird, just break it down starting with the innermost-nested parens. The first thing we do is assign the result of fgets() into c, and then we compare that against EOF. We’ve just crammed it into a single line. This might look hard to read, but study it—it’s idiomatic C.)

But still, we’re operating a character at a time, and lots of text files make more sense at the line level. Let’s switch to that.

9.3.1 Reading a Line at a Time

So how can we get an entire line at once? fgets() to the rescue! For arguments, it takes a pointer to a char buffer to hold bytes, a maximum number of bytes to read, and a FILE* to read from. It returns NULL on end-of-file or error. fgets() is even nice enough to NUL-terminate the string when its done⁵⁸.

Let’s do a similar loop as before, except let’s have a multiline file and read it in a line at a time.

And here’s some code that reads that file a line at a time and prints out a line number before each one:

#include <stdio.h>

int main(void)
{
    FILE *fp;
    char s[1024];  // Big enough for any line this program will encounter
    int linecount = 0;

    fp = fopen("quote.txt", "r");

    while (fgets(s, sizeof s, fp) != NULL) 
        printf("%d: %s", ++linecount, s);

    fclose(fp);
}

9.4 Formatted Input

You know how you can get formatted output with printf() (and, thus, fprintf() like we’ll see, below)?

Let’s have a file with a series of data records in it. In this case, whales, with name, length in meters, and weight in tonnes. whales.txt:

Yes, we could read these with fgets() and then parse the string with sscanf() (and in some ways that’s more resilient against corrupted files), but in this case, let’s just use fscanf() and pull it in directly.

The sscanf() function skips whitespace when reading, and returns EOF on end-of-file or error.

#include <stdio.h>

int main(void)
{
    FILE *fp;
    char name[1024];  // Big enough for any line this program will encounter
    float length;
    int mass;

    fp = fopen("whales.txt", "r");

    while (fscanf(fp, "%s %f %d", name, &length, &mass) != EOF)
        printf("%s whale, %d tonnes, %.1f meters\n", name, mass, length);

    fclose(fp);
}

9.5 Writing Text Files

In much the same way we can use fgetc(), fgets(), and fscanf() to read text streams, we can use fputc(), fputs(), and fprintf() to write text streams.

To do so, we have to fopen() the file in write mode by passing "w" as the second argument. Opening an existing file in "w" mode will instantly truncate that file to 0 bytes for a full overwrite.

We’ll put together a simple program that outputs a file output.txt using a variety of output functions.

#include <stdio.h>

int main(void)
{
    FILE *fp;
    int x = 32;

    fp = fopen("output.txt", "w");

    fputc('B', fp);
    fputc('\n', fp);
    fprintf(fp, "x = %d\n", x);
    fputs("Hello, world!\n", fp);

    fclose(fp);
}

and the program would have outputted to the console instead of to a file. Try it!

9.6 Binary File I/O

So far we’ve just been talking text files. But there’s that other beast we mentioned early on called binary files, or binary streams.

These work very similarly to text files, except the I/O subsystem doesn’t perform any translations on the data like it might with a text file. With binary files, you get a raw stream of bytes, and that’s all.

The big difference in opening the file is that you have to add a "b" to the mode. That is, to read a binary file, open it in "rb" mode. To write a file, open it in "wb" mode.

Because it’s streams of bytes, and streams of bytes can contain NUL characters, and the NUL character is the end-of-string marker in C, it’s rare that people use the fprintf()-and-friends functions to operate on binary files.

Instead the most common functions are fread() and fwrite(). The functions read and write a specified number of bytes to the stream.

To demo, we’ll write a couple programs. One will write a sequence of byte values to disk all at once. And the second program will read a byte at a time and print them out⁵⁹.

#include <stdio.h>

int main(void)
{
    FILE *fp;
    unsigned char bytes[] = {5, 37, 0, 88, 255, 12};

    fp = fopen("output.bin", "wb");  // wb mode for "write binary"!

    // In the call to fwrite, the arguments are:
    //
    // * Pointer to data to write
    // * Size of each "piece" of data
    // * Count of each "piece" of data
    // * FILE*

    fwrite(bytes, sizeof(char), sizeof bytes, fp);

    fclose(fp);
}

Those two middle arguments to fwrite() are pretty odd. But basically what we want to tell the function is, “We have items that are this big, and we want to write that many of them.” This makes it convenient if you have a record of a fixed length, and you have a bunch of them in an array. You can just tell it the size of one record and how many to write.

In the example above, we tell it each record is the size of a char, and we have 6 of them as computed by sizeof bytes.

Running the program gives us a file output.bin, but opening it in a text editor doesn’t show anything friendly! It’s binary data—not text. And random binary data I just made up, at that!

And those values in hex do match up to the values (in decimal) that we wrote out.

But now let’s try to read them back in with a different program. This one will open the file for binary reading ("rb" mode) and will read the bytes one at a time in a loop.

fread() has the neat feature where it returns the number of bytes read, or 0 on EOF. So we can loop until we see that, printing numbers as we go.

#include <stdio.h>

int main(void)
{
    FILE *fp;
    unsigned char c;

    fp = fopen("output.bin", "rb"); // rb for "read binary"!

    while (fread(&c, sizeof(char), 1, fp) > 0)
        printf("%d\n", c);
}

9.6.1 struct and Number Caveats

As we saw in the structs section, the compiler is free to add padding to a struct as it sees fit. And different compilers might do this differently. And the same compiler on different architectures could do it differently. And the same compiler on the same architectures could do it differently.

What I’m getting at is, it’s not portable to just fwrite() an entire struct out to a file when you don’t know where the padding will end up.

How do we fix this? Hold that thought—we’ll look at some ways to do this after looking at another related problem.

Let’s look at a simple fwrite() of a 2-byte number. We’ll write it in hex so each byte is clear. The most significant byte will have the value 0x12 and the least significant will have the value 0x34.

    unsigned short v = 0x1234;  // Two bytes, 0x12 and 0x34
    
    fwrite(&v, sizeof v, 1, fp);

This has something to do with what’s called the endianess⁶¹ of the architecture. Some write the most significant bytes first, and some the least significant bytes first.

This means that if you write a multibyte number out straight from memory, you can’t do it in a portable way⁶².

A similar problem exists with floating point. Most systems use the same format for their floating point numbers, but some do not. No guarantees!

So… how can we fix all these problems with numbers and structs to get our data written in a portable way?

The summary is to serialize the data, which is a general term that means to take all the data and write it out in a format that you control, that is well-known, and programmable to work the same way on all platforms.

As you might imagine, this is a solved problem. There are a bunch of serialization libraries you can take advantage of, such as Google’s protocol buffers⁶³, out there and ready to use. They will take care of all the gritty details for you, and even will allow data from your C programs to interoperate with other languages that support the same serialization methods.

Do yourself and everyone a favor! Serialize your binary data when you write it to a stream!

10 typedef: Making New Types

Well, not so much making new types as getting new names for existing types. Sounds kinda pointless on the surface, but we can really use this to make our code cleaner.

10.1 typedef in Theory

Basically, you take an existing type and you make an alias for it with typedef.

    typedef int antelope;  // Make "antelope" an alias for "int"
    
    antelope x = 10;       // Type "antelope" is the same as type "int"

You can take any existing type and do it. You can even make a number of types with a comma list:

    typedef int antelope, bagel, mushroom;  // These are all "int"

That’s really useful, right? That you can type mushroom instead of int? You must be super excited about this feature!

OK, Professor Sarcasm—we’ll get to some more common applications of this in a moment.

10.1.1 Scoping

For this reason, it’s quite common to find typedef at file scope (“global”) so that all functions can use the new types at will.

10.2 typedef in Practice

So renaming int to something else isn’t that exciting. Let’s see where typedef commonly makes an appearance.

10.2.1 typedef and structs

Sometimes a struct will be typedef’d to a new name so you don’t have to type the word struct over and over.

    struct animal {
        char *name;
        int leg_count, speed;
    };
    
    //  original name      new name
    //            |         |
    //            v         v
    //      |-----------| |----|
    typedef struct animal animal;
    
    struct animal y;  // This works
    animal z;         // This also works because "animal" is an alias

Personally, I don’t care for this practice. I like the clarity the code has when you add the word struct to the type; programmers know what they’re getting. But it’s really common so I’m including it here.

Now I want to run the exact same example in a way that you might commonly see. We’re going to put the struct animal in the typedef. You can mash it all together like this:

    //  original name
    //            |
    //            v
    //      |-----------|
    typedef struct animal {
        char *name;
        int leg_count, speed;
    } animal;                         // <-- new name
    
    struct animal y;  // This works
    animal z;         // This also works because "animal" is an alias

But that’s not all! There’s another common shortcut that you might see in code using what are called anonymous structures⁶⁴. It turns out you don’t actually need to name the structure in a variety of places, and with typedef is one of them.

    //  anonymous struct!
    //         |
    //         v
    //      |----|
    typedef struct {
        char *name;
        int leg_count, speed;
    } animal;                         // <-- new name
    
    //struct animal y;  // ERROR: this no longer works
    animal z;           // This works because "animal" is an alias

    typedef struct {
        int x, y;
    } point;
    
    point p = {.x=20, .y=40};
    
    printf("%d, %d\n", p.x, p.y);  // 20, 40

10.2.2 typedef and Other Types

It’s not that using typedef with a simple type like int is completely useless… it helps you abstract the types to make it easier to change them later.

For example, if you have float all over your code in 100 zillion places, it’s going to be painful to change them all to double if you find you have to do that later for some reason.

    typedef float app_float;
    
    // and
    
    app_float f1, f2, f3;

Then if later you want to change to another type, like long double, you just nee to change the typedef:

    //        voila!
    //      |---------|
    typedef long double app_float;
    
    // and
    
    app_float f1, f2, f3;  // Now these are all long doubles

10.2.3 typedef and Pointers

    typedef int *intptr;
    
    int a = 10;
    intptr x = &a;  // "intptr" is type "int*"

I really don’t like this practice. It hides the fact that x is a pointer type because you don’t see a * in the declaration.

IMHO, it’s better to explicitly show that you’re declaring a pointer type so that other devs can clearly see it and don’t mistake x for having a non-pointer type.

10.2.4 typedef and Capitalization

    typedef struct {
        int x, y;
    } my_point;          // lower snake case
    
    typedef struct {
        int x, y;
    } MyPoint;          // CamelCase
    
    typedef struct {
        int x, y;
    } Mypoint;          // Leading uppercase
    
    typedef struct {
        int x, y;
    } MY_POINT;          // UPPER SNAKE CASE

The C11 specification doesn’t dictate one way or another, and shows examples in all uppercase and all lowercase.

K&R2 uses leading uppercase predominantly, but show some examples in uppercase and snake case (with _t).

If you have a style guide in use, stick with it. If you don’t, grab one and stick with it.

10.3 Arrays and typedef

The syntax is a little weird, and this is rarely seen in my experience, but you can typedef an array of some number of items.

    // Make type five_ints an array of 5 ints
    typedef int five_ints[5];
    
    five_ints x = {11, 22, 33, 44, 55};

I don’t like it because it hides the array nature of the variable, but it’s possible to do.

11 Pointers II: Arithmetic

11.1 Pointer Arithmetic

In short, if you have a pointer to a type, adding one to the pointer moves to the next item of that type directly after it in memory.

It’s important to remember that as we move pointers around and look at different places in memory, we need to make sure that we’re always pointing to a valid place in memory before we dereference. If we’re off in the weeds and we try to see what’s there, the behavior is undefined and a crash is a common result.

11.1.1 Adding to Pointers

    int a[5] = {11, 22, 33, 44, 55};

    int a[5] = {11, 22, 33, 44, 55};
    
    int *p = &a[0];  // Or "int *p = a;" works just as well

    printf("%d\n", *p);  // Prints 11

Now let’s use pointer arithmetic to print the next element in the array, the one at index 1:

    printf("%d\n", *(p + 1));  // Prints 22!!

What happened there? C knows that p is a pointer to an int. So it knows the sizeof an int⁶⁵ and it knows to skip that many bytes to get to the next int after the first one!

    printf("%d\n", *p);        // Prints 11
    printf("%d\n", *(p + 0));  // Prints 11

Let’s think of the upshot here. We can iterate over elements of an array this way instead of using an array:

    int a[5] = {11, 22, 33, 44, 55};
    
    int *p = &a[0];  // Or "int *p = a;" works just as well
    
    for (int i = 0; i < 5; i++) {
        printf("%d\n", *(p + i));  // Same as p[i]!
    }

And that works the same as if we used array notation! Oooo! Getting closer to that array/pointer equivalence thing! More on this later in this chapter.

Remember from early on that memory is like a big array, where a byte is stored at each array index.

For a random example, say that a number 3490 was stored at address (“index”) 23,237,489,202. If we have an int pointer to that 3490, that value of that pointer is 23,237,489,202… because the pointer is the memory address. Different words for the same thing.

And now let’s say we have another number, 4096, stored right after the 3490 at address 23,237,489,210 (8 higher than the 3490 because each int in this example is 8 bytes long).

If we add 1 to that pointer, it actually jumps ahead sizeof(int) bytes to the next int. It knows to jump that far ahead because it’s an int pointer. If it were a float pointer, it’d jump sizeof(float) bytes ahead to get to the next float!

So you can look at the next int, by adding 1 to the pointer, the one after that by adding 2 to the pointer, and so on.

11.1.2 Changing Pointers

We saw how we could add an integer to a pointer in the previous section. This time, let’s modify the pointer, itself.

You can just add (or subtract) integer values directly to (or from) any pointer!

Let’s do that example again, except with a couple changes. First, I’m going to add a 999 to the end of our numbers to act as a sentinel value. This will let us know where the end of the data is.

    int a[] = {11, 22, 33, 44, 55, 999};  // Add 999 here as a sentinel
    
    int *p = &a[0];  // p points to the 11

And we also have p pointing to the element at index 0 of a, namely 11, just like before.

Now—let’s starting incrementing p so that it points at subsequent elements of the array. We’ll do this until p points to the 999; that is, we’ll do it until *p == 999:

    while (*p != 999) {       // While the thing p points to isn't 999
        printf("%d\n", *p);   // Print it
        p++;                  // Move p to point to the next int!
    }

When we give it a run, first p points to 11. Then we increment p, and it points to 22, and then again, it points to 33. And so on, until it points to 999 and we quit.

11.1.3 Subtracting Pointers

You can subtract a value from a pointer to get to earlier address, as well, just like we were adding to them before.

But we can also subtract two pointers to find the difference between them, e.g. we can calculate how many ints there are between two int*s. The catch is that this only works within a single array⁶⁶—if the pointers point to anything else, you get undefined behavior.

Remember how strings are char*s in C? Let’s see if we can use this to write another variant of strlen() to compute the length of a string that utilizes pointer subtraction.

The idea is that if we have a pointer to the beginning of the string, we can find a pointer to the end of the string by scanning ahead for the NUL character.

And if we have a pointer to the beginning of the string, and we computed the pointer to the end of the string, we can just subtract the two pointers to come up with the length!

#include <stdio.h>

int my_strlen(char *s)
{
    // Start scanning from the beginning of the string
    char *p = s;

    // Scan until we find the NUL character
    while (*p != '\0')
        p++;

    // Return the difference in pointers
    return p - s;
}

int main(void)
{
    printf("%d\n", my_strlen("Hello, world!"));  // Prints "13"
}

Remember that you can only use pointer subtraction between two pointers that point to the same array!

11.2 Array/Pointer Equivalence

We’re finally ready to talk about this! We’ve seen plenty of examples of places where we’ve intermixed array notation, but let’s give out the fundamental formula of array/pointer equivalence:

I’ve oversimplified a bit, because in my above example a and b can both be expressions, and we might want a few more parentheses to force order of operations in case the expressions are complex.

but that’s a little harder to grok. Just make sure you include parentheses if the expressions are complicated so all your math happens in the right order.

This means we can decide if we’re going to use array or pointer notation for any array or pointer (assuming it points to an element of an array).

#include <stdio.h>

int main(void)
{
    int a[] = {11, 22, 33, 44, 55};  // Add 999 here as a sentinel

    int *p = a;  // p points to the first element of a, 11

    // Print all elements of the array a variety of ways:

    for (int i = 0; i < 5; i++)
        printf("%d\n", a[i]);      // Array notation with a

    for (int i = 0; i < 5; i++)
        printf("%d\n", p[i]);      // Array notation with p

    for (int i = 0; i < 5; i++)
        printf("%d\n", *(a + i));  // Pointer notation with a

    for (int i = 0; i < 5; i++)
        printf("%d\n", *(p + i));  // Pointer notation with p

    for (int i = 0; i < 5; i++)
        printf("%d\n", *(p++));    // Moving pointer p
        //printf("%d\n", *(a++));    // Moving array variable a--ERROR!
}

So you can see that in general, if you have an array variable, you can use pointer or array notion to access elements. Same with a pointer variable.

The one big difference is that you can modify a pointer to point to a different address, but you can’t do that with an array variable.

11.2.1 Array/Pointer Equivalence in Function Calls

    int my_strlen(char *s)

this means you can pass either an array or a pointer to this function and have it work!

    char s[] = "Antelopes";
    char *t = "Wombats";
    
    printf("%d\n", my_strlen(s));  // Works!
    printf("%d\n", my_strlen(t));  // Works, too!

    int my_strlen(char *s)    // Works!
    int my_strlen(char s[])   // Works, too!

11.3 void Pointers

You’ve already seen the void keyword used with functions, but this is an entirely separate, unrelated animal.

Sometimes it’s useful to have a pointer to a thing that you don’t know the type of.

    void *memcpy(void *s1, void *s2, size_t n);

This function copies n bytes of memory starting from address s1 into the memory starting at address s2.

But look! s1 and s2 are void*s! Why? What does it mean? Let’s run more examples to see.

For instance, we could copy a string with memcpy() (though strcpy() is more appropriate for strings):

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

int main(void)
{
    char s[] = "Goats!";
    char t[100];

    memcpy(t, s, 7);  // Copy 7 bytes--including the NUL terminator!

    printf("%s\n", t);  // "Goats!"
}

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

int main(void)
{
    int a[] = {11, 22, 33};
    int b[3];

    memcpy(b, a, 3 * sizeof(int));  // Copy 3 ints of data

    printf("%d\n", b[1]);  // 22
}

That one’s a little wild—you see what we did there with memcpy()? We copied the data from a to b, but we had to specify how many bytes to copy, and an int is more than one byte.

OK, then—how many bytes does an int take? Answer: depends on the system. But we can tell how many bytes any type takes with the sizeof operator.

And if we have 3 of them in our array, like we did in that example, the entire space used for the 3 ints must be 3 * sizeof(int).

(In the string example, earlier, it would have been more technically accurate to copy 7 * sizeof(char) bytes. But chars are always one byte large, by definition, so that just devolves into 7 * 1.)

We could even copy a float or a struct with memcpy()! (Though this is abusive—we should just use = for that):

    struct antelope my_antelope;
    struct antelopy my_clone_antelope;
    
    // ...
    
    memcpy(&my_clone, &my_antelope, sizeof my_antelope);

Look at how versatile memcpy() is! If you have a pointer to a source and a pointer to a destination, and you have the number of bytes you want to copy, you can copy any type of data.

Imagine if we didn’t have void*. We’d have to write specialized memcpy() functions for each type:

    memcpy_int(int *a, int *b, int count);
    memcpy_float(float *a, float *b, int count);
    memcpy_double(double *a, double *b, int count);
    memcpy_char(char *a, char *b, int count);
    memcpy_unsigned_char(unsigned char *a, unsigned char *b, int count);
    
    // etc... blech!

That’s the power of void*. You can write functions that don’t care about the type and is still able to do things with it.

But with great power comes great responsibility. Maybe not that great in this case, but there are some limits.

And if you think about it, these rules make sense. All those operations rely on knowing the sizeof the type of data pointed to, and with void*, we don’t know the size of the data being pointed to—it could be anything!

Like with memcpy(), it helps you write generic functions that can handle multiple types of data. But the secret is that, deep down, you convert the void* to another type before you use it!

And conversion is easy: you can just assign into a variable of the desired type⁶⁸.

    char a = 'X';  // A single char
    
    void *p = &a;  // p points to the 'X'
    char *q = p;   // q also points to the 'X'
    
    printf("%c\n", *p);  // ERROR--cannot dereference void*!
    printf("%c\n", *q);  // Prints "X"

Let’s write our own memcpy() to try this out. We can copy bytes (chars), and we know the number of bytes because it’s passed in.

    void *my_memcpy(void *dest, void *src, int byte_count)
    {
        // Convert void*s to char*s
        char *s = src, *d = dest;
    
        // Now that we have char*s, we can dereference and copy them
        while (byte_count--) {
            *d++ = *s++;
        }
    
        // Most of these functions return the destination, just in case
        // that's useful to the caller.
        return dest;
    }

Right there at the beginning, we copy the void*s into char*s so that we can use them as char*s. It’s as easy as that.

Then some fun in a while loop, where we decrement byte_count until it becomes false (0). Remember that with post-decrement, the value of the expression is computed (for while to use) and then the variable is decremented.

And some fun in the copy, where we assign *d = *s to copy the byte, but we do it with post-increment so that both d and s move to the next byte after the assignment is made.

Lastly, most memory and string functions return a copy of a pointer to the destination string just in case the caller wants to use it.

Now that we’ve done that, I just want to quickly point out that we can use this technique to iterate over the bytes of any object in C, floats, structs, or anything!

Let’s run one more real-world example with the built-in qsort() routine that can sort anything thanks to the magic of void*s.

(In the following example, you can ignore the word const, which we haven’t covered yet.)

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

// The type of structure we're going to sort
struct animal {
    char *name;
    int leg_count;
};

// This is a comparison function called by qsort() to help it determine
// what exactly to sort by. We'll use it to sort an array of struct
// animals by leg_count.
int compar(const void *elem1, const void *elem2)
{
    // We know we're sorting struct animals, so let's make both
    // arguments pointers to struct animals
    const struct animal *animal1 = elem1;
    const struct animal *animal2 = elem2;

    // Return <0 =0 or >0 depending on whatever we want to sort by.

    // Let's sort ascending by leg_count, so we'll return the difference
    // in the leg_counts
    return animal1->leg_count - animal2->leg_count;
}

int main(void)
{
    // Let's build an array of 4 struct animals with different
    // characteristics. This array is out of order by leg_count, but
    // we'll sort it in a second.
    struct animal a[4] = {
        {.name="Dog", .leg_count=4},
        {.name="Monkey", .leg_count=2},
        {.name="Antelope", .leg_count=4},
        {.name="Snake", .leg_count=0}
    };

    // Call qsort() to sort the array. qsort() needs to be told exactly
    // what to sort this data by, and we'll do that inside the compar()
    // function.
    //
    // This call is saying: qsort array a, which has 4 elements, and
    // each element is sizeof(struct animal) bytes big, and this is the
    // function that will compare any two elements.
    qsort(a, 4, sizeof(struct animal), compar);

    // Print them all out
    for (int i = 0; i < 4; i++) {
        printf("%d: %s\n", a[i].leg_count, a[i].name);
    }
}

As long as you give qsort() a function that can compare two items that you have in your array to be sorted, it can sort anything. And it does this without needing to have the types of the items hardcoded in there anywhere. qsort() just rearranges blocks of bytes based on the results of the compar() function you passed in.

12 Manual Memory Allocation

This is one of the big areas where C likely diverges from languages you already know: manual memory management.

Other languages uses reference counting, garbage collection, or other means to determine when to allocate new memory for some data—and when to deallocate it when no variables refer to it.

And that’s nice. It’s nice to be able to not worry about it, to just drop all the references to an item and trust that at some point the memory associated with it will be freed.

Of course, in C, some variables are automatically allocated and deallocated when they come into scope and leave scope. We call these automatic variables. They’re your average run-of-the-mill block scope “local” variables. No problem.

But what if you want something to persist longer than a particular block? This is where manual memory management comes into play.

You can tell C explicitly to allocate for you a certain number of bytes that you can use as you please. And these bytes will remain allocated until you explicitly free that memory⁶⁹.

It’s important to free the memory you’re done with! If you don’t, we call that a memory leak and your process will continue to reserve that memory until it exits.

If you manually allocated it, you have to manually free it when you’re done with it.

So how do we do this? We’re going to learn a couple new functions, and make use of the sizeof operator to help us learn how many bytes to allocate.

In common C parlance, devs say that automatic local variables are allocated “on the stack”, and manually-allocated memory is “on the heap”. The spec doesn’t talk about either of those things, but all C devs will know what you’re talking about if you bring them up.

All functions we’re going to learn in this chapter can be found in <stdlib.h>.

12.1 Allocating and Deallocating, malloc() and free()

The malloc() function accepts a number of bytes to allocate, and returns a void pointer to that block of newly-allocated memory.

Since it’s a void*, you can assign it into whatever pointer type you want… normally this will correspond in some way to the number of bytes you’re allocating.

So… how many bytes should I allocate? We can use sizeof to help with that. If we want to allocate enough room for a single int, we can use sizeof(int) and pass that to malloc().

After we’re done with some allocated memory, we can call free() to indicate we’re done with that memory and it can be used for something else. As an argument, you pass the same pointer you got from malloc() (or a copy of it). It’s undefined behavior to use a memory region after you free() it.

Let’s try. We’ll allocate enough memory for an int, and then store something there, and the print it.

    // Allocate space for a single int (sizeof(int) bytes-worth):
    
    int *p = malloc(sizeof(int));
    
    *p = 12;  // Store something there
    
    printf("%d\n", *p);  // Print it: 12
    
    free(p);  // All done with that memory
    
    //*p = 3490;  // ERROR: undefined behavior! Use after free()!

Now, in that contrived example, there’s really no benefit to it. We could have just used an automatic int and it would have worked. But we’ll see how the ability to allocate memory this way has its advantages, especially with more complex data structures.

One more thing you’ll commonly see takes advantage of the fact that sizeof can give you the size of the result type of any constant expression. So you could put a variable name in there, too, and use that. Here’s an example of that, just like the previous one:

    int *p = malloc(sizeof *p);  // *p is an int, so same as sizeof(int)

12.2 Error Checking

All the allocation functions return a pointer to the newly-allocated stretch of memory, or NULL if the memory cannot be allocated for some reason.

Some OSes like Linux can be configured in such a way that malloc() never returns NULL, even if you’re out of memory. But despite this, you should always code it up with protections in mind.

    int *x;
    
    x = malloc(sizeof(int) * 10);
    
    if (x == NULL) {
        printf("Error allocating 10 ints\n");
        // do something here to handle it
    }

Here’s a common pattern that you’ll see, where we do the assignment and the condition on the same line:

    int *x;
    
    if ((x = malloc(sizeof(int) * 10)) == NULL)
        printf("Error allocating 10 ints\n");
        // do something here to handle it
    }

12.3 Allocating Space for an Array

We’ve seen how to allocate space for a single thing; now what about for a bunch of them in an array?

In C, an array is a bunch of the same thing back-to-back in a contiguous stretch of memory.

We can allocate a contiguous stretch of memory—we’ve seen how to do that. If we wanted 3490 bytes of memory, we could just ask for it:

    char *p = malloc(3490);  // Voila

And—indeed!—that’s an array of 3490 chars (AKA a string!) since each char is 1 byte. In other words, sizeof(char) is 1.

Note: there’s no initialization done on the newly-allocated memory—it’s full of garbage. Clear it with memset() if you want to, or see calloc(), below.

But we can just multiply the size of the thing we want by the number of elements we want, and then access them using either pointer or array notation. Example!

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

int main(void)
{
    // Allocate space for 10 ints
    int *p = malloc(sizeof(int) * 10);

    // Assign them values 0-45:
    for (int i = 0; i < 10; i++)
        p[i] = i * 5;

    // Print all values 0, 5, 10, 15, ..., 40, 45
    for (int i = 0; i < 10; i++)
        printf("%d\n", p[i]);

    // Free the space
    free(p);
}

The key’s in that malloc() line. If we know each int takes sizeof(int) bytes to hold it, and we know we want 10 of them, we can just allocate exactly that many bytes with:

And this trick works for every type. Just pass it to sizeof and multiply by the size of the array.

12.4 An Alternative: calloc()

This is another allocation function that works similarly to malloc(), with two key differences:

    // Allocate space for 10 ints with calloc(), initialized to 0:
    int *p = calloc(sizeof(int), 10);
    
    // Allocate space for 10 ints with malloc(), initialized to 0:
    int *q = malloc(sizeof(int) * 10);
    memset(q, 0, sizeof(int) * 10);   // set to 0

Again, the result is the same for both except malloc() doesn’t zero the memory by default.

12.5 Changing Allocated Size with realloc()

If you’ve already allocated 10 ints, but later you decide you need 20, what can you do?

One option is to allocate some new space, and then memcpy() the memory over… but it turns out that sometimes you don’t need to move anything. And there’s one function that’s just smart enough to do the right thing in all the right circumstances: realloc().

It takes a pointer to some previously-allocted memory (by malloc() or calloc()) and a new size for the memory region to be.

It then grows or shrinks that memory, and returns a pointer to it. Sometimes it might return the same pointer (if the data didn’t have to be copied elsewhere), or it might return a different one (if the data did have to be copied).

Be sure when you call realloc(), you specify the number of bytes to allocate, and not just the number of array elements! That is:

    num_floats *= 2;
    
    np = realloc(p, num_floats);  // WRONG: need bytes, not number of elements!
    
    np = realloc(p, num_floats * sizeof(float));  // Better!

Let’s allocate an array of 20 floats, and then change our mind and make it an array of 40.

We’re going to assign the return value of realloc() into another pointer just to make sure it’s not NULL. If it’s not, then we can reassign it into our original pointer. (If we just assigned the return value directly into the original pointer, we’d lose that pointer if the function returned NULL and we’d have no way to get it back.)

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

int main(void)
{
    // Allocate space for 20 floats
    float *p = malloc(sizeof *p * 20);  // sizeof *p same as sizeof(float)

    // Assign them fractional values 0.0-1.0:
    for (int i = 0; i < 20; i++)
        p[i] = i / 20.0;

    // But wait! Let's actually make this an array of 40 elements
    float *new_p = realloc(p, sizeof *p * 40);

    // Check to see if we successfully reallocated
    if (new_p == NULL) {
        printf("Error reallocing\n");
        return 1;
    }

    // If we did, we can just reassign p
    p = new_p;

    // And assign the new elements values in the range 1.0-2.0
    for (int i = 20; i < 40; i++)
        p[i] = 1.0 + (i - 20) / 20.0;

    // Print all values 0.0-2.0 in the 40 elements:
    for (int i = 0; i < 40; i++)
        printf("%f\n", p[i]);

    // Free the space
    free(p);
}

Notice in there how we took the return value from realloc() and reassigned it into the same pointer variable p that we passed in. That’s pretty common to do.

Also if line 7 is looking weird, with that sizeof *p in there, remember that sizeof works on the size of the type of the expression. And the type of *p is float, so that line is equivalent to sizeof(float).

12.5.1 Reading in Lines of Arbitrary Length

What we see here is a loop that calls fgetc() over and over to append to a buffer until we see that the last character is a newline.

Once it finds the newline, it shrinks the buffer to just the right size and returns it.

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

// Read a line of arbitrary size from a file
//
// Returns a pointer to the line.
// Returns NULL on EOF or error.
//
// It's up to the caller to free() this pointer when done with it.
//
// Note that this strips the newline from the result. If you need
// it in there, probably best to switch this to a do-while.

char *readline(FILE *fp)
{
    int offset = 0;   // Index next char goes in the buffer
    int bufsize = 4;  // Preferably power of 2 initial size
    char *buf;        // The buffer
    int c;            // The character we've read in

    buf = malloc(bufsize);  // Allocate initial buffer

    if (buf == NULL)   // Error check
        return NULL;

    // Main loop--read until newline or EOF
    while (c = fgetc(fp), c != '\n' && c != EOF) {

        // Check if we're out of room in the buffer accounting
        // for the extra byte for the NUL terminator
        if (offset == bufsize - 1) {  // -1 for the NUL terminator
            bufsize *= 2;  // 2x the space

            char *new_buf = realloc(buf, bufsize);

            if (new_buf == NULL) {
                free(buf);   // On error, free and bail
                return NULL;
            }

            buf = new_buf;  // Successful realloc
        }

        buf[offset++] = c;  // Add the byte onto the buffer
    }

    // We hit newline or EOF...

    // If at EOF and we read no bytes, free the buffer and
    // return NULL to indicate we're at EOF:
    if (c == EOF && offset == 0) {
        free(buf);
        return NULL;
    }

    // Shrink to fit
    if (offset < bufsize - 1) {  // If we're short of the end
        char *new_buf = realloc(buf, offset + 1); // +1 for NUL terminator

        // If successful, point buf to new_buf;
        // otherwise we'll just leave buf where it is
        if (new_buf != NULL)
            buf = new_buf;
    }

    // Add the NUL terminator
    buf[offset] = '\0';

    return buf;
}

int main(void)
{
    FILE *fp = fopen("foo.txt", "r");

    char *line;

    while ((line = readline(fp)) != NULL) {
        printf("%s\n", line);
        free(line);
    }

    fclose(fp);
}

When growing memory like this, it’s common (though hardly a law) to double the space needed each step just to minimize the number of realloc()s that occur.

Finally you might note that readline() returns a pointer to a malloc()d buffer. As such, it’s up to the caller to explicitly free() that memory when it’s done with it.

12.5.2 realloc() with NULL

    char *p = malloc(3490);
    char *p = realloc(NULL, 3490);

That could be convenient if you have some kind of allocation loop and you don’t want to special-case the first malloc().

In that example, we didn’t need an initial malloc() since p was NULL to start.

12.6 Aligned Allocations

And I don’t want to get too far off in the weeds talking about it right now, but there’s this thing called memory alignment, which has to do with the memory address (pointer value) being a multiple of a certain number.

For example, a system might require that 16-bit values begin on memory addresses that are multiples of 2. Or that 64-bit values begin on memory addresses that are multiples of 2, 4, or 8, for example. It depends on the CPU.

Some systems require this kind of alignment for fast memory access, or some even for memory access at all.

Now, if you use malloc(), calloc(), or realloc(), C will give you a chunk of memory that’s well-aligned for any value at all, even structs. Works in all cases.

But there might be times that you know that some data can be aligned at a smaller boundary, or must be aligned at a larger one for some reason. I imagine this is more common with embedded systems programming.

The alignment is an integer power of two greater than zero, so 2, 4, 8, 16, etc. and you give that to aligned_alloc() before the number of bytes you’re interested in.

The other restriction is that the number of bytes you allocate needs to be a multiple of the alignment. But this might be changing. See C Defect Report 460 ⁷⁰

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

int main(void)
{
    // Allocate 256 bytes aligned on a 64-byte boundary
    char *p = aligned_alloc(64, 256);  // 256 == 64 * 4

    // Copy a string in there and print it
    strcpy(p, "Hello, world!");
    printf("%s\n", p);

    // Free the space
    free(p);
}

I want to throw a note here about realloc() and aligned_alloc(). realloc() doesn’t have any alignment guarantees, so if you need to get some aligned reallocated space, you’ll have to do it the hard way with memcpy().

    void *aligned_realloc(void *ptr, size_t old_size, size_t alignment, size_t size)
    {
        char *new_ptr = aligned_alloc(alignment, size);
    
        if (new_ptr == NULL)
            return NULL;
    
        size_t copy_size = old_size < size? old_size: size;  // get min
    
        if (ptr != NULL)
            memcpy(new_ptr, ptr, copy_size);
    
        free(ptr);
    
        return new_ptr;
    }

Note that it always copies data, taking time, while real realloc() will avoid that if it can. So this is hardly efficient. Avoid needing to reallocate custom-aligned data.

13 Scope

13.1 Block Scope

This is the scope of almost all the variables devs define. It includes what other languages might call “function scope”, i.e. variables that are declared inside functions.

The basic rule is that if you’ve declared a variable in a block delimited by squirrelly braces, the scope of that variable is that block.

If there’s a block inside a block, then variables declared in the inner block are local to that block, and cannot be seen in the outer scope.

Once a variable’s scope ends, that variable can no longer be referenced, and you can consider its value to be gone into the great bit bucket ⁷¹ in the sky.

int main(void)
{
    int a = 12;         // Local to outer block, but visible in inner block

    if  (a == 12) {
        int b = 99;     // Local to inner block, not visible in outer block

        printf("%d %d\n", a, b);  // OK: "12 99"
    }

    printf("%d\n", a);  // OK, we're still in a's scope

    printf("%d\n", b);  // ILLEGAL, out of b's scope
}

13.1.1 Where To Define Variables

Another fun fact is that you can define variables anywhere in the block, within reason—they have the scope of that block, but cannot be used before they are defined.

#include <stdio.h>

int main(void)
{
    int i = 0;

    printf("%d\n", i);     // OK: "0"

    //printf("%d\n", j);   // ILLEGAL--can't use j before it's defined

    int j = 5;

    printf("%d %d\n", i, j);   // OK: "0 5"
}

Historically, C required all the variables be defined before any code in the block, but this is no longer the case in the C99 standard.

13.1.2 Variable Hiding

If you have a variable named the same thing at an inner scope as one at an outer scope, the one at the inner scope takes precedence at long as you’re running in the inner scope. That is, it hides the one at outer scope for the duration of its lifetime.

#include <stdio.h>

int main(void)
{
    int i = 10;

    {
        int i = 20;

        printf("%d\n", i);  // Inner scope i, 20 (outer i is hidden)
    }

    printf("%d\n", i);  // Outer scope i, 10
}

You might have noticed in that example that I just threw a block in there at line 7, not so much as a for or if statement to kick it off! This is perfectly legal. Sometimes a dev will want to group a bunch of local variables together for a quick computation and will do this, but it’s rare to see.

13.2 File Scope

If you define a variable outside of a block, that variable has file scope. It’s visible in all functions in the file that come after it, and shared between them. (An exception is if a block defines a variable of the same name, it would hide the one at file scope.)

This is closest to what you would consider to be “global” scope in another language.

#include <stdio.h>

int shared = 10;    // File scope! Visible to the whole file after this!

void func1(void)
{
    shared += 100;  // Now shared holds 110
}

void func2(void)
{
    printf("%d\n", shared);  // Prints "110"
}

int main(void)
{
    func1();
    func2();
}

Note that if shared were declared at the bottom of the file, it wouldn’t compile. It has to be declared before any functions use it.

There are ways to further modify items at file scope, namely with (static)[#static] and (extern)[#extern], but we’ll talk more about those later.

13.3 for-loop Scope

I really don’t know what to call this, as C11 §6.8.5.3¶1 doesn’t give it a proper name. We’ve done it already a few times in this guide, as well. It’s when you declare a variable inside the first clause of a for-loop:

    for (int i = 0; i < 10; i++)
        printf("%d\n", i);
    
    printf("%d\n", i);  // ILLEGAL--i is only in scope for the for-loop

In that example, i’s lifetime begins the moment it is defined, and continues for the duration of the loop.

If the loop body is enclosed in a block, the variables defined in the for-loop are visible from that inner scope.

Unless, of course, that inner scope hides them. This crazy example prints 999 five times:

#include <stdio.h>

int main(void)
{
    for (int i = 0; i < 5; i++) {
        int i = 999;  // Hides the i in the for-loop scope
        printf("%d\n", i);
    }
}

13.4 A Note on Function Scope

The C spec does refer to function scope, but it’s used exclusively with labels, something we haven’t discussed yet. More on that another day.

14 Types II: Way More Types!

We’re used to char, int, and float types, but it’s now time to take that stuff to the next level and see what else we have out there in the types department!

14.1 Signed and Unsigned Integers

So far we’ve used int as a signed type, that is, a value that can be either negative or positive. But C also has specific unsigned integer types that can only hold positive numbers.

    int a;           // signed
    signed int a;    // signed
    signed a;        // signed, "shorthand" for "int" or "signed int", rare
    unsigned int b;  // unsigned
    unsigned c;      // unsigned, shorthand for "unsigned int"

Answer: you can get larger numbers in an unsigned variable than you can in a signed ones.

You can think of integers being represented by a certain number of bits⁷². On my computer, an int is represented by 64 bits.

And each permutation of bits that are either 1 or 0 represents a number. We can decide how to divvy up these numbers.

With signed numbers, we use (roughly) half the permutations to represent negative numbers, and the other half to represent positive numbers.

On my computer with 64-bit ints using two’s complement ⁷³ to represent unsigned numbers, I have the following limits on integer range:

Type	Minimum	Maximum
`int`	`-9,223,372,036,854,775,808`	`9,223,372,036,854,775,807`
`unsigned int`	`0`	`18,446,744,073,709,551,615`

Notice that the largest positive unsigned int is approximately twice as large as the largest positive int. So you can get some flexibility there.

14.2 Character Types

    char c = 'B';
    
    printf("%c\n", c);  // "B"

    char c = 'B';
    
    // Change this from %c to %d:
    printf("%d\n", c);  // 66 (!!)

Deep down, char is just a small int, namely an integer that uses just a single byte of space, limiting its range to…

Here the C spec gets just a little funky. It assures us that a char is a single byte, i.e. sizeof(char) == 1. But then in C11 §3.6¶3 it goes out of its way to say:

Wait—what? Some of you might be used to the notion that a byte is 8 bits, right? I mean, that’s what it is, right? And the answer is, “Almost certainly.”⁷⁴ But C is an old language, and machines back in the day had, shall we say, a more relaxed opinion over how many bits were in a byte. And through the years, C has retained this flexibility.

But assuming your bytes in C are 8 bits, like they are for virtually all machines in the world that you’ll ever see, the range of a char is…

—So before I can tell you, it turns out that chars might be signed or unsigned depending on your compiler. Unless you explicitly specify.

In many cases, just having char is fine because you don’t care about the sign of the data. But if you need signed or unsigned chars, you must be specific:

    char a;           // Could be signed or unsigned
    signed char b;    // Definitely signed
    unsigned char c;  // Definitely unsigned

OK, now, finally, we can figure out the range of numbers if we assume that a char is 8 bits and your system uses the virtually universal two’s complement representation for signed and unsigned⁷⁵.

`char` type	Minimum	Maximum
`signed char`	`-128`	`127`
`unsigned char`	`0`	`255`

#include <stdio.h>

int main(void)
{
    char a = 10, b = 20;

    printf("%d\n", a + b);  // 30!
}

What about those constant characters in single quotes, like 'B'? How does that have a numeric value?

The spec is also hand-wavey here, since C isn’t designed to run on a single type of underlying system.

But let’s just assume for the moment that your character set is based on ASCII ⁷⁶ for at least the first 128 characters. In that case, the character constant will be converted to a char whose value is the same as the ASCII value of the character.

#include <stdio.h>

int main(void)
{
    char a = 10;
    char b = 'B';  // ASCII value 66

    printf("%d\n", a + b);  // 76!
}

This depends on your execution environment and the character set used ⁷⁷. One of the most popular character sets today is Unicode ⁷⁸ (which is a superset of ASCII), so for your basic 0-9, A-Z, a-z and punctuation, you’ll almost certainly get the ASCII values out of them.

14.3 More Integer Types: short, long, long long

and we recently learned about the unsigned variants of the integer types. And we learned that char was secretly a small int in disguise. So we know the ints can come in multiple bit sizes.

But there are a couple more integer types we should look at, and the minimum minimum and maximum values they can hold.

Yes, I said “minimum” twice. The spec says that these types will hold numbers of at least these sizes, so your implementation might be different. The header file <limits.h> defines macros that hold the minimum and maximum integer values; rely on that to be sure, and never hardcode or assume these values.

These additional types are short int, long int, and long long int. Commonly, when using these types, C developers leave the int part off (e.g. long long), and the compiler is perfectly happy.

    // These two lines are equivalent:
    long long int x;
    long long x;
    
    // And so are these:
    short int x;
    short x;

Let’s take a look at the integer data types and sizes in ascending order, grouped by signedness.

Type	Minimum Bytes	Minimum Value	Maximum Value
`char`	1	-127 or 0	127 or 255⁷⁹
`signed char`	1	-127	127
`short`	2	-32767	32767
`int`	2	-32767	32767
`long`	4	-2147483647	2147483647
`long long`	8	-9223372036854775807	9223372036854775807
`unsigned char`	1	0	255
`unsigned short`	2	0	65535
`unsigned int`	2	0	65535
`unsigned long`	4	0	44294967295
`unsigned long long`	8	0	9223372036854775807

There is no long long long type. You can’t just keep adding longs like that. Don’t be silly.

Let’s run the same table on my 64-bit, two’s complement system and see what comes out:

That’s a little more sensible, but we can see how my system has larger limits than the minimums in the specification.

Type	My Bytes	Minimum Value	Maximum Value
`char`	1	-128	127⁸¹
`signed char`	1	-128	127
`short`	2	-32768	32767
`int`	4	-2147483648	2147483647
`long`	8	-9223372036854775808	9223372036854775807
`long long`	8	-9223372036854775808	9223372036854775807
`unsigned char`	1	0	255
`unsigned short`	2	0	65535
`unsigned int`	4	0	4294967295
`unsigned long`	8	0	18446744073709551615
`unsigned long long`	8	0	18446744073709551615

Type	Min Macro	Max Macro
`char`	`CHAR_MIN`	`CHAR_MAX`
`signed char`	`SCHAR_MIN`	`SCHAR_MAX`
`short`	`SHRT_MIN`	`SHRT_MAX`
`int`	`INT_MIN`	`INT_MAX`
`long`	`LONG_MIN`	`LONG_MAX`
`long long`	`LLONG_MIN`	`LLONG_MAX`
`unsigned char`	`0`	`UCHAR_MAX`
`unsigned short`	`0`	`USHRT_MAX`
`unsigned int`	`0`	`UINT_MAX`
`unsigned long`	`0`	`ULONG_MAX`
`unsigned long long`	`0`	`ULLONG_MAX`

Notice there’s a way hidden in there to determine if a system uses signed or unsigned chars. If CHAR_MAX == UCHAR_MAX, it must be unsigned.

Also notice there’s no minimum macro for the unsigned variants—they’re just 0.

14.4 More Float: double and long double

Let’s see what the spec has to say about floating point numbers in §5.2.4.2.2¶1-2:

Parameter	Definition
\(s\)	sign (\(\pm1\))
\(b\)	base or radix of exponent representation (an integer \(> 1\))
\(e\)	exponent (an integer between a minimum \(e_{min}\) and a maximum \(e_{max}\))
\(p\)	precision (the number of base-\(b\) digits in the significand)
\(f_k\)	nonnegative integers less than \(b\) (the significand digits)

Note: we refer to a bunch of macros in this section. They can be found in the header <float.h>.

Floating point number are encoded in a specific sequence of bits (IEEE-754 format ⁸² is tremendously popular) in bytes.

Diving in a bit more, the number is basically represented as the significand (which is the number part—the significant digits themselves, also sometimes referred to as the mantissa) and the exponent, which is what power to raise the digits to. Recall that a negative exponent can make a number smaller.

Imagine we’re using $10$ as a number to raise by an exponent. We could represent the following numbers by using a significand of $12345$, and exponents of $-3$, $4$, and $0$ to encode the following floating point values:

For all those numbers, the significand stays the same. The only difference is the exponent.

On your machine, the base for the exponent is probably $2$, not $10$, since computers like binary. You can check it by printing the FLT_RADIX macro.

So we have a number that’s represented by a number of bytes, encoded in some way. Because there are a limited number of bit patterns, a limited number of floating point numbers can be represented.

But more particularly, only a certain number of significant decimal digits can be represented accurately.

And we have a couple of them. We know about float already, but for more precision we have double. And for even more precision, we have long double (unrelated to long int except by name).

The spec doesn’t go into how many bytes of storage each type should take, but on my system, we can see the relative size increases:

So each of the types (on my system) uses those additional bits for more precision.

Type	`sizeof`
`float`	4
`double`	8
`long double`	16

But how much precision are we talking, here? How many decimal numbers can be represented by these values?

Well, C provides us with a bunch of macros in <float.h> to help us figure that out.

It gets a little wonky if you are using a base-2 (binary) system for storing the numbers (which is virtually everyone on the planet, probably including you), but bear with me while we figure it out.

14.4.1 How Many Decimal Digits?

The million dollar question is, “How many significant decimal digits can I store in a given floating point type so that I get out the same decimal number when I print it?”

The number of decimal digits you can store in a floating point type and surely get the same number back out when you print it is given by these macros:

Type	Decimal Digits You Can Store	Minimum
`float`	`FLT_DIG`	6
`double`	`DBL_DIG`	10
`long double`	`LDBL_DIG`	10

On my system, FLT_DIG is 6, so I can be sure that if I print out a 6 digit float, I’ll get the same thing back. (It could be more digits—some numbers will come back correctly with more digits. But 6 is definitely coming back.)

For example, printing out floats following this pattern of increasing digits, we apparently make it to 8 digits before something goes wrong, but after that we’re back to 7 correct digits.

Let’s do another demo. In this code we’ll have two floats that both hold numbers that have FLT_DIG significant decimal digits⁸³. Then we add those together, for what should be 12 significant decimal digits. But that’s more than we can store in a float and correctly recover as a string—so we see when we print it out, things start going wrong after the 7th significant digit.

#include <stdio.h>
#include <float.h>

int main(void)
{
    // Both these numbers have 6 significant digits, so they can be
    // stored accurately in a float:

    float f = 3.14159f;
    float g = 0.00000265358f;

    printf("%.5f\n", f);   // 3.14159       -- correct!
    printf("%.11f\n", g);  // 0.00000265358 -- correct!

    // Now add them up
    f += g;                // 3.14159265358 is what f _should_ be

    printf("%.11f\n", f);  // 3.14159274101 -- wrong!
}

(The above code has an f after the numeric constants—this indicates that the constant is type float, as opposed to the default of double. More on this later.)

Remember that FLT_DIG is the safe number of digits you can store in a float and retrieve correctly.

Sometimes you might get one or two more out of it. But sometimes you’ll only get FLT_DIG digits back. The sure thing: if you store any number of digits up to and including FLT_DIG in a float, you’re sure to get them back correctly.

14.4.2 Converting to Decimal and Back

But storing a base 10 number in a floating point number and getting it back out is only half the story.

Turns out floating point numbers can encode numbers that require more decimal places to print out completely. It’s just that your big decimal number might not map to one of those numbers.

That is, when you look at floating point numbers from one to the next, there’s a gap. If you try to encode a decimal number in that gap, it’ll use the closest floating point number. That’s why you can only encode FLT_DIG for a float.

But what about those floating point numbers that aren’t in the gap? How many places do you need to print those out accurately?

Another way to phrase this question is for any given floating point number, how many decimal digits do I have to preserve if I want to convert the decimal number back into an identical floating point number? That is, how many digits do I have to print in base 10 to recover all the digits in base 2 in the original number?

Sometimes it might only be a few. But to be sure, you’ll want to convert to decimal with a certain safe number of decimal places. That number is encoded in the following macros:

Macro	Description
`FLT_DECIMAL_DIG`	Number of decimal digits encoded in a `float`.
`DBL_DECIMAL_DIG`	Number of decimal digits encoded in a `double`.
`LDBL_DECIMAL_DIG`	Number of decimal digits encoded in a `long double`.
`DECIMAL_DIG`	Same as the widest encoding, `LDBL_DECIMAL_DIG`.

Let’s see an example where DBL_DIG is 15 (so that’s all we can have in a constant), but DBL_DECIMAL_DIG is 17 (so we have to convert to 17 decimal numbers to preserve all the bits of the original double).

Let’s assign the 15 significant digit number 0.123456789012345 to x, and let’s assign the 1 significant digit number 0.0000000000000006 to y.

But let’s add them together. This should give 0.1234567890123456, but that’s more than DBL_DIG, so strange things might happen… let’s look:

That’s what we get for printing more than DBL_DIG, right? But check this out… that number, above, is exactly representable as it is!

If we’d truncated z down to 15 digits, it wouldn’t have been the same number. That’s why to preserve all the bits of a double, we need DBL_DECIMAL_DIG and not just the lesser DBL_DIG.

All that being said, it’s clear that when we’re messing with decimal numbers in general, it’s not safe to print more than FLT_DIG, DBL_DIG, or LDBL_DIG digits to be sensible in relation to the original base 10 numbers and any subsequent math.

But when converting from float to a decimal representation and back to float, definitely use FLT_DECIMAL_DIG to do that so that all the bits are preserved exactly.

14.5 Constant Numeric Types

When you write down a constant number, like 1234, it has a type. But what type is it? Let’s look at the how C decides what type the constant is, and how to force it to choose a specific type.

14.5.1 Hexadecimal and Octal

In addition to good ol’ decimal like Grandma used to bake, C also supports constants of different bases.

    int a = 0x1A2B;   // Hexadecimal
    int b = 0x1a2b;   // Case doesn't matter for hex digits
    
    printf("%x", a);  // Print a hex number, "1a2b"

    int a = 012;
    
    printf("%o\n", a);  // Print an octal number, "12"

This is particularly problematic for beginner programmers who try to pad decimal numbers on the left with 0 to line things up nice and pretty, inadvertently changing the base of the number:

    int x = 11111;  // Decimal 11111
    int y = 00111;  // Decimal 73 (Octal 111)
    int z = 01111;  // Decimal 585 (Octal 1111)

14.5.1.1 A Note on Binary

An unofficial extension⁸⁴ in many C compilers allows you to represent a binary number with a 0b prefix:

    int x = 0b101010;    // Binary 101010
    
    printf("%d\n", x);   // Prints 42 decimal

There’s no printf() format specifier for printing a binary number. You have to do it a character at a time with bitwise operators.

14.5.2 Integer Constants

You can force a constant integer to be a certain type by appending a suffix to it that indicates the type.

We’ll do some assignments to demo, but most often devs leave off the suffixes unless needed to be precise. The compiler is pretty good at making sure the types are compatible.

    int           x = 1234;
    long int      x = 1234L;
    long long int x = 1234LL
    
    unsigned int           x = 1234U;
    unsigned long int      x = 1234UL;
    unsigned long long int x = 1234ULL;

The suffix can be uppercase or lowercase. And the U and L or LL can appear either one first.

Type	Suffix
`int`	None
`long int`	`L`
`long long int`	`LL`
`unsigned int`	`U`
`unsigned long int`	`UL`
`unsigned long long int`	`ULL`

I mentioned in the table that “no suffix” means int… but it’s actually more complex than that.

What C will generally do is choose the smallest type from int up that can hold the value.

But specifically, that depends on the number’s base (decimal, hex, or octal), as well.

The spec has a great table indicating which type gets used for what unsuffixed value. In fact, I’m just going to copy it wholesale right here.

C11 §6.4.4.1¶5 reads, “The type of an integer constant is the first of the first of the corresponding list in which its value can be represented.”

Suffix	Decimal Constant	Octal or Hexadecimal Constant
none	`int` `long int`	`int` `unsigned int` `long int` `unsigned long int` `long long int` `unsigned long long int`
`u` or `U`	`unsigned int` `unsigned long int` `unsigned long long int`	`unsigned int` `unsigned long int` `unsigned long long int`
`l` or `L`	`long int` `long long int`	`long int` `unsigned long int` `long long int` `unsigned long long int`
Both `u` or `U` and `l` or `L`	`unsigned long int` `unsigned long long int`	`unsigned long int` `unsigned long long int`
`ll` or `LL`	`long long int`	`long long int` `unsigned long long int`
Both `u` or `U` and `ll` or `LL`	`unsigned long long int`	`unsigned long long int`

What that’s saying is that, for example, if you specify a number like 123456789U, first C will see if it can be unsigned int. If it doesn’t fit there, it’ll try unsigned long int. And then unsigned long long int. It’ll use the smallest type that can hold the number.

14.5.3 Floating Point Constants

You’d think that a floating point constant like 1.23 would have a default type of float, right?

Surprise! Turns out unsuffiexed floating point numbers are type double! Happy belated birthday!

You can force it to be of type float by appending an f (or F—it’s case-insensitive). You can force it to be of type long double by appending l (or L).

Type	Suffix
`float`	`F`
`double`	None
`long double`	`L`

    float x       = 3.14f;
    double x      = 3.14;
    long double x = 3.14L;

Isn’t the left a float and the right a double? Yes! But C’s pretty good with automatic numeric conversions, so it’s more common to have an unsuffixed floating point constant than not. More on that later.

14.5.3.1 Scientific Notation

Remember earlier when we talked about how a floating point number can be represented by a significand, base, and exponent?

Well, there’s a common way of writing such a number, shown here followed by it’s more recognizable equivalent which is what you get when you actually run the math:

Writing numbers in the form $s\times b^e$ is called scientific notation⁸⁵. In C, these are written using “E notation”, so these are equivalent:

Scientific Notation	E notation
\(1.2345\times10^{-3}=12.345\)	`1.2345e-3`
\(1.2345\times10^4=123450000\)	`1.2345e+4`

14.5.3.2 Hexadecimal Floating Point Constants

These work similar to decimal floating point numbers, but they begin with a 0x just like integer numbers.

The catch is that you must specify an exponent, and this exponent produces a power of 2. That is: $2^x$.

When using floating point hex constants, We can print hex scientific notation with %a:

    double x = 0xa.1p3;
    
    printf("%a\n", x);  // 0x1.42p+6
    printf("%f\n", x);  // 80.500000

15 Types III: Conversions

In this chapter, we want to talk all about converting from one type to another. C has a variety of ways of doing this, and some might be a little different that you’re used to in other languages.

Before we talk about how to make conversions happen, let’s talk about how they work when they do happen.

15.1 String Conversions

Unlike many languages, C doesn’t do string-to-number (and vice-versa) conversions in quite as streamlined a manner as it does numeric conversions.

15.1.1 Numeric Value to String

When we want to convert a number to a string, we can use either sprintf() (pronounced SPRINT-f) or snprintf() (s-n-print-f)⁸⁶

These basically work like printf(), except they output to a string instead, and you can print that string later, or whatever.

#include <stdio.h>

int main(void)
{
    char s[10];
    float f = 3.14159;

    // Convert "f" to string, storing in "s", writing at most 10 characters
    // including the NUL terminator

    snprintf(s, 10, "%f", f);

    printf("String value: %s\n", s);  // String value: 3.141590
}

If we wanted to convert a double, we’d use %lf. Or a long double, %Lf.

15.1.2 String to Numeric Value

There are a couple families of functions to do this in C. We’ll call these the atoi (pronounced a-to-i) family and the strtol (stir-to-long) family.

For basic conversion from a string to a number, try the atoi functions from <stdlib.h>. These have bad error-handling characteristics (including undefined behavior if you pass in a bad string), so use them carefully.

Function	Description
`atoi`	String to `int`
`atof`	String to `float`
`atol`	String to `long int`
`atoll`	String to `long long int`

Though the spec doesn’t cop to it, the a at the beginning of the function stands for ASCII ⁸⁷, so really atoi() is “ASCII-to-integer”, but saying so today is a bit ASCII-centric.

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

int main(void)
{
    char *pi = "3.14159";
    float f;

    f = atof(pi);

    printf("%f\n", f);
}

    int x = atoi("what");  // "What" ain't no number I ever heard of

(When I run that, I get 0 back, but you really shouldn’t count on that in any way. You could get something completely different.)

For better error handling characteristics, let’s check out all those strtol functions, also in <stdlib.h>. Not only that, but they convert to more types and more bases, too!

These functions all follow a similar pattern of use, and are a lot of people’s first experience with pointers to pointers! But never fret—it’s easier than it looks.

Function	Description
`strtol`	String to `long int`
`strtoll`	String to `long long int`
`strtoul`	String to `unsigned long int`
`strtoull`	String to `unsigned long long int`
`strtof`	String to `float`
`strtod`	String to `double`
`strtold`	String to `long double`

Let’s do an example where we convert a string to an unsigned long, discarding error information (i.e. information about bad characters in the input string):

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

int main(void)
{
    char *s = "3490";

    // Convert string s, a number in base 10, to an unsigned long int.
    // NULL means we don't care to learn about any error information.

    unsigned long int x = strtoul(s, NULL, 10);

    printf("%lu\n", x);  // 3490
}

Notice a couple things there. Even though we didn’t deign to capture any information about error characters in the string, strtoul() won’t give us undefined behavior; it will just return 0.

Does this mean we can convert numbers of different bases? Sure! Let’s do binary!

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

int main(void)
{
    char *s = "101010";  // What's the meaning of this number?

    // Convert string s, a number in base 2, to an unsigned long int.

    unsigned long int x = strtoul(s, NULL, 2);

    printf("%lu\n", x);  // 42
}

OK, that’s all fun and games, but what’s with that NULL in there? What’s that for?

That helps us figure out if an error occurred in the processing of the string. It’s a pointer to a pointer to a char, which sounds scary, but isn’t once you wrap your head around it.

Let’s do an example where we feed in a deliberately bad number, and we’ll see how strtol() lets us know where the first invalid digit is.

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

int main(void)
{
    char *s = "34x90";  // "x" is not a valid digit in base 10!
    char *badchar;

    // Convert string s, a number in base 10, to an unsigned long int.

    unsigned long int x = strtoul(s, &badchar, 10);

    // It tries to convert as much as possible, so gets this far:

    printf("%lu\n", x);  // 34

    // But we can see the offending bad character because badchar
    // points to it!

    printf("Invalid character: %c\n", *badchar);  // "x"
}

So there we have strtoul() modifying what badchar points to in order to show us where things went wrong⁸⁸.

But what if nothing goes wrong? In that case, badchar will point to the NUL terminator at the end of the string. So we can test for it:

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

int main(void)
{
    char *s = "3490";  // "x" is not a valid digit in base 10!
    char *badchar;

    // Convert string s, a number in base 10, to an unsigned long int.

    unsigned long int x = strtoul(s, &badchar, 10);

    // Check if things went well

    if (*badchar == '\0') {
        printf("Success! %lu\n", x);
    } else  {
        printf("Partial conversion: %lu\n", x);
        printf("Invalid character: %c\n", *badchar);
    }
}

So there you have it. The atoi()-style functions are good in a controlled pinch, but the strtol()-style functions give you far more control over error handling and the base of the input.

15.2 Numeric Conversions

15.2.1 Boolean

15.2.2 Integer to Integer Conversions

If an integer type is converted to unsigned and doesn’t fit in it, the unsigned result wraps around odometer-style until it fits in the unsigned⁸⁹.

If an integer type is converted to a signed number and doesn’t fit, the result is implementation-defined! Something documented will happen, but you’ll have to look it up⁹⁰

15.2.3 Integer and Floating Point Conversions

If a floating point type is converted to an integer type, the fractional part is discarded with prejudice⁹¹.

But—and here’s the catch—if the number is too large to fit in the integer, you get undefined behavior. So don’t do that.

Going From integer or floating point to floating point, C makes a best effort to find the closest floating point number to the integer that it can.

Again, though, if the original value can’t be represented, it’s undefined behavior.

15.3 Implicit Conversions

These are conversions the compiler does automatically for you when you mix and match types.

15.3.1 The Integer Promotions

In a number of places, if a int can be used to represent a value from char or short (signed or unsigned), that value is promoted up to int. If it doesn’t fit in an int, it’s promoted to unsigned int.

    char x = 10, y = 20;
    int i = x + y;

In that case, x and y get promoted to int by C before the math takes place.

The integer promotions take place during The Usual Arithmetic Conversions, with variadic functions⁹², unary + and - operators, or when passing values to functions without prototypes⁹³.

15.3.2 The Usual Arithmetic Conversions

These are automatic conversions that C does around numeric operations that you ask for. (That’s actually what they’re called, by the way, by C11 §6.3.1.8.) Note that for this section, we’re just talking about numeric types—strings will come later.

These conversions answer questions about what happens when you mix types, like this:

    int x = 3 + 1.2;   // Mixing int and double
                       // 4.2 is converted to int
                       // 4 is stored in x
    
    float y = 12 * 2;  // Mixing float and int
                       // 24 is converted to float
                       // 24.0 is stored in y

If you want to know the gritty details, check out C11 §6.3.1.8. But you probably don’t.

Just generally remember that int types become float types if there’s a floating point type anywhere in there, and the compiler makes an effort to make sure mixed integer types don’t overflow.

Finally, if you convert from one floating point type to another, the compiler will try to make an exact conversion. If it can’t, it’ll do the best approximation it can. If the number is too large to fit in the type you’re converting into, boom: undefined behavior!

15.3.3 void*

The void* type is interesting because it can be converted from or to any pointer type.

    int x = 10;
    
    void *p = &x;  // &x is type int*, but we store it in a void*
    
    int *q = p;    // p is void*, but we store it in an int*

15.4 Explicit Conversions

These are conversions from type to type that you have to ask for; the compiler won’t do it for you.

You can convert from one type to another by assigning one type to another with an =.

15.4.1 Casting

You can explicitly change the type of an expression by putting a new type in parentheses in front of it. Some C devs frown on the practice unless absolutely necessary, but it’s likely you’ll come across some C code with these in it.

Let’s do an example where we want to convert an int into a long so that we can store it in a long.

Note: this example is contrived and the cast in this case is completely unnecessary because the x + 12 expression would automatically be changed to long int to match the wider type of y.

    int x = 10;
    long int y = (long int)x + 12;

In that example, even those x was type int before, the expression (long int)x has type long int. We say, “We cast x to long int.”

More commonly, you might see a cast being used to convert a void* into a specific pointer type so it can be dereferenced.

A callback from the built-in qsort() function might display this behavior since it has void*s passed into it:

    int compar(const void *elem1, const void *elem2)
    {
        return *((const int*)elem2) - *((const int*)elem1);
    }

    int compar(const void *elem1, const void *elem2)
    {
        const int *e1 = elem1;
        const int *e2 = elem2;
    
        return *e2 - *e1;
    }

One place you’ll see casts more commonly is to avoid a warning when printing pointer values with the rarely-used %p which gets picky with anything other than a void*:

    int x = 3490;
    int *p = &x;
    
    printf("%p\n", p);

    printf("%p\n", (void *)p);

Another place is with explicit pointer changes, if you don’t want to use an intervening void*, but these are also pretty uncommon:

    long x = 3490;
    long *p = &x;
    unsigned char *c = (unsigned char *)p;

Again, casting is rarely needed in practice. If you find yourself casting, there might be another way to do the same thing, or maybe you’re casting unnecessarily.

Or maybe it is necessary. Personally, I try to avoid it, but am not afraid to use it if I have to.

16 Types IV: Qualifiers and Specifiers

Now that we have some more types under our belts, turns out we can give these types some additional attributes that control their behavior. These are the type qualifiers and storage-class specifiers.

16.1 Type Qualifiers

These are going to allow you to declare constant values, and also to give the compiler optimization hints that it can use.

16.1.1 const

This is the most common type qualifier you’ll see. It means the variable is constant, and any attempt to modify it will result in a very angry compiler.

    const int x = 2;
    
    x = 4;  // COMPILER PUKING SOUNDS, can't assign to a constant

    void foo(const int x)
    {
        printf("%d\n", x + 30);  // OK, doesn't modify "x"
    }

16.1.1.1 const and Pointers

This one gets a little funky, because there are two usages that have two meanings when it comes to pointers.

For one thing, we can make it so you can’t change the thing the pointer points to. You do this by putting the const up front with the type name (before the asterisk) in the type declaration.

    int x[] = {10, 20};
    const int *p = x; 
    
    p++;  // We can modify p, no problem
    
    *p = 30; // Compiler error! Can't change what it points to

    const int *p;  // Can't modify what p points to
    int const *p;  // Can't modify what p points to, just like the previous line

Great, so we can’t change the thing the pointer points to, but we can change the pointer itself. What if we want the other way around? We want to be able to change what the pointer points to, but not the pointer itself?

    int x = 10;
    int *const p = &x;
    
    *p = 20;   // Set "x" to 20, no problem

    const int *const p;  // Can't modify p or *p!

Finally, if you have multiple levels of indirection, you should const the appropriate levels. Just because a pointer is const, doesn’t mean the pointer it points to must also be. You can explicitly set them like in the following examples:

    char **p;
    p++;     // OK!
    (*p)++;  // OK!
    
    char **const p;
    p++;     // Error!
    (*p)++;  // OK!
    
    char *const *p;
    p++;     // OK!
    (*p)++;  // Error!
    
    char *const *const p;
    p++;     // Error!
    (*p)++;  // Error!

16.1.1.2 const Correctness

One more thing I have to mention is that the compiler will warn on something like this:

    const int x = 20;
    int *p = &x;

        const int x = 20;
        int *p = &x;
    //    ^       ^
    //    |       |
    //  int*    const int*

The compiler is warning us that the value on the right side of the assignment is const, but the one of the left is not. And the compiler is letting us know that it is discarding the “const-ness” of the expression on the right.

That is, we can still try to do the following, but it’s just wrong. The compiler will warn, and it’s undefined behavior:

    const int x = 20;
    int *p = &x;
    
    *p = 40;  // Undefined behavior--maybe it modifies "x", maybe not!
    
    printf("%d\n", x);  // 40, if you're lucky

16.1.2 restrict

restrict is a hint to the compiler that a particular piece of memory will only be accessed by one pointer and never another. If a developer declares a pointer to be restrict and then accesses the object it points to in another way, the behavior is undefined.

Basically you’re telling C, “Hey—I guarantee that this one single pointer is the only way I access this memory, and if I’m lying, you can pull undefined behavior on me.”

For example, let’s write a function to swap two variables, and we’ll use the restrict keyword to assure C that we’ll never pass in pointers to the same thing. And then let’s blow it an try passing in pointers to the same thing.

void swap(int *restrict a, int *restrict b)
{
    int t;

    t = *a;
    *a = *b;
    *b = t;
}

int main(void)
{
    int x = 10, y = 20;

    swap(&x, &y);  // OK! "a" and "b", above, point to different things

    swap(&x, &x);  // Undefined behavior! "a" and "b" point to the same thing
}

If we were to take out the restrict keywords, above, that would allow both calls to work safely. But then the compiler might not be able to optimize.

restrict has block scope, that is, the restriction only lasts for the scope its used. If it’s in a parameter list for a function, it’s in the block scope of that function.

If the restricted pointer points to an array, the restriction covers the entire array.

If it’s outside any function in file scope, the restriction covers the entire program.

    int printf(const char * restrict format, ...);

Again, that’s just telling the compiler that inside the printf() function, there will be only one pointer that refers to any part of that format string.

16.1.3 volatile

You’re unlikely to see or need this unless you’re dealing with hardware directly.

volatile tells the compiler that a value might change behind its back and should be looked up every time.

An example might be where the compiler is looking in memory at an address that continuously updates behind the scenes, e.g. some kind of hardware timer.

If the compiler decides to optimize that and store the value in a register for a protracted time, the value in memory will update and won’t be reflected in the register.

By declaring something volatile, you’re telling the compiler, “Hey, the thing this points at might change at any time for reasons outside this program code.”

16.1.4 _Atomic

16.2 Storage-Class Specifiers

Storage-class specifiers are similar to type quantifiers. They give the compiler more information about the type of a variable.

16.2.1 auto

You barely ever see this keyword, since auto is the default for block scope variables. It’s implied.

    {
        int a;         // auto is the default...
        auto int a;    // So this is redundant
    }

The auto keyword indicates that this object has automatic storage duration. That is, it exists in the scope in which it is defined, and is automatically deallocated when the scope is exited.

One gotcha about automatic variables is that their value is indeterminate until you explicitly initialize them. We say they’re full of “random” or “garbage” data, though neither of those really makes me happy. In any case, you won’t know what’s in it unless you initialize it.

16.2.2 static

This keyword has two meanings, depending on if the variable is file scope or block scope.

16.2.2.1 static in Block Scope

In this case, we’re basically saying, “I just want a single instance of this variable to exist, shared between calls.”

static in block scope with an initializer will only be initialized one time on program startup, not each time the function is called.

#include <stdio.h>

void counter(void)
{
    static int count = 1;  // This is initialized one time

    printf("This has been called %d time(s)\n", count);

    count++;
}

int main(void)
{
    counter();  // "This has been called 1 time(s)"
    counter();  // "This has been called 2 time(s)"
    counter();  // "This has been called 3 time(s)"
    counter();  // "This has been called 4 time(s)"
}

One thing of note is that static block scope variables are initialized to 0 by default.

    static int foo;      // Default starting value is `0`...
    static int foo = 0;  // So the `0` assignment is redundant

Finally, be advised that if you’re writing multithreaded programs, you have to be sure you don’t let multiple threads trample the same variable.

16.2.2.2 static in File Scope

Variables at file scope already persist between function calls, so that behavior is already there.

Instead what static means in this context is that this variable isn’t visible outside of this particular source file. Kinda like “global”, but only in this file.

16.2.3 extern

The extern storage-class specifier gives us a way to refer to objects in other source files.

// bar.c

int a = 37;

But what if we had another source file, foo.c, and we wanted to refer to the a that’s in bar.c?

// foo.c

extern int a;

int main(void)
{
    printf("%d\n", a);  // 37, from bar.c!

    a = 99;

    printf("%d\n", a);  // Same "a" from bar.c, but it's now 99
}

We could have also made the extern int a in block scope, and it still would have referred to the a in bar.c:

// foo.c

int main(void)
{
    extern int a;

    printf("%d\n", a);  // 37, from bar.c!

    a = 99;

    printf("%d\n", a);  // Same "a" from bar.c, but it's now 99
}

Now, if a in bar.c had been marked static. this wouldn’t have worked. static variables at file scope are not visible outside that file.

A final note about extern on functions. For functions, extern is the default, so it’s redundant. You can declare a function static if you only want it visible in a single source file.

16.2.4 register

This is a keyword to hint to the compiler that this variable is frequently-used, and should be made as fast as possible to access. The compiler is under no obligation to agree to it.

Now, modern C compiler optimizers are pretty effective at figuring this out themselves, so it’s rare to see these days.

#include <stdio.h>

int main(void)
{
    register int a;   // Make "a" as fast to use as possible.

    for (a = 0; a < 10; a++)
        printf("%d\n", a);
}

    register int a;
    int *p = &a;    // COMPILER ERROR! Can't take address of a register

    register int a[] = {11, 22, 33, 44, 55};
    int p = a;  // COMPILER ERROR! Can't take address of a[0]

    register int a[] = {11, 22, 33, 44, 55};
    
    int a = *(a + 2);  // COMPILER ERROR! Address of a[0] taken

    register int a[] = {11, 22, 33, 44, 55};
    
    int a = a[2];  // COMPILER WARNING!

The fact that you can’t take the address of a register variable frees the compiler up to make optimizations around that assumption if it hasn’t figured them out already. Also adding register to a const variable prevents one from accidentally passing its pointer to another function that willfully ignore its constness⁹⁴.

A bit of historic backstory, here: deep inside the CPU are little dedicated “variables” called registers⁹⁵. They are super fast to access compared to RAM, so using them gets you a speed boost. But they’re not in RAM, so they don’t have an associated memory address (which is why you can’t take the address-of or get a pointer to them).

But, like I said, modern compilers are really good at producing optimal code, using registers whenever possible regardless of whether or not you specified the register keyword. Not only that, but the spec allows them to just treat it as if you’d typed auto, if they want. So no guarantees.

16.2.5 _Thread_local

When you’re using multiple threads and you have some variables in either global or static block scope, this is a way to make sure that each thread gets its own copy of the variable. This’ll help you avoid race conditions and threads stepping on each other’s toes.

If you’re in block scope, you have to use this along with either extern or static.

Also, if you include <threads.h>, you can use the rather more palatable thread_local as an alias for the uglier _Thread_local.

17 Multifile Projects

So far we’ve been looking at toy programs that for the most part fit in a single file. But complex C programs are made up of many files that are all compiled and linked together into a single executable.

In this chapter we’ll check out some of the common patterns and practices for putting together larger projects.

17.1 Includes and Function Prototypes

A really common situation is that some of your functions are defined in one file, and you want to call them from another.

This actually works out of the box with a warning… let’s first try it and then look at the right way to fix the warning.

For these examples, we’ll put the filename as the first comment in the source.

In that examples, foo.c and bar.c get built into the executable named foo.

// File bar.c

int add(int x, int y)
{
    return x + y;
}

// File foo.c

#include <stdio.h>

int main(void)
{
    printf("%d\n", add(2, 3));  // 5!
}

See how from main() we call add()—but add() is in a completely different source file! It’s in bar.c, while the call to it is in foo.c!

But if we ignore that (which really we should never do—always get your code to build with zero warnings!) and try to run it:

What implicit declaration means is that we’re using a function, namely add() in this case, without letting C know anything about it ahead of time. C wants to know what it returns, what types it takes as arguments, and things such as that.

We saw how to fix that earlier with a function prototype. Indeed, if we add one of those to foo.c before we make the call, everything works well:

// File foo.c

#include <stdio.h>

int add(int, int);  // Add the prototype

int main(void)
{
    printf("%d\n", add(2, 3));  // 5!
}

But that’s a pain—needing to type in the prototype every time you want to use a function. I mean, we used printf() right there and didn’t need to type in a prototype; what gives?

If you remember from what back with hello.c at the beginning of the book, we actually did include the prototype for printf()! It’s in the file stdio.h! And we included that with #include!

Can we do the same with our add() function? Make a prototype for it and put it in a header file?

Header files in C have a .h extension by default. And they often, but not always, have the same name as their corresponding .c file. So let’s make a bar.h file for our bar.c file, and we’ll stick the prototype in it:

// File bar.h

int add(int, int);

And now let’s modify foo.c to include that file. Assuming it’s in the same directory, we include it inside double quotes (as opposed to angle brackets):

// File foo.c

#include <stdio.h>

#include "bar.h"  // Include from current directory

int main(void)
{
    printf("%d\n", add(2, 3));  // 5!
}

Notice how we don’t have the prototype in foo.c anymore—we included it from bar.h. Now any file that wants that add() functionality can just #include "bar.h" to get it, and you don’t need to worry about typing in the function prototype.

As you might have guessed, #include literally includes the named file right there in your source code, just as if you’d typed it in.

We’re almost there! There’s just one more piece of boilerplate we have to add.

17.2 Dealing with Repeated Includes

It’s not uncommon that a header file will itself #include other headers needed for the functionality of its corresponding C files. I mean, why not?

And it could be that you have a header #included multiple times from different places. Maybe that’s no problem, but maybe it would cause compiler errors. And we can’t control how many places #include it!

Even, worse we might get into a crazy situation where header a.h includes header b.h, and b.h includes a.h! It’s an #include infinite cycle!

What we need to do is make it so that if a file gets included once, subsequent #includes for that file are ignored.

The stuff that we’re about to do is so common that you should just automatically do it every time you make a header file!

And the common way to do this is with a preprocessor variable that we set the first time we #include the file. And then for subsequent #includes, we first check to make sure that the variable isn’t defined.

For that variable name, it’s super common to take the name of the header file, like bar.h, make it uppercase, and replace the period with an underscore: BAR_H.

So put a check at the very, very top of the file where you see if it’s already been included, and effectively comment the whole thing out if it has.

(Don’t put a leading underscore (because a leading underscore followed by a capital letter is reserved) or a double leading underscore (because that’s also reserved.))

#ifndef BAR_H   // If BAR_H isn't defined...
#define BAR_H   // Define it (with no particular value)

// File bar.h

int add(int, int);

#endif          // End of the #ifndef BAR_H

This will effectively cause the header file to be included only a single time, no matter how many places try to #include it.

17.3 static and extern

When it comes to multifile projects, you can make sure file-scope variables and functions are not visible from other source files with the static keyword.

For more info, check out the sections in the book on the static and extern storage-class specifiers.

17.4 Compiling with Object Files

You can compile C files into an intermediate representation called object files. These are compiled machine code that hasn’t been put into an executable yet.

But for larger programs, we can take advantage of the fact that compiling from source to object files is relatively slow, and linking together a bunch of object files is relatively fast.

This really shows with the make utility that only rebuilds sources that are newer than their outputs.

Let’s say you had a thousand C files. You could compile them all to object files to start (slowly) and then combine all those object files into an executable (fast).

Now say you modified just one of those C source files—here’s the magic: you only have to rebuild that one object file for that source file! And then you rebuild the executable (fast). All the other C files don’t have to be touched.

In other words, by only rebuilding the object files we need to, we cut down on compilation times radically. (Unless of course you’re doing a “clean” build, in which case all the object files have to be created.)

18 The Outside Environment

When you run a program, it’s actually you talking to the shell, saying, “Hey, please run this thing.” And the shell says, “Sure,” and then tells the operating system, “Hey, could you please make a new process and run this thing?” And if all goes well, the OS complies and your program runs.

But there’s a whole world outside your program in the shell that can be interacted with from within C. We’ll look at a few of those in this chapter.

18.1 Command Line Arguments

Many command line utilities accept command line arguments. For example, if we want to see all files that end in .txt, we can type something like this on a Unix-like system:

In this case, the command is ls, but it arguments are all all files that end with .txt⁹⁷.

Say we have a program called add that adds all numbers passed on the command line and prints the result:

But seriously, this is a great tool for seeing how to get those arguments from the command line and break them down.

First, let’s see how to get them at all. For this, we’re going to need a new main()!

Here’s a program that prints out all the command line arguments. For example, if we name the executable foo, we can run it like this:

It’s a little weird, because the zeroth argument is the name of the executable, itself. But that’s just something to get used to. The arguments themselves follow directly.

#include <stdio.h>

int main(int argc, char *argv[])
{
    for (int i = 0; i < argc; i++) {
        printf("arg %d: %s\n", i, argv[i]);
    }
}

Whoa! What’s going on with the main() function signature? What’s argc and argv⁹⁸ (pronounced arg-c and arg-v)?

Let’s start with the easy one first: argc. This is the argument count, including the program name, itself. If you think of all the arguments as an array of strings, which is exactly what they are, then you can think of argc as the length of that array, which is exactly what it is.

And so what we’re doing in that loop is going through all the argvs and printing them out one at a time, so for a given input:

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

int main(int argc, char **argv)
{
    int total = 0;

    for (int i = 1; i < argc; i++) {  // Start at 1, the first argument
        int value = atoi(argv[i]);    // Use strtol() for better error handling

        total += value;
    }

    printf("%d\n", total);
}

Of course, it might puke if you pass in a non-integer, but hardening against that is left as an exercise to the reader.

18.1.1 The Last argv is NULL

One bit of fun trivia about argv is that after the last string is a pointer to NULL.

    argv[argc] == NULL

This might seem pointless, but it turns out to be useful in a couple places; we’ll take a look at one of those right now.

18.1.2 The Alternate: char **argv

Remember that when you call a function, C doesn’t differentiate between array notation and pointer notation in the function signature.

    void foo(char a[])
    void foo(char *a)

Now, it’s been convenient to think of argv as an array of strings, i.e. an array of char*s, so this made sense:

    int main(int argc, char *argv[])

    int main(int argc, char **argv)

Yeah, that’s a pointer to a pointer, all right! If it makes it easier, think of it as a pointer to a string. But really, it’s a pointer to a value that points to a char.

    argv[i]
    *(argv + i)

So an alternate way to consume the command line arguments might be to just walk along the argv array by bumping up a pointer until we hit that NULL at the end.

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

int main(int argc, char **argv)
{
    int total = 0;
    
    // Cute trick to get the compiler to stop warning about the
    // unused variable argc:
    (void)argc;

    for (char **p = argv; *p != NULL; p++) {
        int value = atoi(*p);  // Use strtol() for better error handling

        total += value;
    }

    printf("%d\n", total);
}

Personally, I use array notation to access argv, but have seen this style floating around, as well.

18.1.3 Fun Facts

18.2 Exit Status

Did you notice that the function signatures for main() have it returning type int? What’s that all about? It has to do with a thing called the exit status, which is an integer that can be returned to the program that launched yours to let it know how things went.

Now, there are a number of ways a program can exit in C, including returning from main(), or calling one of the exit() variants.

Side note: did you see that in basically all my examples, even though main() is supposed to return an int, I don’t actually return anything? In any other function, this would be illegal, but there’s a special case in C: if execution reaches the end of main() without finding a return, it automatically does a return 0.

But what does the 0 mean? What other numbers can we put there? And how are they used?

The spec is both clear and vague on the matter, as is common. Clear because it spells out what you can do, but vague in that it doesn’t particularly limit it, either.

Let’s get Inception ¹⁰⁰ for a second: turns out that when you run your program, you’re running it from another program.

Usually this other program is some kind of shell ¹⁰¹ that doesn’t do much on its own except launch other programs.

Now, there’s a little piece of communication that takes place between steps 4 and 5: the program can return a status value that the shell can interrogate. Typically, this value is used to indicate the success or failure of your program, and, if a failure, what type of failure.

Now, the C spec allows for two different status values, which have macro names defined in <stdlib.h>:

Let’s write a short program that multiplies two numbers from the command line. We’ll require that you specify exactly two values. If you don’t, we’ll print an error message, and exit with an error status.

Status	Description
`EXIT_SUCCESS` or `0`	Program terminated successfully.
`EXIT_FAILURE`	Program terminated with an error.

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

int main(int argc, char **argv)
{
    if (argc != 3) {
        printf("usage: mult x y\n");
        return EXIT_FAILURE;   // Indicate to shell that it didn't work
    }

    printf("%d\n", atoi(argv[1]) * atoi(argv[2]));

    return 0;  // same as EXIT_SUCCESS, everything was good.
}

Now if we try to run this, we get the expected effect until we specify exactly the right number of command-line arguments:

But that doesn’t really show the exit status that we returned, does it? We can get the shell to print it out, though. Assuming you’re running Bash or another POSIX shell, you can use echo $? to see it¹⁰².

Interesting! We see that on my system, EXIT_FAILURE is 1. The spec doesn’t spell this out, so it could be any number. But try it; it’s probably 1 on your system, too.

18.2.1 Other Exit Status Values

The status 0 most definitely means success, but what about all the other integers, even negative ones?

Here we’re going off the C spec and into Unix land. In general, while 0 means success, a positive non-zero number means failure. So you can only have one type of success, and multiple types of failure. Bash says the exit code should be between 0 and 255, though a number of codes are reserved.

In short, if you want to indicate different error exit statuses in a Unix environment, you can start with 1 and work your way up.

On Linux, if you try any code outside the range 0-255, it will bitwise AND the code with 0xff, effectively clamping it to that range.

You can script the shell to later use these status codes to make decisions about what to do next.

18.3 Environment Variables

Before I get into this, I need to warn you that C doesn’t specify what an environment variable is. So I’m going to describe the environment variable system that works on every major platform I’m aware of.

Basically, the environment is the program that’s going to run your program, e.g. the bash shell. And it might have some bash variables defined. In case you didn’t know, the shell can make its own variables. Each shell is different, but in bash you can just type set and it’ll show you all of them.

Notice they are in the form of key/value pairs. For example, one key is HOSTTYPE and its value is x86_64. From a C perspective, all values are strings, even if they’re numbers¹⁰³.

So, anyway! Long story short, it’s possible to get these values from inside your C program.

Let’s write a program that uses the standard getenv() function to look up a value that you set in the shell.

getenv() will return a pointer to the value string, or else NULL if the environment variable doesn’t exist.

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

int main(void)
{
    char *val = getenv("FROTZ");  // Try to get the value

    // Check to make sure it exists
    if (val == NULL) {
        printf("Cannot find the FROTZ environment variable\n");
        return EXIT_FAILURE;
    }

    printf("Value: %s\n", val);
}

In this way, you can set up data in environment variables, and you can get it in your C code and modify your behavior accordingly.

18.3.1 Setting Environment Variables

This isn’t standard, but a lot of systems provide ways to set environment variables.

If on a Unix-like, look up the documentation for putenv(), setenv(), and unsetenv(). On Windows, see _putenv().

18.3.2 Unix-like Alternative Environment Variables

If you’re on a Unix-like system, odds are you have another couple ways of getting access to environment variables. Note that although the spec points this out as a common extension, it’s not truly part of the C standard. It is, however, part of the POSIX standard.

    extern char **environ;

You should declare it yourself before you use it, or you might find it in the non-standard <unistd.h> header file.

Each string is in the form "key=value" so you’ll have to split it and parse it yourself if you want to get the keys and values out.

Here’s an example of looping through and printing out the environment variables a couple different ways:

#include <stdio.h>

extern char **environ;  // MUST be extern AND named "environ"

int main(void)
{
    for (char **p = environ; *p != NULL; p++) {
        printf("%s\n", *p);
    }

    // Or you could do this:
    for (int i = 0; environ[i] != NULL; i++) {
        printf("%s\n", environ[i]);
    }
}

Use getenv() if at all possible because it’s more portable. But if you have to iterate over environment variables, using environ might be the way to go.

Another non-standard way to get the environment variables is as a parameter to main(). It works much the same way, but you avoid needing to add your extern environ variable. Not even the POSIX spec supports this ¹⁰⁵ as far as I can tell, but it’s common in Unix land.

#include <stdio.h>

int main(int argc, char **argv, char **env)  // <-- env!
{
    (void)argc; (void)argv;  // Suppress unused warnings

    for (char **p = env; *p != NULL; p++) {
        printf("%s\n", *p);
    }

    // Or you could do this:
    for (int i = 0; env[i] != NULL; i++) {
        printf("%s\n", env[i]);
    }
}

19 The C Preprocessor

Before your program gets compiled, it actually runs through a phase called preprocessing. It’s almost like there’s a language on top of the C language that runs first. And it outputs the C code, which then gets compiled.

We’ve already seen this to an extent with #include! That’s the C Preprocessor! Where it sees that directive, it includes the named file right there, just as if you’d typed it in there. And then the compiler builds the whole thing.

But it turns out it’s a lot more powerful than just being able to include things. You can define macros that are substituted… and even macros that take arguments!

19.1 #include

Let’s start with the one we’ve already seen a bunch. This is, of course, a way to include other sources in your source. Very commonly used with header files.

While the spec allows for all kinds of behavior with #include, we’re going to take a more pragmatic approach and talk about the way it works on every system I’ve ever seen.

We can split header files into two categories: system and local. Things that are built-in, like stdio.h, stdlib.h, math.h, and so on, you can include with angle brackets:

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

The angle brackets tell C, “Hey, don’t look in the current directory for this header file—look in the system-wide include directory instead.”

Which, of course, implies that there must be a way to include local files from the current directory. And there is: with double quotes:

    #include "myheader.h"

Or you can very probably look in relative directories using forward slashes and dots, like this:

    #include "mydir/myheader.h"
    #include "../someheader.py"

Don’t use a backslash (\) for your path separators in your #include! It’s undefined behavior! Use forward slash (/) only, even on Windows.

In summary, used angle brackets (< and >) for the system includes, and use double quotes (") for your personal includes.

19.2 Simple Macros

A macro is an identifier that gets expanded to another piece of code before the compiler even sees it. Think of it like a placeholder—when the preprocessor sees one of those identifiers, it replaces it with another value that you’ve defined.

#include <stdio.h>

#define HELLO "Hello, world"
#define PI 3.14159

int main(void)
{
    printf("%s, %f\n", HELLO, PI);
}

On lines 3 and 4 we defined a couple macros. Wherever these appear elsewhere in the code (line 8), they’ll be substituted with the defined values.

From the C compiler’s perspective, it’s exactly as if we’d written this, instead:

#include <stdio.h>

int main(void)
{
    printf("%s, %f\n", "Hello, world", 3.14159);
}

See how HELLO was replaced with "Hello, world" and PI was replaced with 3.14159? From the compiler’s perspective, it’s just like those values had appeared right there in the code.

Note that the macros don’t have a specific type, per se. Really all that happens is they get replaced wholesale with whatever they’re #defined as. If the resulting C code is invalid, the compiler will puke.

    #define EXTRA_HAPPY

in that case, the macro exists and is defined, but is defined to be nothing. So anyplace it occurs in the text will just be replaced with nothing. We’ll see a use for this later.

It’s conventional to write macro names in ALL_CAPS even though that’s not technically required.

Overall, this gives you a way to define constant values that are effectively global and can be used any place. Even in those places where a const variable won’t work, e.g. in switch cases and fixed array lengths.

That said, the debate rages online whether a typed const variable is better than #define macro in the general case.

It can also be used to replace or modify keywords, a concept completely foreign to const, though this practice should be used sparingly.

19.3 Conditional Compilation

It’s possible to get the preprocessor to decide whether or not to present certain blocks of code to the compiler, or just remove them entirely before compilation.

We do that by basically wrapping up the code in conditional blocks, similar to if-else statements.

19.3.1 If Defined, #ifdef and #endif

First of all, let’s try to compile specific code depending on whether or not a macro is even defined.

#include <stdio.h>

#define EXTRA_HAPPY

int main(void)
{

#ifdef EXTRA_HAPPY
    printf("I'm extra happy!\n");
#endif

    printf("OK!\n");
}

In that example, we define EXTRA_HAPPY (to be nothing, but it is defined), then on line 8 we check to see if it is defined with an #ifdef directive. If it is defined, the subsequent code will be included up until the #endif.

So because it is defined, the code will be included for compilation and the output will be:

    //#define EXTRA_HAPPY

then it wouldn’t be defined, and the code wouldn’t be included in compilation. And the output would just be:

It’s important to remember that these decisions happen at compile time! The code actually get compiled or removed depending on the condition. This is in contrast to a standard if statement that gets evaluated while the program is running.

19.3.2 If Not Defined, #ifndef

There’s also the negative sense of “if defined”: “if not defined”, or #ifndef. We could change the previous example to read to output different things based on whether or not something was defined:

#ifdef EXTRA_HAPPY
    printf("I'm extra happy!\n");
#endif

#ifndef EXTRA_HAPPY
    printf("I'm just regular\n");
#endif

Tying it all back in to header files, we’ve seen how we can cause header files to only be included one time by wrapping them in preprocessor directives like this:

    #ifndef MYHEADER_H  // First line of myheader.h
    #define MYHEADER_H
    
    int x = 12;
    
    #endif  // Last line of myheader.h

This demonstrates how a macro persists across files and multiple #includes. If it’s not yet defined, let’s define it and compile the whole header file.

But the next time it’s included, we see that MYHEADER_H is defined, so we don’t send the header file to the compiler—it gets effectively removed.

19.3.3 #else

But that’s not all we can do! There’s also an #else that we can throw in the mix.

#ifdef EXTRA_HAPPY
    printf("I'm extra happy!\n");
#else
    printf("I'm just regular\n");
#endif

19.3.4 General Conditional: #if, #elif

This works very much like the #ifdef and #ifndef directives in that you can also have an #else and the whole thing wraps up with #endif.

The only difference is that the constant expression after the #if must evaluate to true (non-zero) for the code in the #if to be compiled. So instead of whether or not something is defined, we want an expression that evaluates to true.

#include <stdio.h>

#define HAPPY_FACTOR 1

int main(void)
{

#if HAPPY_FACTOR == 0
    printf("I'm not happy!\n");
#elif HAPPY_FACTOR == 1
    printf("I'm just regular\n");
#else
    printf("I'm extra happy!\n");
#endif

    printf("OK!\n");
}

Again, for the unmatched #if clauses, the compiler won’t even see those lines. For the above code, after the preprocessor gets finished with it, all the compiler sees is:

#include <stdio.h>

int main(void)
{

    printf("I'm just regular\n");

    printf("OK!\n");
}

One hackish thing this is used for is to comment out large numbers of lines quickly¹⁰⁶.

If you put an #if 0 (“if false”) at the front of the block to be commented out and an #endif at the end, you can get this effect:

    #if 0
        printf("All this code"); /* is effectively */
        printf("commented out"); // by the #if 0
    #endif

You might have noticed that there’s no #elifdef or #elifndef directives. How can we get the same effect with #if? That is, what if I wanted this:

    #ifdef FOO
        x = 2;
    #elifdef BAR  // ERROR: Not supported by standard C
        x = 3;
    #endif

Turns out there’s a preprocessor operator called defined that we can use with an #if statement.

    #ifdef FOO
    #if defined FOO
    #if defined(FOO)   // Parentheses optional

    #ifndef FOO
    #if !defined FOO
    #if !defined(FOO)   // Parentheses optional

Notice how we can use the standard logical NOT operator (!) for “not defined”.

    #ifdef FOO
        x = 2;
    #elifdef BAR  // ERROR: Not supported by standard C
        x = 3;
    #endif

    #if defined FOO
        x = 2;
    #elif defined BAR
        x = 3;
    #endif

19.3.5 Losing a Macro: #undef

If you’ve defined something but you don’t need it any longer, you can undefine it with #undef.

#include <stdio.h>

int main(void)
{
#define GOATS

#ifdef GOATS
    printf("Goats detected!\n");  // prints
#endif

#undef GOATS  // Make GOATS no longer defined

#ifdef GOATS
    printf("Goats detected, again!\n"); // doesn't print
#endif
}

19.4 Built-in Macros

The standard defines a lot of built-in macros that you can test and use for conditional compilation. Let’s look at those here.

19.4.1 Mandatory Macros

Macro	Description
`__DATE__`	The date of compilation—like when you’re compiling this file—in `Mmm dd yyyy` format
`__TIME__`	The time of compilation in `hh:mm:ss` format
`__FILE__`	A string containing this file’s name
`__LINE__`	The line number of the file this macro appears on
`__func__`	The name of the function this appears in, as a string¹⁰⁷
`__STDC__`	Defined with `1` if this is a standard C compiler
`__STDC_HOSTED__`	This will be `1` if the compiler is a hosted implementation¹⁰⁸, otherwise `0`
`__STDC_VERSION__`	This version of C, a constant `long int` in the form `yyyymmL`, e.g. `201710L`

#include <stdio.h>

int main(void)
{
    printf("This function: %s\n", __func__);
    printf("This file: %s\n", __FILE__);
    printf("This line: %d\n", __LINE__);
    printf("Compiled on: %s %s\n", __DATE__, __TIME__);
    printf("C Version: %ld\n", __STDC_VERSION__);
}

__FILE__, __func__ and __LINE__ are particularly useful to report error conditions in messages to developers. The assert() macro in <assert.h> uses these to call out where in the code the assertion failed.

19.4.2 Optional Macros

Macro	Description
`__STDC_ISO_10646__`	If defined, `wchar_t` holds Unicode values, otherwise something else
`__STDC_MB_MIGHT_NEQ_WC__`	A `1` indicates that the values in multibyte characters might not map equally to values in wide characters
`__STDC_UTF_16__`	A `1` indicates that the system uses UTF-16 encoding in type `char16_t`
`__STDC_UTF_32__`	A `1` indicates that the system uses UTF-32 encoding in type `char32_t`
`__STDC_ANALYZABLE__`	A `1` indicates the code is analyzable¹⁰⁹
`__STDC_IEC_559__`	`1` if IEEE-754 (aka IEC 60559) floating point is supported
`__STDC_IEC_559_COMPLEX__`	`1` if IEC 60559 complex floating point is supported
`__STDC_LIB_EXT1__`	`1` if this implementation supports a variety of “safe” alternate standard library functions (they have `_s` suffixes on the name)
`__STDC_NO_ATOMICS__`	`1` if this implementation does not support `_Atomic` or `<stdatomic.h>`
`__STDC_NO_COMPLEX__`	`1` if this implementation does not support complex types or `<complex.h>`
`__STDC_NO_THREADS__`	`1` if this implementation does not support `<threads.h>`
`__STDC_NO_VLA__`	`1` if this implementation does not support variable-length arrays

19.5 Macros with Arguments

Macros are more powerful than simple substitution, though. You can set them up to take arguments that are substituted in, as well.

A question often arises for when to use parameterized macros versus functions. Short answer: use functions. But you’ll see lots of macros in the wild and in the standard library. People tend to use them for short, mathy things, and also for features that might change from platform to platform. You can define different keywords for one platform or another.

19.5.1 Macros with One Argument

#include <stdio.h>

#define SQR(x) x * x  // Not quite right, but bear with me

int main(void)
{
    printf("%d\n", SQR(12));  // 144
}

What that’s saying is “everywhere you see SQR with some value, replace it with that value times itself”.

    printf("%d\n", 12 * 12);  // 144

Let’s check it out. What if we wanted to compute SQR(3 + 4)? Well, $3+4=7$, so we must want to compute $7^2=49$. That’s it; 49—final answer.

    printf("%d\n", SQR(3 + 4));  // 19!!??

    printf("%d\n", 3 + 4 * 3 + 4);  // 19!

Oops! Since multiplication takes precedence, we do the $4\times3=12$ first, and get $3+12+4=19$. Not what we were after.

This is so common that you should automatically do it every time you make a parameterized math macro!

#define SQR(x) (x) * (x)   // Better... but still not quite good enough!

    printf("%d\n", (3 + 4) * (3 + 4));  // 49! Woo hoo!

But we actually still have the same problem which might manifest if we have a higher-precedence operator than multiply (*) nearby.

So the safe, proper way to put the macro together is to wrap the whole thing in additional parentheses, like so:

#define SQR(x) ((x) * (x))   // Good!

Just make it a habit to do that when you make a math macro and you can’t go wrong.

19.5.2 Macros with More than One Argument

    #define TRIANGLE_AREA(w, h) (0.5 * (w) * (h))

Let’s do some macros that solve for $x$ using the quadratic formula. Just in case you don’t have it on the top of your head, it says for equations of the form:

Which is crazy. Also notice the plus-or-minus ($\pm$) in there, indicating that there are actually two solutions.

    #define QUADP(a, b, c) ((-(b) + sqrt((b) * (b) - 4 * (a) * (c))) / (2 * (a)))
    #define QUADM(a, b, c) ((-(b) - sqrt((b) * (b) - 4 * (a) * (c))) / (2 * (a)))

So that gets us some math. But let’s define one more that we can use as arguments to printf() to print both answers.

    //          macro              replacement
    //      |-----------| |----------------------------|
    #define QUAD(a, b, c) QUADP(a, b, c), QUADM(a, b, c)

That’s just a couple values separated by a comma—and we can use that as a “combined” argument of sorts to printf() like this:

    printf("x = %f or x = %f\n", QUAD(2, 10, 5));

#include <stdio.h>
#include <math.h>  // For sqrt()

#define QUADP(a, b, c) ((-(b) + sqrt((b) * (b) - 4 * (a) * (c))) / (2 * (a)))
#define QUADM(a, b, c) ((-(b) - sqrt((b) * (b) - 4 * (a) * (c))) / (2 * (a)))
#define QUAD(a, b, c) QUADP(a, b, c), QUADM(a, b, c)

int main(void)
{
    printf("2*x^2 + 10*x + 5 = 0\n");
    printf("x = %f or x = %f\n", QUAD(2, 10, 5));
}

Plugging in either of those values gives us roughly zero (a bit off because the numbers aren’t exact):

19.5.3 Macros with Variable Arguments

There’s also a way to have a variable number of arguments passed to a macro, using ellipses (...) after the known, named arguments. When the macro is expanded, all of the extra arguments will be in a comma-separated list in the __VA_ARGS__ macro, and can be replaced from there:

#include <stdio.h>

// Combine the first two arguments to a single number,
// then have a commalist of the rest of them:

#define X(a, b, ...) (10*(a) + 20*(b)), __VA_ARGS__

int main(void)
{
    printf("%d %f %s %d\n", X(5, 4, 3.14, "Hi!", 12));
}

    printf("%d %f %s %d\n", (10*(5) + 20*(4)), 3.14, "Hi!", 12);

    #define X(...) #__VA_ARGS__
    
    printf("%s\n", X(1,2,3));  // Prints "1, 2, 3"

19.5.4 Stringification

Already mentioned, just above, you can turn any argument into a string by preceding it with a # in the replacement text.

For example, we could print anything as a string with this macro and printf():

    #define STR(x) #x
    
    printf("%s\n", STR(3.14159));

    printf("%s\n", "3.14159");

Let’s see if we can use this to greater effect so that we can pass any int variable name into a macro, and have it print out it’s name and value.

#include <stdio.h>

#define PRINT_INT_VAL(x) printf("%s = %d\n", #x, x)

int main(void)
{
    int a = 5;

    PRINT_INT_VAL(a);  // prints "a = 5"
}

    printf("%s = %d\n", "a", 5);

19.5.5 Concatenation

    #define CAT(a, b) a ## b
    
    printf("%f\n", CAT(3.14, 1592));   // 3.141592

19.6 Multiline Macros

It’s possible to continue a macro to multiple lines if you escape the newline with a backslash (\).

Let’s write a multiline macro that prints numbers from 0 to the product of the two arguments passed in.

#include <stdio.h>

#define PRINT_NUMS_TO_PRODUCT(a, b) { \
    int product = (a) * (b); \
    for (int i = 0; i < product; i++) { \
        printf("%d\n", i); \
    } \
}

int main(void)
{
    PRINT_NUMS_TO_PRODUCT(2, 4);  // Outputs numbers from 0 to 7
}

19.7 Example: An Assert Macro

Adding asserts to your code is a good way to catch conditions that you think shouldn’t happen. C provides assert() functionality. It checks a condition, and if it’s false, the program bombs out telling you the file and line number on which the assertion failed.

    ASSERT(x < 20, "x must be under 20");

I want something like this to happen (assuming the ASSERT() is on line 220 of foo.c):

    if (x < 20) {
        fprintf(stderr, "foo.c:220: assertion x < 20 failed: ");
        fprintf(stderr, "x must be under 20\n");
        exit(1)
    }

We can get the filename out of the __FILE__ macro, and the line number from __LINE__. The message is already a string, but x < 20 is not, so we’ll have to stringify it with #. We can make a multiline macro by using backslash escapes at the end of the line.

    #define ASSERT(c, m) \
    { \
        if (!(c)) { \
            fprintf(stderr, __FILE__ ":%d: assertion %s failed: %s\n", \
                            __LINE__, #c, m); \
            exit(1); \
        } \
    }

(It looks a little weird with __FILE__ out front like that, but remember it is a string literal, and string literals next to each other are automagically concatenated. __LINE__ on the other hand, it’s just an int.)

    int x = 30;
    
    ASSERT(x < 20, "x must be under 20");

The only thing left is a way to turn it on and off, and we could do that with conditional compilation.

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

#define ASSERT_ENABLED 1

#if ASSERT_ENABLED
#define ASSERT(c, m) \
{ \
    if (!(c)) { \
        fprintf(stderr, __FILE__ ":%d: assertion %s failed: %s\n", \
                        __LINE__, #c, m); \
        exit(1); \
    } \
}
#else
#define ASSERT(c, m)  // Empty macro if not enabled
#endif

int main(void)
{
    int x = 30;

    ASSERT(x < 20, "x must be under 20");
}

19.8 The #error Directive

Commonly, this is used inside a conditional to prevent compilation unless some prerequisites are met:

    #ifndef __STDC_IEC_559__
        #error I really need IEEE-754 floating point to compile. Sorry!
    #endif

Some compilers have a non-standard complementary #warning directive that will output a warning but not stop compilation, but this is not in the C11 spec.

19.9 The #pragma Directive

This is one funky directive, short for “pragmatic”. You can use it to do… well, anything your compiler supports you doing with it.

Basically the only time you’re going to add this to your code is if some documentation tells you to do so.

19.9.1 Non-Standard Pragmas

Here’s one non-standard example of using #pragma to cause the compiler to execute a for loop in parallel with multiple threads (if the compiler supports the OpenMP ¹¹⁰ extension):

    #pragma omp parallel for
    for (int i = 0; i < 10; i++) { ... }

There are all kinds of #pragma directives documented across all four corners of the globe.

19.9.2 Standard Pragmas

There are also a few standard ones, and these start with STDC, and follow the same form:

    #pragma STDC pragma_name on-off

Pragma Name	Description
`FP_CONTRACT`	Allow floating point expressions to be contracted into a single operation to avoid rounding errors that might occur from multiple operations.
`FENV_ACCESS`	Set to `ON` if you plan to access the floating point status flags. If `OFF`, the compiler might perform optimizations that cause the values in the flags to be inconsistent or invalid.
`CX_LIMITED_RANGE`	Set to `ON` to allow the compiler to skip overflow checks when performing complex arithmetic. Defaults to `OFF`.

    #pragma STDC FP_CONTRACT OFF
    #pragma STDC CX_LIMITED_RANGE ON

19.9.3 _Pragma Operator

    #pragma "Unnecessary" quotes
    _Pragma("\"Unnecessary\" quotes")

    #define PRAGMA(x) _Pragma(#x)

19.10 The #line Directive

This allows you to override the values for __LINE__ and __FILE__. If you want.

    #line 300 "newfilename"

19.11 The Null Directive

A # on a line by itself is ignored by the preprocessor. Now, to be entirely honest, I don’t know what the use case is for this.

    #ifdef FOO
        #
    #else
        printf("Something");
    #endif

which is just cosmetic; the line with the solitary # can be deleted with no ill effect.

    #
    #ifdef FOO
        x = 2;
    #endif
    #
    #if BAR == 17
        x = 12;
    #endif
    #

Another post mentions elimination of comments—that in GCC, a comment after a # will not be seen by the compiler. Which I don’t doubt, but the specification doesn’t seem to say this is standard behavior.

My searches for rationale aren’t bearing much fruit. So I’m going to just say this is some good ol’ fashioned C esoterica.

20 structs II: More Fun with structs

Turns out there’s a lot more you can do with structs than we’ve talked about, but it’s just a big pile of miscellaneous things. So we’ll throw them in this chapter.

20.1 Anonymous structs

These are “the struct with no name”. We also mention these in the typedef section, but we’ll refresh here.

    struct animal {
        char *name;
        int leg_count, speed;
    };

    struct {              // <-- No name!
        char *name;
        int leg_count, speed;
    };

Okaaaaay. So we have a struct, but it has no name, so we have no way of using it later? Seems pretty pointless.

Admittedly, in that example, it is. But we can still make use of it a couple ways.

One is rare, but since the anonymous struct represents a type, we can just put some variable names after it and use them.

    struct {                   // <-- No name!
        char *name;
        int leg_count, speed;
    } a, b, c;                 // 3 variables of this struct type
    
    a.name = "antelope";
    c.leg_count = 4;           // for example

Far more common is use of anonymous structs with a typedef so that we can use it later (e.g. to pass variables to functions).

    typedef struct {                   // <-- No name!
        char *name;
        int leg_count, speed;
    } animal;                          // New type: animal
    
    animal a, b, c;
    
    a.name = "antelope";
    c.leg_count = 4;           // for example

Personally, I don’t use many anonymous structs. I think it’s more pleasant to see the entire struct animal before the variable name in a declaration.

20.2 Self-Referential structs

For any graph-like data structure, it’s useful to be able to have pointers to the connected nodes/vertices. But this means that in the definition of a node, you need to have a pointer to a node. It’s chicken and eggy!

    struct node {
        int data;
        struct node *next;
    };

It’s important to note that next is a pointer. This is what allows the whole thing to even build. Even though the compiler doesn’t know what the entire struct node looks like yet, all pointers are the same size.

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

struct node {
    int data;
    struct node *next;
};

int main(void)
{
    struct node *head;

    // Hackishly set up a linked list (11)->(22)->(33)
    head = malloc(sizeof(struct node));
    head->data = 11;
    head->next = malloc(sizeof(struct node));
    head->next->data = 22;
    head->next->next = malloc(sizeof(struct node));
    head->next->next->data = 33;
    head->next->next->next = NULL;

    // Traverse it
    for (struct node *cur = head; cur != NULL; cur = cur->next) {
        printf("%d\n", cur->data);
    }
}

20.3 Flexible Array Members

Back in the good old days, when people carved C code out of wood, some folks thought would be neat if they could allocate structs that had variable length arrays at the end of them.

I want to be clear that the first part of the section is the old way of doing things, and we’re going to do things the new way after that.

For example, maybe you could define a struct for holding strings and the length of that string. It would have a length and an array to hold the data. Maybe something like this:

    struct len_string {
        int length;
        char data[8];
    };

But that has 8 hardcoded as the maximum length of a string, and that’s not much. What if we did something clever and just malloc()d some extra space at the end after the struct, and then let the data overflow into that space?

    struct len_string *s = malloc(sizeof *s + 40);

Because data is the last field of the struct, if we overflow that field, it runs out into space that we already allocated! For this reason, this trick only works if the short array is the last field in the struct.

    // Copy more than 8 bytes!
    
    strcpy(s->data, "Hello, world!");  // Won't crash. Probably.

In fact, there was a common compiler workaround for doing this, where you’d allocate a zero length array at the end:

    struct len_string {
        int length;
        char data[0];
    };

Because data is the last field of the struct, if we overflow that field, it runs out into space that we already allocated!

    // Copy more than 8 bytes!
    
    strcpy(s->data, "Hello, world!");  // Won't crash. Probably.

But, of course, actually accessing the data beyond the end of that array is undefined behavior! In these modern times, we no longer deign to resort to such savagery.

Luckily for us, we can still get the same effect with C99 and later, but now it’s legal.

    struct len_string {
        int length;
        char data[];
    };

Again, this only works if the flexible array member is the last field in the struct.

And then we can allocate all the space we want for those strings by malloc()ing larger than the struct len_string, as we do in this example that makes a new struct len_string from a C string:

    struct len_string *len_string_from_c_string(char *s)
    {
        int len = strlen(s);
    
        // Allocate "len" more bytes than we'd normally need
        struct len_string *ls = malloc(sizeof *ls + len);
    
        ls->length = len;
    
        // Copy the string into those extra bytes
        memcpy(ls->data, s, len);
    
        return ls;
    }

20.4 Padding Bytes

Beware that C is allowed to add padding bytes within or after a struct as it sees fit. You can’t trust that they will be directly adjacent in memory¹¹².

Let’s take a look at this program. We output two numbers. One is the sum of the sizeofs the individual field types. The other is the sizeof the entire struct.

One would expect them to be the same. The size of the total is the size of the sum of its parts, right?

#include <stdio.h>

struct foo {
    int a;
    char b;
    int c;
    char d;
};

int main(void)
{
    printf("%zu\n", sizeof(int) + sizeof(char) + sizeof(int) + sizeof(char));
    printf("%zu\n", sizeof(struct foo));
}

They’re not the same! The compiler has added 6 bytes of padding to help it be more performant. Maybe you got different output with your compiler, but unless you’re forcing it, you can’t be sure there’s no padding.

20.5 offsetof

In the previous section, we saw that the compiler could inject padding bytes at will inside a structure.

What if we needed to know where those were? We can measure it with offsetof, defined in <stddef.h>.

Let’s modify the code from above to print the offsets of the individual fields in the struct:

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

struct foo {
    int a;
    char b;
    int c;
    char d;
};

int main(void)
{
    printf("%zu\n", offsetof(struct foo, a));
    printf("%zu\n", offsetof(struct foo, b));
    printf("%zu\n", offsetof(struct foo, c));
    printf("%zu\n", offsetof(struct foo, d));
}

indicating that we’re using 4 bytes for each of the fields. It’s a little weird, because char is only 1 byte, right? The compiler is putting 3 padding bytes after each char so that all the fields are 4 bytes long. Presumably this will run faster on my CPU.

20.6 Fake OOP

There’s a slightly abusive thing that’s sort of OOP-like that you can do with structs.

Since the pointer to the struct is the same as a pointer to the first element of the struct, you can freely cast a pointer to the struct to a pointer to the first element.

    struct parent {
        int a, b;
    };
    
    struct child {
        struct parent super;  // MUST be first
        int c, d;
    };

Then we are able to pass a pointer to a struct child to a function that expects either that or a pointer to a struct parent!

Because struct parent super is the first item in the struct child, a pointer to any struct child is the same as a pointer to that super field¹¹³.

Let’s set up an example here. We’ll make structs as above, but then we’ll pass a pointer to a struct child into a function that needs a pointer to a struct parent… and it’ll still work.

#include <stdio.h>

struct parent {
    int a, b;
};

struct child {
    struct parent super;  // MUST be first
    int c, d;
};

// Making the argument `void*` so we can pass any type into it
// (namely a struct parent or struct child)
void print_parent(void *p)
{
    // Expects a struct parent--but a struct child will also work
    // because the pointer points to the struct parent in the first
    // field:
    struct parent *self = p;

    printf("Parent: %d, %d\n", self->a, self->b);
}

void print_child(struct child *self)
{
    printf("Child: %d, %d\n", self->c, self->d);
}

int main(void)
{
    struct child c = {.super.a=1, .super.b=2, .c=3, .d=4};

    print_child(&c);
    print_parent(&c);  // Also works even though it's a struct child!
}

See what we did on the last line of main()? We called print_parent() but passed a struct child* as the argument! Even though print_parent() needs the argument to point to a struct parent, we’re getting away with it because the first field in the struct child is a struct parent.

Again, this works because a pointer to a struct has the same value as a pointer to the first field in that struct.

20.7 Bit-Fields

In my experience, these are rarely used, but you might see them out there from time to time, especially in lower-level applications that pack bits together into larger spaces.

#include <stdio.h>

struct foo {
    unsigned int a;
    unsigned int b;
    unsigned int c;
    unsigned int d;
};

int main(void)
{
    printf("%zu\n", sizeof(struct foo));
}

For me, this prints 16. Which makes sense, since unsigneds are 4 bytes on my system.

But what if we knew that all the values that were going to be stored in a and b could be stored in 5 bits, and the values in c, and d could be stored in 3 bits? That’s only a total 16 bits. Why have 128 bits reserved for them if we’re only going to use 16?

Well, we can tell C to pretty-please try to pack these values in. We can specify the maximum number of bits that values can take (from 1 up the size of the containing type).

We do this by putting a colon after the field name, followed by the field width in bits.

struct foo {
    unsigned int a:5;
    unsigned int b:5;
    unsigned int c:3;
    unsigned int d:3;
};

Now when I ask C how big my struct foo is, it tells me 4! It was 16 bytes, but now it’s only 4. It has “packed” those 4 values down into 4 bytes, which is a four-fold memory savings.

The tradeoff is, of course, that the 5-bit fields can only hold values from 0-31 and the 3-bit fields can only hold values from 0-7. But life’s all about compromise, after all.

20.7.1 Non-Adjacent Bit-Fields

A gotcha: C will only combine adjacent bit-fields. If they’re interrupted by non-bit-fields, you get no savings:

    struct foo {            // sizeof(struct foo) == 16 (for me)
        unsigned int a:1;   // since a is not adjacent to c.
        unsigned int b;
        unsigned int c:1;
        unsigned int d;
    };

In that example, since a is not adjacent to c, they are both “packed” in their own ints.

So we have one int each for a, b, c, and d. Since my ints are 4 bytes, that’s a grand total of 16 bytes.

A quick rearrangement yields some space savings from 16 bytes down to 12 bytes (on my system):

    struct foo {            // sizeof(struct foo) == 12 (for me)
        unsigned int a:1;
        unsigned int c:1;
        unsigned int b;
        unsigned int d;
    };

And now, since a is next to c, the compiler puts them together into a single int.

So we have one int for a combined a and c, and one int each for b and d. For a grand total of 3 ints, or 12 bytes.

20.7.2 Signed or Unsigned ints

If you just declare a bit-field to be int, the different compilers will treat it as signed or unsigned. Just like the situation with char.

20.7.3 Unnamed Bit-Fields

In some specific circumstances, you might need to reserve some bits for hardware reasons, but not need to use them in code.

For example, let’s say you have a byte where the top 2 bits have a meaning, the bottom 1 bit has a meaning, but the middle 5 bits do not get used by you¹¹⁴.

    struct foo {
        unsigned char a:2;
        unsigned char dummy:5;
        unsigned char b:1;
    };

And that works—in our code we use a and b, but never dummy. It’s just there to eat up 5 bits to make sure a and b are in the “required” (by this contrived example) positions within the byte.

C allows us a way to clean this up: unnamed bit-fields. You can just leave the name (dummy) out in this case, and C is perfectly happy for the same effect:

    struct foo {
        unsigned char a:2;
        unsigned char :5;   // <-- unnamed bit-field!
        unsigned char b:1;
    };

20.7.4 Zero-Width Unnamed Bit-Fields

Some more esoterica out here… Let’s say you were packing bits into an unsigned int, and you needed some adjacent bit-fields to pack into the next unsigned int.

    struct foo {
        unsigned int a:1;
        unsigned int b:2;
        unsigned int c:3;
        unsigned int d:4;
    };

the compiler packs all those into a single unsigned int. But what if you needed a and b in one int, and c and d in a different one?

There’s a solution for that: put an unnamed bit-field of width 0 where you want the compiler to start anew with packing bits in a different int:

    struct foo {
        unsigned int a:1;
        unsigned int b:2;
        unsigned int :0;   // <--Zero-width unnamed bit-field
        unsigned int c:3;
        unsigned int d:4;
    };

It’s analogous to an explicit page break in a word processor. You’re telling the compiler, “Stop packing bits in this unsigned, and start packing them in the next one.”

By adding the zero-width unnamed bit field in that spot, the compiler puts a and b in one unsigned int, and c and d in another unsigned int. Two total, for a size of 8 bytes on my system (unsigned ints are 4 bytes each).

20.8 Unions

These are basically just like structs, except the fields overlap in memory. The union will be only large enough for the largest field, and you can only use one field at a time.

You declare them just like structs, except it’s union. Take a look at this:

    union foo {
        int a, b, c, d, e, f;
        float g, h;
        char i, j, k, l;
    };

Now, that’s a lot of fields. If this were a struct, my system would tell me it took 36 bytes to hold it all.

But it’s a union, so all those fields overlap in the same stretch of memory. The biggest one is int (or float), taking up 4 bytes on my system. And, indeed, if I ask for the sizeof the union foo, it tells me 4!

The tradeoff is that you can only portably use one of those fields at a time. If you try to read from a field that was not the last one written to, the behavior is unspecified.

Let’s take that crazy union and first store an int in it, then a float. Then we’ll print out the int again to see what’s in there—even though, since it wasn’t the last value we stored, the result is unspecified.

#include <stdio.h>

union foo {
    int a, b, c, d, e, f;
    float g, h;
    char i, j, k, l;
};

int main(void)
{
    union foo x;

    x.a = 12;
    printf("%d\n", x.a);  // OK--x.a was the last thing we stored into

    x.g = 3.141592;
    printf("%f\n", x.g);  // OK--x.g was the last thing we stored into

    printf("%d\n", x.a);  // Unspecified behavior!
}

Probably deep down the decimal value 1078530008 is probably the same pattern of bits as 3.141592, but the spec makes no guarantees about this.

20.8.1 Pointers to unions

If you have a pointer to a union, you can cast that pointer to any of the types of the fields in that union and get the values out that way.

In this example, we see that the union has ints and floats in it. And we get pointers to the union, but we cast them to int* and float* types (the cast silences compiler warnings). And then if we dereference those, we see that they have the values we stored directly in the union.

#include <stdio.h>

union foo {
    int a, b, c, d, e, f;
    float g, h;
    char i, j, k, l;
};

int main(void)
{
    union foo x;

    int *foo_int_p = (int *)&x;
    float *foo_float_p = (float *)&x;

    x.a = 12;
    printf("%d\n", x.a);           // 12
    printf("%d\n", *foo_int_p);    // 12, again

    x.g = 3.141592;
    printf("%f\n", x.g);           // 3.141592
    printf("%f\n", *foo_float_p);  // 3.141592, again
}

The reverse is also true. If we have a pointer to a type inside the union, we can cast that to a pointer to the union and access its members.

    union foo x;
    int *foo_int_p = (int *)&x;             // Pointer to int field
    union foo *p = (union foo *)foo_int_p;  // Back to pointer to union
    
    p->a = 12;  // This line the same as...
    x.a = 12;   // this one.

All this just lets you know that, under the hood, all these values in a union start at the same place in memory, and that’s the same as where the entire union is.

21 Characters and Strings II

We’ve talked about how char types are actually just small integer types… but it’s the same for a character in single quotes.

Turns out there are few more types of strings and characters, and it leads down one of the most infamous rabbit holes in the language: the whole multibyte/wide/Unicode/localization thingy.

21.1 Escape Sequences

We’re used to strings and characters with regular letters, punctuation, and numbers:

    char *s = "Hello!";
    char t = 'c';

But what if we want some special characters in there that we can’t type on the keyboard because they don’t exist (e.g. “€”), or even if we want a character that’s a single quote? We clearly can’t do this:

To do these things, we use something called escape sequences. These are the backslash character (\) followed by another character. The two (or more) characters together have special meaning.

For our single quote character example, we can put an escape (that is, \) in front of the central single quote to solve it:

Now C knows that \' means just a regular quote we want to print, not the end of the character sequence.

You can say either “backslash” or “escape” in this context (“escape that quote”) and C devs will know what you’re talking about. Also, “escape” in this context is different than your Esc key or the ASCII ESC code.

21.1.1 Frequently-used Escapes

In my humble opinion, these escape characters make up 99.2%¹¹⁵ of all escapes.

Code	Description
`\n`	Newline character—when printing, continue subsequent output on the next line
`\'`	Single quote—used for a single quote character constant
`\"`	Double quote—used for a double quote in a string literal
`\\`	Backslash—used for a literal `\` in a string or character

    printf("Use \\n for newline\n");  // Use \n for newline
    printf("Say \"hello\"!\n");       // Say "hello"!
    printf("%c\n", '\'');             // '

21.1.2 Rarely-used Escapes

Code	Description
`\a`	Alert. This makes the terminal make a sound or flash, or both!
`\b`	Backspace. Moves the cursor back a character. Doesn’t delete the character.
`\f`	Formfeed. This moves to the next “page”, but that doesn’t have much modern meaning. On my system, this behaves like `\v`.
`\r`	Return. Move to the beginning of the same line.
`\t`	Horizontal tab. Moves to the next horizontal tab stop. On my machine, this lines up on columns that are multiples of 8, but YMMV.
`\v`	Vertical tab. Moves to the next vertical tab stop. On my machine, this moves to the same column on the next line.
`\?`	Literal question mark. Sometimes you need this to avoid trigraphs, as shown below.

21.1.2.1 Single Line Status Updates

A use case for \b or \r is to show status updates that appear on the same line on the screen and don’t cause the display to scroll. Here’s an example that does a countdown from 10. (Note this makes use of the non-standard POSIX function sleep() from <unistd.h>—if you’re not on a Unix-like, search for your platform and sleep for the equivalent.)

#include <stdio.h>
#include <unistd.h>  // Non-standard Unix-likes only for sleep()

int main(void)
{
    for (int i = 10; i >= 0; i--) {
        printf("\rT minus %d second%s... \b", i, i != 1? "s": "");

        fflush(stdout);  // Force output to update

        sleep(1);        // Delay 1 second
    }

    printf("\rLiftoff!             \n");
}

Quite a few things are happening on line 7. First of all, we lead with a \r to get us to the beginning of the current line, then we overwrite whatever’s there with the current countdown. (There’s ternary operator out there to make sure we print 1 second instead of 1 seconds.)

Also, there’s a space after the ... That’s so that we properly overwrite the last . when i drops from 10 to 9 and we get a column narrower. Try it without the space to see what I mean.

And we wrap it up with a \b to back up over that space so the cursor sits at the exact end of the line in an aesthetically-pleasing way.

Note that line 14 also has a lot of spaces at the end to overwrite the characters that were already there from the countdown.

Finally, we have a weird fflush(stdout) in there, whatever that means. Short answer is that most terminals are line buffered by default, meaning they don’t actually display anything until a newline character is encountered. Since we don’t have a newline (we just have \r), without this line, the program would just sit there until Liftoff! and then print everything all in one instant. fflush() overrides this behavior and forces output to happen right now.

21.1.2.2 The Question Mark Escape

    printf("Doesn't it?\n");

    printf("Doesn't it\?\n");   // Note \?

    printf("Doesn't it??!\n");

I’m sure we’ll revisit this dusty corner of the language later, but the short of it is the compiler looks for certain triplets of characters starting with ?? and it substitutes other characters in their place. So if you’re on some ancient terminal without a pipe symbol (|) on the keyboard, you can type ??! instead.

    printf("Doesn't it?\?!\n");

These days, of course, no one ever uses trigraphs. But that whole ??! does sometimes appear if you decide to use it in a string for emphasis.

21.1.3 Numeric Escapes

In addition, there are ways to specify numeric constants or other character values inside strings or character constants.

If you know an octal or hexadecimal representation of a byte, you can include that in a string or character constant.

The following table has example numbers, but any hex or octal numbers may be used. Pad with leading zeros if necessary to read the proper digit count.

Code	Description
`\123`	Embed the byte with octal value `123`, 3 digits exactly.
`\x4D`	Embed the byte with hex value `4D`, 2 digits.
`\u2620`	Embed the Unicode character at code point with hex value `2620`, 4 digits.
`\U0001243F`	Embed the Unicode character at code point with hex value `1243F`, 8 digits.

Here’s an example of the less-commonly used octal notation to represent the letter B in between A and C. Normally this would be used for some kind of special unprintable character, but we have other ways to do that, below, and this is just an octal demo:

    printf("A\102C\n");  // 102 is `B` in ASCII/UTF-8

Note there’s no leading zero on the octal number when you include it this way. But it does need to be three characters, so pad with leading zeros if you need to.

But far more common is to use hex constants these days. Here’s a demo that you shouldn’t use, but it demos embedding the UTF-8 bytes 0xE2, 0x80, and 0xA2 in a string, which corresponds to the Unicode “bullet” character (•).

    printf("\xE2\x80\xA2 Bullet 1\n");
    printf("\xE2\x80\xA2 Bullet 2\n");
    printf("\xE2\x80\xA2 Bullet 3\n");

Produces the following output if you’re on a UTF-8 console (or probably garbage if you’re not):

But that’s a crummy way to do Unicode. You can use the escapes \u (16-bit) or \U (32-bit) to just refer to Unicode by code point number. The bullet is 2022 (hex) in Unicode, so you can do this and get more portable results:

    printf("\u2022 Bullet 1\n");
    printf("\u2022 Bullet 2\n");
    printf("\u2022 Bullet 3\n");

Be sure to pad \u with enough leading zeros to get to four characters, and \U with enough to get to eight.

    printf("\U00002022 Bullet 1\n");

22 Enumerated Types: enum

    enum {
      ONE=1,
      TWO=2
    };
    
    printf("%d %d", ONE, TWO);  // 1 2

In some ways, it can be better—or different—than using a #define. Key differences:

Since they’re integer types, they can be used any place integers can be used, including in array dimensions and case statements.

22.1 Behavior of enum

22.1.1 Numbering

    enum {
        SHEEP,  // Value is 0
        WHEAT,  // Value is 1
        WOOD,   // Value is 2
        BRICK,  // Value is 3
        ORE     // Value is 4
    };
    
    printf("%d %d\n", SHEEP, BRICK);  // 0 2

    enum {
      X=2,
      Y=18,
      Z=-2
    };

    enum {
      X=2,
      Y=2,
      Z=2
    };

if values are omitted, numbering continues counting in the positive direction from whichever value was last specified. For example:

    enum {
      A,    // 0, default starting value
      B,    // 1
      C=4,  // 4, manually set
      D,    // 5
      E,    // 6
      F=3   // 3, manually set
      G,    // 4
      H     // 5
    }

22.1.2 Trailing Commas

    enum {
      X=2,
      Y=18,
      Z=-2,   // <-- Trailing comma
    };

It’s gotten more popular in languages of the recent decades so you might be pleased to see it.

22.1.3 Scope

enums scope as you’d expect. If at file scope, the whole file can see it. If in a block, it’s local to that block.

It’s really common for enums to be defined in header files so they can be #included at file scope.

22.1.4 Style

As you’ve noticed, it’s common to declare the enum symbols in uppercase (with underscores).

22.2 Your enum is a Type

This is an important thing to know about enum: they’re a type, analogous to how a struct is a type.

You can give them a tag name so you can refer to the type later and declare variables of that type.

In C, the best reason for this is code clarity–it’s a nice, typed way to describe your thinking in code. C (unlike C++) doesn’t actually enforce any values being in range for a particular enum.

Let’s do an example where we declare a variable r of type enum resource that can hold those values:

    // Named enum, type is "enum resource"
    
    enum resource {
        SHEEP,
        WHEAT,
        WOOD,
        BRICK,
        ORE
    };
    
    // Declare a variable "r" of type "enum resource"
    
    enum resource r = BRICK;
    
    if (r == BRICK) {
        printf("I'll trade you a brick for two sheep.\n");
    }

    typedef enum {
        SHEEP,
        WHEAT,
        WOOD,
        BRICK,
        ORE
    } RESOURCE;
    
    RESOURCE r = BRICK;

Another shortcut that’s legal but rare is to declare variables when you declare the enum:

    // Declare an enum and some initialized variables of that type:
    
    enum {
        SHEEP,
        WHEAT,
        WOOD,
        BRICK,
        ORE
    } r = BRICK, s = WOOD;

You can also give the enum a name so you can use it later, which is probably what you want to do in most cases:

    // Declare an enum and some initialized variables of that type:
    
    enum resource {   // <-- type is now "enum resource"
        SHEEP,
        WHEAT,
        WOOD,
        BRICK,
        ORE
    } r = BRICK, s = WOOD;

23 Pointers III: Pointers to Pointers and More

Here’s where we cover some intermediate and advanced pointer usage. If you don’t have pointers down well, review the previous chapters on pointers and pointer arithmetic before starting on this stuff.

23.1 Pointers to Pointers

If you can have a pointer to a variable, and a variable can be a pointer, can you have a pointer to a variable that it itself a pointer?

Yes! This is a pointer to a pointer, and it’s held in variable of type pointer-pointer.

Before we tear into that, I want to try for a gut feel for how pointers to pointers work.

Remember that a pointer is just a number. It’s a number that represents an index in computer memory, typically one that holds a value we’re interested in for some reason.

That pointer, which is a number, has to be stored somewhere. And that place is memory, just like everything else¹¹⁶.

But because it’s stored in memory, it must have an index it’s stored at, right? The pointer must have an index in memory where it is stored. And that index is a number. It’s the address of the pointer. It’s a pointer to the pointer.

Let’s start with a regular pointer to an int, back from the earlier chapters:

#include <stdio.h>

int main(void)
{
    int x = 3490;  // Type: int
    int *p = &x;   // Type: pointer to an int

    printf("%d\n", *p);  // 3490
}

Straightforward enough, right? We have two types represented: int and int*, and we set up p to point to x. Then we can dereference p on line 8 and print out the value 3490.

But, like we said, we can have a pointer to any variable… so does that mean we can have a pointer to p?

    int x = 3490;  // Type: int
    int *p = &x;   // Type: pointer to an int
    
    &p  // <-- What type is the address of p? AKA a pointer to p?

If x is an int, then &x is a pointer to an int that we’ve stored in p which is type int*. Follow? (Repeat this paragraph until you do!)

And therefore &p is a pointer to an int*, AKA a “pointer to a pointer to an int”. AKA “int-pointer-pointer”.

#include <stdio.h>

int main(void)
{
    int x = 3490;  // Type: int
    int *p = &x;   // Type: pointer to an int
    int **q = &p;  // Type: pointer to pointer to int

    printf("%d %d\n", *p, **q);  // 3490 3490
}

Let’s make up some pretend addresses for the above values as examples and see what these three variables might look like in memory. The address values, below are just made up by me for example purposes:

Variable	Stored at Address	Value Stored There
`x`	`28350`	`3490`—the value from the code
`p`	`29122`	`28350`—the address of `x`!
`q`	`30840`	`29122`—the address of `p`!

Indeed, let’s try it for real on my computer¹¹⁷ and print out the pointer values with %p and I’ll do the same table again with actual references (printed in hex).

You can see those addresses are the same except the last byte, so just focus on those.

Variable	Stored at Address	Value Stored There
`x`	`0x7ffd96a07b94`	`3490`—the value from the code
`p`	`0x7ffd96a07b98`	`0x7ffd96a07b94`—the address of `x`!
`q`	`0x7ffd96a07ba0`	`0x7ffd96a07b98`—the address of `p`!

On my system, ints are 4 bytes, which is why we’re seeing the address go up by 4 from x to p¹¹⁸ and then goes up by 8 from p to q. On my system, all pointers are 8 bytes.

Does it matter if it’s an int* or an int**? Is one more bytes than the other? Nope! Remember that all pointers are addresses, that is indexes into memory. And on my machine you can represent an index with 8 bytes… doesn’t matter what’s stored at that index.

Now check out what we did there on line 9 of the previous example: we double dereferenced q to get back to our 3490.

So you can think of & as being used to make pointers, and * being the inverse—it goes the opposite direction of &—to get to the thing pointed to.

In terms of type, each time you &, that adds another pointer level to the type.

If you have	Then you run	The result type is
`int x`	`&x`	`int *`
`int *x`	`&x`	`int **`
`int **x`	`&x`	`int ***`
`int ***x`	`&x`	`int ****`

If you have	Then you run	The result type is
`int ****x`	`*x`	`int ***`
`int ***x`	`*x`	`int **`
`int **x`	`*x`	`int *`
`int *x`	`*x`	`int`

Note that you can use multiple *s in a row to quickly dereference, just like we saw in the example code with **q, above. Each one strips away one level of indirection.

If you have	Then you run	The result type is
`int ****x`	`***x`	`int *`
`int ***x`	`**x`	`int *`
`int **x`	`**x`	`int`

But & doesn’t work the same way—you can only do those one at a time, and have to store the result in an intermediate variable:

    int x = 3490;     // Type: int
    int *p = &x;      // Type: int *, pointer to an int
    int **q = &p;     // Type: int **, pointer to pointer to int
    int ***r = &q;    // Type: int ***, pointer to pointer to pointer to int
    int ****s = &r;   // Type: int ****, you get the idea
    int *****t = &s;  // Type: int *****

23.1.1 Pointer Pointers and const

means that you can’t modify p. Trying to p++ would give you a compile-time error.

But how does that work with int ** or int ***? Where does the const go, and what does it mean?

Let’s start with the simple bit. The const right next to the variable name refers to that variable. So if you want an int*** that you can’t change, you can do this:

    int ***const p;
    
    p++;  // Not allowed

int main(void)
{
    int x = 3490;
    int *const p = &x;
    int **q = &p;
}

That is, we’re saying that q is type int **, and if you dereference that, the rightmost * in the type goes away. So after the dereference, we have type int *.

And we’re assigning &p into it which is a pointer to an int *const, or, in other words, int *const *.

But q is int **! A type with different constness on the first *! So we get a warning that the const in p’s int *const * is being ignored and thrown away.

    int x = 3490;
    int *const p = &x;
    int *const *q = &p;

We could make q even more const. As it is, above, we’re saying, “q isn’t itself const, but the thing it points to is const.” But we could make them both const:

23.2 Multibyte Values

We kinda hinted at this in a variety of places earlier, but clearly not every value can be stored in a single byte of memory. Things take up multiple bytes of memory (assuming they’re not chars). You can tell how many bytes by using sizeof. And you can tell which address in memory is the first byte of the object by using the standard & operator, which always returns the address of the first byte.

And here’s another fun fact! If you iterate over the bytes of any object, you get its object representation. Two things with the same object representation in memory are equal.

If you want to iterate over the object representation, you should do it with pointers to unsigned char.

    void *my_memcpy(void *dest, const void *src, size_t n)
    {
        // Make local variables for src and dest, but of type unsigned char
    
        const unsigned char *s = src;
        unsigned char *d = dest;
    
        while (n-- > 0)   // For the given number of bytes
            *d++ = *s++;  // Copy source byte to dest byte
    
        // Most copy functions return a pointer to the dest as a convenience
        // to the caller
    
        return dest;
    }

(There are some good examples of post-increment and post-decrement in there for you to study, as well.)

It’s important to note that the version, above, is probably less efficient than the one that comes with your system.

But you can pass pointers to anything into it, and it’ll copy those objects. Could be int*, struct animal*, or anything.

Let’s do another example that prints out the object representation bytes of a struct so we can see if there’s any padding in there and what values it has¹²⁰.

#include <stdio.h>

struct foo {
    char a;
    int b;
};

int main(void)
{
    struct foo x = {0x12, 0x12345678};
    unsigned char *p = (unsigned char *)&x;

    for (size_t i = 0; i < sizeof x; i++) {
        printf("%02X\n", p[i]);
    }
}

What we have there is a struct foo that’s built in such a way that should encourage a compiler to inject padding bytes (though it doesn’t have to). And then we get an unsigned char * to the first byte of the struct foo variable x.

From there, all we need to know is the sizeof x and we can loop through that many bytes, printing out the values (in hex for ease).

Running this gives a bunch of numbers as output. I’ve annotated it below to identify where the values were stored:

On all systems, sizeof(char) is 1, and we see that first byte at the top of the output holding the value 0x12 that we stored there.

Finally, on my system, sizeof(int) is 4, and we can see those 4 bytes at the end. Notice how they’re the same bytes as are in the hex value 0x12345678, but strangely in reverse order¹²¹.

So that’s a little peek under the hood at the bytes of a more complex entity in memory.

23.3 The NULL Pointer and Zero

Personally, I always use NULL when I mean NULL, but you might see some other variants from time to time. Though '\0' (a byte with all bits set to zero) will also compare equal, it’s weird to compare it to a pointer; you should compare NULL against the pointer. (Of course, lots of times in string processing, you’re comparing the thing the pointer points to to '\0', and that’s right.)

0 is called the null pointer constant, and, when compared to or assigned into another pointer, it is converted to a null pointer of the same type.

23.4 Pointers as Integers

You can cast pointers to integers and vice-versa (since a pointer is just an index into memory), but you probably only ever need to do this if you’re doing some low-level hardware stuff. The results of such machinations are implementation-defined, so they aren’t portable. And weird things could happen.

C does make one guarantee, though: you can convert a pointer to a uintptr_t type and you’ll be able to convert it back to a pointer without losing any data.

Additionally, if you feel like being signed, you can use intptr_t to the same effect.

23.5 Pointer Differences

As you know from the section on pointer arithmetic, you can subtract one pointer from another¹²³ to get the difference between them in count of array elements.

Now the type of that difference is something that’s up to the implementation, so it could vary from system to system.

To be more portable, you can store the result in a variable of type ptrdiff_t defined in <stddef.h>.

    int cats[100];
    
    int *f = cats + 20;
    int *g = cats + 60;
    
    ptrdiff_t d = g - f;  // difference is 40

    printf("%td\n", d);  // Print decimal: 40
    printf("%tX\n", d);  // Print hex:     28

23.6 Pointers to Functions

Functions are just collections of machine instructions in memory, so there’s no reason we can’t get a pointer to the first instruction of the function.

This can be useful for passing a pointer to a function into another function as an argument. Then the second one could call whatever was passed in.

The tricky part with these, though, is that C needs to know the type of the variable that is the pointer to the function.

Like “this is a pointer to a function that takes two int arguments and returns void”.

Well, it turns out it looks very much like a function prototype, except with some extra parentheses:

    // Declare p to be a pointer to a function.
    // This function returns a float, and takes two ints as arguments.
    
    float (*p)(int, int);

Also notice that you don’t have to give the parameters names. But you can if you want; they’re just ignored.

    // Declare p to be a pointer to a function.
    // This function returns a float, and takes two ints as arguments.
    
    float (*p)(int a, int b);

So now that we know how to declare a variable, how do we know what to assign into it? How do we get the address of a function?

Turns out there’s a shortcut just like with getting a pointer to an array: you can just refer to the bare function name without parens. (You can put an & in front of this if you like, but it’s unnecessary and not idiomatic.)

Once you have a pointer to a function, you can call it just by adding parens and an argument list.

Let’s do a simple example where I effectively make an alias for a function by setting a pointer to it. Then we’ll call it.

#include <stdio.h>

void print_int(int n)
{
    printf("%d\n", n);
}

int main(void)
{
    // Assign p to point to print_int:

    void (*p)(int) = print_int;

    p(3490);          // Call print_int via the pointer
}

Notice how the type of p represents the return value and parameter types of print_int. It has to, or else C will complain about incompatible pointer types.

One more example here shows how we might pass a pointer to a function as an argument to another function.

We’ll write a function that takes a couple integer arguments, plus a pointer to a function that operates on those two arguments. Then it prints the result.

#include <stdio.h>

int add(int a, int b)
{
    return a + b;
}

int mult(int a, int b)
{
    return a * b;
}

void print_math(int (*op)(int, int), int x, int y)
{
    int result = op(x, y);

    printf("%d\n", result);
}

int main(void)
{
    print_math(add, 5, 7);   // 12
    print_math(mult, 5, 7);  // 35
}

Take a moment to digest that. The idea here is that we’re going to pass a pointer to a function to print_math(), and it’s going to call that function to do some math.

This way we can change the behavior of print_math() by passing another function into it. You can see we do that on lines 22-23 when we pass in pointers to functions add and mult, respectively.

Now, on line 13, I think we can all agree the function signature of print_math() is a sight to behold. And, if you can believe it, this one is actually pretty straight-forward compared to some things you can construct¹²⁴.

But let’s digest it. Turns out there are only three parameters, but they’re a little hard to see:

    //                      op             x      y
    //              |-----------------|  |---|  |---|
    void print_math(int (*op)(int, int), int x, int y)

The first, op, is a pointer to a function that takes two ints as arguments and returns an int. This matches the signatures for both add() and mult().

Slowly and deliberately let your eyes play over the signature while you identify the working parts. One thing that always stands out for me is the sequence (*op)(, the parens and the asterisk. That’s the giveaway it’s a pointer to a function.

24 Bitwise Operations

These numeric operations effectively allow you to manipulate individual bits in variables, fitting since C is such a low-level langauge¹²⁵.

24.1 Bitwise AND, OR, XOR, and NOT

For each of these, the usual arithmetic conversions take place on the operands (which in this case must be an integer type), and then the appropriate bitwise operation is performed.

Operation	Operator	Example
AND	`&`	`a = b & c`
OR	`\|`	`a = b \| c`
XOR	`^`	`a = b ^ c`
NOT	`~`	`a = ~c`

Operator	Example	Longhand equivalent
`&=`	`a &= c`	`a = a & c`
`\|=`	`a \|= c`	`a = a \| c`
`^=`	`a ^= c`	`a = a ^ c`

24.2 Bitwise Shift

For these, the integer promotions are performed on each operand (which must be an integer type) and then a bitwise shift is executed. The type of the result is the type of the promoted left operand.

New bits are filled with zeros, with a possible exception noted in the implementation-defined behavior, below.

Watch for undefined behavior: no negative shifts, and no shifts that are larger than the size of the promoted left operand.

Operation	Operator	Example
Shift left	`<<`	`a = b << c`
Shift right	`>>`	`a = b >> c`

Operator	Example	Longhand equivalent
`>>=`	`a >>= c`	`a = a >> c`
`<<=`	`a <<= c`	`a = a << c`

Also watch for implementation-defined behavior: if you right-shift a negative number, the results are implementation-defined. (It’s perfectly fine to right-shift a signed int, just make sure it’s positive.)

25 Variadic Functions

Variadic is a fancy word for functions that take arbitrary numbers of arguments.

    int add(int x, int y)
    {
        return x + y;
    }

You can only call that with exactly two arguments which correspond to parameters x and y.

    add(2, 3);
    add(5, 12);

    add(2, 3, 4);  // ERROR
    add(5);        // ERROR

We’ve already seen a famous example in printf()! You can pass all kinds of things to it.

    printf("Hello, world!\n");
    printf("The number is %d\n", 2);
    printf("The number is %d and pi is %f\n", 2, 3.14159);

    printf();  // ERROR

This leads us to one of the limitations of variadic functions in C: they must have at least one argument.

But aside from that, they’re pretty flexible, even allows arguments to have different types just like printf() does.

25.1 Ellipses in Function Signatures

What you do is put all the arguments that must be passed first (and remember there has to be at least one) and after that, you put .... Just like this:

    void func(int a, ...)   // Literally 3 dots here

So, great, we can get that first argument that’s in variable a, but what about the rest of the arguments? How do you get to them?

25.2 Getting the Extra Arguments

First things first, we’re going to use a special variable of type va_list (variable argument list) to keep track of which variable we’re accessing at a time.

The idea is that we first start processing arguments with a call to va_start(), process each argument in turn with va_arg(), and then, when done, wrap it up with va_end().

When you call va_start(), you need to pass in the last named parameter (the one just before the ...) so it knows where to start looking for the additional arguments.

And when you call va_arg() to get the next argument, you have to tell it the type of argument to get next.

Here’s a demo that adds together an arbitrary number of integers. The first argument is the number of integers to add together. We’ll make use of that to figure out how many times we have to call va_arg().

#include <stdio.h>
#include <stdarg.h>

int add(int count, ...)
{
    int total = 0;
    va_list va;

    va_start(va, count);   // Start with arguments after "count"

    for (int i = 0; i < count; i++) {
        int n = va_arg(va, int);   // Get the next int

        total += n;
    }

    va_end(va);  // All done

    return total;
}

int main(void)
{
    printf("%d\n", add(4, 6, 2, -4, 17));  // 6 + 2 - 4 + 17 = 21
    printf("%d\n", add(2, 22, 44));        // 22 + 44 = 66
}

When printf() is called, it uses the number of %ds (or whatever) in the format string to know how many more arguments there are!

If the syntax of va_arg() is looking strange to you (because of that loose type name floating around in there), you’re not alone. These are implemented with preprocessor macros in order to get all the proper magic in there.

25.3 va_list Functionality

What is that va_list variable we’re using up there? It’s an opaque variable¹²⁷ that holds information about which argument we’re going to get next with va_arg(). You see how we just call va_arg() over and over? The va_list variable is a placeholder that’s keeping track of progress so far.

But we have to initialize that variable to some sensible value. That’s where va_start() comes into play.

When we called va_start(va, count), above, we were saying, “Initialize the va variable to point to the variable argument immediately after count.”

And that’s why we need to have at least one named variable in our argument list¹²⁸.

Once you have that pointer to the initial parameter, you can easily get subsequent argument values by calling va_arg() repeatedly. When you do, you have to pass in your va_list variable (so it can keep on keeping track of where you are), as well as the type of argument you’re about to copy off.

It’s up to you as a programmer to figure out which type you’re going to pass to va_arg(). In the above example, we just did ints. But in the case of printf(), it uses the format specifier to determine which type to pull off next.

And when you’re done, call va_end() to wrap it up. You must (the spec says) call this on a particular va_list variable before you decide to call either va_start() or va_copy() on it again. I know we haven’t talked about va_copy() yet.

I also mentioned va_copy() up there; it makes a copy of your va_list variable in the exact same state. That is, if you haven’t started with va_arg() with the source variable, the new one won’t be started, either. If you’ve consumed 5 variables with va_arg() so far, the copy will also reflect that.

va_copy() can be useful if you need to scan ahead through the arguments but need to also remember your current place.

25.4 Library Functions That Use va_lists

One of the other uses for these is pretty cool: writing your own custom printf() variant. It would be a pain to have to handle all those format specifiers right? All zillion of them?

Luckily, there are printf() variants that accept a working va_list as an argument. You can use these to wrap up and make your own custom printf()s!

These functions start with the letter v, such as vprintf(), vfprintf(), vsprintf(), and vsnprintf(). Basically all your printf() golden oldies except with a v in front.

Let’s make a function my_printf() that works just like printf() except it takes an extra argument up front.

#include <stdio.h>
#include <stdarg.h>

int my_printf(int serial, const char *format, ...)
{
    va_list va;

    // Do my custom work
    printf("The serial number is: %d\n", serial);

    // Then pass the rest off to vprintf()
    va_start(va, format);
    int rv = vprintf(format, va);
    va_end(va);

    return rv;
}

int main(void)
{
    int x = 10;
    float y = 3.2;

    my_printf(3490, "x is %d, y is %f\n", x, y);
}

See what we did there? On lines 12-14 we started a new va_list variable, and then just passed it right into vprintf(). And it knows just want to do with it, because it has all the printf() smarts built-in.

We still have to call va_end() when we’re done, though, so don’t forget that!

26 Locale and Internationalization

Localization is the process of making your app ready to work well in different locales (or countries).

As you might know, not everyone uses the same character for decimal points or for thousands separators… or for currency.

These locales have names, and you can select one to use. For example, a US locale might write a number like:

Whereas in Brazil, the same might be written with the commas and decimal points swapped:

Makes it easier to write your code so it ports to other nationalities with ease!

Well, sort of. Turns out C only has one built-in locale, and it’s limited. The spec really leaves a lot of ambiguity here; it’s hard to be completely portable.

26.1 Setting the Localization, Quick and Dirty

There is basically one thing you can portably do here in terms of declaring a specific locale. This is likely what you want to do if you’re going to do locale anything:

    set_locale(LC_ALL, "");  // Use this environment's locale for everything

You’ll want to call that so that the program gets initialized with your current locale.

Getting into more details, there is one more thing you can do and stay portable:

    set_locale(LC_ALL, "C");  // Use the default C locale

but that’s called by default every time your program starts, so there’s not much need to do it yourself.

In that second string, you can specify any locale supported by your system. This is completely system-dependent, so it will vary. On my system, I can specify this:

    setlocale(LC_ALL, "en_US.UTF-8");  // Non-portable!

And that’ll work. But it’s only portable to systems which have that exact same name for that exact same locale, and you can’t guarantee it.

By passing in an empty string ("") for the second argument, you’re telling C, “Hey, figure out what the current locale on this system is so I don’t have to tell you.”

26.2 Getting the Monetary Locale Settings

Because moving green pieces of paper around promises to be the key to happiness¹²⁹, let’s talk about monetary locale. When you’re writing portable code, you have to know what to type for cash, right? Whether that’s “$”, “€”, “¥”, or “£”.

How can you write that code without going insane? Luckily, once you call setlocale(LC_ALL, ""), you can just look these up with a call to localeconv():

    struct lconv *x = localeconv();

This function returns a pointer to a statically-allocated struct lconv that has all that juicy information you’re looking for.

“negative”, and int_ means “international”. Though a lot of these are type char or char*, most (or the strings they point to) are actually treated as integers¹³⁰.

Before we go further, know that CHAR_MAX (from <limits.h>) is the maximum value that can be held in a char. And that many of the following char values use that to indicate the value isn’t available in the given locale.

Field	Description
`char *mon_decimal_point`	Decimal pointer character for money, e.g. `"."`.
`char *mon_thousands_sep`	Thousands separator character for money, e.g. `","`.
`char *mon_grouping`	Grouping description for money (see below).
`char *positive_sign`	Positive sign for money, e.g. `"+"` or `""`.
`char *negative_sign`	Negative sign for money, e.g. `"-"`.
`char *currency_symbol`	Currency symbol, e.g. `"$"`.
`char frac_digits`	When printing monetary amounts, how many digits to print past the decimal point, e.g. `2`.
`char p_cs_precedes`	`1` if the `currency_symbol` comes before the value for a non-negative monetary amount, `0` if after.
`char n_cs_precedes`	`1` if the `currency_symbol` comes before the value for a negative monetary amount, `0` if after.
`char p_sep_by_space`	Determines the separation of the `currency symbol` from the value for non-negative amounts (see below).
`char n_sep_by_space`	Determines the separation of the `currency symbol` from the value for negative amounts (see below).
`char p_sign_posn`	Determines the `positive_sign` position for non-negative values.
`char p_sign_posn`	Determines the `positive_sign` position for negative values.
`char *int_curr_symbol`	International currency symbol, e.g. `"USD "`.
`char int_frac_digits`	International value for `frac_digits`.
`char int_p_cs_precedes`	International value for `p_cs_precedes`.
`char int_n_cs_precedes`	International value for `n_cs_precedes`.
`char int_p_sep_by_space`	International value for `p_sep_by_space`.
`char int_n_sep_by_space`	International value for `n_sep_by_space`.
`char int_p_sign_posn`	International value for `p_sign_posn`.
`char int_n_sign_posn`	International value for `n_sign_posn`.

26.2.1 Monetary Digit Grouping

OK, this is a trippy one. mon_grouping is a char*, so you might be thinking it’s a string. But in this case, no, it’s really an array of chars. It should always end either with a 0 or CHAR_MAX.

These values describe how to group sets of numbers in currency to the left of the decimal (the whole number part).

These are groups of three. Group 0 (just left of the decimal) has 3 digits. Group 1 (next group to the left) has 3 digits, and the last one also has 3.

So we could describe these groups, from the right (the decimal) to the left with a bunch of integer values representing the group sizes:

but that’s crazy. Luckily, we can specify 0 to indicate that the previous group size repeats:

Which means to repeat every 3. That would handle $100, $1,000, $10,000, $10,000,000, $100,000,000,000, and so on.

One more value that can occur is CHAR_MAX. This indicates that no more grouping should occur, and can appear anywhere in the array, including the first value.

And simply having CHAR_MAX in the first array position would tell you there was to be no grouping at all.

26.2.2 Separators and Sign Position

All the sep_by_space variants deal with spacing around the currency sign. Valid values are:

Value	Description
`0`	No space between currency symbol and value.
`1`	Separate the currency symbol (and sign, if any) from the value with a space.
`2`	Separate the sign symbol from the currency symbol (if adjacent) with a space, otherwise separate the sign symbol from the value with a space.

Value	Description
`0`	Put parens around the value and the currency symbol.
`1`	Put the sign string in front of the currency symbol and value.
`2`	Put the sign string after the currency symbol and value.
`3`	Put the sign string directly in front of the currency symbol.
`4`	Put the sign string directly behind the currency symbol.

26.2.3 Example Values

When I get the values on my system, this is what I see (grouping string displayed as individual byte values):

26.3 Localization Specifics

Notice how we passed the macro LC_ALL to setlocale() earlier… this hints that there might be some variant that allows you to be more precise about which parts of the locale you’re setting.

Macro	Description
`LC_ALL`	Set all of the following to the given locale.
`LC_COLLATE`	Controls the behavior of the `strcoll()` and `strxfrm()` functions.
`LC_CTYPE`	Controls the behavior of the character-handling functions¹³¹.
`LC_MONETARY`	Controls the values returned by `localeconv()`.
`LC_NUMERIC`	Controls the decimal point for the `printf()` family of functions.
`LC_TIME`	Controls time formatting of the `strftime()` and `wcsftime()` time and date printing functions.

It’s pretty common to see LC_ALL being set, but, hey, at least you have options.

Also I should point out that LC_CTYPE is one of the biggies because it ties into wide characters, a significant can of worms that we’ll talk about later.

27 Unicode, Wide Characters, and All That

Before we begin, note that this is an active area of language development in C as it works to get past some, erm, growing pains. When C2x comes out, updates here are probable.

Most people are basically interested in the deceptively simple question, “How do I use such-and-such character set in C?” We’ll get to that. But as we’ll see, it might already work on your system. Or you might have to punt to a third-party library.

We’re going to take about a lot of things this chapter—some are platform agnostic, and some are C-specific.

27.1 What is Unicode?

Back in the day, it was popular in the US and much of the world to use a 7-bit or 8-bit encoding for characters in memory. This meant we could have 128 or 256 characters (including non-printable characters) total. That was fine for a US-centric world, but it turns out there are actually other alphabets out there—who knew? Chinese has over 50,000 characters, and that’s not fitting in a byte.

So people came up with all kinds of alternate ways to represent their own custom character sets. And that was fine, but turned into a compatibility nightmare.

To escape it, Unicode was invented. One character set to rule them all. It extends off into infinity (effectively) so we’ll never run out of space for new characters. It has Chinese, Latin, Greek, cuniform, chess symbols, emojis… just about everything, really! And more is being added all the time!

27.2 Code Points

I want to talk about two concepts here. It’s confusing because they’re both numbers… different numbers for the same thing. But bear with me.

Let’s loosely define code point to mean a numeric value representing a character. (Code points can also represent unprintable control characters, but just assume I mean something like the letter “B” or the character “π”.)

Each code point represents a unique character. And each character has a unique numeric code point associated with it.

For example, in Unicode, the numeric value 66 represents “B”, and 960 represents “π”. Other character mappings that aren’t Unicode use different values, potentially, but let’s forget them and concentrate on Unicode, the future!

So that’s one thing: there’s a number that represents each character. In Unicode, these numbers run from 0 to over 1 million.

27.3 Encoding

If you recall, an 8-bit byte can hold values from 0-255, inclusive. That’s great for “B” which is 66—that fits in a byte. But “π” is 960, and that doesn’t fit in a byte! We need another byte. How do we store all that in memory? Or what about bigger numbers, like 195,024? That’s going to need a number of bytes to hold.

The Big Question: how are these numbers represented in memory? This is what we call the encoding of the characters.

So we have two things: one is the code point which tells us effectively the serial number of a particular character. And we have the encoding which tells us how we’re going to represent that number in memory.

There are plenty of encodings. You can make up your own right now, if you want¹³². But we’re going to look at some really common encodings that are in use with Unicode.

Encoding	Description
UTF-8	A byte-oriented encoding that uses a variable number of bytes per character. This is the one to use.
UTF-16	A 16-bit per character¹³³ encoding.
UTF-32	A 32-bit per character encoding.

With UTF-16 and UTF-32, the byte order matters, so you might see UTF-16BE for big-endian and UTF-16LE for little-endian. Same for UTF-32. Technically, if unspecified, you should assume big-endian. But since Windows uses UTF-16 extensively and is little-endian, sometimes that is assumed¹³⁴.

Let’s look at some examples. I’m going to write the values in hex because that’s exactly two digits per 8-bit byte, and it makes it easier to see how things are arranged in memory.

Character	Code Point	UTF-16BE	UTF-32BE	UTF-16LE	UTF-32LE	UTF-8
`A`	41	0041	00000041	4100	41000000	41
`B`	42	0042	00000042	4200	42000000	42
`~`	7E	007E	0000007E	7E00	7E000000	7E
`π`	3C0	03C0	000003C0	C003	C0030000	CF80
`€`	20AC	20AC	000020AC	AC20	AC200000	E282AC

Look in there for the patterns. Note that UTF-16BE and UTF-32BE are simply the code point represented directly as 16- and 32-bit values¹³⁵.

Then we have UTF-8 at the end. First you might notice that the single-byte code points are represented as a single byte. That’s nice. You might also notice that different code points take different number of bytes. This is a variable-width encoding.

So as soon as we get above a certain value, UTF-8 starts using additional bytes to store the values. And they don’t appear to correlate with the code point value, either.

That last bit is a neat thing about Unicode and UTF-8 from a North American perspective: it’s backward compatible with 7-bit ASCII encoding! So if you’re used to ASCII, UTF-8 is the same! Every ASCII-encoded document is also UTF-8 encoded! (But not the other way around, obviously.)

It’s probably that last point more than any other that is driving UTF-8 to take over the world.

27.4 Source and Execution Character Sets

When programming in C, there are (at least) three character sets that are in play:

Your compiler probably has options to select these character sets at build-time.

The basic character set for both source and execution will contain the following characters:

The execution character set will additionally have characters for alert (bell/flash), backspace, carriage return, and newline.

But most people don’t go to that extreme and freely use their extended character sets in source and executable, especially now that Unicode and UTF-8 are getting more common. I mean, the basic character set doesn’t even allow for @, $, or `!

Notably, it’s a pain (though possible with escape sequences) to enter Unicode characters using only the basic character set.

27.5 Unicode in C

Before I get into encoding in C, let’s talk about Unicode from a code point standpoint. There is a way in C to specify Unicode characters and these will get translated by the compiler into the execution character set¹³⁸.

How about the euro symbol, code point 0x20AC. (I’ve written it in hex because both ways of representing it in C require hex.) How can we put that in our C code?

Use the \u escape to put it in a string, e.g. "\u20AC" (case for the hex doesn’t matter). You must put exactly four hex digits after the \u, padding with leading zeros if necessary.

    char *s = "\u20AC1.23";
    
    printf("%s\n", s);  // €1.23

So \u works for 16-bit Unicode code points, but what about ones bigger than 16 bits? For that, we need capitals: \U.

    char *s = "\U0001D4D1";
    
    printf("%s\n", s);  // Prints a mathematical letter "B"

Again, these are translated into the execution character set during compilation. They represent Unicode code points, not any specific encoding. Furthermore, if a Unicode code point is not representable in the execution character set, the compiler can do whatever it wants with it.

    char *s = "€1.23";
    
    printf("%s\n", s);  // €1.23

And you probably can, given a modern compiler. The source character set will be translated for you into the execution character set by the compiler. But compilers are free to puke out if they find any characters that aren’t included in their extended character set, and the € symbol certainly isn’t in the basic character set.

Caveat from the spec: you can’t use \u or \U to encode any code points below 0xA0 except for 0x24 ($), 0x40 (@), and 0x60 (`)—yes, those are precisely the trio of common punctuation marks missing from the basic character set. Apparently this restriction is relaxed in the upcoming version of the spec.

Finally, you can also use these in identifiers in your code, with some restrictions. But I don’t want to get into that here. We’re all about string handling in this chapter.

27.6 A Quick Note on UTF-8 Before We Swerve into the Weeds

It could be that your source file on disk, the extended source characters, and the extended execution characters are all in UTF-8 format. And the libraries you use expect UTF-8. This is the glorious future of UTF-8 everywhere.

If that’s the case, and you don’t mind being non-portable to systems that aren’t like that, then just run with it. Stick Unicode characters in your source and data at will. Use regular C strings and be happy.

A lot of things will just work (albeit non-portably) because UTF-8 strings can safely be NUL-terminated just like any other C string. But maybe losing portability in exchange for easier character handling is a tradeoff that’s worth it to you.

And probably others I haven’t discovered. Let me know what pitfalls there are out there…

27.7 Different Character Types

27.7.1 Multibyte Characters

First of all, I want to potentially change your thinking about what a string (array of chars) is. These are multibyte strings made up of multibyte characters.

Even if a particular character in the string is only a single byte, or if a string is made up of only single characters, it’s known as multibyte.

    char c[128] = "Hello, world!";  // Multibyte string

What we’re saying here is that a particular character that’s not in the basic character set could be composed of multiple bytes. Up to MB_LEN_MAX of them (from <limits.h>). Sure, it only looks like one character on the screen, but it could be multiple bytes.

    char *s = "\u20AC1.23";
    
    printf("%s\n", s);  // €1.23

    char *s = "\u20AC1.23";  // €1.23
    
    printf("%zu\n", strlen(s));  // 7!

The string length of "€1.23" is 7?! Yes! Well, on my system, yes! Remember that strlen() returns the number of bytes in the string, not the number of characters. (When we get to “wide characters”, coming up, we’ll see a way to get the number of characters in the string.)`

Note that while C allows individual multibyte char constants, the behavior of these varies by implementation and your compiler might warn on it.

GCC, for example, warns of multi-character character constants for the following two lines (and, on my system, prints out the UTF-8 encoding):

    printf("%x\n", '€');
    printf("%x\n", '\u20ac');

27.7.2 Wide Characters

A wide character is a single value that can uniquely represent any character in the current locale. It’s analogous to Unicode code points. But it might not be. Or it might be.

Basically, where multibyte character strings are arrays of bytes, wide character strings are arrays of characters. So you can start thinking on a character-by-character basis rather than a byte-by-byte basis (the latter of which gets all messy when characters start taking up variable numbers of bytes).

Wide characters can be represented by a number of types, but the big standout one is wchar_t. It’s the main one.

You might be wondering if you can’t tell if it’s Unicode or not, how does that allow you much flexibility in terms of writing code? wchar_t opens some of those doors, as there are a rich set of function you can use to deal with wchar_t strings (like getting the length, etc.) without caring about the encoding.

27.8 Using Wide Characters and wchar_t

Time for a new type: wchar_t. This is the main wide character typre. Remember how a char is only one byte? And a byte’s not enough to represent all characters, potentially? Well, this one is enough.

How many bytes big is it? Well, it’s not totally clear. Could be 16 bits. Could be 32 bits.

But wait, you’re saying—if it’s only 16 bits, it’s not big enough to hold all the Unicode code points, is it? You’re right—it’s not. The spec doesn’t require it to be. It just has to be able to represent all the characters in the current locale.

This can cause grief with Unicode on platforms with 16-bit wchar_ts (ahem—Windows). But that’s out of scope for this guide.

You can declare a string or character of this type with the L prefix, and you can print them with the %ls (“ell ess”) format specifier. Or print an individual wchar_t with %lc.

    wchar_t *s = L"Hello, world!";
    wchar_t c = L'B';
    
    printf("%ls %lc\n", s, c);

Now—are those characters stored are Unicode code points, or not? Depends on the implementation. But you can test if they are with the macro __STDC_ISO_10646__. If this is defined, the answer is, “It’s Unicode!”

More detailedly, the value in that macro is an integer in the form yyyymm that lets you know what Unicode standard you can rely on—whatever was in effect on that date.

27.8.1 Multibyte to wchar_t Conversions

So how do we get from the byte-oriented standard strings to the character-oriented wide strings and back?

So if we want to convert a multibyte string to a wide character string, we can call the mbstowcs(). And the other way around: wcstombs().

Let’s do a quick demo where we convert a multibyte string to a wide character string, and compare the string lengths of the two using their respective functions.

Conversion Function	Description
`mbtowc()`	Convert a multibyte character to a wide character.
`wctomb()`	Convert a wide character to a multibyte character.
`mbstowcs()`	Convert a multibyte string to a wide string.
`wcstombs()`	Convert a wide string to a multibyte string.

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <string.h>
#include <locale.h>

int main(void)
{
    // Get out of the C locale to one that likely has the euro symbol
    setlocale(LC_ALL, "");

    // Original multibyte string with a euro symbol (Unicode point 20ac)
    char *mb_string = "The cost is \u20ac1.23";  // €1.23
    size_t mb_len = strlen(mb_string);

    // Wide character array that will hold the converted string
    wchar_t wc_string[128];  // Holds up to 128 wide characters

    // Convert the MB string to WC; this returns the number of wide chars
    size_t wc_len = mbstowcs(wc_string, mb_string, 128);

    // Print result--note the %ls for wide char strings
    printf("multibyte: \"%s\" (%zu bytes)\n", mb_string, mb_len);
    printf("wide char: \"%ls\" (%zu characters)\n", wc_string, wc_len);
}

One interesting thing to note is that mbstowcs(), in addition to converting the multibyte string to wide, returns the length (in characters) of the wide character string. And, in fact, it has a special mode where it only returns the length-in-characters of a given multibyte string: you just pass NULL to the destination, and 0 to the maximum number of characters to convert (this value is ignored).

(In the code below, I’m using my extended source character set—you might have to replace those with \u escapes.)

    setlocale(LC_ALL, "");
    
    // The following string has 7 characters
    size_t len_in_chars = mbstowcs(NULL, "§¶°±π€•", 0));
    
    printf("%zu", len_in_chars);  // 7

27.9 Wide Character Functionality

Once we’re in wide character land, we have all kinds of functionality at our disposal. I’m just going to summarize a bunch of the functions here, but basically what we have here are the wide character versions of the multibyte string functions that we’re use to. (For example, we know strlen() for multibyte strings; there’s an wcslen() for wide character strings.)

27.9.1 wint_t

A lot of these functions use a wint_t to hold single characters, whether they are passed in or returned.

It is related to wchar_t in nature. A wint_t is an integer that can represent all values in the extended character set, and also a special end-of-file character, WEOF.

27.9.2 I/O Stream Orientation

The tl;dr here is to not mix and match byte-oriented functions (like fprintf() with wide-oriented functions (like fwprintf()). Decide if a stream will be byte-oriented or wide-oriented and stick with those types of I/O functions.

In more detail: streams can be either byte-oriented or wide-oriented. When a stream is first created, it has no orientation, but the first read or write will set the orientation.

If you first use a wide operation (like fwprintf()) it will orient the stream wide.

If you first use a byte operation (like fprintf()) it will orient the stream by bytes.

You can manually set an unoriented stream one way or the other with a call to fwide(). You can use that same function to get the orientation of a stream.

If you need to change the orientation mid-flight, you can do it with freopen().

27.9.3 I/O Functions

I/O Function	Description
`wprintf()`	Formatted console output.
`wscanf()`	Formatted console input.
`getwchar()`	Character-based console input.
`putwchar()`	Character-based console output.
`fwprintf()`	Formatted file output.
`fwscanf()`	Formatted file input.
`fgetwc()`	Character-based file input.
`fputwc()`	Character-based file output.
`fgetws()`	String-based file input.
`fputws()`	String-based file output.
`swprintf()`	Formatted string output.
`swscanf()`	Formatted string input.
`vfwprintf()`	Variadic formatted file output.
`vfwscanf()`	Variadic formatted file input.
`vswprintf()`	Variadic formatted string output.
`vswscanf()`	Variadic formatted string input.
`vwprintf()`	Variadic formatted console output.
`vwscanf()`	Variadic formatted console input.
`ungetwc()`	Push a wide character back on an output stream.
`fwide()`	Get or set stream multibyte/wide orientation.

27.9.4 Type Conversion Functions

Conversion Function	Description
`wcstod()`	Convert string to `double`.
`wcstof()`	Convert string to `float`.
`wcstold()`	Convert string to `long double`.
`wcstol()`	Convert string to `long`.
`wcstoll()`	Convert string to `long long`.
`wcstoul()`	Convert string to `unsigned long`.
`wcstoull()`	Convert string to `unsigned long long`.

27.9.5 String and Memory Copying Functions

Copying Function	Description
`wcscpy()`	Copy string.
`wcsncpy()`	Copy string, length-limited.
`wmemcpy()`	Copy memory.
`wmemmove()`	Copy potentially-overlapping memory.
`wcscat()`	Concatenate strings.
`wcsncat()`	Concatenate strings, length-limited.

27.9.6 String and Memory Comparing Functions

Comparing Function	Description
`wcscmp()`	Compare strings lexicographically.
`wcsncmp()`	Compare strings lexicographically, length-limited.
`wcscoll()`	Compare strings in dictionary order by locale.
`wmemcmp()`	Compare memory lexicographically.
`wcsxfrm()`	Transform strings into versions such that `wcscmp()` behaves like `wcscoll()`¹⁴⁰.

27.9.7 String Searching Functions

Searching Function	Description
`wcschr()`	Find a character in a string.
`wcsrchr()`	Find a character in a string from the back.
`wmemchr()`	Find a character in memory.
`wcsstr()`	Find a substring in a string.
`wcspbrk()`	Find any of a set of characters in a string.
`wcsspn()`	Find length of substring including any of a set of characters.
`wcscspn()`	Find length of substring before any of a set of characters.
`wcstok()`	Find tokens in a string.

27.9.8 Length/Miscellaneous Functions

Length/Misc Function	Description
`wcslen()`	Return the length of the string.
`wmemset()`	Set characters in memory.
`wcsftime()`	Formatted date and time output.

27.9.9 Character Classification Functions

Length/Misc Function	Description
`iswalnum()`	True if the character is alphanumeric.
`iswalpha()`	True if the character is alphabetic.
`iswblank()`	True if the character is blank (space-ish, but not a newline).
`iswcntrl()`	True if the character is a control character.
`iswdigit()`	True if the character is a digit.
`iswgraph()`	True if the character is printable (except space).
`iswlower()`	True if the character is lowercase.
`iswprint()`	True if the character is printable (including space).
`iswpunct()`	True if the character is punctuation.
`iswspace()`	True if the character is whitespace.
`iswupper()`	True if the character is uppercase.
`iswxdigit()`	True if the character is a hex digit.
`towlower()`	Convert character to lowercase.
`towupper()`	Convert character to uppercase.

27.10 Parse State, Restartable Functions

We’re going to get a little bit into the guts of multibyte conversion, but this is a good thing to understand, conceptually.

Imagine how your program takes a sequence of multibyte characters and turns them into wide characters, or vice-versa. It might, at some point, be partway through parsing a character, or it might have to wait for more bytes before it makes the determination of the final value.

This parse state is stored in an opaque variable of type mbstate_t and is used every time conversion is performed. That’s how the conversion functions keep track of where they are mid-work.

And if you change to a different character sequence mid-stream, or try to seek to a different place in your input sequence, it could get confused over that.

Now you might want to call me on this one: we just did some conversions, above, and I never mentioned any mbstate_t anywhere.

That’s because the conversion functions like mbstowcs(), wctomb(), etc. each have their own mbstate_t variable that they use. There’s only one per function, though, so if you’re writing multithreaded code, they’re not safe to use.

Fortunately, C defines restartable versions of these functions where you can pass in your own mbstate_t on per-thread basis if you need to. If you’re doing multithreaded stuff, use these!

Quick note on initializing an mbstate_t variable: just memset() it to zero. There is no built-in function to force it to be initialized.

    mbstate_t mbs;
    
    // Set the state to the initial state
    memset(&mbs, 0, sizeof mbs);

Here is a list of the restartable conversion functions—note the naming convension of putting an “r” after the “from” type:

These are really similar to their non-restartable counterparts, except they require you pass in a pointer to your own mbstate_t variable. And also they modify the source string pointer (to help you out if invalid bytes are found), so it might be useful to save a copy of the original.

Here’s the example from earlier in the chapter reworked to pass in our own mbstate_t.

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <wchar.h>
#include <string.h>
#include <locale.h>

int main(void)
{
    // Get out of the C locale to one that likely has the euro symbol
    setlocale(LC_ALL, "");

    // Original multibyte string with a euro symbol (Unicode point 20ac)
    char *mb_string = "The cost is \u20ac1.23";  // €1.23
    size_t mb_len = strlen(mb_string);

    // Wide character array that will hold the converted string
    wchar_t wc_string[128];  // Holds up to 128 wide characters

    // Set up the conversion state
    mbstate_t mbs;
    memset(&mbs, 0, sizeof mbs);  // Initial state

    // mbsrtowcs() modifies the input pointer to point at the first
    // invalid character, or NULL if successful. Let's make a copy of
    // the pointer for mbsrtowcs() to mess with so our original is
    // unchanged.
    //
    // This example will probably be successful, but we check farther
    // down to see.
    const char *invalid = mb_string;

    // Convert the MB string to WC; this returns the number of wide chars
    size_t wc_len = mbsrtowcs(wc_string, &invalid, 128, &mbs);

    if (invalid == NULL) {
        printf("No invalid characters found\n");

        // Print result--note the %ls for wide char strings
        printf("multibyte: \"%s\" (%zu bytes)\n", mb_string, mb_len);
        printf("wide char: \"%ls\" (%zu characters)\n", wc_string, wc_len);
    } else {
        ptrdiff_t offset = invalid - mb_string;
        printf("Invalid character at offset %td\n", offset);
    }
}

For the conversion functions that manage their own state, you can reset their internal state to the initial one by passing in NULL for their char* arguments, for example:

    mbstowcs(NULL, NULL, 0);   // Reset the parse state for mbstowcs()
    mbstowcs(dest, src, 100);  // Parse some stuff

For I/O, each wide stream manages its own mbstate_t and uses that for input and output conversions as it goes.`

And some of the byte-oriented I/O functions like printf() and scanf() keep their own internal state while doing their work.

Finally, these restartable conversion functions do actually have their own internal state if you pass in NULL for the mbstate_t parameter. This makes them behave more like their non-restartable counterparts.

27.11 Unicode Encodings and C

In this section, we’ll see what C can (and can’t) do when it comes to three specific Unicode encodings: UTF-8, UTF-16, and UTF-32.

27.11.1 UTF-8

You can tell C that you specifically want a string literal to be UTF-8 encoded, and it’ll do it for you. You can prefix a string with u8:

    char *s = u8"Hello, world!";
    
    printf("%s\n", s);   // Hello, world!--if you can output UTF-8

    char *s = u8"€123";

What if it doesn’t? You can specify a Unicode code point with your friendly neighborhood \u and \U, as noted above.

But that’s about it. There’s no portable way in the standard library to take arbirary input and turn it into UTF-8 unless your locale is UTF-8. Or to parse UTF-8 unless your locale is UTF-8.

    setlocale(LC_ALL, "");

or figure out a UTF-8 locale name on your local machine and set it explicitly like so:

    setlocale(LC_ALL, "en_US.UTF-8");  // Non-portable name

27.11.2 UTF-16, UTF-32, char16_t, and char32_t

char16_t and char32_t are a couple other potentially wide character types with sizes of 16 bits and 32 bits, respectively. Not necessarily wide, because if they can’t represent every character in the current locale, they lose their wide character nature. But the spec refers them as “wide character” types all over the place, so there we are.

You can declare a string or character of these types with the u and U prefixes:

    char16_t *s = u"Hello, world!";
    char16_t c = u'B';
    
    char32_t *t = U"Hello, world!";
    char32_t d = U'B';

Now—are values in these stored in UTF-16 or UTF-32? Depends on the implementation.

But you can test to see if they are. If the macros __STDC_UTF_16__ or __STDC_UTF_32__ are defined (to 1) it means the types hold UTF-16 or UTF-32, respectively.

If you’re curious, and I know you are, the values, if UTF-16 or UTF-32, are stored in the native endianess. That is, you should be able to compare them straight up to Unicode code point values:

    char16_t pi = u"\u03C0";  // pi symbol
    
    #if __STDC_UTF_16__
    pi == 0x3C0;  // Always true
    #else
    pi == 0x3C0;  // Probably not true
    #endif

27.11.3 Multibyte Conversions

You can convert from your multibyte encoding to char16_t or char32_t with a number of helper functions.

(Like I said, though, the result might not be UTF-16 or UTF-32 unless the corresponding macro is set to 1.)

All of these functions are restartable (i.e. you pass in your own mbstate_t), and all of them operate character by character¹⁴¹.

Conversion Function	Description
`mbrtoc16()`	Convert a multibyte character to a `char16_t` character.
`mbrtoc32()`	Convert a multibyte character to a `char32_t` character.
`c16rtomb()`	Convert a `char16_t` character to a multibyte character.
`c32rtomb()`	Convert a `char32_t` character to a multibyte character.

27.11.4 Third-Party Libraries

For heavy-duty conversion between different specific encodings, there are a couple mature libraries worth checking out. Note that I haven’t used either of these.

28 Exiting a Program

Turns out there are a lot of ways to do this, and even ways to set up “hooks” so that a function runs when a program exits.

We already covered the meaning of the exit status code in the Exit Status section, so jump back there and review if you have to.

28.1 Normal Exits

We’ll start with the regular ways to exit a program, and then jump to some of the rarer, more esoteric ones.

When you exit a program normally, all open I/O streams are flushed and temporary files removed. Basically it’s a nice exit where everything gets cleaned up and handled. It’s what you want to do almost all the time unless you have reasons to do otherwise.

28.1.1 Returning From main()

If you’ve noticed, main() has a return type of int… and yet I’ve rarely, if ever, been returning anything from main() at all.

This is because for main() only (and I can’t stress enough this special case only applies to main() and no other functions anywhere) has an implicit return 0 if you fall off the end.

You can explicitly return from main() any time you want, and some programmers feel it’s more Right to always have a return at the end of main(). But if you leave it off, C will put one there for you.

28.1.2 exit()

This one has also made an appearance a few times. If you call exit() from anywhere in your program, it will exit at that point.

28.1.3 Setting Up Exit Handlers with atexit()

You can register functions to be called when a program exits whether by returning from main() or calling the exit() function.

A call to atexit() with the handler function name will get it done. You can register multiple exit handlers, and they’ll be called in the reverse order of registration.

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

void on_exit_1(void)
{
    printf("Exit handler 1 called!\n");
}

void on_exit_2(void)
{
    printf("Exit handler 2 called!\n");
}

int main(void)
{
    atexit(on_exit_1);
    atexit(on_exit_2);
    
    printf("About to exit...\n");
}

28.2 Quicker Exits with quick_exit()

But there is a way to register exit handlers: call at_quick_exit() analogously to how you’d call atexit().

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

void on_quick_exit_1(void)
{
    printf("Quick exit handler 1 called!\n");
}

void on_quick_exit_2(void)
{
    printf("Quick exit handler 2 called!\n");
}

void on_exit(void)
{
    printf("Normal exit--I won't be called!\n");
}

int main(void)
{
    at_quick_exit(on_quick_exit_1);
    at_quick_exit(on_quick_exit_2);

    atexit(on_exit);  // This won't be called

    printf("About to quick exit...\n");

    quick_exit(0);
}

It works just like exit()/atexit(), except for the fact that file flushing and cleanup might not be done.

28.3 Nuke it from Orbit: _Exit()

Calling _Exit() exits immediately, period. No on-exit callback functions are executed. Files won’t be flushed. Temp files won’t be removed.

28.4 Exiting Sometimes: assert()

The assert() statement is used to insist that something be true, or else the program will exit.

    #define PI 3.14159
    
    assert(PI > 3);   // Sure enough, it is, so carry on

    goats -= 100;
    
    assert(goats >= 0);  // Can't have negative goats

28.5 Abnormal Exit: abort()

You can use this if something has gone horribly wrong and you want to indicate as much to the outside environment. This also won’t necessarily clean up any open files, etc.

Some foreshadowing about signals: this actually works by raising a SIGABRT which will end the process.

What happens after that is up to the system, but on Unix-likes, it was common to dump core ¹⁴⁴ as the program terminated.

29 Signal Handling

Before we start, I’m just going to advise you to generally ignore this entire chapter and use your OS’s (very likely) superior signal handling functions. Unix-likes have the sigaction() family of functions, and Windows has… whatever it does¹⁴⁵.

29.1 What Are Signals?

A signal is raised on a variety of external events. Your program can be configured to be interrupted to handle the signal, and, optionally, continue where it left off once the signal has been handled.

Think of it like a function that’s automatically called when one of these external events occurs.

What are these events? On your system, there are probably a lot of them, but in the C spec there are just a few:

You can set up your program to ignore, handle, or allow the default action for each of these by using the signal() function.

29.2 Handling Signals with signal()

The signal() call takes two parameters: the signal in question, and an action to take when that signal is raised.

Let’s write a program that you can’t CTRL-C out of. (Don’t fret—in the following program, you can also hit RETURN and it’ll exit.)

#include <stdio.h>
#include <signal.h>

int main(void)
{
    char s[1024];

    signal(SIGINT, SIG_IGN);    // Ignore SIGINT, caused by ^C

    printf("Try hitting ^C...\n");

    // Wait for a line of input so the program doesn't just exit
    fgets(s, sizeof s, stdin);
}

Check out line 8—we tell the program to ignore SIGINT, the interrupt signal that’s raised when CTRL-C is hit. No matter how much you hit it, the signal remains ignored. If you comment out line 8, you’ll see you can CTRL-C with impunity and quit the program on the spot.

29.3 Writing Signal Handlers

I mentioned you could also write a handler function that gets called with the signal is raised.

These are pretty straightforward, are also very capability-limited when it comes to the spec.

Before we start, let’s look at the function prototype for the signal() call:

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

signal() takes two arguments: an integer sig representing the signal, and a pointer func to the handler (the handler returns void and takes an int as an argument), highlighted below:

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

Basically, we’re going to pass in the signal number we’re interesting in catching, and we’re going to pass a pointer to a function of the form:

Now—what about the rest of that prototype? It’s basically all the return type. See, signal() will return whatever you passed as func on success… so that means it’s returning a pointer to a function that returns void and takes an int as an argument.

    returned
    function    indicates we're              and
    returns     returning a                  that function
    void        pointer to function          takes an int
    |--|        |                                   |---|
    void       (*signal(int sig, void (*func)(int)))(int);

Let’s do an example where we make it so you have to hit CTRL-C twice to exit.

I want to be clear that this program engages in undefined behavior in a couple ways. But it’ll probably work for you, and it’s hard to come up with portable non-trivial demos.

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>

int count = 0;

void sigint_handler(int signum)
{
    // The compiler is allowed to run:
    //
    //   signal(signum, SIG_DFL)
    //
    // when the handler is first called. So we reset the handler here:
    signal(SIGINT, sigint_handler);

    (void)signum;   // Get rid of unused variable warning

    count++;                       // Undefined behavior
    printf("Count: %d\n", count);  // Undefined behavior

    if (count == 2) {
        printf("Exiting!\n");      // Undefined behavior
        exit(0);
    }
}

int main(void)
{
    signal(SIGINT, sigint_handler);

    printf("Try hitting ^C...\n");

    for(;;);  // Wait here forever
}

One of the things you’ll notice is that on line 14 we reset the signal handler. This is because C has the option of resetting the signal handler to its SIG_DFL behavior before running your custom handler. In other words, it could be a one-off. So we reset it first thing so that we handle it again for the next one.

We’re ignoring the return value from signal() in this case. If we’d set it to a different handler earlier, it would return a pointer to that handler, which we could get like this:

    // old_handler is type "pointer to function that takes a single
    // int parameter and returns void":
    
    void (*old_handler)(int);
    
    old_handler = signal(SIGINT, sigint_handler);

That said, I’m not sure of a common use case for this. But if you need the old handler for some reason, you can get it that way.

Quick note on line 16—that’s just to tell the compiler to not warn that we’re not using this variable. It’s like saying, “I know I’m not using it; you don’t have to warn me.”

And lastly you’ll see that I’ve marked undefined behavior in a couple places. More on that in the next section.

29.4 What Can We Actually Do?

Turns out we’re pretty limited in what we can and can’t do in our signal handlers. This is one of the reasons why I say you shouldn’t even bother with this and instead use your OS’s signal handling instead (e.g. sigaction() for Unix-like systems).

Wikipedia goes so far as to say the only really portable thing you can do is call signal() with SIG_IGN or SIG_DFL and that’s it.

That last bit–sig_atomic_t–is your ticket to getting data out of a signal handler. (Unless you want to use lock-free atomic objects, which is outside the scope of this section¹⁴⁶.) It’s an integer type that might or might not be signed. And it’s bounded by what you can put in there.

You can look at the minimum and maximum allowable values in the macros SIG_ATOMIC_MIN and SIG_ATOMIC_MAX¹⁴⁷.

Confusingly, the spec also says you can’t refer “to any object with static or thread storage duration that is not a lock-free atomic object other than by assigning a value to an object declared as volatile sig_atomic_t […]”

My read on this is that you can’t read or write anything that’s not a lock-free atomic object. Also you can assign to an object that’s volatile sig_atomic_t.

But can you read from it? I honestly don’t see why not, except that the spec is very pointed about mentioning assigning into. But if you have to read it and make any kind of decision based on it, you might be opening up room for some kind of race conditions.

With that in mind, we can rewrite our “hit CTRL-C twice to exit” code to be a little more portable, albeit less verbose on the output.

Let’s change our SIGINT handler to do nothing except increment a value that’s of type volatile sig_atomic_t. So it’ll count the number of CTRL-Cs that have been hit.

Then in our main loop, we’ll check to see if that counter is over 2, then bail out if it is.

#include <stdio.h>
#include <signal.h>

volatile sig_atomic_t count = 0;

void sigint_handler(int signum)
{
    (void)signum;                    // Unused variable warning

    signal(SIGINT, sigint_handler);  // Reset signal handler

    count++;                         // Undefined behavior
}

int main(void)
{
    signal(SIGINT, sigint_handler);

    printf("Hit ^C twice to exit.\n");

    while(count < 2);
}

Undefined behavior again? It’s my read that this is, because we have to read the value in order to increment and store it. We can do some ridiculous contortions so that we’re only assigning into the values and manage to avoid undefined behavior.

#include <stdio.h>
#include <signal.h>

void sigint_handler_2(int signum)
{
    (void)signum;                      // Unused variable warning
    signal(SIGINT, SIG_DFL);           // Reset signal handler
}

void sigint_handler_1(int signum)
{
    (void)signum;                      // Unused variable warning
    signal(SIGINT, sigint_handler_2);  // Set to second handler
}

int main(void)
{
    signal(SIGINT, sigint_handler_1);

    printf("Hit ^C twice to exit.\n");

    while(1);
}

That’s pretty ugly, all right. Later when we look at lock-free atomic variables, we’ll see a way to fix the count version (assuming lock-free atomic variables are available on your particular system), but we’re getting into zanyland here.

This is why at the beginning, I was suggesting checking out your OS’s built-in signal system as a probably-superior alternative.

29.5 Friends Don’t Let Friends signal()

Again, use your OS’s built-in signal handling or the equivalent. It’s not in the spec, not as portable, but probably is far more capable. Plus your OS probably has a number of signals defined that aren’t in the C spec. And it’s difficult to write portable code using signal() anyway.

30 Variable-Length Arrays (VLAs)

C provides a way for you to declare an array whose size is determined at runtime. This gives you the benefits of dynamic runtime sizing like you get with malloc(), but without needing to worry about free()ing the memory after.

Now, a lot of people don’t like VLAs. They’ve been banned from the Linux kernel, for example. We’ll dig into more of that rationale later.

This is an optional feature of the language. The macro __STDC_NO_VLA__ is set to 1 if VLAs are not present. (They were mandatory in C99, and then became optional in C11.)

    #if __STDC_NO_VLA__ == 1
       #error Sorry, need VLAs for this program!
    #endif

Let’s dive in first with an example, and then we’ll look for the devil in the details.

30.1 The Basics

But with VLAs, we can use a size determined at runtime to set the array, like this:

    int n = 10;
    int v[n];

Now, that looks like the same thing, and in many ways is, but this gives you the flexibility to compute the size you need, and then get an array of exactly that size.

Let’s ask the user to input the size of the array, and then store the index-times-10 in each of those array elements:

#include <stdio.h>

int main(void)
{
    int n;

    printf("Enter a number: "); fflush(stdout);
    scanf(" %d", &n);

    int v[n];

    for (int i = 0; i < n; i++)
        v[i] = i * 10;

    for (int i = 0; i < n; i++)
        printf("v[%d] = %d\n", i, v[i]);
}

(On line 7, I have an fflush() that should force the line to output even though I don’t have a newline at the end.)

Line 10 is where we declare the VLA—once execution gets past that line, the size of the array is set to whatever n was at that moment. The array length can’t be changed later.

Also, entering a negative value for the size of the array invokes undefined behavior—in this universe, anyway.

30.2 sizeof and VLAs

We’re used to sizeof giving us the size in bytes of any particular object, including arrays. And VLAs are no exception.

The main difference is that sizeof on a VLA is executed at runtime, whereas on a non-variably-sized variable it is computed at compile time.

You can even compute the number of elements in a VLA with the usual array trick:

    size_t num_elems = sizeof v / sizeof v[0];

There’s a subtle and correct implication from the above line: pointer arithmetic works just like you’d expect for a regular array. So go ahead and use it to your heart’s content:

#include <stdio.h>

int main(void)
{
    int n = 5;
    int v[n];

    int *p = v;

    *(p+2) = 12;
    printf("%d\n", v[2]);  // 12

    p[3] = 34;
    printf("%d\n", v[3]);  // 34
}

30.3 Multidimensional VLAs

You can go ahead and make all kinds of VLAs with one or more dimensions set to a variable

    int w = 10;
    int h = 20;
    
    int x[h][w];
    int y[5][w];
    int z[10][w][20];

30.4 Passing One-Dimensional VLAs to Functions

Passing single-dimensional VLAs into a function can be no different than passing a regular array in. You just go for it.

#include <stdio.h>

int sum(int count, int *v)
{
    int total = 0;

    for (int i = 0; i < count; i++)
        total += v[i];

    return total;
}

int main(void)
{
    int x[5];   // Standard array

    int a = 5;
    int y[a];   // VLA

    for (int i = 0; i < a; i++)
        x[i] = y[i] = i + 1;

    printf("%d\n", sum(5, x));
    printf("%d\n", sum(a, y));
}

But there’s a bit more to it than that. You can also let C know that the array is a specific VLA size by passing that in first and then giving that dimension in the parameter list:

    int sum(int count, int v[count])
    {
        // ...
    }

Incidentally, there are a couple ways of listing a prototype for the above function; one of them involves an * if you don’t want to specifically name the value in the VLA. It just indicates that the type is a VLA as opposed to a regular pointer.

    void do_something(int count, int v[count]);  // With names
    void do_something(int, int v[*]);            // Without names

Again, that * thing only works with the prototype—in the function itself, you’ll have to put the explicit size.

30.5 Passing Multi-Dimensional VLAs to Functions

Same thing as we did with the second form of one-dimensional VLAs, above, but this time we’re passing in two dimensions and using those.

In the following example, we build a multiplication table matrix of a variable width and height, and then pass it into a function to print it out.

#include <stdio.h>

void print_matrix(int h, int w, int m[h][w])
{
    for (int row = 0; row < h; row++) {
        for (int col = 0; col < w; col++)
            printf("%2d ", m[row][col]);
        printf("\n");
    }
}

int main(void)
{
    int rows = 4;
    int cols = 7;

    int matrix[rows][cols];

    for (int row = 0; row < rows; row++)
        for (int col = 0; col < cols; col++)
            matrix[row][col] = row * col;

    print_matrix(rows, cols, matrix);
}

30.5.1 Partial Multidimensional VLAs

You can have some of the dimensions fixed and some variable. Let’s say we have a record length fixed at 5 elements, but we don’t know how many records there are.

#include <stdio.h>

void print_records(int count, int record[count][5])
{
    for (int i = 0; i < count; i++) {
        for (int j = 0; j < 5; j++)
            printf("%2d ", record[i][j]);
        printf("\n");
    }
}

int main(void)
{
    int rec_count = 3;
    int records[rec_count][5];

    // Fill with some dummy data
    for (int i = 0; i < rec_count; i++)
        for (int j = 0; j < 5; j++)
            records[i][j] = (i+1)*(j+2);

    print_records(rec_count, records);
}

30.6 Compatibility with Regular Arrays

Because VLAs are just like regular arrays in memory, it’s perfectly permissible to pass them interchangeably… as long as the dimensions match.

For example, if we have a function that specifically wants a $3\times5$ array, we can still pass a VLA into it.

    int foo(int m[5][3]) {...}
    
    \\ ...
    
    int w = 3, h = 5;
    int matrix[h][w];
    
    foo(matrix);   // OK!

    int foo(int h, int w, int m[h][w]) {...}
    
    \\ ...
    
    int matrix[3][5];
    
    foo(3, 5, matrix);   // OK!

Beware, through: if your dimensions mismatch, you’re going to have some undefined behavior going on, likely.

30.7 typedef and VLAs

Basically, typedef makes a new type with the values as they existed the moment the typedef was executed.

So it’s not a typedef of a VLA so much as a new fixed size array type of the dimensions at the time.

#include <stdio.h>

int main(void)
{
    int w = 10;

    typedef int goat[w];

    // goat is an array of 10 ints
    goat x;

    // Init with squares of numbers
    for (int i = 0; i < w; i++)
        x[i] = i*i;

    // Print them
    for (int i = 0; i < w; i++)
        printf("%d\n", x[i]);

    // Now let's change w...

    w = 20;

    // But goat is STILL an array of 10 ints, because that was the
    // value of w when the typedef executed.
}

30.8 Jumping Pitfalls

You have to watch out when using goto near VLAs because a lot of things aren’t legal.

And when you’re using longjmp() there’s a case where you could leak memory with VLAs.

30.9 General Issues

Other folks online point out that there’s no way to detect a VLA’s failure to allocate, and programs that suffered such problems would likely just crash. While fixed-size arrays also have the same issue, it’s far more likely that someone accidentally make a VLA Of Unusual Size than somehow accidentally declare a fixed-size, say, 30 megabyte array.

31 goto

The goto statement is universally revered and can be here presented without contest.

Just kidding! Over the years, there has been a lot of back-and-forth over whether or not (often not) goto is considered harmful ¹⁴⁹.

In this programmer’s opinion, you should use whichever constructs leads to the best code, factoring in maintainability and speed. And sometimes this might be goto!

In this chapter, we’ll see how goto works in C, and then check out some of the common cases where it is used¹⁵⁰.

31.1 A Simple Example

In this example, we’re going to use goto to skip a line of code and jump to a label. The label is the identifier that can be a goto target—it ends with a colon (:).

#include <stdio.h>

int main(void)
{
    printf("One\n");
    printf("Two\n");

    goto skip_3;

    printf("Three\n");

skip_3:

    printf("Five!\n");
}

goto sends execution jumping to the specified label, skipping everything in between.

    infinite_loop:
        print("Hello, world!\n");
        goto infinite_loop;

Labels are skipped over during execution. The following will print all three numbers in order just as if the labels weren’t there:

        printf("Zero\n");
    label_1:
    label_2:
        printf("One\n");
    label 3:
        printf("Two\n");
    label 4:
        printf("Three\n");

As you’ve noticed, it’s common convention to justify the labels all the way on the left. This increases readability because a reader can quickly scan to find the destination.

Labels have function scope. That is, no matter how many levels deep in blocks they appear, you can still goto them from anywhere in the function.

It also means you can only goto labels that are in the same function as the goto itself. Labels in other functions are out of scope from goto’s perspective. And it means you can use the same label name in two functions—just not the same label name in the same function.

31.2 Labeled continue

In some languages, you can actually specify a label for a continue statement. C doesn’t allow it, but you can easily use goto instead.

    for (int i = 0; i < 3; i++) {
        for (int j = 0; j < 3; j++) {
            printf("%d, %d\n", i, j);
            continue;   // Always goes to next j
        }
    }

As we see, that continue, like all continues, goes to the next iteration of the nearest enclosing loop. What if we want to continue in the next loop out, the loop with i?

    for (int i = 0; i < 3; i++) {
        for (int j = 0; j < 3; j++) {
            printf("%d, %d\n", i, j);
            break;     // Gets us to the next iteration of i
        }
    }

That gets us two levels of nested loop. But then if we nest another loop, we’re out of options. What about this, where we don’t have any statement that will get us out to the next iteration of i?

    for (int i = 0; i < 3; i++) {
        for (int j = 0; j < 3; j++) {
            for (int k = 0; k < 3; k++) {
                printf("%d, %d, %d\n", i, j, k);
    
                continue;  // Gets us to the next iteration of k
                break;     // Gets us to the next iteration of j
                ????;      // Gets us to the next iteration of i???
    
            }
        }
    }

        for (int i = 0; i < 3; i++) {
            for (int j = 0; j < 3; j++) {
                for (int k = 0; k < 3; k++) {
                    printf("%d, %d, %d\n", i, j, k);
    
                    goto continue_i;   // Now continuing the i loop!!
                }
            }
    continue_i: ;
        }

We have a ; at the end there—that’s because you can’t have a label pointing to the plain end of a compound statement (or before a variable declaration).

31.3 Bailing Out

When you’re super nested in the middle of some code, you can use goto to get out of it in a manner that’s often cleaner than nesting more ifs and using flag variables.

        // Pseudocode
    
        for(...) {
            for (...) {
                while (...) {
                    do {
                        if (some_error_condition)
                            goto bail;
    
                    } while(...);
                }
            }
        }
    
    bail:
        // Cleanup here

Without goto, you’d have to check an error condition flag in all of the loops to get all the way out.

31.4 Labeled break

This is a very similar situation to how continue only continues the innermost loop. break also only breaks out of the innermost loop.

        for (int i = 0; i < 3; i++) {
            for (int j = 0; j < 3; j++) {
                printf("%d, %d\n", i, j);
                break;   // Only breaks out of the j loop
            }
        }
    
        printf("Done!\n");

        for (int i = 0; i < 3; i++) {
            for (int j = 0; j < 3; j++) {
                printf("%d, %d\n", i, j);
                goto break_i;   // Now breaking out of the i loop!
            }
        }
    
    break_i:
    
        printf("Done!\n");

31.5 Multi-level Cleanup

If you’re calling multiple functions to initialize multiple systems and one of them fails, you should only de-initialize the ones that you’ve gotten to so far.

Let’s do a fake example where we start initializing systems and checking to see if any returns an error (we’ll use -1 to indicate an error). If one of them does, we have to shutdown only the systems we’ve initialized so far.

        if (init_system_1() == -1)
            goto shutdown;
    
        if (init_system_2() == -1)
            goto shutdown_1;
    
        if (init_system_3() == -1)
            goto shutdown_2;
    
        if (init_system_4() == -1)
            goto shutdown_3;
    
        do_main_thing();   // Run our program
    
        shutdown_system4();
    
    shutdown_3:
        shutdown_system3();
    
    shutdown_2:
        shutdown_system2();
    
    shutdown_1:
        shutdown_system1();
    
    shutdown:
        print("All subsystems shut down.\n");

Note that we’re shutting down in the reverse order that we initialized the subsystems. So if subsystem 4 fails to start up, it will shut down 3, 2, then 1 in that order.

31.6 Restarting Interrupted System Calls

Certain long-lived system calls might return an error if they’re interrupted by a signal, and errno will be set to EINTR to indicate the syscall was doing fine; it was just interrupted.

In those cases, it’s really common for the programmer to want to restart the call and try it again.

    retry:
        byte_count = read(0, buf, sizeof(buf) - 1);  // Unix read() syscall
    
        if (byte_count == -1) {            // An error occurred...
            if (errno == EINTR) {          // But it was just interrupted
                printf("Restarting...\n");
                goto retry;
            }

Many Unix-likes have an SA_RESTART flag you can pass to sigaction() to request the OS automatically restart any slow syscalls instead of failing with EINTR.

That said, it’s possible to use a similar technique any time any function should be restarted.

31.7 goto and Variable Scope

We’ve already seen that labels have function scope, but weird things can happen if we jump past some variable initialization.

Look at this example where we jump from a place where the variable x is out of scope into the middle of its scope (in the block).

        goto label;
    
        {
            int x = 12345;
    
    label:
            printf("%d\n", x);
        }

Basically what has happened is that we jumped into x’s scope (so it was OK to reference it in the printf()) but we jumped over the line that actually initialized it to 12345. So the value was indeterminate.

The fix is, of course, to get the initialization after the label one way or another.

        goto label;
    
        {
            int x;
    
    label:
            x = 12345;
            printf("%d\n", x);
        }

        {
            int x = 10;
    
    label:
    
            printf("%d\n", x);
        }
    
        goto label;

The first time through the block, we’re good. x is 10 and that’s what prints.

But after the goto, we’re jumping into the scope of x, but past its initialization. Which means we can still print it, but the value is indeterminate (since it hasn’t been reinitialized).

On my machine, it prints 10 again (to infinity), but that’s just luck. It could print any value after the goto since x is uninitialized.

31.8 goto and Variable-Length Arrays

When it comes to VLAs and goto, there’s one rule: you can’t jump from outside the scope of a VLA into the scope of that VLA.

        int x = 10;
    
        goto label;
    
        {
            int v[x];
    
    label:
    
            printf("Hi!\n");
        }

        int x = 10;
    
        goto label;
    
        {
    label:  ;
            int v[x];
    
            printf("Hi!\n");
        }

Because that way the VLA gets allocated properly before its inevitable deallocation once it falls out of scope.

32 Types Part V: Compound Literals and Generic Selections

They’re not particularly related, but don’t really each warrant their own chapters. So I crammed them in here like a rebel!

32.1 Compound Literals

This is a neat feature of the language that allows you to create an object of some type on the fly without ever assigning it to a variable. You can make simple types, arrays, structs, you name it.

One of the main uses for this is passing complex arguments to functions when you don’t want to make a temporary variable to hold the value.

The way you create a compound literal is to put the type name in parentheses, and then put an initializer list after. For example, an unnamed array of ints, might look like this:

Now, that line of code doesn’t do anything on its own. It creates an unnamed array of 4 ints, and then throws them away without using them.

    int *p = (int []){1 ,2 ,3 ,4};
    
    printf("%d\n", p[1]);  // 2

But that seems a little like a long-winded way to have an array. I mean, we could have just done this¹⁵¹:

    int p[] = {1, 2, 3, 4};
    
    printf("%d\n", p[1]);  // 2

32.1.1 Passing Unnamed Objects to Functions

    int sum(int p[], int count)
    {
        int total = 0;
    
        for (int i = 0; i < count; i++)
            total += p[i];
    
        return total;
    }

If we wanted to call it, we’d normally have to do something like this, declaring an array and storing values in it to pass to the function:

    int a[] = {1, 2, 3, 4};
    
    int s = sum(a, 4);

But unnamed objects give us a way to skip the variable by passing it directly in (parameter names listed above). Check it out—we’re going to replace the variable a with an unnamed array that we pass in as the second argument:

    //                   p[]         count
    //           |-----------------|  |
    int s = sum((int []){1, 2, 3, 4}, 4));

32.1.2 Unnamed structs

First, let’s do things without unnamed objects. We’ll define a struct to hold some x/y coordinates. Then we’ll define one, passing in values into its initializer. Finally, we’ll pass it to a function to print the values:

#include <stdio.h>

struct coord {
    int x, y;
};

void print_coord(struct coord c)
{
    printf("%d, %d\n", c.x, c.y);
}

int main(void)
{
    struct coord t = {.x=10, .y=20};

    print_coord(t);   // prints "10, 20"
}

Let’s modify it to use an unnamed object instead of the variable t we’re passing to print_coord().

    //struct coord t = {.x=10, .y=20};

    print_coord((struct coord){.x=10, .y=20});   // prints "10, 20"

32.1.3 Pointers to Unnamed Objects

You might have noticed in the last example that even through we were using a struct, we were passing a copy of the struct to print_coord() as opposed to passing a pointer to the struct.

Turns out, we can just take the address of an unnamed object with & like always.

This is because, in general, if an operator would have worked on a variable of that type, you can use that operator on an unnamed object of that type.

#include <stdio.h>

struct coord {
    int x, y;
};

void print_coord(struct coord *c)
{
    printf("%d, %d\n", c->x, c->y);
}

int main(void)
{
    //     Note the &
    //          |
    print_coord(&(struct coord){.x=10, .y=20});   // prints "10, 20"
}

    // Pass a pointer to an int with value 3490
    foo(&(int){3490});

32.1.4 Unnamed Objects and Scope

The lifetime of an unnamed object ends at the end of its scope. The biggest way this could bite you is if you make a new unnamed object, get a pointer to it, and then leave the object’s scope. In that case, the pointer will refer to a dead object.

    int *p;
    
    {
        p = &(int){10};
    }
    
    printf("%d\n", *p);  // INVALID: The (int){10} fell out of scope

Likewise, you can’t return a pointer to an unnamed object from a function. The object is deallocated when it falls out of scope:

#include <stdio.h>

int *get3490(void)
{
    // Don't do this
    return &(int){3490};
}

int main(void)
{
    printf("%d\n", *get3490());  // INVALID: (int){3490} fell out of scope
}

Just think of their scope like that of an ordinary local variable. You can’t return a pointer to a local variable, either.

32.1.5 Silly Unnamed Object Example

    int x = 3490;
    
    printf("%d\n", x);               // 3490 (variable)
    printf("%d\n", 3490);            // 3490 (constant)
    printf("%d\n", (int){3490});     // 3490 (unnamed object)

That last one is unnamed, but it’s silly. Might as well do the simple one on the line before.

32.2 Generic Selections

This is an expression that allows you select different pieces of code depending on the type of the first argument to the expression.

We’ll look at an example in just a second, but it’s important to know this is processed at compile time, not at runtime. There’s no runtime analysis going on here.

The expression begins with _Generic, works kinda like a switch, and it takes at least two arguments.

The first argument is an expression (or variable¹⁵²) that has a type. All expressions have a type. The remaining arguments to _Generic are the cases of what to substitute in for the result of the expression if the first argument is that type.

#include <stdio.h>

int main(void)
{
    int i;
    float f;
    char c;

    char *s = _Generic(i,
                    int: "that variable is an int",
                    float: "that variable is a float",
                    default: "that variable is some type"
                );

    printf("%s\n", s);
}

When the compiler sees it, it look at the type of the first argument. (In this example, the type of the variable i.) It then looks through the cases for something of that type. And then it substitutes the argument in place of the entire _Generic expression.

In this case, i is an int, so it matches that case. Then the string is substituted in for the expression. So the line turns into this when the compiler sees it:

        char *s = "that variable is an int";

If the compiler can’t find a type match in the _Generic, it looks for the optional default case and uses that.

If it can’t find a type match and there’s no default, you’ll get a compile error. The first expression must match one of the types or default.

Because it’s inconvenient to write _Generic over and over, it’s often used to make the body of a macro that can be easily repeatedly reused.

Let’s make a macro TYPESTR(x) that takes an argument and returns a string with the type of the argument.

    #include <stdio.h>
    
    #define TYPESTR(x) _Generic((x), \
                            int: "int", \
                            long: "long", \
                            float: "float", \
                            double: "double", \
                            default: "something else")
    
    int main(void)
    {
        int i;
        long l;
        float f;
        double d;
        char c;
    
        printf("i is type %s\n", TYPESTR(i));
        printf("l is type %s\n", TYPESTR(l));
        printf("f is type %s\n", TYPESTR(f));
        printf("d is type %s\n", TYPESTR(d));
        printf("c is type %s\n", TYPESTR(c));
    }

Which should be no surprise, because, like we said, that code in main() is replaced with the following when it is compiled:

        printf("i is type %s\n", "int");
        printf("l is type %s\n", "long");
        printf("f is type %s\n", "float");
        printf("d is type %s\n", "double");
        printf("c is type %s\n", "something else");

    int i = 10;
    char *s = "Foo!";
    
    PRINT_VAL(i);
    PRINT_VAL(s);

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

// Macro that gives back a format specifier for a type
#define FMTSPEC(x) _Generic((x), \
                        int: "%d", \
                        long: "%ld", \
                        float: "%f", \
                        double: "%f", \
                        char *: "%s")
                        // TODO: add more types
                        
// Macro that prints a variable in the form "name = value"
#define PRINT_VAL(x) { \
    char fmt[512]; \
    snprintf(fmt, sizeof fmt, #x " = %s\n", FMTSPEC(x)); \
    printf(fmt, (x)); \
}

int main(void)
{
    int i = 10;
    float f = 3.14159;
    char *s = "Hello, world!";

    PRINT_VAL(i);
    PRINT_VAL(f);
    PRINT_VAL(s);
}

We could have crammed that all in one big macro, but I broke it into two to prevent eye bleeding.

33 Arrays Part II

We’re going to go over a few extra misc things this chapter concerning arrays.

They’re not super-commonly seen, but we’ll peek at them since they’re part of the newer spec.

33.1 Type Qualifiers for Arrays in Parameter Lists

If you recall from earlier, these two things are equivalent in function parameter lists:

    int func(int *p) {...}
    int func(int p[]) {...}

And you might also recall that you can add type qualifiers to a pointer variable like so:

    int *const p;
    int *volatile p;
    int *const volatile p;
    // etc.

But how can we do that when we’re using array notation in your parameter list?

Turns out it goes in the brackets. And you can put the optional count after. The two following lines are equivalent:

    int func(int *const volatile p) {...}
    int func(int p[const volatile]) {...}
    int func(int p[const volatile 10]) {...}

If you have a multidimensional array, you need to put the type qualifiers in the first set of brackets.

33.2 static for Arrays in Parameter Lists

This is something I’ve never seen in the wild. It is always followed by a dimension:

    int func(int p[static 4]) {...}

What this means, in the above example, is the compiler is going to assume that any array you pass to the function will be at least 4 elements.

    int func(int p[static 4]) {...}
    
    int main(void)
    {
        int a[] = {11, 22, 33, 44};
        int b[] = {11, 22, 33, 44, 55};
        int c[] = {11, 22};
    
        func(a);  // OK! a is 4 elements, the minimum
        func(b);  // OK! b is at least 4 elements
        func(c);  // Undefined behavior! c is under 4 elements!
    }

Important note: there is nothing in the compiler that prohibits you from passing in a smaller array. The compiler probably won’t warn you, and it won’t detect it at runtime.

By putting static in there, you’re saying, “I double secret PROMISE that I will never pass in a smaller array than this.” And the compiler says, “Yeah, fine,” and trusts you to not do it.

And then the compiler can make certain code optimizations, safe in the knowledge that you, the programmer, will always do the right thing.

33.3 Equivalent Initializers

C is a little bit, shall we say, flexible when it comes to array initializers.

We’ve already seen some of this, where any missing values are replaced with zero.

    int a[5] = {1, 2};

    #include <stdio.h>
    
    int main(void)
    {
        int a[3][2] = {
            {1, 2},
            {3, 4},
            {5, 6}
        };
    
        for (int row = 0; row < 3; row++) {
            for (int col = 0; col < 2; col++)
                printf("%d ", a[row][col]);
            printf("\n");
        }
    }

Let’s leave off some of the initializer elements and see they get set to zero:

        int a[3][2] = {
            {1, 2},
            {3},    // Left off the 4!
            {5, 6}
        };

        int a[3][2] = {
            {1, 2},
            // {3, 4},   // Just cut this whole thing out
            {5, 6}
        };

But if you stop to think about it, we only provided enough initializers for two rows, so they got used for the first two rows. And the remaining elements were initialized to zero.

So far so good. Generally, if we leave off parts of the initializer, the compiler sets the corresponding elements to 0.

        int a[3][2] = { 1, 2, 3, 4, 5, 6 };

Turns out that’s legal (though GCC will warn about it with the proper warnings turned on).

Basically, what it does is starts filling in elements in row 0, then row 1, then row 2 from left to right.

        int a[3][2] = { 1, 2, 3 };

        int a[3][2] = {0};

But my recommendation is if you have a 2D array, use a 2D initializer. It just makes the code more readable. (Except for initializing the whole array with 0, in which case it’s idiomatic to use {0} no matter the dimension of the array.)

34 Long Jumps with setjmp, longjmp

We’ve already seen goto, which jumps in function scope. But longjmp() allows you to jump back to an earlier point in execution, back to a function that called this one.

There are a lot of limitations and caveats, but this can be a useful function for bailing out from deep in the call stack back up to an earlier state.

34.1 Using setjmp and longjmp

The dance we’re going to do here is to basically put a bookmark in execution with setjmp(). Later on, we’ll call longjmp() and it’ll jump back to the earlier point in execution where we set the bookmark with setjmp().

Here’s a quick demo where we call into functions a couple levels deep and then bail out of it.

We’re going to use a file scope variable env to keep the state of things when we call setjmp() so we can restore them when we call longjmp() later. This is the variable in which we remember our “place”.

The variable env is of type jmp_buf, an opaque type declared in <setjmp.h>.

#include <stdio.h>
#include <setjmp.h>

jmp_buf env;

void depth2(void)
{
    printf("Entering depth 2\n");
    longjmp(env, 3490);           // Bail out
    printf("Leaving depth 2\n");  // This won't happen
}

void depth1(void)
{
    printf("Entering depth 1\n");
    depth2();
    printf("Leaving depth 1\n");  // This won't happen
}

int main(void)
{
    switch (setjmp(env)) {
    case 0:
        printf("Calling into functions, setjmp() returned 0\n");
        depth1();
        printf("Returned from functions\n");  // This won't happen
        break;

    case 3490:
        printf("Bailed back to main, setjmp() returned 3490\n");
        break;
    }
}

If you try to take that output and match it up with the code, it’s clear there’s some really funky stuff going on.

One of the most notable things is that setjmp() returns twice. What the actual frank? What is this sorcery?!

So here’s the deal: if setjmp() returns 0, it means that you’ve successfully set the “bookmark” at that point.

If it returns non-zero, it means you’ve just returned to the “bookmark” set earlier. (And the value returned is the one you pass into longjmp().)

This way you can tell the difference between setting the bookmark and returning to it later.

So when the code, above, calls setjmp() the first time, setjmp() stores the state in the env variable and returns 0. Later when we call longjmp() with that same env, it restores the state and setjmp() returns the value longjmp() was passed.

34.2 Pitfalls

Under the hood, this is pretty straightforward. Typically the stack pointer keeps track of the locations in memory that local variables are stored, and the program counter keeps track of the address of the currently-executing instruction¹⁵³.

So if we want to jump back to an earlier function, it’s basically only a matter of restoring the stack pointer and program counter to the values kept in the jmp_buf variable, and making sure the return value is set correctly. And then execution will resume there.

But a variety of factors confound this, making a significant number of undefined behavior traps.

34.2.1 The Values of Local Variables

If you want the values of automatic (non-static and non-extern) local variables to persist in the function that called setjmp() after a longjmp() happens, you must declare those variables to be volatile.

Technically, they only have to be volatile if they change between the time setjmp() is called and longjmp() is called¹⁵⁴.

    int x = 20;
    
    if (setjmp(env) == 0) {
        x = 30;
    }

    volatile int x = 20;
    
    if (setjmp(env) == 0) {
        x = 30;
    }

Now the value will be the correct 30 after a longjmp() returns us to this point.

34.2.2 How Much State is Saved?

When you longjmp(), execution resumes at the point of the corresponding setjmp(). And that’s it.

The spec points out that it’s just as if you’d jumped back into the function at that point with local variables set to whatever values they had when the longjmp() call was made.

34.2.3 You Can’t Name Anything setjmp

You can’t have any extern identifiers with the name setjmp. Or, if setjmp is a macro, you can’t undefine it.

34.2.4 You Can’t setjmp() in a Larger Expression

    if (x == 12 && setjmp(env) == 0) { ... }

That’s too complex to be allowed by the spec due to the machinations that must occur when unrolling the stack and all that. We can’t longjmp() back into some complex expression that’s only been partially executed.

34.2.5 When Can’t You longjmp()?

On that last one, “exited” includes normal returns from the function, as well as the case if another longjmp() jumped back to “earlier” in the call stack than the function in question.

34.2.6 You Can’t Pass 0 to longjmp()

If you try to pass the value 0 to longjmp(), it will silently change that value to 1.

Since setjmp() ultimately returns this value, and having setjmp() return 0 has special meaning, returning 0 is prohibited.

34.2.7 `longjmp() and Variable Length Arrays

If you are in scope of a VLA and longjmp() out there, the memory allocated to the VAL could leak¹⁵⁵.

Same thing happens if you longjmp() back over any earlier functions that had VLAs still in scope.

This is one thing that really bugged me able VLAs—that you could write perfectly legitimate C code that squandered memory. But, hey—I’m not in charge of the spec.

35 Incomplete Types

extern int a[];

int main(void)
{
    struct foo *x;
    union bar *y;
    enum baz *z;
}

We never gave a size for a. And we have pointers to structs foo, bar, and baz that never seem to be declared anywhere.

An incomplete type is a type the size (i.e. the size you’d get back from sizeof) for which is not known. Another way to think of it is a type that you haven’t finished declaring.

You can have a pointer to an incomplete type, but you can’t dereference it or use pointer arithmetic on it. And you can’t sizeof it.

35.1 Use Case: Self-Referential Structures

I only know of one real use case: forward references to structs or unions with self-referential or co-dependent structures. (I’m going to use struct for the rest of these examples, but they all apply equally to unions, as well.)

But before I do, know this! As you declare a struct, the struct is incomplete until the closing brace is reached!

    struct antelope {              // struct antelope is incomplete here
        int leg_count;             // Still incomplete
        float stomach_fullness;    // Still incomplete
        float top_speed;           // Still incomplete
        char *nickname;            // Still incomplete
    };                             // NOW it's complete.

But what if we’re doing a linked list? Each linked list node needs to have a reference to another node. But how can we create a reference to another node if we haven’t finished even declaring the node yet?

C’s allowance for incomplete types makes it possible. We can’t declare a node, but we can declare a pointer to one, even if it’s incomplete!

struct node {
    int val;
    struct node *next;  // struct node is incomplete, but that's OK!
};

Even though the struct node is incomplete on line 3, we can still declare a pointer to one¹⁵⁶.

We can do the same thing if we have two different structs that refer to each other:

    struct a {
        struct b *x;  // Refers to a `struct b`
    };
    
    struct b {
        struct a *x;  // Refers to a `struct a`
    };

We’d never be able to make that pair of structures without the relaxed rules for incomplete types.

35.2 Incomplete Type Error Messages

Most likely culprit: you probably forgot to #include the header file that declares the type.

35.3 Other Incomplete Types

Declaring a struct or union with no body makes an incomplete type, e.g. struct foo;.

If it’s a non-extern array with no size followed by an initializer, it’s incomplete until the closing brace of the initializer.

35.4 Use Case: Arrays in Header Files

It can be useful to declare incomplete array types in header files. In those cases, the actual storage (where the complete array is declared) should be in a single .c file. If you put it in the .h file, it will be duplicated every time the header file is included.

So what you can do is make a header file with an incomplete type that refers to the array, like so:

// File: bar.h

#ifndef BAR_H
#define BAR_H

extern int my_array[];  // Incomplete type

#endif

// File: bar.c

int my_array[1024];     // Complete type!

Then you can include the header from as many places as you’d like, and every one of those places will refer to the same underlying my_array.

// File: foo.c

#include <stdio.h>
#include "bar.h"    // includes the incomplete type for my_array

int main(void)
{
    my_array[0] = 10;

    printf("%d\n", my_array[0]);
}

When compiling multiple files, remember to specific all the .c files to the compiler, but not the .h files, e.g.:

35.5 Completing Incomplete Types

If you have an incomplete type, you can complete it by defining the complete struct, union, enum, or array in the same scope.

    struct foo;        // incomplete type
    
    struct foo *p;     // pointer, no problem
    
    // struct foo f;   // Error: incomplete type!
    
    struct foo {
        int x, y, z;
    };                 // Now the struct foo is complete!
    
    struct foo f;      // Success!

Note that though void is an incomplete type, there’s no way to complete it. Not that anyone ever thinks of doing that weird thing. But it does explain why you can do this:

    void *p;             // OK: pointer to incomplete type

    void v;              // Error: declare variable of incomplete type
    
    printf("%d\n", *p);  // Error: dereference incomplete type

36 Complex Numbers

But that’s as far as I’m going to go. We’ll assume that if you’re reading this chapter, you know what a complex number is and what you want to do with them.

Turns out, though, that complex number support in a compiler is an optional feature. Not all compliant compilers can do it. And the ones that do, might do it to various degrees of completeness.

    #ifdef __STDC_NO_COMPLEX__
    #error Complex numbers not supported!
    #endif

Furthermore, there is a macro that indicates adherence to the ISO 60559 (IEEE 754) standard for floating point math with complex numbers, as well as the presence of the _Imaginary type.

36.1 Complex Types

Those both mean the same thing, so you might as well use the prettier complex.

You also get some types for imaginary numbers if you implementation is IEC 60559-compliant:

    _Imaginary
    imaginary

These also both mean the same thing, so you might as well use the prettier imaginary.

    I
    _Complex_I
    _Imaginary_I

The macro I is set to _Imaginary_I (if available), or _Complex_I. So just use I for the imaginary number.

One aside: I’ve said that if a compiler has __STDC_IEC_559_COMPLEX__ set to 1, it must support _Imaginary types to be compliant. That’s my read of the spec. However, I don’t know of a single compiler that actually supports _Imaginary even though they have __STDC_IEC_559_COMPLEX__ set. So I’m going to write some code with that type in here I have no way of testing. Sorry!

36.2 Assigning Complex Numbers

Since the complex number has a real and imaginary part, but both of them rely on floating point numbers to store values, we need to also tell C what precision to use for those parts of the complex number.

We do that by just pinning a float, double, or long double to the complex, either before or after it.

    float complex c;   // Spec prefers this way
    complex float c;   // Same thing--order doesn't matter

So that’s great for declarations, but how do we initialize them or assign to them?

Signal	Description
`SIGABRT`	Abnormal termination—what happens when `abort()` is called.
`SIGFPE`	Floating point exception.
`SIGILL`	Illegal instruction.
`SIGINT`	Interrupt—usually the result of `CTRL-C` being hit.
`SIGSEGV`	“Segmentation Violation”: invalid memory access.
`SIGTERM`	Termination requested.

1 Foreword

1.1 Audience

1.2 Platform and Compiler

1.3 Official Homepage

1.4 Email Policy

1.5 Mirroring

1.6 Note for Translators

1.7 Copyright and Distribution

2 Hello, World!

2.1 What to Expect from C

2.2 Hello, World!

2.3 Compilation

2.4 Building with gcc

2.5 C Versions

3 Variables and Statements

3.1 Variables

3.1.1 Variable Names

3.1.2 Variable Types

3.1.3 Boolean Types

3.2 Operators and Expressions

3.2.1 The sizeof Operator

3.2.2 Arithmetic

3.2.3 Ternary Operator

3.2.4 Pre-and-Post Increment-and-Decrement

3.2.5 The Comma Operator

3.2.6 Conditional Operators

3.2.7 Boolean Operators

3.3 Flow Control

3.3.1 The if statement

3.3.2 The while statement

3.3.3 The do-while statement

3.3.4 The for statement

3.3.5 The switch Statement

4 Functions

4.1 Passing by Value

4.2 Function Prototypes

4.3 Empty Parameter Lists

5 Pointers—Cower In Fear!

5.1 Memory and Variables

5.2 Pointer Types

5.3 Dereferencing

5.4 Passing Pointers as Parameters

5.5 The NULL Pointer

5.6 A Note on Declaring Pointers

5.7 sizeof and Pointers

6 Arrays

6.1 Easy Example

6.2 Getting the Length of an Array

6.3 Array Initializers

6.4 Out of Bounds!

6.5 Multidimensional Arrays

6.6 Arrays and Pointers

6.6.1 Getting a Pointer to an Array

6.6.2 Passing Single Dimensional Arrays to Functions

6.6.3 Changing Arrays in Functions

6.6.4 Passing Multidimensional Arrays to Functions

7 Strings

7.1 Constant Strings

7.2 String Variables

7.3 String Variables as Arrays

7.4 String Initializers

7.5 Getting String Length

7.6 String Termination

7.7 Copying a String

8 Structs

8.1 Declaring a Struct

8.2 Struct Initializers

8.3 Passing Structs to Functions

8.4 The Arrow Operator

8.5 Copying and Returning structs

9 File Input/Output

9.1 The FILE* Data Type

9.2 Reading Text Files

9.3 End of File: EOF

9.3.1 Reading a Line at a Time

9.4 Formatted Input

9.5 Writing Text Files

9.6 Binary File I/O

9.6.1 struct and Number Caveats

10 typedef: Making New Types

2.4 Building with `gcc`

3.2.1 The `sizeof` Operator

3.3.1 The `if` statement

3.3.2 The `while` statement

3.3.3 The `do-while` statement

3.3.4 The `for` statement

3.3.5 The `switch` Statement

5.5 The `NULL` Pointer

5.7 `sizeof` and Pointers

8.5 Copying and Returning `struct`s

9.1 The `FILE*` Data Type

9.3 End of File: `EOF`

9.6.1 `struct` and Number Caveats

10 `typedef`: Making New Types

10.1 `typedef` in Theory

10.2 `typedef` in Practice

10.2.1 `typedef` and `struct`s

10.2.2 `typedef` and Other Types

10.2.3 `typedef` and Pointers

10.2.4 `typedef` and Capitalization

10.3 Arrays and `typedef`

11.3 `void` Pointers

12.1 Allocating and Deallocating, `malloc()` and `free()`

12.4 An Alternative: `calloc()`

12.5 Changing Allocated Size with `realloc()`

12.5.2 `realloc()` with `NULL`

13.3 `for`-loop Scope

14.3 More Integer Types: `short`, `long`, `long long`

14.4 More Float: `double` and `long double`

15.3.3 `void*`

16.1.1 `const`

16.1.1.1 `const` and Pointers

16.1.1.2 `const` Correctness

16.1.2 `restrict`

16.1.3 `volatile`

16.1.4 `_Atomic`