CC pprreepprroocceessssoorr -- Overview

_P_r_e_p_r_o_c_e_s_s_i_n_g encompasses all  tasks that logically precede the translation
of  a program.   The preprocessor  processes  headers, expands  macros, and
conditionally includes or excludes source code.

_D_i_r_e_c_t_i_v_e_s
The C preprocessor recognizes the following directives:

#iiff.........Include code if a condition is true
#eelliiff.......Include code if directive is true
#eellssee.......Include code if preceding directives fail
#eennddiiff......End of code to be included conditionally

#iiffddeeff......Include code if a given macro is defined
#iiffnnddeeff.....Include code if a given macro is not defined

#ddeeffiinnee.....Define a macro
#uunnddeeff......Undefine a macro
#iinncclluuddee....Read another file and include it
#lliinnee.......Reset current line number

The  COHERENT preprocessor  also  recognizes the  directive #pprraaggmmaa,  which
performs implementation-specific  tasks.  See the Lexicon  entry on #pprraaggmmaa
for details.

A preprocessing  directive is always introduced by  the `#' character.  The
`#' must  be the first non-white  space character on a line,  but it may be
preceded by  white space and  it may be  separated from the  directive name
that follows it by one or more white space characters.

_P_r_e_p_r_o_c_e_s_s_i_n_g _O_p_e_r_a_t_o_r_s
The Standard defines two operators that are recognized by the preprocessor:
the ``stringize'' operator #,  and the ``token-paste'' operator ##. It also
defines a new keyword associated with preprocessor statements: ddeeffiinneedd.

The operator # indicates that the following argument is to be replaced by a
string literal;  this literal names  the preprocessing token  that replaces
the argument.  For example, consider the macro:

    #define display(x) show((long)(x), #x)

When the preprocessor reads the line

    display(abs(-5));

it replaces it with the following:

    show((long)(abs(-5)), "abs(-5)");

The ## operator performs ``token pasting''  -- that is, it joins two tokens
together, to create a single token.  For example, consider the macro:

    #define printvar(x) printf("%d\n", variable ## x)

When the preprocessor reads the line

    printvar(3);

it translates it into:

    printf("%d\n", variable3);

In  the past,  token  pasting had  been  performed by  inserting a  comment
between the tokens to be pasted.  This no longer works.

_P_r_e_d_e_f_i_n_e_d _M_a_c_r_o_s
The ANSI Standard describes the following macros that must be recognized by
the preprocessor:

    __DDAATTEE__  Date of translation
    __FFIILLEE__  Source-file name
    __LLIINNEE__  Current line within source file
    __SSTTDDCC__  Conforming translator and level
    __TTIIMMEE__  Time of translation

For more information on any one of these macros, see its entry.

_C_o_n_d_i_t_i_o_n_a_l _I_n_c_l_u_s_i_o_n
The preprocessor will conditionally include lines of code within a program.
The directives  that include code  conditionally are defined in  such a way
that you  can construct a chain of inclusion  directives to include exactly
the material you want.

The preprocessor keyword ddeeffiinneedd  determines whether a symbol is defined to
the #iiff preprocessor directive.  For example,

    #if defined(SYMBOL)

or

    #if defined SYMBOL

is equivalent to

    #ifdef SYMBOL

except that it can be used in more complex expressions, such as

    #if defined FOO && defined BAR && FOO==10

ddeeffiinneedd is recognized only in lines beginning with #iiff or #eelliiff.

Note that  ddeeffiinneedd is a preprocessor keyword,  not a preprocessor directive
or a C keyword.  You could,  for example, write a function called ddeeffiinneedd()
without any complaint from the C compiler.

The COHERENT preprocessor implicitly defines the following macros:

    __COHERENT__
    __MWC__
    __IEEE__
    __I386__

    _IEEE
    _I386
    MWC
    COHERENT

These can be used to include  conditionally code that applies to a specific
edition of COHERENT.  COHERENT 286 uses DECVAX floating-point code; whereas
COHERENT 386  uses IEEE.   If you were  writing code that  intensively used
floating-point  numbers  and you  wanted  to compile  the  code under  both
editions of COHERENT, you could write code of the form:

    #ifdef _DECVAX
        ...
    #elif _IEEE
        ...
    #endif

The C  preprocessor under  each edition of  COHERENT would ensure  that the
correct code was included for compilation.

_M_a_c_r_o _D_e_f_i_n_i_t_i_o_n _a_n_d _R_e_p_l_a_c_e_m_e_n_t
The preprocessor  performs simple types of macro  replacement.  To define a
macro,  use  the  preprocessor  directive  #ddeeffiinnee _i_d_e_n_t_i_f_i_e_r  _v_a_l_u_e.   The
preprocessor scans the  translation unit for preprocessor tokens that match
_i_d_e_n_t_i_f_i_e_r; when one is found, the preprocessor substitutes _v_a_l_u_e for it.

_I_n_c_l_u_s_i_o_n _o_f _M_a_c_r_o_s _o_r _F_u_n_c_t_i_o_n_s
The ANSI standard demands that every routine implemented as a macro also be
implemented as  a function, with  the exception of the  macro vvaa_aarrgg(). For
example,  COHERENT implements  the STDIO  routines ttoouuppppeerr()  and ttoolloowweerr()
both as macros and functions.

By default,  COHERENT uses the macro  version of routines.  To  force it to
use the  function of a routine,  you must undefine the  macro version.  You
can do  that either  by using the  preprocessor instruction #uunnddeeff  in your
code, or  by using the option  -UU on the cccc command  line.  For example, to
compel  COHERENT to  use  the function  version of  ttoolloowweerr(), include  the
statement

    #undef tolower

in your program, or include the argument

    -Utolower

on the cccc command line.

_c_p_p
Under COHERENT, C preprocessing is done  by the program ccpppp. The cccc command
runs ccpppp as  the first step in compiling a  C program.  ccpppp can also be run
by itself.

ccpppp reads each input _f_i_l_e;  it processes directives, and writes its product
on ssttddoouutt.

If its -EE option is not used, ccpppp also writes into its output statements of
the form #lliinnee _n _f_i_l_e_n_a_m_e,  so that  the parser cccc00  can connect  its error
messages and debugger output with  the original line numbers in your source
files.

See the Lexicon entry on ccpppp for more information.

_S_e_e _A_l_s_o
CC llaanngguuaaggee, cccc, ccpppp, ddeeffiinneedd, mmaaccrroo, mmaanniiffeesstt ccoonnssttaanntt
