Examples

Let us examine some examples of object and function declarations. We discuss declarations of typedef names in “typedef Declarations”.

In the following example, the declarator list in the first line contains two declarators, one of which includes an initializer. The line declares two objects, iVar1 and iVar2, both with type int. iVar2 begins its existence with the value 10:

int iVar1, iVar2 = 10;
static char msg[] = "Hello, world!";

The second line in this example defines and initializes an array of char named msg with static storage duration (we discuss storage duration in “Storage Class Specifiers”).

Next, you see the declaration of an external variable named status with the qualified type volatile short:

extern volatile short status;

The next declaration defines an anonymous enumerated type with the enumeration constants OFF and ON, as well as the variable toggle with this type. The declaration initializes toggle with the value ON:

enum { OFF, ON } toggle = ON;

The following example defines the structure type struct CharColor, whose members are the bit-fields fg, bg, and bl. It also defines the variable attribute with this type, and initializes the members of attribute with the values 12, 1, and 0.

struct CharColor { unsigned fg:4, bg:3, bl:1; } attribute = {12, 1, 0};

The second line of the next example defines an array named clientArray with 100 elements of type struct Client, and a pointer to struct Client named clientPtr, initialized with the address of the first element in clientArray:

struct Client { char name[64], pin[16]; /* ... */ };
struct Client clientArray[100], *clientPtr = clientArray;

Next you see a declaration of a float variable, x, and an array, flPtrArray, whose 10 elements have the type pointer to float. The first of these pointers, flPtrArray[0], is initialized with &x; the remaining array elements are initialized as null pointers:

float x, *flPtrArray[10] = { &x };

The following line declares the function func1() with the return value type int. This declaration offers no information about the number and types of the function’s parameters, if any:

int func1();

We’ll move on to the declaration of a static function named func2(), whose only parameter has the type pointer to double, and which also returns a pointer to double:

static double *func2( double * );

Last, we define the inline function printAmount(), with two parameters, returning int:

inline int printAmount( double amount, int width )
{ return printf( "%*.2lf", width, amount ); }

Storage Class Specifiers

A storage class specifier in a declaration modifies the linkage of the identifier (or identifiers) declared, and the storage duration of the corresponding objects. (The concepts of linkage and storage duration are explained individually in later sections of this chapter.)

No more than one storage class specifier may appear in a declaration. Function identifiers may be accompanied only by the storage class specifier extern or static. Function parameters may take only the storage class specifier register. The five storage class specifiers have the following meanings:

auto

Objects declared with the auto specifier have automatic storage duration. This specifier is permissible only in object declarations within a function. In ANSI C, objects declared within a function have automatic storage duration by default, and the auto specifier is archaic.

register

You can use the specifier register when declaring objects with automatic storage duration. The register keyword is a hint to the compiler that the object should be made as quickly accessible as possible—ideally, by storing it in a CPU register. However, the compiler may treat some or all objects declared with register the same as ordinary objects with automatic storage duration. In any case, programs must not use the address operator on objects declared with the register specifier.

static

A function identifier declared with the specifier static has internal linkage. In other words, such an identifier cannot be used in another translation unit to access the function.

An object identifier declared with static has either no linkage or internal linkage, depending on whether the object’s definition is inside a function or outside all functions. Objects declared with static always have static storage duration. Thus, the specifier static allows you to define local objects—that is, objects with block scope—that have static storage duration.

extern

Function and object identifiers declared with the extern specifier have external linkage. You can use them anywhere in the entire program. External objects have static storage duration.

_Thread_local

The specifier _Thread_local declares the given object as thread-local, which means that each thread has its own separate instance of the object. Only objects can be declared as thread-local, not functions. If you declare a thread-local object within a function, the declaration must also have either the extern or the static specifier. In expressions, the identifier of a thread-local object always refers to the local instance of the object belonging to the thread in which the expression is being evaluated. For an example, see “Using Thread-Local Objects”.

Type Qualifiers

You can modify types in a declaration by including the type qualifiers const, volatile, restrict, and _Atomic. A declaration may contain any number of type qualifiers in any order. A type qualifier list may even contain the same type qualifier several times, or the same qualifier may be applied repeatedly through qualified typedef names. The compiler ignores such repetitions of any qualifier, treating them as if the qualifier were present only once.

The individual type qualifiers have the following meanings:

const

An object whose type is qualified with const is constant; the program cannot modify it after its definition.

volatile

An object whose type is qualified with volatile may be modified by other processes or events. The volatile keyword instructs the compiler to reread the object’s value each time it is used, even if the program itself has not changed it since the previous access. This is most commonly used in programming for hardware interfaces, where a value can be changed by external events.

restrict

The restrict qualifier is applicable only to object pointer types. The type qualifier restrict was introduced in C99, and is a hint to the compiler that the object referenced by a given pointer, if it is modified at all, will not be accessed in any other way except using that pointer, whether directly or indirectly. This feature allows the compiler to apply certain optimization techniques that would not be possible without such a restriction. The compiler may ignore the restrict qualifier without affecting the result of the program.

_Atomic

An object declared with the type qualifier _Atomic is an atomic object. Arrays cannot be atomic. Support for atomic objects is optional: C11 implementations may define the macro __STDC_NO_ATOMICS__ to indicate that programs cannot declare atomic objects. For more information about atomic objects, see “Atomic Objects”.

The compiler may store objects qualified as const but not volatile, in a read-only segment of memory. It may also happen that the compiler allocates no storage for such an object if the program does not use its address.

Objects qualified with both const and volatile, such as the object ticks in the following example, cannot be modified by the program itself but may be modified by something else, such as a clock chip’s interrupt handler:

extern const volatile int ticks;

Here are some more examples of declarations using qualified types:

const int limit = 10000;                    // A constant int object.
typedef struct { double x, y, r; } Circle;  // A structure type.
const Circle unit_circle = { 0, 0, 1 };     // A constant Circle object.
const float v[] = { 1.0F, 0.5F, 0.25F };    // An array of constant
                                            // float elements.
volatile short * restrict vsPtr;            // A restricted pointer to
                                            // volatile short.

With pointer types, the type qualifiers to the right of the asterisk qualify the pointer itself, and those to the left of the asterisk qualify the type of object it points to. In the last example, the pointer vsPtr is qualified with restrict, and the object it points to is qualified with volatile. For more details, including more about restricted pointers, see “Pointers and Type Qualifiers”.

Declarations and Definitions

You can declare an identifier as often as you want, but only one declaration within its scope can be a definition. Placing the definitions of objects and functions with external linkage in header files is a common way of introducing duplicate definitions and is therefore not a good idea.

An identifier’s declaration is a definition in the following cases:

• A function declaration is a definition if it contains the function block. Here is an example:

  int iMax( int a, int b );   // This is a declaration, not a
                              // definition.
  int iMax( int a, int b )    // This is the function's definition.
  { return ( a >= b ? a : b ); }

• An object declaration is a definition if it allocates storage for the object. Declarations that include initializers are always definitions. Furthermore, all declarations within function blocks are definitions unless they contain the storage class specifier extern. Here are some examples:

  int a = 10;               // Definition of a.
  extern double b[];        // Declaration of the array b, which is
                            // defined elsewhere in the program.
  void func()
  {
    extern char c;          // Declaration of c, not a definition.
    static short d;         // Definition of d.
    float e;                // Definition of e.
    /* ... */
  }

  If you declare an object outside of all functions, without an initializer and without the storage class specifier extern, the declaration is a tentative definition. Here are some examples:

  int i, v[];                // Tentative definitions of i, v and j.
  static int j;

  A tentative definition of an identifier remains a simple declaration if the translation unit contains another definition for the same identifier. If not, then the compiler behaves as if the tentative definition had included an initializer with the value zero, making it a definition. Thus, the int variables i and j in the previous example, whose identifiers are declared without initializers, are implicitly initialized with the value 0, and the int array v has one element, with the initial value 0.

Complex Declarators

The symbols (), [ ], and * in a declarator specify that the identifier has a function, array, or pointer type. A complex declarator may contain multiple occurrences of any or all of these symbols. This section explains how to interpret such declarators.

The basic symbols in a declarator have the following meanings:

()

A function whose return value has the type…

[ ]

An array whose elements have the type…

*

A pointer to the type…

In declarators, these symbols have the same priority and associativity as the corresponding operators would have in an expression. Furthermore, as in expressions, you can use additional parentheses to modify the order in which they are interpreted. Here is an example:

int *abc[10];    // An array of 10 elements whose
                 // type is pointer to int.
int (*abc)[10];  // A pointer to a array of 10
                 // elements whose type is int.

In a declarator that involves a function type, the parentheses that indicate a function may contain the parameter declarations. The following example declares a pointer to a function type:

int (*fPtr)(double x);    // fPtr is a pointer to a function that has
                          // one double parameter and returns int.

The declarator must include declarations of the function parameters if it is part of the function definition.

When interpreting a complex declarator, always begin with the identifier. Starting from there, repeat the following steps in order until you have interpreted all the symbols in the declarator:

1. If a left parenthesis (() or bracket ([) appears immediately to the right, then interpret the pair of parentheses or brackets.

2. Otherwise, if an asterisk (*) appears to the left, interpret the asterisk.

Here is an example:

extern char *(* fTab[])(void);

Table 11-1 interprets this example bit by bit. The third column is meant to be read from the top row down, as a sentence.

fTab has an incomplete array type because the declaration does not specify the array length. Before you can use the array, you must define it elsewhere in the program with a specific length.

The parentheses around *fTab[] are necessary. Without them, fTab would be declared as an array whose elements are functions—which is impossible.

The next example shows the declaration of a function identifier, followed by its interpretation:

float (* func())[3][10];

The identifier func is...
a function whose return value has the type...
pointer to...
an array of three elements of type...
array of ten elements of type...
float.

In other words, the function func returns a pointer to a two-dimensional array of 3 rows and 10 columns. Here again, the parentheses around * func() are necessary, as without them the function would be declared as returning an array—which is impossible.

External Linkage

An identifier with external linkage represents the same function or object throughout the program. The compiler presents such identifiers to the linker, which resolves them with other occurrences in other translation units and libraries.

Function and object identifiers declared with the storage class specifier extern have external linkage, with one exception: if an identifier has already been declared with internal linkage, a second declaration within the scope of the first cannot change the identifier’s linkage to external.

The compiler treats function declarations without a storage class specifier as if they included the specifier extern. Similarly, any object identifiers that you declare outside all functions and without a storage class specifier have external linkage.

Internal Linkage

An identifier with internal linkage represents the same object or function within a given translation unit. The identifier is not presented to the linker. As a result, you cannot use the identifier in another translation unit to refer to the same object or function.

A function or object identifier has internal linkage if it is declared outside all functions and with the storage class specifier static.

Identifiers with internal linkage do not conflict with similar identifiers in other translation units. If you declare an identifier with internal linkage in a given translation unit, you cannot also declare and use an external identifier with the same spelling in that translation unit.

No Linkage

All identifiers that have neither external nor internal linkage have no linkage. Each declaration of such an identifier therefore introduces a new entity. Identifiers with no linkage include the following:

• Identifiers that are not names of variables or functions, such as label names, structure tags, and typedef names

• Function parameters

• Object identifiers that are declared within a function and without the storage class specifier extern

Here are a few examples:

int func1( void );         // func1 has external linkage.
int a;                     // a has external linkage.
extern int b = 1;          // b has external linkage.
static int c;              // c has internal linkage.

static void func2( int d ) // func2 has internal linkage; d has no
                           // linkage.
{
  extern int a;            // This a is the same as that above, with
                           // external linkage.
  int b = 2;               // This b has no linkage, and hides the
                           // external b declared above.
  extern int c;            // This c is the same as that above, and
                           // retains internal linkage.
  static int e;            // e has no linkage.
  /* ... */
}

As this example illustrates, an identifier with external or internal linkage is not always visible. The identifier b with no linkage, declared in the function func2(), hides the identifier b with external linkage until the end of the function block (see “Identifier Scope”).

Static Storage Duration

Objects that are defined outside all functions, or within a function and with the storage class specifier static, have static storage duration. These include all objects whose identifiers have internal or external linkage.

All objects with static storage duration are generated and initialized before execution of the program begins. Their lifetime spans the program’s entire runtime.

Thread Storage Duration

Objects defined with the storage class specifier _Thread_local are called thread-local objects and have thread storage duration. The storage duration of a thread-local object is the entire runtime of the thread for which it is created. Each thread has its own separate instance of a thread-local object, which is initialized when the thread starts.

Automatic Storage Duration

Objects defined within a function and with no storage class specifier (or with the unnecessary specifier auto) have automatic storage duration. Function parameters also have automatic storage duration. Objects with automatic storage duration are generally called automatic variables for short.

The lifetime of an automatic object is delimited by the braces ({}) that begin and end the block in which the object is defined. Variable-length arrays are an exception: their lifetime begins at the point of declaration, and ends with the identifier’s scope—that is, at the end of the block containing the declaration, or when a jump occurs to a point before the declaration.

Each time the flow of program execution enters a block, new instances of any automatic objects defined in the block are generated (and initialized, if the declaration includes an initializer). This fact is important in recursive functions, for example.

Implicit Initialization

Objects with automatic storage duration have an undetermined initial value if their definition does not include an initializer. Function parameters, which also have automatic storage duration, are initialized with the argument values when the function call occurs. All other objects have static storage duration, and are implicitly initialized with the default value 0, unless their definition includes an explicit initializer. Or, to put it more exactly:

• Objects with an arithmetic type have the default initial value 0.

• The default initial value of pointer objects is a null pointer (see “Initializing Pointers”).

The compiler applies these rules recursively in initializing array elements, structure members, and the first members of unions.

Explicit Initialization

An initializer in an object definition specifies the object’s initial value explicitly. The initializer is appended to the declarator for the object’s identifier with an equals sign (=). The initializer can be either a single expression or a list of initializer expressions enclosed in braces.

For objects with a scalar type, the initializer is a single expression:

#include <string.h>                // Prototypes of string functions.
double var = 77, *dPtr = &var;
int (*funcPtr)( const char*, const char* ) = strcmp;

The initializers here are 77 for the variable var, and &var for the pointer dPtr. The function pointer funcPtr is initialized with the address of the standard library function strcmp().

As in an assignment operation, the initializer must be an expression that can be implicitly converted to the object’s type. In the previous example, the constant value 77, with type int, is implicitly converted to the type double.

Objects with an array, structure, or union type are initialized with a comma-separated list containing initializers for their individual elements or members:

short a[4] = { 1, 2, 2*2, 2*2*2 };
Rectangle_t rect1 = { { -1, 1 }, { 1, -1 } };

The type Rectangle_t used here is the typedef name of the structure we defined in Example 11-1, whose members are structures with the type Point_t.

The initializers for objects with static storage duration must be constant expressions, as in the previous examples. Automatic objects are not subject to this restriction. You can also initialize an automatic structure or union object with an existing object of the same type:

#include <string.h>            // Prototypes of string functions.
/* ... */
void  func( const char *str )
{
  size_t len = strlen( str );  // Call a function to initialize len.
  Rectangle_t rect2 = rect1;   // Refers to rect1 from the previous
                               // example.
  /* ... */
}

More details on initializing arrays, structures, and unions, including the initialization of strings and the use of element designators, are presented in “Initializing Arrays”, “Initializing Structures”, and “Initializing Unions”.

Objects declared with the type qualifier const ordinarily must have an initializer, as you can’t assign them the desired value later. However, a declaration that is not a definition, such as the declaration of an external identifier, must not include an initializer. Furthermore, you cannot initialize a variable-length array.

void func( void )
{
  extern int n;            // Declaration of n, not a definition.
  char buf[n];             // buf is a variable-length array.
  /* ... */
}

The declarations of the objects n and buf cannot include initializers.