.C File Format – Functions

Function definitions

function-definition:
    declaration-specifiers declarator [declaration-list] compound-statement

int add(int a, int b)
{
    return a + b;
}

• A function may return any complete object type except an array type, or void.
• A function returning a value should use return. If control reaches the closing brace and the caller uses the result, the behaviour is undefined (C17 6.9.1).
• The storage-class specifiers allowed are extern and static, which set linkage.
• The function name’s scope covers the rest of the translation unit, so it can call itself.
• Before C23 each parameter in a definition needed a name. C23 allows unnamed parameters.
• A function specifier may be inline or _Noreturn. See Inline functions and Functions that do not return.

Prototypes

direct-declarator:
    direct-declarator ( parameter-type-list )
    direct-declarator ( [identifier-list] )

parameter-type-list:
    parameter-list
    parameter-list , ...

A declaration that lists parameter types is a prototype. It lets the compiler check calls and convert arguments. A prototype’s parameter names are optional and have only prototype scope.

int add(int a, int b);     /* with names */
int add(int, int);         /* without names */
void log_it(void);         /* no parameters */

int add(a, b)          /* identifier list: old style, removed in C23 */
int a;
int b;
{
    return a + b;
}

Calling a function

Arguments are evaluated and copied to the parameters in an unspecified order, then the call happens (C17 6.5.2.2). There is a sequence point after the arguments and before the call. Each argument is converted as if by assignment to the parameter’s type, when a prototype is visible.

When no prototype is visible, or for a ... argument, the default argument promotions apply: integer promotions, and float to double. Calling a function with a different number of arguments, or with incompatible types, is undefined behaviour unless the prototype allows it.

A function may call itself, and so may main. C does not allow calling a function at file scope outside of any function, or defining one inside another.

Variadic functions

A parameter list ending in ... accepts extra arguments of any type. Before C23 at least one named parameter was required. C23 allows int f(...). The extra arguments are read with the macros in <stdarg.h> (C17 7.16):

#include <stdarg.h>

int sum(int count, ...)
{
    va_list ap;
    int total = 0;

    va_start(ap, count);
    for (int i = 0; i < count; i++)
        total += va_arg(ap, int);
    va_end(ap);

    return total;
}

sum(3, 10, 20, 30);    /* 60 */

Because of the default promotions, va_arg(ap, float) and va_arg(ap, char) are not valid: those types are promoted to double and int. Reading an argument with the wrong type is undefined.

__func__

The predefined identifier __func__ (C99) is available inside every function body. It behaves as if the function began with this declaration (C17 6.4.2.2):

static const char __func__[] = "function-name";

It is an ordinary identifier, not a macro, so it cannot be used by the preprocessor.

Functions that do not return

_Noreturn (C11) and the C23 attribute [[noreturn]] declare a function that never returns to its caller, such as exit and abort (C17 6.7.4). If the function does return, the behaviour is undefined. C23 deprecates _Noreturn and the <stdnoreturn.h> header.

The main function

In a hosted environment, a program starts by calling main. The forms are (C17 5.1.2.2.1):

int main(void) { /* ... */ }
int main(int argc, char *argv[]) { /* ... */ }

An implementation may also allow other forms. The name argv can be declared as char **argv, and the parameter names can differ. The implementation declares no prototype for main.

• argc is the number of arguments and is non-negative.
• argv[argc] is a null pointer.
• argv[0] holds the program’s name, if available. If it is not, it is an empty string or null.
• The strings pointed to by argv can be modified, and stay until the program ends.