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 19…
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.
When compiling for a “real computer”, one that is a reasonable platform for running the GNU/Linux system, the type int is always 32 bits in size. This manual assumes you are compiling for the computer where you are running the compiler, which implies int has that size. GNU C can also compile code for some microprocessors on which type int has fewer bits, but this manual does not try to cover the complications of those peculiar platforms.
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.
Table of Contents
Short Table of Contents
- 1 The First Example
- 2 A Complete Program
- 3 Storage and Data
- 4 Beyond Integers
- 5 Lexical Syntax
- 6 Arithmetic
- 7 Assignment Expressions
- 8 Execution Control Expressions
- 9 Binary Operator Grammar
- 10 Order of Execution
- 11 Primitive Data Types
- 12 Constants
- 13 Type Size
- 14 Pointers
- 15 Structures
- 16 Arrays
- 17 Enumeration Types
- 18 Defining Typedef Names
- 19 Statements
- 20 Variables
- 21 Type Qualifiers
- 22 Functions
- 23 Compatible Types
- 24 Type Conversions
- 25 Scope
- 26 Preprocessing
- 27 Integers in Depth
- 28 Floating Point in Depth
- 29 Compilation
- 30 Directing Compilation
- Appendix A Type Alignment
- Appendix B Aliasing
- Appendix C Digraphs
- Appendix D Attributes in Declarations
- Appendix E Signals
- Appendix F GNU Free Documentation License
- Appendix G GNU General Public License
- Index of Symbols and Keywords
- Concept Index
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 variableninside 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 functionfib, passing as its argument the valuen - 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
returnstatement and theif…elsestatement. See Statements. - Recursion. The function
fibcalls 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.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. In GNU C, type int holds 32 bits (see Integer Data Types), so 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, for more details about this situation.
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 in that case 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; for instance, the expression statement x; would examine the value of x and ignore it. That is not useful.1
Increment operator
The increment operator is ‘++’. ++i is an expression that is short for i = i + 1. See Increment and Decrement Operators.
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 < nand exiting the loop if that’s false. - Executing body.
- Advancing the loop (executing
++i, which incrementsi).
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.
- Complete Program Example
- Complete Program Explanation
- Complete Program, Line by Line
- Compiling the Example Program
2.1 Complete Program Example
Here is the complete program that uses the simple, recursive version of the fib function (see Example: 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 Returning 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.
- An Example with Non-Integer Numbers
- An Example with Arrays
- Calling the Array Example
- Variations for Array Example
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 compute the average of. */
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