Developer Documentation
PATH  Mac OS X Documentation > The GNU C Preprocessor

The GNU C Preprocessor

Previous | Contents | Next

Simple Macros

A simple macro is a kind of abbreviation--it's a name that stands for a fragment of code. Simple macros are sometimes referred to as manifest constants .

Before you can use a macro, you must define it explicitly with the #define command. #define is followed by the name of the macro and then the code it should be an abbreviation for. For example,

#define BUFFER_SIZE 1020

defines a macro named BUFFER_SIZE as an abbreviation for the text 1020 . With this definition in effect, the C preprocessor would expand the following statement

foo = (char *) xmalloc (BUFFER_SIZE);

to

foo = (char *) xmalloc (1020);

The definition must be a single line; however, it may not end in the middle of a multiline string constant or character constant.

For readability, uppercase is used for macro names by convention. Programs are easier to read when it's possible to tell at a glance which names are macros.

Normally, a macro definition must be a single line (although you can always split a long macro definition cosmetically with backslash-newline). There's one exception: Newlines can be included in the macro definition if they're within a string or character constant. It isn't possible for a macro definition to contain an unbalanced quote character; the definition automatically extends to include the matching quote character that ends the string or character constant. Comments within a macro definition may contain newlines (which make no difference, since the comments are entirely replaced with spaces regardless of their contents).

Aside from the above, there is no restriction on what can go in a macro body. Parentheses need not balance, and the body need not resemble valid C code. (Of course, you might get error messages from the C compiler when you use the macro.) However, tokens must be valid C tokens. For example, the symbol 1A would cause an error in both the compiler and the preprocessor.

The C preprocessor scans your program sequentially, so macro definitions take effect at the place you write them. Therefore, the following input to the C preprocessor

foo = X;
#define X 4
bar = X;

produces as output:

foo = X;
bar = 4;

After the preprocessor expands a macro name, the macro's definition body is appended to the front of the remaining input, and the check for macros continues. Therefore, the macro body can contain other macros. For example, after the following definitions

#define BUFSIZE 1020
#define TABLESIZE BUFSIZE

the name TABLESIZE when used in the program would go through two stages of expansion, resulting ultimately in 1020 .

This isn't the same as defining TABLESIZE to be 1020 . The #define for TABLESIZE uses exactly the body you specify--in this case, BUFSIZE --and doesn't check to see whether it too is the name of a macro. It's only when you use TABLESIZE that the result of its expansion is checked for more macro names. See the section " See Cascaded Use of Macros ."


The GNU C Preprocessor

Previous | Contents | Next