An introduction to C

Copyright (c) 1998-2004 by Tom Torfs
tomtorfsimecbe (preferred), tomtorfschellobe

This document, in HTML, PDF and text format, may be distributed freely. Modifications made by anyone but the author must be clearly marked as such and a reference must be provided as to where the reader can obtain the original, unmodified version. This copyright information may not be removed or modified. It will apply only to the original text, not to any text added by others.

The author cannot be held responsible for any damage caused directly or indirectly by the use of information in this document.

Any suggestions for additions, improvements and/or error corrections are welcome at any of the addresses mentioned above.

All the source code in this document should be distributed together with it as plain text files. If you don't have them, you can obtain them, and the latest version of this document, at:

http://www.geocities.com/tom_torfs/c.html

0. Contents

1. Overview and rationale

2. Hello, world!
   2.1. The Hello, world! program
   2.2. Comments
   2.3. #include
   2.4. Functions and types
   2.5. return

3. Using variables
   3.1. The 42 program
   3.2. Defining variables
   3.3. printf()

4. Doing calculations
   4.1. The calc program
   4.2. Operators and typecasts
   4.3. Using the functions from math.h

5. Enums and typedefs
   5.1. The colours program
   5.2. Defining and using enums and typedefs

6. Structs, unions and bit-fields
   6.1. The cars program
   6.2. Using structs, unions and bit-fields

7. Conditionals (if/else)
   7.1. The yesno program
   7.2. Obtaining random numbers
   7.3. Using if/else
   7.4. Using the ?: operator

8. switch/case/default
   8.1. The animals program
   8.2. Using the switch() statement

9. Loops (do,while,for)
   9.1. The loops program
   9.2. Using loops
   9.3. Using break,continue,goto

10. Arrays, strings and pointers
   10.1. The strings program
   10.2. Arrays and strings
   10.3. The pointers program
   10.4. Addresses and pointers
   10.5. Example: using command line arguments

11. Using files
   11.1. The fileio program
   11.2. Using disk files
   11.3. The interact program
   11.4. Using the standard I/O streams

12. Dynamic memory allocation
   12.1. The persons program
   12.2. Dynamically allocating memory

13. Preprocessor macros/conditionals
   13.1. The preproc program
   13.2. Using preprocessor macros/conditionals
   13.3. Using the assert() macro

14. Variable argument functions
   14.1. The vararg program
   14.2. Using variable argument functions
   14.3. Example: a printf() encapsulation

15. Modular approach
   15.1. The module program
   15.2. Using different modules

16. Overview of the standard library
   16.1. Introduction to the standard library
   16.2. assert.h (diagnostics)
   16.3. ctype.h (character handling)
   16.4. errno.h (error handling)
   16.5. float.h (floating-point limits)
   16.6. limits.h (implementation limits)
   16.7. locale.h (localization)
   16.8. math.h (mathematics)
   16.9. setjmp.h (non-local jumps)
   16.10. signal.h (signal handling)
   16.11. stdarg.h (variable arguments)
   16.12. stddef.h (standard type/macro definitions)
   16.13. stdio.h (input/output)
   16.14. stdlib.h (general utilities)
   16.15. string.h (string handling)
   16.16. time.h (date and time)

17. Epilogue
   17.1. Credits
   17.2. Other interesting C-related online material

This document is intended to give people who are interested in learning C, whether they already know another programming language or not, a quick introduction to the language. It does not pretend to be complete, but it should get you familiar with most concepts of the C language. It is not intended to replace a good introductory book on the subject; on the contrary, it is probably best used together with such a book; if you haven't programmed before some of the explanations in this introduction may be a bit short and getting more detailed information from a book would often be useful.

This introduction discusses the standard C language as defined by the International Standards Organization [*], also commonly referred to as "ANSI C" (the American National Standards Institute had standardized the language before ISO). It does not discuss platform/compiler specific extensions such as accessing a screen in either text or graphics mode, interacting with external devices, direct access to memory, using operating system features etc.

[*] ANSI/ISO 9899-1990 aka C89/C90; normative addenda are not discussed here; new C99 features may be referred to occasionally; the implementation is assumed to be hosted

Rationale

It has been - rightfully - reported that the material in this tutorial may not be very easy reading for a complete beginner to the C language, mainly because I try to be as complete as possible even in early stages of this tutorial.
This has two reasons: first, this tutorial can also be useful as reference material, e.g. to look up what printf() specifier can be used for what purpose, etc.
The second, more fundamental reason, is that the principle objective of this tutorial was to prefer accuracy over simplicity. In other words, I feel there are already enough tutorials and introductory books that don't adhere to the standard in several cases to keep things simple. This has the consequence that some people who learned C from such a tutorial/book will have a hard time adjusting their programming habits to write conforming code whenever possible. Since this tutorial is partly intended as a "cure" for those people, it requires some degree of accuracy which also means that it may not read very fluently if you're completely new to C. This only confirms the above statement that this tutorial is not meant to be used on its own, but rather as a complement to a good introductory book.

When reading this tutorial, it is OK to skip certain descriptions and listings which you feel are not required yet. Examples may include the complete list of printf() specifiers, standard types, etc.

/* prog2-1.c: Hello, world! */

#include <stdio.h>

int main(void)
{
   puts("Hello, world!");
   return 0;
}

[*] see your compiler documentation / online help for instructions

Also, keep in mind that you are free to choose your own formatting style. E.g. the above could have been written as: (the reasons it hasn't should be obvious)

/* prog2-1.c: Hello, world! */
#include <stdio.h>
int main(void) {puts("Hello, world!"); return 0;}

/* prog1.c: Hello, world! */

/* this is a /* comment */ inside a comment, which is wrong! */

You may also encounter comments after //. These are C++ comments and while they will be allowed in the next revision of the C standard, you shouldn't use them yet. They are more limited than the flexible /* */ comments anyway.

2.3. #include

#include <stdio.h>

#include <header>

[*] in some cases you may get away with not including the right standard header, but in other cases it may cause nasty things to happen (ranging from a simply malfunctioning program to a core dump or even a system crash: this is called undefined behaviour, in other words anything might happen); basically you should always include the right headers.

The following standard headers are available: (see 16. Overview of the standard library for a detailed discussion of them)

Commonly used headers:

stdio.h    input/output
stdlib.h   general utilities
string.h   string handling
time.h     date and time
math.h     mathematics
ctype.h    character handling

stddef.h   standard type/macro definitions
limits.h   implementation limits
float.h    floating-point limits
errno.h    error handling
assert.h   diagnostics

stdarg.h   variable arguments
setjmp.h   non-local jumps
signal.h   signal handling
locale.h   localization

The second form is:

#include "file"

Now onto the next line: (the { and } braces belong to this line as well)

int main(void)
{
}

type name(parameters)
{
   /* the function code goes here */
}

Integer types: (non-fractional numbers)

signed char    minimum range: -127..+127
unsigned char  minimum range: 0..255
signed short   minimum range: -32767..+32767
unsigned short minimum range: 0..65535
signed int     minimum range: -32767..+32767
unsigned int   minimum range: 0..65535
signed long    minimum range: -2147483647..+2147483647
unsigned long  minimum range: 0..4294967295

Floating point types: (fractional numbers)

float       minimum range: +/- 1E-37..1E+37  minimum precision: 6 digits
double      minimum range: +/- 1E-37..1E+37  minimum precision: 10 digits
long double minimum range: +/- 1E-37..1E+37  minimum precision: 10 digits

Special-purpose types: (don't worry too much about these yet)
Commonly used ones:

size_t        unsigned type used for storing the sizes of objects in bytes
time_t        used to store results of the time() function
clock_t       used to store results of the clock() function
FILE          used for accessing a stream (usually a file or device)

ptrdiff_t     signed type of the difference between 2 pointers
div_t         used to store results of the div() function
ldiv_t        used to store results of ldiv() function
fpos_t        used to hold file position information

va_list      used in variable argument handling
wchar_t      wide character type (used for extended character sets)
sig_atomic_t used in signal handlers
jmp_buf      used for non-local jumps

The function name follows the rules for all names (formally: identifiers): it must consist entirely of letters (uppercase and lowercase are different! [*]), digits and underscores (_), but may not begin with a digit.

[*] during linking, case differences in external names might be ignored; so it's often not a good idea to use 2 variable/function names that only differ in their case (this would also reduce clarity)

The parameter list may be void in which case the function won't take any parameters. Otherwise it should be a list of the following form:

type1 name1, type2 name2, type3 name3     etc.

double myfunction(int foo, long bar)
{
}

The parameters' values will be filled in by the callers. The above function might be called as follows:

myfunction(7,10000);

somevariable = myfunction(7,10000);

myfunction();

myfunction;             /* wrong! */

Here's an example of a situation where using a function provides advantages, apart from the readability advantage that using a function instead of lumping all code together always provides.

   do_something();
   check_error_condition();

   do_something_else();
   check_error_condition();

   etc.

main() is a very special function: it is the function that is called at the beginning of our program's execution. Because it's so special we are not free to choose its return value or parameters. Only two forms are allowed:

int main(void)
{
}

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

In some source code you may find other definitions of main(), such as returning void or taking 3 parameters etc. These may work on certain compilers but they are not standard so you should avoid them.

The actual function code (called the function body) goes inside the { and } braces. In this case the first line of the function body is:

   puts("Hello, world!");

int puts(const char *s);

The return value of the puts() function is an int, and its meaning is rather straightforward: it returns EOF (which is a negative value defined in stdio.h) if an error occurs, or a nonnegative value if it's successful. We ignore this return value in our small program, but in 'real' code it's often a good idea to check these return values, and if an error occurs deal with it properly.

But the parameter, that's something else. To understand it, we must first know what puts() does: it writes a string (= text) to the standard output device (usually the screen, but it may be another device or a file) and then moves on to the next line. So obviously this 'const char *s' parameter must accept the string we want to print.

If you look back to the types listed above, you will notice that there is no string type among them. That is because C doesn't have a special string type. A string in C is just a series of chars, and the end of the string is indicated by a char with value 0. Such a series is called an array. But instead of passing the array to the puts() function, a pointer to it is passed. The pointer is indicated by the * and the const means that the puts() function will not modify the string we pass it. If this seems like Chinese for now (provided you don't live in China, of course), don't worry: this will be more thoroughly explained later in this document (see 10. Arrays, strings and pointers). All you need to know for now is that the above declaration means that puts() will take a string as parameter, and that that string will not be modified.

In our program, we pass puts() the parameter "Hello, world!". The double quotes indicate that this is a string literal (which basically comes down to a string that may not be modified [*]). Since puts() accepts a string that it will not modify, this works out perfectly. If we would have attempted to call puts() with e.g. a number as parameter, the compiler would most likely have complained.

[*] Attempting to modify a string literal will cause undefined behaviour. Some compilers/operating systems may allow string literals to be modified, but this will fail miserably on others (or even the same ones with different compiler options set), so should definitely never be done.

You must be careful to use double quotes ("), which indicate a string literal, because single quotes (') indicate a character literal (e.g. 'A') and these are not interchangeable. [*]

[*] Another peculiarity is that character literals in C are not of type char, but of type int. This is different from C++.

String and character literals may contain special escape codes to perform some implementation-defined actions:

\a alert (causes an audible or visual alert when printed)
\b backspace
\f formfeed (may clear the screen on some systems, don't rely on this)
\n newline (goes to the beginning of the next line; will be automatically
            translated to/from \r\n or another (if any) end-of-line
            sequence on systems where this is necessary)
\r carriage return (goes to the beginning of the current line)
\t horizontal tab
\v vertical tab
\\ backslash (be careful when using backslashes in literals!)
\' single quote (useful inside character literals)
\" double quote (useful inside string literals)
\? question mark (useful to avoid unwanted trigraph translation when two
                  question marks are followed by certain characters)
\<octal digits> character value in octal
\x<hex digits>  character value in hexadecimal

The next, and final, line of our small program is:

   return 0;

As we mentioned above, main() always returns an int value. In the case of main(), this value indicates to the operating system whether the program ended successfully or because of an error. Success is indicated by returning the value 0. Also, the constants EXIT_SUCCESS and EXIT_FAILURE may be used; they are defined in the standard header stdlib.h. [*]

[*] Usually, other return values than 0, EXIT_SUCCESS or EXIT_FAILURE are allowed as well for the return value of main(), but this is not standard so you should avoid it unless you have a specific reason to do so, provided you're aware this may restrict the range of operating systems your program will work on.

Note that the above is specific to the main() function; other functions that you write are of course not subject to these restrictions, and may take any parameters and return any value they like. [*]

[*] Some other functions, like the compare function for qsort() or the function passed to atexit() have to have a certain form as well, but those few exceptions are of a more advanced nature.

/* prog3-1.c: 42 */

#include <stdio.h>

int main(void)
{
   int answer = 42;

   printf("And the answer is: %d\n", answer);
   return 0;
}

And the answer is: 42

   int answer = 42;

   int answer;        /* define uninitialized variable 'answer' */

   /* and after all variable definitions: */

   answer = 42;       /* assigns value 42 to variable 'answer' */

Variables that are defined at the beginning of a block default to the 'auto' status. This means that they only exist during the execution of the block (in our case the function). When the function execution begins, the variables will be created but their contents will be undefined (unless they're explicitly initialized like in our example). When the function returns, the variables will be destroyed. The definition could also have been written as:

   auto int answer = 42;

Since the definition with or without the auto keyword is completely equivalent, the auto keyword is obviously rather redundant.

However, sometimes this is not what you want. Suppose you want a function to keep count of how many times it is called. If the variable would be destroyed every time the function returns, this would not be possible. Therefore it is possible to give the variable what is called static duration, which means it will stay intact during the whole execution of the program. For example:

   static int answer = 42;

Sometimes it is not sufficient that the variable be accessible from one function only (and it might not be convenient to pass the value via a parameter to all other functions that need it), but you need access to the variable from all the functions in the entire source file [*] (but not from other source files).

[*] The term the standard uses is "translation unit". On most implementations such a translation unit is simply a text file containing source code, often marked with a ".c" extension or something similar. Therefore in the rest of this document the term "source file" will be used where "translation unit" is meant.

This can also done with the static keyword (which may be a bit confusing), but by putting the definition outside all functions. For example:

#include <stdio.h>

static int answer = 42; /* will be accessible from entire source file */

int main(void)
{
   printf("And the answer is: %d\n", answer);
   return 0;
}

And there are also cases where a variable needs to be accessible from the entire program, which may consist of several source files (see 15. Modular approach). This is called a global variable and should be avoided when it is not required. This is also done by putting the definition outside all functions, but without using the static keyword:

#include <stdio.h>

int answer = 42; /* will be accessible from entire program! */

int main(void)
{
   printf("And the answer is: %d\n", answer);
   return 0;
}

There is also the extern keyword, which is used for accessing global variables in other modules. This is explained in 15. Modular approach).

There are also a few qualifiers that you can add to variable definitions. The most important of them is const. A variable that is defined as const may not be modified (it will take up space, however, unlike some of the constants in e.g. Pascal; see 13. Preprocessor macros/conditionals if you need an equivalent for those). For example:

#include <stdio.h>

int main(void)
{
   const int value = 42; /* constant, initialized integer variable */

   value = 100;    /* wrong! - will cause compiler error */

   return 0;
}

Then there are two more modifiers that are less commonly used:

The volatile modifier requires the compiler to actually access the variable everytime it is read; i.o.w. it may not optimize the variable by putting it in a register or so. This is mainly used for multithreading and interrupt processing purposes etc., things you needn't worry about yet.

The register modifier requests the compiler to optimize the variable into a register. This is only possible with auto variables and in many cases the compiler can better select the variables to optimize into registers itself, so this keyword is obsolescent. The only direct consequence of making a variable register is that its address cannot be taken (see 10.4. Addresses and pointers).

3.3. printf()

   printf("And the answer is: %d\n", answer);

1) While puts() automatically adds a newline (\n) to the text, this must be done explicitly when using printf() [*]

[*] If the newline is omitted, the output may not show up. If you really want no newline, you must add fflush(stdout); afterwards. (see 11.4. Using the standard I/O streams)

2) While puts() can only print a fixed string, printf() can also be used to print variables etc. To be able to do that, printf() accepts a variable number of parameters (later we'll discuss how to write such functions yourself, see 14. Variable argument functions). The first parameter is the format string. In this string % signs have a special meaning (so if you need a % sign to be printed using printf() you must double it, i.e. use %%): they are placeholders for variable values. These variables are passed as parameters after the format string. For every variable passed, there must be a corresponding format specifier (% placeholder) in the format string, of the right type and in the right order. These are the possible format specifiers:

%d   signed int variable, decimal representation (equivalent to %i)
%u   unsigned int variable, decimal representation
%x   unsigned int variable, lowercase hexadecimal representation
%X   unsigned int variable, uppercase hexadecimal representation
%o   unsigned int variable, octal representation
     (there are no format specifiers for binary representation)
%f   float/double, normal notation
%e   float/double, exponential notation (%E uses E instead of e)
%g   float/double, notation %f or %e chosen depending on value (%E if %G)
%c   character (passed as int), text representation
%s   string (see 10. Arrays, strings and pointers)
%p   pointer (see 10. Arrays, strings and pointers)
%n   number of characters written upto now will be written to int
     that the corresponding argument points to

h     for d,i,o,u,x,X: short int instead of int
      (the short int will be promoted to int when passed anyway)
      for n: store result in short int instead of int
l     for d,i,o,u,x,X: long int instead of int
      for n: store result in long int instead of int
      Do NOT use for e,E,f,F,g,G for e.g. printing doubles.
L     for e,E,f,F,g,G: long double instead of float/double

-     left alignment, pad on the right with spaces (default=right alignment)
+     print plus sign if positive (default=only print minus sign if negative)
      (for signed numbers only)
space print space if positive (default=only print minus sign if negative)
      (for signed numbers only)
0     pad with zeros instead of with spaces (for numbers only)
#     "alternate form": - o: 0 will be prepended to a non-zero result
                        - x/X: prepends 0x/0X to result
                        - f/F,e/E,g/G: decimal point even if no decimals
                        - g/G: trailing zeros are not removed
<nonzero decimal value> specify field width to which result will be padded
      (this can be used together with the 0 flag)
*     field width will be passed as int parameter before the actual argument
.<nonzero decimal value> specify precision (default for f/F,e/E = 6)
      (for s, precision will limit the number of printed characters)
.0    no decimal point is printed for f/F,e/E
.*    precision will be passed as int parameter before the actual argument

printf("Record %lX: name = %s, age = %d, hourly wage = %.3f\n",
       record_num, name, age, hourly_wage);

Now you should understand how this program works, so we can move on to new territory...

/* prog4-1.c: calc */

#include <stdio.h>
#include <math.h>

int main(void)
{
   double a, pi;
   int b;

   a = 500 / 40; /* Fraction is thrown away (integer math) */

   printf("a = %.3f\n", a);

   a = 500.0 / 40; /* Fraction is NOT thrown away (floating point math) */

   printf("a = %.3f\n", a);

   a++;

   printf("a now = %.3f\n", a);

   b = (int) a;
   b ^= 5;

   printf("b = %d\n", b);

   pi = 4 * atan(1.0);
   printf("pi ~= %.10f\n", pi);

   return 0;
}

a = 12.000
a = 12.500
a now = 13.500
b = 8
pi ~= 3.1415926536

[*] If you get "undefined symbol" or similar errors, you have to enable floating-point support in your compiler (see manual / online help)

4.2. Operators and typecasts

   double a, pi;
   int b;

   a = 500 / 40; /* Fraction is thrown away (integer math) */

We've encountered the assignment operator = before. The / is the division operator. So what this code does is dividing the value 500 by the value 40 [*] and storing the result in the variable a.

[*] Because both operands are constants, the compiler will most likely optimize this by calculating the result at compile-time.

The following operators are available (in order of precedence):

Precedence      Operator    Explanation
1. Highest      ()          Function call
                            (see 2.4. Functions and types)
                []          Array subscript
                            (see 10. Arrays, strings and pointers)
                ->          Indirect member selector
                            (see 6. Structs, unions and bit-fields)
                .           Direct member selector
                            (see 6. Structs, unions and bit-fields)
2. Unary        !           Logical negation: nonzero value -> 0, zero -> 1
                ~           Bitwise complement: all bits inverted
                +           Unary plus
                -           Unary minus
                ++          Pre/post-increment (see below)
                --          Pre/post-decrement (see below)
                &           Address
                            (see 10. Arrays, strings and pointers)
                *           Indirection
                            (see 10. Arrays, strings and pointers)
                sizeof      Returns size of operand in bytes; two forms:
                              1) sizeof(type)
                              2) sizeof expression
3. Multi-       *           Multiply
   plicative    /           Divide
                %           Remainder (only works for integers)
4. Additive     +           Binary plus
                -           Binary minus
5. Shift        <<          Shift bits left, e.g. 5 << 1 = 10
                >>          Shift bits right, e.g. 6 >> 1 = 3
6. Relational   <           Less than
                <=          Less than or equal to
                >           Greater than
                >=          Greater than or equal to (not =>)
7. Equality     ==          Equal to (not =)
                !=          Not equal to
8. Bitwise AND  &           Bitwise AND, e.g. 5 & 3 == 1
9. Bitwise XOR  ^           Bitwise XOR, e.g. 5 ^ 3 == 6
10. Bitwise OR  |           Bitwise OR,  e.g. 5 | 3 == 7
11. Logical AND &&          Logical AND
12. Logical OR  ||          Logical OR
13. Conditional ?:          Conditional operator
                            (see 7.4 Using the ?: operator)
14. Assignment  =           Simple assignment
                *=          Assign product (see below)
                /=          Assign quotient
                %=          Assign remainder
                +=          Assign sum
                -=          Assign difference
                &=          Assign bitwise AND
                ^=          Assign bitwise XOR
                |=          Assign bitwise OR
                <<=         Assign left shift
                >>=         Assign right shift
15. Comma       ,           Separates expressions

The unary (2), conditional (13) and assignment (14) operators associate from right to left, the others from left to right. E.g. 4/2*3 groups as (4/2)*3, not 4/(2*3), but e.g. a = b = 7 groups as a = (b = 7), so you can assign a value to multiple variables in one line, but this reduces the clarity, at least in my opinion.

The left operand of the assignment operators must be what is called an "lvalue", i.o.w. something to which a value can be assigned. Of course you can't put a constant or an expression on the left side of an assignment operator, because they are not variables that have a location in which a value can be stored. For the same reason it cannot be, for example, the name of an array or string (see 10. Arrays, strings and pointers).

Don't worry if you're a bit overwhelmed by this list. It's normal if you don't understand most of them yet; the more advanced ones will be explained later in this document (see the forward references); the prefix/postfix and special assignment operators are explained below; the mathematical operators should be obvious, the bitwise operators too if you know something about binary arithmetic; just watch out for their precedence: they have higher precedence than the logical operators but lower precedence than the relational operators. For example:

   a!=b&c

The logical AND/OR, relational and equality operators are usually used in conditions, such as those in an if statement (see Conditionals (if/else)). The relational and equality operators return 1 if the relationship or equality is true, 0 if it isn't. The logical AND/OR operators have the following logic:

logical AND: (&&)

   left operand  right operand  result
   zero          zero           0
   zero          nonzero        0
   nonzero       zero           0
   nonzero       nonzero        1

   left operand  right operand  result
   zero          zero           0
   zero          nonzero        1
   nonzero       zero           1
   nonzero       nonzero        1

   printf("a = %.1f\n", a);

This line outputs the value of a, which is 12.0. But 500/40 is 12.5, and since a double is used one could reasonably expect the decimal digits to be correct. The reason for the wrong result is that the constants 500 and 40 are both interpreted as integer values by the compiler. At least one of the constants should be explicitly made a floating-point constant by writing it as e.g. 500.0. That's what's done in the next line of code:

   a = 500.0 / 40; /* Fraction is NOT thrown away (floating point math) */

   printf("a = %.1f\n", a);

   a++;

a = 5;
b = a++;
/* b will now be 5, a will be 6 */

a = 5;
b = ++a;
/* b will now be 6, a will be 6 */

You can't use something like:

a = a++;                      /* wrong! use a++; or a = a + 1; instead */

   b = (int)a;

[*] Note that a typecasts does NOT reinterpret the bit pattern of a variable for the new type, but converts the value of the variable.

   b ^= 5;

   b = b ^ 5;   /* bitwise XOR of b with 5 */

   printf("b = %d\n",b);

   pi = 4 * atan(1.0);
   printf("pi ~= %.10f\n", pi);

/* prog5-1.c: colours */

#include <stdio.h>

enum colours {RED, ORANGE, YELLOW, GREEN, BLUE, INDIGO, VIOLET,
              NUMBER_OF_COLOURS};

typedef enum colours colour_t;

int main(void)
{
   colour_t sky, forest;

   printf("There are %d colours in the enum\n", NUMBER_OF_COLOURS);

   sky = BLUE;
   forest = GREEN;

   printf("sky = %d\n", (int)sky);
   printf("forest = %d\n", (int)forest);

   return 0;
}

There are 7 colours in the enum
sky = 4
forest = 3

enum colours {RED, ORANGE, YELLOW, GREEN, BLUE, INDIGO, VIOLET,
              NUMBER_OF_COLOURS};

[*] You can override this default numeric value by adding an explicit =value after the constant; the counting for subsequent constants will then continue from there.

word constant     numeric value
RED               0
ORANGE            1
YELLOW            2
GREEN             3
BLUE              4
INDIGO            5
VIOLET            6
NUMBER_OF_COLOURS 7

[*] Of course this will not be valid when different values are explicitly assigned to the constants as mentioned in the above note.

typedef enum colours colour_t;

enum colours somevariable;

In our example this means that everywhere where we use colour_t this is compiled as if there was an enum colours instead. So:

   colour_t sky, forest;

enum colours sky, forest;

   printf("There are %d colours in the enum\n", NUMBER_OF_COLOURS);

[*] That doesn't necessarily mean that enums and ints will be exactly the same type, but they are compatible types

So we could also have defined the variables like this:

int sky, forest;

Another consequence of this equivalence is that there is no special printf() format specifier to print an enum value. We have to use the format specifier for an integer: %d. An enum constant needn't even be cast as it is guaranteed to be of type int.

   printf("There are %d colours in the enum\n", NUMBER_OF_COLOURS);

   sky = BLUE;
   forest = GREEN;

   sky = 4;
   forest = 3;

   printf("sky = %d\n", (int)sky);
   printf("forest = %d\n", (int)forest);

[*] If you would really like the symbolic names to be printed, you'll have to write code to that yourself. You may want to use either an array of strings (see 10.2. Arrays and strings) or a switch() statement (see 8. switch/case/default).

/* prog6-1.c: cars */

enum brands {VOLKSWAGEN, FORD, MERCEDES, TOYOTA, PEUGEOT};

enum colours {RED, GREEN, BLUE, GREY, BLACK, WHITE};

struct car {enum brands brand;
            enum colours colour;
            int second_hand;
            union {unsigned long mileage; int months_guarantee;} carinfo;
            unsigned diesel:1, airbag:1, airconditioning:1;
            };

int main(void)
{
   struct car mycar = {VOLKSWAGEN, GREY, 1, 50000, 0, 0, 0};
   struct car yourcar;

   yourcar.brand = MERCEDES;
   yourcar.colour = BLACK;
   yourcar.second_hand = 0;
   yourcar.carinfo.months_guarantee = 12;
   yourcar.diesel = 1;
   yourcar.airbag = 1;
   yourcar.airconditioning = 1;

   return 0;
}

enum brands {VOLKSWAGEN, FORD, MERCEDES, TOYOTA, PEUGEOT};

enum colours {RED, GREEN, BLUE, GREY, BLACK, WHITE};

struct car {enum brands brand;
            enum colours colour;
            int second_hand;
            union {unsigned long mileage; int months_guarantee;} carinfo;
            unsigned diesel:1, airbag:1, airconditioning:1;
            };

struct structure_tag {type1 member1; type2 member2; /* etc. */ };

struct structure_tag mystructure;  /* don't forget the struct keyword */

[*] This could be written in one line as struct structure_tag {type1 member1; type2 member2;} mystructure; (in which case the structure_tag is optional)

A structure is a collection of different variables (called members) into a single type. It is usually used to describe all properties of a certain item in a single variable. In our cars example we could store information like the brand, colour etc. in a different variable for every car. But it is a lot more clear to concentrate all the information about one specific car into a type of its own, analogous to e.g. Pascal records. That's why a structure is used.

The first two members are familiar enums:

            enum brands brand;
            enum colours colour;

The next variable:

            int second_hand;

But the information that we need to store about a second hand car needn't be the same as that for a new car. For example, we only need to store the mileage information for second hand cars and guarantee information for new cars. So sometimes it may be a good idea to not have unneeded information take up space in our structures. That's why unions are available:

            union {unsigned long mileage; int months_guarantee;} carinfo;

[*] Many systems allow reading other members than the one last assigned to, but this is not standard.

Because of this, we have to keep track of whether the mileage member or the months_guarantee member contains a valid value. This can be determined by looking at the second_hand variable. If that is 1, the mileage member contains a valid value; if that is 0, the months_guarantee member contains a valid value.

            unsigned diesel:1, airbag:1, airconditioning:1;

[*] Bit-fields should always be of type signed int or unsigned int. If you use plain int, it is implementation-defined whether they'll be signed or unsigned. Many systems support other types, but this is not standard.

OK, now we move into the body of main():

   struct car mycar = {VOLKSWAGEN, GREY, 1, 50000, 0, 0, 0};
   struct car yourcar;

   yourcar.brand = MERCEDES;
   yourcar.colour = BLACK;
   yourcar.second_hand = 0;
   yourcar.carinfo.months_guarantee = 12;
   yourcar.diesel = 1;
   yourcar.airbag = 1;
   yourcar.airconditioning = 1;

The reason yourcar can't be initialized in the same way as mycar is that, as mentioned above, we can only initialize the first member variable of a union in that way, not the others (in this case the months_guarantee member variable).

/* prog7-1.c: yesno */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

int main(void)
{
   int yesno;

   srand((unsigned)time(NULL));

   yesno = rand() % 2;

   if (yesno==0)
      printf("No\n");
   else
      printf("Yes\n");

   return 0;
}

No

Yes

However, the oversize calculator that your computer really is cannot return really random numbers [*]. Instead, it uses something called pseudo-random numbers: they are numbers that are calculated using a mathematical algorithm, and which are therefore not really random at all, but which have the appearance of being random.

[*] Some specialized hardware may be used to measure random factors from e.g. the environment, but this falls way outside of the scope of the standard C language.

Obviously, if a program uses a certain mathematical algorithm to obtain these numbers, it will produce the very same numbers every time it runs. Not very random. That's why we must first initialize the random number generator with a value that is different nearly every time the program is run. A good value for that seems to be the current date and time.

The current date and time is returned when we call the time() function with NULL as parameter (see the section on time() in 16. Overview of the standard library if you want to know what this parameter is for). The value it returns is a time_t, and we don't really know what that is (it can be different on every system). All that interests us here is that the value will probably be different every time the program is run. [*]

[*] On some systems without a clock time() may return the same value (time_t)-1 every time, and on those this approach will of course fail.

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

   srand((unsigned)time(NULL));

The srand() function initializes the random number generator. It takes an unsigned integer value as parameter. As explained above, we use the return value of time(NULL) as the initializer (often called the seed of the random number generator), which is this unknown type time_t. We explicitly typecast (see 4.2. Operators and typecasts) this type to an unsigned integer [*] to suppress possible compiler complaints (since we know what we're doing and don't really care if for example we may lose some of the time information in the conversion; all that matters is that the value should be different every time the program is run, when possible).

[*] On some rare systems this may cause an overflow error.

   yesno = rand() % 2;

[*] This method is not very good, but used here for its simplicity. A better method (taken from the c.l.c FAQ) would be to use something like: (int)((double)rand() / ((double)RAND_MAX + 1) * N)
For more information, see question 13.16 in the c.l.c FAQ, the URL can be found in: 17.2. Other interesting C-related online material

7.3. Using if/else

   if (yesno==0)
      printf("No\n");
   else
      printf("Yes\n");

if (condition)
   statement_that_is_executed_if_the_condition_is_true;
else
   statement_that_is_executed_if_the_condition_is_false;

If the code in the if or else part of the statement consists of more than one statement, a block must be used:

if (condition)
{
   possibly_more_than_one_statement;
}
else
   still_one_statement;

You can chain if statements as following:

if (condition)
   some_code;
else if (another_condition)
   some_other_code;
else
   even_different_code;

a = c + (b<4 ? 1 : 2);

if (b<4)
   a = c + 1;
else
   a = c + 2;

   condition ? expr1 : expr2

You have to be careful with predecence: the ?: operator has very low precedence (only assignment and comma operators have lower precedence). If you're not sure, it's safest to use enough parentheses.

/* prog8-1.c: animals */

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

enum animal {CAT, DOG, COW, SNAIL, SPIDER, NUMBER_OF_ANIMALS};

void animalsound(enum animal animalnumber)
{
   switch(animalnumber)
   {
   case CAT:
      printf("Miaow!\n");
      break;
   case DOG:
      printf("Woof!\n");
      break;
   case COW:
      printf("Moo!\n");
      break;
   default:
      printf("Animal makes no audible sound.\n");
      break;
   }
}

void animalfood(enum animal animalnumber)
{
   switch(animalnumber)
   {
   case COW:
   case SNAIL:
      printf("Eats plants.\n");
      break;
   case CAT:
   case SPIDER:
      printf("Eats beasts.\n");
      break;
   }
}

int main(void)
{
   enum animal myanimal, youranimal;

   srand((unsigned)time(NULL));

   myanimal = rand() % NUMBER_OF_ANIMALS;

   animalsound(myanimal);
   animalfood(myanimal);

   youranimal = rand() % NUMBER_OF_ANIMALS;

   animalsound(youranimal);
   animalfood(youranimal);

   return 0;
}

Moo!
Eats plants.
Animal makes no audible sound.
Eats beasts.

enum animal {CAT, DOG, COW, SNAIL, SPIDER, NUMBER_OF_ANIMALS};

void animalsound(enum animal animalnumber)
{
}

In this case, the animalsound() function will print out the corresponding sound for a given animal of our above enum type.

   switch(animalnumber)
   {
   case CAT:
      printf("Miaow!\n");
      break;
   case DOG:
      printf("Woof!\n");
      break;
   case COW:
      printf("Moo!\n");
      break;
   default:
      printf("Animal makes no audible sound.\n");
      break;
   }

Every case should end with a break; statement, because otherwise the code simply keeps continuing into the next case statement. This is known as fallthrough, and has both its advantages and disadvantages. Once you're used to it it shouldn't pose any problems, you just have to remember to put the break; in there. See below for a useful example of fallthrough.

A special case is the default: case. If a default: case is present, its code is executed when none of the other cases match. In our case the animals SNAIL and SPIDER don't have explicit case labels, and for them the default: case of "Animal makes no audible sound." will be executed.

The above code would be equivalent to: (apart from the fact that the animalnumber is evaluated multiple times in the if form)

if (animalnumber==CAT)
   printf("Miaow!\n");
else if (animalnumber==DOG)
   printf("Woof!\n");
else if (animalnumber==COW)
   printf("Moo!\n");
else
   printf("Animal makes no audible sound.\n");

Another difference between the if() and switch() form is that in the if() form non-integral types like double may be used. However, floating point variables may not be able to store an exact value, so you should not compare them with the equality operator (==). Instead you should limit the absolute value of the difference between the two to a certain percentage of the values, something like:

if (fabs(x-y) < x * 0.00001)
   /* x and y may be considered equal */ ;

The following functions prints out the type of food the specified animal number will consume:

void animalfood(enum animal animalnumber)
{
}

   switch(animalnumber)
   {
   case COW:
   case SNAIL:
      printf("Eats plants.\n");
      break;
   case CAT:
   case SPIDER:
      printf("Eats beasts.\n");
      break;
   }

Also, there is no default: statement, which means that for the animals for which no explicit case is present (such as DOG here), no code will be executed, and therefore nothing will be printed.

   enum animal myanimal, youranimal;

   srand((unsigned)time(NULL));

   myanimal = rand() % NUMBER_OF_ANIMALS;

   animalsound(myanimal);
   animalfood(myanimal);

   youranimal = rand() % NUMBER_OF_ANIMALS;

   animalsound(youranimal);
   animalfood(youranimal);

/* prog9-1.c: loops */

#include <stdio.h>

int main(void)
{
   int i;

   i = 1;
   while (i<4)
   {
      printf("%d\n",i);
      i++;
   }

   printf("\n");

   i = 1;
   do
   {
      printf("%d\n",i);
      i++;
   }
   while (i<4);

   printf("\n");

   for (i=15; i>=10; i--)
      printf("%d\n",i);

   return 0;
}

1
2
3

1
2
3

15
14
13
12
11
10

   i = 1;
   while (i<4)
   {
   }

while (condition)
   statement;

while (condition)
{
   code;
}

The code will be repeatedly executed (looped) for as long as the condition is true. Obviously the code somehow needs to do something which may change this condition, or the loop will execute forever.

In our case the code in the loop body is:

      printf("%d\n",i);
      i++;

1
2
3

   printf("\n");

   i = 1;
   do
   {
      printf("%d\n",i);
      i++;
   }
   while (i<4);

However, in a do-while() loop the condition is at the end, which means that the loop will always be executed at least once, even if the condition was false to begin with. So in the above example where i was 5 at the beginning, this loop would still have output 5 before ending.

   for (i=15; i>=10; i--)
      printf("%d\n",i);

A for loop has the following form:

for (initialization; condition; modification)
   code;

for (initialization; condition; modification)
{
   code;
}

initialization;
while (condition)
{
   code;
   modification;
}

[*] Not 100% equivalent, because the continue statement will work differently in the code using while() than that using for()

You can put more than one expression in the initialization, condition and/or modification part by separating them by the comma operator (,).

In our case:

   for (i=15; i>=10; i--)
      printf("%d\n",i);

The loop condition is i>=10.

The modification decrements i by 1.

So this loop will start with i=15, checks that condition i>=10 is fulfilled, print out the value 15, decrement i by 1, check the condition again, etc. until the condition is no longer fulfilled.

This will therefore produce the following output:

15
14
13
12
11
10

i = 15;
while (i>=10)
{
   printf("%d\n",i);
   i--;
}

for (;;)
{
   code;
}

while (1)
{
   code;
}

It works in a similar way for loop statements, such as while(), do-while() or for(). It aborts the execution of the loop without checking the condition. It's a way of saying "exit now, no questions asked". You should try to avoid this when it is not really necessary, because it may cause the program's execution flow to be difficult to follow. Also be aware that a break; statement can only exit the innermost loop or switch() block, not any surrounding ones.

The continue; statement is a slightly more 'civilised' version of the break; statement. It says "abort this round of the loop execution, jump immediately to the condition evaluation". If the condition is still fulfilled, the loop will continue executing at the next round. If it is no longer fulfilled, the loop will be aborted. For example, suppose you want to process all elements i,j of a matrix except those on the main diagonal line (those where i==j), you could do something like this: (assume i and j are integer variables)

for (i=0; i<10; i++)
{
   for (j=0; j<10; j++)
   {
      if (i==j)
         continue;            /* skip elements on main diagonal line */
      /* code to process element i,j */
   }
}

The goto statement can be used to jump to anywhere in the current function [*], but it's best to use it only to jump out of blocks, never into blocks, and jumping past variable initializations is usually a bad idea.

[*] To jump between functions - if you really must! - you should use setjmp()/longjmp() (see 16. Overview of the standard library)

You have to prefix the statement you wish to jump to by a label as follows:

mylabel: printf("some statement\n");

mylabel: ;

   goto mylabel;

for (i=1; i<100; i++)
{
   for (j=1; j<100; j++)
   {
      for (k=1; k<100; k++)
      {
         if (some_error_condition)
            goto abort_for_loops;
      }
   }
}
abort_for_loops: ;

/* prog10-1.c: strings */

#include <stdio.h>
#include <string.h>

int main(void)
{
   char s[20];

   strcpy(s, "strings");

   printf("s = %s\n", s);
   printf("s[3] = %c\n", s[3]);
   printf("s[7] = %d\n", s[7]);
   printf("strlen(s) = %lu\n",(unsigned long)strlen(s));

   strcat(s, " program");
   printf("s now = %s\n", s);
   printf("strlen(s) = %lu\n",(unsigned long)strlen(s));

   return 0;
}

s = strings
s[3] = i
s[7] = 0
strlen(s) = 7
s now = strings program
strlen(s) = 15

#include <string.h>

As usual, at the beginning of main() we find a variable definition:

   char s[20];

[*] Variable length arrays are proposed for the new C standard

Multi-dimensional arrays (e.g. one that has rows and columns) can be defined as, for example, int multiarray[100][50]; etc.

You can have arrays of any type of variable. However arrays of char are often used for a special purpose: strings. A string is basically just text. Some languages have direct support for a 'string' type, but C doesn't. A string is an array of char with a special feature: the end of the string is marked by a char with value 0. That means we need to allocate one additional byte to store this 0 terminator. The consequence for our example is that s is able to hold a string of at most 19 characters long, followed by the 0 terminator byte.

   strcpy(s, "strings");

   s = "strings";          /* wrong! */

To copy string1 to string2 you would write:

   strcpy(string2, string1);    /* notice the order of the parameters! */

   printf("s = %s\n", s);
   printf("s[3] = %c\n", s[3]);
   printf("s[7] = %d\n", s[7]);

The second line prints out the character (element) with index 3 in the array. Such an element is written as arrayname[indexnumber]. You have to be careful with the index numbers, though: in C all counting starts from 0. So the 1st element really is element number 0, the 2nd element is element number 1, etc. This also means that s[20] would be the 21st element of our array, and since the array is only 20 elements long, this value is out of range and therefore not valid!

In our case the string variable contains the text "strings" followed by the 0 byte. Since s[3] is the 4th element of the array, thus the 4th character of the string, an 'i' is printed (the %c printf() format specifier is used to print a character).

The third line prints s[7], which is the 8th character of the string. Since the text is only 7 characters long, the 8th character is our 0 terminator byte. That's why it's printed using %d (integer value) instead of %c (the 0 terminator usually doesn't have a character representation).

   printf("strlen(s) = %lu\n",(unsigned long)strlen(s));

   strcat(s, " program");

   strcat(string2, string1);   /* notice order of parameters */

In our case we add the string literal " program" to our already existing string "strings". The resulting string will be 7 + 8 = 15 characters long, plus the 0 terminator this requires 16 elements. Since our array is 20 elements long, there is no problem.

   printf("s now = %s\n", s);
   printf("strlen(s) = %lu\n",(unsigned long)strlen(s));

/* prog10-2.c: pointers */

#include <stdio.h>

int main(void)
{
   int a[] = {1,2,3,5,7,11,13,17,19};
   int *p;

   printf("a[4] = %d\n", a[4]);

   printf("the address of the array = %p\n", (void *)a);
   printf("the address of element nr. 0 of the array = %p\n", (void *)&a[0]);
   printf("the address of element nr. 4 of the array = %p\n", (void *)&a[4]);

   p = a;

   printf("the value of the pointer = %p\n", (void *)p);
   printf("the value the pointer points at = %d\n", *p);

   p += 4;

   printf("the value of the pointer now = %p\n", (void *)p);
   printf("the value the pointer now points at = %d\n", *p);

   return 0;
}

a[4] = 7
the address of the array = 00030760
the address of element nr. 0 of the array = 00030760
the address of element nr. 4 of the array = 00030770
the value of the pointer = 00030760
the value the pointer points at = 1
the value of the pointer now = 00030770
the value the pointer now points at = 7

What's a pointer ? Well, every variable has to be stored somewhere in your computer's memory. The place where they are stored is called the address of the variable. Such an address is some sort of position value (its exact representation depends on your system, and shouldn't really matter).
Such an address value can of course be stored in another variable (which has its own, different, address). That's called a pointer. A pointer contains the position in memory (address) of another variable, so in effect 'points' to this variable. Now let's analyze the program line by line and explain things on the way:

   int a[] = {1,2,3,5,7,11,13,17,19};

   int *p;

[*] If you need a generic pointer, not to any specific type of variable, you should use a pointer to void (void *). However, you can't do the sort of calculations with these sort of pointers that we're doing in this program.

   printf("a[4] = %d\n", a[4]);

   printf("the address of the array = %p\n", (void *)a);

OK, so we have the address of the array's first element, which is the same value as the address of the array (the type is different; the former is a pointer to int, the latter a pointer to an array of int). Now how do we print it ? That's something special. The printf format specifier %p prints the value of a pointer (thus an address). What it prints exactly will be different on every system, but the concept will be the same.

But %p is used to print a generic pointer as seen in the note above: a void * instead of the int * that the address of the array will be. Therefore we have to typecast (see 4.2. Operators and typecasts) the pointer value (address) to a void *. [*]

[*] On many systems simply passing an int * to the printf() format specifier %p will work fine; but the standard requires this conversion.

   printf("the address of element nr. 0 of the array = %p\n", (void *)&a[0]);
   printf("the address of element nr. 4 of the array = %p\n", (void *)&a[4]);

However, instead of using the arrayname a to get the address of the array's first element, an element index is used (0 resp. 4) between the [ ], and another operator is prepended: the address operator (&). Putting & before something takes the address of that something (when that something has an address of course; something like &5 will not work since the constant 5 doesn't have an address in memory; it is not an lvalue). So &variable takes the address of the variable, and &arrayname[indexnumber] takes the address of an element of an array.

In our case, the first line will always print the same address value as the previous one, because &a[0] (the address of element number 0, i.e. the first element of the array) will always be the same as just a (the address of the array's first element). But &a[4] (the address of element number 4, i.e. the fifth element of the array) will be a bit higher. [*]

[*] The example output printed above on my system can be explained as follows: an int is 4 bytes on my system (this may be different on yours), and my %p prints out addresses as hexadecimal values (that may also be different on yours), so 00030770 (&a[4]) is 16 (10h) bytes past 00030760 (&a[0] or just a).

   p = a;

   printf("the value of the pointer = %p\n", (void *)p);

   printf("the value the pointer points at = %d\n", *p);

[*] As seen above, this * is also used for defining pointers. You could also read the definition int *p; as "p dereferenced is int".

Since p points at the first element of the array, the value of element number 0 of the array will be printed: 1.

   p += 4;

This is equivalent to p = p + 4; (see 4.2. Operators and typecasts). But how can you calculate with a pointer ? Well, the address value contained in the pointer variable can be modified using the operators + and -. However, there's one important difference to calculating with normal integral values: adding 4 to the pointer as in this example does not necessarily add 4 to the address value; instead it moves the pointer 4 elements of the type it points at further (so if your ints are 4 bytes like mine, this will add 4*4=16 to your address value). [*]

[*] You can't do this with the generic pointers to void, because the compiler doesn't know how many bytes the elements you're pointing at are.

So in this case p will now no longer point to element number 0 of the array, but to element number 4.

   printf("the value of the pointer now = %p\n", (void *)p);
   printf("the value the pointer now points at = %d\n", *p);

Note: you can make pointers constants, too, just like regular variables; but watch out:

int *p;              /* p itself and what p points to may be modified */
const int *p;        /* p itself may be modified; what p points to may not */
int * const p;       /* p itself may not be modified; what p points to may */
const int * const p; /* p itself nor what it points to may be modified */

Something else to watch out for is this:

char *a,b;

typedef char *char_pointer;
char_pointer a,b;

There is also a special pointer value, which may be used for all pointer types, that is used to indicate an invalid pointer value. This is the NULL pointer. NULL is defined in stdio.h, stdlib.h, stddef.h and in other headers. You should use NULL only for pointer values (to indicate an invalid pointer), not for other types of variables (e.g. not for an integral 0 value). You can use a plain 0 instead of NULL as well for this purpose, but most people prefer using NULL as a stylistic hint. [*]

[*] You shouldn't worry about what pointer value NULL is exactly. At the source code level 0 will evaluate to a NULL pointer value, but this does definitely not mean that the actual NULL pointer value must be a value with all bits 0.

Pointers are also useful in simulating "call by reference", which means that a function can change the value of its parameters and these changes will be passed on to the caller as well. With normal parameters (other than arrays) this is not possible in C, because they are always passed as "call by value", which means that the function can only access a copy of the actual values, and this will have no effect on the calling code.

By using a parameter of type "pointer to type" instead of just "type" this is possible. The calling code must then insert the address operator & before the variable passed as the parameter. The function can then access and modify the value using the dereference operator (*). This is also referred to as "pass by pointer" and you should not confuse it with the call by reference that is supported in C++, Pascal etc. because they don't require the calling code to explicitly insert an address operator.

An example may shed some light on this:

void swapintegers(int a, int b)
{
   int temp;

   temp = a;
   a = b;
   b = temp;
}

swapintegers(myvariable, yourvariable);

void swapintegers(int *a, int *b)
{
   int temp;

   temp = *a;
   *a = *b;
   *b = temp;
}

swapintegers(&myvariable, &yourvariable);

/* prog10-3.c: command line arguments */

#include <stdio.h>

int main(int argc, char *argv[])
{
   int i;

   printf("There are %d command line arguments\n", argc);

   for (i=0; i < argc; i++)
   {
      printf("Command line argument number %d = %s\n", i, argv[i]);
   }

   return 0;
}

There are 3 command line arguments
Commandline argument number 0 = C:\CINTRO\PROG11.EXE
Commandline argument number 1 = test
Commandline argument number 2 = 123

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

On most systems (not all!) argc is usually at least 1. If that is the case argv[0] is either an empty string or the filename (with or without the full path) of the executable. If argc is at least 2 there are command line arguments. In that case argv[1] is the first command line argument, argv[2] the second one, etc. until argv[argc-1].

   printf("There are %d command line arguments\n", argc);

   int i;

   /* ... */

   for (i=0; i < argc; i++)
   {
      printf("Commandline argument number %d = %s\n", i, argv[i]);
   }

Note: as said above, the definition:

   char *argv[]

   char **argv

These sort of definitions and declarations can soon become confusing, especially when pointers to functions etc. start coming into play. A handy rule to understand complex definitions is the so-called right-to-left rule. You can read all about it in rtlftrul.txt in the Snippets collection (see 17.2. Other interesting online C-related material).

/* prog11-1.c: fileio */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(void)
{
   char s[20];
   char *p;
   FILE *f;

   strcpy(s,"file I/O test!");

   printf("%s\n",s);

   f = fopen("testfile","w");
   if (f==NULL)
   {
      printf("Error: unable to open testfile for writing\n");
      return EXIT_FAILURE;
   }

   fputs(s,f);

   fclose(f);

   strcpy(s,"overwritten");

   printf("%s\n",s);

   f = fopen("testfile","r");
   if (f==NULL)
   {
      printf("Error: unable to open testfile for reading\n");
      return EXIT_FAILURE;
   }

   if (fgets(s, sizeof s, f) != NULL)
   {
      p = strchr(s,'\n');
      if (p!=NULL)
         *p = '\0';

      printf("%s\n",s);
   }

   fclose(f);

   if (remove("testfile") != 0)
   {
      printf("Error: unable to remove testfile\n");
      return EXIT_FAILURE;
   }

   return EXIT_SUCCESS;
}

file I/O test!
overwritten
file I/O test!

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

We need stdlib.h because we're no longer going to simply use return 0; but we're going to return a success/failure status to the operating system and EXIT_SUCCESS and EXIT_FAILURE are defined in stdlib.h (see 2.5. return).

We need string.h because we're going to work with strings, and need the functions strcpy() and strchr().

   char s[20];
   char *p;
   FILE *f;

The second line defines a pointer to char that will be used to store the return value of the strchr() function (see below).

The third line defines a pointer to FILE. Such a pointer to FILE is used by almost all the file I/O programs in C. It is also referred to as a stream. This pointer is the only form the FILE type is used as; you may not define variables of type FILE by themselves.

   strcpy(s,"file I/O test!");

   printf("%s\n",s);

   f = fopen("testfile","w");

The first parameter to fopen() is the filename (a string). The second parameter is also a string, and can be any of the following:

"w"    open for writing (existing file will be overwritten)
"r"    open for reading (file must already exist)
"a"    open for appending (file may or may not exist)
"w+"   open for writing and reading (existing file will be overwritten)
"r+"   open for reading and updating (file must already exist)
"a+"   open for appending and reading (file may or may not exist)

Append mode ("a") will cause all writes to go to the end of the file, regardless of any calls to fseek(). By default the files will be opened in text mode (which means that '\n' will be translated to your operating system's end-of-line indicator, other sorts of translations may be performed, EOF characters may be specially treated etc.). For binary files (files that must appear on disk exactly as you write to them) you should add a "b" after the above strings. [*]

[*] Some compilers also support a "t" for text files, but since this is non-standard and not required (since it is the default) you shouldn't use it.

   if (f==NULL)
   {
      printf("Error: unable to open testfile for writing\n");
      return EXIT_FAILURE;
   }

If that happens, this program prints an error message and returns to the operating system with the EXIT_FAILURE status.

   fputs(s,f);

   fclose(f);

   strcpy(s,"overwritten");

   printf("%s\n",s);

   f = fopen("testfile","r");
   if (f==NULL)
   {
      printf("Error: unable to open testfile for reading\n");
      return EXIT_FAILURE;
   }

   if (fgets(s, sizeof s, f) != NULL)
   {
   }

      p = strchr(s,'\n');
      if (p!=NULL)
         *p = '\0';

The fgets() function does not automatically remove the '\n' character that terminates a line. That's why it is manually removed by the above code. The return value of strchr(s,'\n') will be a pointer to the first occurence of the character '\n' in the string, or NULL if none is found. So we store this return value in the char pointer p, and if it is not NULL we set the newline character it is pointing at to the '\0' terminating character ('\0' is an octal character code constant (see 2.4. Functions and types), and is therefore equivalent to 0. It is often used instead of plain 0 to make clear that it is used as a character constant), thereby effectively terminating the string in such a way that the newline character is stripped off.

      printf("%s\n",s);

   fclose(f);

   if (remove("testfile") != 0)
   {
      printf("Error: unable to remove testfile\n");
      return EXIT_FAILURE;
   }

   return EXIT_SUCCESS;

Note: fgets() and fputs() are used for reading/writing strings, usually from/to text files. When interfacing with binary files, often non-string data should be read/written. That's what the fread()/fwrite() functions are for (see 16. Overview of the standard library) [*].

[*] When reading/writing a specified file format you may be tempted to use fread()/fwrite() to read/write structures from/to a file. However, there may (and will!) often be padding bytes inbetween member variables and at the end of the structure. So in that case you'll have to resort to either reading/writing every member variable separately, or if portability isn't your greatest concern your system may support a way of turning off this padding.

For reading/writing single characters the fgetc()/fputc() functions are available (see 16. Overview of the standard library) [*]. There are also the equivalent getc()/putc() functions which may be implemented as a macro (see 13. Preprocessor macros/conditionals).

[*] When using these functions you should store the return value in a variable of type int, not of type char, because they can return EOF if an error occurred.

11.3. The interact program

/* prog11-2.c: interact */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int main(void)
{
   char name[20];
   char buffer[10];
   char *p;
   int age, ok;

   printf("Enter your name: ");
   fflush(stdout);

   if (fgets(name, sizeof name, stdin) == NULL)
   {
      printf("Error reading name from stdin\n");
      return EXIT_FAILURE;
   }

   p = strchr(name,'\n');
   if (p!=NULL)
      *p = '\0';

   fprintf(stdout, "Welcome, %s!\n", name);

   do
   {
      printf("Enter your age [1-150]: ");
      fflush(stdout);
      if (fgets(buffer, sizeof buffer, stdin) != NULL
          && sscanf(buffer, "%d", &age) == 1
          && age>=1 && age<=150)
      {
         ok = 1;
      }
      else
      {
         ok = 0;
         printf("Invalid age! Enter again...\n");
      }
   }
   while (!ok);

   printf("Your age now is %d. In 10 years your age will be %d.\n",
          age, age+10);

   return EXIT_SUCCESS;
}

Enter your name: John Doe
Welcome, John Doe!
Enter your age [1-150]: 32
Your age now is 32. In 10 years your age will be 42.

   char name[20];
   char buffer[10];
   char *p;
   int age, ok;

   printf("Enter your name: ");
   fflush(stdout);

[*] fflush() should only be used for output streams, because when used on input streams it produces undefined behaviour; on some systems it clears any pending input characters but this is definitely not standardized behaviour

   if (fgets(name, sizeof name, stdin) == NULL)
   {
      printf("Error reading name from stdin\n");
      return EXIT_FAILURE;
   }

   p = strchr(name,'\n');
   if (p!=NULL)
      *p = '\0';

[*] If the user attempts to enter more characters then allowed, the excess characters will be left on stdin to be read later. This may be undesirable, but isn't dealt with here to keep the code simple.

The only difference is that this time we don't use a pointer to FILE which we opened ourselves, but the stdin standard input stream, which is a pointer to FILE that is already opened for us. The following are available:

stdin    standard input stream (often keyboard)
stdout   standard output stream (often screen)
stderr   standard error stream (often screen)

[*] Some systems support more, such as e.g. stdprn for a standard printer stream, but this is not standard.

You may notice that for obtaining input from the stdin stream, instead of fgets() some people use the gets() function. However, this function does not accept a size parameter, so it can't control the input to fit within the array and will therefore happily overwrite any memory past the array thereby causing undefined behaviour (core dump, system crash, ...). Concerning the gets() function I have only one advice: do NOT use it. At all.

   fprintf(stdout, "Welcome, %s!\n", name);

   printf("Welcome, %s!\n", name);

   do
   {
   }
   while (!ok);

      printf("Enter your age [1-150]: ");
      fflush(stdout);

      if (fgets(buffer, sizeof buffer, stdin) != NULL
          && sscanf(buffer, "%d", &age) == 1
          && age>=1 && age<=150)
      {
         ok = 1;
      }
      else
      {
         ok = 0;
         printf("Invalid age! Enter again...\n");
      }

printf() has an opposite: the scanf() function. It also uses a format string like printf(), and is passed a variable number of arguments consisting of variables that correspond to a specific format specifier in the format string. But because the variables will be used to store an input result in, they must be prepended with the & address operator, so that their address is passed instead of their value (this is not required for arrays, such as strings, because they are always passed via their address anyway).

The format specifiers are mostly the same as those for printf() (see 3.3. printf). However, because an address is passed instead of a value there is no more float -> double, char -> int or short -> int promotion, so the following new format specifiers or modifiers are added/changed:

Format specifiers:
%i    unlike %d, allows for entering hex (0x...) or octal constants (0...)
%n    number of characters read upto now will be stored in signed int
%c    exact number of characters specified by width specifier will be read
      (when no width specifier is present, 1 character will be read)
%[character list]   longest string consisting of the characters in the
                    character list will be read
%[^character list]  longest string consisting of characters other than
                    those in the character list will be read
Modifiers:
h     for d,u,x,o: short int instead of int
      for n: result will be stored in short int
l     for d,u,x,o: long int instead of int
      for n: result will be stored in long int
      for f,e,g: double instead of float
      (note that this is different from printf(), where %lf etc.
       may not be used for printing a double)
*     assignment suppression

A better approach is to read a string using the fgets() function, and then process the input from this string using the sscanf() function. The sscanf() function works like the scanf() function, except that it takes as its first parameter the string where it has to read its input from. So in our case:

      sscanf(buffer, "%d", &age)

However, we have to check whether all of this was successful because the user might also have entered something like "foo bar" instead of a valid age. Hence the code:

          sscanf(buffer, "%d", &age) == 1

          && age>=1 && age<=150

We use a special feature of the logical operators && (and ||) here: they are the only operators that are guaranteed to execute from left to right, so we can be sure that by the time the sscanf() is reached the fgets() has been executed and by the time we check the value of age, the sscanf() has been executed. You may not rely on this with other operators (except the comma operator and the ?: operator). The && and || operators also have something called short-circuiting: if the left operand of the && operator is false, the right operand is guaranteed not to be evaluated. Similarly, if the left operand of the || operator is true, the right operand is guaranteed not to be evaluated.

      if (fgets(buffer, sizeof buffer, stdin) != NULL
          && sscanf(buffer, "%d", &age) == 1
          && age>=1 && age<=150)
      {
         ok = 1;
      }
      else
      {
         ok = 0;
         printf("Invalid age! Enter again...\n");
      }

   printf("Your age now is %d. In 10 years your age will be %d.\n",
          age, age+10);

Another function that is often used to read input from stdin is getchar(). It reads a single character, but does require the user to press enter. To avoid this, compiler/operating system specific functions have to be used. You have to be careful when using it similar to this:

if ((c=getchar()) != EOF)
   /* code */ ;

/* prog12-1.c: persons */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

struct person {char name[30];   /* full name */
               unsigned birthday,    /* 1..31 */
                   birthmonth,  /* 1..12 */
                   birthyear;   /* 4 digits */
              };

int main(void)
{
   struct person *personlist;
   unsigned number_of_persons, num;
   char buffer[30];
   char *p;
   int year, month, day;
   int ok;

   do
   {
      printf("Enter the number of persons: ");
      fflush(stdout);
      if (fgets(buffer, sizeof buffer, stdin) != NULL
          && sscanf(buffer, "%u", &number_of_persons) == 1)
      {
         ok = 1;
         if (number_of_persons>0)
         {
            personlist = malloc(number_of_persons * sizeof(struct person));
            if (personlist==NULL)
            {
               printf("Not enough memory to store that many persons!\n");
               ok = 0;
            }
         }
      }
      else
      {
         ok = 0;
         printf("Invalid number! Enter again...\n");
      }
   }
   while (!ok);

   if (number_of_persons==0)
   {
      printf("OK, perhaps another time!\n");
      return 0;
   }

   for (num=0; num<number_of_persons; num++)
   {
      printf("\nEnter the information for person #%u:\n", num);
      printf("Name: ");
      fflush(stdout);
      if (fgets(buffer, sizeof buffer, stdin) == NULL)
      {
         printf("Error reading from stdin; input aborted\n");
         number_of_persons = num;
         break;
      }
      p = strchr(buffer,'\n');
      if (p!=NULL)
         *p = '\0';
      if (strlen(buffer)==0)
      {
         printf("Input stopped\n");
         number_of_persons = num;
         break;
      }
      strcpy(personlist[num].name, buffer);
      do
      {
         printf("Birthday [YYYY-MM-DD]: ");
         fflush(stdout);
         if (fgets(buffer, sizeof buffer, stdin) != NULL
             && sscanf(buffer, "%d-%d-%d", &year, &month, &day) == 3
             && year>=1000 && year<=9999
             && month>=1 && month<=12
             && day>=1 && day<=31)
         {
            ok = 1;
         }
         else
         {
            ok = 0;
            printf("Invalid birthday! Enter again...\n");
         }
      }
      while (!ok);
      personlist[num].birthyear = year;
      personlist[num].birthmonth = month;
      personlist[num].birthday = day;
   }

   printf("\nOK, thank you.\n");

   printf("\nYou entered the following data:\n");

   printf("\n%-10s%-30s%s\n", "Number", "Name", "Birthday");

   for (num=0; num<number_of_persons; num++)
   {
      printf("%-10u%-30s%04d-%02d-%02d\n",
                num,
                personlist[num].name,
                personlist[num].birthyear,
                personlist[num].birthmonth,
                personlist[num].birthday);
   }

   free(personlist);

   return 0;
}

Enter the number of persons: 10

Enter the information for person #0:
Name: John Doe
Birthday [YYYY-MM-DD]: 70-5-31
Invalid birthday! Enter again...
Birthday [YYYY-MM-DD]: 1970-5-31

Enter the information for person #1:
Name: Foo Bar
Birthday [YYYY-MM-DD]: 1948-1-1

Enter the information for person #2:
Name:
Input stopped

OK, thank you.

You entered the following data:

Number    Name                          Birthday
0         John Doe                      1970-05-31
1         Foo Bar                       1948-01-01

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

As usual, stdio.h is needed for our input/output, and string.h for the string functions we need, like strchr() and strcpy(). However, stdlib.h is also needed because it contains the declarations for the malloc() and free() functions, which we'll use for our dynamic memory allocation.

struct person {char name[30];   /* full name */
               unsigned birthday,    /* 1..31 */
                   birthmonth,  /* 1..12 */
                   birthyear;   /* 4 digits */
              };

Don't forget that what we've defined here is just a structure type, we don't have any actual variables capable of holding any information yet.

   struct person *personlist;
   unsigned number_of_persons, num;
   char buffer[30];
   char *p;
   int year, month, day;
   int ok;

   struct person personlist[100];

How do we solve this problem ? Instead of determining the number of persons in our program's source code, we let the user determine it at runtime, dynamically. That's why we'll need dynamic memory allocation. To be able to do that we must define a pointer (see 10.4. Adresses and pointers) to our type (in this case struct person). This pointer doesn't yet point anywhere valid and no memory is allocated yet, so you shouldn't make the mistake of attempting to use the pointer before any memory has been allocated for it.

That explains the following definition of a pointer to struct person:

   struct person *personlist;

   unsigned number_of_persons, num;
   char buffer[30];
   char *p;
   int year, month, day;
   int ok;

   do
   {
   }
   while (!ok);

      printf("Enter the number of persons: ");
      fflush(stdout);
      if (fgets(buffer, sizeof buffer, stdin) != NULL
          && sscanf(buffer, "%u", &number_of_persons) == 1)
      {
         ok = 1;
      }
      else
      {
         ok = 0;
         printf("Invalid number! Enter again...\n");
      }

However, after the ok=1; statement something new follows:

         if (number_of_persons > 0)
         {
            personlist = malloc(number_of_persons * sizeof(struct person));
            if (personlist==NULL)
            {
               printf("Not enough memory to store that many persons!\n");
               ok = 0;
            }
         }

[*] We explicitly check for the 0 case, because according to the standard, the behaviour of malloc(0) is implementation-defined.

The parameter of malloc() is the number of bytes that should be allocated. In our case we use:

   malloc(number_of_persons * sizeof(struct person))

[*] Another, slightly better method would be to use sizeof *personlist instead of sizeof(struct person), because this will remain correct even if we change the type that personlist points to to something other than struct person.

The malloc() function returns a generic pointer to void which points to the allocated memory. By assigning this value to the personlist pointer, our pointer now points to actual usable memory:

            personlist = malloc(number_of_persons * sizeof(struct person));

            if (personlist==NULL)
            {
               printf("Not enough memory to store that many persons!\n");
               ok = 0;
            }

   if (number_of_persons==0)
   {
      printf("OK, perhaps another time!\n");
      return 0;
   }

   for (num=0; num<number_of_persons; num++)
   {
   }

      printf("\nEnter the information for person #%u:\n", num);
      printf("Name: ");
      fflush(stdout);
      if (fgets(buffer, sizeof buffer, stdin) == NULL)
      {
         printf("Error reading from stdin; input aborted\n");
         number_of_persons = num;
         break;
      }
      p = strchr(buffer,'\n');
      if (p!=NULL)
         *p = '\0';
      if (strlen(buffer)==0)
      {
         printf("Input stopped\n");
         number_of_persons = num;
         break;
      }
      strcpy(personlist[num].name, buffer);

[*]See 9.3. Using break,continue,goto. This is an example of where break; can be useful.

After we verified that the input is valid (i.o.w. not an empty string), we copy the string in buffer to the name member variable of the current structure in the personlist. The n-th element (in this case structure) in the memory that personlist points to is accessed like this: (here as well, n starts counting at 0)

   personlist[n]

The member selector operator (.) is then used to access a member variable of this structure, just like if it were a simple struct variable, so that:

   personlist[num].name

      strcpy(personlist[num].name, buffer);

      do
      {
         printf("Birthday [YYYY-MM-DD]: ");
         fflush(stdout);
         if (fgets(buffer, sizeof buffer, stdin) != NULL
             && sscanf(buffer, "%d-%d-%d", &year, &month, &day) == 3
             && year>=1000 && year<=9999
             && month>=1 && month<=12
             && day>=1 && day<=31)
         {
            ok = 1;
         }
         else
         {
            ok = 0;
            printf("Invalid birthday! Enter again...\n");
         }
      }
      while (!ok);

[*] Invalid dates, such as the 31st of February, still go undetected. If you wish to detect these cases also, keep in mind that February has 28 days except in leap years when it has 29. All years that are divisible by 4 but not by 100, unless they're also divisible by 400, are leap years.

      personlist[num].birthyear = year;
      personlist[num].birthmonth = month;
      personlist[num].birthday = day;

   printf("\nOK, thank you.\n");

   printf("\nYou entered the following data:\n");

   printf("\n%-10s%-30s%s\n", "Number", "Name", "Birthday");

   for (num=0; num<number_of_persons; num++)
   {
      printf("%-10u%-30s%04d-%02d-%02d\n",
                num,
                personlist[num].name,
                personlist[num].birthyear,
                personlist[num].birthmonth,
                personlist[num].birthday);
   }

The printf() format string aligns the data in the same way as was done in our title bar (except of course that some of the strings are replaced by numerical data). The %04d format specifier means to align the integer variable to the right in a field of 4 characters wide, and fill up at the left with 0s. The %02d format specifiers are analogous. Again, see 3.3. printf for details.

   free(personlist);

[*] While the standard guarantees that free(NULL); will work fine, you may not pass any pointers to free() other than those received from malloc(), or nasty things may happen (undefined behaviour).

Note: instead of malloc() you can also use calloc() to dynamically allocate memory. The calloc() function takes two parameters, which it multiplies to get the actual number of bytes that should be allocated [*], and initializes the allocated memory to all-bits-0 (however, this will only correctly initialize integral variables; floating-point variables are not guaranteed to be set to 0.0 and pointers are not guaranteed to be set to NULL).

[*] The result of the multiplication should not be larger than what would normally fit in either, so you can't rely on this feature to get around compiler limits (such as the 64K limit on 16-bit compilers, for example).

Note 2: you can use the realloc() function to resize an allocated block of memory while preserving its contents (see 16. Overview of the standard library). However you must watch out for these:
- the realloc() function may actually move the memory block
- if the realloc() function returns NULL, the original memory block is still allocated and unchanged

/* prog13-1.c: preproc */

#include <stdio.h>
#include <assert.h>

/* uncomment the line below for a test of the USEDUTCH macro */
/* #define USEDUTCH */

/* uncomment the line below for a test of the assert() macro */
/* #define TEST_ASSERT */

#define PROGVERSION 1

#define MAX(a,b) ((a) > (b) ? (a) : (b))

int main(void)
{
   int q = 5, r = 3;

#ifdef USEDUTCH

   printf("Dit is versie %d van het preproc programma\n", PROGVERSION);

   printf("De grootste waarde van %d en %d is %d\n", q, r, MAX(q,r));

   printf("Bestand %s, lijn %ld, compilatiedatum %s\n",
          __FILE__, (long)__LINE__, __DATE__);

#else

   printf("This is version %d of the preproc program\n", PROGVERSION);

   printf("The greatest value of %d and %d is %d\n", q, r, MAX(q,r));

   printf("File %s, line %ld, compilation date %s\n",
          __FILE__, (long)__LINE__, __DATE__);

#endif

#if defined(TEST_ASSERT)
   q++;
#endif

   assert(q==5);

   return 0;
}

This is version 1 of the preproc program
The greatest value of 5 and 3 is 5
File prog13-1.c, line 36, compilation date Aug 05 1998

Dit is versie 1 van het preproc programma
De grootste waarde van 5 en 3 is 5
Bestand prog13-1.c, lijn 27, compilatiedatum Aug 05 1998
Assertion failed: a==5, file prog13-1.c, line 44
ABNORMAL PROGRAM TERMINATION

#include <stdio.h>
#include <assert.h>

/* uncomment the line below for a test of the USEDUTCH macro */
/* #define USEDUTCH */

/* uncomment the line below for a test of the assert() macro */
/* #define TEST_ASSERT */

When the above lines are uncommented (the surrounding /* and */ removed), they will define preprocessor macros named USEDUTCH and TEST_ASSERT. In this case, these macros have only names, no corresponding values. This sort of macro is usually used to turn on or off a certain feature in a program at compile-time. In our case the USEDUTCH macro will, when defined, make the program switch to using Dutch instead of English, and the TEST_ASSERT macro will cause the assert() macro to be triggered (see below).

#define PROGVERSION 1

This sort of macro is usually used to avoid hardcoding certain "magic numbers", usually for one of these two reasons:
- using a symbolic constant makes the program clearer, e.g. PI may be more obvious than just 3.1415 and is also less likely to contain typing errors
- the value to which the macro corresponds may change (e.g. like in our example, where it is the program version) and by using a macro the value needs to be changed only in one place, instead of in a lot of places possibly spread throughout the source code

#define MAX(a,b) ((a) > (b) ? (a) : (b))

   ((a) > (b) ? (a) : (b))

This sort of macro is often used to implement a sort of "fake functions", where the code is actually inserted in the program instead of called like a function. However, there are two very important considerations here:
- watch out for precedence: safest is to put parentheses around the entire macro (in case the macro is used next to a higher precedence operator) and around every parameter (in case the actual parameter value that the macro is "called" with contains lower precedence operators), as is done in the above example.
- watch out for multiple evaluation of the parameters: in our above example the a and b parameters are evaluated twice, once in the comparison and once in the actual value returned. This may become a problem if the parameters passed to the macro do not just have values, but also side-effects, like e.g. a function call which would in this case be called twice instead of once, or the ++ or -- operators which would in this case increment or decrement the value twice instead of once [*]. If there is any risk of such problems, it's probably a good idea to make your function-like macro a real function; using a macro for optimization purposes is usually a bad idea.

[*] Actually, that isn't even guaranteed. Using operators like ++ and --, which modify the same variable twice in the same expression (and not separated by a so-called sequence point, but I'm not going to explain all that here; see question 3.8 in the c.l.c FAQ, the URL can be found in 17.2. Other interesting C-related online material) gives undefined behaviour according to the standard, which means anything may happen.

Here are some examples of what might happen if you ignore the above warnings:
- not putting parentheses around macro parameters:

#define SQR(x) (x*x)
/* SQR(a+2) yields (a+2*a+2) */

#define INC(x) (x)+1
/* INC(i)*3 yields (i)+1*3 */

#define CHECK_BOUNDS(value,min,max) ((value)>=(min) && (value)<=(max))

/* the ask_for_integer() function asks the user to enter a number
   and returns this number as an integer */
int ask_for_integer(void);

/* CHECK_BOUNDS(ask_for_integer(),1,100) will ask the user to
   enter the number twice */

#define TEXT(m) #m
TEXT(300)

In a macro value, the operator '##' may be used to concatenate a macro parameter's invocation argument with adjacent text. This can be used to generate identifiers. For example:

#define GEN_ID(a,b) a##b
int GEN_ID(i,9);

int i9;

Any macro may be undefined using the #undef preprocessor directive. For example, the following code will undefine the macro TEST if it is defined, or have no effect otherwise:

#undef TEST

#ifdef USEDUTCH

#else

#endif

The difference with a normal if statement is that this is evaluated by the preprocessor at compile-time. So while if code that may never be executed would probably still be in the executable, it will not be when a preprocessor #ifdef is used.

See below for a more advanced form of preprocessor conditionals.

   printf("This is version %d of the preproc program\n", PROGVERSION);

   printf("The greatest value of %d and %d is %d\n", q, r, MAX(q,r));

   printf("File %s, line %ld, compilation date %s\n",
          __FILE__, (long)__LINE__, __DATE__);

The first line prints the program version, as defined in our PROGVERSION macro. Since this is an integer constant (in our case 1) the %d printf format specifier is used.

The second line uses the MAX(a,b) macro. The MAX(q,r) will be replaced by:

   ((q) > (r) ? (q) : (r))

This means that the third number that is printed will always be the greatest value of the two.

The third line uses some macros that are pre-defined for you by the compiler. The __FILE__ macro expands to a string containing the current filename, the __LINE__ macro expands to a decimal constant containing the current line number in the file, and the __DATE__ macro expands to a string containing the compilation date. The __LINE__ macro is cast to a long because we use the %ld format specifier and we don't know of what type the line number constant will be (in a very long program it might be too large to fit in an integer). The following such macros are available:

__FILE__   source filename (string literal)
__LINE__   line number (decimal constant)
__DATE__   compilation date (string literal)
__TIME__   compilation time (string literal)
__STDC__   set to 1 for standard-conforming mode (decimal constant)

#if defined(TEST_ASSERT)
   q++;
#endif

#ifdef TEST_ASSERT
   q++;
#endif

The #if preprocessor directive is a lot more flexible than #ifdef. It allows for expressions combined using operators, such as e.g.:

#if defined(MYCOMPILER_VERSION) && (MYCOMPILER_VERSION>=2)
   /* some code specific to MYCOMPILER versions greater than 2 */
#endif

You can only use things that are known at preprocessing-time in an #if statement. For example, you can't check for a typedef using #if defined(mytypedef) and you can't check for certain sizes using something like #if sizeof(int)>=4. As an alternative for the latter, you can check the value of e.g. UINT_MAX from limits.h.

There's also the #elif preprocessor directive, which works similar to an else if () construct.

The #error directive can be used to force a diagnostic message from the compiler. The #pragma directive can be used to control compiler specific features. The #line directive can be used to change the current line number value. See your compiler manual / online help if you want to know more details.

13.3. Using the assert() macro

   assert(q==5);

What the assert() macro does depends on whether the NDEBUG macro is defined when assert.h is included or not. If the NDEBUG (no debugging) macro is defined at that time, the assert() macro will do nothing (this is intended for release code, to get rid of unnecessary debugging code).

If the NDEBUG macro isn't defined when assert.h is included, the assert() macro checks the condition that is passed to it as parameter. If this condition is true, nothing happens. If this condition is false, however, the program prints an error message containing the source file, line number and failed condition, and aborts the program abnormally.

Obviously this is not very elegant, but it is only intended for debugging purposes. The conditions you check with it should be conditions that absolutely have to be fulfilled, unless some serious error has occurred in the program's internal logic. It should never be used to trap errors that are caused by external factors such as user input or not-enough-memory errors etc.

In our example, the assert() macro makes sure the q variable equals 5. It should, because we assigned that value to it in its definition. However, when the TEST_ASSERT macro is defined some code above has incremented the value of q by 1, so that it no longer equals 5 but 6, and this will of course trigger the assert() macro.

/* prog14-1.c: vararg */

#include <stdio.h>
#include <stdarg.h>

int sumintegers(int numbers, ...)
{
   va_list vl;
   int i;
   int sum;

   va_start(vl,numbers);

   sum = 0;
   for (i=0; i<numbers; i++)
      sum += va_arg(vl,int);

   va_end(vl);

   return sum;
}

int main(void)
{
   int a,b;

   printf("Sum #1 = %d\n",
          sumintegers(10,1,2,3,5,7,9,11,13,17,19));

   a = 100;
   b = 200;

   printf("Sum #2 = %d\n",
          sumintegers(2,a,b));

   return 0;
}

Sum #1 = 87
Sum #2 = 300

#include <stdarg.h>

int sumintegers(int numbers, ...)
{
}

   va_list vl;
   int i;
   int sum;

   va_start(vl,numbers);

   sum = 0;
   for (i=0; i<numbers; i++)
      sum += va_arg(vl,int);

We use the fixed numbers parameter here to determine how many variable arguments there are. Another commonly used method is to use some sort of "terminator" value, e.g. the value 0 would end the list. However, keep in mind that at least 1 fixed parameter is required.

   va_end(vl);

   return sum;

   int a,b;

   printf("Sum #1 = %d\n",
          sumintegers(10,1,2,3,5,7,9,11,13,17,19));

   a = 100;
   b = 200;

   printf("Sum #2 = %d\n",
          sumintegers(2,a,b));

/* prog14-2.c: myprintf */

#include <stdio.h>
#include <stdarg.h>

void myprintf(const char *text, const char *fmt, ...)
{
   va_list vl;

   printf("myprintf(): %s: ", text);

   va_start(vl,fmt);
   vprintf(fmt,vl);
   va_end(vl);

   printf("\n");
}

int main(void)
{
   int a = 5;

   myprintf("Test #1", "a = %d", a);

   myprintf("Test #2", "File name %s, line number %ld",
                       __FILE__, (long)__LINE__);

   return 0;
}

myprintf(): Test #1: a = 5
myprintf(): Test #2: File name prog14-2.c, line number 26

Sometimes it may be useful to encapsulate the printf() function in a function of your own, so that you can add some text of your own, or write a copy of the text to a logfile, etc. That's what the above program does.

#include <stdarg.h>

void myprintf(const char *text, const char *fmt, ...)
{
}

   va_list vl;

   printf("myprintf(): %s: ", text);

   va_start(vl,fmt);

   vprintf(fmt,vl);

   va_end(vl);

   printf("\n");

   int a = 5;

   myprintf("Test #1", "a = %d", a);

   myprintf("Test #2", "File name %s, line number %ld",
                       __FILE__, (long)__LINE__);

/* prog15-1.c: module 1 */

#include <stdio.h>

#include "prog15-2.h"

int main(void)
{
   myfunction(25);

   printf("This is %s. The value of myvariable is %d\n",
          __FILE__, myvariable);

   return 0;
}

/* prog15-2.c: module 2 */

#include <stdio.h>

int myvariable = 42;

void myfunction(int number)
{
   printf("This is %s. The sum of number and myvariable is %d.\n",
          __FILE__, number+myvariable);
}

/* prog15-2.h: module 2 header file */

extern int myvariable;

void myfunction(int number);

This is prog15-2.c. The sum of number and myvariable is 67.
This is prog15-1.c. The value of myvariable is 42

By splitting up your program in separate modules, each combining the functions that are related to one specific task, the program will become much easier to maintain and only those modules where something has changed need to be recompiled.

Let's start by analyzing the prog15-1.c module:

#include "prog15-2.h"

int main(void)
{
   myfunction(25);

   printf("This is %s. The value of myvariable is %d\n",
          __FILE__, myvariable);

   return 0;
}

int myvariable = 42;

void myfunction(int number)
{
   printf("This is %s. The sum of number and myvariable is %d.\n",
          __FILE__, number+myvariable);
}

Similarly, since the myfunction() is not defined as static, it can also be accessed from all modules. If you don't want this, you should define it like this:

static void myfunction(int number)
{
}

extern int myvariable;

void myfunction(int number);

The second line looks like the definition of the myfunction() function. The only difference is that where normally the function definition would be between { and }, there's now a semicolon. This is called a prototype. Similar to the above case, it is like saying "you can assume this function is there and that it takes these parameters". In fact, we could also have written:

extern void myfunction(int number);

Apart from variable and function declarations (externs and prototypes), a header file is also often used to define macros, typedefs, enums, structs and unions. However, it should not be used for variable or function definitions, because this way the variable resp. function would be defined in every module where the header is included, and this will cause linker errors (unless they are defined as static, but even then it's usually a bad idea).

This overview is sorted on a strictly alphabetical basis (case and underscores are ignored).

All the library functions may be implemented as macros. If you really need a function version (for example, if the argument has side effects), you should #undef the macro first (see 13. Preprocessor macros/conditionals).

All the identifiers (variable and function names etc.) that are defined in the standard library are reserved, which means that you shouldn't use them in your own programs. Identifiers that start with an underscore are reserved in most contexts as well. [*]

[*] An exhaustive discussion of which identifiers are reserved in which contexts falls outside the scope of an introductory document about C programming. More information can be found in: 17.2. Other interesting C-related online material

In addition, the following identifiers are reserved for possible extensions to the library:

Macros:
- Macros that start with E followed by a digit or uppercase letter
- Macros that start with LC_ followed by an uppercase letter
- Macros that start with SIG or SIG_ followed by an uppercase letter
Function names:
- Function names that start with is or to followed by a lowercase letter
- Function names that start with str, mem or wcs followed by a lowercase
  letter
- The function names declared in math.h with the suffix f or l

The following header files that have been added to the original ANSI/ISO standard by normative addenda etc. or the new C99 standard are not included here: (your compiler may not support them yet, either)

complex.h  complex arithmetic
fenv.h     floating-point environment
inttypes.h integer types
iso646.h   alternative spellings for operators
stdbool.h  standard boolean type
tgmath.h   type-generic mathematics
wchar.h    wide-character utilities
wctype.h   wide-character classification

void assert(int expression);

Functions

int isalnum(int c);

int isalpha(int c);

int iscntrl(int c);

int isdigit(int c);

int isgraph(int c);

int islower(int c);

int isprint(int c);

int ispunct(int c);

int isspace(int c);

int isupper(int c);

int isxdigit(int c);

int tolower(int c);

int toupper(int c);

EDOM                          /* domain error */
ERANGE                        /* range error */

errno

DBL_DIG

DBL_EPSILON

DBL_MANT_DIG

DBL_MAX

DBL_MAX_EXP

DBL_MAX_10_EXP

DBL_MIN

DBL_MIN_EXP

DBL_MIN_10_EXP

FLT_DIG

FLT_EPSILON

FLT_MANT_DIG

FLT_MAX

FLT_MAX_EXP

FLT_MAX_10_EXP

FLT_MIN

FLT_MIN_EXP

FLT_MIN_10_EXP

FLT_RADIX

LDBL_DIG

LDBL_EPSILON

LDBL_MANT_DIG

LDBL_MAX

LDBL_MAX_EXP

LDBL_MAX_10_EXP

LDBL_MIN

LDBL_MIN_EXP

LDBL_MIN_10_EXP

CHAR_BIT

CHAR_MAX

CHAR_MIN

INT_MAX

INT_MIN

LONG_MAX

LONG_MIN

MB_LEN_MAX

SCHAR_MAX

SCHAR_MIN

SHRT_MAX

SHRT_MIN

UCHAR_MAX

UINT_MAX

ULONG_MAX

USHRT_MAX

struct lconv {
   char *decimal_point;       /* decimal point character ["."] */
   char *thousands_sep;       /* digit group separating character [""] */
   char *grouping;            /* size of digit groups [""] */
   char *int_curr_symbol;     /* international currency symbol [""] */
   char *currency_symbol;     /* local currency symbol [""] */
   char *mon_decimal_point;   /* monetary decimal point [""] */
   char *mon_thousands_sep;   /* monetary digit group separator [""] */
   char *mon_grouping;        /* monetary digit group size [""] */
   char *positive_sign;       /* monetary nonnegative sign [""] */
   char *negative_sign;       /* monetary negative sign [""] */
   char int_frac_digits;      /* int. monetary decimal digits [CHAR_MAX] */
   char frac_digits;          /* monetary decimal digits [CHAR_MAX] */
   char p_cs_precedes;        /* 1 if currency symbol precedes nonnegative
                                 value [CHAR_MAX] */
   char p_sep_by_space;       /* 1 if currency symbol is separated by space
                                 from nonnegative value [CHAR_MAX] */
   char n_cs_precedes;        /* 1 if currency symbol precedes negative
                                 value [CHAR_MAX] */
   char n_sep_by_space;       /* 1 if currency symbol is separated by space
                                 from negative value [CHAR_MAX] */
   char p_sign_posn;          /* indicates positioning of positive sign
                                 for nonnegative values [CHAR_MAX] */
   char n_sign_posn;          /* indicates positioning of negative sign
                                 for negative values [CHAR_MAX] */
  };

[*] The order of the members may be different

Macros

LC_ALL                        /* all categories */
LC_COLLATE                    /* strcoll() and strxfrm() */
LC_CTYPE                      /* character handling */
LC_MONETARY                   /* localeconv() monetary formatting */
LC_NUMERIC                    /* decimal point */
LC_TIME                       /* strftime() */

NULL

Functions

char *setlocale(int category, const char *locale);

struct lconv *localeconv(void);

The structure may not be modified. Subsequent calls to the localeconv() function may overwrite its contents.

16.8. math.h (mathematics)

HUGE_VAL

Functions

double acos(double x);

double asin(double x);

double atan(double x);

double atan2(double y, double x);

double ceil(double x);

double cos(double x);

double cosh(double x);

double exp(double x);

double fabs(double x);

double floor(double x);

double fmod(double x, double y);

double frexp(double value, int *exp);

double ldexp(double x, int exp);

double log(double x);

double log10(double x);

double modf(double value, double *iptr);

double pow(double x, double y);

double sin(double x);

double sinh(double x);

double sqrt(double x);

double tan(double x);

double tanh(double x);

jmp_buf

Macros

int setjmp(jmp_buf env);

The setjmp() macro may only be used as an expression on its own, or compared with an integral constant, or the logical ! operator.

Functions

void longjmp(jmp_buf env, int val);

sig_atomic_t

Macros

SIGABRT                       /* abnormal program termination */
SIGFPE                        /* arithmetic error */
SIGILL                        /* illegal instruction */
SIGINT                        /* interactive attention signal */
SIGSEGV                       /* invalid access to storage */
SIGTERM                       /* termination request received */

SIG_DFL                       /* default handling */
SIG_IGN                       /* ignore signal */

SIG_ERR

Functions

void (*signal(int sig, void (*func)(int)))(int);

The signal handler must be a function returning void and taking one parameter of type int, the signal number. It may terminate by means of a return statement (unless the signal occurring was SIGFPE or another form of exception) or a call to abort(), exit() or longjmp(). Unless the signal was invoked by the raise() or abort() function, the signal handler may not use any other standard library functions or access any static data other than assigning a value to a static variable of type volatile sig_atomic_t.

If the request is successful, the signal() function will return the address of the previous signal handler for this signal. Otherwise it will return SIG_ERR and set errno.

int raise(int sig);

Types

va_list

Macros

void va_start(va_list ap,  parmN);

type va_arg(va_list ap,  type);

void va_end(va_list ap);

ptrdiff_t

size_t

wchar_t

Macros

NULL

offsetof(type,  member-designator)

FILE

fpos_t

size_t

Macros

BUFSIZ

EOF

FOPEN_MAX

FILENAME_MAX

_IOFBF                        /* full buffering */
_IOLBF                        /* line buffering */
_IONBF                        /* no buffering */

L_tmpnam

NULL

SEEK_CUR                      /* seek from current position */
SEEK_END                      /* seek from end of file */
SEEK_SET                      /* seek from beginning of file */

stderr
stdin
stdout

TMP_MAX

Functions

void clearerr(FILE *stream);

int fclose(FILE *stream);

int feof(FILE *stream);

[*] This is different from the way EOF works in some other languages, where it can be used to check if end-of-file has been reached.

int ferror(FILE *stream);

int fflush(FILE *stream);

int fgetc(FILE *stream);

int fgetpos(FILE *stream, fpos_t *pos);

char *fgets(char *s, int n, FILE *stream);

See also 11.2. Using disk files.

FILE *fopen(const char *filename, const char *mode);

int fprintf(FILE *stream, const char *format, ...);

int fputc(int c, FILE *stream);

int fputs(const char *s, FILE *stream);

size_t fread(void *ptr, size_t size, size_t nmemb,
             FILE *stream);

[*] The result of the multiplication size * nmemb should fit in a size_t, so you can't rely on this feature to get around compiler limits (such as the 64K limit on 16-bit compilers, for example).

FILE *freopen(const char *filename, const char *mode,
              FILE *stream);

int fscanf(FILE *stream, const char *format, ...);

int fseek(FILE *stream, long int offset, int whence);

int fsetpos(FILE *stream, const fpos_t *pos);

long int ftell(FILE *stream);

size_t fwrite(const void *ptr, size_t size, size_t nmemb,
              FILE *stream);

[*] The result of the multiplication size * nmemb should fit in a size_t, so you can't rely on this feature to get around compiler limits (such as the 64K limit on 16-bit compilers, for example).

int getc(FILE *stream);

int getchar(void);

char *gets(char *s);

WARNING: do not use this function; it does not provide any method of limiting the input to fit inside the array bounds.

void perror(const char *s);

int printf(const char *format, ...);

int putc(int c, FILE *stream);

int putchar(int c);

int puts(const char *s);

int remove(const char *filename);

int rename(const char *old, const char *new);

void rewind(FILE *stream);

int scanf(const char *format, ...);

void setbuf(FILE *stream, char *buf);

int setvbuf(FILE *stream, char *buf, int mode, size_t size);

int sprintf(char *s, const char *format, ...);

int sscanf(const char *s, const char *format, ...);

FILE *tmpfile(void);

char *tmpnam(char *s);

int ungetc(int c, FILE *stream);

int vfprintf(FILE *stream, const char *format, va_list arg);

int vprintf(const char *format, va_list arg);

int vsprintf(char *s, const char *format, va_list arg);

typedef struct {
   int quot;                  /* quotient */
   int rem;                   /* remainder */
  } div_t;

typedef struct {
   long quot;                 /* quotient */
   long rem;                  /* remainder */
  } ldiv_t;

[*] The order of the members may be different

size_t

wchar_t

Macros

EXIT_FAILURE                  /* unsuccessful termination status */
EXIT_SUCCESS                  /* successful termination status */

MB_CUR_MAX

NULL

RAND_MAX

Functions

void abort(void);

int abs(int j);

int atexit(void (*func)(void));

double atof(const char *nptr);

int atoi(const char *nptr);

long int atol(const char *nptr);

void *bsearch(const void *key, const void *base,
         size_t nmemb, size_t size,
         int (*compar)(const void *, const void *));

void *calloc(size_t nmemb, size_t size);

div_t div(int numer, int denom);

void exit(int status);

void free(void *ptr);

char *getenv(const char *name);

long int labs(long int j);

ldiv_t ldiv(long int numer, long int denom);

void *malloc(size_t size);

int mblen(const char *s, size_t n);

size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);

int mbtowc(wchar_t *pwc, const char *s, size_t n);

int rand(void);

void *realloc(void *ptr, size_t size);

void srand(unsigned int seed);

double strtod(const char *nptr, char **endptr);

long int strtol(const char *nptr, char **endptr, int base);

unsigned long int strtoul(const char *nptr, char **endptr,
                          int base);

int system(const char *string);

void qsort(void *base, size_t nmemb, size_t size,
         int (*compar)(const void *, const void *));

size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);

int wctomb(char *s, wchar_t wchar);

size_t

Macros

NULL

Functions

void *memchr(const void *s, int c, size_t n);

int memcmp(const void *s1, const void *s2, size_t n);

void *memcpy(void *s1, const void *s2, size_t n);

void *memmove(void *s1, const void *s2, size_t n);

void *memset(void *s, int c, size_t n);

char *strcat(char *s1, const char *s2);

char *strchr(const char *s, int c);

int strcmp(const char *s1, const char *s2);

int strcoll(const char *s1, const char *s2);

char *strcpy(char *s1, const char *s2);

size_t strcspn(const char *s1, const char *s2);

char *strerror(int errnum);

size_t strlen(const char *s);

char *strncat(char *s1, const char *s2, size_t n);

int strncmp(const char *s1, const char *s2, size_t n);

char *strncpy(char *s1, const char *s2, size_t n);

char *strpbrk(const char *s1, const char *s2);

char *strrchr(const char *s, int c);

size_t strspn(const char *s1, const char *s2);

char *strstr(const char *s1, const char *s2);

char *strtok(char *s1, const char *s2);

size_t strxfrm(char *s1, const char *s2, size_t n);

clock_t

size_t

time_t

struct tm {
   int tm_sec;                /*  seconds after the minute [0..60] */
   int tm_min;                /*  minutes after the hour [0..59] */
   int tm_hour;               /*  hours since midnight [0..23] */
   int tm_mday;               /*  day of the month [1..31] */
   int tm_mon;                /*  months since January [0..11] */
   int tm_year;               /*  years since 1900 */
   int tm_wday;               /*  days since Sunday [0..6] */
   int tm_yday;               /*  days since January 1 [0..365] */
   int tm_isdst;              /*  daylight saving time flag */
  };

Macros

CLOCKS_PER_SEC

NULL

Functions

char *asctime(const struct tm *timeptr);

   Sun Sep 16 01:03:52 1973\n\0

   Sun, Mon, Tue, Wed, Thu, Fri, Sat

   Jan, Feb, Mar, Apr, May, Jun,
   Jul, Aug, Sep, Oct, Nov, Dec

clock_t clock(void);

char *ctime(const time_t *timer);

double difftime(time_t time1, time_t time0);

struct tm *gmtime(const time_t *timer);

struct tm *localtime(const time_t *timer);

time_t mktime(struct tm *timeptr);

size_t strftime(char *s, size_t maxsize,
                const char *format, const struct tm *timeptr);

%a  locale's abbreviated weekday name
%A  locale's full weekday name
%b  locale's abbreviated month name
%B  locale's full month name
%c  locale's appropriate date and time representation
%d  day of the month as a decimal number [01..31]
%H  hour (24-hour clock) as a decimal number [00..23]
%I  hour (12-hour clock) as a decimal number [01..12]
%j  day of the year as a decimal number [001..366]
%m  month as a decimal number [01..12]
%M  minute as a decimal number [00..59]
%p  locale's equivalent of AM/PM
%S  second as a decimal number [00..60]
%U  week number of the year (the first Sunday as the first day
    of week 1) as a decimal number [00..53]
%w  weekday (where Sunday is 0) as a decimal number [0..6]
%W  week number of the year (the first Monday as the first day
    of week 1) as a decimal number [00..53]
%x  locale's appropriate date representation
%X  locale's appropriate time representation
%y  last 2 digits of the year as a decimal number [00..99]
%Y  whole year as a decimal number (e.g. 1998)
%Z  timezone name or abbreviation, or no characters if the
    timezone can't be determined

time_t time(time_t *timer);

Nick Austin
Aaron Crane
Dann Corbit
Lawrence Kirby
Bernd Luevelsmeyer
Tom Nolette
Sunil Rao
Robin Sheppard
Jan Schuhr
David Tait
George White

The comp.lang.c answers to frequently asked questions:

http://www.eskimo.com/~scs/C-faq/top.html

Bob Stout's Snippets collection:

http://www.snippets.org/

Dinkumware's C reference:

http://www.dinkumware.com/refxc.html

Overview of reserved identifiers:

http://www.mindspring.com/~brahms/c-predef.htm

Free C/C++ interpreter:

http://www.softintegration.com/

Links to other C resources:

http://www.lysator.liu.se/c/