File Inclusion: include

I l @ ve RuBoard

File Inclusion: #include

When the preprocessor spots an #include directive, it looks for the following filename and includes the contents of that file within the current file. The #include directive in your source code file is replaced with the text from the included file. It's as though you sat down and typed in the entire contents of the included file at that particular location in your source file. The #include directive comes in two varieties.

 #include <stdio.h>             <--Filename in angle brackets #include "mystuff.h"                <--Filename in double quotation marks 

On a UNIX system, the angle brackets tell the preprocessor to look for the file in one or more standard system directories. The double quotation marks tell it to first look in your current directory (or some other directory that you have specified in the filename) and then look in the standard places.

 #include <stdio.h>           <--Searches system directories #include "hot.h"                  <--Searches your current working directory #include "/usr/biff/p.h"          <--Searches the /usr/biff directory 

Integrated development environments (IDEs) also have a standard location or locations for the system header files. Many provide menu choices for specifying additional locations to be searched when angle brackets are used. As with UNIX, using double quotes means to search a local directory first, but the exact directory searched depends on the compiler. Some search the same directory as that holding the source code; some search the current working directory; and some search the same directory as that holding the project file.

ANSI C doesn't demand adherence to the directory model for files because not all computer systems are organized similarly. In general, the method used to name files is system dependent, but the use of the angle brackets and double quotation marks is not.

Why include files? Because they have information the compiler needs. The stdio.h file, for example, typically includes definitions of EOF , NULL , getchar () , and putchar () . The last two are defined as macro functions.

The .h suffix is conventionally used for header files ”files with information that are placed at the head of your program. Header files usually consist of preprocessor statements. Some, like stdio.h , come with the system, but you are free to create your own.

Including a large header file doesn't necessarily add much to the size of your program. The content of header files, for the most part, is information used by the compiler to generate the final code, not material to be added to the final code.

Header Files: An Example

Suppose you like using Boolean values. That is, instead of having 1 be true and be false, you prefer using the words TRUE and FALSE . You could create a file called, say, bool.h that contains these definitions:

 /* bool.h file */ #define BOOLEAN int  /* or typdef int BOOLEAN; */ #define TRUE 1 #define FALSE 0 

Listing 16.4 is an example of a program using this header.

Listing 16.4 The cnt_en.c program.

 /* cnt_en.c -- counts even numbers */ #include <stdio.h> #include <stdlib.h> #include "bool.h" BOOLEAN even_gt(int val, int lim); #define ASIZE 100 int main(void) {     int data[ASIZE];     int i;     int count = 0;     int num;     int num2;     printf("Enter a positive integer: ");     scanf("%d", &num);     num2 = num / 2;     for (i = 0; i < ASIZE; i++)         data[i] = rand() % num;     for (i = 0; i < ASIZE; i++)         if ( even_gt(data[i], num2))             count++;     printf("The sample of %d numbers contains ", ASIZE);     printf("%d even values greater than %d.\n", count, num2);     return 0; } /* returns true if val > lim and if val is even */ BOOLEAN even_gt(int val, int lim) {     if (val > lim && val %2 == 0)          return(TRUE);     else          return(FALSE); } 

Here is a sample run:

 Enter a positive integer:  500  The sample of 100 numbers contains 31 even values greater than 250. 

Note the following points about this program:

• If the two functions in this program, main() and even_gt() , were compiled separately, you would use the #include "bool.h" directive with each.

• We have not created a new type BOOLEAN because BOOLEAN is just int . The purpose of labeling the function BOOLEAN is to remind the programmer that the function is being used for a logical (as opposed to arithmetic) calculation.

• Using a function for involved logical comparisons can make a program clearer. It also can save effort if the comparison is made in more than one place in a program.

Uses for Header Files

A look through any of the standard header files can give you a good idea of the sort of information found in them. Typical header contents include the following:

• Manifest constants. A typical stdio.h file, for instance, defines EOF , NULL , and BUFSIZE (the size of the standard I/O buffer).

• Macro functions. For example, getchar() is usually defined as getc(stdin) , getc() is usually defined as a rather complex macro, and the ctype .h header typically contains macro definitions for the ctype functions.

• Function declarations. The string.h header ( strings.h on some older systems), for instance, contains function declarations for the family of string functions. Under ANSI C, the declarations are in function prototype form.

• Structure template definitions. The standard I/O functions make use of a structure containing information about a file and its associated buffer. The stdio.h file holds the template for this structure.

• Type definitions. You might recall that the standard I/O functions use a pointer-to- FILE argument. Typically, stdio.h uses a #define or a typedef to make file represent a pointer to a structure. Similarly, the size_t and time_t types are defined in header files.

Many programmers develop their own standard header files to use with their programs. Some files might be for special purposes; others might be used with almost every program. Because included files can incorporate #include directives, you can create concise , well-organized header files, if you like.

Consider this example:

 /* header file mystuff.h */ #include <stdio.h> #include "bool.h" #include "funct.h" #define YES 1 #define NO 0 

First, it's a good idea to use a comment to identify the name of the header file. Second, we have included three files. Presumably the third one contains some macro functions or function prototypes that we use often. Third, we have defined YES as 1 , although in bool.h we defined TRUE as 1 . There is no conflict here. We can use YES and TRUE in the same program. Each will be replaced by a 1 .

Also, you can use header files to declare external variables to be shared by several files. Some programmers think it's okay to do so. Others think it is poor style because you have to check another file to see whether a variable is declared. However, external data that is both static and const works well in header files. The const part protects against accidental changes, and the static part means that each file including the header gets its own copy of the constants so that there isn't the problem of needing one file with a defining declaration and the rest with reference declarations.

The #include and #define directives are the most heavily used C preprocessor features. We'll look at the other directives in less detail.

I l @ ve RuBoard