1 # DP: cpp.texi: add a node documenting macro varargs.
3 Sat Aug 7 14:56:50 1999 Matthias Klose <doko@cs.tu-berlin.de>
5 * cpp.texi: cpp.texi: add a node documenting macro varargs (copied
8 --- gcc/cpp.texi~ Wed May 19 13:22:57 1999
9 +++ gcc/cpp.texi Sat Aug 7 14:53:42 1999
11 * Simple Macros:: Macros that always expand the same way.
12 * Argument Macros:: Macros that accept arguments that are substituted
13 into the macro expansion.
14 +* Macro Varargs:: Macros with variable number of arguments.
15 * Predefined:: Predefined macros that are always available.
16 * Stringification:: Macro arguments converted into string constants.
17 * Concatenation:: Building tokens from parts taken from macro arguments.
19 that the result of its expansion is checked for more macro names.
20 @xref{Cascaded Macros}.
22 -@node Argument Macros, Predefined, Simple Macros, Macros
23 +@node Argument Macros, Macro Varargs, Simple Macros, Macros
24 @subsection Macros with Arguments
25 @cindex macros with argument
26 @cindex arguments in macro definitions
28 the left parenthesis; it's the @emph{definition} where it matters whether
31 -@node Predefined, Stringification, Argument Macros, Macros
32 +@node Macro Varargs, Predefined, Argument Macros, Macros
33 +@subsection Macros with Variable Numbers of Arguments
34 +@cindex variable number of arguments
35 +@cindex macro with variable arguments
36 +@cindex rest argument (in macro)
38 +In GNU C, a macro can accept a variable number of arguments, much as a
39 +function can. The syntax for defining the macro looks much like that
40 +used for a function. Here is an example:
43 +#define eprintf(format, args...) \
44 + fprintf (stderr, format , ## args)
47 +Here @code{args} is a @dfn{rest argument}: it takes in zero or more
48 +arguments, as many as the call contains. All of them plus the commas
49 +between them form the value of @code{args}, which is substituted into
50 +the macro body where @code{args} is used. Thus, we have this expansion:
53 +eprintf ("%s:%d: ", input_file_name, line_number)
55 +fprintf (stderr, "%s:%d: " , input_file_name, line_number)
59 +Note that the comma after the string constant comes from the definition
60 +of @code{eprintf}, whereas the last comma comes from the value of
63 +The reason for using @samp{##} is to handle the case when @code{args}
64 +matches no arguments at all. In this case, @code{args} has an empty
65 +value. In this case, the second comma in the definition becomes an
66 +embarrassment: if it got through to the expansion of the macro, we would
67 +get something like this:
70 +fprintf (stderr, "success!\n" , )
74 +which is invalid C syntax. @samp{##} gets rid of the comma, so we get
75 +the following instead:
78 +fprintf (stderr, "success!\n")
81 +This is a special feature of the GNU C preprocessor: @samp{##} before a
82 +rest argument that is empty discards the preceding sequence of
83 +non-whitespace characters from the macro definition. (If another macro
84 +argument precedes, none of it is discarded.)
86 +It might be better to discard the last preprocessor token instead of the
87 +last preceding sequence of non-whitespace characters; in fact, we may
88 +someday change this feature to do so. We advise you to write the macro
89 +definition so that the preceding sequence of non-whitespace characters
90 +is just a single token, so that the meaning will not change if we change
91 +the definition of this feature.
93 +@node Predefined, Stringification, Macro Varargs, Macros
94 @subsection Predefined Macros
96 @cindex predefined macros