1 This is Info file gcc.info, produced by Makeinfo version 1.68 from the
4 This file documents the use and the internals of the GNU compiler.
6 Published by the Free Software Foundation 59 Temple Place - Suite 330
7 Boston, MA 02111-1307 USA
9 Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998
10 Free Software Foundation, Inc.
12 Permission is granted to make and distribute verbatim copies of this
13 manual provided the copyright notice and this permission notice are
14 preserved on all copies.
16 Permission is granted to copy and distribute modified versions of
17 this manual under the conditions for verbatim copying, provided also
18 that the sections entitled "GNU General Public License," "Funding for
19 Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
20 included exactly as in the original, and provided that the entire
21 resulting derived work is distributed under the terms of a permission
22 notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that the sections entitled "GNU General Public
27 License," "Funding for Free Software," and "Protect Your Freedom--Fight
28 `Look And Feel'", and this permission notice, may be included in
29 translations approved by the Free Software Foundation instead of in the
33 File: gcc.info, Node: Cross Runtime, Next: Build Cross, Prev: Cross Headers, Up: Cross-Compiler
35 `libgcc.a' and Cross-Compilers
36 ------------------------------
38 Code compiled by GNU CC uses certain runtime support functions
39 implicitly. Some of these functions can be compiled successfully with
40 GNU CC itself, but a few cannot be. These problem functions are in the
41 source file `libgcc1.c'; the library made from them is called
44 When you build a native compiler, these functions are compiled with
45 some other compiler-the one that you use for bootstrapping GNU CC.
46 Presumably it knows how to open code these operations, or else knows how
47 to call the run-time emulation facilities that the machine comes with.
48 But this approach doesn't work for building a cross-compiler. The
49 compiler that you use for building knows about the host system, not the
52 So, when you build a cross-compiler you have to supply a suitable
53 library `libgcc1.a' that does the job it is expected to do.
55 To compile `libgcc1.c' with the cross-compiler itself does not work.
56 The functions in this file are supposed to implement arithmetic
57 operations that GNU CC does not know how to open code for your target
58 machine. If these functions are compiled with GNU CC itself, they will
59 compile into infinite recursion.
61 On any given target, most of these functions are not needed. If GNU
62 CC can open code an arithmetic operation, it will not call these
63 functions to perform the operation. It is possible that on your target
64 machine, none of these functions is needed. If so, you can supply an
65 empty library as `libgcc1.a'.
67 Many targets need library support only for multiplication and
68 division. If you are linking with a library that contains functions for
69 multiplication and division, you can tell GNU CC to call them directly
70 by defining the macros `MULSI3_LIBCALL', and the like. These macros
71 need to be defined in the target description macro file. For some
72 targets, they are defined already. This may be sufficient to avoid the
73 need for libgcc1.a; if so, you can supply an empty library.
75 Some targets do not have floating point instructions; they need other
76 functions in `libgcc1.a', which do floating arithmetic. Recent
77 versions of GNU CC have a file which emulates floating point. With a
78 certain amount of work, you should be able to construct a floating
79 point emulator that can be used as `libgcc1.a'. Perhaps future
80 versions will contain code to do this automatically and conveniently.
81 That depends on whether someone wants to implement it.
83 Some embedded targets come with all the necessary `libgcc1.a'
84 routines written in C or assembler. These targets build `libgcc1.a'
85 automatically and you do not need to do anything special for them.
86 Other embedded targets do not need any `libgcc1.a' routines since all
87 the necessary operations are supported by the hardware.
89 If your target system has another C compiler, you can configure GNU
90 CC as a native compiler on that machine, build just `libgcc1.a' with
91 `make libgcc1.a' on that machine, and use the resulting file with the
92 cross-compiler. To do this, execute the following on the target
96 ./configure --host=sparc --target=sun3
99 And then this on the host machine:
107 Another way to provide the functions you need in `libgcc1.a' is to
108 define the appropriate `perform_...' macros for those functions. If
109 these definitions do not use the C arithmetic operators that they are
110 meant to implement, you should be able to compile them with the
111 cross-compiler you are building. (If these definitions already exist
112 for your target file, then you are all set.)
114 To build `libgcc1.a' using the perform macros, use
115 `LIBGCC1=libgcc1.a OLDCC=./xgcc' when building the compiler.
116 Otherwise, you should place your replacement library under the name
117 `libgcc1.a' in the directory in which you will build the
118 cross-compiler, before you run `make'.
121 File: gcc.info, Node: Cross Headers, Next: Cross Runtime, Prev: Tools and Libraries, Up: Cross-Compiler
123 Cross-Compilers and Header Files
124 --------------------------------
126 If you are cross-compiling a standalone program or a program for an
127 embedded system, then you may not need any header files except the few
128 that are part of GNU CC (and those of your program). However, if you
129 intend to link your program with a standard C library such as `libc.a',
130 then you probably need to compile with the header files that go with
133 The GNU C compiler does not come with these files, because (1) they
134 are system-specific, and (2) they belong in a C library, not in a
137 If the GNU C library supports your target machine, then you can get
138 the header files from there (assuming you actually use the GNU library
139 when you link your program).
141 If your target machine comes with a C compiler, it probably comes
142 with suitable header files also. If you make these files accessible
143 from the host machine, the cross-compiler can use them also.
145 Otherwise, you're on your own in finding header files to use when
148 When you have found suitable header files, put them in the directory
149 `/usr/local/TARGET/include', before building the cross compiler. Then
150 installation will run fixincludes properly and install the corrected
151 versions of the header files where the compiler will use them.
153 Provide the header files before you build the cross-compiler, because
154 the build stage actually runs the cross-compiler to produce parts of
155 `libgcc.a'. (These are the parts that *can* be compiled with GNU CC.)
156 Some of them need suitable header files.
158 Here's an example showing how to copy the header files from a target
159 machine. On the target machine, do this:
161 (cd /usr/include; tar cf - .) > tarfile
163 Then, on the host machine, do this:
166 lcd /usr/local/TARGET/include
172 File: gcc.info, Node: Build Cross, Prev: Cross Runtime, Up: Cross-Compiler
174 Actually Building the Cross-Compiler
175 ------------------------------------
177 Now you can proceed just as for compiling a single-machine compiler
178 through the step of building stage 1. If you have not provided some
179 sort of `libgcc1.a', then compilation will give up at the point where
180 it needs that file, printing a suitable error message. If you do
181 provide `libgcc1.a', then building the compiler will automatically
182 compile and link a test program called `libgcc1-test'; if you get
183 errors in the linking, it means that not all of the necessary routines
184 in `libgcc1.a' are available.
186 You must provide the header file `float.h'. One way to do this is
187 to compile `enquire' and run it on your target machine. The job of
188 `enquire' is to run on the target machine and figure out by experiment
189 the nature of its floating point representation. `enquire' records its
190 findings in the header file `float.h'. If you can't produce this file
191 by running `enquire' on the target machine, then you will need to come
192 up with a suitable `float.h' in some other way (or else, avoid using it
195 Do not try to build stage 2 for a cross-compiler. It doesn't work to
196 rebuild GNU CC as a cross-compiler using the cross-compiler, because
197 that would produce a program that runs on the target machine, not on the
198 host. For example, if you compile a 386-to-68030 cross-compiler with
199 itself, the result will not be right either for the 386 (because it was
200 compiled into 68030 code) or for the 68030 (because it was configured
201 for a 386 as the host). If you want to compile GNU CC into 68030 code,
202 whether you compile it on a 68030 or with a cross-compiler on a 386, you
203 must specify a 68030 as the host when you configure it.
205 To install the cross-compiler, use `make install', as usual.
208 File: gcc.info, Node: Sun Install, Next: VMS Install, Prev: Cross-Compiler, Up: Installation
210 Installing GNU CC on the Sun
211 ============================
213 On Solaris (version 2.1), do not use the linker or other tools in
214 `/usr/ucb' to build GNU CC. Use `/usr/ccs/bin'.
216 Make sure the environment variable `FLOAT_OPTION' is not set when
217 you compile `libgcc.a'. If this option were set to `f68881' when
218 `libgcc.a' is compiled, the resulting code would demand to be linked
219 with a special startup file and would not link properly without special
222 There is a bug in `alloca' in certain versions of the Sun library.
223 To avoid this bug, install the binaries of GNU CC that were compiled by
224 GNU CC. They use `alloca' as a built-in function and never the one in
227 Some versions of the Sun compiler crash when compiling GNU CC. The
228 problem is a segmentation fault in cpp. This problem seems to be due to
229 the bulk of data in the environment variables. You may be able to avoid
230 it by using the following command to compile GNU CC with Sun CC:
232 make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc"
234 SunOS 4.1.3 and 4.1.3_U1 have bugs that can cause intermittent core
235 dumps when compiling GNU CC. A common symptom is an internal compiler
236 error which does not recur if you run it again. To fix the problem,
237 install Sun recommended patch 100726 (for SunOS 4.1.3) or 101508 (for
238 SunOS 4.1.3_U1), or upgrade to a later SunOS release.
241 File: gcc.info, Node: VMS Install, Next: Collect2, Prev: Sun Install, Up: Installation
243 Installing GNU CC on VMS
244 ========================
246 The VMS version of GNU CC is distributed in a backup saveset
247 containing both source code and precompiled binaries.
249 To install the `gcc' command so you can use the compiler easily, in
250 the same manner as you use the VMS C compiler, you must install the VMS
251 CLD file for GNU CC as follows:
253 1. Define the VMS logical names `GNU_CC' and `GNU_CC_INCLUDE' to
254 point to the directories where the GNU CC executables
255 (`gcc-cpp.exe', `gcc-cc1.exe', etc.) and the C include files are
256 kept respectively. This should be done with the commands:
258 $ assign /system /translation=concealed -
260 $ assign /system /translation=concealed -
261 disk:[gcc.include.] gnu_cc_include
263 with the appropriate disk and directory names. These commands can
264 be placed in your system startup file so they will be executed
265 whenever the machine is rebooted. You may, if you choose, do this
266 via the `GCC_INSTALL.COM' script in the `[GCC]' directory.
268 2. Install the `GCC' command with the command line:
270 $ set command /table=sys$common:[syslib]dcltables -
271 /output=sys$common:[syslib]dcltables gnu_cc:[000000]gcc
272 $ install replace sys$common:[syslib]dcltables
274 3. To install the help file, do the following:
276 $ library/help sys$library:helplib.hlb gcc.hlp
278 Now you can invoke the compiler with a command like `gcc /verbose
279 file.c', which is equivalent to the command `gcc -v -c file.c' in
282 If you wish to use GNU C++ you must first install GNU CC, and then
283 perform the following steps:
285 1. Define the VMS logical name `GNU_GXX_INCLUDE' to point to the
286 directory where the preprocessor will search for the C++ header
287 files. This can be done with the command:
289 $ assign /system /translation=concealed -
290 disk:[gcc.gxx_include.] gnu_gxx_include
292 with the appropriate disk and directory name. If you are going to
293 be using a C++ runtime library, this is where its install
294 procedure will install its header files.
296 2. Obtain the file `gcc-cc1plus.exe', and place this in the same
297 directory that `gcc-cc1.exe' is kept.
299 The GNU C++ compiler can be invoked with a command like `gcc /plus
300 /verbose file.cc', which is equivalent to the command `g++ -v -c
303 We try to put corresponding binaries and sources on the VMS
304 distribution tape. But sometimes the binaries will be from an older
305 version than the sources, because we don't always have time to update
306 them. (Use the `/version' option to determine the version number of
307 the binaries and compare it with the source file `version.c' to tell
308 whether this is so.) In this case, you should use the binaries you get
309 to recompile the sources. If you must recompile, here is how:
311 1. Execute the command procedure `vmsconfig.com' to set up the files
312 `tm.h', `config.h', `aux-output.c', and `md.', and to create files
313 `tconfig.h' and `hconfig.h'. This procedure also creates several
314 linker option files used by `make-cc1.com' and a data file used by
319 2. Setup the logical names and command tables as defined above. In
320 addition, define the VMS logical name `GNU_BISON' to point at the
321 to the directories where the Bison executable is kept. This
322 should be done with the command:
324 $ assign /system /translation=concealed -
325 disk:[bison.] gnu_bison
327 You may, if you choose, use the `INSTALL_BISON.COM' script in the
330 3. Install the `BISON' command with the command line:
332 $ set command /table=sys$common:[syslib]dcltables -
333 /output=sys$common:[syslib]dcltables -
334 gnu_bison:[000000]bison
335 $ install replace sys$common:[syslib]dcltables
337 4. Type `@make-gcc' to recompile everything (alternatively, submit
338 the file `make-gcc.com' to a batch queue). If you wish to build
339 the GNU C++ compiler as well as the GNU CC compiler, you must
340 first edit `make-gcc.com' and follow the instructions that appear
343 5. In order to use GCC, you need a library of functions which GCC
344 compiled code will call to perform certain tasks, and these
345 functions are defined in the file `libgcc2.c'. To compile this
346 you should use the command procedure `make-l2.com', which will
347 generate the library `libgcc2.olb'. `libgcc2.olb' should be built
348 using the compiler built from the same distribution that
349 `libgcc2.c' came from, and `make-gcc.com' will automatically do
352 To install the library, use the following commands:
354 $ library gnu_cc:[000000]gcclib/delete=(new,eprintf)
355 $ library gnu_cc:[000000]gcclib/delete=L_*
356 $ library libgcc2/extract=*/output=libgcc2.obj
357 $ library gnu_cc:[000000]gcclib libgcc2.obj
359 The first command simply removes old modules that will be replaced
360 with modules from `libgcc2' under different module names. The
361 modules `new' and `eprintf' may not actually be present in your
362 `gcclib.olb'--if the VMS librarian complains about those modules
363 not being present, simply ignore the message and continue on with
364 the next command. The second command removes the modules that
365 came from the previous version of the library `libgcc2.c'.
367 Whenever you update the compiler on your system, you should also
368 update the library with the above procedure.
370 6. You may wish to build GCC in such a way that no files are written
371 to the directory where the source files reside. An example would
372 be the when the source files are on a read-only disk. In these
373 cases, execute the following DCL commands (substituting your
376 $ assign dua0:[gcc.build_dir.]/translation=concealed, -
377 dua1:[gcc.source_dir.]/translation=concealed gcc_build
378 $ set default gcc_build:[000000]
380 where the directory `dua1:[gcc.source_dir]' contains the source
381 code, and the directory `dua0:[gcc.build_dir]' is meant to contain
382 all of the generated object files and executables. Once you have
383 done this, you can proceed building GCC as described above. (Keep
384 in mind that `gcc_build' is a rooted logical name, and thus the
385 device names in each element of the search list must be an actual
386 physical device name rather than another rooted logical name).
388 7. *If you are building GNU CC with a previous version of GNU CC, you
389 also should check to see that you have the newest version of the
390 assembler*. In particular, GNU CC version 2 treats global constant
391 variables slightly differently from GNU CC version 1, and GAS
392 version 1.38.1 does not have the patches required to work with GCC
393 version 2. If you use GAS 1.38.1, then `extern const' variables
394 will not have the read-only bit set, and the linker will generate
395 warning messages about mismatched psect attributes for these
396 variables. These warning messages are merely a nuisance, and can
399 If you are compiling with a version of GNU CC older than 1.33,
400 specify `/DEFINE=("inline=")' as an option in all the
401 compilations. This requires editing all the `gcc' commands in
402 `make-cc1.com'. (The older versions had problems supporting
403 `inline'.) Once you have a working 1.33 or newer GNU CC, you can
404 change this file back.
406 8. If you want to build GNU CC with the VAX C compiler, you will need
407 to make minor changes in `make-cccp.com' and `make-cc1.com' to
408 choose alternate definitions of `CC', `CFLAGS', and `LIBS'. See
409 comments in those files. However, you must also have a working
410 version of the GNU assembler (GNU as, aka GAS) as it is used as
411 the back-end for GNU CC to produce binary object modules and is
412 not included in the GNU CC sources. GAS is also needed to compile
413 `libgcc2' in order to build `gcclib' (see above); `make-l2.com'
414 expects to be able to find it operational in
415 `gnu_cc:[000000]gnu-as.exe'.
417 To use GNU CC on VMS, you need the VMS driver programs `gcc.exe',
418 `gcc.com', and `gcc.cld'. They are distributed with the VMS
419 binaries (`gcc-vms') rather than the GNU CC sources. GAS is also
420 included in `gcc-vms', as is Bison.
422 Once you have successfully built GNU CC with VAX C, you should use
423 the resulting compiler to rebuild itself. Before doing this, be
424 sure to restore the `CC', `CFLAGS', and `LIBS' definitions in
425 `make-cccp.com' and `make-cc1.com'. The second generation
426 compiler will be able to take advantage of many optimizations that
427 must be suppressed when building with other compilers.
429 Under previous versions of GNU CC, the generated code would
430 occasionally give strange results when linked with the sharable
431 `VAXCRTL' library. Now this should work.
433 Even with this version, however, GNU CC itself should not be linked
434 with the sharable `VAXCRTL'. The version of `qsort' in `VAXCRTL' has a
435 bug (known to be present in VMS versions V4.6 through V5.5) which
436 causes the compiler to fail.
438 The executables are generated by `make-cc1.com' and `make-cccp.com'
439 use the object library version of `VAXCRTL' in order to make use of the
440 `qsort' routine in `gcclib.olb'. If you wish to link the compiler
441 executables with the shareable image version of `VAXCRTL', you should
442 edit the file `tm.h' (created by `vmsconfig.com') to define the macro
445 `QSORT_WORKAROUND' is always defined when GNU CC is compiled with
446 VAX C, to avoid a problem in case `gcclib.olb' is not yet available.
449 File: gcc.info, Node: Collect2, Next: Header Dirs, Prev: VMS Install, Up: Installation
454 Many target systems do not have support in the assembler and linker
455 for "constructors"--initialization functions to be called before the
456 official "start" of `main'. On such systems, GNU CC uses a utility
457 called `collect2' to arrange to call these functions at start time.
459 The program `collect2' works by linking the program once and looking
460 through the linker output file for symbols with particular names
461 indicating they are constructor functions. If it finds any, it creates
462 a new temporary `.c' file containing a table of them, compiles it, and
463 links the program a second time including that file.
465 The actual calls to the constructors are carried out by a subroutine
466 called `__main', which is called (automatically) at the beginning of
467 the body of `main' (provided `main' was compiled with GNU CC). Calling
468 `__main' is necessary, even when compiling C code, to allow linking C
469 and C++ object code together. (If you use `-nostdlib', you get an
470 unresolved reference to `__main', since it's defined in the standard
471 GCC library. Include `-lgcc' at the end of your compiler command line
472 to resolve this reference.)
474 The program `collect2' is installed as `ld' in the directory where
475 the passes of the compiler are installed. When `collect2' needs to
476 find the *real* `ld', it tries the following file names:
478 * `real-ld' in the directories listed in the compiler's search
481 * `real-ld' in the directories listed in the environment variable
484 * The file specified in the `REAL_LD_FILE_NAME' configuration macro,
487 * `ld' in the compiler's search directories, except that `collect2'
488 will not execute itself recursively.
492 "The compiler's search directories" means all the directories where
493 `gcc' searches for passes of the compiler. This includes directories
494 that you specify with `-B'.
496 Cross-compilers search a little differently:
498 * `real-ld' in the compiler's search directories.
500 * `TARGET-real-ld' in `PATH'.
502 * The file specified in the `REAL_LD_FILE_NAME' configuration macro,
505 * `ld' in the compiler's search directories.
507 * `TARGET-ld' in `PATH'.
509 `collect2' explicitly avoids running `ld' using the file name under
510 which `collect2' itself was invoked. In fact, it remembers up a list
511 of such names--in case one copy of `collect2' finds another copy (or
512 version) of `collect2' installed as `ld' in a second place in the
515 `collect2' searches for the utilities `nm' and `strip' using the
516 same algorithm as above for `ld'.
519 File: gcc.info, Node: Header Dirs, Prev: Collect2, Up: Installation
521 Standard Header File Directories
522 ================================
524 `GCC_INCLUDE_DIR' means the same thing for native and cross. It is
525 where GNU CC stores its private include files, and also where GNU CC
526 stores the fixed include files. A cross compiled GNU CC runs
527 `fixincludes' on the header files in `$(tooldir)/include'. (If the
528 cross compilation header files need to be fixed, they must be installed
529 before GNU CC is built. If the cross compilation header files are
530 already suitable for ANSI C and GNU CC, nothing special need be done).
532 `GPLUS_INCLUDE_DIR' means the same thing for native and cross. It
533 is where `g++' looks first for header files. The C++ library installs
534 only target independent header files in that directory.
536 `LOCAL_INCLUDE_DIR' is used only for a native compiler. It is
537 normally `/usr/local/include'. GNU CC searches this directory so that
538 users can install header files in `/usr/local/include'.
540 `CROSS_INCLUDE_DIR' is used only for a cross compiler. GNU CC
541 doesn't install anything there.
543 `TOOL_INCLUDE_DIR' is used for both native and cross compilers. It
544 is the place for other packages to install header files that GNU CC will
545 use. For a cross-compiler, this is the equivalent of `/usr/include'.
546 When you build a cross-compiler, `fixincludes' processes any header
547 files in this directory.
550 File: gcc.info, Node: C Extensions, Next: C++ Extensions, Prev: Installation, Up: Top
552 Extensions to the C Language Family
553 ***********************************
555 GNU C provides several language features not found in ANSI standard
556 C. (The `-pedantic' option directs GNU CC to print a warning message if
557 any of these features is used.) To test for the availability of these
558 features in conditional compilation, check for a predefined macro
559 `__GNUC__', which is always defined under GNU CC.
561 These extensions are available in C and Objective C. Most of them
562 are also available in C++. *Note Extensions to the C++ Language: C++
563 Extensions, for extensions that apply *only* to C++.
567 * Statement Exprs:: Putting statements and declarations inside expressions.
568 * Local Labels:: Labels local to a statement-expression.
569 * Labels as Values:: Getting pointers to labels, and computed gotos.
570 * Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
571 * Constructing Calls:: Dispatching a call to another function.
572 * Naming Types:: Giving a name to the type of some expression.
573 * Typeof:: `typeof': referring to the type of an expression.
574 * Lvalues:: Using `?:', `,' and casts in lvalues.
575 * Conditionals:: Omitting the middle operand of a `?:' expression.
576 * Long Long:: Double-word integers--`long long int'.
577 * Complex:: Data types for complex numbers.
578 * Zero Length:: Zero-length arrays.
579 * Variable Length:: Arrays whose length is computed at run time.
580 * Macro Varargs:: Macros with variable number of arguments.
581 * Subscripting:: Any array can be subscripted, even if not an lvalue.
582 * Pointer Arith:: Arithmetic on `void'-pointers and function pointers.
583 * Initializers:: Non-constant initializers.
584 * Constructors:: Constructor expressions give structures, unions
586 * Labeled Elements:: Labeling elements of initializers.
587 * Cast to Union:: Casting to union type from any member of the union.
588 * Case Ranges:: `case 1 ... 9' and such.
589 * Function Attributes:: Declaring that functions have no side effects,
590 or that they can never return.
591 * Function Prototypes:: Prototype declarations and old-style definitions.
592 * C++ Comments:: C++ comments are recognized.
593 * Dollar Signs:: Dollar sign is allowed in identifiers.
594 * Character Escapes:: `\e' stands for the character <ESC>.
595 * Variable Attributes:: Specifying attributes of variables.
596 * Type Attributes:: Specifying attributes of types.
597 * Alignment:: Inquiring about the alignment of a type or variable.
598 * Inline:: Defining inline functions (as fast as macros).
599 * Extended Asm:: Assembler instructions with C expressions as operands.
600 (With them you can define "built-in" functions.)
601 * Asm Labels:: Specifying the assembler name to use for a C symbol.
602 * Explicit Reg Vars:: Defining variables residing in specified registers.
603 * Alternate Keywords:: `__const__', `__asm__', etc., for header files.
604 * Incomplete Enums:: `enum foo;', with details to follow.
605 * Function Names:: Printable strings which are the name of the current
607 * Return Address:: Getting the return or frame address of a function.
610 File: gcc.info, Node: Statement Exprs, Next: Local Labels, Up: C Extensions
612 Statements and Declarations in Expressions
613 ==========================================
615 A compound statement enclosed in parentheses may appear as an
616 expression in GNU C. This allows you to use loops, switches, and local
617 variables within an expression.
619 Recall that a compound statement is a sequence of statements
620 surrounded by braces; in this construct, parentheses go around the
623 ({ int y = foo (); int z;
628 is a valid (though slightly more complex than necessary) expression for
629 the absolute value of `foo ()'.
631 The last thing in the compound statement should be an expression
632 followed by a semicolon; the value of this subexpression serves as the
633 value of the entire construct. (If you use some other kind of statement
634 last within the braces, the construct has type `void', and thus
635 effectively no value.)
637 This feature is especially useful in making macro definitions "safe"
638 (so that they evaluate each operand exactly once). For example, the
639 "maximum" function is commonly defined as a macro in standard C as
642 #define max(a,b) ((a) > (b) ? (a) : (b))
644 But this definition computes either A or B twice, with bad results if
645 the operand has side effects. In GNU C, if you know the type of the
646 operands (here let's assume `int'), you can define the macro safely as
649 #define maxint(a,b) \
650 ({int _a = (a), _b = (b); _a > _b ? _a : _b; })
652 Embedded statements are not allowed in constant expressions, such as
653 the value of an enumeration constant, the width of a bit field, or the
654 initial value of a static variable.
656 If you don't know the type of the operand, you can still do this,
657 but you must use `typeof' (*note Typeof::.) or type naming (*note
661 File: gcc.info, Node: Local Labels, Next: Labels as Values, Prev: Statement Exprs, Up: C Extensions
663 Locally Declared Labels
664 =======================
666 Each statement expression is a scope in which "local labels" can be
667 declared. A local label is simply an identifier; you can jump to it
668 with an ordinary `goto' statement, but only from within the statement
669 expression it belongs to.
671 A local label declaration looks like this:
677 __label__ LABEL1, LABEL2, ...;
679 Local label declarations must come at the beginning of the statement
680 expression, right after the `({', before any ordinary declarations.
682 The label declaration defines the label *name*, but does not define
683 the label itself. You must do this in the usual way, with `LABEL:',
684 within the statements of the statement expression.
686 The local label feature is useful because statement expressions are
687 often used in macros. If the macro contains nested loops, a `goto' can
688 be useful for breaking out of them. However, an ordinary label whose
689 scope is the whole function cannot be used: if the macro can be
690 expanded several times in one function, the label will be multiply
691 defined in that function. A local label avoids this problem. For
694 #define SEARCH(array, target) \
697 typeof (target) _SEARCH_target = (target); \
698 typeof (*(array)) *_SEARCH_array = (array); \
701 for (i = 0; i < max; i++) \
702 for (j = 0; j < max; j++) \
703 if (_SEARCH_array[i][j] == _SEARCH_target) \
704 { value = i; goto found; } \
711 File: gcc.info, Node: Labels as Values, Next: Nested Functions, Prev: Local Labels, Up: C Extensions
716 You can get the address of a label defined in the current function
717 (or a containing function) with the unary operator `&&'. The value has
718 type `void *'. This value is a constant and can be used wherever a
719 constant of that type is valid. For example:
725 To use these values, you need to be able to jump to one. This is
726 done with the computed goto statement(1), `goto *EXP;'. For example,
730 Any expression of type `void *' is allowed.
732 One way of using these constants is in initializing a static array
733 that will serve as a jump table:
735 static void *array[] = { &&foo, &&bar, &&hack };
737 Then you can select a label with indexing, like this:
741 Note that this does not check whether the subscript is in bounds--array
742 indexing in C never does that.
744 Such an array of label values serves a purpose much like that of the
745 `switch' statement. The `switch' statement is cleaner, so use that
746 rather than an array unless the problem does not fit a `switch'
749 Another use of label values is in an interpreter for threaded code.
750 The labels within the interpreter function can be stored in the
751 threaded code for super-fast dispatching.
753 You can use this mechanism to jump to code in a different function.
754 If you do that, totally unpredictable things will happen. The best way
755 to avoid this is to store the label address only in automatic variables
756 and never pass it as an argument.
758 ---------- Footnotes ----------
760 (1) The analogous feature in Fortran is called an assigned goto, but
761 that name seems inappropriate in C, where one can do more than simply
762 store label addresses in label variables.
765 File: gcc.info, Node: Nested Functions, Next: Constructing Calls, Prev: Labels as Values, Up: C Extensions
770 A "nested function" is a function defined inside another function.
771 (Nested functions are not supported for GNU C++.) The nested function's
772 name is local to the block where it is defined. For example, here we
773 define a nested function named `square', and call it twice:
775 foo (double a, double b)
777 double square (double z) { return z * z; }
779 return square (a) + square (b);
782 The nested function can access all the variables of the containing
783 function that are visible at the point of its definition. This is
784 called "lexical scoping". For example, here we show a nested function
785 which uses an inherited variable named `offset':
787 bar (int *array, int offset, int size)
789 int access (int *array, int index)
790 { return array[index + offset]; }
793 for (i = 0; i < size; i++)
794 ... access (array, i) ...
797 Nested function definitions are permitted within functions in the
798 places where variable definitions are allowed; that is, in any block,
799 before the first statement in the block.
801 It is possible to call the nested function from outside the scope of
802 its name by storing its address or passing the address to another
805 hack (int *array, int size)
807 void store (int index, int value)
808 { array[index] = value; }
810 intermediate (store, size);
813 Here, the function `intermediate' receives the address of `store' as
814 an argument. If `intermediate' calls `store', the arguments given to
815 `store' are used to store into `array'. But this technique works only
816 so long as the containing function (`hack', in this example) does not
819 If you try to call the nested function through its address after the
820 containing function has exited, all hell will break loose. If you try
821 to call it after a containing scope level has exited, and if it refers
822 to some of the variables that are no longer in scope, you may be lucky,
823 but it's not wise to take the risk. If, however, the nested function
824 does not refer to anything that has gone out of scope, you should be
827 GNU CC implements taking the address of a nested function using a
828 technique called "trampolines".
830 A nested function can jump to a label inherited from a containing
831 function, provided the label was explicitly declared in the containing
832 function (*note Local Labels::.). Such a jump returns instantly to the
833 containing function, exiting the nested function which did the `goto'
834 and any intermediate functions as well. Here is an example:
836 bar (int *array, int offset, int size)
839 int access (int *array, int index)
843 return array[index + offset];
847 for (i = 0; i < size; i++)
848 ... access (array, i) ...
852 /* Control comes here from `access'
853 if it detects an error. */
858 A nested function always has internal linkage. Declaring one with
859 `extern' is erroneous. If you need to declare the nested function
860 before its definition, use `auto' (which is otherwise meaningless for
861 function declarations).
863 bar (int *array, int offset, int size)
866 auto int access (int *, int);
868 int access (int *array, int index)
872 return array[index + offset];
878 File: gcc.info, Node: Constructing Calls, Next: Naming Types, Prev: Nested Functions, Up: C Extensions
880 Constructing Function Calls
881 ===========================
883 Using the built-in functions described below, you can record the
884 arguments a function received, and call another function with the same
885 arguments, without knowing the number or types of the arguments.
887 You can also record the return value of that function call, and
888 later return that value, without knowing what data type the function
889 tried to return (as long as your caller expects that data type).
891 `__builtin_apply_args ()'
892 This built-in function returns a pointer of type `void *' to data
893 describing how to perform a call with the same arguments as were
894 passed to the current function.
896 The function saves the arg pointer register, structure value
897 address, and all registers that might be used to pass arguments to
898 a function into a block of memory allocated on the stack. Then it
899 returns the address of that block.
901 `__builtin_apply (FUNCTION, ARGUMENTS, SIZE)'
902 This built-in function invokes FUNCTION (type `void (*)()') with a
903 copy of the parameters described by ARGUMENTS (type `void *') and
906 The value of ARGUMENTS should be the value returned by
907 `__builtin_apply_args'. The argument SIZE specifies the size of
908 the stack argument data, in bytes.
910 This function returns a pointer of type `void *' to data describing
911 how to return whatever value was returned by FUNCTION. The data
912 is saved in a block of memory allocated on the stack.
914 It is not always simple to compute the proper value for SIZE. The
915 value is used by `__builtin_apply' to compute the amount of data
916 that should be pushed on the stack and copied from the incoming
919 `__builtin_return (RESULT)'
920 This built-in function returns the value described by RESULT from
921 the containing function. You should specify, for RESULT, a value
922 returned by `__builtin_apply'.
925 File: gcc.info, Node: Naming Types, Next: Typeof, Prev: Constructing Calls, Up: C Extensions
927 Naming an Expression's Type
928 ===========================
930 You can give a name to the type of an expression using a `typedef'
931 declaration with an initializer. Here is how to define NAME as a type
932 name for the type of EXP:
936 This is useful in conjunction with the statements-within-expressions
937 feature. Here is how the two together can be used to define a safe
938 "maximum" macro that operates on any arithmetic type:
941 ({typedef _ta = (a), _tb = (b); \
942 _ta _a = (a); _tb _b = (b); \
943 _a > _b ? _a : _b; })
945 The reason for using names that start with underscores for the local
946 variables is to avoid conflicts with variable names that occur within
947 the expressions that are substituted for `a' and `b'. Eventually we
948 hope to design a new form of declaration syntax that allows you to
949 declare variables whose scopes start only after their initializers;
950 this will be a more reliable way to prevent such conflicts.
953 File: gcc.info, Node: Typeof, Next: Lvalues, Prev: Naming Types, Up: C Extensions
955 Referring to a Type with `typeof'
956 =================================
958 Another way to refer to the type of an expression is with `typeof'.
959 The syntax of using of this keyword looks like `sizeof', but the
960 construct acts semantically like a type name defined with `typedef'.
962 There are two ways of writing the argument to `typeof': with an
963 expression or with a type. Here is an example with an expression:
967 This assumes that `x' is an array of functions; the type described is
968 that of the values of the functions.
970 Here is an example with a typename as the argument:
974 Here the type described is that of pointers to `int'.
976 If you are writing a header file that must work when included in
977 ANSI C programs, write `__typeof__' instead of `typeof'. *Note
978 Alternate Keywords::.
980 A `typeof'-construct can be used anywhere a typedef name could be
981 used. For example, you can use it in a declaration, in a cast, or
982 inside of `sizeof' or `typeof'.
984 * This declares `y' with the type of what `x' points to.
988 * This declares `y' as an array of such values.
992 * This declares `y' as an array of pointers to characters:
994 typeof (typeof (char *)[4]) y;
996 It is equivalent to the following traditional C declaration:
1000 To see the meaning of the declaration using `typeof', and why it
1001 might be a useful way to write, let's rewrite it with these macros:
1003 #define pointer(T) typeof(T *)
1004 #define array(T, N) typeof(T [N])
1006 Now the declaration can be rewritten this way:
1008 array (pointer (char), 4) y;
1010 Thus, `array (pointer (char), 4)' is the type of arrays of 4
1014 File: gcc.info, Node: Lvalues, Next: Conditionals, Prev: Typeof, Up: C Extensions
1019 Compound expressions, conditional expressions and casts are allowed
1020 as lvalues provided their operands are lvalues. This means that you
1021 can take their addresses or store values into them.
1023 Standard C++ allows compound expressions and conditional expressions
1024 as lvalues, and permits casts to reference type, so use of this
1025 extension is deprecated for C++ code.
1027 For example, a compound expression can be assigned, provided the last
1028 expression in the sequence is an lvalue. These two expressions are
1034 Similarly, the address of the compound expression can be taken.
1035 These two expressions are equivalent:
1040 A conditional expression is a valid lvalue if its type is not void
1041 and the true and false branches are both valid lvalues. For example,
1042 these two expressions are equivalent:
1045 (a ? b = 5 : (c = 5))
1047 A cast is a valid lvalue if its operand is an lvalue. A simple
1048 assignment whose left-hand side is a cast works by converting the
1049 right-hand side first to the specified type, then to the type of the
1050 inner left-hand side expression. After this is stored, the value is
1051 converted back to the specified type to become the value of the
1052 assignment. Thus, if `a' has type `char *', the following two
1053 expressions are equivalent:
1056 (int)(a = (char *)(int)5)
1058 An assignment-with-arithmetic operation such as `+=' applied to a
1059 cast performs the arithmetic using the type resulting from the cast,
1060 and then continues as in the previous case. Therefore, these two
1061 expressions are equivalent:
1064 (int)(a = (char *)(int) ((int)a + 5))
1066 You cannot take the address of an lvalue cast, because the use of its
1067 address would not work out coherently. Suppose that `&(int)f' were
1068 permitted, where `f' has type `float'. Then the following statement
1069 would try to store an integer bit-pattern where a floating point number
1074 This is quite different from what `(int)f = 1' would do--that would
1075 convert 1 to floating point and store it. Rather than cause this
1076 inconsistency, we think it is better to prohibit use of `&' on a cast.
1078 If you really do want an `int *' pointer with the address of `f',
1079 you can simply write `(int *)&f'.
1082 File: gcc.info, Node: Conditionals, Next: Long Long, Prev: Lvalues, Up: C Extensions
1084 Conditionals with Omitted Operands
1085 ==================================
1087 The middle operand in a conditional expression may be omitted. Then
1088 if the first operand is nonzero, its value is the value of the
1089 conditional expression.
1091 Therefore, the expression
1095 has the value of `x' if that is nonzero; otherwise, the value of `y'.
1097 This example is perfectly equivalent to
1101 In this simple case, the ability to omit the middle operand is not
1102 especially useful. When it becomes useful is when the first operand
1103 does, or may (if it is a macro argument), contain a side effect. Then
1104 repeating the operand in the middle would perform the side effect
1105 twice. Omitting the middle operand uses the value already computed
1106 without the undesirable effects of recomputing it.
1109 File: gcc.info, Node: Long Long, Next: Complex, Prev: Conditionals, Up: C Extensions
1111 Double-Word Integers
1112 ====================
1114 GNU C supports data types for integers that are twice as long as
1115 `int'. Simply write `long long int' for a signed integer, or `unsigned
1116 long long int' for an unsigned integer. To make an integer constant of
1117 type `long long int', add the suffix `LL' to the integer. To make an
1118 integer constant of type `unsigned long long int', add the suffix `ULL'
1121 You can use these types in arithmetic like any other integer types.
1122 Addition, subtraction, and bitwise boolean operations on these types
1123 are open-coded on all types of machines. Multiplication is open-coded
1124 if the machine supports fullword-to-doubleword a widening multiply
1125 instruction. Division and shifts are open-coded only on machines that
1126 provide special support. The operations that are not open-coded use
1127 special library routines that come with GNU CC.
1129 There may be pitfalls when you use `long long' types for function
1130 arguments, unless you declare function prototypes. If a function
1131 expects type `int' for its argument, and you pass a value of type `long
1132 long int', confusion will result because the caller and the subroutine
1133 will disagree about the number of bytes for the argument. Likewise, if
1134 the function expects `long long int' and you pass `int'. The best way
1135 to avoid such problems is to use prototypes.
1138 File: gcc.info, Node: Complex, Next: Zero Length, Prev: Long Long, Up: C Extensions
1143 GNU C supports complex data types. You can declare both complex
1144 integer types and complex floating types, using the keyword
1147 For example, `__complex__ double x;' declares `x' as a variable
1148 whose real part and imaginary part are both of type `double'.
1149 `__complex__ short int y;' declares `y' to have real and imaginary
1150 parts of type `short int'; this is not likely to be useful, but it
1151 shows that the set of complex types is complete.
1153 To write a constant with a complex data type, use the suffix `i' or
1154 `j' (either one; they are equivalent). For example, `2.5fi' has type
1155 `__complex__ float' and `3i' has type `__complex__ int'. Such a
1156 constant always has a pure imaginary value, but you can form any
1157 complex value you like by adding one to a real constant.
1159 To extract the real part of a complex-valued expression EXP, write
1160 `__real__ EXP'. Likewise, use `__imag__' to extract the imaginary part.
1162 The operator `~' performs complex conjugation when used on a value
1163 with a complex type.
1165 GNU CC can allocate complex automatic variables in a noncontiguous
1166 fashion; it's even possible for the real part to be in a register while
1167 the imaginary part is on the stack (or vice-versa). None of the
1168 supported debugging info formats has a way to represent noncontiguous
1169 allocation like this, so GNU CC describes a noncontiguous complex
1170 variable as if it were two separate variables of noncomplex type. If
1171 the variable's actual name is `foo', the two fictitious variables are
1172 named `foo$real' and `foo$imag'. You can examine and set these two
1173 fictitious variables with your debugger.
1175 A future version of GDB will know how to recognize such pairs and
1176 treat them as a single variable with a complex type.
1179 File: gcc.info, Node: Zero Length, Next: Variable Length, Prev: Complex, Up: C Extensions
1181 Arrays of Length Zero
1182 =====================
1184 Zero-length arrays are allowed in GNU C. They are very useful as
1185 the last element of a structure which is really a header for a
1186 variable-length object:
1194 struct line *thisline = (struct line *)
1195 malloc (sizeof (struct line) + this_length);
1196 thisline->length = this_length;
1199 In standard C, you would have to give `contents' a length of 1, which
1200 means either you waste space or complicate the argument to `malloc'.