1.3. A description of Example 1.1

1.3.1. What was in it

Even such a small example has introduced a lot of C. Among other things, it contained two functions, a #include ‘statement’, and some comment. Since comment is the easiest bit to handle, let's look at that first.

1.3.2. Layout and comment

The layout of a C program is not very important to the compiler, although for readability it is important to use this freedom to carry extra information for the human reader. C allows you to put space, tab or newline characters practically anywhere in the program without any special effect on the meaning of the program. All of those three characters are the same as far as the compiler is concerned and are called collectively white space, because they just move the printing position without causing any ‘visible’ printing on an output device. White space can occur practically anywhere in a program except in the middle of identifiers, strings, or character constants. An identifier is simply the name of a function or some other object; strings and character constants will be discussed later—don't worry about them for the moment.

Apart from the special cases, the only place that white space must be used is to separate things that would otherwise run together and become confused. In the example above, the fragment void show_message needs space to separate the two words, whereas show_message( could have space in front of the ( or not, it would be purely a matter of taste.

Comment is introduced to a C program by the pair of characters /*, which must not have a space between them. From then on, everything found up to and including the pair of characters */ is gobbled up and the whole lot is replaced by a single space. In Old C, this was not the case. The rule used to be that comment could occur anywhere that space could occur: the rule is now that comment is space. The significance of the change is minor and eventually becomes apparent in Chapter 7 where we discuss the preprocessor. A consequence of the rule for the end of comment is that you can't put a piece of comment inside another piece, because the first */ pair will finish all of it. This is a minor nuisance, but you learn to live with it.

It is common practice to make a comment stand out by making each line of multi-line comment always start with a *, as the example illustrates.

1.3.3. Preprocessor statements

The first statement in the example is a preprocessor directive. In days gone by, the C compiler used to have two phases: the preprocessor, followed by the real compiler. The preprocessor was a macro processor, whose job was to perform simple textual manipulation of the program before passing the modified text on to be compiled. The preprocessor rapidly became seen as an essential aspect of the compiler and so has now been defined as part of the language and cannot be bypassed.

The preprocessor only knows about lines of text; unlike the rest of the language it is sensitive to the end of a line and though it is possible to write multi-line preprocessor directives, they are uncommon and a source of some wonder when they are found. Any line whose first visible character is a # is a preprocessor directive.

In Example 1.1 the preprocessor directive #include causes the line containing it to be replaced completely by the contents of another file. In this case the filename is found between the < and > brackets. This is a widely used technique to incorporate the text of standard header files into your program without having to go through the effort of typing it all yourself. The <stdio.h> file is an important one, containing the necessary information that allows you to use the standard library for input and output. If you want to use the I/O library you must include <stdio.h>. Old C was more relaxed on this point.

1.3.3.1. Define statements

Another of the preprocessor's talents which is widely exploited is the #define statement. It is used like this:

#define IDENTIFIER      replacement

which says that the name represented by IDENTIFIER will be replaced by the text of replacement whenever IDENTIFIER occurs in the program text. Invariably, the identifier is a name in upper-case; this is a stylistic convention that helps the reader to understand what is going on. The replacement part can be any text at all—remember the preprocessor doesn't know C, it just works on text. The most common use of the statement is to declare names for constant numbers:

#define PI             3.141592
#define SECS_PER_MIN   60
#define MINS_PER_HOUR  60
#define HOURS_PER_DAY  24

and to use them like this

circumf = 2*PI*radius;
if(timer >= SECS_PER_MIN){
mins = mins+1;
        timer = timer - SECS_PER_MIN;
}

the output from the preprocessor will be as if you had written this:

circumf = 2*3.141592*radius;
if(timer >= 60){
        mins = mins+1;
       timer = timer - 60;
}

Summary

Preprocessor statements work on a line-by-line basis, the rest of C does not.

#include statements are used to read the contents of a specified file, typically to facilitate the use of library functions.

#define statements are typically used to give names for constants. By convention, the names are in upper case (capitalized).

1.3.4. Function declaration and definition

1.3.4.1. Declaration

After the <stdio.h> file is included comes a function declaration; it tells the compiler that show_message is a function which takes no arguments and returns no values. This demonstrates one of the changes made by the Standard: it is an example of a function prototype, a subject which Chapter 4 discusses in detail. It isn't always necessary to declare functions in advance—C will use some (old) default rules in such cases—but it is now strongly recommended that you do declare them in advance. The distinction between a declaration and a definition is that the former simply describes the type of the function and any arguments that it might take, the latter is where the body of a function is provided. These terms become more important later.

By declaring show_message before it is used, the compiler is able to check that it is used correctly. The declaration describes three important things about the function: its name, its type, and the number and type of its arguments. The void show_message( part indicates that it is a function and that it returns a value of type void, which is discussed in a moment. The second use of void is in the declaration of the function's argument list, (void), which indicates that there are no arguments to this function.

1.3.4.2. Definition

Right at the end of the program is the function definition itself; although it is only three lines long, it usefully illustrates a complete function.

In C, functions perform the tasks that some other languages split into two parts. Most languages use a function to return a value of some sort, typical examples being perhaps trigonometric functions like sin, cos, or maybe a square root function; C is the same in this respect. Other similar jobs are done by what look very much like functions but which don't return a value: FORTRAN uses subroutines, Pascal and Algol call them procedures. C simply uses functions for all of those jobs, with the type of the function's return value specified when the function is defined. In the example, the function show_message doesn't return a value so we specify that its type is void.

The use of void in that way is either crashingly obvious or enormously subtle, depending on your viewpoint. We could easily get involved here in an entertaining (though fruitless) philosophical side-track on whether void really is a value or not, but we won't. Whichever side of the question you favour, it's clear that you can't do anything with a void and that's what it means here—“I don't want to do anything with any value this function might or might not return”.

The type of the function is void, its name is show_message. The parentheses () following the function name are needed to let the compiler know that at this point we are talking about a function and not something else. If the function did take any arguments, then their names would be put between the parentheses. This one doesn't take any, which is made explicit by putting void between the parentheses.

For something whose essence is emptiness, abnegation and rejection, void turns out to be pretty useful.

The body of the function is a compound statement, which is a sequence of other statements surrounded by curly brackets {}. There is only one statement in there, but the brackets are still needed. In general, C allows you to put a compound statement anywhere that the language allows the use of a single simple statement; the job of the brackets being to turn several statements in a row into what is effectively a single statement.

It is reasonable to ask whether or not the brackets are strictly needed, if their only job is to bind multiple statements into one, yet all that we have in the example is a single statement. Oddly, the answer is yes—they are strictly needed. The only place in C where you can't put a single statement but must have a compound statement is when you are defining a function. The simplest function of all is therefore the empty function, which does nothing at all:

void do_nothing(void){}

The statement inside show_message is a call of the library function printf. printf is used to format and print things, this example being one of the simplest of its uses. printf takes one or more arguments, whose values are passed forward from the point of the call into the function itself. In this case the argument is a string. The contents of the string are interpreted by printf and used to control the way the values of the other arguments are printed. It bears a little resemblance to the FORMAT statement in FORTRAN; but not enough to predict how to use it.

Summary

Declarations are used to introduce the name of a function, its return type and the type (if any) of its arguments.

A function definition is a declaration with the body of the function given too.

A function returning no value should have its type declared as void. For example, void func(/* list of arguments */);

A function taking no arguments should be declared with void as its argument list. For example, void func(void);

1.3.5. Strings

In C, strings are a sequence of characters surrounded by quote marks:

"like this"

Because a string is a single element, a bit like an identifier, it is not allowed to continue across a line—although space or tab characters are permitted inside a string.

"This is a valid string"
"This has a newline in it
and is NOT a valid string"

To get a very long string there are two things that you can do. You could take advantage of the fact that absolutely everywhere in a C program, the sequence ‘backslash end-of-line’ disappears totally.

"This would not be valid but doesn't have \
a newline in it as far as the compiler is concerned"

The other thing you could do is to to use the string joining feature, which says that two adjacent strings are considered to be just one.

"All this " "comes out as "
"just one string"

Back to the example. The sequence ‘\n’ in the string is an example of an escape sequence which in this case represents ‘newline’. Printf simply prints the contents of the string on the program's output file, so the output will read ‘hello’, followed by a new line.

To support people working in environments that use character sets which are ‘wider’ than U.S. ASCII, such as the shift-JIS representation used in Japan, the Standard now allows multibyte characters to be present in strings and comments. The Standard defines the 96 characters that are the alphabet of C (see Chapter 2). If your system supports an extended character set, the only place that you may use these extended characters is in strings, character constants, comment and the names of header files. Support for extended character sets is an implementation defined feature, so you will have to look it up in your system's documentation.

1.3.6. The main function

In Example 1.1 there are actually two functions, show_message and main. Although main is a bit longer than show_message it is obviously built in the same shape: it has a name, the parentheses () are there, followed by the opening bracket { of the compound statement that must follow in a function definition. True, there's a lot more stuff too, but right at the end of the example you'll find the matching closing bracket } that goes with the first one to balance the numbers.

This is a much more realistic function now, because there are several statements inside the function body, not just one. You might also have noticed that the function is not declared to be void. There is a good reason for this: it returns a proper value. Don't worry about its arguments yet; they are discussed in Chapter 10.

The most important thing about main is that it is the first function to be called. In a hosted environment your C language system arranges, magically, for a call on the main function (hence its name) when the program is first started. When the function is over, so is the program. It's obviously an important function. Equally important is the stuff inside main's compound statement. As mentioned before, there can be several statements inside a compound statement, so let's look at them in turn.

1.3.7. Declarations

The first statement is this:

int count;

which is not an instruction to do anything, but simply introduces a variable to the program. It declares something whose name is count, and whose type is ‘integer’; in C the keyword that declares integers is unaccountably shortened to int. C has an idiosyncratic approach to these keywords with some having their names spelled in full and some being shortened like int. At least int has a meaning that is more or less intuitive; just wait until we get on to static.

As a result of that declaration the compiler now knows that there is something that will be used to store integral quantities, and that its name is count. In C, all variables must be declared before they are used; there is none of FORTRAN's implicit declarations. In a compound statement, all the declarations must come first; they must precede any ‘ordinary’ statements and are therefore somewhat special.

(Note for pedants: unless you specifically ask, the declaration of a variable like count is also a definition. The distinction will later be seen to matter.)

1.3.8. Assignment statement

Moving down the example we find a familiar thing, an assignment statement. This is where the first value is assigned to the variable count, in this case the value assigned is a constant whose value is zero. Prior to the assignment, the value of count was undefined and unsafe to use. You might be a little surprised to find that the assignment symbol (strictly speaking an assignment operator) is a single = sign. This is not fashionable in modern languages, but hardly a major blemish.

So far then, we have declared a variable and assigned the value of zero to it. What next?

1.3.9. The while statement

Next is one of C's loop control statements, the while statement. Look carefully at its form. The formal description of the while statement is this:

while(expression)
        statement

Is that what we have got? Yes it is. The bit that reads

count < 10

is a relational expression, which is an example of a valid expression, and the expression is followed by a compound statement, which is a form of valid statement. As a result, it fits the rules for a properly constructed while statement.

What it does must be obvious to anyone who has written programs before. For as long as the relationship count < 10 holds true, the body of the loop is executed and the comparison repeated. If the program is ever to end, then the body of the loop must do something that will eventually cause the comparison to be false: of course it does.

There are just two statements in the body of the loop. The first one is a function call, where the function show_message is invoked. A function call is indicated by the name of the function followed by the parentheses () which contain its argument list—if it takes no arguments, then you provide none. If there were any arguments, they would be put between the parentheses like this:

/* call a function with several arguments */
function_name(first_arg, second_arg, third_arg);

and so on. The call of printf is another example. More is explained in Chapter 4.

The last statement in the loop is another assignment statement. It adds one to the variable count, so that the requirement for program to stop will eventually be met.

1.3.10. The return statement

The last statement that is left to discuss is the return statement. As it is written, it looks like another function call, but in fact the rule is that the statement is written

return expression;

where the expression is optional. The example uses a common stylistic convention and puts the expression into parentheses, which has no effect whatsoever.

The return causes a value to be returned from the current function to its caller. If the expression is missing, then an unknown value is passed back to the caller—this is almost certainly a mistake unless the function returns void. Main wasn't declared with any type at all, unlike show_message, so what type of value does it return? The answer is int. There are a number of places where the language allows you to declare things by default: the default type of functions is int, so it is common to see them used in this way. An equivalent declaration for main would have been

int main(){

and exactly the same results would have occurred.

You can't use the same feature to get a default type for variables because their types must be provided explicitly.

What does the value returned from main mean, and where does it go? In Old C, the value was passed back to the operating system or whatever else was used to start the program running. In a UNIX-like environment, the value of 0 meant ‘success’ in some way, any other value (often -1) meant ‘failure’. The Standard has enshrined this, stating that 0 stands for correct termination of the program. This does not mean that 0 is to be passed back to the host environment, but whatever is the appropriate ‘success’ value for that system. Because there is sometimes confusion around this, you may prefer to use the defined values EXIT_SUCCESS and EXIT_FAILURE instead, which are defined in the header file <stdlib.h>. Returning from the main function is the same as calling the library function exit with the return value as an argument. The difference is that exit may be called from anywhere in the program, and terminates it at that point, after doing some tidying up activities. If you intend to use exit, you must include the header file <stdlib.h>. From now on, we shall use exit rather than returning from main.

Summary

The main function returns an int value.

Returning from main is the same as calling the exit function, but exit can be called from anywhere in a program.

Returning 0 or EXIT_SUCCESS is the way of indicating success, anything else indicates failure.

1.3.11. Progress so far

This example program, although short, has allowed us to introduce several important language features, amongst them:

• Program structure
• Comment
• File inclusion
• Function definition
• Compound statements
• Function calling
• Variable declaration
• Arithmetic
• Looping

although of course none of this has been covered rigorously.