C.2.1 C Program Dissection

In general, a C program is organized into one or more functions. Every program must include the main function, which is where the program starts executing. Most programs use other functions defined elsewhere in the C code and/or in a library. The overall sections of the hello.c program are the header, the main function, and the body.

C.2.2 Running a C Program

C programs can be run on many different machines. This portability is another advantage of C. The program is first compiled on the desired machine using the C compiler. Slightly different versions of the C compiler exist, including cc (C compiler), or gcc (GNU C compiler). Here we show how to compile and run a C program using gcc, which is freely available for download. It runs directly on Linux machines and is accessible under the Cygwin environment on Windows machines. It is also available for many embedded systems such as Microchip PIC32 microcontrollers. The general process described below of C file creation, compilation, and execution is the same for any C program.

C.3.1 Comments

Programmers use comments to describe code at a high-level and clarify code function. Anyone who has read uncommented code can attest to their importance. C programs use two types of comments: Single-line comments begin with // and terminate at the end of the line; multiple-line comments begin with /* and end with */. While comments are critical to the organization and clarity of a program, they are ignored by the compiler.

// This is an example of a one-line comment.

/* This is an example

  of a multi-line comment. */

A comment at the top of each C file is useful to describe the file’s author, creation and modification dates, and purpose. The comment below could be included at the top of the hello.c file.

// hello.c

// 1 June 2012 [email protected], [email protected]

//

// This program prints "Hello world!" to the screen

C.3.2 #define

Constants are named using the #define directive and then used by name throughout the program. These globally defined constants are also called macros. For example, suppose you write a program that allows at most 5 user guesses, you can use #define to identify that number.

#define MAXGUESSES 5

The # indicates that this line in the program will be handled by the preprocessor. Before compilation, the preprocessor replaces each occurrence of the identifier MAXGUESSES in the program with 5. By convention, #define lines are located at the top of the file and identifiers are written in all capital letters. By defining constants in one location and then using the identifier in the program, the program remains consistent, and the value is easily modified – it need only be changed at the #define line instead of at each line in the code where the value is needed.

C Code Example C.2 shows how to use the #define directive to convert inches to centimeters. The variables inch and cm are declared to be float to indicate they represent single-precision floating point numbers. If the conversion factor (INCH2CM) were used throughout a large program, having it declared using #define obviates errors due to typos (for example, typing 2.53 instead of 2.54) and makes it easy to find and change (for example, if more significant digits were required).

C.3.3 #include

Modularity encourages us to split programs across separate files and functions. Commonly used functions can be grouped together for easy reuse. Variable declarations, defined values, and function definitions located in a header file can be used by another file by adding the #include preprocesser directive. Standard libraries that provide commonly used functions are accessed in this way. For example, the following line is required to use the functions defined in the standard input/output (I/O) library, such as printf.

#include <stdio.h>

The “.h” postfix of the include file indicates it is a header file. While #include directives can be placed anywhere in the file before the included functions, variables, or identifiers are needed, they are conventionally located at the top of a C file.

Programmer-created header files can also be included by using quotation marks (" ") around the file name instead of brackets (< >). For example, a user-created header file called myfunctions.h would be included using the following line.

#include "myfunctions.h"

At compile time, files specified in brackets are searched for in system directories. Files specified in quotes are searched for in the same local directory where the C file is found. If the user-created header file is located in a different directory, the path of the file relative to the current directory must be included.

C.4.1 Primitive Data Types

C has a number of primitive, or built-in, data types available. They can be broadly characterized as integers, floating-point variables, and characters. An integer represents a 2’s complement or unsigned number within a finite range. A floating-point variable uses IEEE floating point representation to describe real numbers with a finite range and precision. A character can be viewed as either an ASCII value or an 8-bit integer.¹ Table C.2 lists the size and range of each primitive type. Integers may be 16, 32, or 64 bits. They use 2’s complement unless qualified as unsigned. The size of the int type is machine dependent and is generally the native word size of the machine. For example, on a 32-bit MIPS processor, the size of int or unsigned int is 32 bits. Floating point numbers may be 32- or 64-bit single or double precision. Characters are 8 bits.

Table C.2 Primitive data types and sizes

C Code Example C.3 shows the declaration of variables of different types. As shown in Figure C.2, x requires one byte of data, y requires two, and z requires four. The program decides where these bytes are stored in memory, but each type always requires the same amount of data. For illustration, the addresses of x, y, and z in this example are 1, 2, and 4. Variable names are case-sensitive, so, for example, the variable x and the variable X are two different variables. (But it would be very confusing to use both in the same program!)

C.4.2 Global and Local Variables

Global and local variables differ in where they are declared and where they are visible. A global variable is declared outside of all functions, typically at the top of a program, and can be accessed by all functions. Global variables should be used sparingly because they violate the principle of modularity, making large programs more difficult to read. However, a variable accessed by many functions can be made global.

A local variable is declared inside a function and can only be used by that function. Therefore, two functions can have local variables with the same names without interfering with each other. Local variables are declared at the beginning of a function. They cease to exist when the function ends and are recreated when the function is called again. They do not retain their value from one invocation of a function to the next.

C Code Examples C.4 and C.5 compare programs using global versus local variables. In C Code Example C.4, the global variable max can be accessed by any function. Using a local variable, as shown in C Code Example C.5, is the preferred style because it preserves the well-defined interface of modularity.

C.4.3 Initializing Variables

A variable needs to be initialized – assigned a value – before it is read. When a variable is declared, the correct number of bytes is reserved for that variable in memory. However, the memory at those locations retains whatever value it had last time it was used, essentially a random value. Global and local variables can be initialized either when they are declared or within the body of the program. C Code Example C.3 shows variables initialized at the same time they are declared. C Code Example C.4 shows how variables are initialized before their use, but after declaration; the global variable max is initialized by the getMax function before it is read by the printMax function. Reading from uninitialized variables is a common programming error, and can be tricky to debug.

C.7.1 Conditional Statements

if, if/else, and switch/case statements are conditional statements commonly used in high-level languages including C.

C.7.2 Loops

while, do/while, and for loops are common loop constructs used in many high-level languages including C. These loops repeatedly execute a statement as long as a condition is satisfied.

C.8.1 Pointers

A pointer is the address of a variable. C Code Example C.18 shows how to use pointers. salary1 and salary2 are variables that can contain integers, and ptr is a variable that can hold the address of an integer. The compiler will assign arbitrary locations in RAM for these variables depending on the runtime environment. For the sake of concreteness, suppose this program is compiled on a 32-bit system with salary1 at addresses 0x70-73, salary2 at addresses 0x74-77, and ptr at 0x78-7B. Figure C.3 shows memory and its contents after the program is executed.

In a variable declaration, a star (*) before a variable name indicates that the variable is a pointer to the declared type. In using a pointer variable, the * operator dereferences a pointer, returning the value stored at the indicated memory address contained in the pointer. The & operator is pronounced “address of,” and it produces the memory address of the variable being referenced.

Pointers are particularly useful when a function needs to modify a variable, instead of just returning a value. Because functions can’t modify their inputs directly, a function can make the input a pointer to the variable. This is called passing an input variable by reference instead of by value, as shown in prior examples. C Code Example C.19 gives an example of passing x by reference so that quadruple can modify the variable directly.

A pointer to address 0 is called a null pointer and indicates that the pointer is not actually pointing to meaningful data. It is written as NULL in a program.

C.8.2 Arrays

An array is a group of similar variables stored in consecutive addresses in memory. The elements are numbered from 0 to N−1, where N is the size of the array. C Code Example C.20 declares an array variable called scores that holds the final exam scores for three students. Memory space is reserved for three longs, that is, 3 × 4 = 12 bytes. Suppose the scores array starts at address 0x40. The address of the 1^st element (i.e., scores[0]) is 0x40, the 2^nd element is 0x44, and the 3^rd element is 0x48, as shown in Figure C.4. In C, the array variable, in this case scores, is a pointer to the 1^st element. It is the programmer’s responsibility not to access elements beyond the end of the array. C has no internal bounds checking, so a program that writes beyond the end of an array will compile fine but may stomp on other parts of memory when it runs.

The elements of an array can be initialized either at declaration using curly braces {}, as shown in C Code Example C.21, or individually in the body of the code, as shown in C Code Example C.22. Each element of an array is accessed using brackets []. The contents of memory containing the array are shown in Figure C.4. Array initialization using curly braces {} can only be performed at declaration, and not afterward. for loops are commonly used to assign and read array data, as shown in C Code Example C.23.

When an array is declared, the length must be constant so that the compiler can allocate the proper amount of memory. However, when the array is passed to a function as an input argument, the length need not be defined because the function only needs to know the address of the beginning of the array. C Code Example C.24 shows how an array is passed to a function. The input argument arr is simply the address of the 1^st element of an array. Often the number of elements in an array is also passed as an input argument. In a function, an input argument of type int[] indicates that it is an array of integers. Arrays of any type may be passed to a function.

An array argument is equivalent to a pointer to the beginning of the array. Thus, getMean could also have been declared as

float getMean(int *arr, int len);

Although functionally equivalent, datatype[] is the preferred method for passing arrays as input arguments because it more clearly indicates that the argument is an array.

A function is limited to a single output, i.e., return variable. However, by receiving an array as an input argument, a function can essentially output more than a single value by changing the array itself. C Code Example C.25 sorts an array from lowest to highest and leaves the result in the same array. The three function prototypes below are equivalent. The length of an array in a function declaration is ignored.

void sort(int *vals, int len);

void sort(int vals[], int len);

void sort(int vals[100], int len);

Arrays may have multiple dimensions. C Code Example C.26 uses a two-dimensional array to store the grades across eight problem sets for ten students. Recall that initialization of array values using {} is only allowed at declaration.

C Code Example C.27 shows some functions that operate on the 2-D grades array from C Code Example C.26. Multi-dimensional arrays used as input arguments to a function must define all but the first dimension. Thus, the following two function prototypes are acceptable:

void print2dArray(int arr[10][8]);

void print2dArray(int arr[][8]);

Note that because an array is represented by a pointer to the initial element, C cannot copy or compare arrays using the = or == operators. Instead, you must use a loop to copy or compare each element one at a time.

C.8.3 Characters

A character (char) is an 8-bit variable. It can be viewed either as a 2’s complement number between −128 and 127 or as an ASCII code for a letter, digit, or symbol. ASCII characters can be specified as a numeric value (in decimal, hexadecimal, etc.) or as a printable character enclosed in single quotes. For example, the letter A has the ASCII code 0x41, B=0x42, etc. Thus ‘A’ + 3 is 0x44, or ‘D’. Table 6.2 on page 323 lists the ASCII character encodings, and Table C.4 lists characters used to indicate formatting or special characters. Formatting codes include carriage return ( ), newline ( ), horizontal tab ( ), and the end of a string (). is shown for completeness but is rarely used in C programs. returns the carriage (location of typing) to the beginning (left) of the line, but any text that was there is overwritten. , instead, moves the location of typing to the beginning of a new line.² The NULL character (‘’) indicates the end of a text string and is discussed next in Section C.8.4.

Table C.4 Special characters

C.8.4 Strings

A string is an array of characters used to store a piece of text of bounded but variable length. Each character is a byte representing the ASCII code for that letter, number, or symbol. The size of the array determines the maximum length of the string, but the actual length of the string could be shorter. In C, the length of the string is determined by looking for the null terminator (ASCII value 0x00) at the end of the string.

C Code Example C.28 shows the declaration of a 10-element character array called greeting that holds the string "Hello!". For concreteness, suppose greeting starts at memory address 0x50. Figure C.5 shows the contents of memory from 0x50 to 0x59 holding the string "Hello!" Note that the string only uses the first seven elements of the array, even though ten elements are allocated in memory.

C Code Example C.29 shows an alternate declaration of the string greeting. The pointer greeting, holds the address of the 1^st element of a 7-element array comprised of each of the characters in “Hello!” followed by the null terminator. The code also demonstrates how to print strings by using the %s format code.

Unlike primitive variables, a string cannot be set equal to another string using the equals operator, =. Each element of the character array must be individually copied from the source string to the target string. This is true for any array. C Code Example C.30 copies one string, src, to another, dst. The sizes of the arrays are not needed, because the end of the src string is indicated by the null terminator. However, dst must be large enough so that you don’t stomp on other data. strcpy and other string manipulation functions are available in C’s built-in libraries (see Section C.9.4).

C.8.5 Structures

In C, structures are used to store a collection of data of various types. The general format of a structure declaration is

struct name {

  type1 element1;

  type2 element2;

  …

};

where struct is a keyword indicating that it is a structure, name is the structure tag name, and element1 and element2 are members of the structure. A structure may have any number of members. C Code Example C.31 shows how to use a structure to store contact information. The program then declares a variable c1 of type struct contact.

Just like built-in C types, you can create arrays of structures and pointers to structures. C Code Example C.32 creates an array of contacts.

It is common to use pointers to structures. C provides the member access operator -> to dereference a pointer to a structure and access a member of the structure. C Code Example C.33 shows an example of declaring a pointer to a struct contact, assigning it to point to the 42^nd element of classlist from C Code Example C.32, and using the member access operator to set a value in that element.

Structures can be passed as function inputs or outputs by value or by reference. Passing by value requires the compiler to copy the entire structure into memory for the function to access. This can require a large amount of memory and time for a big structure. Passing by reference involves passing a pointer to the structure, which is more efficient. The function can also modify the structure being pointed to rather than having to return another structure. C Code Example C.34 shows two versions of the stretch function that makes a contact 2 cm taller. stretchByReference avoids copying the large structure twice.

C.8.6 * typedef

C also allows you to define your own names for data types using the typedef statement. For example, writing struct contact becomes tedious when it is often used, so we can define a new type named contact and use it as shown in C Code Example C.35.

typedef can be used to create a new type occupying the same amount of memory as a primitive type. C Code Example C.36 defines byte and bool as 8-bit types. The byte type may make it clearer that the purpose of pos is to be an 8-bit number rather than an ASCII character. The bool type indicates that the 8-bit number is representing TRUE or FALSE. These types make a program easier to read than if one simply used char everywhere.

C Code Example C.37 illustrates defining a 3-element vector and a 3 × 3 matrix type using arrays.

C.8.7 * Dynamic Memory Allocation

In all the examples thus far, variables have been declared statically; that is, their size is known at compile time. This can be problematic for arrays and strings of variable size because the array must be declared large enough to accommodate the largest size the program will ever see. An alternative is to dynamically allocate memory at run time when the actual size is known.

The malloc function from stdlib.h allocates a block of memory of a specified size and returns a pointer to it. If not enough memory is available, it returns a NULL pointer instead. For example, the following code allocates 10 shorts (10 × 2 = 20 bytes). The sizeof operator returns the size of a type or variable in bytes.

// dynamically allocate 20 bytes of memory

short *data = malloc(10*sizeof(short));

C Code Example C.38 illustrates dynamic allocation and de-allocation. The program accepts a variable number of inputs, stores them in a dynamically allocated array, and computes their average. The amount of memory necessary depends on the number of elements in the array and the size of each element. For example, if an int is a 4-byte variable and 10 elements are needed, 40 bytes are dynamically allocated. The free function de-allocates the memory so that it could later be used for other purposes. Failing to de-allocate dynamically allocated data is called a memory leak and should be avoided.

C.8.8 * Linked Lists

A linked list is a common data structure used to store a variable number of elements. Each element in the list is a structure containing one or more data fields and a link to the next element. The first element in the list is called the head. Linked lists illustrate many of the concepts of structures, pointers, and dynamic memory allocation.

C Code Example C.39 describes a linked list for storing computer user accounts to accommodate a variable number of users. Each user has a user name, a password, a unique user identification number (UID), and a field indicating whether they have administrator privileges. Each element of the list is of type userL, containing all of this user information along with a link to the next element in the list. A pointer to the head of the list is stored in a global variable called users, and is initially set to NULL to indicate that there are no users.

The program defines functions to insert, delete, and find a user and to count the number of users. The insertUser function allocates space for a new list element and adds it to the head of the list. The deleteUser function scans through the list until the specified UID is found and then removes that element, adjusting the link from the previous element to skip the deleted element and freeing the memory occupied by the deleted element. The findUser function scans through the list until the specified UID is found and returns a pointer to that element, or NULL if the UID is not found. The numUsers function counts the number of elements in the list.

C.9.1 stdio

The standard input/output library stdio.h contains commands for printing to a console, reading keyboard input, and reading and writing files. To use these functions, the library must be included at the top of the C file:

#include <stdio.h>

C.9.2 stdlib

The standard library stdlib.h provides general purpose functions including random number generation (rand and srand), dynamic memory allocation (malloc and free, already discussed in Section C.8.8), exiting the program early (exit), and number format conversions. To use these functions, add the following line at the top of the C file.

#include <stdlib.h>

C.9.3 math

The math library math.h provides commonly used math functions such as trigonometry functions, square root, and logs. C Code Example C.49 shows how to use some of these functions. To use math functions, place the following line in the C file:

#include <math.h>

C.9.4 string

The string library string.h provides commonly used string manipulation functions. Key functions include:

// copy src into dst and return dst

char *strcpy(char *dst, char *src);

// concatenate (append) src to the end of dst and return dst

char *strcat(char *dst, char *src);

// compare two strings. Return 0 if equal, nonzero otherwise

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

// return the length of str, not including the null termination

int strlen(char *str);

C.10.1 Compiling Multiple C Source Files

Multiple C files are compiled into a single executable by listing all file names on the compile line as shown below. Remember that the group of C files still must contain only one main function, conventionally placed in a file named main.c.

gcc main.c file2.c file3.c

C.10.2 Compiler Options

Compiler options allow the programmer to specify such things as output file names and formats, optimizations, etc. Compiler options are not standardized, but Table C.7 lists ones that are commonly used. Each option is typically preceded by a dash (-) on the command line, as shown. For example, the “-o” option allows the programmer to specify an output file name other than the a.out default. A plethora of options exist; they can be viewed by typing gcc --help at the command line.

Table C.7 Compiler options

C.10.3 Command Line Arguments

Like other functions, main can also take input variables. However, unlike other functions, these arguments are specified at the command line. As shown in C Code Example C.50, argc stands for argument count, and it denotes the number of arguments on the command line. argv stands for argument vector, and it is an array of the strings found on the command line. For example, suppose the program in C Code Example C.50 is compiled into an executable called testargs. When the following lines are typed at the command line, argc has the value 4, and the array argv has the values {”./testargs“, “arg1”, “25”, “lastarg!”}. Note that the executable name is counted as the 1^st argument. The console output after typing this command is shown below C Code Example C.50.

gcc -o testargs testargs.c

./testargs arg1 25 lastarg!

Programs that need numeric arguments may convert the string arguments to numbers using the functions in stdlib.h.