1.4. Functions

Functions break code into manageable pieces and reduce code duplication. Functions may take zero or more parameters as input and they return a single value of a specific type. A function declaration or prototype specifies the function’s name, its return type, and its parameter list (the number and type of all parameters). A function definition includes the code to be executed when the function is called. All functions in C must be declared before they are called. This can be done by declaring a function prototype or by fully defining the function before calling it.

 function definition format:
 ---------------------------
 <return type> <function name> (<parameter list>)
 {
     <function body>
 }

 parameter list format:
 ---------------------
 <type> <parm1 name>, <type> <parm2 name>, ...,  <type> <last parm name>

Here’s an example function definition. Note the comments that describe what the function does, the details of each parameter (what it’s used for, what it should be passed), and what the function returns:

/* This program computes the larger of two
 * values entered by a user.
 */
#include <stdio.h>

/* max: computes the larger of two integer values
 *   x: one integer value
 *   y: the other integer value
 *   returns: the larger of x and y
 */
int max(int x, int y) {
    int bigger;

    bigger = x;
    if (y > x) {
        bigger = y;
    }
    printf("  in max, before return x: %d y: %d\n", x, y);
    return bigger;
}

Functions that do not return a value should specify the void return type. Here’s an example of a void function:

/* prints out the squares from start to stop
 *   start: the beginning of the range
 *   stop: the end of the range
 */
void print_table(int start, int stop) {
    int i;

    for(i=start; i <= stop; i++) {
        printf("%d\t",i*i);
    }
    printf("\n");
}

As in any programming language that supports functions or procedures, a function call invokes a function, passing specific argument values for the particular call. A function is called by its name and is passed arguments, with one argument for each corresponding function parameter. In C, calling a function looks like:

 function call format:
 ---------------------
 function_name(<argument list>);


 argument list format:
 ---------------------
 <argument 1 expression>, <argument 2 expression>, ...,  <last argument expression>

Arguments to C functions are passed by value: each function parameter is assigned the value of its corresponding argument, passed to it in the function call by the caller. Pass by value semantics mean that any change to a parameter’s value in the function (i.e. assigning a parameter a new value in the function) is not visible to the caller.

Here are some example function calls to the max and print_table functions listed above:

int val1, val2, result;

val1 = 6;
val2 = 10;

/* to call max, pass in two int values, and because max returns an
   int value, assign its return value to a local variable  (result)
 */
result = max(val1, val2);   /* call max with argument values 6 and 10 */
printf("%d\n", result);     /* prints out 10 */

result = max(11, 3);        /* call max with argument values 11 and 3 */
printf("%d\n", result);     /* prints out 11 */

result = max(val1 * 2, val2); /* call max with argument values 12 and 10 */
printf("%d\n", result);       /* prints out 12 */

/* print_table does not return a value, but takes two arguments */
print_table(1, 20);       /* prints a table of values from 1 to 20 */
print_table(val1, val2);  /* prints a table of values from 6 to 10 */

Here is another example of a full program that shows a call to a slightly different implementation of the max function that has an additional statement to change the value of its parameter (x = y):

/* max: computes the larger of two int values
 *   x: one value
 *   y: the other value
 *   returns: the larger of x and y
 */
int max(int x, int y) {
    int bigger;

    bigger = x;
    if(y > x) {
        bigger = y;
        // note: changing the parameter x's value here will not
        //        change the value of its corresponding argument
        x = y;
    }
    printf("  in max, before return x: %d y: %d\n", x, y);

    return bigger;
}

/* main: shows a call to max */
int main() {
    int a, b, res;

    printf("Enter two integer values: ");
    scanf("%d%d", &a, &b);

    res = max(a, b);
    printf("The larger value of %d and %d is %d\n", a, b, res);

    return 0;
}

The output below shows what two runs of this program might look like. Note the difference in the parameter x’s value (printed from inside the max function) in the two runs. Specifically, notice that changing the value of parameter x in the second run does not affect the variable that was passed in as an argument to max after the call returns:

$ ./a.out
Enter two integer values: 11  7
  in max, before return x: 11 y: 7
The larger value of 7 and 11 is 11

$ ./a.out
Enter two integer values: 13  100
  in max, before return x: 100 y: 100
The larger value of 13 and 100 is 100

Because arguments are passed by value to functions, the above version of the max function that changes one of its parameter values behaves identically to the original version of max that does not.

1.4.1. The Stack

The execution stack keeps track of the state of active functions in the program. Each function call creates a new stack frame (sometimes called an activation frame or activation record) containing its parameter and local variable values. The frame on the top of the stack is the active frame; it represents the function activation that is currently executing and only its local variables and parameters are in scope. When a function is called, a new stack frame is created for it ("pushed on the top of the stack"), and space for its local variables and parameters are allocated in the new frame. When a function returns, its stack frame is removed from the stack ("popped from the top of the stack"), leaving the caller’s stack frame on the top of the stack.

For the example program above, at the point in its execution right before max executes the return statement, the execution stack will look like Figure 1. Recall that the argument values to max passed by main are passed by value, meaning that the parameters to max, x and y, are assigned the value of their corresponding arguments,a and b from the call in main. Despite the max function changing the value of x, the change does not affect the value of a in main.

A stack with two frames: main at the bottom, and max on top of it.  Main’s stack frame has three variables, a (11), b (7) and res (undefined at this point).  Max’s stack frame also has three variables, x (11), y (7), and bigger (11).
Figure 1. The execution stack contents just before returning from the max function.

Below is a full program that includes two functions and shows examples of calling them from the main function. In this program, we declare function prototypes for max and print_table above the main function so that main can access them despite being defined first. The main function contains the high-level steps of the full program, and defining it first echoes the top-down design of the program. This example includes comments describing the parts of the program that are important to functions and function calls. You can also download and run the full program.

/* This file shows examples of defining and calling C functions.
 * It also demonstrates using scanf().
 */

#include <stdio.h>

/* This is an example of a FUNCTION PROTOTYPE.  It declares just the type
 * information for a function (the function's name, return type, and parameter
 * list). A prototype is used when code in main wants to call the function
 * before its full definition appears in the file.
 */
int max(int n1, int n2);

/* A prototype for another function.  void is the return type of a function
 * that does not return a value
 */
void print_table(int start, int stop);

/* All C programs must have a main function.  This function defines what the
 * program does when it begins executing, and it's typically used to organize
 * the big-picture behavior of the program.
 */
int main() {
    int x, y, larger;

    printf("This program will operate over two int values.\n");

    printf("Enter the first value: ");
    scanf("%d", &x);

    printf("Enter the second value: ");
    scanf("%d", &y);

    larger = max(x,y);

    printf("The larger of %d and %d is %d\n", x, y, larger);

    print_table(x, larger);

    return 0;
}

/* This is an example of a FUNCTION DEFINITION.  It specifies not only the
 * function name and type, but it also fully defines the code of its body.
 * (Notice, and emulate, the complete function comment!)
 */
/* Computes the max of two integer values.
 *   n1: the first value
 *   n2: the other value
 *   returns: the larger of n1 and n2
 */
int max(int n1, int n2)  {
    int result;

    result = n1;

    if (n2 > n1) {
        result = n2;
    }

    return result;
}

/* prints out the squares from start to stop
 *   start: the beginning of the range
 *   stop: the end of the range
 */
void print_table(int start, int stop) {
    int i;

    for (i = start; i <= stop; i++) {
        printf("%d\t",i*i);
    }

    printf("\n");
}