OSDN Git Service

* doc/bugreport.texi, doc/configterms.texi, doc/contrib.texi,
[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 that can be done about these problems.
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).
513
514 @cindex external declaration scope
515 @cindex scope of external declarations
516 @cindex declaration scope
517 @item
518 Declarations of external variables and functions within a block apply
519 only to the block containing the declaration.  In other words, they
520 have the same scope as any other declaration in the same place.
521
522 In some other C compilers, a @code{extern} declaration affects all the
523 rest of the file even if it happens within a block.
524
525 @item
526 In traditional C, you can combine @code{long}, etc., with a typedef name,
527 as shown here:
528
529 @smallexample
530 typedef int foo;
531 typedef long foo bar;
532 @end smallexample
533
534 In ISO C, this is not allowed: @code{long} and other type modifiers
535 require an explicit @code{int}.
536
537 @cindex typedef names as function parameters
538 @item
539 PCC allows typedef names to be used as function parameters.
540
541 @item
542 Traditional C allows the following erroneous pair of declarations to
543 appear together in a given scope:
544
545 @smallexample
546 typedef int foo;
547 typedef foo foo;
548 @end smallexample
549
550 @item
551 GCC treats all characters of identifiers as significant.  According to
552 K&R-1 (2.2), ``No more than the first eight characters are significant,
553 although more may be used.''.  Also according to K&R-1 (2.2), ``An
554 identifier is a sequence of letters and digits; the first character must
555 be a letter.  The underscore _ counts as a letter.'', but GCC also
556 allows dollar signs in identifiers.
557
558 @cindex whitespace
559 @item
560 PCC allows whitespace in the middle of compound assignment operators
561 such as @samp{+=}.  GCC, following the ISO standard, does not
562 allow this.
563
564 @cindex apostrophes
565 @cindex '
566 @item
567 GCC complains about unterminated character constants inside of
568 preprocessing conditionals that fail.  Some programs have English
569 comments enclosed in conditionals that are guaranteed to fail; if these
570 comments contain apostrophes, GCC will probably report an error.  For
571 example, this code would produce an error:
572
573 @smallexample
574 #if 0
575 You can't expect this to work.
576 #endif
577 @end smallexample
578
579 The best solution to such a problem is to put the text into an actual
580 C comment delimited by @samp{/*@dots{}*/}.
581
582 @item
583 Many user programs contain the declaration @samp{long time ();}.  In the
584 past, the system header files on many systems did not actually declare
585 @code{time}, so it did not matter what type your program declared it to
586 return.  But in systems with ISO C headers, @code{time} is declared to
587 return @code{time_t}, and if that is not the same as @code{long}, then
588 @samp{long time ();} is erroneous.
589
590 The solution is to change your program to use appropriate system headers
591 (@code{<time.h>} on systems with ISO C headers) and not to declare
592 @code{time} if the system header files declare it, or failing that to
593 use @code{time_t} as the return type of @code{time}.
594
595 @cindex @code{float} as function value type
596 @item
597 When compiling functions that return @code{float}, PCC converts it to
598 a double.  GCC actually returns a @code{float}.  If you are concerned
599 with PCC compatibility, you should declare your functions to return
600 @code{double}; you might as well say what you mean.
601
602 @cindex structures
603 @cindex unions
604 @item
605 When compiling functions that return structures or unions, GCC
606 output code normally uses a method different from that used on most
607 versions of Unix.  As a result, code compiled with GCC cannot call
608 a structure-returning function compiled with PCC, and vice versa.
609
610 The method used by GCC is as follows: a structure or union which is
611 1, 2, 4 or 8 bytes long is returned like a scalar.  A structure or union
612 with any other size is stored into an address supplied by the caller
613 (usually in a special, fixed register, but on some machines it is passed
614 on the stack).  The target hook @code{TARGET_STRUCT_VALUE_RTX}
615 tells GCC where to pass this address.
616
617 By contrast, PCC on most target machines returns structures and unions
618 of any size by copying the data into an area of static storage, and then
619 returning the address of that storage as if it were a pointer value.
620 The caller must copy the data from that memory area to the place where
621 the value is wanted.  GCC does not use this method because it is
622 slower and nonreentrant.
623
624 On some newer machines, PCC uses a reentrant convention for all
625 structure and union returning.  GCC on most of these machines uses a
626 compatible convention when returning structures and unions in memory,
627 but still returns small structures and unions in registers.
628
629 @opindex fpcc-struct-return
630 You can tell GCC to use a compatible convention for all structure and
631 union returning with the option @option{-fpcc-struct-return}.
632
633 @cindex preprocessing tokens
634 @cindex preprocessing numbers
635 @item
636 GCC complains about program fragments such as @samp{0x74ae-0x4000}
637 which appear to be two hexadecimal constants separated by the minus
638 operator.  Actually, this string is a single @dfn{preprocessing token}.
639 Each such token must correspond to one token in C@.  Since this does not,
640 GCC prints an error message.  Although it may appear obvious that what
641 is meant is an operator and two values, the ISO C standard specifically
642 requires that this be treated as erroneous.
643
644 A @dfn{preprocessing token} is a @dfn{preprocessing number} if it
645 begins with a digit and is followed by letters, underscores, digits,
646 periods and @samp{e+}, @samp{e-}, @samp{E+}, @samp{E-}, @samp{p+},
647 @samp{p-}, @samp{P+}, or @samp{P-} character sequences.  (In strict C89
648 mode, the sequences @samp{p+}, @samp{p-}, @samp{P+} and @samp{P-} cannot
649 appear in preprocessing numbers.)
650
651 To make the above program fragment valid, place whitespace in front of
652 the minus sign.  This whitespace will end the preprocessing number.
653 @end itemize
654
655 @node Fixed Headers
656 @section Fixed Header Files
657
658 GCC needs to install corrected versions of some system header files.
659 This is because most target systems have some header files that won't
660 work with GCC unless they are changed.  Some have bugs, some are
661 incompatible with ISO C, and some depend on special features of other
662 compilers.
663
664 Installing GCC automatically creates and installs the fixed header
665 files, by running a program called @code{fixincludes} (or for certain
666 targets an alternative such as @code{fixinc.svr4}).  Normally, you
667 don't need to pay attention to this.  But there are cases where it
668 doesn't do the right thing automatically.
669
670 @itemize @bullet
671 @item
672 If you update the system's header files, such as by installing a new
673 system version, the fixed header files of GCC are not automatically
674 updated.  The easiest way to update them is to reinstall GCC@.  (If
675 you want to be clever, look in the makefile and you can find a
676 shortcut.)
677
678 @item
679 On some systems, in particular SunOS 4, header file directories contain
680 machine-specific symbolic links in certain places.  This makes it
681 possible to share most of the header files among hosts running the
682 same version of SunOS 4 on different machine models.
683
684 The programs that fix the header files do not understand this special
685 way of using symbolic links; therefore, the directory of fixed header
686 files is good only for the machine model used to build it.
687
688 In SunOS 4, only programs that look inside the kernel will notice the
689 difference between machine models.  Therefore, for most purposes, you
690 need not be concerned about this.
691
692 It is possible to make separate sets of fixed header files for the
693 different machine models, and arrange a structure of symbolic links so
694 as to use the proper set, but you'll have to do this by hand.
695
696 @item
697 On Lynxos, GCC by default does not fix the header files.  This is
698 because bugs in the shell cause the @code{fixincludes} script to fail.
699
700 This means you will encounter problems due to bugs in the system header
701 files.  It may be no comfort that they aren't GCC's fault, but it
702 does mean that there's nothing for us to do about them.
703 @end itemize
704
705 @node Standard Libraries
706 @section Standard Libraries
707
708 @opindex Wall
709 GCC by itself attempts to be a conforming freestanding implementation.
710 @xref{Standards,,Language Standards Supported by GCC}, for details of
711 what this means.  Beyond the library facilities required of such an
712 implementation, the rest of the C library is supplied by the vendor of
713 the operating system.  If that C library doesn't conform to the C
714 standards, then your programs might get warnings (especially when using
715 @option{-Wall}) that you don't expect.
716
717 For example, the @code{sprintf} function on SunOS 4.1.3 returns
718 @code{char *} while the C standard says that @code{sprintf} returns an
719 @code{int}.  The @code{fixincludes} program could make the prototype for
720 this function match the Standard, but that would be wrong, since the
721 function will still return @code{char *}.
722
723 If you need a Standard compliant library, then you need to find one, as
724 GCC does not provide one.  The GNU C library (called @code{glibc})
725 provides ISO C, POSIX, BSD, SystemV and X/Open compatibility for
726 GNU/Linux and HURD-based GNU systems; no recent version of it supports
727 other systems, though some very old versions did.  Version 2.2 of the
728 GNU C library includes nearly complete C99 support.  You could also ask
729 your operating system vendor if newer libraries are available.
730
731 @node Disappointments
732 @section Disappointments and Misunderstandings
733
734 These problems are perhaps regrettable, but we don't know any practical
735 way around them.
736
737 @itemize @bullet
738 @item
739 Certain local variables aren't recognized by debuggers when you compile
740 with optimization.
741
742 This occurs because sometimes GCC optimizes the variable out of
743 existence.  There is no way to tell the debugger how to compute the
744 value such a variable ``would have had'', and it is not clear that would
745 be desirable anyway.  So GCC simply does not mention the eliminated
746 variable when it writes debugging information.
747
748 You have to expect a certain amount of disagreement between the
749 executable and your source code, when you use optimization.
750
751 @cindex conflicting types
752 @cindex scope of declaration
753 @item
754 Users often think it is a bug when GCC reports an error for code
755 like this:
756
757 @smallexample
758 int foo (struct mumble *);
759
760 struct mumble @{ @dots{} @};
761
762 int foo (struct mumble *x)
763 @{ @dots{} @}
764 @end smallexample
765
766 This code really is erroneous, because the scope of @code{struct
767 mumble} in the prototype is limited to the argument list containing it.
768 It does not refer to the @code{struct mumble} defined with file scope
769 immediately below---they are two unrelated types with similar names in
770 different scopes.
771
772 But in the definition of @code{foo}, the file-scope type is used
773 because that is available to be inherited.  Thus, the definition and
774 the prototype do not match, and you get an error.
775
776 This behavior may seem silly, but it's what the ISO standard specifies.
777 It is easy enough for you to make your code work by moving the
778 definition of @code{struct mumble} above the prototype.  It's not worth
779 being incompatible with ISO C just to avoid an error for the example
780 shown above.
781
782 @item
783 Accesses to bit-fields even in volatile objects works by accessing larger
784 objects, such as a byte or a word.  You cannot rely on what size of
785 object is accessed in order to read or write the bit-field; it may even
786 vary for a given bit-field according to the precise usage.
787
788 If you care about controlling the amount of memory that is accessed, use
789 volatile but do not use bit-fields.
790
791 @item
792 GCC comes with shell scripts to fix certain known problems in system
793 header files.  They install corrected copies of various header files in
794 a special directory where only GCC will normally look for them.  The
795 scripts adapt to various systems by searching all the system header
796 files for the problem cases that we know about.
797
798 If new system header files are installed, nothing automatically arranges
799 to update the corrected header files.  You will have to reinstall GCC
800 to fix the new header files.  More specifically, go to the build
801 directory and delete the files @file{stmp-fixinc} and
802 @file{stmp-headers}, and the subdirectory @code{include}; then do
803 @samp{make install} again.
804
805 @item
806 @cindex floating point precision
807 On 68000 and x86 systems, for instance, you can get paradoxical results
808 if you test the precise values of floating point numbers.  For example,
809 you can find that a floating point value which is not a NaN is not equal
810 to itself.  This results from the fact that the floating point registers
811 hold a few more bits of precision than fit in a @code{double} in memory.
812 Compiled code moves values between memory and floating point registers
813 at its convenience, and moving them into memory truncates them.
814
815 @opindex ffloat-store
816 You can partially avoid this problem by using the @option{-ffloat-store}
817 option (@pxref{Optimize Options}).
818
819 @item
820 On AIX and other platforms without weak symbol support, templates
821 need to be instantiated explicitly and symbols for static members
822 of templates will not be generated.
823
824 @item
825 On AIX, GCC scans object files and library archives for static
826 constructors and destructors when linking an application before the
827 linker prunes unreferenced symbols.  This is necessary to prevent the
828 AIX linker from mistakenly assuming that static constructor or
829 destructor are unused and removing them before the scanning can occur.
830 All static constructors and destructors found will be referenced even
831 though the modules in which they occur may not be used by the program.
832 This may lead to both increased executable size and unexpected symbol
833 references.
834 @end itemize
835
836 @node C++ Misunderstandings
837 @section Common Misunderstandings with GNU C++
838
839 @cindex misunderstandings in C++
840 @cindex surprises in C++
841 @cindex C++ misunderstandings
842 C++ is a complex language and an evolving one, and its standard
843 definition (the ISO C++ standard) was only recently completed.  As a
844 result, your C++ compiler may occasionally surprise you, even when its
845 behavior is correct.  This section discusses some areas that frequently
846 give rise to questions of this sort.
847
848 @menu
849 * Static Definitions::  Static member declarations are not definitions
850 * Name lookup::         Name lookup, templates, and accessing members of base classes
851 * Temporaries::         Temporaries may vanish before you expect
852 * Copy Assignment::     Copy Assignment operators copy virtual bases twice
853 @end menu
854
855 @node Static Definitions
856 @subsection Declare @emph{and} Define Static Members
857
858 @cindex C++ static data, declaring and defining
859 @cindex static data in C++, declaring and defining
860 @cindex declaring static data in C++
861 @cindex defining static data in C++
862 When a class has static data members, it is not enough to @emph{declare}
863 the static member; you must also @emph{define} it.  For example:
864
865 @smallexample
866 class Foo
867 @{
868   @dots{}
869   void method();
870   static int bar;
871 @};
872 @end smallexample
873
874 This declaration only establishes that the class @code{Foo} has an
875 @code{int} named @code{Foo::bar}, and a member function named
876 @code{Foo::method}.  But you still need to define @emph{both}
877 @code{method} and @code{bar} elsewhere.  According to the ISO
878 standard, you must supply an initializer in one (and only one) source
879 file, such as:
880
881 @smallexample
882 int Foo::bar = 0;
883 @end smallexample
884
885 Other C++ compilers may not correctly implement the standard behavior.
886 As a result, when you switch to @command{g++} from one of these compilers,
887 you may discover that a program that appeared to work correctly in fact
888 does not conform to the standard: @command{g++} reports as undefined
889 symbols any static data members that lack definitions.
890
891
892 @node Name lookup
893 @subsection Name lookup, templates, and accessing members of base classes
894
895 @cindex base class members
896 @cindex two-stage name lookup
897 @cindex dependent name lookup
898
899 The C++ standard prescribes that all names that are not dependent on
900 template parameters are bound to their present definitions when parsing
901 a template function or class.@footnote{The C++ standard just uses the
902 term ``dependent'' for names that depend on the type or value of
903 template parameters.  This shorter term will also be used in the rest of
904 this section.}  Only names that are dependent are looked up at the point
905 of instantiation.  For example, consider
906
907 @smallexample
908   void foo(double);
909
910   struct A @{
911     template <typename T>
912     void f () @{
913       foo (1);        // 1
914       int i = N;      // 2
915       T t;
916       t.bar();        // 3
917       foo (t);        // 4
918     @}
919
920     static const int N;
921   @};
922 @end smallexample
923
924 Here, the names @code{foo} and @code{N} appear in a context that does
925 not depend on the type of @code{T}.  The compiler will thus require that
926 they are defined in the context of use in the template, not only before
927 the point of instantiation, and will here use @code{::foo(double)} and
928 @code{A::N}, respectively.  In particular, it will convert the integer
929 value to a @code{double} when passing it to @code{::foo(double)}.
930
931 Conversely, @code{bar} and the call to @code{foo} in the fourth marked
932 line are used in contexts that do depend on the type of @code{T}, so
933 they are only looked up at the point of instantiation, and you can
934 provide declarations for them after declaring the template, but before
935 instantiating it.  In particular, if you instantiate @code{A::f<int>},
936 the last line will call an overloaded @code{::foo(int)} if one was
937 provided, even if after the declaration of @code{struct A}.
938
939 This distinction between lookup of dependent and non-dependent names is
940 called two-stage (or dependent) name lookup.  G++ implements it
941 since version 3.4.
942
943 Two-stage name lookup sometimes leads to situations with behavior
944 different from non-template codes. The most common is probably this:
945
946 @smallexample
947   template <typename T> struct Base @{
948     int i;
949   @};
950
951   template <typename T> struct Derived : public Base<T> @{
952     int get_i() @{ return i; @}
953   @};
954 @end smallexample
955
956 In @code{get_i()}, @code{i} is not used in a dependent context, so the
957 compiler will look for a name declared at the enclosing namespace scope
958 (which is the global scope here).  It will not look into the base class,
959 since that is dependent and you may declare specializations of
960 @code{Base} even after declaring @code{Derived}, so the compiler can't
961 really know what @code{i} would refer to.  If there is no global
962 variable @code{i}, then you will get an error message.
963
964 In order to make it clear that you want the member of the base class,
965 you need to defer lookup until instantiation time, at which the base
966 class is known.  For this, you need to access @code{i} in a dependent
967 context, by either using @code{this->i} (remember that @code{this} is of
968 type @code{Derived<T>*}, so is obviously dependent), or using
969 @code{Base<T>::i}. Alternatively, @code{Base<T>::i} might be brought
970 into scope by a @code{using}-declaration.
971
972 Another, similar example involves calling member functions of a base
973 class:
974
975 @smallexample
976   template <typename T> struct Base @{
977       int f();
978   @};
979
980   template <typename T> struct Derived : Base<T> @{
981       int g() @{ return f(); @};
982   @};
983 @end smallexample
984
985 Again, the call to @code{f()} is not dependent on template arguments
986 (there are no arguments that depend on the type @code{T}, and it is also
987 not otherwise specified that the call should be in a dependent context).
988 Thus a global declaration of such a function must be available, since
989 the one in the base class is not visible until instantiation time.  The
990 compiler will consequently produce the following error message:
991
992 @smallexample
993   x.cc: In member function `int Derived<T>::g()':
994   x.cc:6: error: there are no arguments to `f' that depend on a template
995      parameter, so a declaration of `f' must be available
996   x.cc:6: error: (if you use `-fpermissive', G++ will accept your code, but
997      allowing the use of an undeclared name is deprecated)
998 @end smallexample
999
1000 To make the code valid either use @code{this->f()}, or
1001 @code{Base<T>::f()}.  Using the @code{-fpermissive} flag will also let
1002 the compiler accept the code, by marking all function calls for which no
1003 declaration is visible at the time of definition of the template for
1004 later lookup at instantiation time, as if it were a dependent call.
1005 We do not recommend using @code{-fpermissive} to work around invalid
1006 code, and it will also only catch cases where functions in base classes
1007 are called, not where variables in base classes are used (as in the
1008 example above).
1009
1010 Note that some compilers (including G++ versions prior to 3.4) get these
1011 examples wrong and accept above code without an error.  Those compilers
1012 do not implement two-stage name lookup correctly.
1013
1014
1015 @node Temporaries
1016 @subsection Temporaries May Vanish Before You Expect
1017
1018 @cindex temporaries, lifetime of
1019 @cindex portions of temporary objects, pointers to
1020 It is dangerous to use pointers or references to @emph{portions} of a
1021 temporary object.  The compiler may very well delete the object before
1022 you expect it to, leaving a pointer to garbage.  The most common place
1023 where this problem crops up is in classes like string classes,
1024 especially ones that define a conversion function to type @code{char *}
1025 or @code{const char *}---which is one reason why the standard
1026 @code{string} class requires you to call the @code{c_str} member
1027 function.  However, any class that returns a pointer to some internal
1028 structure is potentially subject to this problem.
1029
1030 For example, a program may use a function @code{strfunc} that returns
1031 @code{string} objects, and another function @code{charfunc} that
1032 operates on pointers to @code{char}:
1033
1034 @smallexample
1035 string strfunc ();
1036 void charfunc (const char *);
1037
1038 void
1039 f ()
1040 @{
1041   const char *p = strfunc().c_str();
1042   @dots{}
1043   charfunc (p);
1044   @dots{}
1045   charfunc (p);
1046 @}
1047 @end smallexample
1048
1049 @noindent
1050 In this situation, it may seem reasonable to save a pointer to the C
1051 string returned by the @code{c_str} member function and use that rather
1052 than call @code{c_str} repeatedly.  However, the temporary string
1053 created by the call to @code{strfunc} is destroyed after @code{p} is
1054 initialized, at which point @code{p} is left pointing to freed memory.
1055
1056 Code like this may run successfully under some other compilers,
1057 particularly obsolete cfront-based compilers that delete temporaries
1058 along with normal local variables.  However, the GNU C++ behavior is
1059 standard-conforming, so if your program depends on late destruction of
1060 temporaries it is not portable.
1061
1062 The safe way to write such code is to give the temporary a name, which
1063 forces it to remain until the end of the scope of the name.  For
1064 example:
1065
1066 @smallexample
1067 string& tmp = strfunc ();
1068 charfunc (tmp.c_str ());
1069 @end smallexample
1070
1071 @node Copy Assignment
1072 @subsection Implicit Copy-Assignment for Virtual Bases
1073
1074 When a base class is virtual, only one subobject of the base class
1075 belongs to each full object.  Also, the constructors and destructors are
1076 invoked only once, and called from the most-derived class.  However, such
1077 objects behave unspecified when being assigned.  For example:
1078
1079 @smallexample
1080 struct Base@{
1081   char *name;
1082   Base(char *n) : name(strdup(n))@{@}
1083   Base& operator= (const Base& other)@{
1084    free (name);
1085    name = strdup (other.name);
1086   @}
1087 @};
1088
1089 struct A:virtual Base@{
1090   int val;
1091   A():Base("A")@{@}
1092 @};
1093
1094 struct B:virtual Base@{
1095   int bval;
1096   B():Base("B")@{@}
1097 @};
1098
1099 struct Derived:public A, public B@{
1100   Derived():Base("Derived")@{@}
1101 @};
1102
1103 void func(Derived &d1, Derived &d2)
1104 @{
1105   d1 = d2;
1106 @}
1107 @end smallexample
1108
1109 The C++ standard specifies that @samp{Base::Base} is only called once
1110 when constructing or copy-constructing a Derived object.  It is
1111 unspecified whether @samp{Base::operator=} is called more than once when
1112 the implicit copy-assignment for Derived objects is invoked (as it is
1113 inside @samp{func} in the example).
1114
1115 G++ implements the ``intuitive'' algorithm for copy-assignment: assign all
1116 direct bases, then assign all members.  In that algorithm, the virtual
1117 base subobject can be encountered more than once.  In the example, copying
1118 proceeds in the following order: @samp{val}, @samp{name} (via
1119 @code{strdup}), @samp{bval}, and @samp{name} again.
1120
1121 If application code relies on copy-assignment, a user-defined
1122 copy-assignment operator removes any uncertainties.  With such an
1123 operator, the application can define whether and how the virtual base
1124 subobject is assigned.
1125
1126 @node Protoize Caveats
1127 @section Caveats of using @command{protoize}
1128
1129 The conversion programs @command{protoize} and @command{unprotoize} can
1130 sometimes change a source file in a way that won't work unless you
1131 rearrange it.
1132
1133 @itemize @bullet
1134 @item
1135 @command{protoize} can insert references to a type name or type tag before
1136 the definition, or in a file where they are not defined.
1137
1138 If this happens, compiler error messages should show you where the new
1139 references are, so fixing the file by hand is straightforward.
1140
1141 @item
1142 There are some C constructs which @command{protoize} cannot figure out.
1143 For example, it can't determine argument types for declaring a
1144 pointer-to-function variable; this you must do by hand.  @command{protoize}
1145 inserts a comment containing @samp{???} each time it finds such a
1146 variable; so you can find all such variables by searching for this
1147 string.  ISO C does not require declaring the argument types of
1148 pointer-to-function types.
1149
1150 @item
1151 Using @command{unprotoize} can easily introduce bugs.  If the program
1152 relied on prototypes to bring about conversion of arguments, these
1153 conversions will not take place in the program without prototypes.
1154 One case in which you can be sure @command{unprotoize} is safe is when
1155 you are removing prototypes that were made with @command{protoize}; if
1156 the program worked before without any prototypes, it will work again
1157 without them.
1158
1159 @opindex Wconversion
1160 You can find all the places where this problem might occur by compiling
1161 the program with the @option{-Wconversion} option.  It prints a warning
1162 whenever an argument is converted.
1163
1164 @item
1165 Both conversion programs can be confused if there are macro calls in and
1166 around the text to be converted.  In other words, the standard syntax
1167 for a declaration or definition must not result from expanding a macro.
1168 This problem is inherent in the design of C and cannot be fixed.  If
1169 only a few functions have confusing macro calls, you can easily convert
1170 them manually.
1171
1172 @item
1173 @command{protoize} cannot get the argument types for a function whose
1174 definition was not actually compiled due to preprocessing conditionals.
1175 When this happens, @command{protoize} changes nothing in regard to such
1176 a function.  @command{protoize} tries to detect such instances and warn
1177 about them.
1178
1179 You can generally work around this problem by using @command{protoize} step
1180 by step, each time specifying a different set of @option{-D} options for
1181 compilation, until all of the functions have been converted.  There is
1182 no automatic way to verify that you have got them all, however.
1183
1184 @item
1185 Confusion may result if there is an occasion to convert a function
1186 declaration or definition in a region of source code where there is more
1187 than one formal parameter list present.  Thus, attempts to convert code
1188 containing multiple (conditionally compiled) versions of a single
1189 function header (in the same vicinity) may not produce the desired (or
1190 expected) results.
1191
1192 If you plan on converting source files which contain such code, it is
1193 recommended that you first make sure that each conditionally compiled
1194 region of source code which contains an alternative function header also
1195 contains at least one additional follower token (past the final right
1196 parenthesis of the function header).  This should circumvent the
1197 problem.
1198
1199 @item
1200 @command{unprotoize} can become confused when trying to convert a function
1201 definition or declaration which contains a declaration for a
1202 pointer-to-function formal argument which has the same name as the
1203 function being defined or declared.  We recommend you avoid such choices
1204 of formal parameter names.
1205
1206 @item
1207 You might also want to correct some of the indentation by hand and break
1208 long lines.  (The conversion programs don't write lines longer than
1209 eighty characters in any case.)
1210 @end itemize
1211
1212 @node Non-bugs
1213 @section Certain Changes We Don't Want to Make
1214
1215 This section lists changes that people frequently request, but which
1216 we do not make because we think GCC is better without them.
1217
1218 @itemize @bullet
1219 @item
1220 Checking the number and type of arguments to a function which has an
1221 old-fashioned definition and no prototype.
1222
1223 Such a feature would work only occasionally---only for calls that appear
1224 in the same file as the called function, following the definition.  The
1225 only way to check all calls reliably is to add a prototype for the
1226 function.  But adding a prototype eliminates the motivation for this
1227 feature.  So the feature is not worthwhile.
1228
1229 @item
1230 Warning about using an expression whose type is signed as a shift count.
1231
1232 Shift count operands are probably signed more often than unsigned.
1233 Warning about this would cause far more annoyance than good.
1234
1235 @item
1236 Warning about assigning a signed value to an unsigned variable.
1237
1238 Such assignments must be very common; warning about them would cause
1239 more annoyance than good.
1240
1241 @item
1242 Warning when a non-void function value is ignored.
1243
1244 C contains many standard functions that return a value that most
1245 programs choose to ignore.  One obvious example is @code{printf}.
1246 Warning about this practice only leads the defensive programmer to
1247 clutter programs with dozens of casts to @code{void}.  Such casts are
1248 required so frequently that they become visual noise.  Writing those
1249 casts becomes so automatic that they no longer convey useful
1250 information about the intentions of the programmer.  For functions
1251 where the return value should never be ignored, use the
1252 @code{warn_unused_result} function attribute (@pxref{Function
1253 Attributes}).
1254
1255 @item
1256 @opindex fshort-enums
1257 Making @option{-fshort-enums} the default.
1258
1259 This would cause storage layout to be incompatible with most other C
1260 compilers.  And it doesn't seem very important, given that you can get
1261 the same result in other ways.  The case where it matters most is when
1262 the enumeration-valued object is inside a structure, and in that case
1263 you can specify a field width explicitly.
1264
1265 @item
1266 Making bit-fields unsigned by default on particular machines where ``the
1267 ABI standard'' says to do so.
1268
1269 The ISO C standard leaves it up to the implementation whether a bit-field
1270 declared plain @code{int} is signed or not.  This in effect creates two
1271 alternative dialects of C@.
1272
1273 @opindex fsigned-bitfields
1274 @opindex funsigned-bitfields
1275 The GNU C compiler supports both dialects; you can specify the signed
1276 dialect with @option{-fsigned-bitfields} and the unsigned dialect with
1277 @option{-funsigned-bitfields}.  However, this leaves open the question of
1278 which dialect to use by default.
1279
1280 Currently, the preferred dialect makes plain bit-fields signed, because
1281 this is simplest.  Since @code{int} is the same as @code{signed int} in
1282 every other context, it is cleanest for them to be the same in bit-fields
1283 as well.
1284
1285 Some computer manufacturers have published Application Binary Interface
1286 standards which specify that plain bit-fields should be unsigned.  It is
1287 a mistake, however, to say anything about this issue in an ABI@.  This is
1288 because the handling of plain bit-fields distinguishes two dialects of C@.
1289 Both dialects are meaningful on every type of machine.  Whether a
1290 particular object file was compiled using signed bit-fields or unsigned
1291 is of no concern to other object files, even if they access the same
1292 bit-fields in the same data structures.
1293
1294 A given program is written in one or the other of these two dialects.
1295 The program stands a chance to work on most any machine if it is
1296 compiled with the proper dialect.  It is unlikely to work at all if
1297 compiled with the wrong dialect.
1298
1299 Many users appreciate the GNU C compiler because it provides an
1300 environment that is uniform across machines.  These users would be
1301 inconvenienced if the compiler treated plain bit-fields differently on
1302 certain machines.
1303
1304 Occasionally users write programs intended only for a particular machine
1305 type.  On these occasions, the users would benefit if the GNU C compiler
1306 were to support by default the same dialect as the other compilers on
1307 that machine.  But such applications are rare.  And users writing a
1308 program to run on more than one type of machine cannot possibly benefit
1309 from this kind of compatibility.
1310
1311 This is why GCC does and will treat plain bit-fields in the same
1312 fashion on all types of machines (by default).
1313
1314 There are some arguments for making bit-fields unsigned by default on all
1315 machines.  If, for example, this becomes a universal de facto standard,
1316 it would make sense for GCC to go along with it.  This is something
1317 to be considered in the future.
1318
1319 (Of course, users strongly concerned about portability should indicate
1320 explicitly in each bit-field whether it is signed or not.  In this way,
1321 they write programs which have the same meaning in both C dialects.)
1322
1323 @item
1324 @opindex ansi
1325 @opindex std
1326 Undefining @code{__STDC__} when @option{-ansi} is not used.
1327
1328 Currently, GCC defines @code{__STDC__} unconditionally.  This provides
1329 good results in practice.
1330
1331 Programmers normally use conditionals on @code{__STDC__} to ask whether
1332 it is safe to use certain features of ISO C, such as function
1333 prototypes or ISO token concatenation.  Since plain @command{gcc} supports
1334 all the features of ISO C, the correct answer to these questions is
1335 ``yes''.
1336
1337 Some users try to use @code{__STDC__} to check for the availability of
1338 certain library facilities.  This is actually incorrect usage in an ISO
1339 C program, because the ISO C standard says that a conforming
1340 freestanding implementation should define @code{__STDC__} even though it
1341 does not have the library facilities.  @samp{gcc -ansi -pedantic} is a
1342 conforming freestanding implementation, and it is therefore required to
1343 define @code{__STDC__}, even though it does not come with an ISO C
1344 library.
1345
1346 Sometimes people say that defining @code{__STDC__} in a compiler that
1347 does not completely conform to the ISO C standard somehow violates the
1348 standard.  This is illogical.  The standard is a standard for compilers
1349 that claim to support ISO C, such as @samp{gcc -ansi}---not for other
1350 compilers such as plain @command{gcc}.  Whatever the ISO C standard says
1351 is relevant to the design of plain @command{gcc} without @option{-ansi} only
1352 for pragmatic reasons, not as a requirement.
1353
1354 GCC normally defines @code{__STDC__} to be 1, and in addition
1355 defines @code{__STRICT_ANSI__} if you specify the @option{-ansi} option,
1356 or a @option{-std} option for strict conformance to some version of ISO C@.
1357 On some hosts, system include files use a different convention, where
1358 @code{__STDC__} is normally 0, but is 1 if the user specifies strict
1359 conformance to the C Standard.  GCC follows the host convention when
1360 processing system include files, but when processing user files it follows
1361 the usual GNU C convention.
1362
1363 @item
1364 Undefining @code{__STDC__} in C++.
1365
1366 Programs written to compile with C++-to-C translators get the
1367 value of @code{__STDC__} that goes with the C compiler that is
1368 subsequently used.  These programs must test @code{__STDC__}
1369 to determine what kind of C preprocessor that compiler uses:
1370 whether they should concatenate tokens in the ISO C fashion
1371 or in the traditional fashion.
1372
1373 These programs work properly with GNU C++ if @code{__STDC__} is defined.
1374 They would not work otherwise.
1375
1376 In addition, many header files are written to provide prototypes in ISO
1377 C but not in traditional C@.  Many of these header files can work without
1378 change in C++ provided @code{__STDC__} is defined.  If @code{__STDC__}
1379 is not defined, they will all fail, and will all need to be changed to
1380 test explicitly for C++ as well.
1381
1382 @item
1383 Deleting ``empty'' loops.
1384
1385 Historically, GCC has not deleted ``empty'' loops under the
1386 assumption that the most likely reason you would put one in a program is
1387 to have a delay, so deleting them will not make real programs run any
1388 faster.
1389
1390 However, the rationale here is that optimization of a nonempty loop
1391 cannot produce an empty one, which holds for C but is not always the
1392 case for C++.
1393
1394 @opindex funroll-loops
1395 Moreover, with @option{-funroll-loops} small ``empty'' loops are already
1396 removed, so the current behavior is both sub-optimal and inconsistent
1397 and will change in the future.
1398
1399 @item
1400 Making side effects happen in the same order as in some other compiler.
1401
1402 @cindex side effects, order of evaluation
1403 @cindex order of evaluation, side effects
1404 It is never safe to depend on the order of evaluation of side effects.
1405 For example, a function call like this may very well behave differently
1406 from one compiler to another:
1407
1408 @smallexample
1409 void func (int, int);
1410
1411 int i = 2;
1412 func (i++, i++);
1413 @end smallexample
1414
1415 There is no guarantee (in either the C or the C++ standard language
1416 definitions) that the increments will be evaluated in any particular
1417 order.  Either increment might happen first.  @code{func} might get the
1418 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
1419
1420 @item
1421 Making certain warnings into errors by default.
1422
1423 Some ISO C testsuites report failure when the compiler does not produce
1424 an error message for a certain program.
1425
1426 @opindex pedantic-errors
1427 ISO C requires a ``diagnostic'' message for certain kinds of invalid
1428 programs, but a warning is defined by GCC to count as a diagnostic.  If
1429 GCC produces a warning but not an error, that is correct ISO C support.
1430 If testsuites call this ``failure'', they should be run with the GCC
1431 option @option{-pedantic-errors}, which will turn these warnings into
1432 errors.
1433
1434 @end itemize
1435
1436 @node Warnings and Errors
1437 @section Warning Messages and Error Messages
1438
1439 @cindex error messages
1440 @cindex warnings vs errors
1441 @cindex messages, warning and error
1442 The GNU compiler can produce two kinds of diagnostics: errors and
1443 warnings.  Each kind has a different purpose:
1444
1445 @itemize @w{}
1446 @item
1447 @dfn{Errors} report problems that make it impossible to compile your
1448 program.  GCC reports errors with the source file name and line
1449 number where the problem is apparent.
1450
1451 @item
1452 @dfn{Warnings} report other unusual conditions in your code that
1453 @emph{may} indicate a problem, although compilation can (and does)
1454 proceed.  Warning messages also report the source file name and line
1455 number, but include the text @samp{warning:} to distinguish them
1456 from error messages.
1457 @end itemize
1458
1459 Warnings may indicate danger points where you should check to make sure
1460 that your program really does what you intend; or the use of obsolete
1461 features; or the use of nonstandard features of GNU C or C++.  Many
1462 warnings are issued only if you ask for them, with one of the @option{-W}
1463 options (for instance, @option{-Wall} requests a variety of useful
1464 warnings).
1465
1466 @opindex pedantic
1467 @opindex pedantic-errors
1468 GCC always tries to compile your program if possible; it never
1469 gratuitously rejects a program whose meaning is clear merely because
1470 (for instance) it fails to conform to a standard.  In some cases,
1471 however, the C and C++ standards specify that certain extensions are
1472 forbidden, and a diagnostic @emph{must} be issued by a conforming
1473 compiler.  The @option{-pedantic} option tells GCC to issue warnings in
1474 such cases; @option{-pedantic-errors} says to make them errors instead.
1475 This does not mean that @emph{all} non-ISO constructs get warnings
1476 or errors.
1477
1478 @xref{Warning Options,,Options to Request or Suppress Warnings}, for
1479 more detail on these and related command-line options.