GNU C Language Manual

Short Table of Contents

Table of Contents

GNU C Manual

This manual explains the C language for use with the GNU Compiler Collection (GCC) on the GNU/Linux operating system and other systems. We refer to this dialect as GNU C. If you already know C, you can use this as a reference manual.

If you understand basic concepts of programming but know nothing about C, you can read this manual sequentially from the beginning to learn the C language.

If you are a beginner in programming, we recommend you first learn a language with automatic garbage collection and no explicit pointers, rather than starting with C. Good choices include Lisp, Scheme, Python and Java. Because of C’s explicit pointers, programmers must be careful to avoid certain kinds of errors in memory usage.

C is a venerable language; it was first used in 1973. The GNU C Compiler, which was subsequently extended into the GNU Compiler Collection, was first released in 1987. Other important languages were designed based on C: once you know C, it gives you a useful base for learning C++, C#, Java, Scala, D, Go, and more.

The special advantage of C is that it is fairly simple while allowing close access to the computer’s hardware, which previously required writing in assembler language to describe the individual machine instructions. Some have called C a “high-level assembler language” because of its explicit pointers and lack of automatic management of storage. As one wag put it, “C combines the power of assembler language with the convenience of assembler language.” However, C is far more portable, and much easier to read and write, than assembler language.

This manual describes the GNU C language supported by the GNU Compiler Collection, as of roughly 2017. Please inform us of any changes needed to match the current version of GNU C.

When a construct may be absent or work differently in other C compilers, we say so. When it is not part of ISO standard C, we say it is a “GNU C extension,” because it is useful to know that. However, standards and other dialects are secondary topics for this manual. For simplicity’s sake, we keep those notes short, unless it is vital to say more.

Some aspects of the meaning of C programs depend on the target platform: which computer, and which operating system, the compiled code will run on. Where this is the case, we say so.

We hardly mention C++ or other languages that the GNU Compiler Collection supports. We hope this manual will serve as a base for writing manuals for those languages, but languages so different can’t share one common manual.

The C language provides no built-in facilities for performing such common operations as input/output, memory management, string manipulation, and the like. Instead, these facilities are provided by functions defined in the standard library, which is automatically available in every C program. See The GNU C Library in The GNU C Library Reference Manual.

Most GNU/Linux systems use the GNU C Library to provide those facilities. It is itself written in C, so once you know C you can read its source code and see how its library functions do their jobs. Some fraction of the functions are implemented as system calls, which means they contain a special instruction that asks the system kernel (Linux) to do a specific task. To understand how those are implemented, you’d need to read Linux source code. Whether a library function is a system call is an internal implementation detail that makes no difference for how to call the function.

This manual incorporates the former GNU C Preprocessor Manual, which was among the earliest GNU manuals. It also uses some text from the earlier GNU C Manual that was written by Trevis Rothwell and James Youngman.

GNU C has many obscure features, each one either for historical compatibility or meant for very special situations. We have left them to a companion manual, the GNU C Obscurities Manual, which will be published digitally later.

Please report errors and suggestions to c-manual@gnu.org.

Appendices

— The Detailed Node Listing —

Lexical Syntax

Arithmetic

Assignment Expressions

Execution Control Expressions

Order of Execution

Primitive Data Types

Constants

Pointers

Structures

Arrays

Statements

Variables

Type Qualifiers

Functions

Type Conversions

Scope

Preprocessing

Integers in Depth

Floating Point in Depth

Directing Compilation

1 The First Example

This chapter presents the source code for a very simple C program and uses it to explain a few features of the language. If you already know the basic points of C presented in this chapter, you can skim it or skip it.

We present examples of C source code (other than comments) using a fixed-width typeface, since that’s the way they look when you edit them in an editor such as GNU Emacs.

1.1 Example: Recursive Fibonacci

To introduce the most basic features of C, let’s look at code for a simple mathematical function that does calculations on integers. This function calculates the nth number in the Fibonacci series, in which each number is the sum of the previous two: 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, ….

int
fib (int n)
{
  if (n <= 2)  /* This avoids infinite recursion.  */
    return 1;
  else
    return fib (n - 1) + fib (n - 2);
}

This very simple program illustrates several features of C:

• A function definition, whose first two lines constitute the function header. See Function Definitions.
• A function parameter n, referred to as the variable n inside the function body. See Function Parameter Variables. A function definition uses parameters to refer to the argument values provided in a call to that function.
• Arithmetic. C programs add with ‘+’ and subtract with ‘-’. See Arithmetic.
• Numeric comparisons. The operator ‘<=’ tests for “less than or equal.” See Numeric Comparisons.
• Integer constants written in base 10. See Integer Constants.
• A function call. The function call fib (n - 1) calls the function fib, passing as its argument the value n - 1. See Function Calls.
• A comment, which starts with ‘/*’ and ends with ‘*/’. The comment has no effect on the execution of the program. Its purpose is to provide explanations to people reading the source code. Including comments in the code is tremendously important—they provide background information so others can understand the code more quickly. See Comments.

  In this manual, we present comment text in the variable-width typeface used for the text of the chapters, not in the fixed-width typeface used for the rest of the code. That is to make comments easier to read. This distinction of typeface does not exist in a real file of C source code.

• Two kinds of statements, the return statement and the if…else statement. See Statements.
• Recursion. The function fib calls itself; that is called a recursive call. These are valid in C, and quite common.

  The fib function would not be useful if it didn’t return. Thus, recursive definitions, to be of any use, must avoid infinite recursion.

  This function definition prevents infinite recursion by specially handling the case where n is two or less. Thus the maximum depth of recursive calls is less than n.

1.1.1 Function Header

In our example, the first two lines of the function definition are the header. Its purpose is to state the function’s name and say how it is called:

int
fib (int n)

says that the function returns an integer (type int), its name is fib, and it takes one argument named n which is also an integer. (Data types will be explained later, in Primitive Types.)

1.1.2 Function Body

The rest of the function definition is called the function body. Like every function body, this one starts with ‘{’, ends with ‘}’, and contains zero or more statements and declarations. Statements specify actions to take, whereas declarations define names of variables, functions, and so on. Each statement and each declaration ends with a semicolon (‘;’).

Statements and declarations often contain expressions; an expression is a construct whose execution produces a value of some data type, but may also take actions through “side effects” that alter subsequent execution. A statement, by contrast, does not have a value; it affects further execution of the program only through the actions it takes.

This function body contains no declarations, and just one statement, but that one is a complex statement in that it contains nested statements. This function uses two kinds of statements:

return

The return statement makes the function return immediately. It looks like this:

return value;

Its meaning is to compute the expression value and exit the function, making it return whatever value that expression produced. For instance,

return 1;

returns the integer 1 from the function, and

return fib (n - 1) + fib (n - 2);

returns a value computed by performing two function calls as specified and adding their results.

if…else

The if…else statement is a conditional. Each time it executes, it chooses one of its two substatements to execute and ignores the other. It looks like this:

if (condition)
  if-true-statement
else
  if-false-statement

Its meaning is to compute the expression condition and, if it’s “true,” execute if-true-statement. Otherwise, execute if-false-statement. See if-else Statement.

Inside the if…else statement, condition is simply an expression. It’s considered “true” if its value is nonzero. (A comparison operation, such as n <= 2, produces the value 1 if it’s “true” and 0 if it’s “false.” See Numeric Comparisons.) Thus,

if (n <= 2)
  return 1;
else
  return fib (n - 1) + fib (n - 2);

first tests whether the value of n is less than or equal to 2. If so, the expression n <= 2 has the value 1. So execution continues with the statement

return 1;

Otherwise, execution continues with this statement:

return fib (n - 1) + fib (n - 2);

Each of these statements ends the execution of the function and provides a value for it to return. See return Statement.

Calculating fib using ordinary integers in C works only for n < 47, because the value of fib (47) is too large to fit in type int. The addition operation that tries to add fib (46) and fib (45) cannot deliver the correct result. This occurrence is called integer overflow.

Overflow can manifest itself in various ways, but one thing that can’t possibly happen is to produce the correct value, since that can’t fit in the space for the value. See Integer Overflow.

See Functions, for a full explanation about functions.

1.2 The Stack, And Stack Overflow

Recursion has a drawback: there are limits to how many nested levels of function calls a program can make. In C, each function call allocates a block of memory which it uses until the call returns. C allocates these blocks consecutively within a large area of memory known as the stack, so we refer to the blocks as stack frames.

The size of the stack is limited; if the program tries to use too much, that causes the program to fail because the stack is full. This is called stack overflow.

Stack overflow on GNU/Linux typically manifests itself as the signal named SIGSEGV, also known as a “segmentation fault.” By default, this signal terminates the program immediately, rather than letting the program try to recover, or reach an expected ending point. (We commonly say in this case that the program “crashes”). See Signals.

It is inconvenient to observe a crash by passing too large an argument to recursive Fibonacci, because the program would run a long time before it crashes. This algorithm is simple but ridiculously slow: in calculating fib (n), the number of (recursive) calls fib (1) or fib (2) that it makes equals the final result.

However, you can observe stack overflow very quickly if you use this function instead:

int
fill_stack (int n)
{
  if (n <= 1)  /* This limits the depth of recursion.  */
    return 1;
  else
    return fill_stack (n - 1);
}

Under gNewSense GNU/Linux on the Lemote Yeeloong, without optimization and using the default configuration, an experiment showed there is enough stack space to do 261906 nested calls to that function. One more, and the stack overflows and the program crashes. On another platform, with a different configuration, or with a different function, the limit might be bigger or smaller.

1.3 Example: Iterative Fibonacci

Here’s a much faster algorithm for computing the same Fibonacci series. It is faster for two reasons. First, it uses iteration (that is, repetition or looping) rather than recursion, so it doesn’t take time for a large number of function calls. But mainly, it is faster because the number of repetitions is small—only n.

int
fib (int n)
{
  int last = 1;   /* Initial value is fib (1).  */
  int prev = 0;   /* Initial value controls fib (2).  */
  int i;

  for (i = 1; i < n; ++i)
    /* If n is 1 or less, the loop runs zero times,  */
    /* since i < n is false the first time.  */
    {
      /* Now last is fib (i)
         and prev is fib (i - 1).  */
      /* Compute fib (i + 1).  */
      int next = prev + last;
      /* Shift the values down.  */
      prev = last;
      last = next;
      /* Now last is fib (i + 1)
         and prev is fib (i).
         But that won’t stay true for long,
         because we are about to increment i.  */
    }

  return last;
}

This definition computes fib (n) in a time proportional to n. The comments in the definition explain how it works: it advances through the series, always keeps the last two values in last and prev, and adds them to get the next value.

Here are the additional C features that this definition uses:

Internal blocks

Within a function, wherever a statement is called for, you can write a block. It looks like { … } and contains zero or more statements and declarations. (You can also use additional blocks as statements in a block.)

The function body also counts as a block, which is why it can contain statements and declarations.

See Blocks.

Declarations of local variables

This function body contains declarations as well as statements. There are three declarations directly in the function body, as well as a fourth declaration in an internal block. Each starts with int because it declares a variable whose type is integer. One declaration can declare several variables, but each of these declarations is simple and declares just one variable.

Variables declared inside a block (either a function body or an internal block) are local variables. These variables exist only within that block; their names are not defined outside the block, and exiting the block deallocates their storage. This example declares four local variables: last, prev, i, and next.

The most basic local variable declaration looks like this:

type variablename;

For instance,

int i;

declares the local variable i as an integer. See Variable Declarations.

Initializers

When you declare a variable, you can also specify its initial value, like this:

type variablename = value;

For instance,

int last = 1;

declares the local variable last as an integer (type int) and starts it off with the value 1. See Initializers.

Assignment

Assignment: a specific kind of expression, written with the ‘=’ operator, that stores a new value in a variable or other place. Thus,

variable = value

is an expression that computes value and stores the value in variable. See Assignment Expressions.

Expression statements

An expression statement is an expression followed by a semicolon. That computes the value of the expression, then ignores the value.

An expression statement is useful when the expression changes some data or has other side effects—for instance, with function calls, or with assignments as in this example. See Expression Statement.

Using an expression with no side effects in an expression statement is pointless except in very special cases. For instance, the expression statement x; would examine the value of x and ignore it. That is not useful.

Increment operator

The increment operator is ‘++’. ++i is an expression that is short for i = i + 1. See Increment/Decrement.

for statements

A for statement is a clean way of executing a statement repeatedly—a loop (see Loop Statements). Specifically,

for (i = 1; i < n; ++i)
  body

means to start by doing i = 1 (set i to one) to prepare for the loop. The loop itself consists of

• Testing i < n and exiting the loop if that’s false.
• Executing body.
• Advancing the loop (executing ++i, which increments i).

The net result is to execute body with 1 in i, then with 2 in i, and so on, stopping just before the repetition where i would equal n. If n is less than 1, the loop will execute the body zero times.

The body of the for statement must be one and only one statement. You can’t write two statements in a row there; if you try to, only the first of them will be treated as part of the loop.

The way to put multiple statements in such a place is to group them with a block, and that’s what we do in this example.

2 A Complete Program

It’s all very well to write a Fibonacci function, but you cannot run it by itself. It is a useful program, but it is not a complete program.

In this chapter we present a complete program that contains the fib function. This example shows how to make the program start, how to make it finish, how to do computation, and how to print a result.

2.1 Complete Program Example

Here is the complete program that uses the simple, recursive version of the fib function (see Recursive Fibonacci):

#include <stdio.h>

int
fib (int n)
{
  if (n <= 2)  /* This avoids infinite recursion.  */
    return 1;
  else
    return fib (n - 1) + fib (n - 2);
}

int
main (void)
{
  printf ("Fibonacci series item %d is %d\n",
          20, fib (20));
  return 0;
}

This program prints a message that shows the value of fib (20).

Now for an explanation of what that code means.

2.2 Complete Program Explanation

Here’s the explanation of the code of the example in the previous section.

This sample program prints a message that shows the value of fib (20), and exits with code 0 (which stands for successful execution).

Every C program is started by running the function named main. Therefore, the example program defines a function named main to provide a way to start it. Whatever that function does is what the program does. See The main Function.

The main function is the first one called when the program runs, but it doesn’t come first in the example code. The order of the function definitions in the source code makes no difference to the program’s meaning.

The initial call to main always passes certain arguments, but main does not have to pay attention to them. To ignore those arguments, define main with void as the parameter list. (void as a function’s parameter list normally means “call with no arguments,” but main is a special case.)

The function main returns 0 because that is the conventional way for main to indicate successful execution. It could instead return a positive integer to indicate failure, and some utility programs have specific conventions for the meaning of certain numeric failure codes. See Values from main.

The simplest way to print text in C is by calling the printf function, so here we explain very briefly what that function does. For a full explanation of printf and the other standard I/O functions, see The GNU C Library in The GNU C Library Reference Manual.

The first argument to printf is a string constant (see String Constants) that is a template for output. The function printf copies most of that string directly as output, including the newline character at the end of the string, which is written as ‘\n’. The output goes to the program’s standard output destination, which in the usual case is the terminal.

‘%’ in the template introduces a code that substitutes other text into the output. Specifically, ‘%d’ means to take the next argument to printf and substitute it into the text as a decimal number. (The argument for ‘%d’ must be of type int; if it isn’t, printf will malfunction.) So the output is a line that looks like this:

Fibonacci series item 20 is 6765

This program does not contain a definition for printf because it is defined by the C library, which makes it available in all C programs. However, each program does need to declare printf so it will be called correctly. The #include line takes care of that; it includes a header file called stdio.h into the program’s code. That file is provided by the operating system and it contains declarations for the many standard input/output functions in the C library, one of which is printf.

Don’t worry about header files for now; we’ll explain them later in Header Files.

The first argument of printf does not have to be a string constant; it can be any string (see Strings). However, using a constant is the most common case.

2.3 Complete Program, Line by Line

Here’s the same example, explained line by line. Beginners, do you find this helpful or not? Would you prefer a different layout for the example? Please tell rms@gnu.org.

#include <stdio.h>      /* Include declaration of usual */
                        /*   I/O functions such as printf.  */
                        /* Most programs need these.  */

int                     /* This function returns an int.  */
fib (int n)             /* Its name is fib;  */
                        /*   its argument is called n.  */
{                       /* Start of function body.  */
  /* This stops the recursion from being infinite.  */
  if (n <= 2)           /* If n is 1 or 2,  */
    return 1;           /*   make fib return 1.  */
  else                  /* otherwise, add the two previous  */
                        /* Fibonacci numbers.  */
    return fib (n - 1) + fib (n - 2);
}

int                     /* This function returns an int.  */
main (void)             /* Start here; ignore arguments.  */
{                       /* Print message with numbers in it.  */
  printf ("Fibonacci series item %d is %d\n",
          20, fib (20));
  return 0;             /* Terminate program, report success.  */
}

2.4 Compiling the Example Program

To run a C program requires converting the source code into an executable file. This is called compiling the program, and the command to do that using GNU C is gcc.

This example program consists of a single source file. If we call that file fib1.c, the complete command to compile it is this:

gcc -g -O -o fib1 fib1.c

Here, -g says to generate debugging information, -O says to optimize at the basic level, and -o fib1 says to put the executable program in the file fib1.

To run the program, use its file name as a shell command. For instance,

./fib1

However, unless you are sure the program is correct, you should expect to need to debug it. So use this command,

gdb fib1

which starts the GDB debugger (see A Sample GDB Session in Debugging with GDB) so you can run and debug the executable program fib1.

Richard Stallman’s advice, from personal experience, is to turn to the debugger as soon as you can reproduce the problem. Don’t try to avoid it by using other methods instead—occasionally they are shortcuts, but usually they waste an unbounded amount of time. With the debugger, you will surely find the bug in a reasonable time; overall, you will get your work done faster. The sooner you get serious and start the debugger, the sooner you are likely to find the bug.

See Compilation, for an introduction to compiling more complex programs which consist of more than one source file.

3 Storage and Data

Storage in C programs is made up of units called bytes. A byte is the smallest unit of storage that can be used in a first-class manner.

On nearly all computers, a byte consists of 8 bits. There are a few peculiar computers (mostly “embedded controllers” for very small systems) where a byte is longer than that, but this manual does not try to explain the peculiarity of those computers; we assume that a byte is 8 bits.

Every C data type is made up of a certain number of bytes; that number is the data type’s size. See Type Size, for details. The types signed char and unsigned char are one byte long; use those types to operate on data byte by byte. See Signed and Unsigned Types. You can refer to a series of consecutive bytes as an array of char elements; that’s what a character string looks like in memory. See String Constants.

4 Beyond Integers

So far we’ve presented programs that operate on integers. In this chapter we’ll present examples of handling non-integral numbers and arrays of numbers.

4.1 An Example with Non-Integer Numbers

Here’s a function that operates on and returns floating point numbers that don’t have to be integers. Floating point represents a number as a fraction together with a power of 2. (For more detail, see Floating-Point Data Types.) This example calculates the average of three floating point numbers that are passed to it as arguments:

double
average_of_three (double a, double b, double c)
{
  return (a + b + c) / 3;
}

The values of the parameter a, b and c do not have to be integers, and even when they happen to be integers, most likely their average is not an integer.

double is the usual data type in C for calculations on floating-point numbers.

To print a double with printf, we must use ‘%f’ instead of ‘%d’:

printf ("Average is %f\n",
        average_of_three (1.1, 9.8, 3.62));

The code that calls printf must pass a double for printing with ‘%f’ and an int for printing with ‘%d’. If the argument has the wrong type, printf will produce meaningless output.

Here’s a complete program that computes the average of three specific numbers and prints the result:

double
average_of_three (double a, double b, double c)
{
  return (a + b + c) / 3;
}

int
main (void)
{
    printf ("Average is %f\n",
            average_of_three (1.1, 9.8, 3.62));
    return 0;
}

From now on we will not present examples of calls to main. Instead we encourage you to write them for yourself when you want to test executing some code.

4.2 An Example with Arrays

A function to take the average of three numbers is very specific and limited. A more general function would take the average of any number of numbers. That requires passing the numbers in an array. An array is an object in memory that contains a series of values of the same data type. This chapter presents the basic concepts and use of arrays through an example; for the full explanation, see Arrays.

Here’s a function definition to take the average of several floating-point numbers, passed as type double. The first parameter, length, specifies how many numbers are passed. The second parameter, input_data, is an array that holds those numbers.

double
avg_of_double (int length, double input_data[])
{
  double sum = 0;
  int i;

  for (i = 0; i < length; i++)
    sum = sum + input_data[i];

  return sum / length;
}

This introduces the expression to refer to an element of an array: input_data[i] means the element at index i in input_data. The index of the element can be any expression with an integer value; in this case, the expression is i. See Accessing Array Elements.

The lowest valid index in an array is 0, not 1, and the highest valid index is one less than the number of elements. (This is known as zero-origin indexing.)

This example also introduces the way to declare that a function parameter is an array. Such declarations are modeled after the syntax for an element of the array. Just as double foo declares that foo is of type double, double input_data[] declares that each element of input_data is of type double. Therefore, input_data itself has type “array of double.”

When declaring an array parameter, it’s not necessary to say how long the array is. In this case, the parameter input_data has no length information. That’s why the function needs another parameter, length, for the caller to provide that information to the function avg_of_double.

4.3 Calling the Array Example

To call the function avg_of_double requires making an array and then passing it as an argument. Here is an example.

{
  /* The array of values to average.  */
  double nums_to_average[5];
  /* The average, once we compute it.  */
  double average;

  /* Fill in elements of nums_to_average.  */

  nums_to_average[0] = 58.7;
  nums_to_average[1] = 5.1;
  nums_to_average[2] = 7.7;
  nums_to_average[3] = 105.2;
  nums_to_average[4] = -3.14159;

  average = avg_of_double (5, nums_to_average);

  /* …now make use of average… */
}

This shows an array subscripting expression again, this time on the left side of an assignment, storing a value into an element of an array.

It also shows how to declare a local variable that is an array: double nums_to_average[5];. Since this declaration allocates the space for the array, it needs to know the array’s length. You can specify the length with any expression whose value is an integer, but in this declaration the length is a constant, the integer 5.

The name of the array, when used by itself as an expression, stands for the address of the array’s data, and that’s what gets passed to the function avg_of_double in avg_of_double (5, nums_to_average).

We can make the code easier to maintain by avoiding the need to write 5, the array length, when calling avg_of_double. That way, if we change the array to include more elements, we won’t have to change that call. One way to do this is with the sizeof operator:

  average = avg_of_double ((sizeof (nums_to_average)
                            / sizeof (nums_to_average[0])),
                           nums_to_average);

This computes the number of elements in nums_to_average by dividing its total size by the size of one element. See Type Size, for more details of using sizeof.

We don’t show in this example what happens after storing the result of avg_of_double in the variable average. Presumably more code would follow that uses that result somehow. (Why compute the average and not use it?) But that isn’t part of this topic.

4.4 Variations for Array Example

The code to call avg_of_double has two declarations that start with the same data type:

  /* The array of values to average.  */
  double nums_to_average[5];
  /* The average, once we compute it.  */
  double average;

In C, you can combine the two, like this:

  double nums_to_average[5], average;

This declares nums_to_average so each of its elements is a double, and average so that it simply is a double.

However, while you can combine them, that doesn’t mean you should. If it is useful to write comments about the variables, and usually it is, then it’s clearer to keep the declarations separate so you can put a comment on each one. That also helps with using textual tools to find occurrences of a variable in source files.

We set all of the elements of the array nums_to_average with assignments, but it is more convenient to use an initializer in the declaration:

{
  /* The array of values to average.  */
  double nums_to_average[]
    = { 58.7, 5.1, 7.7, 105.2, -3.14159 };

  /* The average, once we compute it.  */
  average = avg_of_double ((sizeof (nums_to_average)
                            / sizeof (nums_to_average[0])),
                           nums_to_average);

  /* …now make use of average… */
}

The array initializer is a comma-separated list of values, delimited by braces. See Initializers.

Note that the declaration does not specify a size for nums_to_average, so the size is determined from the initializer. There are five values in the initializer, so nums_to_average gets length 5. If we add another element to the initializer, nums_to_average will have six elements.

Because the code computes the number of elements from the size of the array, using sizeof, the program will operate on all the elements in the initializer, regardless of how many those are.

5 Lexical Syntax

To start the full description of the C language, we explain the lexical syntax and lexical units of C code. The lexical units of a programming language are known as tokens. This chapter covers all the tokens of C except for constants, which are covered in a later chapter (see Constants). One vital kind of token is the identifier (see Identifiers), which is used for names of any kind.

5.1 Write Programs in English!

In principle, you can write the function and variable names in a program, and the comments, in any human language. C allows any kinds of Unicode characters in comments, and you can put them into identifiers with a special prefix (see Unicode Character Codes). However, to enable programmers in all countries to understand and develop the program, it is best under today’s circumstances to write all identifiers and comments in English.

English is the common language of programmers; in all countries, programmers generally learn English. If names and comments in a program are written in English, most programmers in Bangladesh, Belgium, Bolivia, Brazil, Bulgaria and Burundi can understand them. In all those countries, most programmers can speak English, or at least read it, but they do not read each other’s languages at all. In India, with so many languages, two programmers may have no common language other than English.

If you don’t feel confident in writing English, do the best you can, and follow each English comment with a version in a language you write better; add a note asking others to translate that to English. Someone will eventually do that.

The program’s user interface is a different matter. We don’t need to choose one language for that; it is easy to support multiple languages and let each user choose the language for display. This requires writing the program to support localization of its interface. (The gettext package exists to support this; see The GNU C Library in The GNU C Library Reference Manual.) Then a community-based translation effort can provide support for all the languages users want to use.

5.2 Characters

GNU C source files are usually written in the ASCII character set, which was defined in the 1960s for English. However, they can also include Unicode characters represented in the UTF-8 multibyte encoding. This makes it possible to represent accented letters such as ‘á’, as well as other scripts such as Arabic, Chinese, Cyrillic, Hebrew, Japanese, and Korean.¹

In C source code, non-ASCII characters are valid in comments, in wide character constants (see Wide Character Constants), and in string constants (see String Constants).

Another way to specify non-ASCII characters in constants (character or string) and identifiers is with an escape sequence starting with backslash, specifying the intended Unicode character. (See Unicode Character Codes.) This specifies non-ASCII characters without putting a real non-ASCII character in the source file itself.

C accepts two-character aliases called digraphs for certain characters. See Digraphs.

5.3 Whitespace

Whitespace means characters that exist in a file but appear blank in a printed listing of a file (or traditionally did appear blank, several decades ago). The C language requires whitespace in order to separate two consecutive identifiers, or to separate an identifier from a numeric constant. Other than that, and a few special situations described later, whitespace is optional; you can put it in when you wish, to make the code easier to read.

Space and tab in C code are treated as whitespace characters. So are line breaks. You can represent a line break with the newline character (also called linefeed or LF), CR (carriage return), or the CRLF sequence (two characters: carriage return followed by a newline character).

The formfeed character, Control-L, was traditionally used to divide a file into pages. It is still used this way in source code, and the tools that generate nice printouts of source code still start a new page after each “formfeed” character. Dividing code into pages separated by formfeed characters is a good way to break it up into comprehensible pieces and show other programmers where they start and end.

The vertical tab character, Control-K, was traditionally used to make printing advance down to the next section of a page. We know of no particular reason to use it in source code, but it is still accepted as whitespace in C.

Comments are also syntactically equivalent to whitespace.

5.4 Comments

A comment encapsulates text that has no effect on the program’s execution or meaning.

The purpose of comments is to explain the code to people that read it. Writing good comments for your code is tremendously important—they should provide background information that helps programmers understand the reasons why the code is written the way it is. You, returning to the code six months from now, will need the help of these comments to remember why you wrote it this way.

Outdated comments that become incorrect are counterproductive, so part of the software developer’s responsibility is to update comments as needed to correspond with changes to the program code.

C allows two kinds of comment syntax, the traditional style and the C++ style. A traditional C comment starts with ‘/*’ and ends with ‘*/’. For instance,

/* This is a comment in traditional C syntax. */

A traditional comment can contain ‘/*’, but these delimiters do not nest as pairs. The first ‘*/’ ends the comment regardless of whether it contains ‘/*’ sequences.

/* This /* is a comment */ But this is not! */

A line comment starts with ‘//’ and ends at the end of the line. For instance,

// This is a comment in C++ style.

Line comments do nest, in effect, because ‘//’ inside a line comment is part of that comment:

// this whole line is // one comment
This is code, not comment.

It is safe to put line comments inside block comments, or vice versa.

/* traditional comment
   // contains line comment
   more traditional comment
 */ text here is not a comment

// line comment /* contains traditional comment */

But beware of commenting out one end of a traditional comment with a line comment. The delimiter ‘/*’ doesn’t start a comment if it occurs inside an already-started comment.

 // line comment  /* That would ordinarily begin a block comment.
    Oops! The line comment has ended;
    this isn't a comment any more.  */

Comments are not recognized within string constants. "/* blah */" is the string constant ‘/* blah */’, not an empty string.

In this manual we show the text in comments in a variable-width font, for readability, but this font distinction does not exist in source files.

A comment is syntactically equivalent to whitespace, so it always separates tokens. Thus,

  int/* comment */foo;
is equivalent to
  int foo;

but clean code always uses real whitespace to separate the comment visually from surrounding code.

5.5 Identifiers

An identifier (name) in C is a sequence of letters and digits, as well as ‘_’, that does not start with a digit. Most compilers also allow ‘$’. An identifier can be as long as you like; for example,

int anti_dis_establishment_arian_ism;

Letters in identifiers are case-sensitive in C; thus, a and A are two different identifiers.

Identifiers in C are used as variable names, function names, typedef names, enumeration constants, type tags, field names, and labels. Certain identifiers in C are keywords, which means they have specific syntactic meanings. Keywords in C are reserved words, meaning you cannot use them in any other way. For instance, you can’t define a variable or function named return or if.

You can also include other characters, even non-ASCII characters, in identifiers by writing their Unicode character names, which start with ‘\u’ or ‘\U’, in the identifier name. See Unicode Character Codes. However, it is usually a bad idea to use non-ASCII characters in identifiers, and when the names are written in English, they never need non-ASCII characters. See English.

As stated above, whitespace is required to separate two consecutive identifiers, or to separate an identifier from a preceding or following numeric constant.

5.6 Operators and Punctuation

Here we describe the lexical syntax of operators and punctuation in C. The specific operators of C and their meanings are presented in subsequent chapters.

Most operators in C consist of one or two characters that can’t be used in identifiers. The characters used for operators in C are ‘!~^&|*/%+-=<>,.?:’.

Some operators are a single character. For instance, ‘-’ is the operator for negation (with one operand) and the operator for subtraction (with two operands).

Some operators are two characters. For example, ‘++’ is the increment operator. Recognition of multicharacter operators works by grouping together as many consecutive characters as can constitute one operator.

For instance, the character sequence ‘++’ is always interpreted as the increment operator; therefore, if we want to write two consecutive instances of the operator ‘+’, we must separate them with a space so that they do not combine as one token. Applying the same rule, a+++++b is always tokenized as a++ ++ + b, not as a++ + ++b, even though the latter could be part of a valid C program and the former could not (since a++ is not an lvalue and thus can’t be the operand of ++).

A few C operators are keywords rather than special characters. They include sizeof (see Type Size) and _Alignof (see Type Alignment).

The characters ‘;{}[]()’ are used for punctuation and grouping. Semicolon (‘;’) ends a statement. Braces (‘{’ and ‘}’) begin and end a block at the statement level (see Blocks), and surround the initializer (see Initializers) for a variable with multiple elements or fields (such as arrays or structures).

Square brackets (‘[’ and ‘]’) do array indexing, as in array[5].

Parentheses are used in expressions for explicit nesting of expressions (see Basic Arithmetic), around the parameter declarations in a function declaration or definition, and around the arguments in a function call, as in printf ("Foo %d\n", i) (see Function Calls). Several kinds of statements also use parentheses as part of their syntax—for instance, if statements, for statements, while statements, and switch statements. See if Statement, and following sections.

Parentheses are also required around the operand of the operator keywords sizeof and _Alignof when the operand is a data type rather than a value. See Type Size.

5.7 Line Continuation

The sequence of a backslash and a newline is ignored absolutely anywhere in a C program. This makes it possible to split a single source line into multiple lines in the source file. GNU C tolerates and ignores other whitespace between the backslash and the newline. In particular, it always ignores a CR (carriage return) character there, in case some text editor decided to end the line with the CRLF sequence.

The main use of line continuation in C is for macro definitions that would be inconveniently long for a single line (see Macros).

It is possible to continue a line comment onto another line with backslash-newline. You can put backslash-newline in the middle of an identifier, even a keyword, or an operator. You can even split ‘/*’, ‘*/’, and ‘//’ onto multiple lines with backslash-newline. Here’s an ugly example:

/\
*
*/ fo\
o +\
= 1\
0;

That’s equivalent to ‘/* */ foo += 10;’.

Don’t do those things in real programs, since they make code hard to read.

Note: For the sake of using certain tools on the source code, it is wise to end every source file with a newline character which is not preceded by a backslash, so that it really ends the last line.

6 Arithmetic

Arithmetic operators in C attempt to be as similar as possible to the abstract arithmetic operations, but it is impossible to do this perfectly. Numbers in a computer have a finite range of possible values, and non-integer values have a limit on their possible accuracy. Nonetheless, except when results are out of range, you will encounter no surprises in using ‘+’ for addition, ‘-’ for subtraction, and ‘*’ for multiplication.

Each C operator has a precedence, which is its rank in the grammatical order of the various operators. The operators with the highest precedence grab adjoining operands first; these expressions then become operands for operators of lower precedence. We give some information about precedence of operators in this chapter where we describe the operators; for the full explanation, see Binary Operator Grammar.

The arithmetic operators always promote their operands before operating on them. This means converting narrow integer data types to a wider data type (see Operand Promotions). If you are just learning C, don’t worry about this yet.

Given two operands that have different types, most arithmetic operations convert them both to their common type. For instance, if one is int and the other is double, the common type is double. (That’s because double can represent all the values that an int can hold, but not vice versa.) For the full details, see Common Type.

6.1 Basic Arithmetic

Basic arithmetic in C is done with the usual binary operators of algebra: addition (‘+’), subtraction (‘-’), multiplication (‘*’) and division (‘/’). The unary operator ‘-’ is used to change the sign of a number. The unary + operator also exists; it yields its operand unaltered.

‘/’ is the division operator, but dividing integers may not give the result you expect. Its value is an integer, which is not equal to the mathematical quotient when that is a fraction. Use ‘%’ to get the corresponding integer remainder when necessary. See Division and Remainder. Floating point division yields value as close as possible to the mathematical quotient.

These operators use algebraic syntax with the usual algebraic precedence rule (see Binary Operator Grammar) that multiplication and division are done before addition and subtraction, but you can use parentheses to explicitly specify how the operators nest. They are left-associative (see Associativity and Ordering). Thus,

-a + b - c + d * e / f

is equivalent to

(((-a) + b) - c) + ((d * e) / f)

6.2 Integer Arithmetic

Each of the basic arithmetic operations in C has two variants for integers: signed and unsigned. The choice is determined by the data types of their operands.

Each integer data type in C is either signed or unsigned. A signed type can hold a range of positive and negative numbers, with zero near the middle of the range. An unsigned type can hold only nonnegative numbers; its range starts with zero and runs upward.

The most basic integer types are int, which normally can hold numbers from -2,147,483,648 to 2,147,483,647, and unsigned int, which normally can hold numbers from 0 to 4,294,967,295. (This assumes int is 32 bits wide, always true for GNU C on real computers but not always on embedded controllers.) See Integer Types, for full information about integer types.

When a basic arithmetic operation is given two signed operands, it does signed arithmetic. Given two unsigned operands, it does unsigned arithmetic.

If one operand is unsigned int and the other is int, the operator treats them both as unsigned. More generally, the common type of the operands determines whether the operation is signed or not. See Common Type.

Printing the results of unsigned arithmetic with printf using ‘%d’ can produce surprising results for values far away from zero. Even though the rules above say that the computation was done with unsigned arithmetic, the printed result may appear to be signed!

The explanation is that the bit pattern resulting from addition, subtraction or multiplication is actually the same for signed and unsigned operations. The difference is only in the data type of the result, which affects the interpretation of the result bit pattern, and whether the arithmetic operation can overflow (see the next section).

But ‘%d’ doesn’t know its argument’s data type. It sees only the value’s bit pattern, and it is defined to interpret that as signed int. To print it as unsigned requires using ‘%u’ instead of ‘%d’. See The GNU C Library in The GNU C Library Reference Manual.

Arithmetic in C never operates directly on narrow integer types (those with fewer bits than int; Narrow Integers). Instead it “promotes” them to int. See Operand Promotions.

6.3 Integer Overflow

When the mathematical value of an arithmetic operation doesn’t fit in the range of the data type in use, that’s called overflow. When it happens in integer arithmetic, it is integer overflow.

Integer overflow happens only in arithmetic operations. Type conversion operations, by definition, do not cause overflow, not even when the result can’t fit in its new type. See Integer Conversion.

Signed numbers use two’s-complement representation, in which the most negative number lacks a positive counterpart (see Integers in Depth). Thus, the unary ‘-’ operator on a signed integer can overflow.

6.3.1 Overflow with Unsigned Integers

Unsigned arithmetic in C ignores overflow; it produces the true result modulo the nth power of 2, where n is the number of bits in the data type. We say it “truncates” the true result to the lowest n bits.

A true result that is negative, when taken modulo the nth power of 2, yields a positive number. For instance,

unsigned int x = 1;
unsigned int y;

y = -x;

causes overflow because the negative number -1 can’t be stored in an unsigned type. The actual result, which is -1 modulo the nth power of 2, is one less than the nth power of 2. That is the largest value that the unsigned data type can store. For a 32-bit unsigned int, the value is 4,294,967,295. See Maximum and Minimum Values.

Adding that number to itself, as here,

unsigned int z;

z = y + y;

ought to yield 8,489,934,590; however, that is again too large to fit, so overflow truncates the value to 4,294,967,294. If that were a signed integer, it would mean -2, which (not by coincidence) equals -1 + -1.

6.3.2 Overflow with Signed Integers

For signed integers, the result of overflow in C is in principle undefined, meaning that anything whatsoever could happen. Therefore, C compilers can do optimizations that treat the overflow case with total unconcern. (Since the result of overflow is undefined in principle, one cannot claim that these optimizations are erroneous.)

Watch out: These optimizations can do surprising things. For instance,

int i;
…
if (i < i + 1)
  x = 5;

could be optimized to do the assignment unconditionally, because the if-condition is always true if i + 1 does not overflow.

GCC offers compiler options to control handling signed integer overflow. These options operate per module; that is, each module behaves according to the options it was compiled with.

These two options specify particular ways to handle signed integer overflow, other than the default way:

-fwrapv

Make signed integer operations well-defined, like unsigned integer operations: they produce the n low-order bits of the true result. The highest of those n bits is the sign bit of the result. With -fwrapv, these out-of-range operations are not considered overflow, so (strictly speaking) integer overflow never happens.

The option -fwrapv enables some optimizations based on the defined values of out-of-range results. In GCC 8, it disables optimizations that are based on assuming signed integer operations will not overflow.

-ftrapv

Generate a signal SIGFPE when signed integer overflow occurs. This terminates the program unless the program handles the signal. See Signals.

One other option is useful for finding where overflow occurs:

-fsanitize=signed-integer-overflow

Output a warning message at run time when signed integer overflow occurs. This checks the ‘+’, ‘*’, and ‘-’ operators. This takes priority over -ftrapv.

6.4 Mixed-Mode Arithmetic

Mixing integers and floating-point numbers in a basic arithmetic operation converts the integers automatically to floating point. In most cases, this gives exactly the desired results. But sometimes it matters precisely where the conversion occurs.

If i and j are integers, (i + j) * 2.0 adds them as an integer, then converts the sum to floating point for the multiplication. If the addition causes an overflow, that is not equivalent to converting each integer to floating point and then adding the two floating point numbers. You can get the latter result by explicitly converting the integers, as in ((double) i + (double) j) * 2.0. See Explicit Type Conversion.

Adding or multiplying several values, including some integers and some floating point, performs the operations left to right. Thus, 3.0 + i + j converts i to floating point, then adds 3.0, then converts j to floating point and adds that. You can specify a different order using parentheses: 3.0 + (i + j) adds i and j first and then adds that sum (converted to floating point) to 3.0. In this respect, C differs from other languages, such as Fortran.

6.5 Division and Remainder

Division of integers in C rounds the result to an integer. The result is always rounded towards zero.

 16 / 3  ⇒ 5
-16 / 3  ⇒ -5
 16 / -3 ⇒ -5
-16 / -3 ⇒ 5

To get the corresponding remainder, use the ‘%’ operator:

 16 % 3  ⇒ 1
-16 % 3  ⇒ -1
 16 % -3 ⇒ 1
-16 % -3 ⇒ -1

‘%’ has the same operator precedence as ‘/’ and ‘*’.

From the rounded quotient and the remainder, you can reconstruct the dividend, like this:

int
original_dividend (int divisor, int quotient, int remainder)
{
  return divisor * quotient + remainder;
}

To do unrounded division, use floating point. If only one operand is floating point, ‘/’ converts the other operand to floating point.

16.0 / 3   ⇒ 5.333333333333333
16   / 3.0 ⇒ 5.333333333333333
16.0 / 3.0 ⇒ 5.333333333333333
16   / 3   ⇒ 5

The remainder operator ‘%’ is not allowed for floating-point operands, because it is not needed. The concept of remainder makes sense for integers because the result of division of integers has to be an integer. For floating point, the result of division is a floating-point number, in other words a fraction, which will differ from the exact result only by a very small amount.

There are functions in the standard C library to calculate remainders from integral-values division of floating-point numbers. See The GNU C Library in The GNU C Library Reference Manual.

Integer division overflows in one specific case: dividing the smallest negative value for the data type (see Maximum and Minimum Values) by -1. That’s because the correct result, which is the corresponding positive number, does not fit (see Integer Overflow) in the same number of bits. On some computers now in use, this always causes a signal SIGFPE (see Signals), the same behavior that the option -ftrapv specifies (see Signed Overflow).

Division by zero leads to unpredictable results—depending on the type of computer, it might cause a signal SIGFPE, or it might produce a numeric result.

Watch out: Make sure the program does not divide by zero. If you can’t prove that the divisor is not zero, test whether it is zero, and skip the division if so.

6.6 Numeric Comparisons

There are two kinds of comparison operators: equality and ordering. Equality comparisons test whether two expressions have the same value. The result is a truth value: a number that is 1 for “true” and 0 for “false.”

a == b   /* Test for equal.  */
a != b   /* Test for not equal.  */

The equality comparison is written == because plain = is the assignment operator.

Ordering comparisons test which operand is greater or less. Their results are truth values. These are the ordering comparisons of C:

a < b   /* Test for less-than.  */
a > b   /* Test for greater-than.  */
a <= b  /* Test for less-than-or-equal.  */
a >= b  /* Test for greater-than-or-equal.  */

For any integers a and b, exactly one of the comparisons a < b, a == b and a > b is true, just as in mathematics. However, if a and b are special floating point values (not ordinary numbers), all three can be false. See Special Float Values, and Invalid Optimizations.

6.7 Shift Operations

Shifting an integer means moving the bit values to the left or right within the bits of the data type. Shifting is defined only for integers. Here’s the way to write it:

/* Left shift.  */
5 << 2 ⇒ 20

/* Right shift.  */
5 >> 2 ⇒ 1

The left operand is the value to be shifted, and the right operand says how many bits to shift it (the shift count). The left operand is promoted (see Operand Promotions), so shifting never operates on a narrow integer type; it’s always either int or wider. The result of the shift operation has the same type as the promoted left operand.

6.7.1 Shifting Makes New Bits

A shift operation shifts towards one end of the number and has to generate new bits at the other end.

Shifting left one bit must generate a new least significant bit. It always brings in zero there. It is equivalent to multiplying by the appropriate power of 2. For example,

5 << 3     is equivalent to   5 * 2*2*2
-10 << 4   is equivalent to   -10 * 2*2*2*2

The meaning of shifting right depends on whether the data type is signed or unsigned (see Signed and Unsigned Types). For a signed data type, it performs “arithmetic shift,” which keeps the number’s sign unchanged by duplicating the sign bit. For an unsigned data type, it performs “logical shift,” which always shifts in zeros at the most significant bit.

In both cases, shifting right one bit is division by two, rounding towards negative infinity. For example,

(unsigned) 19 >> 2 ⇒ 4
(unsigned) 20 >> 2 ⇒ 5
(unsigned) 21 >> 2 ⇒ 5

For negative left operand a, a >> 1 is not equivalent to a / 2. They both divide by 2, but ‘/’ rounds toward zero.

The shift count must be zero or greater. Shifting by a negative number of bits gives machine-dependent results.

6.7.2 Caveats for Shift Operations

Warning: If the shift count is greater than or equal to the width in bits of the promoted first operand, the results are machine-dependent. Logically speaking, the “correct” value would be either -1 (for right shift of a negative number) or 0 (in all other cases), but the actual result is whatever the machine’s shift instruction does in that case. So unless you can prove that the second operand is not too large, write code to check it at run time.

Warning: Never rely on how the shift operators relate in precedence to other arithmetic binary operators. Programmers don’t remember these precedences, and won’t understand the code. Always use parentheses to explicitly specify the nesting, like this:

a + (b << 5)   /* Shift first, then add.  */
(a + b) << 5   /* Add first, then shift.  */

Note: according to the C standard, shifting of signed values isn’t guaranteed to work properly when the value shifted is negative, or becomes negative during the operation of shifting left. However, only pedants have a reason to be concerned about this; only computers with strange shift instructions could plausibly do this wrong. In GNU C, the operation always works as expected,

6.7.3 Shift Hacks

You can use the shift operators for various useful hacks. For example, given a date specified by day of the month d, month m, and year y, you can store the entire date in a single integer date:

unsigned int d = 12;		/* 12 in binary is 0b1100.  */
unsigned int m = 6;             /* 6 in binary is 0b110.  */
unsigned int y = 1983;          /* 1983 in binary is 0b11110111111.  */
unsigned int date = (((y << 4) + m) << 5) + d;
                                /* Add 0b11110111111000000000
                                   and 0b11000000 and 0b1100.
                                   Sum is 0b11110111111011001100.  */

To extract the day, month, and year out of date, use a combination of shift and remainder:

/* 32 in binary is 0b100000.  */
/* Remainder dividing by 32 gives lowest 5 bits, 0b1100.  */
d = date % 32;
/* Shifting 5 bits right discards the day, leaving 0b111101111110110.
   Remainder dividing by 16 gives lowest remaining 4 bits, 0b110.  */
m = (date >> 5) % 16;
/* Shifting 9 bits right discards day and month,
   leaving 0b111101111110.  */
y = date >> 9;

-1 << LOWBITS is a clever way to make an integer whose LOWBITS lowest bits are all 0 and the rest are all 1. -(1 << LOWBITS) is equivalent to that, due to associativity of multiplication, since negating a value is equivalent to multiplying it by -1.

6.8 Bitwise Operations

Bitwise operators operate on integers, treating each bit independently. They are not allowed for floating-point types.

The examples in this section use binary constants, starting with ‘0b’ (see Integer Constants). They stand for 32-bit integers of type int.

~a

Unary operator for bitwise negation; this changes each bit of a from 1 to 0 or from 0 to 1.

~0b10101000 ⇒ 0b11111111111111111111111101010111
~0 ⇒ 0b11111111111111111111111111111111
~0b11111111111111111111111111111111 ⇒ 0
~ (-1) ⇒ 0

It is useful to remember that ~x + 1 equals -x, for integers, and ~x equals -x - 1. The last example above shows this with -1 as x.

a & b

Binary operator for bitwise “and” or “conjunction.” Each bit in the result is 1 if that bit is 1 in both a and b.

0b10101010 & 0b11001100 ⇒ 0b10001000

a | b

Binary operator for bitwise “or” (“inclusive or” or “disjunction”). Each bit in the result is 1 if that bit is 1 in either a or b.

0b10101010 | 0b11001100 ⇒ 0b11101110

a ^ b

Binary operator for bitwise “xor” (“exclusive or”). Each bit in the result is 1 if that bit is 1 in exactly one of a and b.

0b10101010 ^ 0b11001100 ⇒ 0b01100110

To understand the effect of these operators on signed integers, keep in mind that all modern computers use two’s-complement representation (see Integer Representations) for negative integers. This means that the highest bit of the number indicates the sign; it is 1 for a negative number and 0 for a positive number. In a negative number, the value in the other bits increases as the number gets closer to zero, so that 0b111…111 is -1 and 0b100…000 is the most negative possible integer.

Warning: C defines a precedence ordering for the bitwise binary operators, but you should never rely on it. You should never rely on how bitwise binary operators relate in precedence to the arithmetic and shift binary operators. Other programmers don’t remember this precedence ordering, so always use parentheses to explicitly specify the nesting.

For example, suppose offset is an integer that specifies the offset within shared memory of a table, except that its bottom few bits (LOWBITS says how many) are special flags. Here’s how to get just that offset and add it to the base address.

shared_mem_base + (offset & (-1 << LOWBITS))

Thanks to the outer set of parentheses, we don’t need to know whether ‘&’ has higher precedence than ‘+’. Thanks to the inner set, we don’t need to know whether ‘&’ has higher precedence than ‘<<’. But we can rely on all unary operators to have higher precedence than any binary operator, so we don’t need parentheses around the left operand of ‘<<’.

7 Assignment Expressions

As a general concept in programming, an assignment is a construct that stores a new value into a place where values can be stored—for instance, in a variable. Such places are called lvalues (see Lvalues) because they are locations that hold a value.

An assignment in C is an expression because it has a value; we call it an assignment expression. A simple assignment looks like

lvalue = value-to-store

We say it assigns the value of the expression value-to-store to the location lvalue, or that it stores value-to-store there. You can think of the “l” in “lvalue” as standing for “left,” since that’s what you put on the left side of the assignment operator.

However, that’s not the only way to use an lvalue, and not all lvalues can be assigned to. To use the lvalue in the left side of an assignment, it has to be modifiable. In C, that means it was not declared with the type qualifier const (see const).

The value of the assignment expression is that of lvalue after the new value is stored in it. This means you can use an assignment inside other expressions. Assignment operators are right-associative so that

x = y = z = 0;

is equivalent to

x = (y = (z = 0));

This is the only useful way for them to associate; the other way,

((x = y) = z) = 0;

would be invalid since an assignment expression such as x = y is not valid as an lvalue.

Warning: Write parentheses around an assignment if you nest it inside another expression, unless that is a conditional expression, or comma-separated series, or another assignment.

7.1 Simple Assignment

A simple assignment expression computes the value of the right operand and stores it into the lvalue on the left. Here is a simple assignment expression that stores 5 in i:

i = 5

We say that this is an assignment to the variable i and that it assigns i the value 5. It has no semicolon because it is an expression (so it has a value). Adding a semicolon at the end would make it a statement (see Expression Statement).

Here is another example of a simple assignment expression. Its operands are not simple, but the kind of assignment done here is simple assignment.

x[foo ()] = y + 6

A simple assignment with two different numeric data types converts the right operand value to the lvalue’s type, if possible. It can convert any numeric type to any other numeric type.

Simple assignment is also allowed on some non-numeric types: pointers (see Pointers), structures (see Structure Assignment), and unions (see Unions).

Warning: Assignment is not allowed on arrays because there are no array values in C; C variables can be arrays, but these arrays cannot be manipulated as wholes. See Limitations of C Arrays.

See Assignment Type Conversions, for the complete rules about data types used in assignments.

7.2 Lvalues

An expression that identifies a memory space that holds a value is called an lvalue, because it is a location that can hold a value.

The standard kinds of lvalues are:

• A variable.
• A pointer-dereference expression (see Pointer Dereference) using unary ‘*’.
• A structure field reference (see Structures) using ‘.’, if the structure value is an lvalue.
• A structure field reference using ‘->’. This is always an lvalue since ‘->’ implies pointer dereference.
• A union alternative reference (see Unions), on the same conditions as for structure fields.
• An array-element reference using ‘[…]’, if the array is an lvalue.

If an expression’s outermost operation is any other operator, that expression is not an lvalue. Thus, the variable x is an lvalue, but x + 0 is not, even though these two expressions compute the same value (assuming x is a number).

An array can be an lvalue (the rules above determine whether it is one), but using the array in an expression converts it automatically to a pointer to the zeroth element. The result of this conversion is not an lvalue. Thus, if the variable a is an array, you can’t use a by itself as the left operand of an assignment. But you can assign to an element of a, such as a[0]. That is an lvalue since a is an lvalue.

7.3 Modifying Assignment

You can abbreviate the common construct

lvalue = lvalue + expression

as

lvalue += expression

This is known as a modifying assignment. For instance,

i = i + 5;
i += 5;

shows two statements that are equivalent. The first uses simple assignment; the second uses modifying assignment.

Modifying assignment works with any binary arithmetic operator. For instance, you can subtract something from an lvalue like this,

lvalue -= expression

or multiply it by a certain amount like this,

lvalue *= expression

or shift it by a certain amount like this.

lvalue <<= expression
lvalue >>= expression

In most cases, this feature adds no power to the language, but it provides substantial convenience. Also, when lvalue contains code that has side effects, the simple assignment performs those side effects twice, while the modifying assignment performs them once. For instance,

x[foo ()] = x[foo ()] + 5;

calls foo twice, and it could return different values each time. If foo () returns 1 the first time and 3 the second time, then the effect could be to add x[3] and 5 and store the result in x[1], or to add x[1] and 5 and store the result in x[3]. We don’t know which of the two it will do, because C does not specify which call to foo is computed first.

Such a statement is not well defined, and shouldn’t be used.

By contrast,

x[foo ()] += 5;

is well defined: it calls foo only once to determine which element of x to adjust, and it adjusts that element by adding 5 to it.

7.4 Increment and Decrement Operators

The operators ‘++’ and ‘--’ are the increment and decrement operators. When used on a numeric value, they add or subtract 1. We don’t consider them assignments, but they are equivalent to assignments.

Using ‘++’ or ‘--’ as a prefix, before an lvalue, is called preincrement or predecrement. This adds or subtracts 1 and the result becomes the expression’s value. For instance,

#include <stdio.h>   /* Declares printf. */

int
main (void)
{
  int i = 5;
  printf ("%d\n", i);
  printf ("%d\n", ++i);
  printf ("%d\n", i);
  return 0;
}

prints lines containing 5, 6, and 6 again. The expression ++i increments i from 5 to 6, and has the value 6, so the output from printf on that line says ‘6’.

Using ‘--’ instead, for predecrement,

#include <stdio.h>   /* Declares printf. */

int
main (void)
{
  int i = 5;
  printf ("%d\n", i);
  printf ("%d\n", --i);
  printf ("%d\n", i);
  return 0;
}

prints three lines that contain (respectively) ‘5’, ‘4’, and again ‘4’.

7.5 Postincrement and Postdecrement

Using ‘++’ or ‘--’ after an lvalue does something peculiar: it gets the value directly out of the lvalue and then increments or decrements it. Thus, the value of i++ is the same as the value of i, but i++ also increments i “a little later.” This is called postincrement or postdecrement.

For example,

#include <stdio.h>   /* Declares printf. */

int
main (void)
{
  int i = 5;
  printf ("%d\n", i);
  printf ("%d\n", i++);
  printf ("%d\n", i);
  return 0;
}

prints lines containing 5, again 5, and 6. The expression i++ has the value 5, which is the value of i at the time, but it increments i from 5 to 6 just a little later.

How much later is “just a little later”? The compiler has some flexibility in deciding that. The rule is that the increment has to happen by the next sequence point; in simple cases, that means by the end of the statement. See Sequence Points.

Regardless of precisely where the compiled code increments the value of i, the crucial thing is that the value of i++ is the value that i has before incrementing it.

If a unary operator precedes a postincrement or postincrement expression, the increment nests inside:

-a++   is equivalent to   -(a++)

That’s the only order that makes sense; -a is not an lvalue, so it can’t be incremented.

The most common use of postincrement is with arrays. Here’s an example of using postincrement to access one element of an array and advance the index for the next access. Compare this with the example avg_of_double (see Array Example), which is almost the same but doesn’t use postincrement.

double
avg_of_double_alt (int length, double input_data[])
{
  double sum = 0;
  int i;

  /* Fetch each element and add it into sum.  */
  for (i = 0; i < length;)
    /* Use the index i, then increment it.  */
    sum += input_data[i++];

  return sum / length;
}

7.6 Pitfall: Assignment in Subexpressions

In C, the order of computing parts of an expression is not fixed. Aside from a few special cases, the operations can be computed in any order. If one part of the expression has an assignment to x and another part of the expression uses x, the result is unpredictable because that use might be computed before or after the assignment.

Here’s an example of ambiguous code:

x = 20;
printf ("%d %d\n", x, x = 4);

If the second argument, x, is computed before the third argument, x = 4, the second argument’s value will be 20. If they are computed in the other order, the second argument’s value will be 4.

Here’s one way to make that code unambiguous:

y = 20;
printf ("%d %d\n", y, x = 4);

Here’s another way, with the other meaning:

x = 4;
printf ("%d %d\n", x, x);

This issue applies to all kinds of assignments, and to the increment and decrement operators, which are equivalent to assignments. See Order of Execution, for more information about this.

However, it can be useful to write assignments inside an if-condition or while-test along with logical operators. See Logicals and Assignments.

7.7 Write Assignments in Separate Statements

It is often convenient to write an assignment inside an if-condition, but that can reduce the readability of the program. Here’s an example of what to avoid:

if (x = advance (x))
  …

The idea here is to advance x and test if the value is nonzero. However, readers might miss the fact that it uses ‘=’ and not ‘==’. In fact, writing ‘=’ where ‘==’ was intended inside a condition is a common error, so GNU C can give warnings when ‘=’ appears in a way that suggests it’s an error.

It is much clearer to write the assignment as a separate statement, like this:

x = advance (x);
if (x != 0)
  …

This makes it unmistakably clear that x is assigned a new value.

Another method is to use the comma operator (see Comma Operator), like this:

if (x = advance (x), x != 0)
  …

However, putting the assignment in a separate statement is usually clearer unless the assignment is very short, because it reduces nesting.

8 Execution Control Expressions

This chapter describes the C operators that combine expressions to control which of those expressions execute, or in which order.

8.1 Logical Operators

The logical operators combine truth values, which are normally represented in C as numbers. Any expression with a numeric value is a valid truth value: zero means false, and any other value means true. A pointer type is also meaningful as a truth value; a null pointer (which is zero) means false, and a non-null pointer means true (see Pointer Types). The value of a logical operator is always 1 or 0 and has type int (see Integer Types).

The logical operators are used mainly in the condition of an if statement, or in the end test in a for statement or while statement (see Statements). However, they are valid in any context where an integer-valued expression is allowed.

‘! exp’

Unary operator for logical “not.” The value is 1 (true) if exp is 0 (false), and 0 (false) if exp is nonzero (true).

Warning: if exp is anything but an lvalue or a function call, you should write parentheses around it.

‘left && right’

The logical “and” binary operator computes left and, if necessary, right. If both of the operands are true, the ‘&&’ expression gives the value 1 (which is true). Otherwise, the ‘&&’ expression gives the value 0 (false). If left yields a false value, that determines the overall result, so right is not computed.

‘left || right’

The logical “or” binary operator computes left and, if necessary, right. If at least one of the operands is true, the ‘||’ expression gives the value 1 (which is true). Otherwise, the ‘||’ expression gives the value 0 (false). If left yields a true value, that determines the overall result, so right is not computed.

Warning: never rely on the relative precedence of ‘&&’ and ‘||’. When you use them together, always use parentheses to specify explicitly how they nest, as shown here:

if ((r != 0 && x % r == 0)
    ||
    (s != 0 && x % s == 0))

8.2 Logical Operators and Comparisons

The most common thing to use inside the logical operators is a comparison. Conveniently, ‘&&’ and ‘||’ have lower precedence than comparison operators and arithmetic operators, so we can write expressions like this without parentheses and get the nesting that is natural: two comparison operations that must both be true.

if (r != 0 && x % r == 0)

This example also shows how it is useful that ‘&&’ guarantees to skip the right operand if the left one turns out false. Because of that, this code never tries to divide by zero.

This is equivalent:

if (r && x % r == 0)

A truth value is simply a number, so using r as a truth value tests whether it is nonzero. But r’s meaning as en expression is not a truth value—it is a number to divide by. So it is better style to write the explicit != 0.

Here’s another equivalent way to write it:

if (!(r == 0) && x % r == 0)

This illustrates the unary ‘!’ operator, and the need to write parentheses around its operand.

8.3 Logical Operators and Assignments

There are cases where assignments nested inside the condition can actually make a program easier to read. Here is an example using a hypothetical type list which represents a list; it tests whether the list has at least two links, using hypothetical functions, nonempty which is true if the argument is a nonempty list, and list_next which advances from one list link to the next. We assume that a list is never a null pointer, so that the assignment expressions are always “true.”

if (nonempty (list)
    && (temp1 = list_next (list))
    && nonempty (temp1)
    && (temp2 = list_next (temp1)))
  …  /* use temp1 and temp2 */

Here we take advantage of the ‘&&’ operator to avoid executing the rest of the code if a call to nonempty returns “false.” The only natural place to put the assignments is among those calls.

It would be possible to rewrite this as several statements, but that could make it much more cumbersome. On the other hand, when the test is even more complex than this one, splitting it into multiple statements might be necessary for clarity.

If an empty list is a null pointer, we can dispense with calling nonempty:

if ((temp1 = list_next (list))
    && (temp2 = list_next (temp1)))
 …

8.4 Conditional Expression

C has a conditional expression that selects one of two expressions to compute and get the value from. It looks like this:

condition ? iftrue : iffalse

8.4.1 Rules for the Conditional Operator

The first operand, condition, should be a value that can be compared with zero—a number or a pointer. If it is true (nonzero), then the conditional expression computes iftrue and its value becomes the value of the conditional expression. Otherwise the conditional expression computes iffalse and its value becomes the value of the conditional expression. The conditional expression always computes just one of iftrue and iffalse, never both of them.

Here’s an example: the absolute value of a number x can be written as (x >= 0 ? x : -x).

Warning: The conditional expression operators have rather low syntactic precedence. Except when the conditional expression is used as an argument in a function call, write parentheses around it. For clarity, always write parentheses around it if it extends across more than one line.

Assignment operators and the comma operator (see Comma Operator) have lower precedence than conditional expression operators, so write parentheses around those when they appear inside a conditional expression. See Order of Execution.

8.4.2 Conditional Operator Branches

We call iftrue and iffalse the branches of the conditional.

The two branches should normally have the same type, but a few exceptions are allowed. If they are both numeric types, the conditional converts both to their common type (see Common Type).

With pointers (see Pointers), the two values can be pointers to nearly compatible types (see Compatible Types). In this case, the result type is a similar pointer whose target type combines all the type qualifiers (see Type Qualifiers) of both branches.

If one branch has type void * and the other is a pointer to an object (not to a function), the conditional converts the void * branch to the type of the other.

If one branch is an integer constant with value zero and the other is a pointer, the conditional converts zero to the pointer’s type.

In GNU C, you can omit iftrue in a conditional expression. In that case, if condition is nonzero, its value becomes the value of the conditional expression, after conversion to the common type. Thus,

x ? : y

has the value of x if that is nonzero; otherwise, the value of y.

Omitting iftrue is useful when condition has side effects. In that case, writing that expression twice would carry out the side effects twice, but writing it once does them just once. For example, if we suppose that the function next_element advances a pointer variable to point to the next element in a list and returns the new pointer,

next_element () ? : default_pointer

is a way to advance the pointer and use its new value if it isn’t null, but use default_pointer if that is null. We cannot do it this way,

next_element () ? next_element () : default_pointer

because that would advance the pointer a second time.

8.5 Comma Operator

The comma operator stands for sequential execution of expressions. The value of the comma expression comes from the last expression in the sequence; the previous expressions are computed only for their side effects. It looks like this:

exp1, exp2 …

You can bundle any number of expressions together this way, by putting commas between them.

8.5.1 The Uses of the Comma Operator

With commas, you can put several expressions into a place that requires just one expression—for example, in the header of a for statement. This statement

for (i = 0, j = 10, k = 20; i < n; i++)

contains three assignment expressions, to initialize i, j and k. The syntax of for requires just one expression for initialization; to include three assignments, we use commas to bundle them into a single larger expression, i = 0, j = 10, k = 20. This technique is also useful in the loop-advance expression, the last of the three inside the for parentheses.

In the for statement and the while statement (see Loop Statements), a comma provides a way to perform some side effect before the loop-exit test. For example,

while (printf ("At the test, x = %d\n", x), x != 0)

8.5.2 Clean Use of the Comma Operator

Always write parentheses around a series of comma operators, except when it is at top level in an expression statement, or within the parentheses of an if, for, while, or switch statement (see Statements). For instance, in

for (i = 0, j = 10, k = 20; i < n; i++)

the commas between the assignments are clear because they are between a parenthesis and a semicolon.

The arguments in a function call are also separated by commas, but that is not an instance of the comma operator. Note the difference between

foo (4, 5, 6)

which passes three arguments to foo and

foo ((4, 5, 6))

which uses the comma operator and passes just one argument (with value 6).

Warning: don’t use the comma operator around an argument of a function unless it makes the code more readable. When you do so, don’t put part of another argument on the same line. Instead, add a line break to make the parentheses around the comma operator easier to see, like this.

foo ((mumble (x, y), frob (z)),
     *p)

8.5.3 When Not to Use the Comma Operator

You can use a comma in any subexpression, but in most cases it only makes the code confusing, and it is clearer to raise all but the last of the comma-separated expressions to a higher level. Thus, instead of this:

x = (y += 4, 8);

it is much clearer to write this:

y += 4, x = 8;

or this:

y += 4;
x = 8;

Use commas only in the cases where there is no clearer alternative involving multiple statements.

By contrast, don’t hesitate to use commas in the expansion in a macro definition. The trade-offs of code clarity are different in that case, because the use of the macro may improve overall clarity so much that the ugliness of the macro’s definition is a small price to pay. See Macros.

9 Binary Operator Grammar

Binary operators are those that take two operands, one on the left and one on the right.

All the binary operators in C are syntactically left-associative. This means that a op b op c means (a op b) op c. However, the only operators you should repeat in this way without parentheses are ‘+’, ‘-’, ‘*’ and ‘/’, because those cases are clear from algebra. So it is OK to write a + b + c or a - b - c, but never a == b == c or a % b % c. For those operators, use explicit parentheses to show how the operations nest.

Each C operator has a precedence, which is its rank in the grammatical order of the various operators. The operators with the highest precedence grab adjoining operands first; these expressions then become operands for operators of lower precedence.

The precedence order of operators in C is fully specified, so any combination of operations leads to a well-defined nesting. We state only part of the full precedence ordering here because it is bad practice for C code to depend on the other cases. For cases not specified in this chapter, always use parentheses to make the nesting explicit.²

You can depend on this subsequence of the precedence ordering (stated from highest precedence to lowest):

1. Postfix operations: access to a field or alternative (‘.’ and ‘->’), array subscripting, function calls, and unary postfix operators.
2. Unary prefix operators.
3. Multiplication, division, and remainder (they have the same precedence).
4. Addition and subtraction (they have the same precedence).
5. Comparisons—but watch out!
6. Logical operators ‘&&’ and ‘||’—but watch out!
7. Conditional expression with ‘?’ and ‘:’.
8. Assignments.
9. Sequential execution (the comma operator, ‘,’).

Two of the lines in the above list say “but watch out!” That means that the line covers operators with subtly different precedence. Never depend on the grammar of C to decide how two comparisons nest; instead, always use parentheses to specify their nesting.

You can let several ‘&&’ operators associate, or several ‘||’ operators, but always use parentheses to show how ‘&&’ and ‘||’ nest with each other. See Logical Operators.

There is one other precedence ordering that code can depend on:

1. Unary postfix operators.
2. Bitwise and shift operators—but watch out!
3. Conditional expression with ‘?’ and ‘:’.

The caveat for bitwise and shift operators is like that for logical operators: you can let multiple uses of one bitwise operator associate, but always use parentheses to control nesting of dissimilar operators.

These lists do not specify any precedence ordering between the bitwise and shift operators of the second list and the binary operators above conditional expressions in the first list. When they come together, parenthesize them. See Bitwise Operations.

10 Order of Execution

The order of execution of a C program is not always obvious, and not necessarily predictable. This chapter describes what you can count on.

10.1 Reordering of Operands

The C language does not necessarily carry out operations within an expression in the order they appear in the code. For instance, in this expression,

foo () + bar ()

foo might be called first or bar might be called first. If foo updates a datum and bar uses that datum, the results can be unpredictable.

The unpredictable order of computation of subexpressions also makes a difference when one of them contains an assignment. We already saw this example of bad code,

x = 20;
printf ("%d %d\n", x, x = 4);

in which the second argument, x, has a different value depending on whether it is computed before or after the assignment in the third argument.

10.2 Associativity and Ordering

An associative binary operator, such as +, when used repeatedly can combine any number of operands. The operands’ values may be computed in any order.

If the values are integers and overflow can be ignored, they may be combined in any order. Thus, given four functions that return unsigned int, calling them and adding their results as here

(foo () + bar ()) + (baz () + quux ())

may add up the results in any order.

By contrast, arithmetic on signed integers, in which overflow is significant, is not always associative (see Integer Overflow). Thus, the additions must be done in the order specified, obeying parentheses and left-association. That means computing (foo () + bar ()) and (baz () + quux ()) first (in either order), then adding the two.

The same applies to arithmetic on floating-point values, since that too is not really associative. However, the GCC option -funsafe-math-optimizations allows the compiler to change the order of calculation when an associative operation (associative in exact mathematics) combines several operands. The option takes effect when compiling a module (see Compilation). Changing the order of association can enable the program to pipeline the floating point operations.

In all these cases, the four function calls can be done in any order. There is no right or wrong about that.

10.3 Sequence Points

There are some points in the code where C makes limited guarantees about the order of operations. These are called sequence points. Here is where they occur:

• At the end of a full expression; that is to say, an expression that is not part of a larger expression. All side effects specified by that expression are carried out before execution moves on to subsequent code.
• At the end of the first operand of certain operators: ‘,’, ‘&&’, ‘||’, and ‘?:’. All side effects specified by that expression are carried out before any execution of the next operand.

  The commas that separate arguments in a function call are not comma operators, and they do not create sequence points. The rule for function arguments and the rule for operands are different (see Ordering of Operands).

• Just before calling a function. All side effects specified by the argument expressions are carried out before calling the function.

  If the function to be called is not constant—that is, if it is computed by an expression—all side effects in that expression are carried out before calling the function.

The ordering imposed by a sequence point applies locally to a limited range of code, as stated above in each case. For instance, the ordering imposed by the comma operator does not apply to code outside the operands of that comma operator. Thus, in this code,

(x = 5, foo (x)) + x * x

the sequence point of the comma operator orders x = 5 before foo (x), but x * x could be computed before or after them.

10.4 Postincrement and Ordering

The ordering requirements for the postincrement and postdecrement operations (see Postincrement/Postdecrement) are loose: those side effects must happen “a little later,” before the next sequence point. That still leaves room for various orders that give different results. In this expression,

z = x++ - foo ()

it’s unpredictable whether x gets incremented before or after calling the function foo. If foo refers to x, it might see the old value or it might see the incremented value.

In this perverse expression,

x = x++

x will certainly be incremented but the incremented value may be replaced with the old value. That’s because the incrementation and the assignment may occur in either oder. If the incrementation of x occurs after the assignment to x, the incremented value will remain in place. But if the incrementation happens first, the assignment will put the not-yet-incremented value back into x, so the expression as a whole will leave x unchanged.

The conclusion: avoid such expressions. Take care, when you use postincrement and postdecrement, that the specific expression you use is not ambiguous as to order of execution.

10.5 Ordering of Operands

Operands and arguments can be computed in any order, but there are limits to this intermixing in GNU C:

• The operands of a binary arithmetic operator can be computed in either order, but they can’t be intermixed: one of them has to come first, followed by the other. Any side effects in the operand that’s computed first are executed before the other operand is computed.
• That applies to assignment operators too, except that, in simple assignment, the previous value of the left operand is unused.
• The arguments in a function call can be computed in any order, but they can’t be intermixed. Thus, one argument is fully computed, then another, and so on until they have all been done. Any side effects in one argument are executed before computation of another argument begins.

These rules don’t cover side effects caused by postincrement and postdecrement operators—those can be deferred up to the next sequence point.

If you want to get pedantic, the fact is that GCC can reorder the computations in many other ways provided that it doesn’t alter the result of running the program. However, because it doesn’t alter the result of running the program, it is negligible, unless you are concerned with the values in certain variables at various times as seen by other processes. In those cases, you should use volatile to prevent optimizations that would make them behave strangely. See volatile.

10.6 Optimization and Ordering

Sequence points limit the compiler’s freedom to reorder operations arbitrarily, but optimizations can still reorder them if the compiler concludes that this won’t alter the results. Thus, in this code,

x++;
y = z;
x++;

there is a sequence point after each statement, so the code is supposed to increment x once before the assignment to y and once after. However, incrementing x has no effect on y or z, and setting y can’t affect x, so the code could be optimized into this:

y = z;
x += 2;

Normally that has no effect except to make the program faster. But there are special situations where it can cause trouble due to things that the compiler cannot know about, such as shared memory. To limit optimization in those places, use the volatile type qualifier (see volatile).

11 Primitive Data Types

This chapter describes all the primitive data types of C—that is, all the data types that aren’t built up from other types. They include the types int and double that we’ve already covered.

These types are all made up of bytes (see Storage).

11.1 Integer Data Types

Here we describe all the integer types and their basic characteristics. See Integers in Depth, for more information about the bit-level integer data representations and arithmetic.

11.1.1 Basic Integers

Integer data types in C can be signed or unsigned. An unsigned type can represent only positive numbers and zero. A signed type can represent both positive and negative numbers, in a range spread almost equally on both sides of zero.

Aside from signedness, the integer data types vary in size: how many bytes long they are. The size determines the range of integer values the type can hold.

Here’s a list of the signed integer data types, with the sizes they have on most computers. Each has a corresponding unsigned type; see Signed and Unsigned Types.

signed char

One byte (8 bits). This integer type is used mainly for integers that represent characters, usually as elements of arrays or fields of other data structures.

short

short int

Two bytes (16 bits).

int

Four bytes (32 bits).

long

long int

Four bytes (32 bits) or eight bytes (64 bits), depending on the platform. Typically it is 32 bits on 32-bit computers and 64 bits on 64-bit computers, but there are exceptions.

long long

long long int

Eight bytes (64 bits). Supported in GNU C in the 1980s, and incorporated into standard C as of ISO C99.

You can omit int when you use long or short. This is harmless and customary.

11.1.2 Signed and Unsigned Types

An unsigned integer type can represent only positive numbers and zero. A signed type can represent both positive and negative number, in a range spread almost equally on both sides of zero. For instance, unsigned char holds numbers from 0 to 255 (on most computers), while signed char holds numbers from -128 to 127. Each of these types holds 256 different possible values, since they are both 8 bits wide.

Write signed or unsigned before the type keyword to specify a signed or an unsigned type. However, the integer types other than char are signed by default; with them, signed is a no-op.

Plain char may be signed or unsigned; this depends on the compiler, the machine in use, and its operating system.

In many programs, it makes no difference whether char is signed. When it does matter, don’t leave it to chance; write signed char or unsigned char.³

11.1.3 Narrow Integers

The types that are narrower than int are rarely used for ordinary variables—we declare them int instead. This is because C converts those narrower types to int for any arithmetic. There is literally no reason to declare a local variable char, for instance.

In particular, if the value is really a character, you should declare the variable int. Not char! Using that narrow type can force the compiler to truncate values for conversion, which is a waste. Furthermore, some functions return either a character value, or -1 for “no character.” Using int makes it possible to distinguish -1 from a character by sign.

The narrow integer types are useful as parts of other objects, such as arrays and structures. Compare these array declarations, whose sizes on 32-bit processors are shown:

signed char ac[1000];   /* 1000 bytes */
short as[1000];         /* 2000 bytes */
int ai[1000];           /* 4000 bytes */
long long all[1000];    /* 8000 bytes */

In addition, character strings must be made up of chars, because that’s what all the standard library string functions expect. Thus, array ac could be used as a character string, but the others could not be.

11.1.4 Conversion among Integer Types

C converts between integer types implicitly in many situations. It converts the narrow integer types, char and short, to int whenever they are used in arithmetic. Assigning a new value to an integer variable (or other lvalue) converts the value to the variable’s type.

You can also convert one integer type to another explicitly with a cast operator. See Explicit Type Conversion.

The process of conversion to a wider type is straightforward: the value is unchanged. The only exception is when converting a negative value (in a signed type, obviously) to a wider unsigned type. In that case, the result is a positive value with the same bits (see Integers in Depth).

Converting to a narrower type, also called truncation, involves discarding some of the value’s bits. This is not considered overflow (see Integer Overflow) because loss of significant bits is a normal consequence of truncation. Likewise for conversion between signed and unsigned types of the same width.

More information about conversion for assignment is in Assignment Type Conversions. For conversion for arithmetic, see Argument Promotions.

11.1.5 Boolean Type

The unsigned integer type bool holds truth values: its possible values are 0 and 1. Converting any nonzero value to bool results in 1. For example:

bool a = 0;
bool b = 1;
bool c = 4; /* Stores the value 1 in c.  */

Unlike int, bool is not a keyword. It is defined in the header file stdbool.h.

11.1.6 Integer Variations

The integer types of C have standard names, but what they mean varies depending on the kind of platform in use: which kind of computer, which operating system, and which compiler. It may even depend on the compiler options used.

Plain char may be signed or unsigned; this depends on the platform, too. Even for GNU C, there is no general rule.

In theory, all of the integer types’ sizes can vary. char is always considered one “byte” for C, but it is not necessarily an 8-bit byte; on some platforms it may be more than 8 bits. ISO C specifies only that none of these types is narrower than the ones above it in the list in Basic Integers, and that short has at least 16 bits.

It is possible that in the future GNU C will support platforms where int is 64 bits long. In practice, however, on today’s real computers, there is little variation; you can rely on the table given previously (see Basic Integers).

To be completely sure of the size of an integer type, use the types int16_t, int32_t and int64_t. Their corresponding unsigned types add ‘u’ at the front: uint16_t, uint32_t and uint64_t. To define all these types, include the header file stdint.h.

The GNU C Compiler can compile for some embedded controllers that use two bytes for int. On some, int is just one “byte,” and so is short int—but that “byte” may contain 16 bits or even 32 bits. These processors can’t support an ordinary operating system (they may have their own specialized operating systems), and most C programs do not try to support them.

11.2 Floating-Point Data Types

Floating point is the binary analogue of scientific notation: internally it represents a number as a fraction and a binary exponent; the value is that fraction multiplied by the specified power of 2. (The C standard nominally permits other bases, but in GNU C the base is always 2.)

For instance, to represent 6, the fraction would be 0.75 and the exponent would be 3; together they stand for the value 0.75 * 2³, meaning 0.75 * 8. The value 1.5 would use 0.75 as the fraction and 1 as the exponent. The value 0.75 would use 0.75 as the fraction and 0 as the exponent. The value 0.375 would use 0.75 as the fraction and -1 as the exponent.

These binary exponents are used by machine instructions. You can write a floating-point constant this way if you wish, using hexadecimal; but normally we write floating-point numbers in decimal (base 10). See Floating Constants.

C has three floating-point data types:

double

“Double-precision” floating point, which uses 64 bits. This is the normal floating-point type, and modern computers normally do their floating-point computations in this type, or some wider type. Except when there is a special reason to do otherwise, this is the type to use for floating-point values.

float

“Single-precision” floating point, which uses 32 bits. It is useful for floating-point values stored in structures and arrays, to save space when the full precision of double is not needed. In addition, single-precision arithmetic is faster on some computers, and occasionally that is useful. But not often—most programs don’t use the type float.

C would be cleaner if float were the name of the type we use for most floating-point values; however, for historical reasons, that’s not so.

long double

“Extended-precision” floating point is either 80-bit or 128-bit precision, depending on the machine in use. On some machines, which have no floating-point format wider than double, this is equivalent to double.

Floating-point arithmetic raises many subtle issues. See Floating Point in Depth, for more information.

11.3 Complex Data Types

Complex numbers can include both a real part and an imaginary part. The numeric constants covered above have real-numbered values. An imaginary-valued constant is an ordinary real-valued constant followed by ‘i’.

To declare numeric variables as complex, use the _Complex keyword.⁴ The standard C complex data types are floating point,

_Complex float foo;
_Complex double bar;
_Complex long double quux;

but GNU C supports integer complex types as well.

Since _Complex is a keyword just like float and double and long, the keywords can appear in any order, but the order shown above seems most logical.

GNU C supports constants for complex values; for instance, 4.0 + 3.0i has the value 4 + 3i as type _Complex double. See Imaginary Constants.

To pull the real and imaginary parts of the number back out, GNU C provides the keywords __real__ and __imag__:

_Complex double foo = 4.0 + 3.0i;

double a = __real__ foo; /* a is now 4.0. */
double b = __imag__ foo; /* b is now 3.0. */

Standard C does not include these keywords, and instead relies on functions defined in complex.h for accessing the real and imaginary parts of a complex number: crealf, creal, and creall extract the real part of a float, double, or long double complex number, respectively; cimagf, cimag, and cimagl extract the imaginary part.

GNU C also defines ‘~’ as an operator for complex conjugation, which means negating the imaginary part of a complex number:

_Complex double foo = 4.0 + 3.0i;
_Complex double bar = ~foo; /* bar is now 4 - 3i. */

For standard C compatibility, you can use the appropriate library function: conjf, conj, or confl.

11.4 The Void Type

The data type void is a dummy—it allows no operations. It really means “no value at all.” When a function is meant to return no value, we write void for its return type. Then return statements in that function should not specify a value (see return Statement). Here’s an example:

void
print_if_positive (double x, double y)
{
  if (x <= 0)
    return;
  if (y <= 0)
    return;
  printf ("Next point is (%f,%f)\n", x, y);
}

A void-returning function is comparable to what some other languages (for instance, Fortran and Pascal) call a “procedure” instead of a “function.”

11.5 Other Data Types

Beyond the primitive types, C provides several ways to construct new data types. For instance, you can define pointers, values that represent the addresses of other data (see Pointers). You can define structures, as in many other languages (see Structures), and unions, which define multiple ways to interpret the contents of the same memory space (see Unions). Enumerations are collections of named integer codes (see Enumeration Types).

Array types in C are used for allocating space for objects, but C does not permit operating on an array value as a whole. See Arrays.

11.6 Type Designators

Some C constructs require a way to designate a specific data type independent of any particular variable or expression which has that type. The way to do this is with a type designator. The constructs that need one include casts (see Explicit Type Conversion) and sizeof (see Type Size).

We also use type designators to talk about the type of a value in C, so you will see many type designators in this manual. When we say, “The value has type int,” int is a type designator.

To make the designator for any type, imagine a variable declaration for a variable of that type and delete the variable name and the final semicolon.

For example, to designate the type of full-word integers, we start with the declaration for a variable foo with that type, which is this:

int foo;

Then we delete the variable name foo and the semicolon, leaving int—exactly the keyword used in such a declaration. Therefore, the type designator for this type is int.

What about long unsigned integers? From the declaration

unsigned long int foo;

we determine that the designator is unsigned long int.

Following this procedure, the designator for any primitive type is simply the set of keywords which specifies that type in a declaration. The same is true for compound types such as structures, unions, and enumerations.

Designators for pointer types do follow the rule of deleting the variable name and semicolon, but the result is not so simple. See Pointer Type Designators, as part of the chapter about pointers. See Array Type Designators), for designators for array types.

To understand what type a designator stands for, imagine a variable name inserted into the right place in the designator to make a valid declaration. What type would that variable be declared as? That is the type the designator designates.

12 Constants

A constant is an expression that stands for a specific value by explicitly representing the desired value. C allows constants for numbers, characters, and strings. We have already seen numeric and string constants in the examples.

12.1 Integer Constants

An integer constant consists of a number to specify the value, followed optionally by suffix letters to specify the data type.

The simplest integer constants are numbers written in base 10 (decimal), such as 5, 77, and 403. A decimal constant cannot start with the character ‘0’ (zero) because that makes the constant octal.

You can get the effect of a negative integer constant by putting a minus sign at the beginning. In grammatical terms, that is an arithmetic expression rather than a constant, but it behaves just like a true constant.

Integer constants can also be written in octal (base 8), hexadecimal (base 16), or binary (base 2). An octal constant starts with the character ‘0’ (zero), followed by any number of octal digits (‘0’ to ‘7’):

0      // zero
077    // 63
0403   // 259

Pedantically speaking, the constant 0 is an octal constant, but we can think of it as decimal; it has the same value either way.

A hexadecimal constant starts with ‘0x’ (upper or lower case) followed by hex digits (‘0’ to ‘9’, as well as ‘a’ through ‘f’ in upper or lower case):

0xff   // 255
0XA0   // 160
0xffFF // 65535

A binary constant starts with ‘0b’ (upper or lower case) followed by bits (each represented by the characters ‘0’ or ‘1’):

0b101  // 5

Binary constants are a GNU C extension, not part of the C standard.

Sometimes a space is needed after an integer constant to avoid lexical confusion with the following tokens. See Invalid Numbers.

12.2 Integer Constant Data Types

The type of an integer constant is normally int, if the value fits in that type, but here are the complete rules. The type of an integer constant is the first one in this sequence that can properly represent the value,

1. int
2. unsigned int
3. long int
4. unsigned long int
5. long long int
6. unsigned long long int

and that isn’t excluded by the following rules.

If the constant has ‘l’ or ‘L’ as a suffix, that excludes the first two types (non-long).

If the constant has ‘ll’ or ‘LL’ as a suffix, that excludes first four types (non-long long).

If the constant has ‘u’ or ‘U’ as a suffix, that excludes the signed types.

Otherwise, if the constant is decimal (not binary, octal, or hexadecimal), that excludes the unsigned types.

Here are some examples of the suffixes.

3000000000u      // three billion as unsigned int.
0LL              // zero as a long long int.
0403l            // 259 as a long int.

Suffixes in integer constants are rarely used. When the precise type is important, it is cleaner to convert explicitly (see Explicit Type Conversion).

See Integer Types.

12.3 Floating-Point Constants

A floating-point constant must have either a decimal point, an exponent-of-ten, or both; they distinguish it from an integer constant.

To indicate an exponent, write ‘e’ or ‘E’. The exponent value follows. It is always written as a decimal number; it can optionally start with a sign. The exponent n means to multiply the constant’s value by ten to the nth power.

Thus, ‘1500.0’, ‘15e2’, ‘15e+2’, ‘15.0e2’, ‘1.5e+3’, ‘.15e4’, and ‘15000e-1’ are six ways of writing a floating-point number whose value is 1500. They are all equivalent in principle.

Here are more examples with decimal points:

1.0
1000.
3.14159
.05
.0005

For each of them, here are some equivalent constants written with exponents:

1e0, 1.0000e0
100e1, 100e+1, 100E+1, 1e3, 10000e-1
3.14159e0
5e-2, .0005e+2, 5E-2, .0005E2
.05e-2

A floating-point constant normally has type double. You can force it to type float by adding ‘f’ or ‘F’ at the end. For example,

3.14159f
3.14159e0f
1000.f
100E1F
.0005f
.05e-2f

Likewise, ‘l’ or ‘L’ at the end forces the constant to type long double.

You can use exponents in hexadecimal floating constants, but since ‘e’ would be interpreted as a hexadecimal digit, the character ‘p’ or ‘P’ (for “power”) indicates an exponent.

The exponent in a hexadecimal floating constant is an optionally signed decimal integer that specifies a power of 2 (not 10 or 16) to multiply into the number.

Here are some examples:

0xAp2        // 40 in decimal
0xAp-1       // 5 in decimal
0x2.0Bp4     // 32.6875 decimal
0xE.2p3      // 113 decimal
0x123.ABCp0  // 291.6708984375 in decimal
0x123.ABCp4  // 4666.734375 in decimal
0x100p-8     // 1
0x10p-4      // 1
0x1p+4       // 16
0x1p+8       // 256

See Floating-Point Data Types.

12.4 Imaginary Constants

A complex number consists of a real part plus an imaginary part. (You may omit one part if it is zero.) This section explains how to write numeric constants with imaginary values. By adding these to ordinary real-valued numeric constants, we can make constants with complex values.

The simple way to write an imaginary-number constant is to attach the suffix ‘i’ or ‘I’, or ‘j’ or ‘J’, to an integer or floating-point constant. For example, 2.5fi has type _Complex float and 3i has type _Complex int. The four alternative suffix letters are all equivalent.

The other way to write an imaginary constant is to multiply a real constant by _Complex_I, which represents the imaginary number i. Standard C doesn’t support suffixing with ‘i’ or ‘j’, so this clunky method is needed.

To write a complex constant with a nonzero real part and a nonzero imaginary part, write the two separately and add them, like this:

4.0 + 3.0i

That gives the value 4 + 3i, with type _Complex double.

Such a sum can include multiple real constants, or none. Likewise, it can include multiple imaginary constants, or none. For example:

_Complex double foo, bar, quux;

foo = 2.0i + 4.0 + 3.0i; /* Imaginary part is 5.0. */
bar = 4.0 + 12.0; /* Imaginary part is 0.0. */
quux = 3.0i + 15.0i; /* Real part is 0.0. */

See Complex Data Types.

12.5 Invalid Numbers

Some number-like constructs which are not really valid as numeric constants are treated as numbers in preprocessing directives. If these constructs appear outside of preprocessing, they are erroneous. See Preprocessing Tokens.

Sometimes we need to insert spaces to separate tokens so that they won’t be combined into a single number-like construct. For example, 0xE+12 is a preprocessing number that is not a valid numeric constant, so it is a syntax error. If what we want is the three tokens 0xE + 12, we have to insert two spaces as separators.

12.6 Character Constants

A character constant is written with single quotes, as in 'c'. In the simplest case, c is a single ASCII character that the constant should represent. The constant has type int, and its value is the character code of that character. For instance, 'a' represents the character code for the letter ‘a’: 97, that is.

To put the ‘'’ character (single quote) in the character constant, escape it with a backslash (‘\’). This character constant looks like '\''. The backslash character here functions as an escape character, and such a sequence, starting with ‘\’, is called an escape sequence.

To put the ‘\’ character (backslash) in the character constant, escape it with ‘\’ (another backslash). This character constant looks like '\\'.

Here are all the escape sequences that represent specific characters in a character constant. The numeric values shown are the corresponding ASCII character codes, as decimal numbers.

'\a' ⇒ 7       /* alarm, CTRL-g */
'\b' ⇒ 8       /* backspace, BS, CTRL-h */
'\t' ⇒ 9       /* tab, TAB, CTRL-i */
'\n' ⇒ 10      /* newline, CTRL-j */
'\v' ⇒ 11      /* vertical tab, CTRL-k */
'\f' ⇒ 12      /* formfeed, CTRL-l */
'\r' ⇒ 13      /* carriage return, RET, CTRL-m */
'\e' ⇒ 27      /* escape character, ESC, CTRL-[ */
'\\' ⇒ 92      /* backslash character, \ */
'\'' ⇒ 39      /* single quote character, ' */
'\"' ⇒ 34      /* double quote character, " */
'\?' ⇒ 63      /* question mark, ? */

‘\e’ is a GNU C extension; to stick to standard C, write ‘\33’. (The number after ‘backslash’ is octal.) To specify a character constant using decimal, use a cast; for instance, (unsigned char) 27.

You can also write octal and hex character codes as ‘\octalcode’ or ‘\xhexcode’. Decimal is not an option here, so octal codes do not need to start with ‘0’.

The character constant’s value has type int. However, the character code is treated initially as a char value, which is then converted to int. If the character code is greater than 127 (0177 in octal), the resulting int may be negative on a platform where the type char is 8 bits long and signed.

12.7 String Constants

A string constant represents a series of characters. It starts with ‘"’ and ends with ‘"’; in between are the contents of the string. Quoting special characters such as ‘"’, ‘\’ and newline in the contents works in string constants as in character constants. In a string constant, ‘'’ does not need to be quoted.

A string constant defines an array of characters which contains the specified characters followed by the null character (code 0). Using the string constant is equivalent to using the name of an array with those contents. In simple cases, where there are no backslash escape sequences, the length in bytes of the string constant is one greater than the number of characters written in it.

As with any array in C, using the string constant in an expression converts the array to a pointer (see Pointers) to the array’s zeroth element (see Accessing Array Elements). This pointer will have type char * because it points to an element of type char. char * is an example of a type designator for a pointer type (see Pointer Type Designators). That type is used for strings generally, not just the strings expressed as constants in a program.

Thus, the string constant "Foo!" is almost equivalent to declaring an array like this

char string_array_1[] = {'F', 'o', 'o', '!', '\0' };

and then using string_array_1 in the program. There are two differences, however:

• The string constant doesn’t define a name for the array.
• The string constant is probably stored in a read-only area of memory.

Newlines are not allowed in the text of a string constant. The motive for this prohibition is to catch the error of omitting the closing ‘"’. To put a newline in a constant string, write it as ‘\n’ in the string constant.

A real null character in the source code inside a string constant causes a warning. To put a null character in the middle of a string constant, write ‘\0’ or ‘\000’.

Consecutive string constants are effectively concatenated. Thus,

"Fo" "o!"   is equivalent to   "Foo!"

This is useful for writing a string containing multiple lines, like this:

"This message is so long that it needs more than\n"
"a single line of text.  C does not allow a newline\n"
"to represent itself in a string constant, so we have to\n"
"write \\n to put it in the string.  For readability of\n"
"the source code, it is advisable to put line breaks in\n"
"the source where they occur in the contents of the\n"
"constant.\n"

The sequence of a backslash and a newline is ignored anywhere in a C program, and that includes inside a string constant. Thus, you can write multi-line string constants this way:

"This is another way to put newlines in a string constant\n\
and break the line after them in the source code."

However, concatenation is the recommended way to do this.

You can also write perverse string constants like this,

"Fo\
o!"

but don’t do that—write it like this instead:

"Foo!"

Be careful to avoid passing a string constant to a function that modifies the string it receives. The memory where the string constant is stored may be read-only, which would cause a fatal SIGSEGV signal that normally terminates the function (see Signals. Even worse, the memory may not be read-only. Then the function might modify the string constant, thus spoiling the contents of other string constants that are supposed to contain the same value and are unified by the compiler.

12.8 UTF-8 String Constants

Writing ‘u8’ immediately before a string constant, with no intervening space, means to represent that string in UTF-8 encoding as a sequence of bytes. UTF-8 represents ASCII characters with a single byte, and represents non-ASCII Unicode characters (codes 128 and up) as multibyte sequences. Here is an example of a UTF-8 constant:

u8"A cónstàñt"

This constant occupies 13 bytes plus the terminating null, because each of the accented letters is a two-byte sequence.

Concatenating an ordinary string with a UTF-8 string conceptually produces another UTF-8 string. However, if the ordinary string contains character codes 128 and up, the results cannot be relied on.

12.9 Unicode Character Codes

You can specify Unicode characters, for individual character constants or as part of string constants (see String Constants), using escape sequences; and even in C identifiers. Use the ‘\u’ escape sequence with a 16-bit hexadecimal Unicode character code. If the code value is too big for 16 bits, use the ‘\U’ escape sequence with a 32-bit hexadecimal Unicode character code. (These codes are called universal character names.) For example,

\u6C34      /* 16-bit code (UTF-16) */
\U0010ABCD  /* 32-bit code (UTF-32) */

One way to use these is in UTF-8 string constants (see UTF-8 String Constants). For instance,

u8"fóó \u6C34 \U0010ABCD"

You can also use them in wide character constants (see Wide Character Constants), like this:

u'\u6C34'      /* 16-bit code */
U'\U0010ABCD'  /* 32-bit code */

and in wide string constants (see Wide String Constants), like this:

u"\u6C34\u6C33"  /* 16-bit code */
U"\U0010ABCD"    /* 32-bit code */

And in an identifier:

int foo\u6C34bar = 0;

Codes in the range of D800 through DFFF are not valid in Unicode. Codes less than 00A0 are also forbidden, except for 0024, 0040, and 0060; these characters are actually ASCII control characters, and you can specify them with other escape sequences (see Character Constants).

12.10 Wide Character Constants

A wide character constant represents characters with more than 8 bits of character code. This is an obscure feature that we need to document but that you probably won’t ever use. If you’re just learning C, you may as well skip this section.

The original C wide character constant looks like ‘L’ (upper case!) followed immediately by an ordinary character constant (with no intervening space). Its data type is wchar_t, which is an alias defined in stddef.h for one of the standard integer types. Depending on the platform, it could be 16 bits or 32 bits. If it is 16 bits, these character constants use the UTF-16 form of Unicode; if 32 bits, UTF-32.

There are also Unicode wide character constants which explicitly specify the width. These constants start with ‘u’ or ‘U’ instead of ‘L’. ‘u’ specifies a 16-bit Unicode wide character constant, and ‘U’ a 32-bit Unicode wide character constant. Their types are, respectively, char16_t and char32_t; they are declared in the header file uchar.h. These character constants are valid even if uchar.h is not included, but some uses of them may be inconvenient without including it to declare those type names.

The character represented in a wide character constant can be an ordinary ASCII character. L'a', u'a' and U'a' are all valid, and they are all equal to 'a'.

In all three kinds of wide character constants, you can write a non-ASCII Unicode character in the constant itself; the constant’s value is the character’s Unicode character code. Or you can specify the Unicode character with an escape sequence (see Unicode Character Codes).

12.11 Wide String Constants

A wide string constant stands for an array of 16-bit or 32-bit characters. They are rarely used; if you’re just learning C, you may as well skip this section.

There are three kinds of wide string constants, which differ in the data type used for each character in the string. Each wide string constant is equivalent to an array of integers, but the data type of those integers depends on the kind of wide string. Using the constant in an expression will convert the array to a pointer to its zeroth element, as usual for arrays in C (see Accessing Array Elements). For each kind of wide string constant, we state here what type that pointer will be.

char16_t

This is a 16-bit Unicode wide string constant: each element is a 16-bit Unicode character code with type char16_t, so the string has the pointer type char16_t *. (That is a type designator; see Pointer Type Designators.) The constant is written as ‘u’ (which must be lower case) followed (with no intervening space) by a string constant with the usual syntax.

char32_t

This is a 32-bit Unicode wide string constant: each element is a 32-bit Unicode character code, and the string has type char32_t *. It’s written as ‘U’ (which must be upper case) followed (with no intervening space) by a string constant with the usual syntax.

wchar_t

This is the original kind of wide string constant. It’s written as ‘L’ (which must be upper case) followed (with no intervening space) by a string constant with the usual syntax, and the string has type wchar_t *.

The width of the data type wchar_t depends on the target platform, which makes this kind of wide string somewhat less useful than the newer kinds.

char16_t and char32_t are declared in the header file uchar.h. wchar_t is declared in stddef.h.

Consecutive wide string constants of the same kind concatenate, just like ordinary string constants. A wide string constant concatenated with an ordinary string constant results in a wide string constant. You can’t concatenate two wide string constants of different kinds. In addition, you can’t concatenate a wide string constant (of any kind) with a UTF-8 string constant.

13 Type Size

Each data type has a size, which is the number of bytes (see Storage) that it occupies in memory. To refer to the size in a C program, use sizeof. There are two ways to use it:

sizeof expression

This gives the size of expression, based on its data type. It does not calculate the value of expression, only its size, so if expression includes side effects or function calls, they do not happen. Therefore, sizeof is always a compile-time operation that has zero run-time cost.

A value that is a bit field (see Bit Fields) is not allowed as an operand of sizeof.

For example,

double a;

i = sizeof a + 10;

sets i to 18 on most computers because a occupies 8 bytes.

Here’s how to determine the number of elements in an array array:

(sizeof array / sizeof array[0])

The expression sizeof array gives the size of the array, not the size of a pointer to an element. However, if expression is a function parameter that was declared as an array, that variable really has a pointer type (see Array Parm Pointer), so the result is the size of that pointer.

sizeof (type)

This gives the size of type. For example,

i = sizeof (double) + 10;

is equivalent to the previous example.

You can’t apply sizeof to an incomplete type (see Incomplete Types), nor void. Using it on a function type gives 1 in GNU C, which makes adding an integer to a function pointer work as desired (see Pointer Arithmetic).

Warning: When you use sizeof with a type instead of an expression, you must write parentheses around the type.

Warning: When applying sizeof to the result of a cast (see Explicit Type Conversion), you must write parentheses around the cast expression to avoid an ambiguity in the grammar of C. Specifically,

sizeof (int) -x

parses as

(sizeof (int)) - x

If what you want is

sizeof ((int) -x)

you must write it that way, with parentheses.

The data type of the value of the sizeof operator is always one of the unsigned integer types; which one of those types depends on the machine. The header file stddef.h defines the typedef name size_t as an alias for this type. See Defining Typedef Names.

14 Pointers

Among high-level languages, C is rather low-level, close to the machine. This is mainly because it has explicit pointers. A pointer value is the numeric address of data in memory. The type of data to be found at that address is specified by the data type of the pointer itself. Nothing in C can determine the “correct” data type of data in memory; it can only blindly follow the data type of the pointer you use to access the data.

The unary operator ‘*’ gets the data that a pointer points to—this is called dereferencing the pointer. Its value always has the type that the pointer points to.

C also allows pointers to functions, but since there are some differences in how they work, we treat them later. See Function Pointers.

14.1 Address of Data

The most basic way to make a pointer is with the “address-of” operator, ‘&’. Let’s suppose we have these variables available:

int i;
double a[5];

Now, &i gives the address of the variable i—a pointer value that points to i’s location—and &a[3] gives the address of the element 3 of a. (By the usual 1-origin numbering convention of ordinary English, it is actually the fourth element in the array, since the element at the start has index 0.)

The address-of operator is unusual because it operates on a place to store a value (an lvalue, see Lvalues), not on the value currently stored there. (The left argument of a simple assignment is unusual in the same way.) You can use it on any lvalue except a bit field (see Bit Fields) or a constructor (see Structure Constructors).

14.2 Pointer Types

For each data type t, there is a type for pointers to type t. For these variables,

int i;
double a[5];

• i has type int; we say &i is a “pointer to int.”
• a has type double[5]; we say &a is a “pointer to arrays of five doubles.”
• a[3] has type double; we say &a[3] is a “pointer to double.”

14.3 Pointer-Variable Declarations

The way to declare that a variable foo points to type t is

t *foo;

To remember this syntax, think “if you dereference foo, using the ‘*’ operator, what you get is type t. Thus, foo points to type t.”

Thus, we can declare variables that hold pointers to these three types, like this:

int *ptri;            /* Pointer to int. */
double *ptrd;         /* Pointer to double. */
double (*ptrda)[5];   /* Pointer to double[5]. */

‘int *ptri;’ means, “if you dereference ptri, you get an int.” ‘double (*ptrda)[5];’ means, “if you dereference ptrda, then subscript it by an integer less than 5, you get a double.” The parentheses express the point that you would dereference it first, then subscript it.

Contrast the last one with this:

double *aptrd[5];     /* Array of five pointers to double. */

Because ‘*’ has lower syntactic precedence than subscripting, ‘double *aptrd[5]’ means, “if you subscript aptrd by an integer less than 5, then dereference it, you get a double.” Therefore, *aptrd[5] declares an array of pointers, not a pointer to an array.

14.4 Pointer-Type Designators

Every type in C has a designator; you make it by deleting the variable name and the semicolon from a declaration (see Type Designators). Here are the designators for the pointer types of the example declarations in the previous section:

int *           /* Pointer to int. */
double *        /* Pointer to double. */
double (*)[5]   /* Pointer to double[5]. */

Remember, to understand what type a designator stands for, imagine the corresponding variable declaration with a variable name in it, and figure out what type that variable would have. Thus, the type designator double (*)[5] corresponds to the variable declaration double (*variable)[5]. That declares a pointer variable which, when dereferenced, gives an array of 5 doubles. So the type designator means, “pointer to an array of 5 doubles.”

14.5 Dereferencing Pointers

The main use of a pointer value is to dereference it (access the data it points at) with the unary ‘*’ operator. For instance, *&i is the value at i’s address—which is just i. The two expressions are equivalent, provided &i is valid.

A pointer-dereference expression whose type is data (not a function) is an lvalue.

Pointers become really useful when we store them somewhere and use them later. Here’s a simple example to illustrate the practice:

{
  int i;
  int *ptr;

  ptr = &i;

  i = 5;

  …

  return *ptr;   /* Returns 5, fetched from i.  */
}

This shows how to declare the variable ptr as type int * (pointer to int), store a pointer value into it (pointing at i), and use it later to get the value of the object it points at (the value in i).

If anyone can provide a useful example which is this basic, I would be grateful.

14.6 Null Pointers

A pointer value can be null, which means it does not point to any object. The cleanest way to get a null pointer is by writing NULL, a standard macro defined in stddef.h. You can also do it by casting 0 to the desired pointer type, as in (char *) 0. (The cast operator performs explicit type conversion; See Explicit Type Conversion.)

You can store a null pointer in any lvalue whose data type is a pointer type:

char *foo;
foo = NULL;

These two, if consecutive, can be combined into a declaration with initializer,

char *foo = NULL;

You can also explicitly cast NULL to the specific pointer type you want—it makes no difference.

char *foo;
foo = (char *) NULL;

To test whether a pointer is null, compare it with zero or NULL, as shown here:

if (p != NULL)
  /* p is not null.  */
  operate (p);

Since testing a pointer for not being null is basic and frequent, all but beginners in C will understand the conditional without need for != NULL:

if (p)
  /* p is not null.  */
  operate (p);

14.7 Dereferencing Null or Invalid Pointers

Trying to dereference a null pointer is an error. On most platforms, it generally causes a signal, usually SIGSEGV (see Signals).

char *foo = NULL;
c = *foo;    /* This causes a signal and terminates.  */

Likewise a pointer that has the wrong alignment for the target data type (on most types of computer), or points to a part of memory that has not been allocated in the process’s address space.

The signal terminates the program, unless the program has arranged to handle the signal (see The GNU C Library in The GNU C Library Reference Manual).

However, the signal might not happen if the dereference is optimized away. In the example above, if you don’t subsequently use the value of c, GCC might optimize away the code for *foo. You can prevent such optimization using the volatile qualifier, as shown here:

volatile char *p;
volatile char c;
c = *p;

You can use this to test whether p points to unallocated memory. Set up a signal handler first, so the signal won’t terminate the program.

14.8 Void Pointers

The peculiar type void *, a pointer whose target type is void, is used often in C. It represents a pointer to we-don’t-say-what. Thus,

void *numbered_slot_pointer (int);

declares a function numbered_slot_pointer that takes an integer parameter and returns a pointer, but we don’t say what type of data it points to.

The functions for dynamic memory allocation (see Dynamic Memory Allocation) use type void * to refer to blocks of memory, regardless of what sort of data the program stores in those blocks.

With type void *, you can pass the pointer around and test whether it is null. However, dereferencing it gives a void value that can’t be used (see The Void Type). To dereference the pointer, first convert it to some other pointer type.

Assignments convert void * automatically to any other pointer type, if the left operand has a pointer type; for instance,

{
  int *p;
  /* Converts return value to int *.  */
  p = numbered_slot_pointer (5);
  …
}

Passing an argument of type void * for a parameter that has a pointer type also converts. For example, supposing the function hack is declared to require type float * for its parameter, this call to hack will convert the argument to that type.

/* Declare hack that way.
   We assume it is defined somewhere else.  */
void hack (float *);
…
/* Now call hack.  */
{
  /* Converts return value of numbered_slot_pointer
     to float * to pass it to hack.  */
  hack (numbered_slot_pointer (5));
  …
}

You can also convert to another pointer type with an explicit cast (see Explicit Type Conversion), like this:

(int *) numbered_slot_pointer (5)

Here is an example which decides at run time which pointer type to convert to:

void
extract_int_or_double (void *ptr, bool its_an_int)
{
  if (its_an_int)
    handle_an_int (*(int *)ptr);
  else
    handle_a_double (*(double *)ptr);
}

The expression *(int *)ptr means to convert ptr to type int *, then dereference it.

14.9 Pointer Comparison

Two pointer values are equal if they point to the same location, or if they are both null. You can test for this with == and !=. Here’s a trivial example:

{
  int i;
  int *p, *q;

  p = &i;
  q = &i;
  if (p == q)
    printf ("This will be printed.\n");
  if (p != q)
    printf ("This won't be printed.\n");
}

Ordering comparisons such as > and >= operate on pointers by converting them to unsigned integers. The C standard says the two pointers must point within the same object in memory, but on GNU/Linux systems these operations simply compare the numeric values of the pointers.

The pointer values to be compared should in principle have the same type, but they are allowed to differ in limited cases. First of all, if the two pointers’ target types are nearly compatible (see Compatible Types), the comparison is allowed.

If one of the operands is void * (see Void Pointers) and the other is another pointer type, the comparison operator converts the void * pointer to the other type so as to compare them. (In standard C, this is not allowed if the other type is a function pointer type, but it works in GNU C.)

Comparison operators also allow comparing the integer 0 with a pointer value. This works by converting 0 to a null pointer of the same type as the other operand.

14.10 Pointer Arithmetic

Adding an integer (positive or negative) to a pointer is valid in C. It assumes that the pointer points to an element in an array, and advances or retracts the pointer across as many array elements as the integer specifies. Here is an example, in which adding a positive integer advances the pointer to a later element in the same array.

void
incrementing_pointers ()
{
  int array[5] = { 45, 29, 104, -3, 123456 };
  int elt0, elt1, elt4;

  int *p = &array[0];
  /* Now p points at element 0.  Fetch it.  */
  elt0 = *p;

  ++p;
  /* Now p points at element 1.  Fetch it.  */
  elt1 = *p;

  p += 3;
  /* Now p points at element 4 (the last).  Fetch it.  */
  elt4 = *p;

  printf ("elt0 %d  elt1 %d  elt4 %d.\n",
          elt0, elt1, elt4);
  /* Prints elt0 45  elt1 29  elt4 123456.  */
}

Here’s an example where adding a negative integer retracts the pointer to an earlier element in the same array.

void
decrementing_pointers ()
{
  int array[5] = { 45, 29, 104, -3, 123456 };
  int elt0, elt3, elt4;

  int *p = &array[4];
  /* Now p points at element 4 (the last).  Fetch it.  */
  elt4 = *p;

  --p;
  /* Now p points at element 3.  Fetch it.  */
  elt3 = *p;

  p -= 3;
  /* Now p points at element 0.  Fetch it.  */
  elt0 = *p;

  printf ("elt0 %d  elt3 %d  elt4 %d.\n",
          elt0, elt3, elt4);
  /* Prints elt0 45  elt3 -3  elt4 123456.  */
}

If one pointer value was made by adding an integer to another pointer value, it should be possible to subtract the pointer values and recover that integer. That works too in C.

void
subtract_pointers ()
{
  int array[5] = { 45, 29, 104, -3, 123456 };
  int *p0, *p3, *p4;

  int *p = &array[4];
  /* Now p points at element 4 (the last).  Save the value.  */
  p4 = p;

  --p;
  /* Now p points at element 3.  Save the value.  */
  p3 = p;

  p -= 3;
  /* Now p points at element 0.  Save the value.  */
  p0 = p;

  printf ("%d, %d, %d, %d\n",
          p4 - p0, p0 - p0, p3 - p0, p0 - p3);
  /* Prints 4, 0, 3, -3.  */
}

The addition operation does not know where arrays begin or end in memory. All it does is add the integer (multiplied by target object size) to the numeric value of the pointer. When the initial pointer and the result point into the same array, the result is well-defined.

Warning: Only experts should do pointer arithmetic involving pointers into different memory objects.

The difference between two pointers has type int, or long if necessary (see Integer Types). The clean way to declare it is to use the typedef name ptrdiff_t defined in the file stddef.h.

C defines pointer subtraction to be consistent with pointer-integer addition, so that (p3 - p1) + p1 equals p3, as in ordinary algebra. Pointer subtraction works by subtracting p1’s numeric value from p3’s, and dividing by target object size. The two pointer arguments should point into the same array.

In standard C, addition and subtraction are not allowed on void *, since the target type’s size is not defined in that case. Likewise, they are not allowed on pointers to function types. However, these operations work in GNU C, and the “size of the target type” is taken as 1 byte.

14.11 Pointers and Arrays

The clean way to refer to an array element is array[index]. Another, complicated way to do the same job is to get the address of that element as a pointer, then dereference it: * (&array[0] + index) (or equivalently * (array + index)). This first gets a pointer to element zero, then increments it with + to point to the desired element, then gets the value from there.

That pointer-arithmetic construct is the definition of square brackets in C. a[b] means, by definition, *(a + b). This definition uses a and b symmetrically, so one must be a pointer and the other an integer; it does not matter which comes first.

Since indexing with square brackets is defined in terms of addition and dereferencing, that too is symmetrical. Thus, you can write 3[array] and it is equivalent to array[3]. However, it would be foolish to write 3[array], since it has no advantage and could confuse people who read the code.

It may seem like a discrepancy that the definition *(a + b) requires a pointer, while array[3] uses an array value instead. Why is this valid? The name of the array, when used by itself as an expression (other than in sizeof), stands for a pointer to the array’s zeroth element. Thus, array + 3 converts array implicitly to &array[0], and the result is a pointer to element 3, equivalent to &array[3].

Since square brackets are defined in terms of such an addition, array[3] first converts array to a pointer. That’s why it works to use an array directly in that construct.

14.12 Pointer Arithmetic at Low-Level

The behavior of pointer arithmetic is theoretically defined only when the pointer values all point within one object allocated in memory. But the addition and subtraction operators can’t tell whether the pointer values are all within one object. They don’t know where objects start and end. So what do they really do?

Adding pointer p to integer i treats p as a memory address, which is in fact an integer—call it pint. It treats i as a number of elements of the type that p points to. These elements’ sizes add up to i * sizeof (*p). So the sum, as an integer, is pint + i * sizeof (*p). This value is reinterpreted as a pointer of the same type as p.

If the starting pointer value p and the result do not point at parts of the same object, the operation is not officially legitimate, and C code is not “supposed” to do it. But you can do it anyway, and it gives precisely the results described by the procedure above. In some special situations it can do something useful, but non-wizards should avoid it.

Here’s a function to offset a pointer value as if it pointed to an object of any given size, by explicitly performing that calculation:

#include <stdint.h>

void *
ptr_add (void *p, int i, int objsize)
{
  intptr_t p_address = (long) p;
  intptr_t totalsize = i * objsize;
  intptr_t new_address = p_address + totalsize;
  return (void *) new_address;
}

This does the same job as p + i with the proper pointer type for p. It uses the type intptr_t, which is defined in the header file stdint.h. (In practice, long long would always work, but it is cleaner to use intptr_t.)

14.13 Pointer Increment and Decrement

The ‘++’ operator adds 1 to a variable. We have seen it for integers (see Increment/Decrement), but it works for pointers too. For instance, suppose we have a series of positive integers, terminated by a zero, and we want to add them up. Here is a simple way to step forward through the array by advancing a pointer.

int
sum_array_till_0 (int *p)
{
  int sum = 0;

  for (;;)
    {
      /* Fetch the next integer.  */
      int next = *p++;
      /* Exit the loop if it’s 0.  */
      if (next == 0)
        break;
      /* Add it into running total.  */
      sum += next;
    }

  return sum;
}

The statement ‘break;’ will be explained further on (see break Statement). Used in this way, it immediately exits the surrounding for statement.

*p++ uses postincrement (++; see Postincrement/Postdecrement) on the pointer p. that expression parses as *(p++), because a postfix operator always takes precedence over a prefix operator. Therefore, it dereferences the entering value of p, then increments p afterwards.

Incrementing a variable means adding 1 to it, as in p = p + 1. Since p is a pointer, adding 1 to it advances it by the width of the datum it points to—in this case, sizeof (int). Therefore, each iteration of the loop picks up the next integer from the series and puts it into next.

This for-loop has no initialization expression since p and sum are already initialized, has no end-test since the ‘break;’ statement will exit it, and needs no expression to advance it since that’s done within the loop by incrementing p and sum. Thus, those three expressions after for are left empty.

Another way to write this function is by keeping the parameter value unchanged and using indexing to access the integers in the table.

int
sum_array_till_0_indexing (int *p)
{
  int i;
  int sum = 0;

  for (i = 0; ; i++)
    {
      /* Fetch the next integer.  */
      int next = p[i];
      /* Exit the loop if it’s 0.  */
      if (next == 0)
        break;
      /* Add it into running total.  */
      sum += next;
    }

  return sum;
}

In this program, instead of advancing p, we advance i and add it to p. (Recall that p[i] means *(p + i).) Either way, it uses the same address to get the next integer.

It makes no difference in this program whether we write i++ or ++i, because the value of that expression is not used. We use it for its effect, to increment i.

The ‘--’ operator also works on pointers; it can be used to step backwards through an array, like this:

int
after_last_nonzero (int *p, int len)
{
  /* Set up q to point just after the last array element.  */
  int *q = p + len;

  while (q != p)
    /* Step q back until it reaches a nonzero element.  */
    if (*--q != 0)
      /* Return the index of the element after that nonzero.  */
      return q - p + 1;

  return 0;
}

That function returns the length of the nonzero part of the array specified by its arguments; that is, the index of the first zero of the run of zeros at the end.

14.14 Drawbacks of Pointer Arithmetic

Pointer arithmetic is clean and elegant, but it is also the cause of a major security flaw in the C language. Theoretically, it is only valid to adjust a pointer within one object allocated as a unit in memory. However, if you unintentionally adjust a pointer across the bounds of the object and into some other object, the system has no way to detect this error.

A bug which does that can easily result in clobbering (overwriting) part of another object. For example, with array[-1] you can read or write the nonexistent element before the beginning of an array—probably part of some other data.

Combining pointer arithmetic with casts between pointer types, you can create a pointer that fails to be properly aligned for its type. For example,

int a[2];
char *pa = (char *)a;
int *p = (int *)(pa + 1);

gives p a value pointing to an “integer” that includes part of a[0] and part of a[1]. Dereferencing that with *p can cause a fatal SIGSEGV signal or it can return the contents of that badly aligned int (see Signals. If it “works,” it may be quite slow. It can also cause aliasing confusions (see Aliasing).

Warning: Using improperly aligned pointers is risky—don’t do it unless it is really necessary.

14.15 Pointer-Integer Conversion

On modern computers, an address is simply a number. It occupies the same space as some size of integer. In C, you can convert a pointer to the appropriate integer types and vice versa, without losing information. The appropriate integer types are uintptr_t (an unsigned type) and intptr_t (a signed type). Both are defined in stdint.h.

For instance,

#include <stdint.h>
#include <stdio.h>

void
print_pointer (void *ptr)
{
  uintptr_t converted = (uintptr_t) ptr;

  printf ("Pointer value is 0x%x\n",
          (unsigned int) converted);
}

The specification ‘%x’ in the template (the first argument) for printf means to represent this argument using hexadecimal notation. It’s cleaner to use uintptr_t, since hexadecimal printing treats the number as unsigned, but it won’t actually matter: all printf gets to see is the series of bits in the number.

Warning: Converting pointers to integers is risky—don’t do it unless it is really necessary.

14.16 Printing Pointers

To print the numeric value of a pointer, use the ‘%p’ specifier. For example:

void
print_pointer (void *ptr)
{
  printf ("Pointer value is %p\n", ptr);
}

The specification ‘%p’ works with any pointer type. It prints ‘0x’ followed by the address in hexadecimal, printed as the appropriate unsigned integer type.

15 Structures

A structure is a user-defined data type that holds various fields of data. Each field has a name and a data type specified in the structure’s definition.

Here we define a structure suitable for storing a linked list of integers. Each list item will hold one integer, plus a pointer to the next item.

struct intlistlink
  {
    int datum;
    struct intlistlink *next;
  };

The structure definition has a type tag so that the code can refer to this structure. The type tag here is intlistlink. The definition refers recursively to the same structure through that tag.

You can define a structure without a type tag, but then you can’t refer to it again. That is useful only in some special contexts, such as inside a typedef or a union.

The contents of the structure are specified by the field declarations inside the braces. Each field in the structure needs a declaration there. The fields in one structure definition must have distinct names, but these names do not conflict with any other names in the program.

A field declaration looks just like a variable declaration. You can combine field declarations with the same beginning, just as you can combine variable declarations.

This structure has two fields. One, named datum, has type int and will hold one integer in the list. The other, named next, is a pointer to another struct intlistlink which would be the rest of the list. In the last list item, it would be NULL.

This structure definition is recursive, since the type of the next field refers to the structure type. Such recursion is not a problem; in fact, you can use the type struct intlistlink * before the definition of the type struct intlistlink itself. That works because pointers to all kinds of structures really look the same at the machine level.

After defining the structure, you can declare a variable of type struct intlistlink like this:

struct intlistlink foo;

The structure definition itself can serve as the beginning of a variable declaration, so you can declare variables immediately after, like this:

struct intlistlink
  {
    int datum;
    struct intlistlink *next;
  } foo;

But that is ugly. It is almost always clearer to separate the definition of the structure from its uses.

Declaring a structure type inside a block (see Blocks) limits the scope of the structure type name to that block. That means the structure type is recognized only within that block. Declaring it in a function parameter list, as here,

int f (struct foo {int a, b} parm);

(assuming that struct foo is not already defined) limits the scope of the structure type struct foo to that parameter list; that is basically useless, so it triggers a warning.

Standard C requires at least one field in a structure. GNU C does not require this.

15.1 Referencing Structure Fields

To make a structure useful, there has to be a way to examine and store its fields. The ‘.’ (period) operator does that; its use looks like object.field.

Given this structure and variable,

struct intlistlink
  {
    int datum;
    struct intlistlink *next;
  };

struct intlistlink foo;

you can write foo.datum and foo.next to refer to the two fields in the value of foo. These fields are lvalues, so you can store values into them, and read the values out again.

Most often, structures are dynamically allocated (see the next section), and we refer to the objects via pointers. (*p).field is somewhat cumbersome, so there is an abbreviation: p->field. For instance, assume the program contains this declaration:

struct intlistlink *ptr;

You can write ptr->datum and ptr->next to refer to the two fields in the object that ptr points to.

If a unary operator precedes an expression using ‘->’, the ‘->’ nests inside:

  -ptr->datum   is equivalent to   -(ptr->datum)

You can intermix ‘->’ and ‘.’ without parentheses, as shown here:

struct { double d; struct intlistlink l; } foo;

…foo.l.next->next->datum…

15.2 Arrays as Fields

When you declare field in a structure as an array, as here:

struct record
  {
    char *name;
    int data[4];
  };

Each struct record object holds one string (a pointer, of course) and four integers, all part of a field called data. If recptr is a pointer of type struct record *, then it points to a struct record which contains those things; you can access the second integer in that record with recptr->data[1].

If you have two objects of type struct record, each one contains an array. With this declaration,

struct record r1, r2;

r1.data holds space for 4 ints, and r2.data holds space for another 4 ints,

15.3 Dynamic Memory Allocation

To allocate an object dynamically, call the library function malloc (see The GNU C Library in The GNU C Library Reference Manual). Here is how to allocate an object of type struct intlistlink. To make this code work, include the file stdlib.h, like this:

#include <stddef.h>  /* Defines NULL. */
#include <stdlib.h>  /* Declares malloc.  */

…

struct intlistlink *
alloc_intlistlink ()
{
  struct intlistlink *p;

  p = malloc (sizeof (struct intlistlink));

  if (p == NULL)
    fatal ("Ran out of storage");

  /* Initialize the contents. */
  p->datum = 0;
  p->next = NULL;

  return p;
}

malloc returns void *, so the assignment to p will automatically convert it to type struct intlistlink *. The return value of malloc is always sufficiently aligned (see Type Alignment) that it is valid for any data type.

The test for p == NULL is necessary because malloc returns a null pointer if it cannot get any storage. We assume that the program defines the function fatal to report a fatal error to the user.

Here’s how to add one more integer to the front of such a list:

struct intlistlink *my_list = NULL;

void
add_to_mylist (int my_int)
{
  struct intlistlink *p = alloc_intlistlink ();

  p->datum = my_int;
  p->next = mylist;
  mylist = p;
}

The way to free the objects is by calling free. Here’s a function to free all the links in one of these lists:

void
free_intlist (struct intlistlink *p)
{
  while (p)
    {
      struct intlistlink *q = p;
      p = p->next;
      free (q);
    }
}

We must extract the next pointer from the object before freeing it, because free can clobber the data that was in the object. For the same reason, the program must not use the list any more after freeing its elements. To make sure it won’t, it is best to clear out the variable where the list was stored, like this:

free_intlist (mylist);

mylist = NULL;

15.4 Field Offset

To determine the offset of a given field field in a structure type type, use the macro offsetof, which is defined in the file stddef.h. It is used like this:

offsetof (type, field)

Here is an example:

struct foo
{
  int element;
  struct foo *next;
};

offsetof (struct foo, next)
/* On most machines that is 4.  It may be 8.  */

15.5 Structure Layout

The rest of this chapter covers advanced topics about structures. If you are just learning C, you can skip it.

The precise layout of a struct type is crucial when using it to overlay hardware registers, to access data structures in shared memory, or to assemble and disassemble packets for network communication. It is also important for avoiding memory waste when the program makes many objects of that type. However, the layout depends on the target platform. Each platform has conventions for structure layout, which compilers need to follow.

Here are the conventions used on most platforms.

The structure’s fields appear in the structure layout in the order they are declared. When possible, consecutive fields occupy consecutive bytes within the structure. However, if a field’s type demands more alignment than it would get that way, C gives it the alignment it requires by leaving a gap after the previous field.

Once all the fields have been laid out, it is possible to determine the structure’s alignment and size. The structure’s alignment is the maximum alignment of any of the fields in it. Then the structure’s size is rounded up to a multiple of its alignment. That may require leaving a gap at the end of the structure.

Here are some examples, where we assume that char has size and alignment 1 (always true), and int has size and alignment 4 (true on most kinds of computers):

struct foo
{
  char a, b;
  int c;
};

This structure occupies 8 bytes, with an alignment of 4. a is at offset 0, b is at offset 1, and c is at offset 4. There is a gap of 2 bytes before c.

Contrast that with this structure:

struct foo
{
  char a;
  int c;
  char b;
};

This structure has size 12 and alignment 4. a is at offset 0, c is at offset 4, and b is at offset 8. There are two gaps: three bytes before c, and three bytes at the end.

These two structures have the same contents at the C level, but one takes 8 bytes and the other takes 12 bytes due to the ordering of the fields. A reliable way to avoid this sort of wastage is to order the fields by size, biggest fields first.

15.6 Packed Structures

In GNU C you can force a structure to be laid out with no gaps by adding __attribute__((packed)) after struct (or at the end of the structure type declaration). Here’s an example:

struct __attribute__((packed)) foo
{
  char a;
  int c;
  char b;
};

Without __attribute__((packed)), this structure occupies 12 bytes (as described in the previous section), assuming 4-byte alignment for int. With __attribute__((packed)), it is only 6 bytes long—the sum of the lengths of its fields.

Use of __attribute__((packed)) often results in fields that don’t have the normal alignment for their types. Taking the address of such a field can result in an invalid pointer because of its improper alignment. Dereferencing such a pointer can cause a SIGSEGV signal on a machine that doesn’t, in general, allow unaligned pointers.

See Attributes.

15.7 Bit Fields

A structure field declaration with an integer type can specify the number of bits the field should occupy. We call that a bit field. These are useful because consecutive bit fields are packed into a larger storage unit. For instance,

unsigned char opcode: 4;

specifies that this field takes just 4 bits. Since it is unsigned, its possible values range from 0 to 15. A signed field with 4 bits, such as this,

signed char small: 4;

can hold values from -8 to 7.

You can subdivide a single byte into those two parts by writing

unsigned char opcode: 4;
signed char small: 4;

in the structure. With bit fields, these two numbers fit into a single char.

Here’s how to declare a one-bit field that can hold either 0 or 1:

unsigned char special_flag: 1;

You can also use the bool type for bit fields:

bool special_flag: 1;

Except when using bool (which is always unsigned, see Boolean Type), always specify signed or unsigned for a bit field. There is a default, if that’s not specified: the bit field is signed if plain char is signed, except that the option -funsigned-bitfields forces unsigned as the default. But it is cleaner not to depend on this default.

Bit fields are special in that you cannot take their address with ‘&’. They are not stored with the size and alignment appropriate for the specified type, so they cannot be addressed through pointers to that type.

15.8 Bit Field Packing

Programs to communicate with low-level hardware interfaces need to define bit fields laid out to match the hardware data. This section explains how to do that.

Consecutive bit fields are packed together, but each bit field must fit within a single object of its specified type. In this example,

unsigned short a : 3, b : 3, c : 3, d : 3, e : 3;

all five fields fit consecutively into one two-byte short. They need 15 bits, and one short provides 16. By contrast,

unsigned char a : 3, b : 3, c : 3, d : 3, e : 3;

needs three bytes. It fits a and b into one char, but c won’t fit in that char (they would add up to 9 bits). So c and d go into a second char, leaving a gap of two bits between b and c. Then e needs a third char. By contrast,

unsigned char a : 3, b : 3;
unsigned int c : 3;
unsigned char d : 3, e : 3;

needs only two bytes: the type unsigned int allows c to straddle bytes that are in the same word.

You can leave a gap of a specified number of bits by defining a nameless bit field. This looks like type : nbits;. It is allocated space in the structure just as a named bit field would be allocated.

You can force the following bit field to advance to the following aligned memory object with type : 0;.

Both of these constructs can syntactically share type with ordinary bit fields. This example illustrates both:

unsigned int a : 5, : 3, b : 5, : 0, c : 5, : 3, d : 5;

It puts a and b into one int, with a 3-bit gap between them. Then : 0 advances to the next int, so c and d fit into that one.

These rules for packing bit fields apply to most target platforms, including all the usual real computers. A few embedded controllers have special layout rules.

15.9 const Fields

A structure field declared const cannot be assigned to (see const). For instance, let’s define this modified version of struct intlistlink:

struct intlistlink_ro  /* “ro” for read-only.  */
  {
    const int datum;
    struct intlistlink *next;
  };

This structure can be used to prevent part of the code from modifying the datum field:

/* p has type struct intlistlink *.
   Convert it to struct intlistlink_ro *.  */
struct intlistlink_ro *q
  = (struct intlistlink_ro *) p;

q->datum = 5;     /* Error! */
p->datum = 5;     /* Valid since *p is
                     not a struct intlistlink_ro.  */

A const field can get a value in two ways: by initialization of the whole structure, and by making a pointer-to-structure point to an object in which that field already has a value.

Any const field in a structure type makes assignment impossible for structures of that type (see Structure Assignment). That is because structure assignment works by assigning the structure’s fields, one by one.

15.10 Arrays of Length Zero

GNU C allows zero-length arrays. They are useful as the last field of a structure that is really a header for a variable-length object. Here’s an example, where we construct a variable-size structure to hold a line which is this_length characters long:

struct line {
  int length;
  char contents[0];
};

struct line *thisline
  = ((struct line *)
     malloc (sizeof (struct line)
             + this_length));
thisline->length = this_length;

In ISO C90, we would have to give contents a length of 1, which means either wasting space or complicating the argument to malloc.

15.11 Flexible Array Fields

The C99 standard adopted a more complex equivalent of zero-length array fields. It’s called a flexible array, and it’s indicated by omitting the length, like this:

struct line
{
  int length;
  char contents[];
};

The flexible array has to be the last field in the structure, and there must be other fields before it.

Under the C standard, a structure with a flexible array can’t be part of another structure, and can’t be an element of an array.

GNU C allows static initialization of flexible array fields. The effect is to “make the array long enough” for the initializer.

struct f1 { int x; int y[]; } f1
  = { 1, { 2, 3, 4 } };

This defines a structure variable named f1 whose type is struct f1. In C, a variable name or function name never conflicts with a structure type tag.

Omitting the flexible array field’s size lets the initializer determine it. This is allowed only when the flexible array is defined in the outermost structure and you declare a variable of that structure type. For example:

struct foo { int x; int y[]; };
struct bar { struct foo z; };

struct foo a = { 1, { 2, 3, 4 } };        // Valid.
struct bar b = { { 1, { 2, 3, 4 } } };    // Invalid.
struct bar c = { { 1, { } } };            // Valid.
struct foo d[1] = { { 1 { 2, 3, 4 } } };  // Invalid.

15.12 Overlaying Different Structures

Be careful about using different structure types to refer to the same memory within one function, because GNU C can optimize code assuming it never does that. See Aliasing. Here’s an example of the kind of aliasing that can cause the problem:

struct a { int size; char *data; };
struct b { int size; char *data; };
struct a foo;
struct a *p = &foo;
struct b *q = (struct b *) &foo;

Here q points to the same memory that the variable foo occupies, but they have two different types. The two types struct a and struct b are defined alike, but they are not the same type. Interspersing references using the two types, like this,

p->size = 0;
q->size = 1;
x = p->size;

allows GNU C to assume that p->size is still zero when it is copied into x. The GNU C compiler “knows” that q points to a struct b and this is not supposed to overlap with a struct a. Other compilers might also do this optimization.

The ISO C standard considers such code erroneous, precisely so that this optimization will not be incorrect.

15.13 Structure Assignment

Assignment operating on a structure type copies the structure. The left and right operands must have the same type. Here is an example:

#include <stddef.h>  /* Defines NULL. */
#include <stdlib.h>  /* Declares malloc.  */
…

struct point { double x, y; };

struct point *
copy_point (struct point point)
{
  struct point *p
    = (struct point *) malloc (sizeof (struct point));
  if (p == NULL)
    fatal ("Out of memory");
  *p = point;
  return p;
}

Notionally, assignment on a structure type works by copying each of the fields. Thus, if any of the fields has the const qualifier, that structure type does not allow assignment:

struct point { const double x, y; };

struct point a, b;

a = b;            /* Error! */

See Assignment Expressions.

When a structure type has a field which is an array, as here,

struct record
  {
    char *name;
    int data[4];
  };

struct record r1, r2;

structure assigment such as r1 = r2 copies array fields’ contents just as it copies all the other fields.

This is the only way in C that you can operate on the whole contents of a array with one operation: when the array is contained in a struct. You can’t copy the contents of the data field as an array, because

r1.data = r2.data;

would convert the array objects (as always) to pointers to the zeroth elements of the arrays (of type struct record *), and the assignment would be invalid because the left operand is not an lvalue.

15.14 Unions

A union type defines alternative ways of looking at the same piece of memory. Each alternative view is defined with a data type, and identified by a name. A union definition looks like this:

union name
{
  alternative declarations…
};

Each alternative declaration looks like a structure field declaration, except that it can’t be a bit field. For instance,

union number
{
  long int integer;
  double float;
}

lets you store either an integer (type long int) or a floating point number (type double) in the same place in memory. The length and alignment of the union type are the maximum of all the alternatives—they do not have to be the same. In this union example, double probably takes more space than long int, but that doesn’t cause a problem in programs that use the union in the normal way.

The members don’t have to be different in data type. Sometimes each member pertains to a way the data will be used. For instance,

union datum
{
  double latitude;
  double longitude;
  double height;
  double weight;
  int continent;
}

This union holds one of several kinds of data; most kinds are floating points, but the value can also be a code for a continent which is an integer. You could use one member of type double to access all the values which have that type, but the different member names will make the program clearer.

The alignment of a union type is the maximum of the alignments of the alternatives. The size of the union type is the maximum of the sizes of the alternatives, rounded up to a multiple of the alignment (because every type’s size must be a multiple of its alignment).

All the union alternatives start at the address of the union itself. If an alternative is shorter than the union as a whole, it occupies the first part of the union’s storage, leaving the last part unused for that alternative.

Warning: if the code stores data using one union alternative and accesses it with another, the results depend on the kind of computer in use. Only wizards should try to do this. However, when you need to do this, a union is a clean way to do it.

Assignment works on any union type by copying the entire value.

15.15 Packing With Unions

Sometimes we design a union with the intention of packing various kinds of objects into a certain amount of memory space. For example.

union bytes8
{
  long long big_int_elt;
  double double_elt;
  struct { int first, second; } two_ints;
  struct { void *first, *second; } two_ptrs;
};

union bytes8 *p;

This union makes it possible to look at 8 bytes of data that p points to as a single 8-byte integer (p->big_int_elt), as a single floating-point number (p->double_elt), as a pair of integers (p->two_ints.first and p->two_ints.second), or as a pair of pointers (p->two_ptrs.first and p->two_ptrs.second).

To pack storage with such a union makes assumptions about the sizes of all the types involved. This particular union was written expecting a pointer to have the same size as int. On a machine where one pointer takes 8 bytes, the code using this union probably won’t work as expected. The union, as such, will function correctly—if you store two values through two_ints and extract them through two_ints, you will get the same integers back—but the part of the program that expects the union to be 8 bytes long could malfunction, or at least use too much space.

The above example shows one case where a struct type with no tag can be useful. Another way to get effectively the same result is with arrays as members of the union:

union eight_bytes
{
  long long big_int_elt;
  double double_elt;
  int two_ints[2];
  void *two_ptrs[2];
};

15.16 Cast to a Union Type

In GNU C, you can explicitly cast any of the alternative types to the union type; for instance,

(union eight_bytes) (long long) 5

makes a value of type union eight_bytes which gets its contents through the alternative named big_int_elt.

The value being cast must exactly match the type of the alternative, so this is not valid:

(union eight_bytes) 5  /* Error!  5 is int. */

A cast to union type looks like any other cast, except that the type specified is a union type. You can specify the type either with union tag or with a typedef name (see Defining Typedef Names).

Using the cast as the right-hand side of an assignment to a variable of union type is equivalent to storing in an alternative of the union:

union foo u;

u = (union foo) x   means   u.i = x

u = (union foo) y   means   u.d = y

You can also use the union cast as a function argument:

void hack (union foo);
…
hack ((union foo) x);

15.17 Structure Constructors

You can construct a structure value by writing its type in parentheses, followed by an initializer that would be valid in a declaration for that type. For instance, given this declaration,

struct foo {int a; char b[2];} structure;

you can create a struct foo value as follows:

((struct foo) {x + y, 'a', 0})

This specifies x + y for field a, the character ‘a’ for field b’s element 0, and the null character for field b’s element 1.

The parentheses around that constructor are not necessary, but we recommend writing them to make the nesting of the containing expression clearer.

You can also show the nesting of the two by writing it like this:

((struct foo) {x + y, {'a', 0} })

Each of those is equivalent to writing the following statement expression (see Statement Exprs):

({
  struct foo temp = {x + y, 'a', 0};
  temp;
})

You can also use field labels in the structure constructor to indicate which fields you’re specifying values for, instead of using the order of the fields to specify that:

(struct foo) {.a = x + y, .b = {'a', 0}}

You can also create a union value this way, but it is not especially useful since that is equivalent to doing a cast:

  ((union whosis) {value})
is equivalent to
  ((union whosis) (value))

15.18 Unnamed Types as Fields

A structure or a union can contain, as fields, unnamed structures and unions. Here’s an example:

struct
{
  int a;
  union
  {
    int b;
    float c;
  };
  int d;
} foo;

You can access the fields of the unnamed union within foo as if they were individual fields at the same level as the union definition:

foo.a = 42;
foo.b = 47;
foo.c = 5.25; // Overwrites the value in foo.b.
foo.d = 314;

Avoid using field names that could cause ambiguity. For example, with this definition:

struct
{
  int a;
  struct
  {
    int a;
    float b;
  };
} foo;

it is impossible to tell what foo.a refers to. GNU C reports an error when a definition is ambiguous in this way.

15.19 Incomplete Types

A type that has not been fully defined is called an incomplete type. Structure and union types are incomplete when the code makes a forward reference, such as struct foo, before defining the type. An array type is incomplete when its length is unspecified.

You can’t use an incomplete type to declare a variable or field, or use it for a function parameter or return type. The operators sizeof and _Alignof give errors when used on an incomplete type.

However, you can define a pointer to an incomplete type, and declare a variable or field with such a pointer type. In general, you can do everything with such pointers except dereference them. For example:

extern void bar (struct mysterious_value *);

void
foo (struct mysterious_value *arg)
{
  bar (arg);
}

…

{
  struct mysterious_value *p, **q;

  p = *q;
  foo (p);
}

These examples are valid because the code doesn’t try to understand what p points to; it just passes the pointer around. (Presumably bar is defined in some other file that really does have a definition for struct mysterious_value.) However, dereferencing the pointer would get an error; that requires a definition for the structure type.

15.20 Intertwined Incomplete Types

When several structure types contain pointers to each other, you can define the types in any order because pointers to types that come later are incomplete types. Thus, Here is an example.

/* An employee record points to a group.  */
struct employee
{
  char *name;
  …
  struct group *group;  /* incomplete type.  */
  …
};

/* An employee list points to employees.  */
struct employee_list
{
  struct employee *this_one;
  struct employee_list *next;  /* incomplete type.  */
  …
};

/* A group points to one employee_list.  */
struct group
{
  char *name;
  …
  struct employee_list *employees;
  …
};

15.21 Type Tags

The name that follows struct (see Structures), union (see Unions, or enum (see Enumeration Types) is called a type tag. In C, a type tag never conflicts with a variable name or function name; the type tags have a separate name space. Thus, there is no name conflict in this code:

struct pair { int a, b; };
int pair = 1;

nor in this one:

struct pair { int a, b; } pair;

where pair is both a structure type tag and a variable name.

However, struct, union, and enum share the same name space of tags, so this is a conflict:

struct pair { int a, b; };
enum pair { c, d };

and so is this:

struct pair { int a, b; };
struct pair { int c, d; };

When the code defines a type tag inside a block, the tag’s scope is limited to that block (as for local variables). Two definitions for one type tag do not conflict if they are in different scopes; rather, each is valid in its scope. For example,

struct pair { int a, b; };

void
pair_up_doubles (int len, double array[])
{
  struct pair { double a, b; };
  …
}

has two definitions for struct pair which do not conflict. The one inside the function applies only within the definition of pair_up_doubles. Within its scope, that definition shadows the outer definition.

If struct pair appears inside the function body, before the inner definition, it refers to the outer definition—the only one that has been seen at that point. Thus, in this code,

struct pair { int a, b; };

void
pair_up_doubles (int len, double array[])
{
  struct two_pairs { struct pair *p, *q; };
  struct pair { double a, b; };
  …
}

the structure two_pairs has pointers to the outer definition of struct pair, which is probably not desirable.

To prevent that, you can write struct pair; inside the function body as a variable declaration with no variables. This is a forward declaration of the type tag pair: it makes the type tag local to the current block, with the details of the type to come later. Here’s an example:

void
pair_up_doubles (int len, double array[])
{
  /* Forward declaration for pair.  */
  struct pair;
  struct two_pairs { struct pair *p, *q; };
  /* Give the details.  */
  struct pair { double a, b; };
  …
}

However, the cleanest practice is to avoid shadowing type tags.

16 Arrays

An array is a data object that holds a series of elements, all of the same data type. Each element is identified by its numeric index within the array.

We presented arrays of numbers in the sample programs early in this manual (see Array Example). However, arrays can have elements of any data type, including pointers, structures, unions, and other arrays.

If you know another programming language, you may suppose that you know all about arrays, but C arrays have special quirks, so in this chapter we collect all the information about arrays in C.

The elements of a C array are allocated consecutively in memory, with no gaps between them. Each element is aligned as required for its data type (see Type Alignment).

16.1 Accessing Array Elements

If the variable a is an array, the nth element of a is a[n]. You can use that expression to access an element’s value or to assign to it:

x = a[5];
a[6] = 1;

Since the variable a is an lvalue, a[n] is also an lvalue.

The lowest valid index in an array is 0, not 1, and the highest valid index is one less than the number of elements.

The C language does not check whether array indices are in bounds, so if the code uses an out-of-range index, it will access memory outside the array.

Warning: Using only valid index values in C is the programmer’s responsibility.

Array indexing in C is not a primitive operation: it is defined in terms of pointer arithmetic and dereferencing. Now that we know what a[i] does, we can ask how a[i] does its job.

In C, x[y] is an abbreviation for *(x+y). Thus, a[i] really means *(a+i). See Pointers and Arrays.

When an expression with array type (such as a) appears as part of a larger C expression, it is converted automatically to a pointer to element zero of that array. For instance, a in an expression is equivalent to &a[0]. Thus, *(a+i) is computed as *(&a[0]+i).

Now we can analyze how that expression gives us the desired element of the array. It makes a pointer to element 0 of a, advances it by the value of i, and dereferences that pointer.

Another equivalent way to write the expression is (&a[0])[i].

16.2 Declaring an Array

To make an array declaration, write [length] after the name being declared. This construct is valid in the declaration of a variable, a function parameter, a function value type (the value can’t be an array, but it can be a pointer to one), a structure field, or a union alternative.

The surrounding declaration specifies the element type of the array; that can be any type of data, but not void or a function type. For instance,

double a[5];

declares a as an array of 5 doubles.

struct foo bstruct[length];

declares bstruct as an array of length objects of type struct foo. A variable array size like this is allowed when the array is not file-scope.

Other declaration constructs can nest within the array declaration construct. For instance:

struct foo *b[length];

declares b as an array of length pointers to struct foo. This shows that the length need not be a constant (see Arrays of Variable Length).

double (*c)[5];

declares c as a pointer to an array of 5 doubles, and

char *(*f (int))[5];

declares f as a function taking an int argument and returning a pointer to an array of 5 strings (pointers to chars).

double aa[5][10];

declares aa as an array of 5 elements, each of which is an array of 10 doubles. This shows how to declare a multidimensional array in C (see Multidimensional Arrays).

All these declarations specify the array’s length, which is needed in these cases in order to allocate storage for the array.

16.3 Strings

A string in C is a sequence of elements of type char, terminated with the null character, the character with code zero.

Programs often need to use strings with specific, fixed contents. To write one in a C program, use a string constant such as "Take me to your leader!". The data type of a string constant is char *. For the full syntactic details of writing string constants, String Constants.

To declare a place to store a non-constant string, declare an array of char. Keep in mind that it must include one extra char for the terminating null. For instance,

char text[] = { 'H', 'e', 'l', 'l', 'o', 0 };

declares an array named ‘text’ with six elements—five letters and the terminating null character. An equivalent way to get the same result is this,

char text[] = "Hello";

which copies the elements of the string constant, including its terminating null character.

char message[200];

declares an array long enough to hold a string of 199 ASCII characters plus the terminating null character.

When you store a string into message be sure to check or prove that the length does not exceed its size. For example,

void
set_message (char *text)
{
  int i;
  for (i = 0; i < sizeof (message); i++)
    {
      message[i] = text[i];
      if (text[i] == 0)
        return;
    }
  fatal_error ("Message is too long for `message'\n");
}

It’s easy to do this with the standard library function strncpy, which fills out the whole destination array (up to a specified length) with null characters. Thus, if the last character of the destination is not null, the string did not fit. Many system libraries, including the GNU C library, hand-optimize strncpy to run faster than an explicit for-loop.

Here’s what the code looks like:

void
set_message (char *text)
{
  strncpy (message, text, sizeof (message));
  if (message[sizeof (message) - 1] != 0)
    fatal_error ("Message is too long for `message');
}

See The GNU C Library in The GNU C Library Reference Manual, for more information about the standard library functions for operating on strings.

You can avoid putting a fixed length limit on strings you construct or operate on by allocating the space for them dynamically. See Dynamic Memory Allocation.

16.4 Array Type Designators

Every C type has a type designator, which you make by deleting the variable name and the semicolon from a declaration (see Type Designators). The designators for array types follow this rule, but they may appear surprising.

type   int a[5];           designator   int [5]
type   double a[5][3];     designator   double [5][3]
type   struct foo *a[5];   designator   struct foo *[5]

16.5 Incomplete Array Types

An array is equivalent, for most purposes, to a pointer to its zeroth element. When that is true, the length of the array is irrelevant. The length needs to be known only for allocating space for the array, or for sizeof and typeof (see Auto Type). Thus, in some contexts C allows

• An extern declaration says how to refer to a variable allocated elsewhere. It does not need to allocate space for the variable, so if it is an array, you can omit the length. For example,

  extern int foo[];
  

• When declaring a function parameter as an array, the argument value passed to the function is really a pointer to the array’s zeroth element. This value does not say how long the array really is, there is no need to declare it. For example,

  int
  func (int foo[])
  

These declarations are examples of incomplete array types, types that are not fully specified. The incompleteness makes no difference for accessing elements of the array, but it matters for some other things. For instance, sizeof is not allowed on an incomplete type.

With multidimensional arrays, only the first dimension can be omitted. For example, suppose we want to represent the positions of pieces on a chessboard which has the usual 8 files (columns), but more (or fewer) ranks (rows) than the usual 8. This declaration could hold a pointer to a two-dimensional array that can hold that data. Each element of the array holds one row.

struct chesspiece *funnyboard[][8];

Since it is just a pointer to the start of an array, its type can be incomplete, but it must state how big each array element is—the number of elements in each row.

16.6 Limitations of C Arrays

Arrays have quirks in C because they are not “first-class objects”: there is no way in C to operate on an array as a unit.

The other composite objects in C, structures and unions, are first-class objects: a C program can copy a structure or union value in an assignment, or pass one as an argument to a function, or make a function return one. You can’t do those things with an array in C. That is because a value you can operate on never has an array type.

An expression in C can have an array type, but that doesn’t produce the array as a value. Instead it is converted automatically to a pointer to the array’s element at index zero. The code can operate on the pointer, and through that on individual elements of the array, but it can’t get and operate on the array as a unit.

There are three exceptions to this conversion rule, but none of them offers a way to operate on the array as a whole.

First, ‘&’ applied to an expression with array type gives you the address of the array, as an array type. However, you can’t operate on the whole array that way—if you apply ‘*’ to get the array back, that expression converts, as usual, to a pointer to its zeroth element.

Second, the operators sizeof, _Alignof, and typeof do not convert the array to a pointer; they leave it as an array. But they don’t operate on the array’s data—they only give information about its type.

Third, a string constant used as an initializer for an array is not converted to a pointer—rather, the declaration copies the contents of that string in that one special case.

You can copy the contents of an array, just not with an assignment operator. You can do it by calling the library function memcpy or memmove (see The GNU C Library in The GNU C Library Reference Manual). Also, when a structure contains just an array, you can copy that structure.

An array itself is an lvalue if it is a declared variable, or part of a structure or union that is an lvalue. When you construct an array from elements (see Constructing Array Values), that array is not an lvalue.