Functions, scope, the stack and header files

Functions in C play the same role as in Python: they name a piece of work, take parameters, return a result and let you decompose a program into parts that can be understood and tested separately. C adds rules Python does not have. Every function has a declared return type and parameter types; a function must be declared before it is called; arguments are always passed by value, so a function receives copies; and every call creates a stack frame holding its parameters and local variables, which disappears when the function returns. This lesson covers defining and declaring functions, pass-by-value, scope and storage duration (local, static and global variables), how the call stack works, recursion, and how to design a module's interface in a header file. It ends with a first look at gdb, the debugger, showing the call stack of a running program.

Defining and declaring functions

A function definition gives the return type, the name, the parameter list with a type for each parameter, and the body. A function that returns nothing has return type void, and a function that takes no parameters should say so with (void); in C17 an empty pair of parentheses means "unspecified parameters", an old rule that turns off checking (C23 finally made () mean no parameters). The compiler reads a file from top to bottom, so it must see either the definition or a declaration of a function before the first call. A declaration, or prototype, is the first line of the definition followed by a semicolon. Small programs often define helper functions above main; larger ones put prototypes in headers, as lesson 2 showed.

#include <stdio.h>

double celsius_to_fahrenheit(double c);     /* prototype: declared before use */
static void print_row(double c);

int main(void) {
    for (double c = -40.0; c <= 40.0; c += 20.0) {
        print_row(c);
    }
    return 0;
}

double celsius_to_fahrenheit(double c) {     /* definition */
    return c * 9.0 / 5.0 + 32.0;
}

static void print_row(double c) {
    printf("%6.1f C = %6.1f F\n", c, celsius_to_fahrenheit(c));
}

 -40.0 C =  -40.0 F
 -20.0 C =   -4.0 F
   0.0 C =   32.0 F
  20.0 C =   68.0 F
  40.0 C =  104.0 F

The word static in front of print_row gives the function internal linkage: it is visible only inside this source file, and the linker will not let other files call it. Mark helper functions static unless they are part of a module's public interface; this keeps the global namespace clean and lets the compiler optimize more. celsius_to_fahrenheit has external linkage, the default, so another file could declare and call it.

Pass by value

When you call a function in C, each argument is evaluated and its value is copied into the corresponding parameter, which is a new local variable of the called function. Changing a parameter therefore changes only the copy. This is simpler than Python's rule of passing references to objects, but it means a function cannot change its caller's variables directly. The classic demonstration is a swap function.

#include <stdio.h>

static void swap_wrong(int a, int b) {
    int tmp = a;
    a = b;
    b = tmp;
    printf("  inside swap_wrong: a=%d b=%d\n", a, b);
}

static void swap(int *a, int *b) {      /* receives the addresses */
    int tmp = *a;
    *a = *b;
    *b = tmp;
}

int main(void) {
    int x = 1, y = 2;
    swap_wrong(x, y);
    printf("after swap_wrong: x=%d y=%d\n", x, y);
    swap(&x, &y);
    printf("after swap:       x=%d y=%d\n", x, y);
    return 0;
}

  inside swap_wrong: a=2 b=1
after swap_wrong: x=1 y=2
after swap:       x=2 y=1

swap_wrong exchanges its own copies and then discards them. The working version receives the addresses of x and y, written &x and &y, and uses the * operator to reach the caller's variables through those addresses. That is a pointer, the subject of lesson 5. For now the point is that pass-by-value is universal in C: even the pointer is passed by value, but a copy of an address still leads to the same variable. The same mechanism is how a function returns more than one result, and how standard functions such as scanf store values into your variables.

Arrays are the one apparent exception. When you pass an array to a function, C passes the address of its first element rather than copying the whole array, so the function can change the caller's elements. Lesson 6 explains why. Mark array and pointer parameters const when the function only reads them, as mean did in lesson 2, so that the compiler stops accidental changes and readers know the function is safe to call.

Scope and storage duration

Scope is the part of the program where a name can be used. A variable declared inside a block, between braces, has block scope: it exists from its declaration to the closing brace, and a variable declared in an inner block can hide one with the same name in an outer block (-Wshadow warns about this). A variable declared outside all functions has file scope and can be used anywhere below its declaration in the file.

Storage duration is how long the variable's memory exists. Local variables normally have automatic storage duration: they are created when execution enters their block and destroyed when it leaves, and they start with indeterminate values, so reading one before assigning it is a bug that -Wall often catches. Variables at file scope, and local variables declared static, have static storage duration: they exist for the whole run of the program, are initialized once before main starts, and are set to zero if you give no initializer. A static local variable therefore keeps its value between calls.

#include <stdio.h>

static int calls_total = 0;          /* file scope, static duration, internal linkage */

static int next_ticket(void) {
    static int ticket = 100;         /* initialized once, keeps its value */
    calls_total++;
    return ticket++;
}

int main(void) {
    for (int i = 0; i < 3; i++) {
        int local = i * 10;          /* automatic: new each time round the loop */
        printf("ticket %d, local %d\n", next_ticket(), local);
    }
    printf("next_ticket was called %d times\n", calls_total);
    return 0;
}

ticket 100, local 0
ticket 101, local 10
ticket 102, local 20
next_ticket was called 3 times

Global variables, file-scope variables with external linkage, can be shared between files: one file defines int verbose = 0; and a header declares extern int verbose; so other files can use it. Use them sparingly. Any function anywhere can change a global, which makes programs hard to reason about and test; passing values as parameters is almost always clearer. The static keyword at file scope keeps a variable private to its file, a good compromise for state that one module needs to remember.

The call stack

Each time a function is called, the program reserves a block of memory called a stack frame or activation record. It holds the function's parameters, its local variables, the address to return to when the function finishes, and some saved processor state. The frames are kept on the call stack, a region of memory that grows when functions are called and shrinks when they return, in strict last-in, first-out order. When a function returns, its frame is popped and its local variables cease to exist; that is why returning the address of a local variable is a serious bug, because the address points into memory that will soon be reused.

Recursion works because every call has its own frame with its own copies of the parameters. The factorial function below calls itself with a smaller n until it reaches the base case; then the frames return one by one, multiplying as they go. Recursion is elegant for problems that are naturally self-similar, such as tree traversal and divide-and-conquer algorithms, which CMPUT-204 studies. But the stack is limited, typically 8 MB for the main thread on Linux, so very deep recursion causes a stack overflow and the program crashes with a segmentation fault. C compilers may turn some tail calls into loops at -O2, but the standard does not guarantee it, so for a loop of a million steps write a loop.

#include <stdio.h>

static long factorial(int n) {
    if (n <= 1) {
        return 1;          /* base case */
    }
    return n * factorial(n - 1);
}

int main(void) {
    printf("5! = %ld\n", factorial(5));
    return 0;
}

5! = 120

The debugger gdb can show the call stack of a running program. In the session below, gdb stops the program each time factorial is entered with n equal to 1, and the backtrace command, bt, lists every frame from the innermost outward, with the value of each parameter. Lesson 11 covers gdb fully; here it is a window into the stack. The gdb commands are given in batch mode so the whole session runs without typing.

gcc -std=c17 -Wall -Wextra -g -O0 fact.c -o fact
gdb -q -batch -ex "break factorial if n == 1" -ex run -ex bt ./fact

Breakpoint 1 at 0x1159: file fact.c, line 4.

Breakpoint 1, factorial (n=1) at fact.c:4
4	    if (n <= 1) {
#0  factorial (n=1) at fact.c:4
#1  0x0000555555555179 in factorial (n=2) at fact.c:7
#2  0x0000555555555179 in factorial (n=3) at fact.c:7
#3  0x0000555555555179 in factorial (n=4) at fact.c:7
#4  0x0000555555555179 in factorial (n=5) at fact.c:7
#5  0x0000555555555195 in main () at fact.c:11

Frame #0 is the innermost call, factorial(n=1), and frame #5 is main. Each frame line gives the function, its arguments and the source line where it is currently executing, which is exactly the information you need when a program crashes deep inside a chain of calls.

Designing interfaces with headers

A header file is a contract between a module and its users. It should declare only what users need: the public functions with clear names and parameter types, any types and constants they need to call those functions, and comments describing what each function does, what it requires of its arguments and what it returns. Everything else, helper functions and private state, stays in the .c file and is marked static. This separation, an interface hiding an implementation, is the same abstraction CMPUT-174 described, enforced by the compiler and linker instead of by convention.

/* temperature.h - conversions between temperature scales */
#ifndef TEMPERATURE_H
#define TEMPERATURE_H

#include <stdbool.h>

/* Absolute zero in degrees Celsius. */
#define ABSOLUTE_ZERO_C (-273.15)

/* Convert Celsius to Fahrenheit. */
double c_to_f(double celsius);

/* Convert Fahrenheit to Celsius. */
double f_to_c(double fahrenheit);

/* Return true if the Celsius temperature is physically possible. */
bool is_valid_celsius(double celsius);

#endif

A good header compiles on its own: it includes the headers it needs, such as stdbool.h for bool, so that users can include it in any order. It never defines variables or function bodies (except static inline functions, an advanced case), because that would cause multiple definitions when two files include it. Finally, the module's own .c file should include its header first, which checks that the header is self-contained and that the definitions match the declarations.