| This is Info file gcc.info, produced by Makeinfo version 1.68 from the |
| input file gcc.texi. |
| |
| This file documents the use and the internals of the GNU compiler. |
| |
| Published by the Free Software Foundation 59 Temple Place - Suite 330 |
| Boston, MA 02111-1307 USA |
| |
| Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of this |
| manual provided the copyright notice and this permission notice are |
| preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of |
| this manual under the conditions for verbatim copying, provided also |
| that the sections entitled "GNU General Public License," "Funding for |
| Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are |
| included exactly as in the original, and provided that the entire |
| resulting derived work is distributed under the terms of a permission |
| notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this |
| manual into another language, under the above conditions for modified |
| versions, except that the sections entitled "GNU General Public |
| License," "Funding for Free Software," and "Protect Your Freedom--Fight |
| `Look And Feel'", and this permission notice, may be included in |
| translations approved by the Free Software Foundation instead of in the |
| original English. |
| |
| |
| File: gcc.info, Node: Cross Runtime, Next: Build Cross, Prev: Cross Headers, Up: Cross-Compiler |
| |
| `libgcc.a' and Cross-Compilers |
| ------------------------------ |
| |
| Code compiled by GNU CC uses certain runtime support functions |
| implicitly. Some of these functions can be compiled successfully with |
| GNU CC itself, but a few cannot be. These problem functions are in the |
| source file `libgcc1.c'; the library made from them is called |
| `libgcc1.a'. |
| |
| When you build a native compiler, these functions are compiled with |
| some other compiler-the one that you use for bootstrapping GNU CC. |
| Presumably it knows how to open code these operations, or else knows how |
| to call the run-time emulation facilities that the machine comes with. |
| But this approach doesn't work for building a cross-compiler. The |
| compiler that you use for building knows about the host system, not the |
| target system. |
| |
| So, when you build a cross-compiler you have to supply a suitable |
| library `libgcc1.a' that does the job it is expected to do. |
| |
| To compile `libgcc1.c' with the cross-compiler itself does not work. |
| The functions in this file are supposed to implement arithmetic |
| operations that GNU CC does not know how to open code for your target |
| machine. If these functions are compiled with GNU CC itself, they will |
| compile into infinite recursion. |
| |
| On any given target, most of these functions are not needed. If GNU |
| CC can open code an arithmetic operation, it will not call these |
| functions to perform the operation. It is possible that on your target |
| machine, none of these functions is needed. If so, you can supply an |
| empty library as `libgcc1.a'. |
| |
| Many targets need library support only for multiplication and |
| division. If you are linking with a library that contains functions for |
| multiplication and division, you can tell GNU CC to call them directly |
| by defining the macros `MULSI3_LIBCALL', and the like. These macros |
| need to be defined in the target description macro file. For some |
| targets, they are defined already. This may be sufficient to avoid the |
| need for libgcc1.a; if so, you can supply an empty library. |
| |
| Some targets do not have floating point instructions; they need other |
| functions in `libgcc1.a', which do floating arithmetic. Recent |
| versions of GNU CC have a file which emulates floating point. With a |
| certain amount of work, you should be able to construct a floating |
| point emulator that can be used as `libgcc1.a'. Perhaps future |
| versions will contain code to do this automatically and conveniently. |
| That depends on whether someone wants to implement it. |
| |
| Some embedded targets come with all the necessary `libgcc1.a' |
| routines written in C or assembler. These targets build `libgcc1.a' |
| automatically and you do not need to do anything special for them. |
| Other embedded targets do not need any `libgcc1.a' routines since all |
| the necessary operations are supported by the hardware. |
| |
| If your target system has another C compiler, you can configure GNU |
| CC as a native compiler on that machine, build just `libgcc1.a' with |
| `make libgcc1.a' on that machine, and use the resulting file with the |
| cross-compiler. To do this, execute the following on the target |
| machine: |
| |
| cd TARGET-BUILD-DIR |
| ./configure --host=sparc --target=sun3 |
| make libgcc1.a |
| |
| And then this on the host machine: |
| |
| ftp TARGET-MACHINE |
| binary |
| cd TARGET-BUILD-DIR |
| get libgcc1.a |
| quit |
| |
| Another way to provide the functions you need in `libgcc1.a' is to |
| define the appropriate `perform_...' macros for those functions. If |
| these definitions do not use the C arithmetic operators that they are |
| meant to implement, you should be able to compile them with the |
| cross-compiler you are building. (If these definitions already exist |
| for your target file, then you are all set.) |
| |
| To build `libgcc1.a' using the perform macros, use |
| `LIBGCC1=libgcc1.a OLDCC=./xgcc' when building the compiler. |
| Otherwise, you should place your replacement library under the name |
| `libgcc1.a' in the directory in which you will build the |
| cross-compiler, before you run `make'. |
| |
| |
| File: gcc.info, Node: Cross Headers, Next: Cross Runtime, Prev: Tools and Libraries, Up: Cross-Compiler |
| |
| Cross-Compilers and Header Files |
| -------------------------------- |
| |
| If you are cross-compiling a standalone program or a program for an |
| embedded system, then you may not need any header files except the few |
| that are part of GNU CC (and those of your program). However, if you |
| intend to link your program with a standard C library such as `libc.a', |
| then you probably need to compile with the header files that go with |
| the library you use. |
| |
| The GNU C compiler does not come with these files, because (1) they |
| are system-specific, and (2) they belong in a C library, not in a |
| compiler. |
| |
| If the GNU C library supports your target machine, then you can get |
| the header files from there (assuming you actually use the GNU library |
| when you link your program). |
| |
| If your target machine comes with a C compiler, it probably comes |
| with suitable header files also. If you make these files accessible |
| from the host machine, the cross-compiler can use them also. |
| |
| Otherwise, you're on your own in finding header files to use when |
| cross-compiling. |
| |
| When you have found suitable header files, put them in the directory |
| `/usr/local/TARGET/include', before building the cross compiler. Then |
| installation will run fixincludes properly and install the corrected |
| versions of the header files where the compiler will use them. |
| |
| Provide the header files before you build the cross-compiler, because |
| the build stage actually runs the cross-compiler to produce parts of |
| `libgcc.a'. (These are the parts that *can* be compiled with GNU CC.) |
| Some of them need suitable header files. |
| |
| Here's an example showing how to copy the header files from a target |
| machine. On the target machine, do this: |
| |
| (cd /usr/include; tar cf - .) > tarfile |
| |
| Then, on the host machine, do this: |
| |
| ftp TARGET-MACHINE |
| lcd /usr/local/TARGET/include |
| get tarfile |
| quit |
| tar xf tarfile |
| |
| |
| File: gcc.info, Node: Build Cross, Prev: Cross Runtime, Up: Cross-Compiler |
| |
| Actually Building the Cross-Compiler |
| ------------------------------------ |
| |
| Now you can proceed just as for compiling a single-machine compiler |
| through the step of building stage 1. If you have not provided some |
| sort of `libgcc1.a', then compilation will give up at the point where |
| it needs that file, printing a suitable error message. If you do |
| provide `libgcc1.a', then building the compiler will automatically |
| compile and link a test program called `libgcc1-test'; if you get |
| errors in the linking, it means that not all of the necessary routines |
| in `libgcc1.a' are available. |
| |
| You must provide the header file `float.h'. One way to do this is |
| to compile `enquire' and run it on your target machine. The job of |
| `enquire' is to run on the target machine and figure out by experiment |
| the nature of its floating point representation. `enquire' records its |
| findings in the header file `float.h'. If you can't produce this file |
| by running `enquire' on the target machine, then you will need to come |
| up with a suitable `float.h' in some other way (or else, avoid using it |
| in your programs). |
| |
| Do not try to build stage 2 for a cross-compiler. It doesn't work to |
| rebuild GNU CC as a cross-compiler using the cross-compiler, because |
| that would produce a program that runs on the target machine, not on the |
| host. For example, if you compile a 386-to-68030 cross-compiler with |
| itself, the result will not be right either for the 386 (because it was |
| compiled into 68030 code) or for the 68030 (because it was configured |
| for a 386 as the host). If you want to compile GNU CC into 68030 code, |
| whether you compile it on a 68030 or with a cross-compiler on a 386, you |
| must specify a 68030 as the host when you configure it. |
| |
| To install the cross-compiler, use `make install', as usual. |
| |
| |
| File: gcc.info, Node: Sun Install, Next: VMS Install, Prev: Cross-Compiler, Up: Installation |
| |
| Installing GNU CC on the Sun |
| ============================ |
| |
| On Solaris (version 2.1), do not use the linker or other tools in |
| `/usr/ucb' to build GNU CC. Use `/usr/ccs/bin'. |
| |
| Make sure the environment variable `FLOAT_OPTION' is not set when |
| you compile `libgcc.a'. If this option were set to `f68881' when |
| `libgcc.a' is compiled, the resulting code would demand to be linked |
| with a special startup file and would not link properly without special |
| pains. |
| |
| There is a bug in `alloca' in certain versions of the Sun library. |
| To avoid this bug, install the binaries of GNU CC that were compiled by |
| GNU CC. They use `alloca' as a built-in function and never the one in |
| the library. |
| |
| Some versions of the Sun compiler crash when compiling GNU CC. The |
| problem is a segmentation fault in cpp. This problem seems to be due to |
| the bulk of data in the environment variables. You may be able to avoid |
| it by using the following command to compile GNU CC with Sun CC: |
| |
| make CC="TERMCAP=x OBJS=x LIBFUNCS=x STAGESTUFF=x cc" |
| |
| SunOS 4.1.3 and 4.1.3_U1 have bugs that can cause intermittent core |
| dumps when compiling GNU CC. A common symptom is an internal compiler |
| error which does not recur if you run it again. To fix the problem, |
| install Sun recommended patch 100726 (for SunOS 4.1.3) or 101508 (for |
| SunOS 4.1.3_U1), or upgrade to a later SunOS release. |
| |
| |
| File: gcc.info, Node: VMS Install, Next: Collect2, Prev: Sun Install, Up: Installation |
| |
| Installing GNU CC on VMS |
| ======================== |
| |
| The VMS version of GNU CC is distributed in a backup saveset |
| containing both source code and precompiled binaries. |
| |
| To install the `gcc' command so you can use the compiler easily, in |
| the same manner as you use the VMS C compiler, you must install the VMS |
| CLD file for GNU CC as follows: |
| |
| 1. Define the VMS logical names `GNU_CC' and `GNU_CC_INCLUDE' to |
| point to the directories where the GNU CC executables |
| (`gcc-cpp.exe', `gcc-cc1.exe', etc.) and the C include files are |
| kept respectively. This should be done with the commands: |
| |
| $ assign /system /translation=concealed - |
| disk:[gcc.] gnu_cc |
| $ assign /system /translation=concealed - |
| disk:[gcc.include.] gnu_cc_include |
| |
| with the appropriate disk and directory names. These commands can |
| be placed in your system startup file so they will be executed |
| whenever the machine is rebooted. You may, if you choose, do this |
| via the `GCC_INSTALL.COM' script in the `[GCC]' directory. |
| |
| 2. Install the `GCC' command with the command line: |
| |
| $ set command /table=sys$common:[syslib]dcltables - |
| /output=sys$common:[syslib]dcltables gnu_cc:[000000]gcc |
| $ install replace sys$common:[syslib]dcltables |
| |
| 3. To install the help file, do the following: |
| |
| $ library/help sys$library:helplib.hlb gcc.hlp |
| |
| Now you can invoke the compiler with a command like `gcc /verbose |
| file.c', which is equivalent to the command `gcc -v -c file.c' in |
| Unix. |
| |
| If you wish to use GNU C++ you must first install GNU CC, and then |
| perform the following steps: |
| |
| 1. Define the VMS logical name `GNU_GXX_INCLUDE' to point to the |
| directory where the preprocessor will search for the C++ header |
| files. This can be done with the command: |
| |
| $ assign /system /translation=concealed - |
| disk:[gcc.gxx_include.] gnu_gxx_include |
| |
| with the appropriate disk and directory name. If you are going to |
| be using a C++ runtime library, this is where its install |
| procedure will install its header files. |
| |
| 2. Obtain the file `gcc-cc1plus.exe', and place this in the same |
| directory that `gcc-cc1.exe' is kept. |
| |
| The GNU C++ compiler can be invoked with a command like `gcc /plus |
| /verbose file.cc', which is equivalent to the command `g++ -v -c |
| file.cc' in Unix. |
| |
| We try to put corresponding binaries and sources on the VMS |
| distribution tape. But sometimes the binaries will be from an older |
| version than the sources, because we don't always have time to update |
| them. (Use the `/version' option to determine the version number of |
| the binaries and compare it with the source file `version.c' to tell |
| whether this is so.) In this case, you should use the binaries you get |
| to recompile the sources. If you must recompile, here is how: |
| |
| 1. Execute the command procedure `vmsconfig.com' to set up the files |
| `tm.h', `config.h', `aux-output.c', and `md.', and to create files |
| `tconfig.h' and `hconfig.h'. This procedure also creates several |
| linker option files used by `make-cc1.com' and a data file used by |
| `make-l2.com'. |
| |
| $ @vmsconfig.com |
| |
| 2. Setup the logical names and command tables as defined above. In |
| addition, define the VMS logical name `GNU_BISON' to point at the |
| to the directories where the Bison executable is kept. This |
| should be done with the command: |
| |
| $ assign /system /translation=concealed - |
| disk:[bison.] gnu_bison |
| |
| You may, if you choose, use the `INSTALL_BISON.COM' script in the |
| `[BISON]' directory. |
| |
| 3. Install the `BISON' command with the command line: |
| |
| $ set command /table=sys$common:[syslib]dcltables - |
| /output=sys$common:[syslib]dcltables - |
| gnu_bison:[000000]bison |
| $ install replace sys$common:[syslib]dcltables |
| |
| 4. Type `@make-gcc' to recompile everything (alternatively, submit |
| the file `make-gcc.com' to a batch queue). If you wish to build |
| the GNU C++ compiler as well as the GNU CC compiler, you must |
| first edit `make-gcc.com' and follow the instructions that appear |
| in the comments. |
| |
| 5. In order to use GCC, you need a library of functions which GCC |
| compiled code will call to perform certain tasks, and these |
| functions are defined in the file `libgcc2.c'. To compile this |
| you should use the command procedure `make-l2.com', which will |
| generate the library `libgcc2.olb'. `libgcc2.olb' should be built |
| using the compiler built from the same distribution that |
| `libgcc2.c' came from, and `make-gcc.com' will automatically do |
| all of this for you. |
| |
| To install the library, use the following commands: |
| |
| $ library gnu_cc:[000000]gcclib/delete=(new,eprintf) |
| $ library gnu_cc:[000000]gcclib/delete=L_* |
| $ library libgcc2/extract=*/output=libgcc2.obj |
| $ library gnu_cc:[000000]gcclib libgcc2.obj |
| |
| The first command simply removes old modules that will be replaced |
| with modules from `libgcc2' under different module names. The |
| modules `new' and `eprintf' may not actually be present in your |
| `gcclib.olb'--if the VMS librarian complains about those modules |
| not being present, simply ignore the message and continue on with |
| the next command. The second command removes the modules that |
| came from the previous version of the library `libgcc2.c'. |
| |
| Whenever you update the compiler on your system, you should also |
| update the library with the above procedure. |
| |
| 6. You may wish to build GCC in such a way that no files are written |
| to the directory where the source files reside. An example would |
| be the when the source files are on a read-only disk. In these |
| cases, execute the following DCL commands (substituting your |
| actual path names): |
| |
| $ assign dua0:[gcc.build_dir.]/translation=concealed, - |
| dua1:[gcc.source_dir.]/translation=concealed gcc_build |
| $ set default gcc_build:[000000] |
| |
| where the directory `dua1:[gcc.source_dir]' contains the source |
| code, and the directory `dua0:[gcc.build_dir]' is meant to contain |
| all of the generated object files and executables. Once you have |
| done this, you can proceed building GCC as described above. (Keep |
| in mind that `gcc_build' is a rooted logical name, and thus the |
| device names in each element of the search list must be an actual |
| physical device name rather than another rooted logical name). |
| |
| 7. *If you are building GNU CC with a previous version of GNU CC, you |
| also should check to see that you have the newest version of the |
| assembler*. In particular, GNU CC version 2 treats global constant |
| variables slightly differently from GNU CC version 1, and GAS |
| version 1.38.1 does not have the patches required to work with GCC |
| version 2. If you use GAS 1.38.1, then `extern const' variables |
| will not have the read-only bit set, and the linker will generate |
| warning messages about mismatched psect attributes for these |
| variables. These warning messages are merely a nuisance, and can |
| safely be ignored. |
| |
| If you are compiling with a version of GNU CC older than 1.33, |
| specify `/DEFINE=("inline=")' as an option in all the |
| compilations. This requires editing all the `gcc' commands in |
| `make-cc1.com'. (The older versions had problems supporting |
| `inline'.) Once you have a working 1.33 or newer GNU CC, you can |
| change this file back. |
| |
| 8. If you want to build GNU CC with the VAX C compiler, you will need |
| to make minor changes in `make-cccp.com' and `make-cc1.com' to |
| choose alternate definitions of `CC', `CFLAGS', and `LIBS'. See |
| comments in those files. However, you must also have a working |
| version of the GNU assembler (GNU as, aka GAS) as it is used as |
| the back-end for GNU CC to produce binary object modules and is |
| not included in the GNU CC sources. GAS is also needed to compile |
| `libgcc2' in order to build `gcclib' (see above); `make-l2.com' |
| expects to be able to find it operational in |
| `gnu_cc:[000000]gnu-as.exe'. |
| |
| To use GNU CC on VMS, you need the VMS driver programs `gcc.exe', |
| `gcc.com', and `gcc.cld'. They are distributed with the VMS |
| binaries (`gcc-vms') rather than the GNU CC sources. GAS is also |
| included in `gcc-vms', as is Bison. |
| |
| Once you have successfully built GNU CC with VAX C, you should use |
| the resulting compiler to rebuild itself. Before doing this, be |
| sure to restore the `CC', `CFLAGS', and `LIBS' definitions in |
| `make-cccp.com' and `make-cc1.com'. The second generation |
| compiler will be able to take advantage of many optimizations that |
| must be suppressed when building with other compilers. |
| |
| Under previous versions of GNU CC, the generated code would |
| occasionally give strange results when linked with the sharable |
| `VAXCRTL' library. Now this should work. |
| |
| Even with this version, however, GNU CC itself should not be linked |
| with the sharable `VAXCRTL'. The version of `qsort' in `VAXCRTL' has a |
| bug (known to be present in VMS versions V4.6 through V5.5) which |
| causes the compiler to fail. |
| |
| The executables are generated by `make-cc1.com' and `make-cccp.com' |
| use the object library version of `VAXCRTL' in order to make use of the |
| `qsort' routine in `gcclib.olb'. If you wish to link the compiler |
| executables with the shareable image version of `VAXCRTL', you should |
| edit the file `tm.h' (created by `vmsconfig.com') to define the macro |
| `QSORT_WORKAROUND'. |
| |
| `QSORT_WORKAROUND' is always defined when GNU CC is compiled with |
| VAX C, to avoid a problem in case `gcclib.olb' is not yet available. |
| |
| |
| File: gcc.info, Node: Collect2, Next: Header Dirs, Prev: VMS Install, Up: Installation |
| |
| `collect2' |
| ========== |
| |
| Many target systems do not have support in the assembler and linker |
| for "constructors"--initialization functions to be called before the |
| official "start" of `main'. On such systems, GNU CC uses a utility |
| called `collect2' to arrange to call these functions at start time. |
| |
| The program `collect2' works by linking the program once and looking |
| through the linker output file for symbols with particular names |
| indicating they are constructor functions. If it finds any, it creates |
| a new temporary `.c' file containing a table of them, compiles it, and |
| links the program a second time including that file. |
| |
| The actual calls to the constructors are carried out by a subroutine |
| called `__main', which is called (automatically) at the beginning of |
| the body of `main' (provided `main' was compiled with GNU CC). Calling |
| `__main' is necessary, even when compiling C code, to allow linking C |
| and C++ object code together. (If you use `-nostdlib', you get an |
| unresolved reference to `__main', since it's defined in the standard |
| GCC library. Include `-lgcc' at the end of your compiler command line |
| to resolve this reference.) |
| |
| The program `collect2' is installed as `ld' in the directory where |
| the passes of the compiler are installed. When `collect2' needs to |
| find the *real* `ld', it tries the following file names: |
| |
| * `real-ld' in the directories listed in the compiler's search |
| directories. |
| |
| * `real-ld' in the directories listed in the environment variable |
| `PATH'. |
| |
| * The file specified in the `REAL_LD_FILE_NAME' configuration macro, |
| if specified. |
| |
| * `ld' in the compiler's search directories, except that `collect2' |
| will not execute itself recursively. |
| |
| * `ld' in `PATH'. |
| |
| "The compiler's search directories" means all the directories where |
| `gcc' searches for passes of the compiler. This includes directories |
| that you specify with `-B'. |
| |
| Cross-compilers search a little differently: |
| |
| * `real-ld' in the compiler's search directories. |
| |
| * `TARGET-real-ld' in `PATH'. |
| |
| * The file specified in the `REAL_LD_FILE_NAME' configuration macro, |
| if specified. |
| |
| * `ld' in the compiler's search directories. |
| |
| * `TARGET-ld' in `PATH'. |
| |
| `collect2' explicitly avoids running `ld' using the file name under |
| which `collect2' itself was invoked. In fact, it remembers up a list |
| of such names--in case one copy of `collect2' finds another copy (or |
| version) of `collect2' installed as `ld' in a second place in the |
| search path. |
| |
| `collect2' searches for the utilities `nm' and `strip' using the |
| same algorithm as above for `ld'. |
| |
| |
| File: gcc.info, Node: Header Dirs, Prev: Collect2, Up: Installation |
| |
| Standard Header File Directories |
| ================================ |
| |
| `GCC_INCLUDE_DIR' means the same thing for native and cross. It is |
| where GNU CC stores its private include files, and also where GNU CC |
| stores the fixed include files. A cross compiled GNU CC runs |
| `fixincludes' on the header files in `$(tooldir)/include'. (If the |
| cross compilation header files need to be fixed, they must be installed |
| before GNU CC is built. If the cross compilation header files are |
| already suitable for ANSI C and GNU CC, nothing special need be done). |
| |
| `GPLUS_INCLUDE_DIR' means the same thing for native and cross. It |
| is where `g++' looks first for header files. The C++ library installs |
| only target independent header files in that directory. |
| |
| `LOCAL_INCLUDE_DIR' is used only for a native compiler. It is |
| normally `/usr/local/include'. GNU CC searches this directory so that |
| users can install header files in `/usr/local/include'. |
| |
| `CROSS_INCLUDE_DIR' is used only for a cross compiler. GNU CC |
| doesn't install anything there. |
| |
| `TOOL_INCLUDE_DIR' is used for both native and cross compilers. It |
| is the place for other packages to install header files that GNU CC will |
| use. For a cross-compiler, this is the equivalent of `/usr/include'. |
| When you build a cross-compiler, `fixincludes' processes any header |
| files in this directory. |
| |
| |
| File: gcc.info, Node: C Extensions, Next: C++ Extensions, Prev: Installation, Up: Top |
| |
| Extensions to the C Language Family |
| *********************************** |
| |
| GNU C provides several language features not found in ANSI standard |
| C. (The `-pedantic' option directs GNU CC to print a warning message if |
| any of these features is used.) To test for the availability of these |
| features in conditional compilation, check for a predefined macro |
| `__GNUC__', which is always defined under GNU CC. |
| |
| These extensions are available in C and Objective C. Most of them |
| are also available in C++. *Note Extensions to the C++ Language: C++ |
| Extensions, for extensions that apply *only* to C++. |
| |
| * Menu: |
| |
| * Statement Exprs:: Putting statements and declarations inside expressions. |
| * Local Labels:: Labels local to a statement-expression. |
| * Labels as Values:: Getting pointers to labels, and computed gotos. |
| * Nested Functions:: As in Algol and Pascal, lexical scoping of functions. |
| * Constructing Calls:: Dispatching a call to another function. |
| * Naming Types:: Giving a name to the type of some expression. |
| * Typeof:: `typeof': referring to the type of an expression. |
| * Lvalues:: Using `?:', `,' and casts in lvalues. |
| * Conditionals:: Omitting the middle operand of a `?:' expression. |
| * Long Long:: Double-word integers--`long long int'. |
| * Complex:: Data types for complex numbers. |
| * Zero Length:: Zero-length arrays. |
| * Variable Length:: Arrays whose length is computed at run time. |
| * Macro Varargs:: Macros with variable number of arguments. |
| * Subscripting:: Any array can be subscripted, even if not an lvalue. |
| * Pointer Arith:: Arithmetic on `void'-pointers and function pointers. |
| * Initializers:: Non-constant initializers. |
| * Constructors:: Constructor expressions give structures, unions |
| or arrays as values. |
| * Labeled Elements:: Labeling elements of initializers. |
| * Cast to Union:: Casting to union type from any member of the union. |
| * Case Ranges:: `case 1 ... 9' and such. |
| * Function Attributes:: Declaring that functions have no side effects, |
| or that they can never return. |
| * Function Prototypes:: Prototype declarations and old-style definitions. |
| * C++ Comments:: C++ comments are recognized. |
| * Dollar Signs:: Dollar sign is allowed in identifiers. |
| * Character Escapes:: `\e' stands for the character <ESC>. |
| * Variable Attributes:: Specifying attributes of variables. |
| * Type Attributes:: Specifying attributes of types. |
| * Alignment:: Inquiring about the alignment of a type or variable. |
| * Inline:: Defining inline functions (as fast as macros). |
| * Extended Asm:: Assembler instructions with C expressions as operands. |
| (With them you can define "built-in" functions.) |
| * Asm Labels:: Specifying the assembler name to use for a C symbol. |
| * Explicit Reg Vars:: Defining variables residing in specified registers. |
| * Alternate Keywords:: `__const__', `__asm__', etc., for header files. |
| * Incomplete Enums:: `enum foo;', with details to follow. |
| * Function Names:: Printable strings which are the name of the current |
| function. |
| * Return Address:: Getting the return or frame address of a function. |
| |
| |
| File: gcc.info, Node: Statement Exprs, Next: Local Labels, Up: C Extensions |
| |
| Statements and Declarations in Expressions |
| ========================================== |
| |
| A compound statement enclosed in parentheses may appear as an |
| expression in GNU C. This allows you to use loops, switches, and local |
| variables within an expression. |
| |
| Recall that a compound statement is a sequence of statements |
| surrounded by braces; in this construct, parentheses go around the |
| braces. For example: |
| |
| ({ int y = foo (); int z; |
| if (y > 0) z = y; |
| else z = - y; |
| z; }) |
| |
| is a valid (though slightly more complex than necessary) expression for |
| the absolute value of `foo ()'. |
| |
| The last thing in the compound statement should be an expression |
| followed by a semicolon; the value of this subexpression serves as the |
| value of the entire construct. (If you use some other kind of statement |
| last within the braces, the construct has type `void', and thus |
| effectively no value.) |
| |
| This feature is especially useful in making macro definitions "safe" |
| (so that they evaluate each operand exactly once). For example, the |
| "maximum" function is commonly defined as a macro in standard C as |
| follows: |
| |
| #define max(a,b) ((a) > (b) ? (a) : (b)) |
| |
| But this definition computes either A or B twice, with bad results if |
| the operand has side effects. In GNU C, if you know the type of the |
| operands (here let's assume `int'), you can define the macro safely as |
| follows: |
| |
| #define maxint(a,b) \ |
| ({int _a = (a), _b = (b); _a > _b ? _a : _b; }) |
| |
| Embedded statements are not allowed in constant expressions, such as |
| the value of an enumeration constant, the width of a bit field, or the |
| initial value of a static variable. |
| |
| If you don't know the type of the operand, you can still do this, |
| but you must use `typeof' (*note Typeof::.) or type naming (*note |
| Naming Types::.). |
| |
| |
| File: gcc.info, Node: Local Labels, Next: Labels as Values, Prev: Statement Exprs, Up: C Extensions |
| |
| Locally Declared Labels |
| ======================= |
| |
| Each statement expression is a scope in which "local labels" can be |
| declared. A local label is simply an identifier; you can jump to it |
| with an ordinary `goto' statement, but only from within the statement |
| expression it belongs to. |
| |
| A local label declaration looks like this: |
| |
| __label__ LABEL; |
| |
| or |
| |
| __label__ LABEL1, LABEL2, ...; |
| |
| Local label declarations must come at the beginning of the statement |
| expression, right after the `({', before any ordinary declarations. |
| |
| The label declaration defines the label *name*, but does not define |
| the label itself. You must do this in the usual way, with `LABEL:', |
| within the statements of the statement expression. |
| |
| The local label feature is useful because statement expressions are |
| often used in macros. If the macro contains nested loops, a `goto' can |
| be useful for breaking out of them. However, an ordinary label whose |
| scope is the whole function cannot be used: if the macro can be |
| expanded several times in one function, the label will be multiply |
| defined in that function. A local label avoids this problem. For |
| example: |
| |
| #define SEARCH(array, target) \ |
| ({ \ |
| __label__ found; \ |
| typeof (target) _SEARCH_target = (target); \ |
| typeof (*(array)) *_SEARCH_array = (array); \ |
| int i, j; \ |
| int value; \ |
| for (i = 0; i < max; i++) \ |
| for (j = 0; j < max; j++) \ |
| if (_SEARCH_array[i][j] == _SEARCH_target) \ |
| { value = i; goto found; } \ |
| value = -1; \ |
| found: \ |
| value; \ |
| }) |
| |
| |
| File: gcc.info, Node: Labels as Values, Next: Nested Functions, Prev: Local Labels, Up: C Extensions |
| |
| Labels as Values |
| ================ |
| |
| You can get the address of a label defined in the current function |
| (or a containing function) with the unary operator `&&'. The value has |
| type `void *'. This value is a constant and can be used wherever a |
| constant of that type is valid. For example: |
| |
| void *ptr; |
| ... |
| ptr = &&foo; |
| |
| To use these values, you need to be able to jump to one. This is |
| done with the computed goto statement(1), `goto *EXP;'. For example, |
| |
| goto *ptr; |
| |
| Any expression of type `void *' is allowed. |
| |
| One way of using these constants is in initializing a static array |
| that will serve as a jump table: |
| |
| static void *array[] = { &&foo, &&bar, &&hack }; |
| |
| Then you can select a label with indexing, like this: |
| |
| goto *array[i]; |
| |
| Note that this does not check whether the subscript is in bounds--array |
| indexing in C never does that. |
| |
| Such an array of label values serves a purpose much like that of the |
| `switch' statement. The `switch' statement is cleaner, so use that |
| rather than an array unless the problem does not fit a `switch' |
| statement very well. |
| |
| Another use of label values is in an interpreter for threaded code. |
| The labels within the interpreter function can be stored in the |
| threaded code for super-fast dispatching. |
| |
| You can use this mechanism to jump to code in a different function. |
| If you do that, totally unpredictable things will happen. The best way |
| to avoid this is to store the label address only in automatic variables |
| and never pass it as an argument. |
| |
| ---------- Footnotes ---------- |
| |
| (1) The analogous feature in Fortran is called an assigned goto, but |
| that name seems inappropriate in C, where one can do more than simply |
| store label addresses in label variables. |
| |
| |
| File: gcc.info, Node: Nested Functions, Next: Constructing Calls, Prev: Labels as Values, Up: C Extensions |
| |
| Nested Functions |
| ================ |
| |
| A "nested function" is a function defined inside another function. |
| (Nested functions are not supported for GNU C++.) The nested function's |
| name is local to the block where it is defined. For example, here we |
| define a nested function named `square', and call it twice: |
| |
| foo (double a, double b) |
| { |
| double square (double z) { return z * z; } |
| |
| return square (a) + square (b); |
| } |
| |
| The nested function can access all the variables of the containing |
| function that are visible at the point of its definition. This is |
| called "lexical scoping". For example, here we show a nested function |
| which uses an inherited variable named `offset': |
| |
| bar (int *array, int offset, int size) |
| { |
| int access (int *array, int index) |
| { return array[index + offset]; } |
| int i; |
| ... |
| for (i = 0; i < size; i++) |
| ... access (array, i) ... |
| } |
| |
| Nested function definitions are permitted within functions in the |
| places where variable definitions are allowed; that is, in any block, |
| before the first statement in the block. |
| |
| It is possible to call the nested function from outside the scope of |
| its name by storing its address or passing the address to another |
| function: |
| |
| hack (int *array, int size) |
| { |
| void store (int index, int value) |
| { array[index] = value; } |
| |
| intermediate (store, size); |
| } |
| |
| Here, the function `intermediate' receives the address of `store' as |
| an argument. If `intermediate' calls `store', the arguments given to |
| `store' are used to store into `array'. But this technique works only |
| so long as the containing function (`hack', in this example) does not |
| exit. |
| |
| If you try to call the nested function through its address after the |
| containing function has exited, all hell will break loose. If you try |
| to call it after a containing scope level has exited, and if it refers |
| to some of the variables that are no longer in scope, you may be lucky, |
| but it's not wise to take the risk. If, however, the nested function |
| does not refer to anything that has gone out of scope, you should be |
| safe. |
| |
| GNU CC implements taking the address of a nested function using a |
| technique called "trampolines". |
| |
| A nested function can jump to a label inherited from a containing |
| function, provided the label was explicitly declared in the containing |
| function (*note Local Labels::.). Such a jump returns instantly to the |
| containing function, exiting the nested function which did the `goto' |
| and any intermediate functions as well. Here is an example: |
| |
| bar (int *array, int offset, int size) |
| { |
| __label__ failure; |
| int access (int *array, int index) |
| { |
| if (index > size) |
| goto failure; |
| return array[index + offset]; |
| } |
| int i; |
| ... |
| for (i = 0; i < size; i++) |
| ... access (array, i) ... |
| ... |
| return 0; |
| |
| /* Control comes here from `access' |
| if it detects an error. */ |
| failure: |
| return -1; |
| } |
| |
| A nested function always has internal linkage. Declaring one with |
| `extern' is erroneous. If you need to declare the nested function |
| before its definition, use `auto' (which is otherwise meaningless for |
| function declarations). |
| |
| bar (int *array, int offset, int size) |
| { |
| __label__ failure; |
| auto int access (int *, int); |
| ... |
| int access (int *array, int index) |
| { |
| if (index > size) |
| goto failure; |
| return array[index + offset]; |
| } |
| ... |
| } |
| |
| |
| File: gcc.info, Node: Constructing Calls, Next: Naming Types, Prev: Nested Functions, Up: C Extensions |
| |
| Constructing Function Calls |
| =========================== |
| |
| Using the built-in functions described below, you can record the |
| arguments a function received, and call another function with the same |
| arguments, without knowing the number or types of the arguments. |
| |
| You can also record the return value of that function call, and |
| later return that value, without knowing what data type the function |
| tried to return (as long as your caller expects that data type). |
| |
| `__builtin_apply_args ()' |
| This built-in function returns a pointer of type `void *' to data |
| describing how to perform a call with the same arguments as were |
| passed to the current function. |
| |
| The function saves the arg pointer register, structure value |
| address, and all registers that might be used to pass arguments to |
| a function into a block of memory allocated on the stack. Then it |
| returns the address of that block. |
| |
| `__builtin_apply (FUNCTION, ARGUMENTS, SIZE)' |
| This built-in function invokes FUNCTION (type `void (*)()') with a |
| copy of the parameters described by ARGUMENTS (type `void *') and |
| SIZE (type `int'). |
| |
| The value of ARGUMENTS should be the value returned by |
| `__builtin_apply_args'. The argument SIZE specifies the size of |
| the stack argument data, in bytes. |
| |
| This function returns a pointer of type `void *' to data describing |
| how to return whatever value was returned by FUNCTION. The data |
| is saved in a block of memory allocated on the stack. |
| |
| It is not always simple to compute the proper value for SIZE. The |
| value is used by `__builtin_apply' to compute the amount of data |
| that should be pushed on the stack and copied from the incoming |
| argument area. |
| |
| `__builtin_return (RESULT)' |
| This built-in function returns the value described by RESULT from |
| the containing function. You should specify, for RESULT, a value |
| returned by `__builtin_apply'. |
| |
| |
| File: gcc.info, Node: Naming Types, Next: Typeof, Prev: Constructing Calls, Up: C Extensions |
| |
| Naming an Expression's Type |
| =========================== |
| |
| You can give a name to the type of an expression using a `typedef' |
| declaration with an initializer. Here is how to define NAME as a type |
| name for the type of EXP: |
| |
| typedef NAME = EXP; |
| |
| This is useful in conjunction with the statements-within-expressions |
| feature. Here is how the two together can be used to define a safe |
| "maximum" macro that operates on any arithmetic type: |
| |
| #define max(a,b) \ |
| ({typedef _ta = (a), _tb = (b); \ |
| _ta _a = (a); _tb _b = (b); \ |
| _a > _b ? _a : _b; }) |
| |
| The reason for using names that start with underscores for the local |
| variables is to avoid conflicts with variable names that occur within |
| the expressions that are substituted for `a' and `b'. Eventually we |
| hope to design a new form of declaration syntax that allows you to |
| declare variables whose scopes start only after their initializers; |
| this will be a more reliable way to prevent such conflicts. |
| |
| |
| File: gcc.info, Node: Typeof, Next: Lvalues, Prev: Naming Types, Up: C Extensions |
| |
| Referring to a Type with `typeof' |
| ================================= |
| |
| Another way to refer to the type of an expression is with `typeof'. |
| The syntax of using of this keyword looks like `sizeof', but the |
| construct acts semantically like a type name defined with `typedef'. |
| |
| There are two ways of writing the argument to `typeof': with an |
| expression or with a type. Here is an example with an expression: |
| |
| typeof (x[0](1)) |
| |
| This assumes that `x' is an array of functions; the type described is |
| that of the values of the functions. |
| |
| Here is an example with a typename as the argument: |
| |
| typeof (int *) |
| |
| Here the type described is that of pointers to `int'. |
| |
| If you are writing a header file that must work when included in |
| ANSI C programs, write `__typeof__' instead of `typeof'. *Note |
| Alternate Keywords::. |
| |
| A `typeof'-construct can be used anywhere a typedef name could be |
| used. For example, you can use it in a declaration, in a cast, or |
| inside of `sizeof' or `typeof'. |
| |
| * This declares `y' with the type of what `x' points to. |
| |
| typeof (*x) y; |
| |
| * This declares `y' as an array of such values. |
| |
| typeof (*x) y[4]; |
| |
| * This declares `y' as an array of pointers to characters: |
| |
| typeof (typeof (char *)[4]) y; |
| |
| It is equivalent to the following traditional C declaration: |
| |
| char *y[4]; |
| |
| To see the meaning of the declaration using `typeof', and why it |
| might be a useful way to write, let's rewrite it with these macros: |
| |
| #define pointer(T) typeof(T *) |
| #define array(T, N) typeof(T [N]) |
| |
| Now the declaration can be rewritten this way: |
| |
| array (pointer (char), 4) y; |
| |
| Thus, `array (pointer (char), 4)' is the type of arrays of 4 |
| pointers to `char'. |
| |
| |
| File: gcc.info, Node: Lvalues, Next: Conditionals, Prev: Typeof, Up: C Extensions |
| |
| Generalized Lvalues |
| =================== |
| |
| Compound expressions, conditional expressions and casts are allowed |
| as lvalues provided their operands are lvalues. This means that you |
| can take their addresses or store values into them. |
| |
| Standard C++ allows compound expressions and conditional expressions |
| as lvalues, and permits casts to reference type, so use of this |
| extension is deprecated for C++ code. |
| |
| For example, a compound expression can be assigned, provided the last |
| expression in the sequence is an lvalue. These two expressions are |
| equivalent: |
| |
| (a, b) += 5 |
| a, (b += 5) |
| |
| Similarly, the address of the compound expression can be taken. |
| These two expressions are equivalent: |
| |
| &(a, b) |
| a, &b |
| |
| A conditional expression is a valid lvalue if its type is not void |
| and the true and false branches are both valid lvalues. For example, |
| these two expressions are equivalent: |
| |
| (a ? b : c) = 5 |
| (a ? b = 5 : (c = 5)) |
| |
| A cast is a valid lvalue if its operand is an lvalue. A simple |
| assignment whose left-hand side is a cast works by converting the |
| right-hand side first to the specified type, then to the type of the |
| inner left-hand side expression. After this is stored, the value is |
| converted back to the specified type to become the value of the |
| assignment. Thus, if `a' has type `char *', the following two |
| expressions are equivalent: |
| |
| (int)a = 5 |
| (int)(a = (char *)(int)5) |
| |
| An assignment-with-arithmetic operation such as `+=' applied to a |
| cast performs the arithmetic using the type resulting from the cast, |
| and then continues as in the previous case. Therefore, these two |
| expressions are equivalent: |
| |
| (int)a += 5 |
| (int)(a = (char *)(int) ((int)a + 5)) |
| |
| You cannot take the address of an lvalue cast, because the use of its |
| address would not work out coherently. Suppose that `&(int)f' were |
| permitted, where `f' has type `float'. Then the following statement |
| would try to store an integer bit-pattern where a floating point number |
| belongs: |
| |
| *&(int)f = 1; |
| |
| This is quite different from what `(int)f = 1' would do--that would |
| convert 1 to floating point and store it. Rather than cause this |
| inconsistency, we think it is better to prohibit use of `&' on a cast. |
| |
| If you really do want an `int *' pointer with the address of `f', |
| you can simply write `(int *)&f'. |
| |
| |
| File: gcc.info, Node: Conditionals, Next: Long Long, Prev: Lvalues, Up: C Extensions |
| |
| Conditionals with Omitted Operands |
| ================================== |
| |
| The middle operand in a conditional expression may be omitted. Then |
| if the first operand is nonzero, its value is the value of the |
| conditional expression. |
| |
| Therefore, the expression |
| |
| x ? : y |
| |
| has the value of `x' if that is nonzero; otherwise, the value of `y'. |
| |
| This example is perfectly equivalent to |
| |
| x ? x : y |
| |
| In this simple case, the ability to omit the middle operand is not |
| especially useful. When it becomes useful is when the first operand |
| does, or may (if it is a macro argument), contain a side effect. Then |
| repeating the operand in the middle would perform the side effect |
| twice. Omitting the middle operand uses the value already computed |
| without the undesirable effects of recomputing it. |
| |
| |
| File: gcc.info, Node: Long Long, Next: Complex, Prev: Conditionals, Up: C Extensions |
| |
| Double-Word Integers |
| ==================== |
| |
| GNU C supports data types for integers that are twice as long as |
| `int'. Simply write `long long int' for a signed integer, or `unsigned |
| long long int' for an unsigned integer. To make an integer constant of |
| type `long long int', add the suffix `LL' to the integer. To make an |
| integer constant of type `unsigned long long int', add the suffix `ULL' |
| to the integer. |
| |
| You can use these types in arithmetic like any other integer types. |
| Addition, subtraction, and bitwise boolean operations on these types |
| are open-coded on all types of machines. Multiplication is open-coded |
| if the machine supports fullword-to-doubleword a widening multiply |
| instruction. Division and shifts are open-coded only on machines that |
| provide special support. The operations that are not open-coded use |
| special library routines that come with GNU CC. |
| |
| There may be pitfalls when you use `long long' types for function |
| arguments, unless you declare function prototypes. If a function |
| expects type `int' for its argument, and you pass a value of type `long |
| long int', confusion will result because the caller and the subroutine |
| will disagree about the number of bytes for the argument. Likewise, if |
| the function expects `long long int' and you pass `int'. The best way |
| to avoid such problems is to use prototypes. |
| |
| |
| File: gcc.info, Node: Complex, Next: Zero Length, Prev: Long Long, Up: C Extensions |
| |
| Complex Numbers |
| =============== |
| |
| GNU C supports complex data types. You can declare both complex |
| integer types and complex floating types, using the keyword |
| `__complex__'. |
| |
| For example, `__complex__ double x;' declares `x' as a variable |
| whose real part and imaginary part are both of type `double'. |
| `__complex__ short int y;' declares `y' to have real and imaginary |
| parts of type `short int'; this is not likely to be useful, but it |
| shows that the set of complex types is complete. |
| |
| To write a constant with a complex data type, use the suffix `i' or |
| `j' (either one; they are equivalent). For example, `2.5fi' has type |
| `__complex__ float' and `3i' has type `__complex__ int'. Such a |
| constant always has a pure imaginary value, but you can form any |
| complex value you like by adding one to a real constant. |
| |
| To extract the real part of a complex-valued expression EXP, write |
| `__real__ EXP'. Likewise, use `__imag__' to extract the imaginary part. |
| |
| The operator `~' performs complex conjugation when used on a value |
| with a complex type. |
| |
| GNU CC can allocate complex automatic variables in a noncontiguous |
| fashion; it's even possible for the real part to be in a register while |
| the imaginary part is on the stack (or vice-versa). None of the |
| supported debugging info formats has a way to represent noncontiguous |
| allocation like this, so GNU CC describes a noncontiguous complex |
| variable as if it were two separate variables of noncomplex type. If |
| the variable's actual name is `foo', the two fictitious variables are |
| named `foo$real' and `foo$imag'. You can examine and set these two |
| fictitious variables with your debugger. |
| |
| A future version of GDB will know how to recognize such pairs and |
| treat them as a single variable with a complex type. |
| |
| |
| File: gcc.info, Node: Zero Length, Next: Variable Length, Prev: Complex, Up: C Extensions |
| |
| Arrays of Length Zero |
| ===================== |
| |
| Zero-length arrays are allowed in GNU C. They are very useful as |
| the last element of a structure which is really a header for a |
| variable-length object: |
| |
| struct line { |
| int length; |
| char contents[0]; |
| }; |
| |
| { |
| struct line *thisline = (struct line *) |
| malloc (sizeof (struct line) + this_length); |
| thisline->length = this_length; |
| } |
| |
| In standard C, you would have to give `contents' a length of 1, which |
| means either you waste space or complicate the argument to `malloc'. |
| |