#define -- Preprocessing Directive

Define an identifier as a macro

The  preprocessing directive  #define tells  the  C preprocessor  to regard
identifier as a macro.

#define can define two kinds of macros: object-like, and function-like.

An object-like macro has the syntax

    #define identifier replacement-list

This type  of macro  is also called  a manifest constant.  The preprocessor
searches for  identifier throughout the  text of the  translation unit, and
replaces it with the  elements of replacement-list, 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 identifier is replaced  only once by a given replacement-list. 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 identifier lparen identifier-listopt ) replacement-list

The preprocessor  looks for identifier,  which is a macro  that resembles a
function in that  it is followed by a pair  of parentheses that may enclose
an   identifier-list.  It   replaces  identifier   with  the   contents  of
replacement-list, up to the first lparen `(' within replacement-list.

The preprocessor then examines identifier-list for further macros, which it
expands.  The  modified identifier-list is  then replaced with  the rest of
replacement-list. Pairs  of parentheses that are  nested between the lparen
that  begins replacement-list  and the  `)'  that ends  it are  copied into
identifier-list as literal  characters.  The identifiers within identifier-
list are preserved after it has been modified by replacement-list. 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.

Example

For an example of using a function-like macro in a program, see #.

See Also

#,
##,
#undef,
C preprocessor
ANSI Standard, §6.8.3

Notes

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 #define 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 #define
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.

© 2012 by Stephen A. Ness