gcc.1

早期freebsd实现

\&\|' except that the macro arguments and contents are omitted.
Only `\|\c
.B #define \c
.I name\c
\&\c
\&\|' is included in the output.
.PP

.SH LINKER OPTIONS
These options come into play when the compiler links object files into
an executable output file.  They are meaningless if the compiler is
not doing a link step.
.TP
.I object-file-name
A file name that does not end in a special recognized suffix is
considered to name an object file or library.  (Object files are
distinguished from libraries by the linker according to the file
contents.)  If GCC does a link step, these object files are used as input
to the linker.
.TP
.BI \-l library\c
\&
Use the library named \c
.I library\c
\& when linking.

The linker searches a standard list of directories for the library,
which is actually a file named `\|\c
.B lib\c
.I library\c
\&.a\c
\&\|'.  The linker
then 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 `\|\c
.B \-L\c
\&\|'.

Normally the files found this way are library files\(em\&archive files
whose members are object files.  The linker handles an archive file by
scanning through it for members which define symbols that have so far
been referenced but not defined.  However, if the linker finds an
ordinary object file rather than a library, the object file is linked
in the usual fashion.  The only difference between using an `\|\c
.B \-l\c
\&\|' option and specifying a file
name is that `\|\c
.B \-l\c
\&\|' surrounds 
.I library
with `\|\c
.B lib\c
\&\|' and `\|\c
.B .a\c
\&\|' and searches several directories.
.TP
.B \-nostdlib
Don't use the standard system libraries and startup files when linking.
Only the files you specify will be passed to the linker.
.TP
.B \-static
On systems that support dynamic linking, this prevents linking with the shared
libraries.  On other systems, this option has no effect.
.PP

.SH DIRECTORY OPTIONS
These options specify directories to search for header files, for
libraries and for parts of the compiler:
.TP
.BI "\-I" "dir"\c
\&
Append directory \c
.I dir\c
\& to the list of directories searched for include files.
.TP
.B \-I\-
Any directories you specify with `\|\c
.B \-I\c
\&\|' options before the `\|\c
.B \-I\-\c
\&\|'
option are searched only for the case of `\|\c
.B 
#include "\c
.I file\c
.B
\&"\c
\&\|';
they are not searched for `\|\c
.B #include <\c
.I file\c
\&>\c
\&\|'.

If additional directories are specified with `\|\c
.B \-I\c
\&\|' options after
the `\|\c
.B \-I\-\c
\&\|', these directories are searched for all `\|\c
.B #include\c
\&\|'
directives.  (Ordinarily \c
.I all\c
\& `\|\c
.B \-I\c
\&\|' directories are used
this way.)

In addition, the `\|\c
.B \-I\-\c
\&\|' option inhibits the use of the current
directory (where the current input file came from) as the first search
directory for `\|\c
.B 
#include "\c
.I file\c
.B
\&"\c
\&\|'.  There is no way to
override this effect of `\|\c
.B \-I\-\c
\&\|'.  With `\|\c
.B \-I.\c
\&\|' you can specify
searching the directory which was current when the compiler was
invoked.  That is not exactly the same as what the preprocessor does
by default, but it is often satisfactory.

`\|\c
.B \-I\-\c
\&\|' does not inhibit the use of the standard system directories
for header files.  Thus, `\|\c
.B \-I\-\c
\&\|' and `\|\c
.B \-nostdinc\c
\&\|' are
independent.
.TP
.BI "\-L" "dir"\c
\&
Add directory \c
.I dir\c
\& to the list of directories to be searched
for `\|\c
.B \-l\c
\&\|'.
.TP
.BI "\-B" "prefix"\c
\&
This option specifies where to find the executables, libraries and
data files of the compiler itself.

The compiler driver program runs one or more of the subprograms
`\|\c
.B cpp\c
\&\|', `\|\c
.B cc1\c
\&\|' (or, for C++, `\|\c
.B cc1plus\c
\&\|'), `\|\c
.B as\c
\&\|' and `\|\c
.B ld\c
\&\|'.  It tries
\c
.I prefix\c
\& as a prefix for each program it tries to run, both with and
without `\|\c
.B \c
.I machine\c
\&/\c
.I version\c
\&/\c
\&\|'.

For each subprogram to be run, the compiler driver first tries the
`\|\c
.B \-B\c
\&\|' prefix, if any.  If that name is not found, or if `\|\c
.B \-B\c
\&\|'
was not specified, the driver tries two standard prefixes, which are
`\|\c
.B /usr/lib/gcc/\c
\&\|' and `\|\c
.B /usr/local/lib/gcc-lib/\c
\&\|'.  If neither of
those results in a file name that is found, the compiler driver
searches for the unmodified program
name, using the directories specified in your
`\|\c
.B PATH\c
\&\|' environment variable.

The run-time support file `\|\c
.B libgcc.a\c
\&\|' is also searched for using the
`\|\c
.B \-B\c
\&\|' prefix, if needed.  If it is not found there, the two
standard prefixes above are tried, and that is all.  The file is left
out of the link if it is not found by those means.  Most of the time,
on most machines, `\|\c
.B libgcc.a\c
\&\|' is not actually necessary.

You can get a similar result from the environment variable
\c
.B GCC_EXEC_PREFIX\c
\&; if it is defined, its value is used as a prefix
in the same way.  If both the `\|\c
.B \-B\c
\&\|' option and the
\c
.B GCC_EXEC_PREFIX\c
\& variable are present, the `\|\c
.B \-B\c
\&\|' option is
used first and the environment variable value second.
.PP

.SH WARNING OPTIONS
Warnings are diagnostic messages that report constructions which
are not inherently erroneous but which are risky or suggest there
may have been an error.

These options control the amount and kinds of warnings produced by GNU
CC:
.TP
.B \-fsyntax\-only
Check the code for syntax errors, but don't emit any output.
.TP
.B \-w
Inhibit all warning messages.
.TP
.B \-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 `\|\c
.B \-ansi\c
\&\|').  However,
without this option, certain GNU extensions and traditional C features
are supported as well.  With this option, they are rejected.  There is
no reason to \c
.I use\c
\& this option; it exists only to satisfy pedants.

`\|\c
.B \-pedantic\c
\&\|' does not cause warning messages for use of the
alternate keywords whose names begin and end with `\|\c
.B __\c
\&\|'.  Pedantic
warnings are also disabled in the expression that follows
\c
.B __extension__\c
\&.  However, only system header files should use
these escape routes; application programs should avoid them.
.TP
.B \-pedantic\-errors
Like `\|\c
.B \-pedantic\c
\&\|', except that errors are produced rather than
warnings.
.TP
.B \-W
Print extra warning messages for these events:
.TP
\ \ \ \(bu
A nonvolatile automatic variable might be changed by a call to
\c
.B longjmp\c
\&.  These warnings are possible only in
optimizing compilation.

The compiler sees only the calls to \c
.B setjmp\c
\&.  It cannot know
where \c
.B longjmp\c
\& will be called; in fact, a signal handler could
call it at any point in the code.  As a result, you may get a warning
even when there is in fact no problem because \c
.B longjmp\c
\& cannot
in fact be called at the place which would cause a problem.
.TP
\ \ \ \(bu
A function can return either with or without a value.  (Falling
off the end of the function body is considered returning without
a value.)  For example, this function would evoke such a
warning:
.sp
.br
foo\ (a)
.br
{
.br
\ \ if\ (a\ >\ 0)
.br
\ \ \ \ return\ a;
.br
}
.br
.sp

Spurious warnings can occur because GNU CC does not realize that
certain functions (including \c
.B abort\c
\& and \c
.B longjmp\c
\&)
will never return.
.TP
\ \ \ \(bu
An expression-statement contains no side effects.
.TP
\ \ \ \(bu
An unsigned value is compared against zero with `\|\c
.B >\c
\&\|' or `\|\c
.B <=\c
\&\|'.
.PP
.TP
.B \-Wimplicit
Warn whenever a function or parameter is implicitly declared.
.TP
.B \-Wreturn\-type
Warn whenever a function is defined with a return-type that defaults
to \c
.B int\c
\&.  Also warn about any \c
.B return\c
\& statement with no
return-value in a function whose return-type is not \c
.B void\c
\&.
.TP
.B \-Wunused
Warn whenever a local variable is unused aside from its declaration,
whenever a function is declared static but never defined, and whenever
a statement computes a result that is explicitly not used.
.TP
.B \-Wswitch
Warn whenever a \c
.B switch\c
\& statement has an index of enumeral type
and lacks a \c
.B case\c
\& for one or more of the named codes of that
enumeration.  (The presence of a \c
.B default\c
\& label prevents this
warning.)  \c
.B case\c
\& labels outside the enumeration range also
provoke warnings when this option is used.
.TP
.B \-Wcomment
Warn whenever a comment-start sequence `\|\c
.B /*\c
\&\|' appears in a comment.
.TP
.B \-Wtrigraphs
Warn if any trigraphs are encountered (assuming they are enabled).
.TP
.B \-Wformat
Check calls to \c
.B printf\c
\& and \c
.B scanf\c
\&, etc., to make sure that
the arguments supplied have types appropriate to the format string
specified.
.TP
.B \-Wuninitialized
An automatic variable is used without first being initialized.

These warnings are possible only in optimizing compilation,
because they require data flow information that is computed only
when optimizing.  If you don't specify `\|\c
.B \-O\c
\&\|', you simply won't
get these warnings.

These warnings occur only for variables that are candidates for
register allocation.  Therefore, they do not occur for a variable that
is declared \c
.B volatile\c
\&, or whose address is taken, or whose size
is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
structures, unions or arrays, even when they are in registers.

Note that there may be no warning about a variable that is used only
to compute a value that itself is never used, because such
computations may be deleted by data flow analysis before the warnings
are printed.

These warnings are made optional because GNU CC is not smart
enough to see all the reasons why the code might be correct
despite appearing to have an error.  Here is one example of how
this can happen:

.sp
.br
{
.br
\ \ int\ x;
.br
\ \ switch\ (y)
.br
\ \ \ \ {
.br
\ \ \ \ case\ 1:\ x\ =\ 1;
.br
\ \ \ \ \ \ break;
.br
\ \ \ \ case\ 2:\ x\ =\ 4;
.br
\ \ \ \ \ \ break;
.br
\ \ \ \ case\ 3:\ x\ =\ 5;
.br
\ \ \ \ }
.br
\ \ foo\ (x);
.br
}
.br
.sp


If the value of \c
.B y\c
\& is always 1, 2 or 3, then \c
.B x\c
\& is
always initialized, but GNU CC doesn't know this.  Here is
another common case:

.sp
.br
{
.br
\ \ int\ save_y;
.br
\ \ if\ (change_y)\ save_y\ =\ y,\ y\ =\ new_y;
.br
\ \ .\|.\|.
.br
\ \ if\ (change_y)\ y\ =\ save_y;
.br
}
.br
.sp


This has no bug because \c
.B save_y\c
\& is used only if it is set.

Some spurious warnings can be avoided if you declare as
\c
.B volatile\c
\& all the functions you use that never return.
.TP
.B \-Wparentheses
Warn if parentheses are omitted in certain contexts.
.TP
.B \-Wall
All of the above `\|\c
.B \-W\c
\&\|' options combined.  These are all the
options which pertain to usage that we recommend avoiding and that we
believe are easy to avoid, even in conjunction with macros.
.PP

The remaining `\|\c
.B \-W.\|.\|.\c
\&\|' options are not implied by `\|\c
.B \-Wall\c
\&\|'
because they warn about constructions that we consider reasonable to
use, on occasion, in clean programs.
.TP
.B \-Wtraditional
Warn about certain constructs that behave differently in traditional and
ANSI C.
.TP
\ \ \ \(bu
Macro arguments occurring within string constants in the macro body.
These would substitute the argument in traditional C, but are part of
the constant in ANSI C.
.TP
\ \ \ \(bu
A function declared external in one block and then used after the end of
the block.
.TP
\ \ \ \(bu
A \c
.B switch\c
\& statement has an operand of type \c
.B long\c
\&.
.PP
.TP
.B \-Wshadow
Warn whenever a local variable shadows another local variable.
.TP
.BI "\-Wid\-clash\-" "len"\c
\&
Warn whenever two distinct identifiers match in the first \c
.I len\c
\&
characters.  This may help you prepare a program that will compile
with certain obsolete, brain-damaged compilers.
.TP
.B \-Wpointer\-arith
Warn about anything that depends on the ``size of'' a function type or
of \c
.B void\c
\&.  GNU C assigns these types a size of 1, for
convenience in calculations with \c
.B void *\c
\& pointers and pointers
to functions.
.TP
.B \-Wcast\-qual
Warn whenever a pointer is cast so as to remove a type qualifier from
the target type.  For example, warn if a \c
.B const char *\c
\& is cast
to an ordinary \c
.B char *\c
\&.
.TP
.B \-Wcast\-align
Warn whenever a pointer is cast such that the required alignment of the
target is increased.  For example, warn if a \c
.B char *\c
\& is cast to
an \c
.B int *\c
\& on machines where integers can only be accessed at
two- or four-byte boundaries.
.TP
.B \-Wwrite\-strings
Give string constants the type \c