The#errordirective will cause the preprocessor to report a fatal error and halt. This can be used to trap conditions where there is an attempt to compile a program in some way that is known not to work. For example, the following will only compile successfully if the macro__unix__has been defined:
#ifndef __unix__
#error "This section will only work on UNIX systems"
#endif
The#warningdirective works the same as the#errordirective, except the condition is not fatal and the preprocessor continues after issuing the message.
#if, #elif, #else, and #endif
The#ifdirective evaluates an arithmetic expression and examines the result. If the result of the evaluation is not zero, it is considered to be true and the conditional code is compiled. Otherwise, the expression is considered to be false and the code is not compiled. For example, the following string is declared only if the value of theCOUNT macro has not been defined as zero:
#if COUNT
char *desc = "The count is non-zero";
#endif
The following is a list of characteristics and rules that apply to the expression and to the conditional directives:
■ The expression can include integer constants and macro names if the macro name has been declared with a value.
■ Parentheses can be used to specify the order of evaluation of the expression.
■ The expression can include arithmetic in the form of the+,-,*,/,<<,and>>
operators, which work much the same as the corresponding integer arithmetic operators in C. All arithmetic is performed as the largest integer size available on the platform, which is normally 64 bits.
■ The expression can include the comparison operators>,<,>=,<=,and==, which work the same as the corresponding operators in C.
■ The expression can include the logical operators&&and||.
■ The not (!) logical operator can be used to reverse the result of an expression.
For example, the following is true only ifLIMXPis not greater than 12:
#if !(LIMXP > 12)
■ Thedefinedoperator can be used to determine whether a macro has been defined. For example, the following is true only if a macro namedMINXPhas been defined:
#if defined(MINXP)
The not (!) operator is often used in conjunction with thedefinedoperator to test for a macro having not been defined, as in the following example:
#if !defined(MINXP)
USINGTHECOMPILERCOLLECTION
■ An identifier that has not been defined as a macro always results in zero. The -Wundefoption can be used to produce a warning in this circumstance.
■ Macro names defined as having arguments always evaluate to zero. The -Wundefoption can be used produce a warning in this circumstance.
■ An#elsedirective can be used to provide alternate code that will be compiled, as in the following example:
#if MINTXT <= 5
#define MINTLOG 11
#else
#define MINTLOG 14
#endif
■ An#elifdirective can be used to provide one or more alternative expressions, as in the following example:
#if MINTXT <= 5
#define MINTLOG 11
#elif MINTXT == 6
#define MINTLOG 12
#elif MINTXT == 7
#define MINTLOG 13
#else
#define MINTLOG 14
#endif
#ifdef, #else, and #endif
The lines of code following the#ifdefdirective are compiled only if the named macro has been defined. The#ifdefdirective is terminated by an#endif. For example, the following array is declared only if the macroMINTARRAYhas been defined:
#ifdef MINTARRAY int xarray[20];
#endif /* MINTARRAY */
The comment on the line with the#endifis not required, but it has been shown to be helpful in reading the code.
The inverse of the#ifdefdirective is the#ifndefdirective, which will compile the conditional code only if the macro hasnotbeen defined.
An#elsedirective can be used following an#ifdefto provide an alternative. In the following example, ifMINTARRAYhas been defined, the array will be of type int;
otherwise, it will be of type char:
USINGTHECOMPILERCOLLECTION
Other directives can be included as part of the code that is conditionally compiled.
This includes#ifdef,#ifndef, and#if, but each one must be properly paired with its own#endif.
#include
Theincludedirective searches for the named file and inserts its contents into the text just as if it had been inserted there by a text editor. A file that is included this way is generally referred to as aheaderfile and carries a .h suffix, but it can be any text file with any name.
Theincludedirective has two forms. The one most used for system header files surrounds the name with a pair of angle brackets, with the form for user header files being surrounded by quotes, as follows:
#include <syshead.h>
#include "userhead.h"
The following is a list of characteristics and rules that apply to the#include directive:
■ The angle brackets surrounding the file name cause the search to begin in any directories that were specified by using a-Ioption and then continue by looking through the standard set of system directories.
■ A pair of quotes surrounding the file name causes the search to begin in the current working directory (the one containing the source file being processed) and then continue with the directories that would normally be searched by a directive with the angle brackets.
■ On a UNIX system, the standard set of system directories is as follows:
/usr/local/include
/usr/lib/gcc-lib/target/version/include /usr/target/include
/usr/include
■ Two separate lists of directories are searched to locate header files. The standard system header files are in the second list. The-Icommand-line option adds directories to the list that is searched first. The options-prefix,-withprefix, and-idirafterall manipulate the directory names in the second list searched.
■ If GCC is compiling a C++ program, the directory/usr/include/g++v3is searched by the preprocessor before any of the other standard system directories.
■ A relative path name can be used as the name of the file. For example, if you specify#include <sys/time.h>,the filetime.hwill be sought in a subdirectory namedsysof all the standard directories.
■ The slash character is always interpreted as a path separator, even on systems that use a different character (such as a backslash) as the path separator. This way, it is always portable to use a slash for the path names.
■ The file name is taken literally. No macros are expanded and no characters have special meanings. If the name specified contains an asterisk or backslash character, the name of the file must contain a literal asterisk or backslash character.
■ A#definedirective can be used to specify the name of a header file, as in the following example:
#define BOGHEADER "bog_3.h"
#include BOGHEADER
■ It is an error to have anything other than a comment on the same line as the
#includedirective.
■ For the purposes of searching for files, the#linedirective does not change the current working directory.
■ The-I-option can be used to modify how the-Ioptions specify which directories are to be searched. See Appendix D for more information.