Complete Programs in C

• 1. Putting it all together
• 2. Arguments to main
• 3. Interpreting program arguments
• 4. A pattern matching program
• 5. A more ambitious example
• 6. Afterword

1. Putting it all together

Having considered the language and the libraries defined by the Standard, all that now remains is to demonstrate what complete programs look like. This chapter contains some example programs which illustrate how to combine these elements to build programs.

However, just before these examples are presented there is one more aspect of the C language to discuss.

2. Arguments to main

For those writing programs which will run in a hosted environment, arguments to main provide a useful opportunity to give parameters to programs. Typically, this facility is used to direct the way the program goes about its task. It's particularly common to provide file names to a program through its arguments.

The declaration of main looks like this:

This indicates that main is a function returning an integer. In hosted environments such as DOS or UNIX, this value or exit status is passed back to the command line interpreter. Under UNIX, for example, the exit status is used to indicate that a program completed successfully (a zero value) or some error occurred (a non-zero value). The Standard has adopted this convention; exit( is used to return 'success' to its host environment, any other value is used to indicate failure. If the host environment itself uses a different numbering convention, exit will do the necessary translation. Since the translation is implementation-defined, it is now considered better practice to use the values defined in <stdlib.h>: EXIT_SUCCESS and EXIT_FAILURE.

There are at least two arguments to main: argc and argv. The first of these is a count of the arguments supplied to the program and the second is an array of pointers to the strings which are those arguments-its type is (almost) 'array of pointer to char'. These arguments are passed to the program by the host system's command line interpreter or job control language.

The declaration of the argv argument is often a novice programmer's first encounter with pointers to arrays of pointers and can prove intimidating. However, it is really quite simple to understand. Since argv is used to refer to an array of strings, its declaration will look like this:

Remember too that when it is passed to a function, the name of an array is converted to the address of its first element. This means that we can also declare argv as char **argv; the two declarations are equivalent in this context.

Indeed, you will often see the declaration of main expressed in these terms. This declaration is exactly equivalent to that shown above:

When a program starts, the arguments to main will have been initialized to meet the following conditions:

• argc is greater than zero.
• argv[argc] is a null pointer.
• argv[ through to argv[argc-1] are pointers to strings whose meaning will be determined by the program.
• argv[ will be a string containing the program's name or a null string if that is not available. Remaining elements of argv represent the arguments supplied to the program. In cases where there is only support for single-case characters, the contents of these strings will be supplied to the program in lower-case.

To illustrate these points, here is a simple program which writes the arguments supplied to main on the program's standard output.

Example 1

If the program name is show_args and it has arguments abcde, text, and hello when it is run, the state of the arguments and the value of argv can be illustrated like this:

Figure 1. Arguments to a program

Each time that argv is incremented, it is stepped one item further along the array of arguments. Thus after the first iteration of the loop, argv will point to the pointer which in turn points to the abcde argument. This is shown in Figure 2.

Figure 2. Arguments to a program after incrementing argv

On the system where this program was tested, a program is run by typing its name and then the arguments, separated by spaces. This is what happened (the is a prompt):

3. Interpreting program arguments

The loop used to examine the program arguments in the example above is a common C idiom which you will see in many other programs. An additional common idiom is to use 'options' to control the behaviour of the program (these are also sometimes called switches or flags). Arguments which start with a ' ' are taken to introduce one or more single-letter option indicators, which can be run together or provided separately:

The idea is that each of the options selects a particular aspect from the program's repertoire of features. An extension to that idea is to allow options to take arguments; if the -x option is specified to take an argument, then this is how it might be used:

so that the arg argument is associated with the option. The options function below automates the processing of this style of use, with the additional (common but preferably considered obsolescent) support for the provision of option arguments immediately following the option letter, as in:

In either of the above cases, the options routine returns the character 'x' and sets a global pointer, OptArg, to point to the value arg.

To use this routine, a program must supply a list of valid option letters in the form of a string; when a letter in this string is followed by a ' ' this indicates that the option letter is to be followed by an argument. When the program is run, it is then simply a question of repeatedly calling the options routine until no more option letters remain to be found.

It seems to be a fact of life that functions which scan text strings looking for various combinations or patterns within them end up being hard to read; if it's any consolation they aren't all that easy to write either. The code that implements the options is definitely one of the breed, although by no means one of the worst:

Example 2

4. A pattern matching program

This section presents a complete program which makes use of option letters as program arguments to control the way it performs its job.

The program first processes any arguments that resemble options; the first argument which is not an option is remembered for use as a 'search string'. Any remaining arguments are used to specify file names which are to be read as input to the program; if no file names are provided, the program reads from its standard input instead. If a match for the search string is found in a line of input text, that whole line is printed on the standard output.

The options function is used to process all option letters supplied to the program. This program recognises five options: -c, -i, -l, -n, and -v. None of these options is required to be followed by an option argument. When the program is run with one or more of these options its behaviour is modified as follows:

-c

the program prints a count of the total number of matching lines it found in the input file(s). No lines of text are printed.

-i

when searching for a match, the case of letters in both the input lines and string is ignored.

-l

each line of text printed on the output is prefixed with the line number being examined in the current input file.

-n

each line of text printed on the output is prefixed with the name of the file that contained the line.

-v

the program prints only lines which do not match the string supplied.

When the program finishes, it returns an exit status to indicate one of the following situations:

EXIT_SUCCESS

at least one match was found.

EXIT_FAILURE

no match was found, or some error occurred.

The program makes extensive use of standard library functions to do all of the hard work. For example, all of the file handling is performed by calls to stdio functions. Notice too that the real heart of the program, the string matching, is simply handled by a call to the strstr library function.

Here is the code for the whole program. Of course, to get this to work you would need to compile it together with the code for the options routine presented above.

Example 3

5. A more ambitious example

Finally here is a set of programs designed to cooperate and manipulate a single data file in a coherent, robust fashion.

The programs are intended to help keep track of a ladder of players who compete against each other at some game, squash or chess perhaps.

Each player has a rank from one to n, where n is the number of players who play, one being the highest rank on the ladder. Players lower down the ladder may challenge players above them and, if the lower ranked player wins, he or she moves up taking the rank of the player who loses. The loser in such a situation, and any other players between challenger and loser, are then moved down one rank. If a challenger does not win, the rankings on the ladder remain unchanged.

To provide some measure of equilibrium in the rankings, a player may challenge any higher ranked player, but only wins over players ranked three (or less) higher will allow the challenger to move up the rankings. This ensures that new players added to the bottom of the ladder are forced to play more than one game to reach the top of the ladder!

There are three basic tasks which are required to record all the information needed to keep such a ladder going:

• Printing the ladder.
• Addition of new players.
• Recording of results.

The design to be used here provides a separate program to perform each of these tasks. Having made this decision it is clear that a number of operations needed by each program will be common to all three. For example, all three will need to read player records from the data file, at least two will need to write player records into the data file.

This suggests that a good approach would be to design a 'library' of functions which manipulate player records and the data file which may in turn be combined to make up the programs which maintain the ladder.

Before this can be done it will be necessary to define the data structure which represents player records. The minimum information necessary to record for each player consists of player name and rank. However, to allow for more interesting statistics to be compiled about the ladder let us chose to also keep a record of games won, games lost and the time when the last game was played. Clearly this disparate set of information is best collected together in a structure.

The player structure declaration together with the declarations of the player library functions are combined together in the player.h header file. The data file is maintained as lines of text, each line corresponding to a record; this requires input and output conversions to be performed but is a useful technique if the conversions don't cost too much in performance terms.

Example 4

Here is the code for the player.c file implementing the generic functions which manipulate player records and the data file. These functions can be combined with more specific routines to make up the three programs required to maintain the ladder.

Notice that to manipulate the player records, each program is required to read the entire data file into a dynamically allocated array. Before this array is written back to the data file, it is assumed that the records it contains will have been sorted into rank order. If the records do not remain sorted, the push_down function will produce some 'interesting' results!

Example 5

This code, when tested, was compiled into an object file which was then linked (together with an object file containing the code for the options function) with one of the following three programs to for the ladder maintenance utilities.

Here is the code for the simplest of those utilities, showlddr which is contained in the file showlddr.c.

This program takes a single option, -f, which you will notice takes an option argument. The purpose of this argument is to allow you to print a ladder data file with a name other than the default file name, ladder.

The player records in the data file should be stored pre-sorted but, just to be safe, showlddr sorts them before it prints them out.

Example 6

Of course the showlddr program works only if there is an existing data file containing player records in the correct format. The program newplyr creates such a file if one does not already exist and then adds a new player record, in the correct format to that file.

Typically, new players are added at the bottom of the rankings but for the odd occasion where this really may not make sense, newplyr also allows a player to be inserted into the middle of the rankings.

A player may only appear once on the ladder (unless a pseudonym is used!) and there can only be one player at any one rank. Thus the program checks for duplicate entries and if the new player is to be inserted into a middling rank, moves other players already on the ladder out of the way.

As with the showlddr program, newplyr recognises a -f option as a request to add the new player to a file named by the option argument rather than the default file, ladder. In addition, newplyr requires two options, -n and -r, each with option arguments to specify both the new player's name and initial ranking respectively.

Example 7

The only remaining utility required is one for recording the results of games played. The result program performs this task.

As with the previous two utilities, result will accept a -f option together with a file name to specify an alternative to the default player record file.

Unlike the newplyr utility, result interactively prompts the user for the names of the winning and losing players. The program insists that the names supplied should be those of existing players.

Given a valid pair of names, a check is then made to see if the loser is higher ranked than winner and whether or not the winner is ranked close enough for the victory to alter the rankings.

If a change in the standings is in order, the victor takes the loser's rank and the loser (as well as any other player on an intervening rank) is demoted one rank.

Here is the code for the result utility.

Example 8

6. Afterword

The programs shown in this chapter should help to to get a feel for what middle-of-the-road C programs look like, using the language and libraries defined in the Standard.

What do we mean by 'middle-of-the-road'? Simply this: they have been designed, implemented, tested and documented in a way appropriate for small, self-contained programs that have no real need to show high levels of robustness and reliability. Many programs don't need to meet demanding criteria; to do more to them would be over-engineering. Clearly, it is entirely dependent on the eventual purpose for which the program is intended.

There are situations which place very high demands on the software that is in use; programs to meet these requirements are very carefully engineered and have much higher amounts of effort put into reviewing, testing and the control of access to the source code than would be appropriate for simple illustrative example programs. C is also used in these application areas. The source code of programs that meet such high requirements tends to look distinctively different; the language is the same, but the amount of error checking and correction is typically much higher. We have not tried to illustrate that type of program.

Whichever environment you work in, we hope that this book has helped you in your understanding of C. Good luck!