Chapter 2 - Library functions

An introductory comment

The source code of a program has not one audience, but two. Whilst it is certainly the case that a compiler must be able to read your code, it is also true that humans must read it, and be able to understand it. Since it is not always obvious what a line of C code does, the language provides a facility for adding a documentary comment to the code, in which you can explain what's going on for the benefit of a human reader.

A comment starts with the two-character combination slash-star /* and ends with the two-character combination */ star-slash; this enables us to write code such as:

int main(void)
{
  /* we will write something clever here one day soon */

  return 0; /* terminate the program */
}

To make the compiler's job simpler, before compilation the source code undergoes an operation named preprocessing. The preprocessor has a number of jobs to do, and one of them is the removal of comments. We can write code as shown above, and the preprocessor (which is normally bundled seamlessly into the compiler so that we don't have to worry about it) converts that code into:

int main(void)
{

  return 0;
}

with the comments removed entirely. They're still there in your source code, but they are no longer present in the code that the preprocessor presents to the compiler for translation.

The standard library - C's toolbox

Unlike imperative languages such as BASIC, the C language does not provide any commands. Instead, everything is done via functions. There is, for example, no special syntax for writing a digit or a letter onto the screen (or any other output device). Instead, we call a function to do this. Neither is there any command for retrieving a digit or a letter from the keyboard (or other input device). Again, this is instead done via a function call.

Consider the problem of displaying a character (a letter, or a digit, or a punctuation symbol) on an output device. For our purposes, this is a somewhat urgent problem, as it's difficult to see what a program is actually achieving if it doesn't write anything down anywhere.

C allows us to embed literal character constants into our program by enclosing them in single quotes. Thus 'A' means "the upper case Roman character A". Character constants, like almost everything in C, have a type, and that type is int.

C also provides a standard library function for displaying such a character constant on the standard output device, which is normally a window on your computer's screen. Before we can use this standard library function, however, there are a couple of things we need to know.

Firstly, a typical C implementation has buffered output, which means that the system saves up its output until it has a full line of text. The clue that a full line of text has been presented for output is that a newline character is encountered. C's code for newline is the letter n. To distinguish it from an ordinary letter n, it is escaped using the \ character. Thus, 'n' means the letter n, but '\n' means 'a newline character'. When we've finished writing characters to the standard output device, we must write a newline character. (It's not hard, and you'll see how in a moment.)

The other thing we need to know is the prototype for the function that displays a character on the standard output device. This function is called putchar and its prototype looks like this:

int putchar(int);

This means that the putchar function expects a parameter of type int, and returns an int to its caller.

This is by no means the only useful output function that C provides as standard. What's more, there are many useful input functions available. So that we don't have to write a prototype for every single one we use, C gives us a mechanism for incorporating prototypes for all of them in one fell swoop. The compiler has them all written down somewhere, and all we have to do to take advantage of this pre-existing list is to tell the preprocessor to include the list in our source file before handing it to the compiler. We do this using a preprocessor directive:

#include <stdio.h>

The # that begins the line tells the preprocessor that it has a job to do, the include tells it what that job is, and the <stdio.h> tells it what to include.

As you might guess, std means standard, and io means input/output. The dot-h suffix is a traditional means of indicating a C header. The C language definition requires the existence of a small army of headers, of which <stdio.h> is one of the most important.

We are now ready to write the first program that does anything useful. As you will see, it is liberally sprinkled with comments:

/* write_hello.c */

#include <stdio.h> /* pull in the prototype for putchar */

int main(void) /* main is a function that takes no parameters, and returns int */
{
  putchar('H');
  putchar('e');
  putchar('l');
  putchar('l');
  putchar('o');
  putchar('\n'); /* terminate the line with a newline character */

  return 0; /* terminate the program */
}

This is a very clumsy way to write 'Hello' on the screen! There are of course better ways. But this way has the virtue of being very, very simple. We'll get to the more complicated ways later on.

The program has a very simple call graph:

It is of course possible that putchar calls other functions to help it to do its job but, thankfully, we don't have to worry about that. From our point of view, putchar is a leaf function, so called because it's like the leaf of a tree - no branches coming off it.

Things to do

Now would be a good time to copy the write_hello.c program into your text editor, save it as a file on your system (in a place where you know you can find it again), and submit it to your compiler. Once your compiler has translated it correctly, run it (this is normally as simple as typing its name, although under Linux you will normally have to type ./write_hello so as to tell the shell to look for the program in the current working directory).

If you have problems doing this, there is little point in reading on until you have solved that problem. Learning C isn't just about reading. It's about writing programs. If you can't compile the above program, try to find some help before proceeding any further.

Summary

In this chapter, you learned of the existence of C's standard toolbox of functions, you learned how to document a program using comment syntax, and you were introduced to the C preprocessor and the putchar function.

In the next chapter, we will learn how to capture and process basic input.

Progress

Terminology

• preprocessor
• standard library function
• user function
• control flow
• function
• main
• parameter list
• statement terminator
• function prototype

Syntax

• comments

Standard library functions, by header

• <stdio.h>
  • putchar