Developer --> Technical Publications
PATH  Mac OS X Server Documentation > The GNU C Preprocessor

The GNU C Preprocessor

Previous | Contents | Next

Macros that Take Arguments

A simple macro always stands for exactly the same text, each time it's used. Macros can be more flexible when they accept arguments. Arguments are fragments of code that you supply each time the macro is used. These fragments are included in the expansion of the macro according to the directions in the macro definition.

To define a macro that takes arguments, you use the #define command with a list of parameters in parentheses after the name of the macro. The parameters may be any valid C identifiers separated by commas at the top level (that is, commas that aren't within parentheses) and, optionally, by white-space characters. The left parenthesis must follow the macro name immediately, with no space in between.

For example, here's a macro that computes the minimum of two numeric values:

#define min(X, Y) ((X) < (Y) ? (X) : (Y))

Note that this isn't the best way to define a "minimum" macro in GNU C (see the section " See Duplication of Side Effects " for more information).

To use a macro that takes arguments, you write the name of the macro followed by a list of arguments in parentheses, separated by commas. The number of arguments you give must match the number of parameters in the macro definition. The following examples show the use of the macro min :

min (1, 2)
min (x + 28, *p)

The expansion text of the macro depends on the arguments you use. Each of the macro's parameters is replaced, throughout the macro definition, with the corresponding argument. Using the same macro min defined above, min (1, 2) expands to

((1) < (2) ? (1) : (2))

where 1 has been substituted for X and 2 for Y .

Likewise, min (x + 28, *p) expands into

((x + 28) < (*p) ? (x + 28) : (*p))

Parentheses in the arguments must balance; a comma within parentheses doesn't end an argument. However, there's no requirement for brackets or braces to balance; thus, if you want to supply

array[x = y, x + 1]

as an argument, you would write it as

array[(x = y, x + 1)]

After the arguments are substituted into the macro body, the entire result is appended to the front of the remaining input, and the check for macros continues. Therefore, the arguments can contain other macros, either with or without arguments, or even the same macro. The macro body can also contain other macros. For example, min (min (a, b), c) expands into

((((a) < (b) ? (a) : (b))) < (c)
? (((a) < (b) ? (a) : (b)))
: (c))

Line breaks shown here for clarity wouldn't actually be generated.

If a macro takes one argument, and you want to supply an empty argument, you must write at least some whitespace between the parentheses. For example

foo ( )

is acceptable, but

foo ()

generates an error if foo expects an argument.

The correct way to call a macro defined to take zero arguments is:

#define foo() . . . foo()

If you use the macro name followed by something other than a left parenthesis (after ignoring any spaces, tabs, and comments that follow), it isn't considered a macro invocation, and the preprocessor doesn't change what you've written. Therefore, it's possible for the same name to be a variable or function in your program as well as a macro, and you can choose in each instance whether to refer to the macro (if an argument list follows) or the variable or function (if an argument list doesn't follow).

Such dual use of one name could be confusing and should be avoided except when the two meanings are effectively synonymous: that is, when the name is both a macro and a function and the two have similar effects. You can think of the name simply as a function; use of the name for purposes other than calling it (such as, to take the address) will refer to the function, while calls will expand the macro. For example, you can use a function named min in the same source file that defines the macro. If you write &min with no argument list, you refer to the function. If you write min (x, bb) , with an argument list, the macro is expanded. If you write (min) (a, bb) , where the name min isn't followed by a left parenthesis, the macro isn't expanded; rather, the function min is called.

A name can't be defined as both a simple macro and a macro with arguments.

In the definition of a macro with arguments, the list of argument names must follow the macro name immediately with no space in between. If there is a space after the macro name, the macro is defined as taking no arguments, and the rest of the name is taken to be the expansion. The reason for this is that it's often useful to define a macro that takes no arguments and whose definition begins with an identifier in parentheses. This rule about spaces makes it possible for you to do either this (which defines FOO to take an argument and expand into minus the reciprocal of that argument)

#define FOO(x) - 1 / (x)

or this (which defines FOO to take no argument and always expand into (x) - 1 / (x) ):

#define FOO (x) - 1 / (x)

It matters only in the macro definition whether there's a space before the left parenthesis; when you use the macro, it doesn't matter if there are spaces there or not.


The GNU C Preprocessor

Previous | Contents | Next