#ddeeffiinnee -- Preprocessing Directive

Define an identifier as a macro

The  preprocessing directive  #ddeeffiinnee tells  the  C preprocessor  to regard
_i_d_e_n_t_i_f_i_e_r as a macro.

#ddeeffiinnee can define two kinds of macros: _o_b_j_e_c_t-_l_i_k_e, and _f_u_n_c_t_i_o_n-_l_i_k_e.

An object-like macro has the syntax

    #define _i_d_e_n_t_i_f_i_e_r _r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t

This type  of macro  is also called  a _m_a_n_i_f_e_s_t _c_o_n_s_t_a_n_t.  The preprocessor
searches for  _i_d_e_n_t_i_f_i_e_r throughout the  text of the  translation unit, and
replaces it with the  elements of _r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t, which is then rescanned
for further macro substitutions.

For example, consider the directive:

    #define BUFFERSIZE 75

When the preprocessor reads the line

    malloc(BUFFERSIZE);

it replaces it with:

    malloc(75);

A given _i_d_e_n_t_i_f_i_e_r is replaced  only once by a given _r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t. This
is to prevent such code as

    #define FOO FOO

or

    #define FOO BAR
    #define BAR FOO

from generating an infinite loop.

A function-like macro is more complex.  It has the syntax:

    #define _i_d_e_n_t_i_f_i_e_r _l_p_a_r_e_n _i_d_e_n_t_i_f_i_e_r-_l_i_s_t9_o_p_t8 ) _r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t

The preprocessor  looks for _i_d_e_n_t_i_f_i_e_r,  which is a macro  that resembles a
function in that  it is followed by a pair  of parentheses that may enclose
an   _i_d_e_n_t_i_f_i_e_r-_l_i_s_t.  It   replaces  _i_d_e_n_t_i_f_i_e_r   with  the   contents  of
_r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t, up to the first lparen `(' within _r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t.

The preprocessor then examines _i_d_e_n_t_i_f_i_e_r-_l_i_s_t for further macros, which it
expands.  The  modified _i_d_e_n_t_i_f_i_e_r-_l_i_s_t is  then replaced with  the rest of
_r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t. Pairs  of parentheses that are  nested between the lparen
that  begins _r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t  and the  `)'  that ends  it are  copied into
_i_d_e_n_t_i_f_i_e_r-_l_i_s_t as literal  characters.  The identifiers within _i_d_e_n_t_i_f_i_e_r-
_l_i_s_t are preserved after it has been modified by _r_e_p_l_a_c_e_m_e_n_t-_l_i_s_t. The only
exceptions are identifiers that are prefixed by the preprocessing operators
# or ##; these are handled appropriately.

For example, the consider the macro:

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

When the preprocessor reads the following line

    display(abs(-5));

it replaces it with the following:

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

When an argument to a function-like macro contains no preprocessing tokens,
or when an argument to a function-like macro contains a preprocessing token
that is identical to a preprocessing directive, the behavior is undefined.

_E_x_a_m_p_l_e
For an example of using a function-like macro in a program, see #.

_S_e_e _A_l_s_o
#, ##, #uunnddeeff, CC pprreepprroocceessssoorr
ANSI Standard, section 6.8.3

_N_o_t_e_s
A  macro expansion  always occupies  exactly one line,  no matter  how many
lines are spanned by the definition  or the actual parameters.  If you have
defined macros that span more than  one line, you must either redefine them
to occupy one line, or somehow embed the newline character within the macro
itself; otherwise, the macro will not expand correctly.

A macro  definition can  extend over  more than one  line, provided  that a
backslash `\'  appears before the newline character  that breaks the lines.
The size of a #ddeeffiinnee directive is therefore limited by the maximum size of
a logical source line, which can be up to at least 509 characters long.

Some implementations allowed a user to re-define a macro with a new #ddeeffiinnee
directive.  The  Standard, however, allows only  a ``benign'' redefinition;
that  is,  the body  of  the  new definition  must  exactly  match the  old
definition, including parameter names and white space.
