Functions: Function Prototypes

It is now considered good form to use function prototypes for all functions in your program. A prototype declares the function name, its parameters, and its return type to the rest of the program prior to the function's actual declaration. To understand why function prototypes are useful, enter the following code and run it:

#include <stdio.h>

void main()
{
 printf("%d\n",add(3));
}

int add(int i, int j)
{
 return i+j;
}

This code compiles on many compilers without giving you a warning, even though add expects two parameters but receives only one. It works because many C compilers do not check for parameter matching either in type or count. You can waste an enormous amount of time debugging code in which you are simply passing one too many or too few parameters by mistake. The above code compiles properly, but it produces the wrong answer.

To solve this problem, C lets you place function prototypes at the beginning of (actually, anywhere in) a program. If you do so, C checks the types and counts of all parameter lists. Try compiling the following:

#include <stdio.h>

int add (int,int); /* function prototype for add */

void main()
{
 printf("%d\n",add(3));
}

int add(int i, int j)
{
 return i+j;
}

The prototype causes the compiler to flag an error on the printf statement.

Place one prototype for each function at the beginning of your program. They can save you a great deal of debugging time, and they also solve the problem you get when you compile with functions that you use before they are declared. For example, the following code will not compile:

#include <stdio.h>

void main()
{
 printf("%d\n",add(3));
}

float add(int i, int j)
{
 return i+j;
}

Why, you might ask, will it compile when add returns an int but not when it returns a float? Because older C compilers default to an int return value. Using a prototype will solve this problem. "Old style" (non-ANSI) compilers allow prototypes, but the parameter list for the prototype must be empty. Old style compilers do no error checking on parameter lists.

Libraries

Libraries are very important in C because the C language supports only the most basic features that it needs. C does not even contain I/O functions to read from the keyboard and write to the screen. Anything that extends beyond the basic language must be written by a programmer. The resulting chunks of code are often placed in libraries to make them easily reusable. We have seen the standard I/O, or stdio, library already: Standard libraries exist for standard I/O, math functions, string handling, time manipulation, and so on. You can use libraries in your own programs to split up your programs into modules. This makes them easier to understand, test, and debug, and also makes it possible to reuse code from other programs that you write.

You can create your own libraries easily. As an example, we will take some code from a previous article in this series and make a library out of two of its functions. Here's the code we will start with:

#include <stdio.h>

#define MAX 10

int a[MAX];
int rand_seed=10;

int rand()
/* from K&R
 - produces a random number between 0 and 32767.*/
{
 rand_seed = rand_seed * 1103515245 +12345;
 return (unsigned int)(rand_seed / 65536) % 32768;
}

void main()
{
 int i,t,x,y;

 /* fill array */
 for (i=0; i < MAX; i++)
 {
 a[i]=rand();
 printf("%d\n",a[i]);
 }

 /* bubble sort the array */
 for (x=0; x < MAX-1; x++)
 for (y=0; y < MAX-x-1; y++)
 if (a[y] > a[y+1])
 {
 t=a[y];
 a[y]=a[y+1];
 a[y+1]=t;
 }

 /* print sorted array */
 printf("--------------------\n");
 for (i=0; i < MAX; i++)
 printf("%d\n",a[i]);
}

This code fills an array with random numbers, sorts them using a bubble sort, and then displays the sorted list.

Take the bubble sort code, and use what you learned in the previous article to make a function from it. Since both the array a and the constant MAX are known globally, the function you create needs no parameters, nor does it need to return a result. However, you should use local variables for x, y, and t.

Once you have tested the function to make sure it is working, pass in the number of elements as a parameter rather than using MAX:

#include <stdio.h>

#define MAX 10

int a[MAX];
int rand_seed=10;

/* from K&R
 - returns random number between 0 and 32767.*/
int rand()
{
 rand_seed = rand_seed * 1103515245 +12345;
 return (unsigned int)(rand_seed / 65536) % 32768;
}

void bubble_sort(int m)
{
 int x,y,t;
 for (x=0; x < m-1; x++)
 for (y=0; y < m-x-1; y++)
 if (a[y] > a[y+1])
 {
 t=a[y];
 a[y]=a[y+1];
 a[y+1]=t;
 }
}

void main()
{
 int i,t,x,y;
 /* fill array */
 for (i=0; i < MAX; i++)
 {
 a[i]=rand();
 printf("%d\n",a[i]);
 }
 bubble_sort(MAX);
 /* print sorted array */
 printf("--------------------\n");
 for (i=0; i < MAX; i++)
 printf("%d\n",a[i]);
}

You can also generalize the bubble_sort function even more by passing in a as a parameter:

bubble_sort(int m, int a[])

This line says, "Accept the integer array a of any size as a parameter." Nothing in the body of the bubble_sort function needs to change. To call bubble_sort, change the call to:

bubble_sort(MAX, a);

Note that &a has not been used in the function call even though the sort will change a. The reason for this will become clear once you understand pointers.

Making a Library

Since the rand and bubble_sort functions in the previous program are useful, you will probably want to reuse them in other programs you write. You can put them into a utility library to make their reuse easier.

Every library consists of two parts: a header file and the actual code file. The header file, normally denoted by a .h suffix, contains information about the library that programs using it need to know. In general, the header file contains constants and types, along with prototypes for functions available in the library. Enter the following header file and save it to a file named util.h.

/* util.h */
extern int rand();
extern void bubble_sort(int, int []);

These two lines are function prototypes. The word "extern" in C represents functions that will be linked in later. If you are using an old-style compiler, remove the parameters from the parameter list of bubble_sort.

Enter the following code into a file named util.c.

/* util.c */
#include "util.h"

int rand_seed=10;

/* from K&R
 - produces a random number between 0 and 32767.*/
int rand()
{
 rand_seed = rand_seed * 1103515245 +12345;
 return (unsigned int)(rand_seed / 65536) % 32768;
}

void bubble_sort(int m,int a[])
{
 int x,y,t;
 for (x=0; x < m-1; x++)
 for (y=0; y < m-x-1; y++)
 if (a[y] > a[y+1])
 {
 t=a[y];
 a[y]=a[y+1];
 a[y+1]=t;
 }
}

Note that the file includes its own header file (util.h) and that it uses quotes instead of the symbols < and> , which are used only for system libraries. As you can see, this looks like normal C code. Note that the variable rand_seed, because it is not in the header file, cannot be seen or modified by a program using this library. This is called information hiding. Adding the word static in front of int enforces the hiding completely.

Enter the following main program in a file named main.c.

#include <stdio.h>
#include "util.h"

#define MAX 10

int a[MAX];

void main()
{
 int i,t,x,y;
 /* fill array */
 for (i=0; i < MAX; i++)
 {
 a[i]=rand();
 printf("%d\n",a[i]);
 }

 bubble_sort(MAX,a);

 /* print sorted array */
 printf("--------------------\n");
 for (i=0; i < MAX; i++)
 printf("%d\n",a[i]);
}

This code includes the utility library. The main benefit of using a library is that the code in the main program is much shorter.

Compiling and Running with a Library

To compile the library, type the following at the command line (assuming you are using UNIX) (replace gcc with cc if your system uses cc):

gcc -c -g util.c

The -c causes the compiler to produce an object file for the library. The object file contains the library's machine code. It cannot be executed until it is linked to a program file that contains a main function. The machine code resides in a separate file named util.o.

To compile the main program, type the following:

gcc -c -g main.c

This line creates a file named main.o that contains the machine code for the main program. To create the final executable that contains the machine code for the entire program, link the two object files by typing the following:

gcc -o main main.o util.o

This links main.o and util.o to form an executable named main. To run it, type main.

Makefiles make working with libraries a bit easier. You'll find out about makefiles on the next page.

Makefiles

It can be cumbersome to type all of the gcc lines over and over again, especially if you are making a lot of changes to the code and it has several libraries. The make facility solves this problem. You can use the following makefile to replace the compilation sequence above:

main: main.o util.o
 gcc -o main main.o util.o
main.o: main.c util.h
 gcc -c -g main.c
util.o: util.c util.h
 gcc -c -g util.c

Enter this into a file named makefile, and type maketo build the executable. Note that you must precede all gcc lines with a tab. (Eight spaces will not suffice -- it must be a tab. All other lines must be flush left.)

This makefile contains two types of lines. The lines appearing flush left are dependency lines. The lines preceded by a tab are executable lines, which can contain any valid UNIX command. A dependency line says that some file is dependent on some other set of files. For example, main.o: main.c util.h says that the file main.o is dependent on the files main.c and util.h. If either of these two files changes, the following executable line(s) should be executed to recreate main.o.

Note that the final executable produced by the whole makefile is main, on line 1 in the makefile. The final result of the makefile should always go on line 1, which in this makefile says that the file main is dependent on main.o and util.o. If either of these changes, execute the line gcc -o main main.o util.o to recreate main.

It is possible to put multiple lines to be executed below a dependency line -- they must all start with a tab. A large program may have several libraries and a main program. The makefile automatically recompiles everything that needs to be recompiled because of a change.

If you are not working on a UNIX machine, your compiler almost certainly has functionality equivalent to makefiles. Read the documentation for your compiler to learn how to use it.

Now you understand why you have been including stdio.h in earlier programs. It is simply a standard library that someone created long ago and made available to other programmers to make their lives easier.

Text Files

Text files in C are straightforward and easy to understand. All text file functions and types in C come from the stdio library.

When you need text I/O in a C program, and you need only one source for input information and one sink for output information, you can rely on stdin (standard in) and stdout (standard out). You can then use input and output redirection at the command line to move different information streams through the program. There are six different I/O commands in <stdio.h> that you can use with stdin and stdout:

• printf - prints formatted output to stdout
• scanf - reads formatted input from stdin
• puts - prints a string to stdout
• gets - reads a string from stdin
• putc - prints a character to stdout
• getc, getchar - reads a character from stdin

The advantage of stdin and stdout is that they are easy to use. Likewise, the ability to redirect I/O is very powerful. For example, maybe you want to create a program that reads from stdin and counts the number of characters:

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

void main()
{
 char s[1000];
 int count=0;
 while (gets(s))
 count += strlen(s);
 printf("%d\n",count);
}

Enter this code and run it. It waits for input from stdin, so type a few lines. When you are done, press CTRL-D to signal end-of-file (eof). The gets function reads a line until it detects eof, then returns a 0 so that the while loop ends. When you press CTRL-D, you see a count of the number of characters in stdout (the screen). (Use man gets or your compiler's documentation to learn more about the gets function.)

Now, suppose you want to count the characters in a file. If you compiled the program to an executable named xxx, you can type the following:

xxx < filename

Instead of accepting input from the keyboard, the contents of the file named filename will be used instead. You can achieve the same result using pipes:

cat < filename | xxx

You can also redirect the output to a file:

xxx < filename > out

This command places the character count produced by the program in a text file named out.

Sometimes, you need to use a text file directly. For example, you might need to open a specific file and read from or write to it. You might want to manage several streams of input or output or create a program like a text editor that can save and recall data or configuration files on command. In that case, use the text file functions in stdio:

• fopen - opens a text file
• fclose - closes a text file
• feof - detects end-of-file marker in a file
• fprintf - prints formatted output to a file
• fscanf - reads formatted input from a file
• fputs - prints a string to a file
• fgets - reads a string from a file
• fputc - prints a character to a file
• fgetc - reads a character from a file

Text Files: Opening

You use fopen to open a file. It opens a file for a specified mode (the three most common are r, w, and a, for read, write, and append). It then returns a file pointer that you use to access the file. For example, suppose you want to open a file and write the numbers 1 to 10 in it. You could use the following code:

#include <stdio.h>
#define MAX 10

int main()
{
 FILE *f;
 int x;
 f=fopen("out","w");
 if (!f)
 return 1;
 for(x=1; x<=MAX; x++)
 fprintf(f,"%d\n",x);
 fclose(f);
 return 0;
}

The fopen statement here opens a file named out with the w mode. This is a destructive write mode, which means that if out does not exist it is created, but if it does exist it is destroyed and a new file is created in its place. The fopen command returns a pointer to the file, which is stored in the variable f. This variable is used to refer to the file. If the file cannot be opened for some reason, f will contain NULL.

The fprintf statement should look very familiar: It is just like printf but uses the file pointer as its first parameter. The fclose statement closes the file when you are done.

Text Files: Reading

To read a file, open it with r mode. In general, it is not a good idea to use fscanf for reading: Unless the file is perfectly formatted, fscanf will not handle it correctly. Instead, use fgets to read in each line and then parse out the pieces you need.

The following code demonstrates the process of reading a file and dumping its contents to the screen:

#include <stdio.h>

int main()
{
 FILE *f;
 char s[1000];

 f=fopen("infile","r");
 if (!f)
 return 1;
 while (fgets(s,1000,f)!=NULL)
 printf("%s",s);
 fclose(f);
 return 0;
}

The fgets statement returns a NULL value at the end-of-file marker. It reads a line (up to 1,000 characters in this case) and then prints it to stdout. Notice that the printf statement does not include \n in the format string, because fgets adds \n to the end of each line it reads. Thus, you can tell if a line is not complete in the event that it overflows the maximum line length specified in the second parameter to fgets.

Pointers

Pointers are used everywhere in C, so if you want to use the C language fully you have to have a very good understanding of pointers. They have to become comfortable for you. The goal of this section and the next several that follow is to help you build a complete understanding of pointers and how C uses them. For most people it takes a little time and some practice to become fully comfortable with pointers, but once you master them you are a full-fledged C programmer.

C uses pointers in three different ways:

• C uses pointers to create dynamic data structures -- data structures built up from blocks of memory allocated from the heap at run-time.
• C uses pointers to handle variable parameters passed to functions.
• Pointers in C provide an alternative way to access information stored in arrays. Pointer techniques are especially valuable when you work with strings. There is an intimate link between arrays and pointers in C.

In some cases, C programmers also use pointers because they make the code slightly more efficient. What you will find is that, once you are completely comfortable with pointers, you tend to use them all the time.

We will start this discussion with a basic introduction to pointers and the concepts surrounding pointers, and then move on to the three techniques described above. Especially on this article, you will want to read things twice. The first time through you can learn all the concepts. The second time through you can work on binding the concepts together into an integrated whole in your mind. After you make your way through the material the second time, it will make a lot of sense.

Pointers: Why?

Imagine that you would like to create a text editor -- a program that lets you edit normal ASCII text files, like "vi" on UNIX or "Notepad" on Windows. A text editor is a fairly common thing for someone to create because, if you think about it, a text editor is probably a programmer's most commonly used piece of software. The text editor is a programmer's intimate link to the computer -- it is where you enter all of your thoughts and then manipulate them. Obviously, with anything you use that often and work with that closely, you want it to be just right. Therefore many programmers create their own editors and customize them to suit their individual working styles and preferences.

So one day you sit down to begin working on your editor. After thinking about the features you want, you begin to think about the "data structure" for your editor. That is, you begin thinking about how you will store the document you are editing in memory so that you can manipulate it in your program. What you need is a way to store the information you are entering in a form that can be manipulated quickly and easily. You believe that one way to do that is to organize the data on the basis of lines of characters. Given what we have discussed so far, the only thing you have at your disposal at this point is an array. You think, "Well, a typical line is 80 characters long, and a typical file is no more than 1,000 lines long." You therefore declare a two-dimensional array, like this:

char doc[1000][80];

This declaration requests an array of 1,000 80-character lines. This array has a total size of 80,000 characters.

As you think about your editor and its data structure some more, however, you might realize three things:

• Some documents are long lists. Every line is short, but there are thousands of lines.
• Some special-purpose text files have very long lines. For example, a certain data file might have lines containing 542 characters, with each character representing the amino acid pairs in segments of DNA.
• In most modern editors, you can open multiple files at one time.

Let's say you set a maximum of 10 open files at once, a maximum line length of 1,000 characters and a maximum file size of 50,000 lines. Your declaration now looks like this:

char doc[50000][1000][10];

That doesn't seem like an unreasonable thing, until you pull out your calculator, multiply 50,000 by 1,000 by 10 and realize the array contains 500 million characters! Most computers today are going to have a problem with an array that size. They simply do not have the RAM, or even the virtual memory space, to support an array that large. If users were to try to run three or four copies of this program simultaneously on even the largest multi-user system, it would put a severe strain on the facilities.

Even if the computer would accept a request for such a large array, you can see that it is an extravagant waste of space. It seems strange to declare a 500 million character array when, in the vast majority of cases, you will run this editor to look at 100 line files that consume at most 4,000 or 5,000 bytes. The problem with an array is the fact that you have to declare it to have its maximum size in every dimension from the beginning. Those maximum sizes often multiply together to form very large numbers. Also, if you happen to need to be able to edit an odd file with a 2,000 character line in it, you are out of luck. There is really no way for you to predict and handle the maximum line length of a text file, because, technically, that number is infinite.

Pointers are designed to solve this problem. With pointers, you can create dynamic data structures. Instead of declaring your worst-case memory consumption up-front in an array, you instead allocate memory from the heap while the program is running. That way you can use the exact amount of memory a document needs, with no waste. In addition, when you close a document you can return the memory to the heap so that other parts of the program can use it. With pointers, memory can be recycled while the program is running.

By the way, if you read the previous discussion and one of the big questions you have is, "What IS a byte, really?," then the article How Bits and Bytes Work will help you understand the concepts, as well as things like "mega," "giga" and "tera." Go take a look and then come back.