gcc(1) SDK R4.11 gcc(1)
NAME
gcc - GNU C language compiler
SYNOPSIS
/bin/gcc [ option ] ... file ...
DESCRIPTION
The GNU C compiler uses a command syntax much like the Unix C
compiler. The gcc command accepts options and file names as
operands. Multiple single-letter options may not be grouped: `-dr'
is very different from `-d -r'. When you invoke gcc, it normally
does preprocessing, compilation, assembly and linking. File names
that end in .c are taken as C source to be preprocessed and compiled;
compiler output files plus any input files with names ending in .s
are assembled; then the resulting object files, plus any other input
files, are linked together to produce an executable. Command options
allow you to stop this process at an intermediate stage. For
example, the -c option says not to run the link editor. Then the
output consists of object files output by the assembler. Other
command options are passed on to one stage. Some options control the
preprocessor and others the compiler itself.
Many options have long names starting with -f or with -W: for
example, -fforce-mem, -fstrength-reduce, -Wformat and so on. Most of
these have both positive and negative forms: for example, the
negative form of -finline would be -fno-inline. Both the positive
and negative forms are documented below. If conflicting options are
specified on a command line, then the last conflicting option has
precedence.
For additional information, use the info gcc command to access the
on-line documentation for gcc.
Commonly Used Options
-c Compile or assemble the source files, but do not link. Produce
object files with names made by replacing .c or .s with .o at the
end of the input file names. Do nothing at all for object files
specified as input.
-S Compile into assembler code but do not assemble. The assembler
output file name is made by replacing .c with .s at the end of
the input file name. Do nothing at all for assembler source
files or object files specified as input.
-E Run only the C preprocessor. Preprocess all the C source files
specified and output the results to standard output.
-o file
Place output in file file. This applies to any output being
produced, whether it be an executable file, an object file, an
assembler file or preprocessed C code. If -o is not specified,
the default is to put an executable file in a.out, the object
file for source.c in source.o, an assembler file in source.s, and
preprocessed C on standard output.
-ansi
Support all ANSI standard C programs. This turns off certain
features of GNU C that are incompatible with ANSI C, such as the
asm, inline and typeof keywords, and predefined macros such as
unix that identify the type of system you are using. It also
enables the rarely-used ANSI trigraph feature.
The alternate keywords asm, inline and typeof
continue to work despite -ansi. You would not want to use them
in an ANSI C program, of course, but it useful to put them in
header files that might be included in compilations done with
-ansi. Alternate predefined macros such as unix are also
available, with or without -ansi.
The -ansi option does not cause non-ANSI programs to be rejected
gratuitously. For that, -pedantic is required in addition to
-ansi. The macro STRICTANSI is predefined when the -ansi
option is used. Some header files may notice this macro and
refrain from declaring certain functions or defining certain
macros that the ANSI standard doesn't call for; this is to avoid
interfering with any programs that might use these names for
other things.
-traditional
Attempt to support some aspects of traditional C compilers.
Specifically:
* All extern declarations take effect globally even if they are
written inside a function definition. This includes implicit
declarations of functions.
* The keywords typeof, inline, signed, const and volatile are
not recognized. (You can still use the alternative keywords
such as typeof, inline, and so on.)
* Comparisons between pointers and integers are always allowed.
* Integer types unsigned short and unsigned char promote to
unsigned int.
* Out-of-range floating point literals are not an error.
* String ``constants'' are not necessarily constant; they are
stored in writable space, and identical looking constants are
allocated separately. (This is the same as the effect of
-fwritable-strings.)
* All automatic variables not declared register are preserved by
longjmp. Ordinarily, GNU C follows ANSI C: automatic
variables not declared volatile may be clobbered.
* In the preprocessor, comments convert to nothing at all,
rather than to a space. This allows traditional token
concatenation.
* In the preprocessor, macro arguments are recognized within
string constants in a macro definition (and their values are
stringified, though without additional quote marks, when they
appear in such a context). The preprocessor also considers a
string constant to end at a newline.
* The predefined macro STDC is not defined when you use
-traditional, but GNUC is (since the GNU extensions which
GNUC indicates are not affected by -traditional).
* The -Xt option is passed to the link editor.
-fwritable-strings
-fno-writable-strings
Store, or do not store, string constants in the writable data
segment and represent identical strings distinctly (don't share
storage). This is for compatibility with old programs which
assume they can write into string constants. -traditional also
has this effect. -fno-writable-strings is the default.
-w Inhibit all warning messages.
-pedantic
Issue all the warnings demanded by strict ANSI standard C; reject
all programs that use forbidden extensions. Valid ANSI standard
C programs should compile properly with or without this option
(though a rare few will require -ansi). However, without this
option, certain GNU extensions and traditional C features are
supported as well. With this option, they are rejected.
-pedantic does not cause warning messages for use of the
alternate keywords whose names begin and end with . Pedantic
warnings are also disabled in the expression that follows
extension. However, only system header files should use
these escape routes; application programs should avoid them.
-pedantic-errors
Like -pedantic, except that errors are produced rather than
warnings.
-Wall
Enable all warnings.
Options for Debugging Your Program
-g Produce debugging information for mxdb or dbx.
Unlike most other C compilers, GNU C allows you to use -g with -O.
The shortcuts taken by optimized code may occasionally produce
surprising results: some variables you declared may not exist at all;
flow of control may briefly move where you did not expect it; some
statements may not be executed because they compute constant results
or their values were already at hand; some statements may execute in
different places because they were moved out of loops. Nevertheless
it proves possible to debug optimized output. This makes it
reasonable to use the optimizer for programs that might have bugs.
Debugging information is in legend(5) format for all supported
debuggers. An optional LEGENDS environment variable can contain
special generation options such as -external to reduce link-time by
storing most debugging information in a separate file. See legend(5)
for details.
These five options control legend generation.
-mstandard
Causes the assembler to retain standard debugging information.
-mlegend
In the ELF environment, causes the assembler to invoke dtl(1),
the DWARF-to-legend translator. In a COFF environment, causes
the assembler to invoke ctl(1), the COFF-to-legend translator.
This is the default behaviour.
-mno-legend
Suppresses the creation of legend(5) format debugging information
described in -mlegend.
-mexternal-legend
Causes the assembler to pass the -external option to dtl(1) or
ctl(1).
-mkeep-coff
Causes the assembler to pass the -keep-std option to dtl(1) or
ctl(1).
-p Generate extra code to write profile information suitable for the
analysis program prof.
-Olevel
Optimize. Optimizing compilation takes somewhat more time, and a
lot more memory for a large function. The default value for
level is 1.
Without -Olevel, the compiler's goal is to reduce the cost of
compilation and to make debugging produce the expected results.
Statements are independent: if you stop the program with a
breakpoint between statements, you can then assign a new value to
any variable or change the program counter to any other statement
in the function and get exactly the results you would expect from
the source code. Without -Olevel, only variables declared
register are allocated in registers.
With -O1, the compiler tries to reduce code size and execution
time. The -O1 option turns on -fthread-jumps, -fdelayed-branch,
-fdefer-pop, and -fomit-frame-pointer.
With -O2, the compiler performs all supported optimizations that
do not involve a space-speed tradeoff. As compared to -O1, this
option will increase both compilation time and the performance of
the generated code. -O2 implies -fstrength-reduce,
-fthread-jumps, -fcse-follow-jumps, -frerun-cse-after-loop,
-fcse-skip-blocks, -fexpensive-optimizations, -fdelayed-branch,
-fschedule-insns, -fschedule-insns2, -fdefer-pop, and
-fomit-frame-pointer,
Options Controlling the Preprocessor
These options control the C preprocessor, which is run on each C
source file before actual compilation. If you use the -E option,
nothing is done except C preprocessing. Some of these options make
sense only together with -E because they request preprocessor output
that is not suitable for actual compilation.
-E Run only the C preprocessor. Preprocess all the C source files
specified and output the results to standard output.
-C Tell the preprocessor not to discard comments. Used with the -E
option.
-H Print the name of each header file to the standard error file, in
addition to the normal processing.
-Dmacro
Define macro macro with the string `1' as its definition.
-Dmacro=defn
Define macro macro as defn.
-Umacro
Undefine macro macro. Cause any definition of macro to be
forgotten, as if by the #undef preprocessor directive. If the
same name is specified for both -D and -U, macro is not defined,
regardless of the order of the options.
Options for Linking
-llibrary
Search a standard list of directories for a library named
library, which is actually a file named liblibrary.a. The link
editor uses this file as if it had been specified precisely by
name. The directories searched include several standard system
directories plus any that you specify with -L. Normally the
files found this way are library files--archive files whose
members are object files. The link editor handles an archive
file by scanning through it for members which define symbols that
have so far been referenced but not defined. But if the file
that is found is an ordinary object file, it is linked in the
usual fashion. The only difference between an -l option and
specifying a file name is that -l searches several directories.
-nostdlib
Don't use the standard system libraries and startup files when
linking. Only the files you specify will be passed to the link
editor.
-static
Produce a static object, that is an object which contains no
shared objects. This option causes -dn to be added to the link
line; see ld(1).
-shared
Produce a shared object. This option causes -G to be added to
the link line, to produce a shared object which can then be
linked with other objects to form an executable.
-symbolic
Bind references to global symbols when building a shared object.
Warn about any unresolved references (unless overridden by the
link editor option -z defs: see ld(1)). This option causes
-Bsymbolic -G to be added to the link line.
-Xlinker option
Pass option as an option to the linker. You can use this to
supply system-specific linker options which GNU CC does not know
how to recognize.
If you want to pass an option that takes an argument, you must
use -Xlinker twice, once for the option and once for the
argument. For example, to pass -assert definitions, you must
write -Xlinker -assert -Xlinker definitions. It does not work to
write -Xlinker "-assert definitions", because this passes the
entire string as a single argument, which is not what the linker
expects.
GNU C also passes the options -e, -h, -n, -r, -s, -t, -u, -x, and -z
to the link editor; see ld(1) for these options.
Options for Directory Search
-Idir
Search directory dir for include files.
-I- Any directories specified with -I options before the -I- option
are searched only for the case of `#include "file"'; they are not
searched for `#include <file>'. If additional directories are
specified with -I options after the -I-, these directories are
searched for all #include directives. (Ordinarily all -I
directories are used this way.) In addition, the -I- option
inhibits the use of the current directory as the first search
directory for `#include "file"'. (The current directory is the
directory of the current input file. It is tried first because
it is presumed to be the location of the files that the current
input file refers to.) Therefore, the current directory is
searched only if it is requested explicitly with `-I.'.
Specifying both `-I-' and `-I.' allows you to control precisely
which directories are searched before the current one and which
are searched after.
-Ldir
Add directory dir to the list of directories to be searched for
-l.
Options for Code Generation Conventions
-fpic, -fno-pic
Generate, or do not generate, position-independent code, suitable
for use in a shared object.
-fno-pic is the default.
-mserialize-volatile
-mno-serialize-volatile
Do, or don't, generate code to guarantee sequential consistency
of volatile memory references. By default, consistency is
guaranteed.
The order of memory references made by the MC88110 processor does
not always match the order of the instructions requesting those
references. In particular, a load instruction may execute before
a preceding store instruction. Such reordering violates
sequential consistency of volatile memory references, when there
are multiple processors. When consistency must be guaranteed,
GNU C generates special instructions, as needed, to force
execution in the proper order.
The MC88100 processor does not reorder memory references and so
always provides sequential consistency. However, by default, GNU
C generates the special instructions to guarantee consistency
even when you use -m88100, so that the code may be run on an
MC88110 processor. If you intend to run your code only on the
MC88100 processor, you may use -mno-serialize-volatile.
The extra code generated to guarantee consistency may affect the
performance of your application. If you know that you can safely
forgo this guarantee, you may use -mno-serialize-volatile.
Options for 88k Platform Code Generation Conventions
-m88000
-m88100
-m88110
Generate code that:
-m88000: runs well on all members of the 88000 family
-m88100: is optimized for MC88100, but also runs on MC88110
-m88110: is optimized for MC88110, and may not run on MC88100
-mshort-data-size
Specify the maximum size of a datum to be referenced with short
addressing. Short addressing will be used to reference a static
datum if its size is less than or equal to size bytes. For
example, specifying -mshort-data-512 requests short addressing
for data no larger than 512 bytes in size.
Short addressing generates more compact references to small
static data by pooling these data and referencing them relative
to one or more static base registers. Because the number of base
registers and the range for register-based addressing are
limited, linking can fail if there is too much short data. The
only recourse is recompilation with a smaller value for size.
For this reason, use of -mshort-data-size is discouraged for
software to be distributed in object form, such as libraries.
The default value for size is zero. That is, short addressing is
disabled by default.
-fPIC, -fno-PIC
Generate, or do not generate, position-independent code, as with
-fpic except that the resulting code will work correctly if the
global offset table of a shared object exceeds 16k. (Modules
should be recompiled with this option instead of -fpic when the
link editor reports the error ``Relocation overflows at
address...'' when producing a shared object.)
-fno-PIC is the default.
Environment Variables Affecting GNU C
Several environment variables affect the operation of GNU C. They
work by specifying directories or prefixes to use when searching for
various kinds of files. Note that you can also specify places to
search using options such as -B, -I and -L. These take precedence
over places specified using environment variables, which in turn take
precedence over those specified by the configuration of GNU C.
TMPDIR
If TMPDIR is set, it specifies the directory to use for temporary
files. GNU C uses temporary files to hold the output of one
stage of compilation which is to be used as input to the next
stage: for example, the output of the preprocessor, which is the
input to the compiler proper.
LIBRARYPATH
The value of LIBRARY_PATH is a colon-separated list of
directories, much like PATH. GNU C tries the directories thus
specified when searching for special linker files, if it can't
find them using GCC_EXEC_PREFIX. Linking using GNU C also uses
these directories when searching for ordinary libraries for the
-l option (but directories specified with -L come first).
There are several macros you can define to control your source and
target environments when developing applications. These macros
control header files, function declarations, binary formats, and
other aspects of the source and target environments. The macros are
helpful when you are porting applications to or from non-DG/UX
systems such as BSD or AT&T systems. The macros can also make
development of POSIX- or BCS-conformant applications easier. For
developing BCS-conformant applications, the SDE utility is also
helpful. See Porting Applications to the DG/UX (Trademark) System
and the sde-target(1), sdetab(4), and sde(5) manual pages.
FILES
file.c input file
file.o object file
a.out loaded output
TMPDIR/cc* temporary files. TMPDIR is usually /usr/tmp
but can be redefined by setting the
environment variable TMPDIR.
/usr/lib/gcc/gcc-cpp preprocessor
/usr/lib/gcc/gcc-cc1 compiler
/usr/lib/gcc/gcc-gnulib library needed by gcc
/lib/crt*.o runtime startup routines
/lib/libc.a standard library, see intro(3)
/usr/include standard directory for #include files
SEE ALSO
as(1), cc(1), ctl(1), dtl(1), info(1), ld(1), sde-target(1),
sdetab(4), sde(5), legend(5).
COPYING
Copyright (c) 1988-1995 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of the
gcc(1) manual page provided the copyright notice and this permission
notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of the
gcc(1) manual page under the conditions for verbatim copying,
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 the
gcc(1) manual page into another language, under the above conditions
for modified versions, except that this permission notice may be
included in translations approved by the Free Software Foundation
instead of in the original English.
Licensed material--property of copyright holder(s)