-
Notifications
You must be signed in to change notification settings - Fork 0
/
cpp.texi
2506 lines (2031 loc) · 86.8 KB
/
cpp.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@c Copyright @copyright{} 2022 Richard Stallman and Free Software Foundation, Inc.
This is part of the GNU C Intro and Reference Manual
and covered by its license.
@node Preprocessing
@chapter Preprocessing
@c man begin DESCRIPTION
@cindex preprocessing
As the first stage of compiling a C source module, GCC transforms the
text with text substitutions and file inclusions. This is called
@dfn{preprocessing}.
@menu
* Preproc Overview::
* Directives::
* Preprocessing Tokens::
* Header Files::
* Macros::
* Conditionals::
* Diagnostics::
* Line Control::
* Null Directive::
@end menu
@node Preproc Overview
@section Preprocessing Overview
GNU C performs preprocessing on each line of a C program as the first
stage of compilation. Preprocessing operates on a line only when it
contains a @dfn{preprocessing directive} or uses a @dfn{macro}---all
other lines pass through preprocessing unchanged.
Here are some jobs that preprocessing does. The rest of
this chapter gives the details.
@itemize @bullet
@item
Inclusion of header files. These are files (usually containing
declarations and macro definitions) that can be substituted into your
program.
@item
Macro expansion. You can define @dfn{macros}, which are abbreviations
for arbitrary fragments of C code. Preprocessing replaces the macros
with their definitions. Some macros are automatically predefined.
@item
Conditional compilation. You can include or exclude parts of the
program according to various conditions.
@item
Line control. If you use a program to combine or rearrange source files
into an intermediate file that is then compiled, you can use line
control to inform the compiler where each source line originally came
from.
@item
Compilation control. @code{#pragma} and @code{_Pragma} invoke
some special compiler features in how to handle certain constructs.
@item
Diagnostics. You can detect problems at compile time and issue errors
or warnings.
@end itemize
Except for expansion of predefined macros, all these operations happen
only if you use preprocessing directives to request them.
@node Directives
@section Directives
@cindex directives
@cindex preprocessing directives
@cindex directive line
@cindex directive name
@dfn{Preprocessing directives} are lines in the program that start
with @samp{#}. Whitespace is allowed before and after the @samp{#}.
The @samp{#} is followed by an identifier, the @dfn{directive name}.
It specifies the operation to perform. Here are a couple of examples:
@example
#define LIMIT 51
# undef LIMIT
# error You screwed up!
@end example
We usually refer to a directive as @code{#@var{name}} where @var{name}
is the directive name. For example, @code{#define} means the
directive that defines a macro.
The @samp{#} that begins a directive cannot come from a macro
expansion. Also, the directive name is not macro expanded. Thus, if
@code{foo} is defined as a macro expanding to @code{define}, that does
not make @code{#foo} a valid preprocessing directive.
The set of valid directive names is fixed. Programs cannot define new
preprocessing directives.
Some directives require arguments; these make up the rest of the
directive line and must be separated from the directive name by
whitespace. For example, @code{#define} must be followed by a macro
name and the intended expansion of the macro.
A preprocessing directive cannot cover more than one line. The line
can, however, be continued with backslash-newline, or by a
@samp{/*@r{@dots{}}*/}-style comment that extends past the end of the
line. These will be replaced (by nothing, or by whitespace) before
the directive is processed.
@node Preprocessing Tokens
@section Preprocessing Tokens
@cindex preprocessing tokens
Preprocessing divides C code (minus its comments) into
@dfn{tokens} that are similar to C tokens, but not exactly the same.
Here are the quirks of preprocessing tokens.
The main classes of preprocessing tokens are identifiers,
preprocessing numbers, string constants, character constants, and
punctuators; there are a few others too.
@table @asis
@item identifier
@cindex identifiers
An @dfn{identifier} preprocessing token is syntactically like an
identifier in C: any sequence of letters, digits, or underscores, as
well as non-ASCII characters represented using @samp{\U} or @samp{\u},
that doesn't begin with a digit.
During preprocessing, the keywords of C have no special significance;
at that stage, they are simply identifiers. Thus, you can define a
macro whose name is a keyword. The only identifier that is special
during preprocessing is @code{defined} (@pxref{defined}).
@item preprocessing number
@cindex numbers, preprocessing
@cindex preprocessing numbers
A @dfn{preprocessing number} is something that preprocessing treats
textually as a number, including C numeric constants, and other
sequences of characters which resemble numeric constants.
Preprocessing does not try to verify that a preprocessing number is a
valid number in C, and indeed it need not be one.
More precisely, preprocessing numbers begin with an optional period, a
required decimal digit, and then continue with any sequence of
letters, digits, underscores, periods, and exponents. Exponents are
the two-character sequences @samp{e+}, @samp{e-}, @samp{E+},
@samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and @samp{P-}. (The
exponents that begin with @samp{p} or @samp{P} are new to C99. They
are used for hexadecimal floating-point constants.)
The reason behind this unusual syntactic class is that the full
complexity of numeric constants is irrelevant during preprocessing.
The distinction between lexically valid and invalid floating-point
numbers, for example, doesn't matter at this stage. The use of
preprocessing numbers makes it possible to split an identifier at any
position and get exactly two tokens, and reliably paste them together
using the @code{##} operator (@pxref{Concatenation}).
@item punctuator
A @dfn{punctuator} is syntactically like an operator.
These are the valid punctuators:
@example
[ ] ( ) @{ @} . ->
++ -- & * + - ~ !
/ % << >> < > <= >= == != ^ | && ||
? : ; ...
= *= /= %= += -= <<= >>= &= ^= |=
, # ##
<: :> <% %> %: %:%:
@end example
@item string constant
A string constant in the source code is recognized by preprocessing as
a single preprocessing token.
@item character constant
A character constant in the source code is recognized by preprocessing
as a single preprocessing token.
@item header name
Within the @code{#include} directive, preprocessing recognizes a
@dfn{header name} token. It consists of @samp{"@var{name}"}, where
@var{name} is a sequence of source characters other than newline and
@samp{"}, or @samp{<@var{name}>}, where @var{name} is a sequence of
source characters other than newline and @samp{>}.
In practice, it is more convenient to think that the @code{#include} line
is exempt from tokenization.
@item other
Any other character that's valid in a C source program
is treated as a separate preprocessing token.
@end table
Once the program is broken into preprocessing tokens, they remain
separate until the end of preprocessing. Macros that generate two
consecutive tokens insert whitespace to keep them separate, if
necessary. For example,
@example
@group
#define foo() bar
foo()baz
@expansion{} bar baz
@emph{not}
@expansion{} barbaz
@end group
@end example
The only exception is with the @code{##} preprocessing operator, which
pastes tokens together (@pxref{Concatenation}).
Preprocessing treats the null character (code 0) as whitespace, but
generates a warning for it because it may be invisible to the user
(many terminals do not display it at all) and its presence in the file
is probably a mistake.
@node Header Files
@section Header Files
@cindex header file
A header file is a file of C code, typically containing C declarations
and macro definitions (@pxref{Macros}), to be shared between several
source files. You request the use of a header file in your program by
@dfn{including} it, with the C preprocessing directive
@code{#include}.
Header files serve two purposes.
@itemize @bullet
@item
@cindex system header files
System header files declare the interfaces to parts of the operating
system. You include them in your program to supply the definitions and
declarations that you need to invoke system calls and libraries.
@item
Program-specific header files contain declarations for interfaces between the
source files of a particular program. It is a good idea to create a header
file for related declarations and macro definitions if all or most of them
are needed in several different source files.
@end itemize
Including a header file produces the same results as copying the header
file into each source file that needs it. Such copying would be
time-consuming and error-prone. With a header file, the related
declarations appear in only one place. If they need to be changed, you
can change them in one place, and programs that include the header file
will then automatically use the new version when next recompiled. The header
file eliminates the labor of finding and changing all the copies as well
as the risk that a failure to change one copy will result in
inconsistencies within a program.
In C, the usual convention is to give header files names that end with
@file{.h}. It is most portable to use only letters, digits, dashes, and
underscores in header file names, and at most one dot.
@menu
* include Syntax::
* include Operation::
* Search Path::
* Once-Only Headers::
@c * Alternatives to Wrapper #ifndef::
* Computed Includes::
@c * Wrapper Headers::
@c * System Headers::
@end menu
@node include Syntax
@subsection @code{#include} Syntax
@findex #include
You can specify inclusion of user and system header files with the
preprocessing directive @code{#include}. It has two variants:
@table @code
@item #include <@var{file}>
This variant is used for system header files. It searches for a file
named @var{file} in a standard list of system directories. You can
prepend directories to this list with the @option{-I} option
(@pxref{Invocation, Invoking GCC, Invoking GCC, gcc, Using the GNU
Compiler Collection}).
@item #include "@var{file}"
This variant is used for header files of your own program. It
searches for a file named @var{file} first in the directory containing
the current file, then in the quote directories, then the same
directories used for @code{<@var{file}>}. You can prepend directories
to the list of quote directories with the @option{-iquote} option.
@end table
The argument of @code{#include}, whether delimited with quote marks or
angle brackets, behaves like a string constant in that comments are not
recognized, and macro names are not expanded. Thus, @code{@w{#include
<x/*y>}} specifies inclusion of a system header file named @file{x/*y}.
However, if backslashes occur within @var{file}, they are considered
ordinary text characters, not escape characters: character escape
sequences such as used in string constants in C are not meaningful
here. Thus, @code{@w{#include "x\n\\y"}} specifies a filename
containing three backslashes. By the same token, there is no way to
escape @samp{"} or @samp{>} to include it in the header file name if
it would instead end the file name.
Some systems interpret @samp{\} as a file name component separator.
All these systems also interpret @samp{/} the same way. It is most
portable to use only @samp{/}.
It is an error to put anything other than comments on the
@code{#include} line after the file name.
@node include Operation
@subsection @code{#include} Operation
The @code{#include} directive works by scanning the specified header
file as input before continuing with the rest of the current file.
The result of preprocessing consists of the text already generated,
followed by the result of preprocessing the included file, followed by
whatever results from the text after the @code{#include} directive.
For example, if you have a header file @file{header.h} as follows,
@example
char *test (void);
@end example
@noindent
and a main program called @file{program.c} that uses the header file,
like this,
@example
int x;
#include "header.h"
int
main (void)
@{
puts (test ());
@}
@end example
@noindent
the result is equivalent to putting this text in @file{program.c}:
@example
int x;
char *test (void);
int
main (void)
@{
puts (test ());
@}
@end example
Included files are not limited to declarations and macro definitions;
those are merely the typical uses. Any fragment of a C program can be
included from another file. The include file could even contain the
beginning of a statement that is concluded in the containing file, or
the end of a statement that was started in the including file. However,
an included file must consist of complete tokens. Comments and string
literals that have not been closed by the end of an included file are
invalid. For error recovery, the compiler terminates them at the end of
the file.
To avoid confusion, it is best if header files contain only complete
syntactic units---function declarations or definitions, type
declarations, etc.
The line following the @code{#include} directive is always treated as
a separate line, even if the included file lacks a final newline.
There is no problem putting a preprocessing directive there.
@node Search Path
@subsection Search Path
GCC looks in several different places for header files to be included.
On the GNU system, and Unix systems, the default directories for
system header files are:
@example
@var{libdir}/gcc/@var{target}/@var{version}/include
/usr/local/include
@var{libdir}/gcc/@var{target}/@var{version}/include-fixed
@var{libdir}/@var{target}/include
/usr/include/@var{target}
/usr/include
@end example
@noindent
The list may be different in some operating systems. Other
directories are added for C++.
In the above, @var{target} is the canonical name of the system GCC was
configured to compile code for; often but not always the same as the
canonical name of the system it runs on. @var{version} is the version
of GCC in use.
You can add to this list with the @option{-I@var{dir}} command-line
option. All the directories named by @option{-I} are searched, in
left-to-right order, @emph{before} the default directories. The only
exception is when @file{dir} is already searched by default. In
this case, the option is ignored and the search order for system
directories remains unchanged.
Duplicate directories are removed from the quote and bracket search
chains before the two chains are merged to make the final search chain.
Thus, it is possible for a directory to occur twice in the final search
chain if it was specified in both the quote and bracket chains.
You can prevent GCC from searching any of the default directories with
the @option{-nostdinc} option. This is useful when you are compiling an
operating system kernel or some other program that does not use the
standard C library facilities, or the standard C library itself.
@option{-I} options are not ignored as described above when
@option{-nostdinc} is in effect.
GCC looks for headers requested with @code{@w{#include "@var{file}"}}
first in the directory containing the current file, then in the
@dfn{quote directories} specified by @option{-iquote} options, then in
the same places it looks for a system header. For example, if
@file{/usr/include/sys/stat.h} contains @code{@w{#include "types.h"}},
GCC looks for @file{types.h} first in @file{/usr/include/sys}, then in
the quote directories and then in its usual search path.
@code{#line} (@pxref{Line Control}) does not change GCC's idea of the
directory containing the current file.
@cindex quote directories
The @option{-I-} is an old-fashioned, deprecated way to specify the
quote directories. To look for headers in a directory named @file{-},
specify @option{-I./-}. There are several more ways to adjust the
header search path. @xref{invocation, Invoking GCC, Invoking GCC,
gcc, Using the GNU Compiler Collection}.
@node Once-Only Headers
@subsection Once-Only Headers
@cindex repeated inclusion
@cindex including just once
@cindex wrapper @code{#ifndef}
If a header file happens to be included twice, the compiler will process
its contents twice. This is very likely to cause an error, e.g.@: when the
compiler sees the same structure definition twice.
The standard way to prevent this is to enclose the entire real contents
of the file in a conditional, like this:
@example
@group
/* File foo. */
#ifndef FILE_FOO_SEEN
#define FILE_FOO_SEEN
@var{the entire file}
#endif /* !FILE_FOO_SEEN */
@end group
@end example
This construct is commonly known as a @dfn{wrapper #ifndef}. When the
header is included again, the conditional will be false, because
@code{FILE_FOO_SEEN} is defined. Preprocessing skips over the entire
contents of the file, so that compilation will never ``see'' the file
contents twice in one module.
GCC optimizes this case even further. It remembers when a header file
has a wrapper @code{#ifndef}. If a subsequent @code{#include}
specifies that header, and the macro in the @code{#ifndef} is still
defined, it does not bother to rescan the file at all.
You can put comments in the header file outside the wrapper. They
do not interfere with this optimization.
@cindex controlling macro
@cindex guard macro
The macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro}
or @dfn{guard macro}. In a user header file, the macro name should
not begin with @samp{_}. In a system header file, it should begin
with @samp{__} (or @samp{_} followed by an upper-case letter) to avoid
conflicts with user programs. In any kind of header file, the macro
name should contain the name of the file and some additional text, to
avoid conflicts with other header files.
@node Computed Includes
@subsection Computed Includes
@cindex computed includes
@cindex macros in include
Sometimes it is necessary to select one of several different header
files to be included into your program. They might specify
configuration parameters to be used on different sorts of operating
systems, for instance. You could do this with a series of conditionals,
@example
#if SYSTEM_1
# include "system_1.h"
#elif SYSTEM_2
# include "system_2.h"
#elif SYSTEM_3
/* @r{@dots{}} */
#endif
@end example
That rapidly becomes tedious. Instead, GNU C offers the ability to use
a macro for the header name. This is called a @dfn{computed include}.
Instead of writing a header name as the direct argument of
@code{#include}, you simply put a macro name there instead:
@example
#define SYSTEM_H "system_1.h"
/* @r{@dots{}} */
#include SYSTEM_H
@end example
@noindent
@code{SYSTEM_H} is expanded, then @file{system_1.h} is included as if
the @code{#include} had been written with that name. @code{SYSTEM_H}
could be defined by your Makefile with a @option{-D} option.
You must be careful when you define such a macro. @code{#define}
saves tokens, not text. GCC has no way of knowing that the macro will
be used as the argument of @code{#include}, so it generates ordinary
tokens, not a header name. This is unlikely to cause problems if you
use double-quote includes, which are syntactically similar to string
constants. If you use angle brackets, however, you may have trouble.
The syntax of a computed include is actually a bit more general than the
above. If the first non-whitespace character after @code{#include} is
not @samp{"} or @samp{<}, then the entire line is macro-expanded
like running text would be.
If the line expands to a single string constant, the contents of that
string constant are the file to be included. Preprocessing does not
re-examine the string for embedded quotes, but neither does it process
backslash escapes in the string. Therefore
@example
#define HEADER "a\"b"
#include HEADER
@end example
@noindent
looks for a file named @file{a\"b}. Preprocessing searches for the
file according to the rules for double-quoted includes.
If the line expands to a token stream beginning with a @samp{<} token
and including a @samp{>} token, then the tokens between the @samp{<} and
the first @samp{>} are combined to form the filename to be included.
Any whitespace between tokens is reduced to a single space; then any
space after the initial @samp{<} is retained, but a trailing space
before the closing @samp{>} is ignored. Preprocessing searches for the file
according to the rules for angle-bracket includes.
In either case, if there are any tokens on the line after the file name,
an error occurs and the directive is not processed. It is also an error
if the result of expansion does not match either of the two expected
forms.
These rules are implementation-defined behavior according to the C
standard. To minimize the risk of different compilers interpreting your
computed includes differently, we recommend you use only a single
object-like macro that expands to a string constant. That also
makes it clear to people reading your program.
@node Macros
@section Macros
@cindex macros
A @dfn{macro} is a fragment of code that has been given a name.
Whenever the name is used, it is replaced by the contents of the macro.
There are two kinds of macros. They differ mostly in what they look
like when they are used. @dfn{Object-like} macros resemble data objects
when used, @dfn{function-like} macros resemble function calls.
You may define any valid identifier as a macro, even if it is a C
keyword. In the preprocessing stage, GCC does not know anything about
keywords. This can be useful if you wish to hide a keyword such as
@code{const} from an older compiler that does not understand it.
However, the preprocessing operator @code{defined} (@pxref{defined})
can never be defined as a macro, and C@code{++}'s named operators
(@pxref{C++ Named Operators, C++ Named Operators, C++ Named Operators,
gcc, Using the GNU Compiler Collection}) cannot be macros when
compiling C@code{++} code.
The operator @code{#} is used in macros for stringification of an
argument (@pxref{Stringification}), and @code{##} is used for
concatenation of arguments into larger tokens (@pxref{Concatenation})
@menu
* Object-like Macros::
* Function-like Macros::
@c * Macro Pragmas::
* Macro Arguments::
* Stringification::
* Concatenation::
* Variadic Macros::
* Predefined Macros::
* Undefining and Redefining Macros::
* Directives Within Macro Arguments::
* Macro Pitfalls::
@end menu
@node Object-like Macros
@subsection Object-like Macros
@cindex object-like macro
@cindex symbolic constants
@cindex manifest constants
An @dfn{object-like macro} is a simple identifier that will be
replaced by a code fragment. It is called object-like because in most
cases the use of the macro looks like reference to a data object in
code that uses it. These macros are most commonly used to give
symbolic names to numeric constants.
@findex #define
The way to define macros with the @code{#define} directive.
@code{#define} is followed by the name of the macro and then the token
sequence it should be an abbreviation for, which is variously referred
to as the macro's @dfn{body}, @dfn{expansion} or @dfn{replacement
list}. For example,
@example
#define BUFFER_SIZE 1024
@end example
@noindent
defines a macro named @code{BUFFER_SIZE} as an abbreviation for the
token @code{1024}. If somewhere after this @code{#define} directive
there comes a C statement of the form
@example
foo = (char *) malloc (BUFFER_SIZE);
@end example
@noindent
then preprocessing will recognize and @dfn{expand} the macro
@code{BUFFER_SIZE}, so that compilation will see the tokens:
@example
foo = (char *) malloc (1024);
@end example
By convention, macro names are written in upper case. Programs are
easier to read when it is possible to tell at a glance which names are
macros. Macro names that start with @samp{__} are reserved for
internal uses, and many of them are defined automatically, so don't
define such macro names unless you really know what you're doing.
Likewise for macro names that start with @samp{_} and an upper-case letter.
The macro's body ends at the end of the @code{#define} line. You may
continue the definition onto multiple lines, if necessary, using
backslash-newline. When the macro is expanded, however, it will all
come out on one line. For example,
@example
#define NUMBERS 1, \
2, \
3
int x[] = @{ NUMBERS @};
@expansion{} int x[] = @{ 1, 2, 3 @};
@end example
@noindent
The most common visible consequence of this is surprising line numbers
in error messages.
There is no restriction on what can go in a macro body provided it
decomposes into valid preprocessing tokens. Parentheses need not
balance, and the body need not resemble valid C code. (If it does not,
you may get error messages from the C compiler when you use the macro.)
Preprocessing scans the program sequentially. A macro definition
takes effect right after its appearance. Therefore, the following
input
@example
foo = X;
#define X 4
bar = X;
@end example
@noindent
produces
@example
foo = X;
bar = 4;
@end example
When preprocessing expands a macro name, the macro's expansion
replaces the macro invocation, then the expansion is examined for more
macros to expand. For example,
@example
@group
#define TABLESIZE BUFSIZE
#define BUFSIZE 1024
TABLESIZE
@expansion{} BUFSIZE
@expansion{} 1024
@end group
@end example
@noindent
@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that
macro is expanded to produce the final result, @code{1024}.
Notice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was
defined. The @code{#define} for @code{TABLESIZE} uses exactly the
expansion you specify---in this case, @code{BUFSIZE}---and does not
check to see whether it too contains macro names. Only when you
@emph{use} @code{TABLESIZE} is the result of its expansion scanned for
more macro names.
This makes a difference if you change the definition of @code{BUFSIZE}
at some point in the source file. @code{TABLESIZE}, defined as shown,
will always expand using the definition of @code{BUFSIZE} that is
currently in effect:
@example
#define BUFSIZE 1020
#define TABLESIZE BUFSIZE
#undef BUFSIZE
#define BUFSIZE 37
@end example
@noindent
Now @code{TABLESIZE} expands (in two stages) to @code{37}.
If the expansion of a macro contains its own name, either directly or
via intermediate macros, it is not expanded again when the expansion is
examined for more macros. This prevents infinite recursion.
@xref{Self-Referential Macros}, for the precise details.
@node Function-like Macros
@subsection Function-like Macros
@cindex function-like macros
You can also define macros whose use looks like a function call.
These are called @dfn{function-like macros}. To define one, use the
@code{#define} directive with a pair of parentheses immediately after
the macro name. For example,
@example
#define lang_init() c_init()
lang_init()
@expansion{} c_init()
@end example
A function-like macro is expanded only when its name appears with a
pair of parentheses after it. If you write just the name, without
parentheses, it is left alone. This can be useful when you have a
function and a macro of the same name, and you wish to use the
function sometimes. Whitespace and line breaks before or between the
parentheses are ignored when the macro is called.
@example
extern void foo(void);
#define foo() /* @r{optimized inline version} */
/* @r{@dots{}} */
foo();
funcptr = foo;
@end example
Here the call to @code{foo()} expands the macro, but the function
pointer @code{funcptr} gets the address of the real function
@code{foo}. If the macro were to be expanded there, it would cause a
syntax error.
If you put spaces between the macro name and the parentheses in the
macro definition, that does not define a function-like macro, it defines
an object-like macro whose expansion happens to begin with a pair of
parentheses. Here is an example:
@example
#define lang_init () c_init()
lang_init()
@expansion{} () c_init()()
@end example
The first two pairs of parentheses in this expansion come from the
macro. The third is the pair that was originally after the macro
invocation. Since @code{lang_init} is an object-like macro, it does not
consume those parentheses.
Any name can have at most one macro definition at a time. Thus,
you can't define the same name as an object-like macro and a
function-like macro at once.
@node Macro Arguments
@subsection Macro Arguments
@cindex arguments
@cindex macros with arguments
@cindex arguments in macro definitions
Function-like macros can take @dfn{arguments}, just like true functions.
To define a macro that uses arguments, you insert @dfn{parameters}
between the pair of parentheses in the macro definition that make the
macro function-like. The parameters must be valid C identifiers,
separated by commas and optionally whitespace.
To invoke a macro that takes arguments, you write the name of the macro
followed by a list of @dfn{actual arguments} in parentheses, separated
by commas. The invocation of the macro need not be restricted to a
single logical line---it can cross as many lines in the source file as
you wish. The number of arguments you give must match the number of
parameters in the macro definition. When the macro is expanded, each
use of a parameter in its body is replaced by the tokens of the
corresponding argument. (The macro body is not required to use all of the
parameters.)
As an example, here is a macro that computes the minimum of two numeric
values, as it is defined in many C programs, and some uses.
@example
#define min(X, Y) ((X) < (Y) ? (X) : (Y))
x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b));
y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2));
z = min(a+28, *p); @expansion{} z = ((a+28) < (*p) ? (a+28) : (*p));
@end example
@noindent
In this small example you can already see several of the dangers of
macro arguments. @xref{Macro Pitfalls}, for detailed explanations.
Leading and trailing whitespace in each argument is dropped, and all
whitespace between the tokens of an argument is reduced to a single
space. Parentheses within each argument must balance; a comma within
such parentheses does not end the argument. However, there is no
requirement for square brackets or braces to balance, and they do not
prevent a comma from separating arguments. Thus,
@example
macro (array[x = y, x + 1])
@end example
@noindent
passes two arguments to @code{macro}: @code{array[x = y} and @code{x +
1]}. If you want to supply @code{array[x = y, x + 1]} as an argument,
you can write it as @code{array[(x = y, x + 1)]}, which is equivalent C
code. However, putting an assignment inside an array subscript
is to be avoided anyway.
All arguments to a macro are completely macro-expanded before they are
substituted into the macro body. After substitution, the complete text
is scanned again for macros to expand, including the arguments. This rule
may seem strange, but it is carefully designed so you need not worry
about whether any function call is actually a macro invocation. You can
run into trouble if you try to be too clever, though. @xref{Argument
Prescan}, for detailed discussion.
For example, @code{min (min (a, b), c)} is first expanded to
@example
min (((a) < (b) ? (a) : (b)), (c))
@end example
@noindent
and then to
@example
@group
((((a) < (b) ? (a) : (b))) < (c)
? (((a) < (b) ? (a) : (b)))
: (c))
@end group
@end example
@noindent
(The line breaks shown here for clarity are not actually generated.)
@cindex empty macro arguments
You can leave macro arguments empty without error, but many macros
will then expand to invalid code. You cannot leave out arguments
entirely; if a macro takes two arguments, there must be exactly one
comma at the top level of its argument list. Here are some silly
examples using @code{min}:
@smallexample
min(, b) @expansion{} (( ) < (b) ? ( ) : (b))
min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( ))
min(,) @expansion{} (( ) < ( ) ? ( ) : ( ))
min((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( ))
min() @error{} macro "min" requires 2 arguments, but only 1 given
min(,,) @error{} macro "min" passed 3 arguments, but takes just 2
@end smallexample
Whitespace is not a preprocessing token, so if a macro @code{foo} takes
one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an
empty argument.
@ignore @c How long ago was this?
Previous GNU preprocessor implementations and
documentation were incorrect on this point, insisting that a
function-like macro that takes a single argument be passed a space if an
empty argument was required.
@end ignore
Macro parameters appearing inside string literals are not replaced by
their corresponding actual arguments.
@example
#define foo(x) x, "x"
foo(bar) @expansion{} bar, "x"
@end example
@noindent
See the next subsection for how to insert macro arguments
into a string literal.
The token following the macro call and the last token of the macro
expansion do not become one token even if it looks like they could:
@example
#define foo() abc
foo()def @expansion{} abc def
@end example
@node Stringification
@subsection Stringification
@cindex stringification
@cindex @code{#} operator
Sometimes you may want to convert a macro argument into a string
constant. Parameters are not replaced inside string constants, but
you can use the @code{#} preprocessing operator instead. When a macro
parameter is used with a leading @code{#}, preprocessing replaces it
with the literal text of the actual argument, converted to a string
constant. Unlike normal parameter replacement, the argument is not
macro-expanded first. This is called @dfn{stringification}.
There is no way to combine an argument with surrounding text and
stringify it all together. But you can write a series of string
constants and stringified arguments. After preprocessing replaces the
stringified arguments with string constants, the consecutive string
constants will be concatenated into one long string constant
(@pxref{String Constants}).
Here is an example that uses stringification and concatenation of
string constants:
@example
@group
#define WARN_IF(EXP) \
do @{ if (EXP) \
fprintf (stderr, "Warning: " #EXP "\n"); @} \
while (0)
WARN_IF (x == 0);
@expansion{}
do @{ if (x == 0)
fprintf (stderr, "Warning: " "x == 0" "\n"); @}
while (0);
@end group
@end example
@noindent
The argument for @code{EXP} is substituted once, as is, into the
@code{if} statement, and once, stringified, into the argument to
@code{fprintf}. If @code{x} were a macro, it would be expanded in the
@code{if} statement but not in the string.
The @code{do} and @code{while (0)} are a kludge to make it possible to
write @code{WARN_IF (@var{arg});}. The resemblance of @code{WARN_IF}
to a function makes that a natural way to write it.
@xref{Swallowing the Semicolon}.
Stringification in C involves more than putting double-quote
characters around the fragment. It also backslash-escapes the quotes
surrounding embedded string constants, and all backslashes within
string and character constants, in order to get a valid C string
constant with the proper contents. Thus, stringifying @code{@w{p =
"foo\n";}} results in @t{@w{"p = \"foo\\n\";"}}. However, backslashes
that are not inside string or character constants are not duplicated:
@samp{\n} by itself stringifies to @t{"\n"}.
All leading and trailing whitespace in text being stringified is
ignored. Any sequence of whitespace in the middle of the text is
converted to a single space in the stringified result. Comments are
replaced by whitespace long before stringification happens, so they
never appear in stringified text.
There is no way to convert a macro argument into a character constant.
To stringify the result of expansion of a macro argument, you have to
use two levels of macros, like this:
@example
#define xstr(S) str(S)
#define str(s) #s
#define foo 4
str (foo)
@expansion{} "foo"
xstr (foo)
@expansion{} xstr (4)