OSDN Git Service

c28f9a21f5237c563ed22c994ea0dac6868b7ed4
[pf3gnuchains/gcc-fork.git] / gcc / doc / trouble.texi
1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
2 @c 1999, 2000, 2001, 2003, 2004 Free Software Foundation, Inc.
3 @c This is part of the GCC manual.
4 @c For copying conditions, see the file gcc.texi.
5
6 @node Trouble
7 @chapter Known Causes of Trouble with GCC
8 @cindex bugs, known
9 @cindex installation trouble
10 @cindex known causes of trouble
11
12 This section describes known problems that affect users of GCC@.  Most
13 of these are not GCC bugs per se---if they were, we would fix them.
14 But the result for a user may be like the result of a bug.
15
16 Some of these problems are due to bugs in other software, some are
17 missing features that are too much work to add, and some are places
18 where people's opinions differ as to what is best.
19
20 @menu
21 * Actual Bugs::               Bugs we will fix later.
22 * Cross-Compiler Problems::   Common problems of cross compiling with GCC.
23 * Interoperation::      Problems using GCC with other compilers,
24                            and with certain linkers, assemblers and debuggers.
25 * External Bugs::       Problems compiling certain programs.
26 * Incompatibilities::   GCC is incompatible with traditional C.
27 * Fixed Headers::       GCC uses corrected versions of system header files.
28                            This is necessary, but doesn't always work smoothly.
29 * Standard Libraries::  GCC uses the system C library, which might not be
30                            compliant with the ISO C standard.
31 * Disappointments::     Regrettable things we can't change, but not quite bugs.
32 * C++ Misunderstandings::     Common misunderstandings with GNU C++.
33 * Protoize Caveats::    Things to watch out for when using @code{protoize}.
34 * Non-bugs::            Things we think are right, but some others disagree.
35 * Warnings and Errors:: Which problems in your code get warnings,
36                          and which get errors.
37 @end menu
38
39 @node Actual Bugs
40 @section Actual Bugs We Haven't Fixed Yet
41
42 @itemize @bullet
43 @item
44 The @code{fixincludes} script interacts badly with automounters; if the
45 directory of system header files is automounted, it tends to be
46 unmounted while @code{fixincludes} is running.  This would seem to be a
47 bug in the automounter.  We don't know any good way to work around it.
48
49 @item
50 The @code{fixproto} script will sometimes add prototypes for the
51 @code{sigsetjmp} and @code{siglongjmp} functions that reference the
52 @code{jmp_buf} type before that type is defined.  To work around this,
53 edit the offending file and place the typedef in front of the
54 prototypes.
55
56 @item
57 @opindex pedantic-errors
58 When @option{-pedantic-errors} is specified, GCC will incorrectly give
59 an error message when a function name is specified in an expression
60 involving the comma operator.
61 @end itemize
62
63 @node Cross-Compiler Problems
64 @section Cross-Compiler Problems
65
66 You may run into problems with cross compilation on certain machines,
67 for several reasons.
68
69 @itemize @bullet
70 @item
71 Cross compilation can run into trouble for certain machines because
72 some target machines' assemblers require floating point numbers to be
73 written as @emph{integer} constants in certain contexts.
74
75 The compiler writes these integer constants by examining the floating
76 point value as an integer and printing that integer, because this is
77 simple to write and independent of the details of the floating point
78 representation.  But this does not work if the compiler is running on
79 a different machine with an incompatible floating point format, or
80 even a different byte-ordering.
81
82 In addition, correct constant folding of floating point values
83 requires representing them in the target machine's format.
84 (The C standard does not quite require this, but in practice
85 it is the only way to win.)
86
87 It is now possible to overcome these problems by defining macros such
88 as @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
89 work for each target machine.
90 @xref{Cross-compilation,,Cross Compilation and Floating Point,
91 gccint, GNU Compiler Collection (GCC) Internals}.
92
93 @item
94 At present, the program @file{mips-tfile} which adds debug
95 support to object files on MIPS systems does not work in a cross
96 compile environment.
97 @end itemize
98
99 @node Interoperation
100 @section Interoperation
101
102 This section lists various difficulties encountered in using GCC
103 together with other compilers or with the assemblers, linkers,
104 libraries and debuggers on certain systems.
105
106 @itemize @bullet
107 @item
108 On many platforms, GCC supports a different ABI for C++ than do other
109 compilers, so the object files compiled by GCC cannot be used with object
110 files generated by another C++ compiler.
111
112 An area where the difference is most apparent is name mangling.  The use
113 of different name mangling is intentional, to protect you from more subtle
114 problems.
115 Compilers differ as to many internal details of C++ implementation,
116 including: how class instances are laid out, how multiple inheritance is
117 implemented, and how virtual function calls are handled.  If the name
118 encoding were made the same, your programs would link against libraries
119 provided from other compilers---but the programs would then crash when
120 run.  Incompatible libraries are then detected at link time, rather than
121 at run time.
122
123 @item
124 Older GDB versions sometimes fail to read the output of GCC version
125 2.  If you have trouble, get GDB version 4.4 or later.
126
127 @item
128 @cindex DBX
129 DBX rejects some files produced by GCC, though it accepts similar
130 constructs in output from PCC@.  Until someone can supply a coherent
131 description of what is valid DBX input and what is not, there is
132 nothing I can do about these problems.  You are on your own.
133
134 @item
135 The GNU assembler (GAS) does not support PIC@.  To generate PIC code, you
136 must use some other assembler, such as @file{/bin/as}.
137
138 @item
139 On some BSD systems, including some versions of Ultrix, use of profiling
140 causes static variable destructors (currently used only in C++) not to
141 be run.
142
143 @ignore
144 @cindex @code{vfork}, for the Sun-4
145 @item
146 There is a bug in @code{vfork} on the Sun-4 which causes the registers
147 of the child process to clobber those of the parent.  Because of this,
148 programs that call @code{vfork} are likely to lose when compiled
149 optimized with GCC when the child code alters registers which contain
150 C variables in the parent.  This affects variables which are live in the
151 parent across the call to @code{vfork}.
152
153 If you encounter this, you can work around the problem by declaring
154 variables @code{volatile} in the function that calls @code{vfork}, until
155 the problem goes away, or by not declaring them @code{register} and not
156 using @option{-O} for those source files.
157 @end ignore
158
159 @item
160 On some SGI systems, when you use @option{-lgl_s} as an option,
161 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
162 Naturally, this does not happen when you use GCC@.
163 You must specify all three options explicitly.
164
165 @item
166 On a SPARC, GCC aligns all values of type @code{double} on an 8-byte
167 boundary, and it expects every @code{double} to be so aligned.  The Sun
168 compiler usually gives @code{double} values 8-byte alignment, with one
169 exception: function arguments of type @code{double} may not be aligned.
170
171 As a result, if a function compiled with Sun CC takes the address of an
172 argument of type @code{double} and passes this pointer of type
173 @code{double *} to a function compiled with GCC, dereferencing the
174 pointer may cause a fatal signal.
175
176 One way to solve this problem is to compile your entire program with GCC@.
177 Another solution is to modify the function that is compiled with
178 Sun CC to copy the argument into a local variable; local variables
179 are always properly aligned.  A third solution is to modify the function
180 that uses the pointer to dereference it via the following function
181 @code{access_double} instead of directly with @samp{*}:
182
183 @smallexample
184 inline double
185 access_double (double *unaligned_ptr)
186 @{
187   union d2i @{ double d; int i[2]; @};
188
189   union d2i *p = (union d2i *) unaligned_ptr;
190   union d2i u;
191
192   u.i[0] = p->i[0];
193   u.i[1] = p->i[1];
194
195   return u.d;
196 @}
197 @end smallexample
198
199 @noindent
200 Storing into the pointer can be done likewise with the same union.
201
202 @item
203 On Solaris, the @code{malloc} function in the @file{libmalloc.a} library
204 may allocate memory that is only 4 byte aligned.  Since GCC on the
205 SPARC assumes that doubles are 8 byte aligned, this may result in a
206 fatal signal if doubles are stored in memory allocated by the
207 @file{libmalloc.a} library.
208
209 The solution is to not use the @file{libmalloc.a} library.  Use instead
210 @code{malloc} and related functions from @file{libc.a}; they do not have
211 this problem.
212
213 @item
214 Sun forgot to include a static version of @file{libdl.a} with some
215 versions of SunOS (mainly 4.1).  This results in undefined symbols when
216 linking static binaries (that is, if you use @option{-static}).  If you
217 see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
218 when linking, compile and link against the file
219 @file{mit/util/misc/dlsym.c} from the MIT version of X windows.
220
221 @item
222 The 128-bit long double format that the SPARC port supports currently
223 works by using the architecturally defined quad-word floating point
224 instructions.  Since there is no hardware that supports these
225 instructions they must be emulated by the operating system.  Long
226 doubles do not work in Sun OS versions 4.0.3 and earlier, because the
227 kernel emulator uses an obsolete and incompatible format.  Long doubles
228 do not work in Sun OS version 4.1.1 due to a problem in a Sun library.
229 Long doubles do work on Sun OS versions 4.1.2 and higher, but GCC
230 does not enable them by default.  Long doubles appear to work in Sun OS
231 5.x (Solaris 2.x).
232
233 @item
234 On HP-UX version 9.01 on the HP PA, the HP compiler @code{cc} does not
235 compile GCC correctly.  We do not yet know why.  However, GCC
236 compiled on earlier HP-UX versions works properly on HP-UX 9.01 and can
237 compile itself properly on 9.01.
238
239 @item
240 On the HP PA machine, ADB sometimes fails to work on functions compiled
241 with GCC@.  Specifically, it fails to work on functions that use
242 @code{alloca} or variable-size arrays.  This is because GCC doesn't
243 generate HP-UX unwind descriptors for such functions.  It may even be
244 impossible to generate them.
245
246 @item
247 Debugging (@option{-g}) is not supported on the HP PA machine, unless you use
248 the preliminary GNU tools.
249
250 @item
251 Taking the address of a label may generate errors from the HP-UX
252 PA assembler.  GAS for the PA does not have this problem.
253
254 @item
255 Using floating point parameters for indirect calls to static functions
256 will not work when using the HP assembler.  There simply is no way for GCC
257 to specify what registers hold arguments for static functions when using
258 the HP assembler.  GAS for the PA does not have this problem.
259
260 @item
261 In extremely rare cases involving some very large functions you may
262 receive errors from the HP linker complaining about an out of bounds
263 unconditional branch offset.  This used to occur more often in previous
264 versions of GCC, but is now exceptionally rare.  If you should run
265 into it, you can work around by making your function smaller.
266
267 @item
268 GCC compiled code sometimes emits warnings from the HP-UX assembler of
269 the form:
270
271 @smallexample
272 (warning) Use of GR3 when
273   frame >= 8192 may cause conflict.
274 @end smallexample
275
276 These warnings are harmless and can be safely ignored.
277
278 @item
279 On the IBM RS/6000, compiling code of the form
280
281 @smallexample
282 extern int foo;
283
284 @dots{} foo @dots{}
285
286 static int foo;
287 @end smallexample
288
289 @noindent
290 will cause the linker to report an undefined symbol @code{foo}.
291 Although this behavior differs from most other systems, it is not a
292 bug because redefining an @code{extern} variable as @code{static}
293 is undefined in ISO C@.
294
295 @item
296 In extremely rare cases involving some very large functions you may
297 receive errors from the AIX Assembler complaining about a displacement
298 that is too large.  If you should run into it, you can work around by
299 making your function smaller.
300
301 @item
302 The @file{libstdc++.a} library in GCC relies on the SVR4 dynamic
303 linker semantics which merges global symbols between libraries and
304 applications, especially necessary for C++ streams functionality.
305 This is not the default behavior of AIX shared libraries and dynamic
306 linking.  @file{libstdc++.a} is built on AIX with ``runtime-linking''
307 enabled so that symbol merging can occur.  To utilize this feature,
308 the application linked with @file{libstdc++.a} must include the
309 @option{-Wl,-brtl} flag on the link line.  G++ cannot impose this
310 because this option may interfere with the semantics of the user
311 program and users may not always use @samp{g++} to link his or her
312 application. Applications are not required to use the
313 @option{-Wl,-brtl} flag on the link line---the rest of the
314 @file{libstdc++.a} library which is not dependent on the symbol
315 merging semantics will continue to function correctly.
316
317 @item
318 An application can interpose its own definition of functions for
319 functions invoked by @file{libstdc++.a} with ``runtime-linking''
320 enabled on AIX.  To accomplish this the application must be linked
321 with ``runtime-linking'' option and the functions explicitly must be
322 exported by the application (@option{-Wl,-brtl,-bE:exportfile}).
323
324 @item
325 AIX on the RS/6000 provides support (NLS) for environments outside of
326 the United States.  Compilers and assemblers use NLS to support
327 locale-specific representations of various objects including
328 floating-point numbers (@samp{.} vs @samp{,} for separating decimal
329 fractions). There have been problems reported where the library linked
330 with GCC does not produce the same floating-point formats that the
331 assembler accepts. If you have this problem, set the @env{LANG}
332 environment variable to @samp{C} or @samp{En_US}.
333
334 @item
335 @opindex fdollars-in-identifiers
336 Even if you specify @option{-fdollars-in-identifiers},
337 you cannot successfully use @samp{$} in identifiers on the RS/6000 due
338 to a restriction in the IBM assembler.  GAS supports these
339 identifiers.
340
341 @cindex VAX calling convention
342 @cindex Ultrix calling convention
343 @item
344 @opindex fcall-saved
345 On Ultrix, the Fortran compiler expects registers 2 through 5 to be saved
346 by function calls.  However, the C compiler uses conventions compatible
347 with BSD Unix: registers 2 through 5 may be clobbered by function calls.
348
349 GCC uses the same convention as the Ultrix C compiler.  You can use
350 these options to produce code compatible with the Fortran compiler:
351
352 @smallexample
353 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
354 @end smallexample
355
356 @item
357 On the Alpha, you may get assembler errors about invalid syntax as a
358 result of floating point constants.  This is due to a bug in the C
359 library functions @code{ecvt}, @code{fcvt} and @code{gcvt}.  Given valid
360 floating point numbers, they sometimes print @samp{NaN}.
361 @end itemize
362
363 @node External Bugs
364 @section Problems Compiling Certain Programs
365
366 @c prevent bad page break with this line
367 Certain programs have problems compiling.
368
369 @itemize @bullet
370 @item
371 Parse errors may occur compiling X11 on a Decstation running Ultrix 4.2
372 because of problems in DEC's versions of the X11 header files
373 @file{X11/Xlib.h} and @file{X11/Xutil.h}.  People recommend adding
374 @option{-I/usr/include/mit} to use the MIT versions of the header files,
375 or fixing the header files by adding this:
376
377 @smallexample
378 #ifdef __STDC__
379 #define NeedFunctionPrototypes 0
380 #endif
381 @end smallexample
382
383 @item
384 On various 386 Unix systems derived from System V, including SCO, ISC,
385 and ESIX, you may get error messages about running out of virtual memory
386 while compiling certain programs.
387
388 You can prevent this problem by linking GCC with the GNU malloc
389 (which thus replaces the malloc that comes with the system).  GNU malloc
390 is available as a separate package, and also in the file
391 @file{src/gmalloc.c} in the GNU Emacs 19 distribution.
392
393 If you have installed GNU malloc as a separate library package, use this
394 option when you relink GCC:
395
396 @smallexample
397 MALLOC=/usr/local/lib/libgmalloc.a
398 @end smallexample
399
400 Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
401 the object file to @file{gmalloc.o} and use this option when you relink
402 GCC:
403
404 @smallexample
405 MALLOC=gmalloc.o
406 @end smallexample
407 @end itemize
408
409 @node Incompatibilities
410 @section Incompatibilities of GCC
411 @cindex incompatibilities of GCC
412 @opindex traditional
413
414 There are several noteworthy incompatibilities between GNU C and K&R
415 (non-ISO) versions of C@.
416
417 @itemize @bullet
418 @cindex string constants
419 @cindex read-only strings
420 @cindex shared strings
421 @item
422 GCC normally makes string constants read-only.  If several
423 identical-looking string constants are used, GCC stores only one
424 copy of the string.
425
426 @cindex @code{mktemp}, and constant strings
427 One consequence is that you cannot call @code{mktemp} with a string
428 constant argument.  The function @code{mktemp} always alters the
429 string its argument points to.
430
431 @cindex @code{sscanf}, and constant strings
432 @cindex @code{fscanf}, and constant strings
433 @cindex @code{scanf}, and constant strings
434 Another consequence is that @code{sscanf} does not work on some very
435 old systems when passed a string constant as its format control string
436 or input.  This is because @code{sscanf} incorrectly tries to write
437 into the string constant.  Likewise @code{fscanf} and @code{scanf}.
438
439 The solution to these problems is to change the program to use
440 @code{char}-array variables with initialization strings for these
441 purposes instead of string constants.
442
443 @item
444 @code{-2147483648} is positive.
445
446 This is because 2147483648 cannot fit in the type @code{int}, so
447 (following the ISO C rules) its data type is @code{unsigned long int}.
448 Negating this value yields 2147483648 again.
449
450 @item
451 GCC does not substitute macro arguments when they appear inside of
452 string constants.  For example, the following macro in GCC
453
454 @smallexample
455 #define foo(a) "a"
456 @end smallexample
457
458 @noindent
459 will produce output @code{"a"} regardless of what the argument @var{a} is.
460
461 @cindex @code{setjmp} incompatibilities
462 @cindex @code{longjmp} incompatibilities
463 @item
464 When you use @code{setjmp} and @code{longjmp}, the only automatic
465 variables guaranteed to remain valid are those declared
466 @code{volatile}.  This is a consequence of automatic register
467 allocation.  Consider this function:
468
469 @smallexample
470 jmp_buf j;
471
472 foo ()
473 @{
474   int a, b;
475
476   a = fun1 ();
477   if (setjmp (j))
478     return a;
479
480   a = fun2 ();
481   /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */
482   return a + fun3 ();
483 @}
484 @end smallexample
485
486 Here @code{a} may or may not be restored to its first value when the
487 @code{longjmp} occurs.  If @code{a} is allocated in a register, then
488 its first value is restored; otherwise, it keeps the last value stored
489 in it.
490
491 @opindex W
492 If you use the @option{-W} option with the @option{-O} option, you will
493 get a warning when GCC thinks such a problem might be possible.
494
495 @item
496 Programs that use preprocessing directives in the middle of macro
497 arguments do not work with GCC@.  For example, a program like this
498 will not work:
499
500 @smallexample
501 @group
502 foobar (
503 #define luser
504         hack)
505 @end group
506 @end smallexample
507
508 ISO C does not permit such a construct.
509
510 @item
511 K&R compilers allow comments to cross over an inclusion boundary
512 (i.e.@: started in an include file and ended in the including file).  I think
513 this would be quite ugly and can't imagine it could be needed.
514
515 @cindex external declaration scope
516 @cindex scope of external declarations
517 @cindex declaration scope
518 @item
519 Declarations of external variables and functions within a block apply
520 only to the block containing the declaration.  In other words, they
521 have the same scope as any other declaration in the same place.
522
523 In some other C compilers, a @code{extern} declaration affects all the
524 rest of the file even if it happens within a block.
525
526 @item
527 In traditional C, you can combine @code{long}, etc., with a typedef name,
528 as shown here:
529
530 @smallexample
531 typedef int foo;
532 typedef long foo bar;
533 @end smallexample
534
535 In ISO C, this is not allowed: @code{long} and other type modifiers
536 require an explicit @code{int}.
537
538 @cindex typedef names as function parameters
539 @item
540 PCC allows typedef names to be used as function parameters.
541
542 @item
543 Traditional C allows the following erroneous pair of declarations to
544 appear together in a given scope:
545
546 @smallexample
547 typedef int foo;
548 typedef foo foo;
549 @end smallexample
550
551 @item
552 GCC treats all characters of identifiers as significant.  According to
553 K&R-1 (2.2), ``No more than the first eight characters are significant,
554 although more may be used.''.  Also according to K&R-1 (2.2), ``An
555 identifier is a sequence of letters and digits; the first character must
556 be a letter.  The underscore _ counts as a letter.'', but GCC also
557 allows dollar signs in identifiers.
558
559 @cindex whitespace
560 @item
561 PCC allows whitespace in the middle of compound assignment operators
562 such as @samp{+=}.  GCC, following the ISO standard, does not
563 allow this.
564
565 @cindex apostrophes
566 @cindex '
567 @item
568 GCC complains about unterminated character constants inside of
569 preprocessing conditionals that fail.  Some programs have English
570 comments enclosed in conditionals that are guaranteed to fail; if these
571 comments contain apostrophes, GCC will probably report an error.  For
572 example, this code would produce an error:
573
574 @smallexample
575 #if 0
576 You can't expect this to work.
577 #endif
578 @end smallexample
579
580 The best solution to such a problem is to put the text into an actual
581 C comment delimited by @samp{/*@dots{}*/}.
582
583 @item
584 Many user programs contain the declaration @samp{long time ();}.  In the
585 past, the system header files on many systems did not actually declare
586 @code{time}, so it did not matter what type your program declared it to
587 return.  But in systems with ISO C headers, @code{time} is declared to
588 return @code{time_t}, and if that is not the same as @code{long}, then
589 @samp{long time ();} is erroneous.
590
591 The solution is to change your program to use appropriate system headers
592 (@code{<time.h>} on systems with ISO C headers) and not to declare
593 @code{time} if the system header files declare it, or failing that to
594 use @code{time_t} as the return type of @code{time}.
595
596 @cindex @code{float} as function value type
597 @item
598 When compiling functions that return @code{float}, PCC converts it to
599 a double.  GCC actually returns a @code{float}.  If you are concerned
600 with PCC compatibility, you should declare your functions to return
601 @code{double}; you might as well say what you mean.
602
603 @cindex structures
604 @cindex unions
605 @item
606 When compiling functions that return structures or unions, GCC
607 output code normally uses a method different from that used on most
608 versions of Unix.  As a result, code compiled with GCC cannot call
609 a structure-returning function compiled with PCC, and vice versa.
610
611 The method used by GCC is as follows: a structure or union which is
612 1, 2, 4 or 8 bytes long is returned like a scalar.  A structure or union
613 with any other size is stored into an address supplied by the caller
614 (usually in a special, fixed register, but on some machines it is passed
615 on the stack).  The target hook @code{TARGET_STRUCT_VALUE_RTX}
616 tells GCC where to pass this address.
617
618 By contrast, PCC on most target machines returns structures and unions
619 of any size by copying the data into an area of static storage, and then
620 returning the address of that storage as if it were a pointer value.
621 The caller must copy the data from that memory area to the place where
622 the value is wanted.  GCC does not use this method because it is
623 slower and nonreentrant.
624
625 On some newer machines, PCC uses a reentrant convention for all
626 structure and union returning.  GCC on most of these machines uses a
627 compatible convention when returning structures and unions in memory,
628 but still returns small structures and unions in registers.
629
630 @opindex fpcc-struct-return
631 You can tell GCC to use a compatible convention for all structure and
632 union returning with the option @option{-fpcc-struct-return}.
633
634 @cindex preprocessing tokens
635 @cindex preprocessing numbers
636 @item
637 GCC complains about program fragments such as @samp{0x74ae-0x4000}
638 which appear to be two hexadecimal constants separated by the minus
639 operator.  Actually, this string is a single @dfn{preprocessing token}.
640 Each such token must correspond to one token in C@.  Since this does not,
641 GCC prints an error message.  Although it may appear obvious that what
642 is meant is an operator and two values, the ISO C standard specifically
643 requires that this be treated as erroneous.
644
645 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
646 begins with a digit and is followed by letters, underscores, digits,
647 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
648 @samp{p-}, @samp{P+}, or @samp{P-} character sequences.  (In strict C89
649 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
650 appear in preprocessing numbers.)
651
652 To make the above program fragment valid, place whitespace in front of
653 the minus sign.  This whitespace will end the preprocessing number.
654 @end itemize
655
656 @node Fixed Headers
657 @section Fixed Header Files
658
659 GCC needs to install corrected versions of some system header files.
660 This is because most target systems have some header files that won't
661 work with GCC unless they are changed.  Some have bugs, some are
662 incompatible with ISO C, and some depend on special features of other
663 compilers.
664
665 Installing GCC automatically creates and installs the fixed header
666 files, by running a program called @code{fixincludes} (or for certain
667 targets an alternative such as @code{fixinc.svr4}).  Normally, you
668 don't need to pay attention to this.  But there are cases where it
669 doesn't do the right thing automatically.
670
671 @itemize @bullet
672 @item
673 If you update the system's header files, such as by installing a new
674 system version, the fixed header files of GCC are not automatically
675 updated.  The easiest way to update them is to reinstall GCC@.  (If
676 you want to be clever, look in the makefile and you can find a
677 shortcut.)
678
679 @item
680 On some systems, in particular SunOS 4, header file directories contain
681 machine-specific symbolic links in certain places.  This makes it
682 possible to share most of the header files among hosts running the
683 same version of SunOS 4 on different machine models.
684
685 The programs that fix the header files do not understand this special
686 way of using symbolic links; therefore, the directory of fixed header
687 files is good only for the machine model used to build it.
688
689 In SunOS 4, only programs that look inside the kernel will notice the
690 difference between machine models.  Therefore, for most purposes, you
691 need not be concerned about this.
692
693 It is possible to make separate sets of fixed header files for the
694 different machine models, and arrange a structure of symbolic links so
695 as to use the proper set, but you'll have to do this by hand.
696
697 @item
698 On Lynxos, GCC by default does not fix the header files.  This is
699 because bugs in the shell cause the @code{fixincludes} script to fail.
700
701 This means you will encounter problems due to bugs in the system header
702 files.  It may be no comfort that they aren't GCC's fault, but it
703 does mean that there's nothing for us to do about them.
704 @end itemize
705
706 @node Standard Libraries
707 @section Standard Libraries
708
709 @opindex Wall
710 GCC by itself attempts to be a conforming freestanding implementation.
711 @xref{Standards,,Language Standards Supported by GCC}, for details of
712 what this means.  Beyond the library facilities required of such an
713 implementation, the rest of the C library is supplied by the vendor of
714 the operating system.  If that C library doesn't conform to the C
715 standards, then your programs might get warnings (especially when using
716 @option{-Wall}) that you don't expect.
717
718 For example, the @code{sprintf} function on SunOS 4.1.3 returns
719 @code{char *} while the C standard says that @code{sprintf} returns an
720 @code{int}.  The @code{fixincludes} program could make the prototype for
721 this function match the Standard, but that would be wrong, since the
722 function will still return @code{char *}.
723
724 If you need a Standard compliant library, then you need to find one, as
725 GCC does not provide one.  The GNU C library (called @code{glibc})
726 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
727 GNU/Linux and HURD-based GNU systems; no recent version of it supports
728 other systems, though some very old versions did.  Version 2.2 of the
729 GNU C library includes nearly complete C99 support.  You could also ask
730 your operating system vendor if newer libraries are available.
731
732 @node Disappointments
733 @section Disappointments and Misunderstandings
734
735 These problems are perhaps regrettable, but we don't know any practical
736 way around them.
737
738 @itemize @bullet
739 @item
740 Certain local variables aren't recognized by debuggers when you compile
741 with optimization.
742
743 This occurs because sometimes GCC optimizes the variable out of
744 existence.  There is no way to tell the debugger how to compute the
745 value such a variable ``would have had'', and it is not clear that would
746 be desirable anyway.  So GCC simply does not mention the eliminated
747 variable when it writes debugging information.
748
749 You have to expect a certain amount of disagreement between the
750 executable and your source code, when you use optimization.
751
752 @cindex conflicting types
753 @cindex scope of declaration
754 @item
755 Users often think it is a bug when GCC reports an error for code
756 like this:
757
758 @smallexample
759 int foo (struct mumble *);
760
761 struct mumble @{ @dots{} @};
762
763 int foo (struct mumble *x)
764 @{ @dots{} @}
765 @end smallexample
766
767 This code really is erroneous, because the scope of @code{struct
768 mumble} in the prototype is limited to the argument list containing it.
769 It does not refer to the @code{struct mumble} defined with file scope
770 immediately below---they are two unrelated types with similar names in
771 different scopes.
772
773 But in the definition of @code{foo}, the file-scope type is used
774 because that is available to be inherited.  Thus, the definition and
775 the prototype do not match, and you get an error.
776
777 This behavior may seem silly, but it's what the ISO standard specifies.
778 It is easy enough for you to make your code work by moving the
779 definition of @code{struct mumble} above the prototype.  It's not worth
780 being incompatible with ISO C just to avoid an error for the example
781 shown above.
782
783 @item
784 Accesses to bit-fields even in volatile objects works by accessing larger
785 objects, such as a byte or a word.  You cannot rely on what size of
786 object is accessed in order to read or write the bit-field; it may even
787 vary for a given bit-field according to the precise usage.
788
789 If you care about controlling the amount of memory that is accessed, use
790 volatile but do not use bit-fields.
791
792 @item
793 GCC comes with shell scripts to fix certain known problems in system
794 header files.  They install corrected copies of various header files in
795 a special directory where only GCC will normally look for them.  The
796 scripts adapt to various systems by searching all the system header
797 files for the problem cases that we know about.
798
799 If new system header files are installed, nothing automatically arranges
800 to update the corrected header files.  You will have to reinstall GCC
801 to fix the new header files.  More specifically, go to the build
802 directory and delete the files @file{stmp-fixinc} and
803 @file{stmp-headers}, and the subdirectory @code{include}; then do
804 @samp{make install} again.
805
806 @item
807 @cindex floating point precision
808 On 68000 and x86 systems, for instance, you can get paradoxical results
809 if you test the precise values of floating point numbers.  For example,
810 you can find that a floating point value which is not a NaN is not equal
811 to itself.  This results from the fact that the floating point registers
812 hold a few more bits of precision than fit in a @code{double} in memory.
813 Compiled code moves values between memory and floating point registers
814 at its convenience, and moving them into memory truncates them.
815
816 @opindex ffloat-store
817 You can partially avoid this problem by using the @option{-ffloat-store}
818 option (@pxref{Optimize Options}).
819
820 @item
821 On AIX and other platforms without weak symbol support, templates
822 need to be instantiated explicitly and symbols for static members
823 of templates will not be generated.
824
825 @item
826 On AIX, GCC scans object files and library archives for static
827 constructors and destructors when linking an application before the
828 linker prunes unreferenced symbols.  This is necessary to prevent the
829 AIX linker from mistakenly assuming that static constructor or
830 destructor are unused and removing them before the scanning can occur.
831 All static constructors and destructors found will be referenced even
832 though the modules in which they occur may not be used by the program.
833 This may lead to both increased executable size and unexpected symbol
834 references.
835 @end itemize
836
837 @node C++ Misunderstandings
838 @section Common Misunderstandings with GNU C++
839
840 @cindex misunderstandings in C++
841 @cindex surprises in C++
842 @cindex C++ misunderstandings
843 C++ is a complex language and an evolving one, and its standard
844 definition (the ISO C++ standard) was only recently completed.  As a
845 result, your C++ compiler may occasionally surprise you, even when its
846 behavior is correct.  This section discusses some areas that frequently
847 give rise to questions of this sort.
848
849 @menu
850 * Static Definitions::  Static member declarations are not definitions
851 * Name lookup::         Name lookup, templates, and accessing members of base classes
852 * Temporaries::         Temporaries may vanish before you expect
853 * Copy Assignment::     Copy Assignment operators copy virtual bases twice
854 @end menu
855
856 @node Static Definitions
857 @subsection Declare @emph{and} Define Static Members
858
859 @cindex C++ static data, declaring and defining
860 @cindex static data in C++, declaring and defining
861 @cindex declaring static data in C++
862 @cindex defining static data in C++
863 When a class has static data members, it is not enough to @emph{declare}
864 the static member; you must also @emph{define} it.  For example:
865
866 @smallexample
867 class Foo
868 @{
869   @dots{}
870   void method();
871   static int bar;
872 @};
873 @end smallexample
874
875 This declaration only establishes that the class @code{Foo} has an
876 @code{int} named @code{Foo::bar}, and a member function named
877 @code{Foo::method}.  But you still need to define @emph{both}
878 @code{method} and @code{bar} elsewhere.  According to the ISO
879 standard, you must supply an initializer in one (and only one) source
880 file, such as:
881
882 @smallexample
883 int Foo::bar = 0;
884 @end smallexample
885
886 Other C++ compilers may not correctly implement the standard behavior.
887 As a result, when you switch to @command{g++} from one of these compilers,
888 you may discover that a program that appeared to work correctly in fact
889 does not conform to the standard: @command{g++} reports as undefined
890 symbols any static data members that lack definitions.
891
892
893 @node Name lookup
894 @subsection Name lookup, templates, and accessing members of base classes
895
896 @cindex base class members
897 @cindex two-stage name lookup
898 @cindex dependent name lookup
899
900 The C++ standard prescribes that all names that are not dependent on
901 template parameters are bound to their present definitions when parsing
902 a template function or class.@footnote{The C++ standard just uses the
903 term ``dependent'' for names that depend on the type or value of
904 template parameters.  This shorter term will also be used in the rest of
905 this section.}  Only names that are dependent are looked up at the point
906 of instantiation.  For example, consider
907
908 @smallexample
909   void foo(double);
910
911   struct A @{
912     template <typename T>
913     void f () @{
914       foo (1);        // 1
915       int i = N;      // 2
916       T t;
917       t.bar();        // 3
918       foo (t);        // 4
919     @}
920
921     static const int N;
922   @};
923 @end smallexample
924
925 Here, the names @code{foo} and @code{N} appear in a context that does
926 not depend on the type of @code{T}.  The compiler will thus require that
927 they are defined in the context of use in the template, not only before
928 the point of instantiation, and will here use @code{::foo(double)} and
929 @code{A::N}, respectively.  In particular, it will convert the integer
930 value to a @code{double} when passing it to @code{::foo(double)}.
931
932 Conversely, @code{bar} and the call to @code{foo} in the fourth marked
933 line are used in contexts that do depend on the type of @code{T}, so
934 they are only looked up at the point of instantiation, and you can
935 provide declarations for them after declaring the template, but before
936 instantiating it.  In particular, if you instantiate @code{A::f<int>},
937 the last line will call an overloaded @code{::foo(int)} if one was
938 provided, even if after the declaration of @code{struct A}.
939
940 This distinction between lookup of dependent and non-dependent names is
941 called two-stage (or dependent) name lookup.  G++ implements it
942 since version 3.4.
943
944 Two-stage name lookup sometimes leads to situations with behavior
945 different from non-template codes. The most common is probably this:
946
947 @smallexample
948   template <typename T> struct Base @{
949     int i;
950   @};
951
952   template <typename T> struct Derived : public Base<T> @{
953     int get_i() @{ return i; @}
954   @};
955 @end smallexample
956
957 In @code{get_i()}, @code{i} is not used in a dependent context, so the
958 compiler will look for a name declared at the enclosing namespace scope
959 (which is the global scope here).  It will not look into the base class,
960 since that is dependent and you may declare specializations of
961 @code{Base} even after declaring @code{Derived}, so the compiler can't
962 really know what @code{i} would refer to.  If there is no global
963 variable @code{i}, then you will get an error message.
964
965 In order to make it clear that you want the member of the base class,
966 you need to defer lookup until instantiation time, at which the base
967 class is known.  For this, you need to access @code{i} in a dependent
968 context, by either using @code{this->i} (remember that @code{this} is of
969 type @code{Derived<T>*}, so is obviously dependent), or using
970 @code{Base<T>::i}. Alternatively, @code{Base<T>::i} might be brought
971 into scope by a @code{using}-declaration.
972
973 Another, similar example involves calling member functions of a base
974 class:
975
976 @smallexample
977   template <typename T> struct Base @{
978       int f();
979   @};
980
981   template <typename T> struct Derived : Base<T> @{
982       int g() @{ return f(); @};
983   @};
984 @end smallexample
985
986 Again, the call to @code{f()} is not dependent on template arguments
987 (there are no arguments that depend on the type @code{T}, and it is also
988 not otherwise specified that the call should be in a dependent context).
989 Thus a global declaration of such a function must be available, since
990 the one in the base class is not visible until instantiation time.  The
991 compiler will consequently produce the following error message:
992
993 @smallexample
994   x.cc: In member function `int Derived<T>::g()':
995   x.cc:6: error: there are no arguments to `f' that depend on a template
996      parameter, so a declaration of `f' must be available
997   x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but
998      allowing the use of an undeclared name is deprecated)
999 @end smallexample
1000
1001 To make the code valid either use @code{this->f()}, or
1002 @code{Base<T>::f()}.  Using the @code{-fpermissive} flag will also let
1003 the compiler accept the code, by marking all function calls for which no
1004 declaration is visible at the time of definition of the template for
1005 later lookup at instantiation time, as if it were a dependent call.
1006 We do not recommend using @code{-fpermissive} to work around invalid
1007 code, and it will also only catch cases where functions in base classes
1008 are called, not where variables in base classes are used (as in the
1009 example above).
1010
1011 Note that some compilers (including G++ versions prior to 3.4) get these
1012 examples wrong and accept above code without an error.  Those compilers
1013 do not implement two-stage name lookup correctly.
1014
1015
1016 @node Temporaries
1017 @subsection Temporaries May Vanish Before You Expect
1018
1019 @cindex temporaries, lifetime of
1020 @cindex portions of temporary objects, pointers to
1021 It is dangerous to use pointers or references to @emph{portions} of a
1022 temporary object.  The compiler may very well delete the object before
1023 you expect it to, leaving a pointer to garbage.  The most common place
1024 where this problem crops up is in classes like string classes,
1025 especially ones that define a conversion function to type @code{char *}
1026 or @code{const char *}---which is one reason why the standard
1027 @code{string} class requires you to call the @code{c_str} member
1028 function.  However, any class that returns a pointer to some internal
1029 structure is potentially subject to this problem.
1030
1031 For example, a program may use a function @code{strfunc} that returns
1032 @code{string} objects, and another function @code{charfunc} that
1033 operates on pointers to @code{char}:
1034
1035 @smallexample
1036 string strfunc ();
1037 void charfunc (const char *);
1038
1039 void
1040 f ()
1041 @{
1042   const char *p = strfunc().c_str();
1043   @dots{}
1044   charfunc (p);
1045   @dots{}
1046   charfunc (p);
1047 @}
1048 @end smallexample
1049
1050 @noindent
1051 In this situation, it may seem reasonable to save a pointer to the C
1052 string returned by the @code{c_str} member function and use that rather
1053 than call @code{c_str} repeatedly.  However, the temporary string
1054 created by the call to @code{strfunc} is destroyed after @code{p} is
1055 initialized, at which point @code{p} is left pointing to freed memory.
1056
1057 Code like this may run successfully under some other compilers,
1058 particularly obsolete cfront-based compilers that delete temporaries
1059 along with normal local variables.  However, the GNU C++ behavior is
1060 standard-conforming, so if your program depends on late destruction of
1061 temporaries it is not portable.
1062
1063 The safe way to write such code is to give the temporary a name, which
1064 forces it to remain until the end of the scope of the name.  For
1065 example:
1066
1067 @smallexample
1068 string& tmp = strfunc ();
1069 charfunc (tmp.c_str ());
1070 @end smallexample
1071
1072 @node Copy Assignment
1073 @subsection Implicit Copy-Assignment for Virtual Bases
1074
1075 When a base class is virtual, only one subobject of the base class
1076 belongs to each full object.  Also, the constructors and destructors are
1077 invoked only once, and called from the most-derived class.  However, such
1078 objects behave unspecified when being assigned.  For example:
1079
1080 @smallexample
1081 struct Base@{
1082   char *name;
1083   Base(char *n) : name(strdup(n))@{@}
1084   Base& operator= (const Base& other)@{
1085    free (name);
1086    name = strdup (other.name);
1087   @}
1088 @};
1089
1090 struct A:virtual Base@{
1091   int val;
1092   A():Base("A")@{@}
1093 @};
1094
1095 struct B:virtual Base@{
1096   int bval;
1097   B():Base("B")@{@}
1098 @};
1099
1100 struct Derived:public A, public B@{
1101   Derived():Base("Derived")@{@}
1102 @};
1103
1104 void func(Derived &d1, Derived &d2)
1105 @{
1106   d1 = d2;
1107 @}
1108 @end smallexample
1109
1110 The C++ standard specifies that @samp{Base::Base} is only called once
1111 when constructing or copy-constructing a Derived object.  It is
1112 unspecified whether @samp{Base::operator=} is called more than once when
1113 the implicit copy-assignment for Derived objects is invoked (as it is
1114 inside @samp{func} in the example).
1115
1116 G++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1117 direct bases, then assign all members.  In that algorithm, the virtual
1118 base subobject can be encountered more than once.  In the example, copying
1119 proceeds in the following order: @samp{val}, @samp{name} (via
1120 @code{strdup}), @samp{bval}, and @samp{name} again.
1121
1122 If application code relies on copy-assignment, a user-defined
1123 copy-assignment operator removes any uncertainties.  With such an
1124 operator, the application can define whether and how the virtual base
1125 subobject is assigned.
1126
1127 @node Protoize Caveats
1128 @section Caveats of using @command{protoize}
1129
1130 The conversion programs @command{protoize} and @command{unprotoize} can
1131 sometimes change a source file in a way that won't work unless you
1132 rearrange it.
1133
1134 @itemize @bullet
1135 @item
1136 @command{protoize} can insert references to a type name or type tag before
1137 the definition, or in a file where they are not defined.
1138
1139 If this happens, compiler error messages should show you where the new
1140 references are, so fixing the file by hand is straightforward.
1141
1142 @item
1143 There are some C constructs which @command{protoize} cannot figure out.
1144 For example, it can't determine argument types for declaring a
1145 pointer-to-function variable; this you must do by hand.  @command{protoize}
1146 inserts a comment containing @samp{???} each time it finds such a
1147 variable; so you can find all such variables by searching for this
1148 string.  ISO C does not require declaring the argument types of
1149 pointer-to-function types.
1150
1151 @item
1152 Using @command{unprotoize} can easily introduce bugs.  If the program
1153 relied on prototypes to bring about conversion of arguments, these
1154 conversions will not take place in the program without prototypes.
1155 One case in which you can be sure @command{unprotoize} is safe is when
1156 you are removing prototypes that were made with @command{protoize}; if
1157 the program worked before without any prototypes, it will work again
1158 without them.
1159
1160 @opindex Wconversion
1161 You can find all the places where this problem might occur by compiling
1162 the program with the @option{-Wconversion} option.  It prints a warning
1163 whenever an argument is converted.
1164
1165 @item
1166 Both conversion programs can be confused if there are macro calls in and
1167 around the text to be converted.  In other words, the standard syntax
1168 for a declaration or definition must not result from expanding a macro.
1169 This problem is inherent in the design of C and cannot be fixed.  If
1170 only a few functions have confusing macro calls, you can easily convert
1171 them manually.
1172
1173 @item
1174 @command{protoize} cannot get the argument types for a function whose
1175 definition was not actually compiled due to preprocessing conditionals.
1176 When this happens, @command{protoize} changes nothing in regard to such
1177 a function.  @command{protoize} tries to detect such instances and warn
1178 about them.
1179
1180 You can generally work around this problem by using @command{protoize} step
1181 by step, each time specifying a different set of @option{-D} options for
1182 compilation, until all of the functions have been converted.  There is
1183 no automatic way to verify that you have got them all, however.
1184
1185 @item
1186 Confusion may result if there is an occasion to convert a function
1187 declaration or definition in a region of source code where there is more
1188 than one formal parameter list present.  Thus, attempts to convert code
1189 containing multiple (conditionally compiled) versions of a single
1190 function header (in the same vicinity) may not produce the desired (or
1191 expected) results.
1192
1193 If you plan on converting source files which contain such code, it is
1194 recommended that you first make sure that each conditionally compiled
1195 region of source code which contains an alternative function header also
1196 contains at least one additional follower token (past the final right
1197 parenthesis of the function header).  This should circumvent the
1198 problem.
1199
1200 @item
1201 @command{unprotoize} can become confused when trying to convert a function
1202 definition or declaration which contains a declaration for a
1203 pointer-to-function formal argument which has the same name as the
1204 function being defined or declared.  We recommend you avoid such choices
1205 of formal parameter names.
1206
1207 @item
1208 You might also want to correct some of the indentation by hand and break
1209 long lines.  (The conversion programs don't write lines longer than
1210 eighty characters in any case.)
1211 @end itemize
1212
1213 @node Non-bugs
1214 @section Certain Changes We Don't Want to Make
1215
1216 This section lists changes that people frequently request, but which
1217 we do not make because we think GCC is better without them.
1218
1219 @itemize @bullet
1220 @item
1221 Checking the number and type of arguments to a function which has an
1222 old-fashioned definition and no prototype.
1223
1224 Such a feature would work only occasionally---only for calls that appear
1225 in the same file as the called function, following the definition.  The
1226 only way to check all calls reliably is to add a prototype for the
1227 function.  But adding a prototype eliminates the motivation for this
1228 feature.  So the feature is not worthwhile.
1229
1230 @item
1231 Warning about using an expression whose type is signed as a shift count.
1232
1233 Shift count operands are probably signed more often than unsigned.
1234 Warning about this would cause far more annoyance than good.
1235
1236 @item
1237 Warning about assigning a signed value to an unsigned variable.
1238
1239 Such assignments must be very common; warning about them would cause
1240 more annoyance than good.
1241
1242 @item
1243 Warning when a non-void function value is ignored.
1244
1245 Coming as I do from a Lisp background, I balk at the idea that there is
1246 something dangerous about discarding a value.  There are functions that
1247 return values which some callers may find useful; it makes no sense to
1248 clutter the program with a cast to @code{void} whenever the value isn't
1249 useful.
1250
1251 @item
1252 @opindex fshort-enums
1253 Making @option{-fshort-enums} the default.
1254
1255 This would cause storage layout to be incompatible with most other C
1256 compilers.  And it doesn't seem very important, given that you can get
1257 the same result in other ways.  The case where it matters most is when
1258 the enumeration-valued object is inside a structure, and in that case
1259 you can specify a field width explicitly.
1260
1261 @item
1262 Making bit-fields unsigned by default on particular machines where ``the
1263 ABI standard'' says to do so.
1264
1265 The ISO C standard leaves it up to the implementation whether a bit-field
1266 declared plain @code{int} is signed or not.  This in effect creates two
1267 alternative dialects of C@.
1268
1269 @opindex fsigned-bitfields
1270 @opindex funsigned-bitfields
1271 The GNU C compiler supports both dialects; you can specify the signed
1272 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1273 @option{-funsigned-bitfields}.  However, this leaves open the question of
1274 which dialect to use by default.
1275
1276 Currently, the preferred dialect makes plain bit-fields signed, because
1277 this is simplest.  Since @code{int} is the same as @code{signed int} in
1278 every other context, it is cleanest for them to be the same in bit-fields
1279 as well.
1280
1281 Some computer manufacturers have published Application Binary Interface
1282 standards which specify that plain bit-fields should be unsigned.  It is
1283 a mistake, however, to say anything about this issue in an ABI@.  This is
1284 because the handling of plain bit-fields distinguishes two dialects of C@.
1285 Both dialects are meaningful on every type of machine.  Whether a
1286 particular object file was compiled using signed bit-fields or unsigned
1287 is of no concern to other object files, even if they access the same
1288 bit-fields in the same data structures.
1289
1290 A given program is written in one or the other of these two dialects.
1291 The program stands a chance to work on most any machine if it is
1292 compiled with the proper dialect.  It is unlikely to work at all if
1293 compiled with the wrong dialect.
1294
1295 Many users appreciate the GNU C compiler because it provides an
1296 environment that is uniform across machines.  These users would be
1297 inconvenienced if the compiler treated plain bit-fields differently on
1298 certain machines.
1299
1300 Occasionally users write programs intended only for a particular machine
1301 type.  On these occasions, the users would benefit if the GNU C compiler
1302 were to support by default the same dialect as the other compilers on
1303 that machine.  But such applications are rare.  And users writing a
1304 program to run on more than one type of machine cannot possibly benefit
1305 from this kind of compatibility.
1306
1307 This is why GCC does and will treat plain bit-fields in the same
1308 fashion on all types of machines (by default).
1309
1310 There are some arguments for making bit-fields unsigned by default on all
1311 machines.  If, for example, this becomes a universal de facto standard,
1312 it would make sense for GCC to go along with it.  This is something
1313 to be considered in the future.
1314
1315 (Of course, users strongly concerned about portability should indicate
1316 explicitly in each bit-field whether it is signed or not.  In this way,
1317 they write programs which have the same meaning in both C dialects.)
1318
1319 @item
1320 @opindex ansi
1321 @opindex std
1322 Undefining @code{__STDC__} when @option{-ansi} is not used.
1323
1324 Currently, GCC defines @code{__STDC__} unconditionally.  This provides
1325 good results in practice.
1326
1327 Programmers normally use conditionals on @code{__STDC__} to ask whether
1328 it is safe to use certain features of ISO C, such as function
1329 prototypes or ISO token concatenation.  Since plain @command{gcc} supports
1330 all the features of ISO C, the correct answer to these questions is
1331 ``yes''.
1332
1333 Some users try to use @code{__STDC__} to check for the availability of
1334 certain library facilities.  This is actually incorrect usage in an ISO
1335 C program, because the ISO C standard says that a conforming
1336 freestanding implementation should define @code{__STDC__} even though it
1337 does not have the library facilities.  @samp{gcc -ansi -pedantic} is a
1338 conforming freestanding implementation, and it is therefore required to
1339 define @code{__STDC__}, even though it does not come with an ISO C
1340 library.
1341
1342 Sometimes people say that defining @code{__STDC__} in a compiler that
1343 does not completely conform to the ISO C standard somehow violates the
1344 standard.  This is illogical.  The standard is a standard for compilers
1345 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1346 compilers such as plain @command{gcc}.  Whatever the ISO C standard says
1347 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1348 for pragmatic reasons, not as a requirement.
1349
1350 GCC normally defines @code{__STDC__} to be 1, and in addition
1351 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1352 or a @option{-std} option for strict conformance to some version of ISO C@.
1353 On some hosts, system include files use a different convention, where
1354 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1355 conformance to the C Standard.  GCC follows the host convention when
1356 processing system include files, but when processing user files it follows
1357 the usual GNU C convention.
1358
1359 @item
1360 Undefining @code{__STDC__} in C++.
1361
1362 Programs written to compile with C++-to-C translators get the
1363 value of @code{__STDC__} that goes with the C compiler that is
1364 subsequently used.  These programs must test @code{__STDC__}
1365 to determine what kind of C preprocessor that compiler uses:
1366 whether they should concatenate tokens in the ISO C fashion
1367 or in the traditional fashion.
1368
1369 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1370 They would not work otherwise.
1371
1372 In addition, many header files are written to provide prototypes in ISO
1373 C but not in traditional C@.  Many of these header files can work without
1374 change in C++ provided @code{__STDC__} is defined.  If @code{__STDC__}
1375 is not defined, they will all fail, and will all need to be changed to
1376 test explicitly for C++ as well.
1377
1378 @item
1379 Deleting ``empty'' loops.
1380
1381 Historically, GCC has not deleted ``empty'' loops under the
1382 assumption that the most likely reason you would put one in a program is
1383 to have a delay, so deleting them will not make real programs run any
1384 faster.
1385
1386 However, the rationale here is that optimization of a nonempty loop
1387 cannot produce an empty one, which holds for C but is not always the
1388 case for C++.
1389
1390 @opindex funroll-loops
1391 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1392 removed, so the current behavior is both sub-optimal and inconsistent
1393 and will change in the future.
1394
1395 @item
1396 Making side effects happen in the same order as in some other compiler.
1397
1398 @cindex side effects, order of evaluation
1399 @cindex order of evaluation, side effects
1400 It is never safe to depend on the order of evaluation of side effects.
1401 For example, a function call like this may very well behave differently
1402 from one compiler to another:
1403
1404 @smallexample
1405 void func (int, int);
1406
1407 int i = 2;
1408 func (i++, i++);
1409 @end smallexample
1410
1411 There is no guarantee (in either the C or the C++ standard language
1412 definitions) that the increments will be evaluated in any particular
1413 order.  Either increment might happen first.  @code{func} might get the
1414 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1415
1416 @item
1417 Making certain warnings into errors by default.
1418
1419 Some ISO C testsuites report failure when the compiler does not produce
1420 an error message for a certain program.
1421
1422 @opindex pedantic-errors
1423 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1424 programs, but a warning is defined by GCC to count as a diagnostic.  If
1425 GCC produces a warning but not an error, that is correct ISO C support.
1426 If testsuites call this ``failure'', they should be run with the GCC
1427 option @option{-pedantic-errors}, which will turn these warnings into
1428 errors.
1429
1430 @end itemize
1431
1432 @node Warnings and Errors
1433 @section Warning Messages and Error Messages
1434
1435 @cindex error messages
1436 @cindex warnings vs errors
1437 @cindex messages, warning and error
1438 The GNU compiler can produce two kinds of diagnostics: errors and
1439 warnings.  Each kind has a different purpose:
1440
1441 @itemize @w{}
1442 @item
1443 @dfn{Errors} report problems that make it impossible to compile your
1444 program.  GCC reports errors with the source file name and line
1445 number where the problem is apparent.
1446
1447 @item
1448 @dfn{Warnings} report other unusual conditions in your code that
1449 @emph{may} indicate a problem, although compilation can (and does)
1450 proceed.  Warning messages also report the source file name and line
1451 number, but include the text @samp{warning:} to distinguish them
1452 from error messages.
1453 @end itemize
1454
1455 Warnings may indicate danger points where you should check to make sure
1456 that your program really does what you intend; or the use of obsolete
1457 features; or the use of nonstandard features of GNU C or C++.  Many
1458 warnings are issued only if you ask for them, with one of the @option{-W}
1459 options (for instance, @option{-Wall} requests a variety of useful
1460 warnings).
1461
1462 @opindex pedantic
1463 @opindex pedantic-errors
1464 GCC always tries to compile your program if possible; it never
1465 gratuitously rejects a program whose meaning is clear merely because
1466 (for instance) it fails to conform to a standard.  In some cases,
1467 however, the C and C++ standards specify that certain extensions are
1468 forbidden, and a diagnostic @emph{must} be issued by a conforming
1469 compiler.  The @option{-pedantic} option tells GCC to issue warnings in
1470 such cases; @option{-pedantic-errors} says to make them errors instead.
1471 This does not mean that @emph{all} non-ISO constructs get warnings
1472 or errors.
1473
1474 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1475 more detail on these and related command-line options.