![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to cpp.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [GCC 2.x] / gcc|
Return to cpp.texi CVS log | Up to [GCC 2.x] / gcc |
1.1 root 1: \input texinfo
2: @setfilename cpp.info
3: @settitle The C Preprocessor
4:
5: @ignore
6: @ifinfo
7: @format
8: START-INFO-DIR-ENTRY
9: * Cpp: (cpp). The C preprocessor.
10: END-INFO-DIR-ENTRY
11: @end format
12: @end ifinfo
13: @end ignore
14:
15: @c @smallbook
16: @c @cropmarks
17: @c @finalout
18: @setchapternewpage odd
19: @ifinfo
20: This file documents the GNU C Preprocessor.
21:
1.1.1.8 ! root 22: Copyright 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free Software
! 23: Foundation, Inc.
1.1 root 24:
25: Permission is granted to make and distribute verbatim copies of
26: this manual provided the copyright notice and this permission notice
27: are preserved on all copies.
28:
29: @ignore
30: Permission is granted to process this file through Tex and print the
31: results, provided the printed document carries copying permission
32: notice identical to this one except for the removal of this paragraph
33: (this paragraph not being relevant to the printed manual).
34:
35: @end ignore
36: Permission is granted to copy and distribute modified versions of this
37: manual under the conditions for verbatim copying, provided also that
38: the entire resulting derived work is distributed under the terms of a
39: permission notice identical to this one.
40:
41: Permission is granted to copy and distribute translations of this manual
42: into another language, under the above conditions for modified versions.
43: @end ifinfo
44:
45: @titlepage
46: @c @finalout
1.1.1.4 root 47: @title The C Preprocessor
48: @subtitle Last revised July 1992
49: @subtitle for GCC version 2
50: @author Richard M. Stallman
1.1 root 51: @page
52: @vskip 2pc
53: This booklet is eventually intended to form the first chapter of a GNU
54: C Language manual.
55:
56: @vskip 0pt plus 1filll
1.1.1.8 ! root 57: Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995 Free
! 58: Software Foundation, Inc.
1.1 root 59:
60: Permission is granted to make and distribute verbatim copies of
61: this manual provided the copyright notice and this permission notice
62: are preserved on all copies.
63:
64: Permission is granted to copy and distribute modified versions of this
65: manual under the conditions for verbatim copying, provided also that
66: the entire resulting derived work is distributed under the terms of a
67: permission notice identical to this one.
68:
69: Permission is granted to copy and distribute translations of this manual
70: into another language, under the above conditions for modified versions.
71: @end titlepage
72: @page
73:
74: @node Top, Global Actions,, (DIR)
75: @chapter The C Preprocessor
76:
77: The C preprocessor is a @dfn{macro processor} that is used automatically by
78: the C compiler to transform your program before actual compilation. It is
79: called a macro processor because it allows you to define @dfn{macros},
80: which are brief abbreviations for longer constructs.
81:
82: The C preprocessor provides four separate facilities that you can use as
83: you see fit:
84:
85: @itemize @bullet
86: @item
87: Inclusion of header files. These are files of declarations that can be
88: substituted into your program.
89:
90: @item
91: Macro expansion. You can define @dfn{macros}, which are abbreviations
92: for arbitrary fragments of C code, and then the C preprocessor will
93: replace the macros with their definitions throughout the program.
94:
95: @item
1.1.1.8 ! root 96: Conditional compilation. Using special preprocessing directives, you
1.1 root 97: can include or exclude parts of the program according to various
98: conditions.
99:
100: @item
101: Line control. If you use a program to combine or rearrange source files into
102: an intermediate file which is then compiled, you can use line control
103: to inform the compiler of where each source line originally came from.
104: @end itemize
105:
106: C preprocessors vary in some details. This manual discusses the GNU C
107: preprocessor, the C Compatible Compiler Preprocessor. The GNU C
108: preprocessor provides a superset of the features of ANSI Standard C.
109:
110: ANSI Standard C requires the rejection of many harmless constructs commonly
111: used by today's C programs. Such incompatibility would be inconvenient for
112: users, so the GNU C preprocessor is configured to accept these constructs
113: by default. Strictly speaking, to get ANSI Standard C, you must use the
114: options @samp{-trigraphs}, @samp{-undef} and @samp{-pedantic}, but in
115: practice the consequences of having strict ANSI Standard C make it
116: undesirable to do this. @xref{Invocation}.
117:
118: @menu
119: * Global Actions:: Actions made uniformly on all input files.
1.1.1.8 ! root 120: * Directives:: General syntax of preprocessing directives.
1.1 root 121: * Header Files:: How and why to use header files.
122: * Macros:: How and why to use macros.
123: * Conditionals:: How and why to use conditionals.
124: * Combining Sources:: Use of line control when you combine source files.
1.1.1.8 ! root 125: * Other Directives:: Miscellaneous preprocessing directives.
1.1 root 126: * Output:: Format of output from the C preprocessor.
127: * Invocation:: How to invoke the preprocessor; command options.
128: * Concept Index:: Index of concepts and terms.
1.1.1.8 ! root 129: * Index:: Index of directives, predefined macros and options.
1.1 root 130: @end menu
131:
1.1.1.8 ! root 132: @node Global Actions, Directives, Top, Top
1.1 root 133: @section Transformations Made Globally
134:
1.1.1.8 ! root 135: Most C preprocessor features are inactive unless you give specific directives
! 136: to request their use. (Preprocessing directives are lines starting with
! 137: @samp{#}; @pxref{Directives}). But there are three transformations that the
1.1 root 138: preprocessor always makes on all the input it receives, even in the absence
1.1.1.8 ! root 139: of directives.
1.1 root 140:
141: @itemize @bullet
142: @item
143: All C comments are replaced with single spaces.
144:
145: @item
146: Backslash-Newline sequences are deleted, no matter where. This
147: feature allows you to break long lines for cosmetic purposes without
148: changing their meaning.
149:
150: @item
151: Predefined macro names are replaced with their expansions
152: (@pxref{Predefined}).
153: @end itemize
154:
155: The first two transformations are done @emph{before} nearly all other parsing
1.1.1.8 ! root 156: and before preprocessing directives are recognized. Thus, for example, you
1.1 root 157: can split a line cosmetically with Backslash-Newline anywhere (except
158: when trigraphs are in use; see below).
159:
160: @example
161: /*
162: */ # /*
163: */ defi\
164: ne FO\
165: O 10\
166: 20
167: @end example
168:
169: @noindent
170: is equivalent into @samp{#define FOO 1020}. You can split even an escape
171: sequence with Backslash-Newline. For example, you can split @code{"foo\bar"}
172: between the @samp{\} and the @samp{b} to get
173:
174: @example
175: "foo\\
176: bar"
177: @end example
178:
179: @noindent
180: This behavior is unclean: in all other contexts, a Backslash can be
181: inserted in a string constant as an ordinary character by writing a double
182: Backslash, and this creates an exception. But the ANSI C standard requires
183: it. (Strict ANSI C does not allow Newlines in string constants, so they
184: do not consider this a problem.)
185:
186: But there are a few exceptions to all three transformations.
187:
188: @itemize @bullet
189: @item
190: C comments and predefined macro names are not recognized inside a
1.1.1.8 ! root 191: @samp{#include} directive in which the file name is delimited with
1.1 root 192: @samp{<} and @samp{>}.
193:
194: @item
195: C comments and predefined macro names are never recognized within a
196: character or string constant. (Strictly speaking, this is the rule,
197: not an exception, but it is worth noting here anyway.)
198:
199: @item
200: Backslash-Newline may not safely be used within an ANSI ``trigraph''.
201: Trigraphs are converted before Backslash-Newline is deleted. If you
202: write what looks like a trigraph with a Backslash-Newline inside, the
203: Backslash-Newline is deleted as usual, but it is then too late to
204: recognize the trigraph.
205:
206: This exception is relevant only if you use the @samp{-trigraphs}
207: option to enable trigraph processing. @xref{Invocation}.
208: @end itemize
209:
1.1.1.8 ! root 210: @node Directives, Header Files, Global Actions, Top
! 211: @section Preprocessing Directives
1.1 root 212:
1.1.1.8 ! root 213: @cindex preprocessing directives
! 214: @cindex directives
! 215: Most preprocessor features are active only if you use preprocessing directives
1.1 root 216: to request their use.
217:
1.1.1.8 ! root 218: Preprocessing directives are lines in your program that start with @samp{#}.
! 219: The @samp{#} is followed by an identifier that is the @dfn{directive name}.
! 220: For example, @samp{#define} is the directive that defines a macro.
1.1 root 221: Whitespace is also allowed before and after the @samp{#}.
222:
1.1.1.8 ! root 223: The set of valid directive names is fixed. Programs cannot define new
! 224: preprocessing directives.
1.1 root 225:
1.1.1.8 ! root 226: Some directive names require arguments; these make up the rest of the directive
! 227: line and must be separated from the directive name by whitespace. For example,
1.1 root 228: @samp{#define} must be followed by a macro name and the intended expansion
1.1.1.7 root 229: of the macro. @xref{Simple Macros}.
1.1 root 230:
1.1.1.8 ! root 231: A preprocessing directive cannot be more than one line in normal circumstances.
1.1 root 232: It may be split cosmetically with Backslash-Newline, but that has no effect
1.1.1.8 ! root 233: on its meaning. Comments containing Newlines can also divide the
! 234: directive into multiple lines, but the comments are changed to Spaces
! 235: before the directive is interpreted. The only way a significant Newline
! 236: can occur in a preprocessing directive is within a string constant or
! 237: character constant. Note that
1.1 root 238: most C compilers that might be applied to the output from the preprocessor
239: do not accept string or character constants containing Newlines.
240:
1.1.1.8 ! root 241: The @samp{#} and the directive name cannot come from a macro expansion. For
1.1 root 242: example, if @samp{foo} is defined as a macro expanding to @samp{define},
1.1.1.8 ! root 243: that does not make @samp{#foo} a valid preprocessing directive.
1.1 root 244:
1.1.1.8 ! root 245: @node Header Files, Macros, Directives, Top
1.1 root 246: @section Header Files
247:
248: @cindex header file
249: A header file is a file containing C declarations and macro definitions
250: (@pxref{Macros}) to be shared between several source files. You request
1.1.1.8 ! root 251: the use of a header file in your program with the C preprocessing directive
1.1 root 252: @samp{#include}.
253:
254: @menu
255: * Header Uses:: What header files are used for.
1.1.1.8 ! root 256: * Include Syntax:: How to write @samp{#include} directives.
1.1 root 257: * Include Operation:: What @samp{#include} does.
258: * Once-Only:: Preventing multiple inclusion of one header file.
259: * Inheritance:: Including one header file in another header file.
260: @end menu
261:
262: @node Header Uses, Include Syntax, Header Files, Header Files
263: @subsection Uses of Header Files
264:
265: Header files serve two kinds of purposes.
266:
267: @itemize @bullet
268: @item
269: @findex system header files
270: System header files declare the interfaces to parts of the operating
271: system. You include them in your program to supply the definitions and
272: declarations you need to invoke system calls and libraries.
273:
274: @item
275: Your own header files contain declarations for interfaces between the
276: source files of your program. Each time you have a group of related
277: declarations and macro definitions all or most of which are needed in
278: several different source files, it is a good idea to create a header
279: file for them.
280: @end itemize
281:
282: Including a header file produces the same results in C compilation as
283: copying the header file into each source file that needs it. But such
284: copying would be time-consuming and error-prone. With a header file, the
285: related declarations appear in only one place. If they need to be changed,
286: they can be changed in one place, and programs that include the header file
287: will automatically use the new version when next recompiled. The header
288: file eliminates the labor of finding and changing all the copies as well as
289: the risk that a failure to find one copy will result in inconsistencies
290: within a program.
291:
1.1.1.7 root 292: The usual convention is to give header files names that end with
293: @file{.h}. Avoid unusual characters in header file names, as they
294: reduce portability.
1.1 root 295:
296: @node Include Syntax, Include Operation, Header Uses, Header Files
1.1.1.8 ! root 297: @subsection The @samp{#include} Directive
1.1 root 298:
299: @findex #include
1.1.1.8 ! root 300: Both user and system header files are included using the preprocessing
! 301: directive @samp{#include}. It has three variants:
1.1 root 302:
303: @table @code
304: @item #include <@var{file}>
305: This variant is used for system header files. It searches for a file
306: named @var{file} in a list of directories specified by you, then in a
307: standard list of system directories. You specify directories to
308: search for header files with the command option @samp{-I}
309: (@pxref{Invocation}). The option @samp{-nostdinc} inhibits searching
310: the standard system directories; in this case only the directories
311: you specify are searched.
312:
313: The parsing of this form of @samp{#include} is slightly special
314: because comments are not recognized within the @samp{<@dots{}>}.
315: Thus, in @samp{#include <x/*y>} the @samp{/*} does not start a comment
1.1.1.8 ! root 316: and the directive specifies inclusion of a system header file named
1.1 root 317: @file{x/*y}. Of course, a header file with such a name is unlikely to
318: exist on Unix, where shell wildcard features would make it hard to
319: manipulate.@refill
320:
321: The argument @var{file} may not contain a @samp{>} character. It may,
322: however, contain a @samp{<} character.
323:
324: @item #include "@var{file}"
325: This variant is used for header files of your own program. It
326: searches for a file named @var{file} first in the current directory,
327: then in the same directories used for system header files. The
328: current directory is the directory of the current input file. It is
329: tried first because it is presumed to be the location of the files
330: that the current input file refers to. (If the @samp{-I-} option is
331: used, the special treatment of the current directory is inhibited.)
332:
333: The argument @var{file} may not contain @samp{"} characters. If
334: backslashes occur within @var{file}, they are considered ordinary text
335: characters, not escape characters. None of the character escape
336: sequences appropriate to string constants in C are processed. Thus,
337: @samp{#include "x\n\\y"} specifies a filename containing three
338: backslashes. It is not clear why this behavior is ever useful, but
339: the ANSI standard specifies it.
340:
341: @item #include @var{anything else}
1.1.1.7 root 342: @cindex computed @samp{#include}
1.1 root 343: This variant is called a @dfn{computed #include}. Any @samp{#include}
1.1.1.8 ! root 344: directive whose argument does not fit the above two forms is a computed
1.1 root 345: include. The text @var{anything else} is checked for macro calls,
346: which are expanded (@pxref{Macros}). When this is done, the result
347: must fit one of the above two variants---in particular, the expanded
348: text must in the end be surrounded by either quotes or angle braces.
349:
350: This feature allows you to define a macro which controls the file name
1.1.1.7 root 351: to be used at a later point in the program. One application of this is
352: to allow a site-specific configuration file for your program to specify
353: the names of the system include files to be used. This can help in
354: porting the program to various operating systems in which the necessary
355: system header files are found in different places.
1.1 root 356: @end table
357:
358: @node Include Operation, Once-Only, Include Syntax, Header Files
359: @subsection How @samp{#include} Works
360:
1.1.1.8 ! root 361: The @samp{#include} directive works by directing the C preprocessor to scan
1.1 root 362: the specified file as input before continuing with the rest of the current
363: file. The output from the preprocessor contains the output already
364: generated, followed by the output resulting from the included file,
365: followed by the output that comes from the text after the @samp{#include}
1.1.1.8 ! root 366: directive. For example, given a header file @file{header.h} as follows,
1.1.1.7 root 367:
368: @example
369: char *test ();
370: @end example
371:
372: @noindent
373: and a main program called @file{program.c} that uses the header file,
374: like this,
1.1 root 375:
376: @example
377: int x;
378: #include "header.h"
379:
380: main ()
381: @{
382: printf (test ());
383: @}
384: @end example
385:
386: @noindent
387: the output generated by the C preprocessor for @file{program.c} as input
388: would be
389:
390: @example
391: int x;
392: char *test ();
393:
394: main ()
395: @{
396: printf (test ());
397: @}
398: @end example
399:
400: Included files are not limited to declarations and macro definitions; those
401: are merely the typical uses. Any fragment of a C program can be included
402: from another file. The include file could even contain the beginning of a
403: statement that is concluded in the containing file, or the end of a
404: statement that was started in the including file. However, a comment or a
405: string or character constant may not start in the included file and finish
406: in the including file. An unterminated comment, string constant or
407: character constant in an included file is considered to end (with an error
408: message) at the end of the file.
409:
1.1.1.7 root 410: It is possible for a header file to begin or end a syntactic unit such
411: as a function definition, but that would be very confusing, so don't do
412: it.
413:
1.1.1.8 ! root 414: The line following the @samp{#include} directive is always treated as a
1.1 root 415: separate line by the C preprocessor even if the included file lacks a final
416: newline.
417:
418: @node Once-Only, Inheritance, Include Operation, Header Files
419: @subsection Once-Only Include Files
420: @cindex repeated inclusion
1.1.1.7 root 421: @cindex including just once
1.1 root 422:
423: Very often, one header file includes another. It can easily result that a
424: certain header file is included more than once. This may lead to errors,
425: if the header file defines structure types or typedefs, and is certainly
426: wasteful. Therefore, we often wish to prevent multiple inclusion of a
427: header file.
428:
429: The standard way to do this is to enclose the entire real contents of the
430: file in a conditional, like this:
431:
432: @example
1.1.1.7 root 433: #ifndef FILE_FOO_SEEN
434: #define FILE_FOO_SEEN
1.1 root 435:
436: @var{the entire file}
437:
1.1.1.7 root 438: #endif /* FILE_FOO_SEEN */
1.1 root 439: @end example
440:
1.1.1.7 root 441: The macro @code{FILE_FOO_SEEN} indicates that the file has been included
442: once already. In a user header file, the macro name should not begin
443: with @samp{_}. In a system header file, this name should begin with
444: @samp{__} to avoid conflicts with user programs. In any kind of header
445: file, the macro name should contain the name of the file and some
446: additional text, to avoid conflicts with other header files.
1.1 root 447:
448: The GNU C preprocessor is programmed to notice when a header file uses
449: this particular construct and handle it efficiently. If a header file
450: is contained entirely in a @samp{#ifndef} conditional, then it records
451: that fact. If a subsequent @samp{#include} specifies the same file,
452: and the macro in the @samp{#ifndef} is already defined, then the file
453: is entirely skipped, without even reading it.
454:
455: @findex #pragma once
1.1.1.8 ! root 456: There is also an explicit directive to tell the preprocessor that it need
1.1 root 457: not include a file more than once. This is called @samp{#pragma once},
458: and was used @emph{in addition to} the @samp{#ifndef} conditional around
459: the contents of the header file. @samp{#pragma once} is now obsolete
460: and should not be used at all.
461:
1.1.1.7 root 462: @findex #import
1.1 root 463: In the Objective C language, there is a variant of @samp{#include}
464: called @samp{#import} which includes a file, but does so at most once.
465: If you use @samp{#import} @emph{instead of} @samp{#include}, then you
466: don't need the conditionals inside the header file to prevent multiple
467: execution of the contents.
468:
1.1.1.7 root 469: @samp{#import} is obsolete because it is not a well designed feature.
1.1 root 470: It requires the users of a header file---the applications
471: programmers---to know that a certain header file should only be included
472: once. It is much better for the header file's implementor to write the
473: file so that users don't need to know this. Using @samp{#ifndef}
474: accomplishes this goal.
475:
476: @node Inheritance,, Once-Only, Header Files
1.1.1.7 root 477: @subsection Inheritance and Header Files
1.1 root 478: @cindex inheritance
479: @cindex overriding a header file
480:
481: @dfn{Inheritance} is what happens when one object or file derives some
482: of its contents by virtual copying from another object or file. In
483: the case of C header files, inheritance means that one header file
484: includes another header file and then replaces or adds something.
485:
486: If the inheriting header file and the base header file have different
487: names, then inheritance is straightforward: simply write @samp{#include
488: "@var{base}"} in the inheriting file.
489:
490: Sometimes it is necessary to give the inheriting file the same name as
491: the base file. This is less straightforward.
492:
493: For example, suppose an application program uses the system header file
494: @file{sys/signal.h}, but the version of @file{/usr/include/sys/signal.h}
495: on a particular system doesn't do what the application program expects.
1.1.1.3 root 496: It might be convenient to define a ``local'' version, perhaps under the
497: name @file{/usr/local/include/sys/signal.h}, to override or add to the
498: one supplied by the system.
1.1 root 499:
500: You can do this by using the option @samp{-I.} for compilation, and
501: writing a file @file{sys/signal.h} that does what the application
502: program expects. But making this file include the standard
503: @file{sys/signal.h} is not so easy---writing @samp{#include
504: <sys/signal.h>} in that file doesn't work, because it includes your own
505: version of the file, not the standard system version. Used in that file
506: itself, this leads to an infinite recursion and a fatal error in
507: compilation.
508:
509: @samp{#include </usr/include/sys/signal.h>} would find the proper file,
510: but that is not clean, since it makes an assumption about where the
511: system header file is found. This is bad for maintenance, since it
512: means that any change in where the system's header files are kept
513: requires a change somewhere else.
514:
515: @findex #include_next
1.1.1.2 root 516: The clean way to solve this problem is to use
1.1 root 517: @samp{#include_next}, which means, ``Include the @emph{next} file with
1.1.1.8 ! root 518: this name.'' This directive works like @samp{#include} except in
1.1 root 519: searching for the specified file: it starts searching the list of header
520: file directories @emph{after} the directory in which the current file
521: was found.
522:
1.1.1.2 root 523: Suppose you specify @samp{-I /usr/local/include}, and the list of
524: directories to search also includes @file{/usr/include}; and suppose that
525: both directories contain a file named @file{sys/signal.h}. Ordinary
526: @samp{#include <sys/signal.h>} finds the file under
527: @file{/usr/local/include}. If that file contains @samp{#include_next
528: <sys/signal.h>}, it starts searching after that directory, and finds the
529: file in @file{/usr/include}.
1.1 root 530:
531: @node Macros, Conditionals, Header Files, Top
532: @section Macros
533:
534: A macro is a sort of abbreviation which you can define once and then
535: use later. There are many complicated features associated with macros
536: in the C preprocessor.
537:
538: @menu
539: * Simple Macros:: Macros that always expand the same way.
540: * Argument Macros:: Macros that accept arguments that are substituted
541: into the macro expansion.
542: * Predefined:: Predefined macros that are always available.
543: * Stringification:: Macro arguments converted into string constants.
544: * Concatenation:: Building tokens from parts taken from macro arguments.
545: * Undefining:: Cancelling a macro's definition.
546: * Redefining:: Changing a macro's definition.
547: * Macro Pitfalls:: Macros can confuse the unwary. Here we explain
548: several common problems and strange features.
549: @end menu
550:
551: @node Simple Macros, Argument Macros, Macros, Macros
552: @subsection Simple Macros
1.1.1.7 root 553: @cindex simple macro
554: @cindex manifest constant
1.1 root 555:
556: A @dfn{simple macro} is a kind of abbreviation. It is a name which
557: stands for a fragment of code. Some people refer to these as
558: @dfn{manifest constants}.
559:
560: Before you can use a macro, you must @dfn{define} it explicitly with the
1.1.1.8 ! root 561: @samp{#define} directive. @samp{#define} is followed by the name of the
1.1 root 562: macro and then the code it should be an abbreviation for. For example,
563:
564: @example
565: #define BUFFER_SIZE 1020
566: @end example
567:
568: @noindent
569: defines a macro named @samp{BUFFER_SIZE} as an abbreviation for the text
1.1.1.8 ! root 570: @samp{1020}. If somewhere after this @samp{#define} directive there comes
1.1.1.7 root 571: a C statement of the form
1.1 root 572:
573: @example
574: foo = (char *) xmalloc (BUFFER_SIZE);
575: @end example
576:
577: @noindent
578: then the C preprocessor will recognize and @dfn{expand} the macro
579: @samp{BUFFER_SIZE}, resulting in
580:
581: @example
582: foo = (char *) xmalloc (1020);
583: @end example
584:
585: The use of all upper case for macro names is a standard convention.
586: Programs are easier to read when it is possible to tell at a glance which
587: names are macros.
588:
1.1.1.7 root 589: Normally, a macro definition must be a single line, like all C
1.1.1.8 ! root 590: preprocessing directives. (You can split a long macro definition
1.1.1.7 root 591: cosmetically with Backslash-Newline.) There is one exception: Newlines
592: can be included in the macro definition if within a string or character
593: constant. This is because it is not possible for a macro definition to
594: contain an unbalanced quote character; the definition automatically
595: extends to include the matching quote character that ends the string or
596: character constant. Comments within a macro definition may contain
597: Newlines, which make no difference since the comments are entirely
598: replaced with Spaces regardless of their contents.
1.1 root 599:
600: Aside from the above, there is no restriction on what can go in a macro
601: body. Parentheses need not balance. The body need not resemble valid C
1.1.1.7 root 602: code. (But if it does not, you may get error messages from the C
603: compiler when you use the macro.)
1.1 root 604:
605: The C preprocessor scans your program sequentially, so macro definitions
606: take effect at the place you write them. Therefore, the following input to
607: the C preprocessor
608:
609: @example
610: foo = X;
611: #define X 4
612: bar = X;
613: @end example
614:
615: @noindent
616: produces as output
617:
618: @example
619: foo = X;
620:
621: bar = 4;
622: @end example
623:
624: After the preprocessor expands a macro name, the macro's definition body is
625: appended to the front of the remaining input, and the check for macro calls
626: continues. Therefore, the macro body can contain calls to other macros.
627: For example, after
628:
629: @example
630: #define BUFSIZE 1020
631: #define TABLESIZE BUFSIZE
632: @end example
633:
634: @noindent
635: the name @samp{TABLESIZE} when used in the program would go through two
636: stages of expansion, resulting ultimately in @samp{1020}.
637:
638: This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
639: The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
640: specify---in this case, @samp{BUFSIZE}---and does not check to see whether
641: it too is the name of a macro. It's only when you @emph{use} @samp{TABLESIZE}
642: that the result of its expansion is checked for more macro names.
643: @xref{Cascaded Macros}.
644:
645: @node Argument Macros, Predefined, Simple Macros, Macros
646: @subsection Macros with Arguments
1.1.1.7 root 647: @cindex macros with argument
648: @cindex arguments in macro definitions
649: @cindex function-like macro
1.1 root 650:
651: A simple macro always stands for exactly the same text, each time it is
652: used. Macros can be more flexible when they accept @dfn{arguments}.
653: Arguments are fragments of code that you supply each time the macro is
1.1.1.7 root 654: used. These fragments are included in the expansion of the macro
655: according to the directions in the macro definition. A macro that
656: accepts arguments is called a @dfn{function-like macro} because the
657: syntax for using it looks like a function call.
1.1 root 658:
1.1.1.7 root 659: @findex #define
1.1.1.8 ! root 660: To define a macro that uses arguments, you write a @samp{#define} directive
1.1 root 661: with a list of @dfn{argument names} in parentheses after the name of the
662: macro. The argument names may be any valid C identifiers, separated by
663: commas and optionally whitespace. The open-parenthesis must follow the
664: macro name immediately, with no space in between.
665:
666: For example, here is a macro that computes the minimum of two numeric
667: values, as it is defined in many C programs:
668:
669: @example
670: #define min(X, Y) ((X) < (Y) ? (X) : (Y))
671: @end example
672:
673: @noindent
674: (This is not the best way to define a ``minimum'' macro in GNU C.
675: @xref{Side Effects}, for more information.)
676:
677: To use a macro that expects arguments, you write the name of the macro
1.1.1.5 root 678: followed by a list of @dfn{actual arguments} in parentheses, separated by
1.1 root 679: commas. The number of actual arguments you give must match the number of
680: arguments the macro expects. Examples of use of the macro @samp{min}
681: include @samp{min (1, 2)} and @samp{min (x + 28, *p)}.
682:
683: The expansion text of the macro depends on the arguments you use.
684: Each of the argument names of the macro is replaced, throughout the
685: macro definition, with the corresponding actual argument. Using the
686: same macro @samp{min} defined above, @samp{min (1, 2)} expands into
687:
688: @example
689: ((1) < (2) ? (1) : (2))
690: @end example
691:
692: @noindent
693: where @samp{1} has been substituted for @samp{X} and @samp{2} for @samp{Y}.
694:
695: Likewise, @samp{min (x + 28, *p)} expands into
696:
697: @example
698: ((x + 28) < (*p) ? (x + 28) : (*p))
699: @end example
700:
701: Parentheses in the actual arguments must balance; a comma within
702: parentheses does not end an argument. However, there is no requirement
703: for brackets or braces to balance, and they do not prevent a comma from
704: separating arguments. Thus,
705:
706: @example
707: macro (array[x = y, x + 1])
708: @end example
709:
710: @noindent
711: passes two arguments to @code{macro}: @samp{array[x = y} and @samp{x +
712: 1]}. If you want to supply @samp{array[x = y, x + 1]} as an argument,
713: you must write it as @samp{array[(x = y, x + 1)]}, which is equivalent C
714: code.
715:
716: After the actual arguments are substituted into the macro body, the entire
717: result is appended to the front of the remaining input, and the check for
718: macro calls continues. Therefore, the actual arguments can contain calls
719: to other macros, either with or without arguments, or even to the same
720: macro. The macro body can also contain calls to other macros. For
721: example, @samp{min (min (a, b), c)} expands into this text:
722:
723: @example
724: ((((a) < (b) ? (a) : (b))) < (c)
725: ? (((a) < (b) ? (a) : (b)))
726: : (c))
727: @end example
728:
729: @noindent
730: (Line breaks shown here for clarity would not actually be generated.)
731:
1.1.1.7 root 732: @cindex blank macro arguments
733: @cindex space as macro argument
1.1.1.4 root 734: If a macro @code{foo} takes one argument, and you want to supply an
735: empty argument, you must write at least some whitespace between the
736: parentheses, like this: @samp{foo ( )}. Just @samp{foo ()} is providing
737: no arguments, which is an error if @code{foo} expects an argument. But
738: @samp{foo0 ()} is the correct way to call a macro defined to take zero
739: arguments, like this:
740:
741: @example
742: #define foo0() @dots{}
743: @end example
744:
1.1 root 745: If you use the macro name followed by something other than an
746: open-parenthesis (after ignoring any spaces, tabs and comments that
747: follow), it is not a call to the macro, and the preprocessor does not
748: change what you have written. Therefore, it is possible for the same name
749: to be a variable or function in your program as well as a macro, and you
750: can choose in each instance whether to refer to the macro (if an actual
751: argument list follows) or the variable or function (if an argument list
752: does not follow).
753:
754: Such dual use of one name could be confusing and should be avoided
755: except when the two meanings are effectively synonymous: that is, when the
756: name is both a macro and a function and the two have similar effects. You
757: can think of the name simply as a function; use of the name for purposes
758: other than calling it (such as, to take the address) will refer to the
759: function, while calls will expand the macro and generate better but
760: equivalent code. For example, you can use a function named @samp{min} in
761: the same source file that defines the macro. If you write @samp{&min} with
762: no argument list, you refer to the function. If you write @samp{min (x,
763: bb)}, with an argument list, the macro is expanded. If you write
764: @samp{(min) (a, bb)}, where the name @samp{min} is not followed by an
765: open-parenthesis, the macro is not expanded, so you wind up with a call to
766: the function @samp{min}.
767:
768: You may not define the same name as both a simple macro and a macro with
769: arguments.
770:
771: In the definition of a macro with arguments, the list of argument names
772: must follow the macro name immediately with no space in between. If there
773: is a space after the macro name, the macro is defined as taking no
1.1.1.4 root 774: arguments, and all the rest of the line is taken to be the expansion. The
1.1 root 775: reason for this is that it is often useful to define a macro that takes no
776: arguments and whose definition begins with an identifier in parentheses.
777: This rule about spaces makes it possible for you to do either this:
778:
779: @example
780: #define FOO(x) - 1 / (x)
781: @end example
782:
783: @noindent
784: (which defines @samp{FOO} to take an argument and expand into minus the
785: reciprocal of that argument) or this:
786:
787: @example
788: #define BAR (x) - 1 / (x)
789: @end example
790:
791: @noindent
792: (which defines @samp{BAR} to take no argument and always expand into
793: @samp{(x) - 1 / (x)}).
794:
795: Note that the @emph{uses} of a macro with arguments can have spaces before
796: the left parenthesis; it's the @emph{definition} where it matters whether
797: there is a space.
798:
799: @node Predefined, Stringification, Argument Macros, Macros
800: @subsection Predefined Macros
801:
802: @cindex predefined macros
803: Several simple macros are predefined. You can use them without giving
804: definitions for them. They fall into two classes: standard macros and
805: system-specific macros.
806:
807: @menu
808: * Standard Predefined:: Standard predefined macros.
809: * Nonstandard Predefined:: Nonstandard predefined macros.
810: @end menu
811:
812: @node Standard Predefined, Nonstandard Predefined, Predefined, Predefined
813: @subsubsection Standard Predefined Macros
1.1.1.7 root 814: @cindex standard predefined macros
1.1 root 815:
816: The standard predefined macros are available with the same meanings
817: regardless of the machine or operating system on which you are using GNU C.
818: Their names all start and end with double underscores. Those preceding
819: @code{__GNUC__} in this table are standardized by ANSI C; the rest are
820: GNU C extensions.
821:
822: @table @code
823: @item __FILE__
824: @findex __FILE__
825: This macro expands to the name of the current input file, in the form of
826: a C string constant. The precise name returned is the one that was
827: specified in @samp{#include} or as the input file name argument.
828:
829: @item __LINE__
830: @findex __LINE__
831: This macro expands to the current input line number, in the form of a
832: decimal integer constant. While we call it a predefined macro, it's
833: a pretty strange macro, since its ``definition'' changes with each
834: new line of source code.
835:
836: This and @samp{__FILE__} are useful in generating an error message to
837: report an inconsistency detected by the program; the message can state
838: the source line at which the inconsistency was detected. For example,
839:
840: @smallexample
841: fprintf (stderr, "Internal error: "
1.1.1.7 root 842: "negative string length "
1.1 root 843: "%d at %s, line %d.",
844: length, __FILE__, __LINE__);
845: @end smallexample
846:
1.1.1.8 ! root 847: A @samp{#include} directive changes the expansions of @samp{__FILE__}
1.1 root 848: and @samp{__LINE__} to correspond to the included file. At the end of
849: that file, when processing resumes on the input file that contained
1.1.1.8 ! root 850: the @samp{#include} directive, the expansions of @samp{__FILE__} and
1.1 root 851: @samp{__LINE__} revert to the values they had before the
852: @samp{#include} (but @samp{__LINE__} is then incremented by one as
853: processing moves to the line after the @samp{#include}).
854:
855: The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered
1.1.1.8 ! root 856: if a @samp{#line} directive is used. @xref{Combining Sources}.
1.1.1.2 root 857:
1.1 root 858: @item __DATE__
859: @findex __DATE__
860: This macro expands to a string constant that describes the date on
861: which the preprocessor is being run. The string constant contains
862: eleven characters and looks like @samp{"Jan 29 1987"} or @w{@samp{"Apr
863: 1 1905"}}.
864:
865: @item __TIME__
866: @findex __TIME__
867: This macro expands to a string constant that describes the time at
868: which the preprocessor is being run. The string constant contains
869: eight characters and looks like @samp{"23:59:01"}.
870:
871: @item __STDC__
872: @findex __STDC__
873: This macro expands to the constant 1, to signify that this is ANSI
874: Standard C. (Whether that is actually true depends on what C compiler
875: will operate on the output from the preprocessor.)
876:
1.1.1.8 ! root 877: @item __STDC_VERSION__
! 878: @findex __STDC_VERSION__
! 879: This macro expands to the C Standard's version number,
! 880: a long integer constant of the form @samp{@var{yyyy}@var{mm}L}
! 881: where @var{yyyy} and @var{mm} are the year and month of the Standard version.
! 882: This signifies which version of the C Standard the preprocessor conforms to.
! 883: Like @samp{__STDC__}, whether this version number is accurate
! 884: for the entire implementation depends on what C compiler
! 885: will operate on the output from the preprocessor.
! 886:
1.1 root 887: @item __GNUC__
1.1.1.7 root 888: @findex __GNUC__
1.1 root 889: This macro is defined if and only if this is GNU C. This macro is
1.1.1.7 root 890: defined only when the entire GNU C compiler is in use; if you invoke the
891: preprocessor directly, @samp{__GNUC__} is undefined. The value
892: identifies the major version number of GNU CC (@samp{1} for GNU CC
893: version 1, which is now obsolete, and @samp{2} for version 2).
1.1 root 894:
1.1.1.8 ! root 895: @item __GNUC_MINOR__
! 896: @findex __GNUC_MINOR__
! 897: The macro contains the minor version number of the compiler. This can
! 898: be used to work around differences between different releases of the
! 899: compiler (for example, if gcc 2.6.3 is known to support a feature, you
! 900: can test for @code{__GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 6)}).
! 901: The last number, @samp{3} in the
! 902: example above, denotes the bugfix level of the compiler; no macro
! 903: contains this value.
! 904:
1.1.1.5 root 905: @item __GNUG__
1.1.1.7 root 906: @findex __GNUG__
1.1.1.5 root 907: The GNU C compiler defines this when the compilation language is
908: C++; use @samp{__GNUG__} to distinguish between GNU C and GNU
909: C++.
910:
911: @item __cplusplus
1.1.1.7 root 912: @findex __cplusplus
1.1.1.5 root 913: The draft ANSI standard for C++ used to require predefining this
914: variable. Though it is no longer required, GNU C++ continues to define
915: it, as do other popular C++ compilers. You can use @samp{__cplusplus}
916: to test whether a header is compiled by a C compiler or a C++ compiler.
917:
1.1 root 918: @item __STRICT_ANSI__
1.1.1.7 root 919: @findex __STRICT_ANSI__
1.1 root 920: This macro is defined if and only if the @samp{-ansi} switch was
921: specified when GNU C was invoked. Its definition is the null string.
922: This macro exists primarily to direct certain GNU header files not to
923: define certain traditional Unix constructs which are incompatible with
924: ANSI C.
925:
1.1.1.3 root 926: @item __BASE_FILE__
927: @findex __BASE_FILE__
928: This macro expands to the name of the main input file, in the form
929: of a C string constant. This is the source file that was specified
930: as an argument when the C compiler was invoked.
931:
1.1.1.8 ! root 932: @item __INCLUDE_LEVEL__
! 933: @findex __INCLUDE_LEVEL_
! 934: This macro expands to a decimal integer constant that represents the
! 935: depth of nesting in include files. The value of this macro is
! 936: incremented on every @samp{#include} directive and decremented at every
! 937: end of file. For input files specified by command line arguments,
! 938: the nesting level is zero.
! 939:
1.1 root 940: @item __VERSION__
1.1.1.7 root 941: @findex __VERSION__
1.1 root 942: This macro expands to a string which describes the version number of
943: GNU C. The string is normally a sequence of decimal numbers separated
1.1.1.7 root 944: by periods, such as @samp{"2.6.0"}. The only reasonable use of this
1.1 root 945: macro is to incorporate it into a string constant.
946:
947: @item __OPTIMIZE__
1.1.1.7 root 948: @findex __OPTIMIZE__
1.1 root 949: This macro is defined in optimizing compilations. It causes certain
950: GNU header files to define alternative macro definitions for some
951: system library functions. It is unwise to refer to or test the
952: definition of this macro unless you make very sure that programs will
953: execute with the same effect regardless.
954:
955: @item __CHAR_UNSIGNED__
1.1.1.7 root 956: @findex __CHAR_UNSIGNED__
1.1 root 957: This macro is defined if and only if the data type @code{char} is
958: unsigned on the target machine. It exists to cause the standard
959: header file @file{limit.h} to work correctly. It is bad practice
960: to refer to this macro yourself; instead, refer to the standard
961: macros defined in @file{limit.h}. The preprocessor uses
962: this macro to determine whether or not to sign-extend large character
1.1.1.8 ! root 963: constants written in octal; see @ref{#if Directive,,The @samp{#if} Directive}.
! 964:
! 965: @item __REGISTER_PREFIX__
! 966: @findex __REGISTER_PREFIX__
! 967: This macro expands to a string describing the prefix applied to cpu
! 968: registers in assembler code. It can be used to write assembler code
! 969: that is usable in multiple environments. For example, in the
! 970: @samp{m68k-aout} environment it expands to the string @samp{""},
! 971: but in the @samp{m68k-coff} environment it expands to the string
! 972: @samp{"%"}.
! 973:
! 974: @item __USER_LABEL_PREFIX__
! 975: @findex __USER_LABEL_PREFIX__
! 976: This macro expands to a string describing the prefix applied to
! 977: user generated labels in assembler code. It can be used to write
! 978: assembler code that is usable in multiple environments.
! 979: For example, in the @samp{m68k-aout} environment it expands to the
! 980: string @samp{"_"}, but in the @samp{m68k-coff} environment it expands
! 981: to the string @samp{""}.
1.1 root 982: @end table
983:
984: @node Nonstandard Predefined,, Standard Predefined, Predefined
985: @subsubsection Nonstandard Predefined Macros
986:
987: The C preprocessor normally has several predefined macros that vary between
988: machines because their purpose is to indicate what type of system and
989: machine is in use. This manual, being for all systems and machines, cannot
990: tell you exactly what their names are; instead, we offer a list of some
991: typical ones. You can use @samp{cpp -dM} to see the values of
1.1.1.7 root 992: predefined macros; see @ref{Invocation}.
1.1 root 993:
994: Some nonstandard predefined macros describe the operating system in use,
995: with more or less specificity. For example,
996:
997: @table @code
998: @item unix
999: @findex unix
1000: @samp{unix} is normally predefined on all Unix systems.
1001:
1002: @item BSD
1003: @findex BSD
1004: @samp{BSD} is predefined on recent versions of Berkeley Unix
1005: (perhaps only in version 4.3).
1006: @end table
1007:
1008: Other nonstandard predefined macros describe the kind of CPU, with more or
1009: less specificity. For example,
1010:
1011: @table @code
1012: @item vax
1013: @findex vax
1014: @samp{vax} is predefined on Vax computers.
1015:
1016: @item mc68000
1017: @findex mc68000
1018: @samp{mc68000} is predefined on most computers whose CPU is a Motorola
1019: 68000, 68010 or 68020.
1020:
1021: @item m68k
1022: @findex m68k
1023: @samp{m68k} is also predefined on most computers whose CPU is a 68000,
1024: 68010 or 68020; however, some makers use @samp{mc68000} and some use
1025: @samp{m68k}. Some predefine both names. What happens in GNU C
1026: depends on the system you are using it on.
1027:
1028: @item M68020
1029: @findex M68020
1030: @samp{M68020} has been observed to be predefined on some systems that
1031: use 68020 CPUs---in addition to @samp{mc68000} and @samp{m68k}, which
1032: are less specific.
1033:
1034: @item _AM29K
1035: @findex _AM29K
1036: @itemx _AM29000
1037: @findex _AM29000
1038: Both @samp{_AM29K} and @samp{_AM29000} are predefined for the AMD 29000
1039: CPU family.
1040:
1041: @item ns32000
1042: @findex ns32000
1043: @samp{ns32000} is predefined on computers which use the National
1044: Semiconductor 32000 series CPU.
1045: @end table
1046:
1047: Yet other nonstandard predefined macros describe the manufacturer of
1048: the system. For example,
1049:
1050: @table @code
1051: @item sun
1052: @findex sun
1053: @samp{sun} is predefined on all models of Sun computers.
1054:
1055: @item pyr
1056: @findex pyr
1057: @samp{pyr} is predefined on all models of Pyramid computers.
1058:
1059: @item sequent
1060: @findex sequent
1061: @samp{sequent} is predefined on all models of Sequent computers.
1062: @end table
1063:
1064: These predefined symbols are not only nonstandard, they are contrary to the
1065: ANSI standard because their names do not start with underscores.
1066: Therefore, the option @samp{-ansi} inhibits the definition of these
1067: symbols.
1068:
1069: This tends to make @samp{-ansi} useless, since many programs depend on the
1070: customary nonstandard predefined symbols. Even system header files check
1071: them and will generate incorrect declarations if they do not find the names
1072: that are expected. You might think that the header files supplied for the
1073: Uglix computer would not need to test what machine they are running on,
1074: because they can simply assume it is the Uglix; but often they do, and they
1075: do so using the customary names. As a result, very few C programs will
1076: compile with @samp{-ansi}. We intend to avoid such problems on the GNU
1077: system.
1078:
1079: What, then, should you do in an ANSI C program to test the type of machine
1080: it will run on?
1081:
1082: GNU C offers a parallel series of symbols for this purpose, whose names
1083: are made from the customary ones by adding @samp{__} at the beginning
1.1.1.3 root 1084: and end. Thus, the symbol @code{__vax__} would be available on a Vax,
1.1 root 1085: and so on.
1086:
1087: The set of nonstandard predefined names in the GNU C preprocessor is
1088: controlled (when @code{cpp} is itself compiled) by the macro
1089: @samp{CPP_PREDEFINES}, which should be a string containing @samp{-D}
1090: options, separated by spaces. For example, on the Sun 3, we use the
1091: following definition:
1092:
1093: @example
1094: #define CPP_PREDEFINES "-Dmc68000 -Dsun -Dunix -Dm68k"
1095: @end example
1096:
1097: @noindent
1098: This macro is usually specified in @file{tm.h}.
1099:
1100: @node Stringification, Concatenation, Predefined, Macros
1101: @subsection Stringification
1102:
1103: @cindex stringification
1104: @dfn{Stringification} means turning a code fragment into a string constant
1105: whose contents are the text for the code fragment. For example,
1106: stringifying @samp{foo (z)} results in @samp{"foo (z)"}.
1107:
1108: In the C preprocessor, stringification is an option available when macro
1109: arguments are substituted into the macro definition. In the body of the
1110: definition, when an argument name appears, the character @samp{#} before
1111: the name specifies stringification of the corresponding actual argument
1112: when it is substituted at that point in the definition. The same argument
1113: may be substituted in other places in the definition without
1114: stringification if the argument name appears in those places with no
1115: @samp{#}.
1116:
1117: Here is an example of a macro definition that uses stringification:
1118:
1119: @smallexample
1.1.1.7 root 1120: @group
1.1 root 1121: #define WARN_IF(EXP) \
1122: do @{ if (EXP) \
1123: fprintf (stderr, "Warning: " #EXP "\n"); @} \
1124: while (0)
1.1.1.7 root 1125: @end group
1.1 root 1126: @end smallexample
1127:
1128: @noindent
1129: Here the actual argument for @samp{EXP} is substituted once as given,
1130: into the @samp{if} statement, and once as stringified, into the
1131: argument to @samp{fprintf}. The @samp{do} and @samp{while (0)} are
1132: a kludge to make it possible to write @samp{WARN_IF (@var{arg});},
1133: which the resemblance of @samp{WARN_IF} to a function would make
1.1.1.7 root 1134: C programmers want to do; see @ref{Swallow Semicolon}.
1.1 root 1135:
1136: The stringification feature is limited to transforming one macro argument
1137: into one string constant: there is no way to combine the argument with
1138: other text and then stringify it all together. But the example above shows
1139: how an equivalent result can be obtained in ANSI Standard C using the
1140: feature that adjacent string constants are concatenated as one string
1.1.1.4 root 1141: constant. The preprocessor stringifies the actual value of @samp{EXP}
1.1 root 1142: into a separate string constant, resulting in text like
1143:
1144: @smallexample
1.1.1.7 root 1145: @group
1.1 root 1146: do @{ if (x == 0) \
1147: fprintf (stderr, "Warning: " "x == 0" "\n"); @} \
1148: while (0)
1.1.1.7 root 1149: @end group
1.1 root 1150: @end smallexample
1151:
1152: @noindent
1153: but the C compiler then sees three consecutive string constants and
1154: concatenates them into one, producing effectively
1155:
1156: @smallexample
1157: do @{ if (x == 0) \
1158: fprintf (stderr, "Warning: x == 0\n"); @} \
1159: while (0)
1160: @end smallexample
1161:
1162: Stringification in C involves more than putting doublequote characters
1163: around the fragment; it is necessary to put backslashes in front of all
1164: doublequote characters, and all backslashes in string and character
1165: constants, in order to get a valid C string constant with the proper
1166: contents. Thus, stringifying @samp{p = "foo\n";} results in @samp{"p =
1167: \"foo\\n\";"}. However, backslashes that are not inside of string or
1168: character constants are not duplicated: @samp{\n} by itself stringifies to
1169: @samp{"\n"}.
1170:
1171: Whitespace (including comments) in the text being stringified is handled
1172: according to precise rules. All leading and trailing whitespace is ignored.
1173: Any sequence of whitespace in the middle of the text is converted to
1174: a single space in the stringified result.
1175:
1176: @node Concatenation, Undefining, Stringification, Macros
1177: @subsection Concatenation
1178: @cindex concatenation
1.1.1.7 root 1179: @cindex @samp{##}
1.1 root 1180: @dfn{Concatenation} means joining two strings into one. In the context
1181: of macro expansion, concatenation refers to joining two lexical units
1182: into one longer one. Specifically, an actual argument to the macro can be
1183: concatenated with another actual argument or with fixed text to produce
1184: a longer name. The longer name might be the name of a function,
1185: variable or type, or a C keyword; it might even be the name of another
1186: macro, in which case it will be expanded.
1187:
1188: When you define a macro, you request concatenation with the special
1189: operator @samp{##} in the macro body. When the macro is called,
1190: after actual arguments are substituted, all @samp{##} operators are
1191: deleted, and so is any whitespace next to them (including whitespace
1192: that was part of an actual argument). The result is to concatenate
1193: the syntactic tokens on either side of the @samp{##}.
1194:
1195: Consider a C program that interprets named commands. There probably needs
1196: to be a table of commands, perhaps an array of structures declared as
1197: follows:
1198:
1199: @example
1200: struct command
1201: @{
1202: char *name;
1203: void (*function) ();
1204: @};
1205:
1206: struct command commands[] =
1207: @{
1208: @{ "quit", quit_command@},
1209: @{ "help", help_command@},
1210: @dots{}
1211: @};
1212: @end example
1213:
1214: It would be cleaner not to have to give each command name twice, once in
1215: the string constant and once in the function name. A macro which takes the
1216: name of a command as an argument can make this unnecessary. The string
1217: constant can be created with stringification, and the function name by
1218: concatenating the argument with @samp{_command}. Here is how it is done:
1219:
1220: @example
1221: #define COMMAND(NAME) @{ #NAME, NAME ## _command @}
1222:
1223: struct command commands[] =
1224: @{
1225: COMMAND (quit),
1226: COMMAND (help),
1227: @dots{}
1228: @};
1229: @end example
1230:
1231: The usual case of concatenation is concatenating two names (or a name and a
1232: number) into a longer name. But this isn't the only valid case. It is
1233: also possible to concatenate two numbers (or a number and a name, such as
1234: @samp{1.5} and @samp{e3}) into a number. Also, multi-character operators
1235: such as @samp{+=} can be formed by concatenation. In some cases it is even
1236: possible to piece together a string constant. However, two pieces of text
1237: that don't together form a valid lexical unit cannot be concatenated. For
1238: example, concatenation with @samp{x} on one side and @samp{+} on the other
1239: is not meaningful because those two characters can't fit together in any
1240: lexical unit of C. The ANSI standard says that such attempts at
1241: concatenation are undefined, but in the GNU C preprocessor it is well
1242: defined: it puts the @samp{x} and @samp{+} side by side with no particular
1243: special results.
1244:
1245: Keep in mind that the C preprocessor converts comments to whitespace before
1246: macros are even considered. Therefore, you cannot create a comment by
1247: concatenating @samp{/} and @samp{*}: the @samp{/*} sequence that starts a
1248: comment is not a lexical unit, but rather the beginning of a ``long'' space
1249: character. Also, you can freely use comments next to a @samp{##} in a
1250: macro definition, or in actual arguments that will be concatenated, because
1251: the comments will be converted to spaces at first sight, and concatenation
1252: will later discard the spaces.
1253:
1254: @node Undefining, Redefining, Concatenation, Macros
1255: @subsection Undefining Macros
1256:
1257: @cindex undefining macros
1258: To @dfn{undefine} a macro means to cancel its definition. This is done
1.1.1.8 ! root 1259: with the @samp{#undef} directive. @samp{#undef} is followed by the macro
1.1 root 1260: name to be undefined.
1261:
1262: Like definition, undefinition occurs at a specific point in the source
1263: file, and it applies starting from that point. The name ceases to be a
1264: macro name, and from that point on it is treated by the preprocessor as if
1265: it had never been a macro name.
1266:
1267: For example,
1268:
1269: @example
1270: #define FOO 4
1271: x = FOO;
1272: #undef FOO
1273: x = FOO;
1274: @end example
1275:
1276: @noindent
1277: expands into
1278:
1279: @example
1280: x = 4;
1281:
1282: x = FOO;
1283: @end example
1284:
1285: @noindent
1286: In this example, @samp{FOO} had better be a variable or function as well
1287: as (temporarily) a macro, in order for the result of the expansion to be
1288: valid C code.
1289:
1.1.1.8 ! root 1290: The same form of @samp{#undef} directive will cancel definitions with
1.1 root 1291: arguments or definitions that don't expect arguments. The @samp{#undef}
1.1.1.8 ! root 1292: directive has no effect when used on a name not currently defined as a macro.
1.1 root 1293:
1294: @node Redefining, Macro Pitfalls, Undefining, Macros
1295: @subsection Redefining Macros
1296:
1297: @cindex redefining macros
1298: @dfn{Redefining} a macro means defining (with @samp{#define}) a name that
1299: is already defined as a macro.
1300:
1301: A redefinition is trivial if the new definition is transparently identical
1302: to the old one. You probably wouldn't deliberately write a trivial
1303: redefinition, but they can happen automatically when a header file is
1304: included more than once (@pxref{Header Files}), so they are accepted
1305: silently and without effect.
1306:
1307: Nontrivial redefinition is considered likely to be an error, so
1308: it provokes a warning message from the preprocessor. However, sometimes it
1309: is useful to change the definition of a macro in mid-compilation. You can
1310: inhibit the warning by undefining the macro with @samp{#undef} before the
1311: second definition.
1312:
1313: In order for a redefinition to be trivial, the new definition must
1314: exactly match the one already in effect, with two possible exceptions:
1315:
1316: @itemize @bullet
1317: @item
1318: Whitespace may be added or deleted at the beginning or the end.
1319:
1320: @item
1321: Whitespace may be changed in the middle (but not inside strings).
1322: However, it may not be eliminated entirely, and it may not be added
1323: where there was no whitespace at all.
1324: @end itemize
1325:
1326: Recall that a comment counts as whitespace.
1327:
1328: @node Macro Pitfalls,, Redefining, Macros
1329: @subsection Pitfalls and Subtleties of Macros
1.1.1.7 root 1330: @cindex problems with macros
1331: @cindex pitfalls of macros
1.1 root 1332:
1333: In this section we describe some special rules that apply to macros and
1334: macro expansion, and point out certain cases in which the rules have
1335: counterintuitive consequences that you must watch out for.
1336:
1337: @menu
1338: * Misnesting:: Macros can contain unmatched parentheses.
1339: * Macro Parentheses:: Why apparently superfluous parentheses
1340: may be necessary to avoid incorrect grouping.
1341: * Swallow Semicolon:: Macros that look like functions
1342: but expand into compound statements.
1343: * Side Effects:: Unsafe macros that cause trouble when
1344: arguments contain side effects.
1345: * Self-Reference:: Macros whose definitions use the macros' own names.
1346: * Argument Prescan:: Actual arguments are checked for macro calls
1347: before they are substituted.
1348: * Cascaded Macros:: Macros whose definitions use other macros.
1.1.1.4 root 1349: * Newlines in Args:: Sometimes line numbers get confused.
1.1 root 1350: @end menu
1351:
1352: @node Misnesting, Macro Parentheses, Macro Pitfalls, Macro Pitfalls
1353: @subsubsection Improperly Nested Constructs
1354:
1355: Recall that when a macro is called with arguments, the arguments are
1356: substituted into the macro body and the result is checked, together with
1357: the rest of the input file, for more macro calls.
1358:
1359: It is possible to piece together a macro call coming partially from the
1360: macro body and partially from the actual arguments. For example,
1361:
1362: @example
1363: #define double(x) (2*(x))
1364: #define call_with_1(x) x(1)
1365: @end example
1366:
1367: @noindent
1368: would expand @samp{call_with_1 (double)} into @samp{(2*(1))}.
1369:
1370: Macro definitions do not have to have balanced parentheses. By writing an
1371: unbalanced open parenthesis in a macro body, it is possible to create a
1372: macro call that begins inside the macro body but ends outside of it. For
1373: example,
1374:
1375: @example
1376: #define strange(file) fprintf (file, "%s %d",
1377: @dots{}
1378: strange(stderr) p, 35)
1379: @end example
1380:
1381: @noindent
1382: This bizarre example expands to @samp{fprintf (stderr, "%s %d", p, 35)}!
1383:
1384: @node Macro Parentheses, Swallow Semicolon, Misnesting, Macro Pitfalls
1385: @subsubsection Unintended Grouping of Arithmetic
1.1.1.7 root 1386: @cindex parentheses in macro bodies
1.1 root 1387:
1388: You may have noticed that in most of the macro definition examples shown
1389: above, each occurrence of a macro argument name had parentheses around it.
1390: In addition, another pair of parentheses usually surround the entire macro
1391: definition. Here is why it is best to write macros that way.
1392:
1393: Suppose you define a macro as follows,
1394:
1395: @example
1396: #define ceil_div(x, y) (x + y - 1) / y
1397: @end example
1398:
1399: @noindent
1.1.1.4 root 1400: whose purpose is to divide, rounding up. (One use for this operation is
1401: to compute how many @samp{int} objects are needed to hold a certain
1402: number of @samp{char} objects.) Then suppose it is used as follows:
1.1 root 1403:
1404: @example
1405: a = ceil_div (b & c, sizeof (int));
1406: @end example
1407:
1408: @noindent
1409: This expands into
1410:
1411: @example
1412: a = (b & c + sizeof (int) - 1) / sizeof (int);
1413: @end example
1414:
1415: @noindent
1416: which does not do what is intended. The operator-precedence rules of
1417: C make it equivalent to this:
1418:
1419: @example
1420: a = (b & (c + sizeof (int) - 1)) / sizeof (int);
1421: @end example
1422:
1423: @noindent
1424: But what we want is this:
1425:
1426: @example
1427: a = ((b & c) + sizeof (int) - 1)) / sizeof (int);
1428: @end example
1429:
1430: @noindent
1431: Defining the macro as
1432:
1433: @example
1434: #define ceil_div(x, y) ((x) + (y) - 1) / (y)
1435: @end example
1436:
1437: @noindent
1438: provides the desired result.
1439:
1440: However, unintended grouping can result in another way. Consider
1441: @samp{sizeof ceil_div(1, 2)}. That has the appearance of a C expression
1442: that would compute the size of the type of @samp{ceil_div (1, 2)}, but in
1443: fact it means something very different. Here is what it expands to:
1444:
1445: @example
1446: sizeof ((1) + (2) - 1) / (2)
1447: @end example
1448:
1449: @noindent
1450: This would take the size of an integer and divide it by two. The precedence
1451: rules have put the division outside the @samp{sizeof} when it was intended
1452: to be inside.
1453:
1454: Parentheses around the entire macro definition can prevent such problems.
1455: Here, then, is the recommended way to define @samp{ceil_div}:
1456:
1457: @example
1458: #define ceil_div(x, y) (((x) + (y) - 1) / (y))
1459: @end example
1460:
1461: @node Swallow Semicolon, Side Effects, Macro Parentheses, Macro Pitfalls
1462: @subsubsection Swallowing the Semicolon
1463:
1464: @cindex semicolons (after macro calls)
1465: Often it is desirable to define a macro that expands into a compound
1466: statement. Consider, for example, the following macro, that advances a
1467: pointer (the argument @samp{p} says where to find it) across whitespace
1468: characters:
1469:
1470: @example
1471: #define SKIP_SPACES (p, limit) \
1472: @{ register char *lim = (limit); \
1473: while (p != lim) @{ \
1474: if (*p++ != ' ') @{ \
1475: p--; break; @}@}@}
1476: @end example
1477:
1478: @noindent
1479: Here Backslash-Newline is used to split the macro definition, which must
1480: be a single line, so that it resembles the way such C code would be
1481: laid out if not part of a macro definition.
1482:
1483: A call to this macro might be @samp{SKIP_SPACES (p, lim)}. Strictly
1484: speaking, the call expands to a compound statement, which is a complete
1485: statement with no need for a semicolon to end it. But it looks like a
1486: function call. So it minimizes confusion if you can use it like a function
1487: call, writing a semicolon afterward, as in @samp{SKIP_SPACES (p, lim);}
1488:
1489: But this can cause trouble before @samp{else} statements, because the
1490: semicolon is actually a null statement. Suppose you write
1491:
1492: @example
1493: if (*p != 0)
1494: SKIP_SPACES (p, lim);
1495: else @dots{}
1496: @end example
1497:
1498: @noindent
1499: The presence of two statements---the compound statement and a null
1500: statement---in between the @samp{if} condition and the @samp{else}
1501: makes invalid C code.
1502:
1503: The definition of the macro @samp{SKIP_SPACES} can be altered to solve
1504: this problem, using a @samp{do @dots{} while} statement. Here is how:
1505:
1506: @example
1507: #define SKIP_SPACES (p, limit) \
1508: do @{ register char *lim = (limit); \
1509: while (p != lim) @{ \
1510: if (*p++ != ' ') @{ \
1511: p--; break; @}@}@} \
1512: while (0)
1513: @end example
1514:
1515: Now @samp{SKIP_SPACES (p, lim);} expands into
1516:
1517: @example
1518: do @{@dots{}@} while (0);
1519: @end example
1520:
1521: @noindent
1522: which is one statement.
1523:
1524: @node Side Effects, Self-Reference, Swallow Semicolon, Macro Pitfalls
1525: @subsubsection Duplication of Side Effects
1526:
1527: @cindex side effects (in macro arguments)
1528: @cindex unsafe macros
1529: Many C programs define a macro @samp{min}, for ``minimum'', like this:
1530:
1531: @example
1532: #define min(X, Y) ((X) < (Y) ? (X) : (Y))
1533: @end example
1534:
1535: When you use this macro with an argument containing a side effect,
1536: as shown here,
1537:
1538: @example
1539: next = min (x + y, foo (z));
1540: @end example
1541:
1542: @noindent
1543: it expands as follows:
1544:
1545: @example
1546: next = ((x + y) < (foo (z)) ? (x + y) : (foo (z)));
1547: @end example
1548:
1549: @noindent
1550: where @samp{x + y} has been substituted for @samp{X} and @samp{foo (z)}
1551: for @samp{Y}.
1552:
1553: The function @samp{foo} is used only once in the statement as it appears
1554: in the program, but the expression @samp{foo (z)} has been substituted
1555: twice into the macro expansion. As a result, @samp{foo} might be called
1556: two times when the statement is executed. If it has side effects or
1557: if it takes a long time to compute, the results might not be what you
1558: intended. We say that @samp{min} is an @dfn{unsafe} macro.
1559:
1560: The best solution to this problem is to define @samp{min} in a way that
1561: computes the value of @samp{foo (z)} only once. The C language offers no
1562: standard way to do this, but it can be done with GNU C extensions as
1563: follows:
1564:
1565: @example
1566: #define min(X, Y) \
1567: (@{ typeof (X) __x = (X), __y = (Y); \
1568: (__x < __y) ? __x : __y; @})
1569: @end example
1570:
1571: If you do not wish to use GNU C extensions, the only solution is to be
1572: careful when @emph{using} the macro @samp{min}. For example, you can
1573: calculate the value of @samp{foo (z)}, save it in a variable, and use that
1574: variable in @samp{min}:
1575:
1576: @example
1577: #define min(X, Y) ((X) < (Y) ? (X) : (Y))
1578: @dots{}
1579: @{
1580: int tem = foo (z);
1581: next = min (x + y, tem);
1582: @}
1583: @end example
1584:
1585: @noindent
1.1.1.3 root 1586: (where we assume that @samp{foo} returns type @samp{int}).
1.1 root 1587:
1588: @node Self-Reference, Argument Prescan, Side Effects, Macro Pitfalls
1589: @subsubsection Self-Referential Macros
1590:
1591: @cindex self-reference
1592: A @dfn{self-referential} macro is one whose name appears in its definition.
1593: A special feature of ANSI Standard C is that the self-reference is not
1594: considered a macro call. It is passed into the preprocessor output
1595: unchanged.
1596:
1597: Let's consider an example:
1598:
1599: @example
1600: #define foo (4 + foo)
1601: @end example
1602:
1603: @noindent
1604: where @samp{foo} is also a variable in your program.
1605:
1606: Following the ordinary rules, each reference to @samp{foo} will expand into
1607: @samp{(4 + foo)}; then this will be rescanned and will expand into @samp{(4
1608: + (4 + foo))}; and so on until it causes a fatal error (memory full) in the
1609: preprocessor.
1610:
1611: However, the special rule about self-reference cuts this process short
1612: after one step, at @samp{(4 + foo)}. Therefore, this macro definition
1613: has the possibly useful effect of causing the program to add 4 to
1614: the value of @samp{foo} wherever @samp{foo} is referred to.
1615:
1616: In most cases, it is a bad idea to take advantage of this feature. A
1617: person reading the program who sees that @samp{foo} is a variable will
1618: not expect that it is a macro as well. The reader will come across the
1619: identifier @samp{foo} in the program and think its value should be that
1620: of the variable @samp{foo}, whereas in fact the value is four greater.
1621:
1622: The special rule for self-reference applies also to @dfn{indirect}
1623: self-reference. This is the case where a macro @var{x} expands to use a
1.1.1.4 root 1624: macro @samp{y}, and the expansion of @samp{y} refers to the macro
1625: @samp{x}. The resulting reference to @samp{x} comes indirectly from the
1626: expansion of @samp{x}, so it is a self-reference and is not further
1627: expanded. Thus, after
1.1 root 1628:
1629: @example
1630: #define x (4 + y)
1631: #define y (2 * x)
1632: @end example
1633:
1634: @noindent
1635: @samp{x} would expand into @samp{(4 + (2 * x))}. Clear?
1636:
1637: But suppose @samp{y} is used elsewhere, not from the definition of @samp{x}.
1638: Then the use of @samp{x} in the expansion of @samp{y} is not a self-reference
1639: because @samp{x} is not ``in progress''. So it does expand. However,
1640: the expansion of @samp{x} contains a reference to @samp{y}, and that
1641: is an indirect self-reference now because @samp{y} is ``in progress''.
1642: The result is that @samp{y} expands to @samp{(2 * (4 + y))}.
1643:
1644: It is not clear that this behavior would ever be useful, but it is specified
1645: by the ANSI C standard, so you may need to understand it.
1646:
1647: @node Argument Prescan, Cascaded Macros, Self-Reference, Macro Pitfalls
1648: @subsubsection Separate Expansion of Macro Arguments
1.1.1.7 root 1649: @cindex expansion of arguments
1650: @cindex macro argument expansion
1651: @cindex prescan of macro arguments
1.1 root 1652:
1653: We have explained that the expansion of a macro, including the substituted
1654: actual arguments, is scanned over again for macro calls to be expanded.
1655:
1656: What really happens is more subtle: first each actual argument text is scanned
1657: separately for macro calls. Then the results of this are substituted into
1658: the macro body to produce the macro expansion, and the macro expansion
1659: is scanned again for macros to expand.
1660:
1661: The result is that the actual arguments are scanned @emph{twice} to expand
1662: macro calls in them.
1663:
1664: Most of the time, this has no effect. If the actual argument contained
1665: any macro calls, they are expanded during the first scan. The result
1666: therefore contains no macro calls, so the second scan does not change it.
1667: If the actual argument were substituted as given, with no prescan,
1668: the single remaining scan would find the same macro calls and produce
1669: the same results.
1670:
1671: You might expect the double scan to change the results when a
1672: self-referential macro is used in an actual argument of another macro
1673: (@pxref{Self-Reference}): the self-referential macro would be expanded once
1674: in the first scan, and a second time in the second scan. But this is not
1675: what happens. The self-references that do not expand in the first scan are
1676: marked so that they will not expand in the second scan either.
1677:
1678: The prescan is not done when an argument is stringified or concatenated.
1679: Thus,
1680:
1681: @example
1682: #define str(s) #s
1683: #define foo 4
1684: str (foo)
1685: @end example
1686:
1687: @noindent
1688: expands to @samp{"foo"}. Once more, prescan has been prevented from
1689: having any noticeable effect.
1690:
1691: More precisely, stringification and concatenation use the argument as
1692: written, in un-prescanned form. The same actual argument would be used in
1693: prescanned form if it is substituted elsewhere without stringification or
1694: concatenation.
1695:
1696: @example
1697: #define str(s) #s lose(s)
1698: #define foo 4
1699: str (foo)
1700: @end example
1701:
1702: expands to @samp{"foo" lose(4)}.
1703:
1704: You might now ask, ``Why mention the prescan, if it makes no difference?
1705: And why not skip it and make the preprocessor faster?'' The answer is
1706: that the prescan does make a difference in three special cases:
1707:
1708: @itemize @bullet
1709: @item
1710: Nested calls to a macro.
1711:
1712: @item
1713: Macros that call other macros that stringify or concatenate.
1714:
1715: @item
1716: Macros whose expansions contain unshielded commas.
1717: @end itemize
1718:
1719: We say that @dfn{nested} calls to a macro occur when a macro's actual
1720: argument contains a call to that very macro. For example, if @samp{f}
1721: is a macro that expects one argument, @samp{f (f (1))} is a nested
1722: pair of calls to @samp{f}. The desired expansion is made by
1723: expanding @samp{f (1)} and substituting that into the definition of
1724: @samp{f}. The prescan causes the expected result to happen.
1725: Without the prescan, @samp{f (1)} itself would be substituted as
1726: an actual argument, and the inner use of @samp{f} would appear
1727: during the main scan as an indirect self-reference and would not
1728: be expanded. Here, the prescan cancels an undesirable side effect
1729: (in the medical, not computational, sense of the term) of the special
1730: rule for self-referential macros.
1731:
1732: But prescan causes trouble in certain other cases of nested macro calls.
1733: Here is an example:
1734:
1735: @example
1736: #define foo a,b
1737: #define bar(x) lose(x)
1738: #define lose(x) (1 + (x))
1739:
1740: bar(foo)
1741: @end example
1742:
1743: @noindent
1744: We would like @samp{bar(foo)} to turn into @samp{(1 + (foo))}, which
1745: would then turn into @samp{(1 + (a,b))}. But instead, @samp{bar(foo)}
1746: expands into @samp{lose(a,b)}, and you get an error because @code{lose}
1747: requires a single argument. In this case, the problem is easily solved
1748: by the same parentheses that ought to be used to prevent misnesting of
1749: arithmetic operations:
1750:
1751: @example
1752: #define foo (a,b)
1753: #define bar(x) lose((x))
1754: @end example
1755:
1756: The problem is more serious when the operands of the macro are not
1757: expressions; for example, when they are statements. Then parentheses
1758: are unacceptable because they would make for invalid C code:
1759:
1760: @example
1761: #define foo @{ int a, b; @dots{} @}
1762: @end example
1763:
1764: @noindent
1765: In GNU C you can shield the commas using the @samp{(@{@dots{}@})}
1766: construct which turns a compound statement into an expression:
1767:
1768: @example
1769: #define foo (@{ int a, b; @dots{} @})
1770: @end example
1771:
1772: Or you can rewrite the macro definition to avoid such commas:
1773:
1774: @example
1775: #define foo @{ int a; int b; @dots{} @}
1776: @end example
1777:
1778: There is also one case where prescan is useful. It is possible
1779: to use prescan to expand an argument and then stringify it---if you use
1780: two levels of macros. Let's add a new macro @samp{xstr} to the
1781: example shown above:
1782:
1783: @example
1784: #define xstr(s) str(s)
1785: #define str(s) #s
1786: #define foo 4
1787: xstr (foo)
1788: @end example
1789:
1790: This expands into @samp{"4"}, not @samp{"foo"}. The reason for the
1791: difference is that the argument of @samp{xstr} is expanded at prescan
1792: (because @samp{xstr} does not specify stringification or concatenation of
1793: the argument). The result of prescan then forms the actual argument for
1794: @samp{str}. @samp{str} uses its argument without prescan because it
1795: performs stringification; but it cannot prevent or undo the prescanning
1796: already done by @samp{xstr}.
1797:
1.1.1.4 root 1798: @node Cascaded Macros, Newlines in Args, Argument Prescan, Macro Pitfalls
1.1 root 1799: @subsubsection Cascaded Use of Macros
1800:
1801: @cindex cascaded macros
1802: @cindex macro body uses macro
1803: A @dfn{cascade} of macros is when one macro's body contains a reference
1804: to another macro. This is very common practice. For example,
1805:
1806: @example
1807: #define BUFSIZE 1020
1808: #define TABLESIZE BUFSIZE
1809: @end example
1810:
1811: This is not at all the same as defining @samp{TABLESIZE} to be @samp{1020}.
1812: The @samp{#define} for @samp{TABLESIZE} uses exactly the body you
1813: specify---in this case, @samp{BUFSIZE}---and does not check to see whether
1814: it too is the name of a macro.
1815:
1816: It's only when you @emph{use} @samp{TABLESIZE} that the result of its expansion
1817: is checked for more macro names.
1818:
1819: This makes a difference if you change the definition of @samp{BUFSIZE}
1820: at some point in the source file. @samp{TABLESIZE}, defined as shown,
1821: will always expand using the definition of @samp{BUFSIZE} that is
1822: currently in effect:
1823:
1824: @example
1825: #define BUFSIZE 1020
1826: #define TABLESIZE BUFSIZE
1827: #undef BUFSIZE
1828: #define BUFSIZE 37
1829: @end example
1830:
1831: @noindent
1.1.1.7 root 1832: Now @samp{TABLESIZE} expands (in two stages) to @samp{37}. (The
1833: @samp{#undef} is to prevent any warning about the nontrivial
1834: redefinition of @code{BUFSIZE}.)
1.1 root 1835:
1.1.1.4 root 1836: @node Newlines in Args,, Cascaded Macros, Macro Pitfalls
1837: @subsection Newlines in Macro Arguments
1.1.1.7 root 1838: @cindex newlines in macro arguments
1.1.1.4 root 1839:
1840: Traditional macro processing carries forward all newlines in macro
1841: arguments into the expansion of the macro. This means that, if some of
1842: the arguments are substituted more than once, or not at all, or out of
1843: order, newlines can be duplicated, lost, or moved around within the
1844: expansion. If the expansion consists of multiple statements, then the
1845: effect is to distort the line numbers of some of these statements. The
1846: result can be incorrect line numbers, in error messages or displayed in
1847: a debugger.
1848:
1849: The GNU C preprocessor operating in ANSI C mode adjusts appropriately
1850: for multiple use of an argument---the first use expands all the
1851: newlines, and subsequent uses of the same argument produce no newlines.
1852: But even in this mode, it can produce incorrect line numbering if
1853: arguments are used out of order, or not used at all.
1854:
1855: Here is an example illustrating this problem:
1856:
1857: @example
1858: #define ignore_second_arg(a,b,c) a; c
1859:
1860: ignore_second_arg (foo (),
1861: ignored (),
1862: syntax error);
1863: @end example
1864:
1865: @noindent
1866: The syntax error triggered by the tokens @samp{syntax error} results
1867: in an error message citing line four, even though the statement text
1868: comes from line five.
1869:
1.1 root 1870: @node Conditionals, Combining Sources, Macros, Top
1871: @section Conditionals
1872:
1873: @cindex conditionals
1.1.1.8 ! root 1874: In a macro processor, a @dfn{conditional} is a directive that allows a part
1.1 root 1875: of the program to be ignored during compilation, on some conditions.
1876: In the C preprocessor, a conditional can test either an arithmetic expression
1877: or whether a name is defined as a macro.
1878:
1879: A conditional in the C preprocessor resembles in some ways an @samp{if}
1880: statement in C, but it is important to understand the difference between
1881: them. The condition in an @samp{if} statement is tested during the execution
1882: of your program. Its purpose is to allow your program to behave differently
1883: from run to run, depending on the data it is operating on. The condition
1.1.1.8 ! root 1884: in a preprocessing conditional directive is tested when your program is compiled.
1.1 root 1885: Its purpose is to allow different code to be included in the program depending
1886: on the situation at the time of compilation.
1887:
1888: @menu
1889: * Uses: Conditional Uses. What conditionals are for.
1890: * Syntax: Conditional Syntax. How conditionals are written.
1891: * Deletion: Deleted Code. Making code into a comment.
1892: * Macros: Conditionals-Macros. Why conditionals are used with macros.
1.1.1.4 root 1893: * Assertions:: How and why to use assertions.
1.1.1.8 ! root 1894: * Errors: #error Directive. Detecting inconsistent compilation parameters.
1.1 root 1895: @end menu
1896:
1.1.1.4 root 1897: @node Conditional Uses
1.1 root 1898: @subsection Why Conditionals are Used
1899:
1900: Generally there are three kinds of reason to use a conditional.
1901:
1902: @itemize @bullet
1903: @item
1904: A program may need to use different code depending on the machine or
1905: operating system it is to run on. In some cases the code for one
1906: operating system may be erroneous on another operating system; for
1907: example, it might refer to library routines that do not exist on the
1908: other system. When this happens, it is not enough to avoid executing
1909: the invalid code: merely having it in the program makes it impossible
1.1.1.8 ! root 1910: to link the program and run it. With a preprocessing conditional, the
1.1 root 1911: offending code can be effectively excised from the program when it is
1912: not valid.
1913:
1914: @item
1915: You may want to be able to compile the same source file into two
1916: different programs. Sometimes the difference between the programs is
1917: that one makes frequent time-consuming consistency checks on its
1.1.1.7 root 1918: intermediate data, or prints the values of those data for debugging,
1919: while the other does not.
1.1 root 1920:
1921: @item
1922: A conditional whose condition is always false is a good way to exclude
1923: code from the program but keep it as a sort of comment for future
1924: reference.
1925: @end itemize
1926:
1927: Most simple programs that are intended to run on only one machine will
1.1.1.8 ! root 1928: not need to use preprocessing conditionals.
1.1 root 1929:
1.1.1.4 root 1930: @node Conditional Syntax
1.1 root 1931: @subsection Syntax of Conditionals
1932:
1933: @findex #if
1934: A conditional in the C preprocessor begins with a @dfn{conditional
1.1.1.8 ! root 1935: directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}.
1.1 root 1936: @xref{Conditionals-Macros}, for information on @samp{#ifdef} and
1937: @samp{#ifndef}; only @samp{#if} is explained here.
1938:
1939: @menu
1.1.1.8 ! root 1940: * If: #if Directive. Basic conditionals using @samp{#if} and @samp{#endif}.
! 1941: * Else: #else Directive. Including some text if the condition fails.
! 1942: * Elif: #elif Directive. Testing several alternative possibilities.
1.1 root 1943: @end menu
1944:
1.1.1.8 ! root 1945: @node #if Directive
! 1946: @subsubsection The @samp{#if} Directive
1.1 root 1947:
1.1.1.8 ! root 1948: The @samp{#if} directive in its simplest form consists of
1.1 root 1949:
1950: @example
1951: #if @var{expression}
1952: @var{controlled text}
1953: #endif /* @var{expression} */
1954: @end example
1955:
1956: The comment following the @samp{#endif} is not required, but it is a good
1957: practice because it helps people match the @samp{#endif} to the
1958: corresponding @samp{#if}. Such comments should always be used, except in
1959: short conditionals that are not nested. In fact, you can put anything at
1960: all after the @samp{#endif} and it will be ignored by the GNU C preprocessor,
1961: but only comments are acceptable in ANSI Standard C.
1962:
1963: @var{expression} is a C expression of integer type, subject to stringent
1964: restrictions. It may contain
1965:
1966: @itemize @bullet
1967: @item
1968: Integer constants, which are all regarded as @code{long} or
1969: @code{unsigned long}.
1970:
1971: @item
1972: Character constants, which are interpreted according to the character
1973: set and conventions of the machine and operating system on which the
1974: preprocessor is running. The GNU C preprocessor uses the C data type
1975: @samp{char} for these character constants; therefore, whether some
1976: character codes are negative is determined by the C compiler used to
1977: compile the preprocessor. If it treats @samp{char} as signed, then
1978: character codes large enough to set the sign bit will be considered
1979: negative; otherwise, no character code is considered negative.
1980:
1981: @item
1982: Arithmetic operators for addition, subtraction, multiplication,
1.1.1.7 root 1983: division, bitwise operations, shifts, comparisons, and logical
1984: operations (@samp{&&} and @samp{||}).
1.1 root 1985:
1986: @item
1987: Identifiers that are not macros, which are all treated as zero(!).
1988:
1989: @item
1990: Macro calls. All macro calls in the expression are expanded before
1991: actual computation of the expression's value begins.
1992: @end itemize
1993:
1994: Note that @samp{sizeof} operators and @code{enum}-type values are not allowed.
1995: @code{enum}-type values, like all other identifiers that are not taken
1996: as macro calls and expanded, are treated as zero.
1997:
1998: The @var{controlled text} inside of a conditional can include
1.1.1.8 ! root 1999: preprocessing directives. Then the directives inside the conditional are
1.1 root 2000: obeyed only if that branch of the conditional succeeds. The text can
1.1.1.4 root 2001: also contain other conditional groups. However, the @samp{#if} and
1.1.1.8 ! root 2002: @samp{#endif} directives must balance.
1.1 root 2003:
1.1.1.8 ! root 2004: @node #else Directive
! 2005: @subsubsection The @samp{#else} Directive
1.1 root 2006:
2007: @findex #else
1.1.1.8 ! root 2008: The @samp{#else} directive can be added to a conditional to provide
1.1 root 2009: alternative text to be used if the condition is false. This is what
2010: it looks like:
2011:
2012: @example
2013: #if @var{expression}
2014: @var{text-if-true}
2015: #else /* Not @var{expression} */
2016: @var{text-if-false}
2017: #endif /* Not @var{expression} */
2018: @end example
2019:
1.1.1.3 root 2020: If @var{expression} is nonzero, and thus the @var{text-if-true} is
2021: active, then @samp{#else} acts like a failing conditional and the
1.1 root 2022: @var{text-if-false} is ignored. Contrariwise, if the @samp{#if}
2023: conditional fails, the @var{text-if-false} is considered included.
2024:
1.1.1.8 ! root 2025: @node #elif Directive
! 2026: @subsubsection The @samp{#elif} Directive
1.1 root 2027:
2028: @findex #elif
2029: One common case of nested conditionals is used to check for more than two
2030: possible alternatives. For example, you might have
2031:
2032: @example
2033: #if X == 1
2034: @dots{}
2035: #else /* X != 1 */
2036: #if X == 2
2037: @dots{}
2038: #else /* X != 2 */
2039: @dots{}
2040: #endif /* X != 2 */
2041: #endif /* X != 1 */
2042: @end example
2043:
1.1.1.8 ! root 2044: Another conditional directive, @samp{#elif}, allows this to be abbreviated
1.1 root 2045: as follows:
2046:
2047: @example
2048: #if X == 1
2049: @dots{}
2050: #elif X == 2
2051: @dots{}
2052: #else /* X != 2 and X != 1*/
2053: @dots{}
2054: #endif /* X != 2 and X != 1*/
2055: @end example
2056:
2057: @samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the
2058: middle of a @samp{#if}-@samp{#endif} pair and subdivides it; it does not
2059: require a matching @samp{#endif} of its own. Like @samp{#if}, the
1.1.1.8 ! root 2060: @samp{#elif} directive includes an expression to be tested.
1.1 root 2061:
2062: The text following the @samp{#elif} is processed only if the original
1.1.1.4 root 2063: @samp{#if}-condition failed and the @samp{#elif} condition succeeds.
2064: More than one @samp{#elif} can go in the same @samp{#if}-@samp{#endif}
2065: group. Then the text after each @samp{#elif} is processed only if the
2066: @samp{#elif} condition succeeds after the original @samp{#if} and any
1.1.1.8 ! root 2067: previous @samp{#elif} directives within it have failed. @samp{#else} is
1.1.1.4 root 2068: equivalent to @samp{#elif 1}, and @samp{#else} is allowed after any
1.1.1.8 ! root 2069: number of @samp{#elif} directives, but @samp{#elif} may not follow
1.1.1.4 root 2070: @samp{#else}.
1.1 root 2071:
1.1.1.4 root 2072: @node Deleted Code
1.1 root 2073: @subsection Keeping Deleted Code for Future Reference
1.1.1.7 root 2074: @cindex commenting out code
1.1 root 2075:
2076: If you replace or delete a part of the program but want to keep the old
1.1.1.7 root 2077: code around as a comment for future reference, the easy way to do this
2078: is to put @samp{#if 0} before it and @samp{#endif} after it. This is
2079: better than using comment delimiters @samp{/*} and @samp{*/} since those
2080: won't work if the code already contains comments (C comments do not
2081: nest).
1.1 root 2082:
2083: This works even if the code being turned off contains conditionals, but
2084: they must be entire conditionals (balanced @samp{#if} and @samp{#endif}).
2085:
1.1.1.7 root 2086: Conversely, do not use @samp{#if 0} for comments which are not C code.
2087: Use the comment delimiters @samp{/*} and @samp{*/} instead. The
2088: interior of @samp{#if 0} must consist of complete tokens; in particular,
2089: singlequote characters must balance. But comments often contain
2090: unbalanced singlequote characters (known in English as apostrophes).
2091: These confuse @samp{#if 0}. They do not confuse @samp{/*}.
2092:
1.1.1.4 root 2093: @node Conditionals-Macros
1.1 root 2094: @subsection Conditionals and Macros
2095:
1.1.1.4 root 2096: Conditionals are useful in connection with macros or assertions, because
2097: those are the only ways that an expression's value can vary from one
1.1.1.8 ! root 2098: compilation to another. A @samp{#if} directive whose expression uses no
1.1.1.4 root 2099: macros or assertions is equivalent to @samp{#if 1} or @samp{#if 0}; you
2100: might as well determine which one, by computing the value of the
2101: expression yourself, and then simplify the program.
1.1 root 2102:
2103: For example, here is a conditional that tests the expression
2104: @samp{BUFSIZE == 1020}, where @samp{BUFSIZE} must be a macro.
2105:
2106: @example
2107: #if BUFSIZE == 1020
2108: printf ("Large buffers!\n");
2109: #endif /* BUFSIZE is large */
2110: @end example
2111:
1.1.1.4 root 2112: (Programmers often wish they could test the size of a variable or data
2113: type in @samp{#if}, but this does not work. The preprocessor does not
2114: understand @code{sizeof}, or typedef names, or even the type keywords
2115: such as @code{int}.)
2116:
1.1 root 2117: @findex defined
1.1.1.4 root 2118: The special operator @samp{defined} is used in @samp{#if} expressions to
2119: test whether a certain name is defined as a macro. Either @samp{defined
2120: @var{name}} or @samp{defined (@var{name})} is an expression whose value
2121: is 1 if @var{name} is defined as macro at the current point in the
2122: program, and 0 otherwise. For the @samp{defined} operator it makes no
2123: difference what the definition of the macro is; all that matters is
2124: whether there is a definition. Thus, for example,@refill
1.1 root 2125:
2126: @example
2127: #if defined (vax) || defined (ns16000)
2128: @end example
2129:
2130: @noindent
1.1.1.7 root 2131: would succeed if either of the names @samp{vax} and @samp{ns16000} is
2132: defined as a macro. You can test the same condition using assertions
2133: (@pxref{Assertions}), like this:
1.1.1.4 root 2134:
2135: @example
2136: #if #cpu (vax) || #cpu (ns16000)
2137: @end example
1.1 root 2138:
2139: If a macro is defined and later undefined with @samp{#undef},
1.1.1.4 root 2140: subsequent use of the @samp{defined} operator returns 0, because
1.1 root 2141: the name is no longer defined. If the macro is defined again with
2142: another @samp{#define}, @samp{defined} will recommence returning 1.
2143:
2144: @findex #ifdef
2145: @findex #ifndef
1.1.1.7 root 2146: Conditionals that test whether just one name is defined are very common,
1.1.1.8 ! root 2147: so there are two special short conditional directives for this case.
1.1 root 2148:
2149: @table @code
2150: @item #ifdef @var{name}
2151: is equivalent to @samp{#if defined (@var{name})}.
2152:
2153: @item #ifndef @var{name}
2154: is equivalent to @samp{#if ! defined (@var{name})}.
2155: @end table
2156:
2157: Macro definitions can vary between compilations for several reasons.
2158:
2159: @itemize @bullet
2160: @item
2161: Some macros are predefined on each kind of machine. For example, on a
2162: Vax, the name @samp{vax} is a predefined macro. On other machines, it
2163: would not be defined.
2164:
2165: @item
2166: Many more macros are defined by system header files. Different
2167: systems and machines define different macros, or give them different
2168: values. It is useful to test these macros with conditionals to avoid
2169: using a system feature on a machine where it is not implemented.
2170:
2171: @item
2172: Macros are a common way of allowing users to customize a program for
2173: different machines or applications. For example, the macro
2174: @samp{BUFSIZE} might be defined in a configuration file for your
2175: program that is included as a header file in each source file. You
1.1.1.8 ! root 2176: would use @samp{BUFSIZE} in a preprocessing conditional in order to
1.1 root 2177: generate different code depending on the chosen configuration.
2178:
2179: @item
2180: Macros can be defined or undefined with @samp{-D} and @samp{-U}
2181: command options when you compile the program. You can arrange to
2182: compile the same source file into two different programs by choosing
2183: a macro name to specify which program you want, writing conditionals
2184: to test whether or how this macro is defined, and then controlling
2185: the state of the macro with compiler command options.
2186: @xref{Invocation}.
2187: @end itemize
2188:
1.1.1.4 root 2189: @ifinfo
2190: Assertions are usually predefined, but can be defined with preprocessor
1.1.1.8 ! root 2191: directives or command-line options.
1.1.1.4 root 2192: @end ifinfo
2193:
2194: @node Assertions
2195: @subsection Assertions
2196:
2197: @cindex assertions
2198: @dfn{Assertions} are a more systematic alternative to macros in writing
2199: conditionals to test what sort of computer or system the compiled
2200: program will run on. Assertions are usually predefined, but you can
1.1.1.8 ! root 2201: define them with preprocessing directives or command-line options.
1.1.1.4 root 2202:
2203: @cindex predicates
2204: The macros traditionally used to describe the type of target are not
2205: classified in any way according to which question they answer; they may
2206: indicate a hardware architecture, a particular hardware model, an
2207: operating system, a particular version of an operating system, or
2208: specific configuration options. These are jumbled together in a single
2209: namespace. In contrast, each assertion consists of a named question and
2210: an answer. The question is usually called the @dfn{predicate}.
2211: An assertion looks like this:
2212:
2213: @example
2214: #@var{predicate} (@var{answer})
2215: @end example
2216:
2217: @noindent
2218: You must use a properly formed identifier for @var{predicate}. The
2219: value of @var{answer} can be any sequence of words; all characters are
2220: significant except for leading and trailing whitespace, and differences
2221: in internal whitespace sequences are ignored. Thus, @samp{x + y} is
2222: different from @samp{x+y} but equivalent to @samp{x + y}. @samp{)} is
2223: not allowed in an answer.
2224:
2225: @cindex testing predicates
2226: Here is a conditional to test whether the answer @var{answer} is asserted
2227: for the predicate @var{predicate}:
2228:
2229: @example
2230: #if #@var{predicate} (@var{answer})
2231: @end example
2232:
2233: @noindent
2234: There may be more than one answer asserted for a given predicate. If
2235: you omit the answer, you can test whether @emph{any} answer is asserted
2236: for @var{predicate}:
2237:
2238: @example
2239: #if #@var{predicate}
2240: @end example
2241:
1.1.1.7 root 2242: @findex #system
2243: @findex #machine
2244: @findex #cpu
1.1.1.4 root 2245: Most of the time, the assertions you test will be predefined assertions.
2246: GNU C provides three predefined predicates: @code{system}, @code{cpu},
2247: and @code{machine}. @code{system} is for assertions about the type of
2248: software, @code{cpu} describes the type of computer architecture, and
2249: @code{machine} gives more information about the computer. For example,
2250: on a GNU system, the following assertions would be true:
2251:
2252: @example
2253: #system (gnu)
2254: #system (mach)
2255: #system (mach 3)
2256: #system (mach 3.@var{subversion})
2257: #system (hurd)
2258: #system (hurd @var{version})
2259: @end example
2260:
2261: @noindent
1.1.1.6 root 2262: and perhaps others. The alternatives with
1.1.1.4 root 2263: more or less version information let you ask more or less detailed
2264: questions about the type of system software.
2265:
1.1.1.6 root 2266: On a Unix system, you would find @code{#system (unix)} and perhaps one of:
2267: @code{#system (aix)}, @code{#system (bsd)}, @code{#system (hpux)},
2268: @code{#system (lynx)}, @code{#system (mach)}, @code{#system (posix)},
2269: @code{#system (svr3)}, @code{#system (svr4)}, or @code{#system (xpg4)}
2270: with possible version numbers following.
2271:
2272: Other values for @code{system} are @code{#system (mvs)}
2273: and @code{#system (vms)}.
2274:
1.1.1.4 root 2275: @strong{Portability note:} Many Unix C compilers provide only one answer
2276: for the @code{system} assertion: @code{#system (unix)}, if they support
2277: assertions at all. This is less than useful.
2278:
2279: An assertion with a multi-word answer is completely different from several
2280: assertions with individual single-word answers. For example, the presence
2281: of @code{system (mach 3.0)} does not mean that @code{system (3.0)} is true.
2282: It also does not directly imply @code{system (mach)}, but in GNU C, that
2283: last will normally be asserted as well.
2284:
1.1.1.6 root 2285: The current list of possible assertion values for @code{cpu} is:
2286: @code{#cpu (a29k)}, @code{#cpu (alpha)}, @code{#cpu (arm)}, @code{#cpu
2287: (clipper)}, @code{#cpu (convex)}, @code{#cpu (elxsi)}, @code{#cpu
2288: (tron)}, @code{#cpu (h8300)}, @code{#cpu (i370)}, @code{#cpu (i386)},
2289: @code{#cpu (i860)}, @code{#cpu (i960)}, @code{#cpu (m68k)}, @code{#cpu
2290: (m88k)}, @code{#cpu (mips)}, @code{#cpu (ns32k)}, @code{#cpu (hppa)},
2291: @code{#cpu (pyr)}, @code{#cpu (ibm032)}, @code{#cpu (rs6000)},
2292: @code{#cpu (sh)}, @code{#cpu (sparc)}, @code{#cpu (spur)}, @code{#cpu
2293: (tahoe)}, @code{#cpu (vax)}, @code{#cpu (we32000)}.
2294:
1.1.1.4 root 2295: @findex #assert
2296: You can create assertions within a C program using @samp{#assert}, like
2297: this:
2298:
2299: @example
2300: #assert @var{predicate} (@var{answer})
2301: @end example
2302:
2303: @noindent
2304: (Note the absence of a @samp{#} before @var{predicate}.)
2305:
2306: @cindex unassert
2307: @cindex assertions, undoing
2308: @cindex retracting assertions
2309: @findex #unassert
2310: Each time you do this, you assert a new true answer for @var{predicate}.
2311: Asserting one answer does not invalidate previously asserted answers;
2312: they all remain true. The only way to remove an assertion is with
2313: @samp{#unassert}. @samp{#unassert} has the same syntax as
2314: @samp{#assert}. You can also remove all assertions about
2315: @var{predicate} like this:
2316:
2317: @example
2318: #unassert @var{predicate}
2319: @end example
2320:
2321: You can also add or cancel assertions using command options
2322: when you run @code{gcc} or @code{cpp}. @xref{Invocation}.
2323:
1.1.1.8 ! root 2324: @node #error Directive
! 2325: @subsection The @samp{#error} and @samp{#warning} Directives
1.1 root 2326:
2327: @findex #error
1.1.1.8 ! root 2328: The directive @samp{#error} causes the preprocessor to report a fatal
1.1 root 2329: error. The rest of the line that follows @samp{#error} is used as the
2330: error message.
2331:
2332: You would use @samp{#error} inside of a conditional that detects a
2333: combination of parameters which you know the program does not properly
2334: support. For example, if you know that the program will not run
2335: properly on a Vax, you might write
2336:
2337: @smallexample
1.1.1.7 root 2338: @group
2339: #ifdef __vax__
1.1 root 2340: #error Won't work on Vaxen. See comments at get_last_object.
2341: #endif
1.1.1.7 root 2342: @end group
1.1 root 2343: @end smallexample
2344:
2345: @noindent
2346: @xref{Nonstandard Predefined}, for why this works.
2347:
2348: If you have several configuration parameters that must be set up by
2349: the installation in a consistent way, you can use conditionals to detect
2350: an inconsistency and report it with @samp{#error}. For example,
2351:
2352: @smallexample
2353: #if HASH_TABLE_SIZE % 2 == 0 || HASH_TABLE_SIZE % 3 == 0 \
2354: || HASH_TABLE_SIZE % 5 == 0
2355: #error HASH_TABLE_SIZE should not be divisible by a small prime
2356: #endif
2357: @end smallexample
2358:
2359: @findex #warning
1.1.1.8 ! root 2360: The directive @samp{#warning} is like the directive @samp{#error}, but causes
1.1 root 2361: the preprocessor to issue a warning and continue preprocessing. The rest of
2362: the line that follows @samp{#warning} is used as the warning message.
2363:
2364: You might use @samp{#warning} in obsolete header files, with a message
2365: directing the user to the header file which should be used instead.
2366:
1.1.1.8 ! root 2367: @node Combining Sources, Other Directives, Conditionals, Top
1.1 root 2368: @section Combining Source Files
2369:
2370: @cindex line control
2371: One of the jobs of the C preprocessor is to inform the C compiler of where
2372: each line of C code came from: which source file and which line number.
2373:
2374: C code can come from multiple source files if you use @samp{#include};
2375: both @samp{#include} and the use of conditionals and macros can cause
2376: the line number of a line in the preprocessor output to be different
2377: from the line's number in the original source file. You will appreciate
2378: the value of making both the C compiler (in error messages) and symbolic
2379: debuggers such as GDB use the line numbers in your source file.
2380:
1.1.1.8 ! root 2381: The C preprocessor builds on this feature by offering a directive by which
1.1 root 2382: you can control the feature explicitly. This is useful when a file for
2383: input to the C preprocessor is the output from another program such as the
2384: @code{bison} parser generator, which operates on another file that is the
2385: true source file. Parts of the output from @code{bison} are generated from
2386: scratch, other parts come from a standard parser file. The rest are copied
2387: nearly verbatim from the source file, but their line numbers in the
2388: @code{bison} output are not the same as their original line numbers.
2389: Naturally you would like compiler error messages and symbolic debuggers to
2390: know the original source file and line number of each line in the
1.1.1.3 root 2391: @code{bison} input.
1.1 root 2392:
1.1.1.7 root 2393: @findex #line
1.1.1.8 ! root 2394: @code{bison} arranges this by writing @samp{#line} directives into the output
! 2395: file. @samp{#line} is a directive that specifies the original line number
1.1 root 2396: and source file name for subsequent input in the current preprocessor input
2397: file. @samp{#line} has three variants:
2398:
2399: @table @code
2400: @item #line @var{linenum}
2401: Here @var{linenum} is a decimal integer constant. This specifies that
2402: the line number of the following line of input, in its original source file,
2403: was @var{linenum}.
2404:
2405: @item #line @var{linenum} @var{filename}
2406: Here @var{linenum} is a decimal integer constant and @var{filename}
2407: is a string constant. This specifies that the following line of input
2408: came originally from source file @var{filename} and its line number there
2409: was @var{linenum}. Keep in mind that @var{filename} is not just a
2410: file name; it is surrounded by doublequote characters so that it looks
2411: like a string constant.
2412:
2413: @item #line @var{anything else}
2414: @var{anything else} is checked for macro calls, which are expanded.
2415: The result should be a decimal integer constant followed optionally
2416: by a string constant, as described above.
2417: @end table
2418:
1.1.1.8 ! root 2419: @samp{#line} directives alter the results of the @samp{__FILE__} and
1.1 root 2420: @samp{__LINE__} predefined macros from that point on. @xref{Standard
2421: Predefined}.
2422:
1.1.1.4 root 2423: The output of the preprocessor (which is the input for the rest of the
1.1.1.8 ! root 2424: compiler) contains directives that look much like @samp{#line} directives.
1.1.1.4 root 2425: They start with just @samp{#} instead of @samp{#line}, but this is
2426: followed by a line number and file name as in @samp{#line}. @xref{Output}.
2427:
1.1.1.8 ! root 2428: @node Other Directives, Output, Combining Sources, Top
! 2429: @section Miscellaneous Preprocessing Directives
1.1 root 2430:
1.1.1.8 ! root 2431: @cindex null directive
! 2432: This section describes three additional preprocessing directives. They are
1.1 root 2433: not very useful, but are mentioned for completeness.
2434:
1.1.1.8 ! root 2435: The @dfn{null directive} consists of a @samp{#} followed by a Newline, with
! 2436: only whitespace (including comments) in between. A null directive is
! 2437: understood as a preprocessing directive but has no effect on the preprocessor
! 2438: output. The primary significance of the existence of the null directive is
1.1 root 2439: that an input line consisting of just a @samp{#} will produce no output,
2440: rather than a line of output containing just a @samp{#}. Supposedly
2441: some old C programs contain such lines.
2442:
1.1.1.7 root 2443: @findex #pragma
1.1.1.8 ! root 2444: The ANSI standard specifies that the @samp{#pragma} directive has an
1.1 root 2445: arbitrary, implementation-defined effect. In the GNU C preprocessor,
1.1.1.8 ! root 2446: @samp{#pragma} directives are not used, except for @samp{#pragma once}
1.1.1.5 root 2447: (@pxref{Once-Only}). However, they are left in the preprocessor output,
2448: so they are available to the compilation pass.
1.1 root 2449:
1.1.1.7 root 2450: @findex #ident
1.1.1.8 ! root 2451: The @samp{#ident} directive is supported for compatibility with certain
1.1 root 2452: other systems. It is followed by a line of text. On some systems, the
2453: text is copied into a special place in the object file; on most systems,
1.1.1.8 ! root 2454: the text is ignored and this directive has no effect. Typically
1.1 root 2455: @samp{#ident} is only used in header files supplied with those systems
2456: where it is meaningful.
2457:
1.1.1.8 ! root 2458: @node Output, Invocation, Other Directives, Top
1.1 root 2459: @section C Preprocessor Output
2460:
2461: @cindex output format
2462: The output from the C preprocessor looks much like the input, except
1.1.1.8 ! root 2463: that all preprocessing directive lines have been replaced with blank lines
1.1 root 2464: and all comments with spaces. Whitespace within a line is not altered;
2465: however, a space is inserted after the expansions of most macro calls.
2466:
2467: Source file name and line number information is conveyed by lines of
2468: the form
2469:
2470: @example
1.1.1.4 root 2471: # @var{linenum} @var{filename} @var{flags}
1.1 root 2472: @end example
2473:
2474: @noindent
2475: which are inserted as needed into the middle of the input (but never
2476: within a string or character constant). Such a line means that the
2477: following line originated in file @var{filename} at line @var{linenum}.
2478:
1.1.1.4 root 2479: After the file name comes zero or more flags, which are @samp{1},
1.1.1.8 ! root 2480: @samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces separate
1.1.1.4 root 2481: them. Here is what the flags mean:
2482:
2483: @table @samp
2484: @item 1
2485: This indicates the start of a new file.
2486: @item 2
2487: This indicates returning to a file (after having included another file).
2488: @item 3
2489: This indicates that the following text comes from a system header file,
2490: so certain warnings should be suppressed.
1.1.1.8 ! root 2491: @item 4
! 2492: This indicates that the following text should be treated as C.
! 2493: @c maybe cross reference NO_IMPLICIT_EXTERN_C
1.1.1.4 root 2494: @end table
1.1 root 2495:
2496: @node Invocation, Concept Index, Output, Top
2497: @section Invoking the C Preprocessor
1.1.1.7 root 2498: @cindex invocation of the preprocessor
1.1 root 2499:
2500: Most often when you use the C preprocessor you will not have to invoke it
2501: explicitly: the C compiler will do so automatically. However, the
1.1.1.7 root 2502: preprocessor is sometimes useful on its own.
1.1 root 2503:
2504: The C preprocessor expects two file names as arguments, @var{infile} and
2505: @var{outfile}. The preprocessor reads @var{infile} together with any other
2506: files it specifies with @samp{#include}. All the output generated by the
2507: combined input files is written in @var{outfile}.
2508:
2509: Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile}
2510: means to read from standard input and as @var{outfile} means to write to
2511: standard output. Also, if @var{outfile} or both file names are omitted,
2512: the standard output and standard input are used for the omitted file names.
2513:
2514: @cindex options
2515: Here is a table of command options accepted by the C preprocessor.
2516: These options can also be given when compiling a C program; they are
2517: passed along automatically to the preprocessor when it is invoked by the
2518: compiler.
2519:
2520: @table @samp
2521: @item -P
2522: @findex -P
2523: Inhibit generation of @samp{#}-lines with line-number information in
2524: the output from the preprocessor (@pxref{Output}). This might be
2525: useful when running the preprocessor on something that is not C code
2526: and will be sent to a program which might be confused by the
2527: @samp{#}-lines.
2528:
2529: @item -C
2530: @findex -C
2531: Do not discard comments: pass them through to the output file.
2532: Comments appearing in arguments of a macro call will be copied to the
2533: output before the expansion of the macro call.
2534:
1.1.1.4 root 2535: @item -traditional
2536: @findex -traditional
2537: Try to imitate the behavior of old-fashioned C, as opposed to ANSI C.
2538:
2539: @itemize @bullet
2540: @item
2541: Traditional macro expansion pays no attention to singlequote or
2542: doublequote characters; macro argument symbols are replaced by the
2543: argument values even when they appear within apparent string or
2544: character constants.
2545:
2546: @item
1.1.1.5 root 2547: Traditionally, it is permissible for a macro expansion to end in the
1.1.1.4 root 2548: middle of a string or character constant. The constant continues into
2549: the text surrounding the macro call.
2550:
2551: @item
2552: However, traditionally the end of the line terminates a string or
2553: character constant, with no error.
2554:
2555: @item
2556: In traditional C, a comment is equivalent to no text at all. (In ANSI
2557: C, a comment counts as whitespace.)
2558:
2559: @item
2560: Traditional C does not have the concept of a ``preprocessing number''.
2561: It considers @samp{1.0e+4} to be three tokens: @samp{1.0e}, @samp{+},
2562: and @samp{4}.
2563:
2564: @item
2565: A macro is not suppressed within its own definition, in traditional C.
2566: Thus, any macro that is used recursively inevitably causes an error.
2567:
2568: @item
2569: The character @samp{#} has no special meaning within a macro definition
2570: in traditional C.
2571:
2572: @item
2573: In traditional C, the text at the end of a macro expansion can run
2574: together with the text after the macro call, to produce a single token.
2575: (This is impossible in ANSI C.)
2576:
2577: @item
2578: Traditionally, @samp{\} inside a macro argument suppresses the syntactic
2579: significance of the following character.
2580: @end itemize
2581:
1.1 root 2582: @item -trigraphs
2583: @findex -trigraphs
2584: Process ANSI standard trigraph sequences. These are three-character
2585: sequences, all starting with @samp{??}, that are defined by ANSI C to
2586: stand for single characters. For example, @samp{??/} stands for
2587: @samp{\}, so @samp{'??/n'} is a character constant for a newline.
2588: Strictly speaking, the GNU C preprocessor does not support all
2589: programs in ANSI Standard C unless @samp{-trigraphs} is used, but if
2590: you ever notice the difference it will be with relief.
2591:
2592: You don't want to know any more about trigraphs.
2593:
2594: @item -pedantic
2595: @findex -pedantic
2596: Issue warnings required by the ANSI C standard in certain cases such
2597: as when text other than a comment follows @samp{#else} or @samp{#endif}.
2598:
2599: @item -pedantic-errors
2600: @findex -pedantic-errors
2601: Like @samp{-pedantic}, except that errors are produced rather than
2602: warnings.
2603:
2604: @item -Wtrigraphs
1.1.1.5 root 2605: @findex -Wtrigraphs
1.1 root 2606: Warn if any trigraphs are encountered (assuming they are enabled).
2607:
2608: @item -Wcomment
2609: @findex -Wcomment
2610: @ignore
2611: @c "Not worth documenting" both singular and plural forms of this
2612: @c option, per RMS. But also unclear which is better; hence may need to
2613: @c switch this at some future date. [email protected], 2jan92.
2614: @itemx -Wcomments
2615: (Both forms have the same effect).
2616: @end ignore
2617: Warn whenever a comment-start sequence @samp{/*} appears in a comment.
2618:
2619: @item -Wall
2620: @findex -Wall
2621: Requests both @samp{-Wtrigraphs} and @samp{-Wcomment} (but not
2622: @samp{-Wtraditional}).
2623:
2624: @item -Wtraditional
2625: @findex -Wtraditional
2626: Warn about certain constructs that behave differently in traditional and
2627: ANSI C.
2628:
2629: @item -I @var{directory}
2630: @findex -I
1.1.1.8 ! root 2631: Add the directory @var{directory} to the head of the list of
1.1 root 2632: directories to be searched for header files (@pxref{Include Syntax}).
2633: This can be used to override a system header file, substituting your
2634: own version, since these directories are searched before the system
2635: header file directories. If you use more than one @samp{-I} option,
2636: the directories are scanned in left-to-right order; the standard
2637: system directories come after.
2638:
2639: @item -I-
2640: Any directories specified with @samp{-I} options before the @samp{-I-}
2641: option are searched only for the case of @samp{#include "@var{file}"};
2642: they are not searched for @samp{#include <@var{file}>}.
2643:
2644: If additional directories are specified with @samp{-I} options after
2645: the @samp{-I-}, these directories are searched for all @samp{#include}
1.1.1.8 ! root 2646: directives.
1.1 root 2647:
2648: In addition, the @samp{-I-} option inhibits the use of the current
2649: directory as the first search directory for @samp{#include "@var{file}"}.
2650: Therefore, the current directory is searched only if it is requested
2651: explicitly with @samp{-I.}. Specifying both @samp{-I-} and @samp{-I.}
2652: allows you to control precisely which directories are searched before
2653: the current one and which are searched after.
2654:
2655: @item -nostdinc
1.1.1.5 root 2656: @findex -nostdinc
1.1 root 2657: Do not search the standard system directories for header files.
2658: Only the directories you have specified with @samp{-I} options
2659: (and the current directory, if appropriate) are searched.
2660:
1.1.1.3 root 2661: @item -nostdinc++
1.1.1.5 root 2662: @findex -nostdinc++
1.1.1.3 root 2663: Do not search for header files in the C++-specific standard directories,
2664: but do still search the other standard directories.
1.1.1.5 root 2665: (This option is used when building libg++.)
1.1.1.3 root 2666:
1.1 root 2667: @item -D @var{name}
2668: @findex -D
2669: Predefine @var{name} as a macro, with definition @samp{1}.
2670:
2671: @item -D @var{name}=@var{definition}
2672: Predefine @var{name} as a macro, with definition @var{definition}.
2673: There are no restrictions on the contents of @var{definition}, but if
2674: you are invoking the preprocessor from a shell or shell-like program you
2675: may need to use the shell's quoting syntax to protect characters such as
2676: spaces that have a meaning in the shell syntax. If you use more than
2677: one @samp{-D} for the same @var{name}, the rightmost definition takes
2678: effect.
2679:
2680: @item -U @var{name}
2681: @findex -U
2682: Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are
2683: specified for one name, the @samp{-U} beats the @samp{-D} and the name
2684: is not predefined.
2685:
1.1.1.5 root 2686: @item -undef
2687: @findex -undef
2688: Do not predefine any nonstandard macros.
2689:
1.1.1.4 root 2690: @item -A @var{predicate}(@var{answer})
2691: @findex -A
2692: Make an assertion with the predicate @var{predicate} and answer
2693: @var{answer}. @xref{Assertions}.
2694:
2695: @noindent
2696: You can use @samp{-A-} to disable all predefined assertions; it also
2697: undefines all predefined macros that identify the type of target system.
1.1 root 2698:
2699: @item -dM
2700: @findex -dM
2701: Instead of outputting the result of preprocessing, output a list of
1.1.1.8 ! root 2702: @samp{#define} directives for all the macros defined during the
1.1 root 2703: execution of the preprocessor, including predefined macros. This gives
2704: you a way of finding out what is predefined in your version of the
2705: preprocessor; assuming you have no file @samp{foo.h}, the command
2706:
2707: @example
2708: touch foo.h; cpp -dM foo.h
2709: @end example
2710:
2711: @noindent
2712: will show the values of any predefined macros.
2713:
2714: @item -dD
2715: @findex -dD
2716: Like @samp{-dM} except in two respects: it does @emph{not} include the
2717: predefined macros, and it outputs @emph{both} the @samp{#define}
1.1.1.8 ! root 2718: directives and the result of preprocessing. Both kinds of output go to
1.1 root 2719: the standard output file.
2720:
1.1.1.7 root 2721: @item -M [-MG]
1.1 root 2722: @findex -M
2723: Instead of outputting the result of preprocessing, output a rule
2724: suitable for @code{make} describing the dependencies of the main
2725: source file. The preprocessor outputs one @code{make} rule containing
2726: the object file name for that source file, a colon, and the names of
2727: all the included files. If there are many included files then the
2728: rule is split into several lines using @samp{\}-newline.
2729:
1.1.1.7 root 2730: @samp{-MG} says to treat missing header files as generated files and assume
2731: they live in the same directory as the source file. It must be specified
2732: in addition to @samp{-M}.
2733:
1.1 root 2734: This feature is used in automatic updating of makefiles.
2735:
1.1.1.7 root 2736: @item -MM [-MG]
1.1 root 2737: @findex -MM
2738: Like @samp{-M} but mention only the files included with @samp{#include
2739: "@var{file}"}. System header files included with @samp{#include
2740: <@var{file}>} are omitted.
2741:
1.1.1.7 root 2742: @item -MD @var{file}
1.1 root 2743: @findex -MD
1.1.1.7 root 2744: Like @samp{-M} but the dependency information is written to @var{file}.
2745: This is in addition to compiling the file as specified---@samp{-MD} does
2746: not inhibit ordinary compilation the way @samp{-M} does.
2747:
2748: When invoking gcc, do not specify the @var{file} argument.
2749: Gcc will create file names made by replacing ".c" with ".d" at
2750: the end of the input file names.
1.1 root 2751:
1.1.1.7 root 2752: In Mach, you can use the utility @code{md} to merge multiple dependency
2753: files into a single dependency file suitable for using with the @samp{make}
1.1 root 2754: command.
2755:
1.1.1.7 root 2756: @item -MMD @var{file}
1.1 root 2757: @findex -MMD
2758: Like @samp{-MD} except mention only user header files, not system
2759: header files.
2760:
2761: @item -H
2762: @findex -H
2763: Print the name of each header file used, in addition to other normal
2764: activities.
2765:
2766: @item -imacros @var{file}
2767: @findex -imacros
2768: Process @var{file} as input, discarding the resulting output, before
2769: processing the regular input file. Because the output generated from
2770: @var{file} is discarded, the only effect of @samp{-imacros @var{file}}
2771: is to make the macros defined in @var{file} available for use in the
2772: main input.
2773:
2774: @item -include @var{file}
2775: @findex -include
2776: Process @var{file} as input, and include all the resulting output,
2777: before processing the regular input file.
2778:
1.1.1.5 root 2779: @item -idirafter @var{dir}
2780: @findex -idirafter
2781: @cindex second include path
2782: Add the directory @var{dir} to the second include path. The directories
2783: on the second include path are searched when a header file is not found
2784: in any of the directories in the main include path (the one that
2785: @samp{-I} adds to).
2786:
2787: @item -iprefix @var{prefix}
2788: @findex -iprefix
2789: Specify @var{prefix} as the prefix for subsequent @samp{-iwithprefix}
2790: options.
2791:
2792: @item -iwithprefix @var{dir}
2793: @findex -iwithprefix
2794: Add a directory to the second include path. The directory's name is
2795: made by concatenating @var{prefix} and @var{dir}, where @var{prefix}
2796: was specified previously with @samp{-iprefix}.
2797:
1.1.1.7 root 2798: @item -isystem @var{dir}
2799: @findex -isystem
2800: Add a directory to the beginning of the second include path, marking it
2801: as a system directory, so that it gets the same special treatment as
2802: is applied to the standard system directories.
2803:
1.1 root 2804: @item -lang-c
1.1.1.8 ! root 2805: @itemx -lang-c89
1.1 root 2806: @itemx -lang-c++
2807: @itemx -lang-objc
2808: @itemx -lang-objc++
1.1.1.5 root 2809: @findex -lang-c
1.1.1.8 ! root 2810: @findex -lang-c89
1.1.1.5 root 2811: @findex -lang-c++
2812: @findex -lang-objc
2813: @findex -lang-objc++
1.1.1.8 ! root 2814: Specify the source language. @samp{-lang-c} is the default; it
! 2815: allows recognition of C++ comments (comments that begin with
! 2816: @samp{//} and end at end of line), since this is
! 2817: a common feature and it will most likely be in the next C standard.
! 2818: @samp{-lang-c89} disables recognition of C++ comments. @samp{-lang-c++}
! 2819: handles C++ comment syntax and includes extra default include
! 2820: directories for C++. @samp{-lang-objc} enables the Objective C
! 2821: @samp{#import} directive. @samp{-lang-objc++} enables both C++ and Objective C
! 2822: extensions.
1.1 root 2823:
2824: These options are generated by the compiler driver @code{gcc}, but not
1.1.1.8 ! root 2825: passed from the @samp{gcc} command line unless you use the driver's
! 2826: @samp{-Wp} option.
1.1 root 2827:
2828: @item -lint
2829: Look for commands to the program checker @code{lint} embedded in
2830: comments, and emit them preceded by @samp{#pragma lint}. For example,
2831: the comment @samp{/* NOTREACHED */} becomes @samp{#pragma lint
2832: NOTREACHED}.
2833:
2834: This option is available only when you call @code{cpp} directly;
2835: @code{gcc} will not pass it from its command line.
2836:
2837: @item -$
1.1.1.5 root 2838: @findex -$
1.1 root 2839: Forbid the use of @samp{$} in identifiers. This is required for ANSI
2840: conformance. @code{gcc} automatically supplies this option to the
2841: preprocessor if you specify @samp{-ansi}, but @code{gcc} doesn't
2842: recognize the @samp{-$} option itself---to use it without the other
2843: effects of @samp{-ansi}, you must call the preprocessor directly.
2844:
2845: @end table
2846:
2847: @node Concept Index, Index, Invocation, Top
2848: @unnumbered Concept Index
2849: @printindex cp
2850:
2851: @node Index,, Concept Index, Top
1.1.1.8 ! root 2852: @unnumbered Index of Directives, Macros and Options
1.1 root 2853: @printindex fn
2854:
2855: @contents
2856: @bye
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.