\input texinfo  @c -*- texinfo -*-
@comment %**start of header
@settitle GCC for the Atari ST
@setfilename gcc-st
@comment %**end of header

@iftex
@finalout
@end iftex

@ifinfo
This file documents the usage of the GNU C compiler on the Atari ST
and contains material from other copyrighted GNU manuals. The version of
the C compiler, on which this manual is based is currently 1.37.1.

Copyright (C) 1988, 1989, 1990 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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU CC General Public License'' is 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 section entitled ``GNU CC General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.
@end ifinfo

@titlepage
@sp 10
@center @titlefont{GCC for the Atari ST}
@sp 3
@center Using the GNU C-Compiler on the Atari ST
@sp 1
@center by Frank Ridderbusch
@sp 2
@center 1. Draft March 9, 1990

@page
@vskip 0pt plus 1fill
Copyright @copyright{}  1988, 1989, 1990 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
section entitled ``GNU CC General Public License'' is 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 section entitled ``GNU CC General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.
@end titlepage
@page

@ifinfo
@node     Top,        Copying, (dir),     (dir)
@comment  node-name,  next,    previous,  up
@ichapter Introduction

This manual documents how to install and run the GNU C compiler on
the Atari ST. 

@end ifinfo
@menu
* Copying::             GNU CC General Public License says
                         how you can copy and share GNU CC.
* Contributors::        People who have contributed to GNU CC
                         and to the port for the Atari ST.
* Installing GCC::      How to install GCC on your Atari ST.
* The Compiler Driver:: Command options supported by @samp{gcc.ttp}.
* The Preprocessor::    Command options and predefined macros supported
                        by @samp{gcc-cpp.ttp}.
* The Assembler::       Command options supported by @samp{gcc-as.ttp}.
* The Utilities::       How to use the support programs like @samp{gcc-ld.ttp},
                         @samp{gcc-ar.ttp}, @samp{sym-ld.ttp} etc.

* Memory Requirements::

* Concept Index::
* Command Options::
@end menu

@node     Copying,    Contributors, Top,       Top
@comment  node-name,  next,         previous,  up
@unnumbered GNU CC GENERAL PUBLIC LICENSE
@center (Clarified 11 Feb 1988)

  The license agreements of most software companies keep you at the
mercy of those companies.  By contrast, our general public license is
intended to give everyone the right to share GNU CC.  To make sure that
you get the rights we want you to have, we need to make restrictions
that forbid anyone to deny you these rights or to ask you to surrender
the rights.  Hence this license agreement.

  Specifically, we want to make sure that you have the right to give
away copies of GNU CC, that you receive source code or else can get it
if you want it, that you can change GNU CC or use pieces of it in new
free programs, and that you know you can do these things.

  To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of GNU CC, you must give the recipients all the rights that you
have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.

  Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for GNU CC.  If GNU CC is modified by
someone else and passed on, we want its recipients to know that what
they have is not what we distributed, so that any problems introduced
by others will not reflect on our reputation.

  Therefore we (Richard Stallman and the Free Software Foundation,
Inc.) make the following terms which say what you must do to be
allowed to distribute or change GNU CC.

@unnumberedsec COPYING POLICIES

@enumerate
@item
You may copy and distribute verbatim copies of GNU CC source code as
you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy a valid copyright notice
``Copyright @copyright{} 1988 Free Software Foundation, Inc.'' (or
with whatever year is appropriate); keep intact the notices on all
files that refer to this License Agreement and to the absence of any
warranty; and give any other recipients of the GNU CC program a copy
of this License Agreement along with the program.  You may charge a
distribution fee for the physical act of transferring a copy.

@item
You may modify your copy or copies of GNU CC or any portion of it,
and copy and distribute such modifications under the terms of
Paragraph 1 above, provided that you also do the following:

@itemize @bullet
@item
cause the modified files to carry prominent notices stating
that you changed the files and the date of any change; and

@item
cause the whole of any work that you distribute or publish, that
in whole or in part contains or is a derivative of GNU CC or any
part thereof, to be licensed at no charge to all third parties on
terms identical to those contained in this License Agreement
(except that you may choose to grant more extensive warranty
protection to some or all third parties, at your option).

@item
You may charge a distribution fee for the physical act of
transferring a copy, and you may at your option offer warranty
protection in exchange for a fee.
@end itemize

Mere aggregation of another unrelated program with this program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other program under the scope of these terms.

@item
You may copy and distribute GNU CC (or a portion or derivative of it,
under Paragraph 2) in object code or executable form under the terms
of Paragraphs 1 and 2 above provided that you also do one of the
following:

@itemize @bullet
@item
accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal
shipping charge) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with the information you received as to where the
corresponding source code may be obtained.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
@end itemize

For an executable file, complete source code means all the source code
for all modules it contains; but, as a special exception, it need not
include source code for modules which are standard libraries that
accompany the operating system on which the executable file runs.

@item
You may not copy, sublicense, distribute or transfer GNU CC except as
expressly provided under this License Agreement.  Any attempt
otherwise to copy, sublicense, distribute or transfer GNU CC is void
and your rights to use the program under this License agreement shall
be automatically terminated.  However, parties who have received
computer software programs from you with this License Agreement will
not have their licenses terminated so long as such parties remain in
full compliance.

@item
If you wish to incorporate parts of GNU CC into other free programs
whose distribution conditions are different, write to the Free Software
Foundation at 675 Mass Ave, Cambridge, MA 02139.  We have not yet worked
out a simple rule that can be stated here, but we will often permit
this.  We will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing and
reuse of software.
@end enumerate

Your comments and suggestions about our licensing policies and our
software are welcome!  Please contact the Free Software Foundation,
Inc., 675 Mass Ave, Cambridge, MA 02139, or call (617) 876-3296.

@unnumberedsec NO WARRANTY

  BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO
WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND
PERFORMANCE OF GNU CC IS WITH YOU.  SHOULD GNU CC PROVE DEFECTIVE, YOU
ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M.
STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY
WHO MAY MODIFY AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO
YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU CC, EVEN
IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR
ANY CLAIM BY ANY OTHER PARTY.

@node     Contributors, Installing GCC, Copying,   Top
@comment  node-name,    next,         previous,  up
@unnumbered Contributors to GNU CC

In addition to Richard Stallman, several people have written parts
of GNU CC.

@itemize @bullet
@item
The idea of using RTL and some of the optimization ideas came from the
U. of Arizona Portable Optimizer, written by Jack Davidson and
Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole
Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
857-866.

@item
Paul Rubin wrote most of the preprocessor.

@item
Leonard Tower wrote parts of the parser, RTL generator, RTL
definitions, and of the Vax machine description.

@item
Ted Lemon wrote parts of the RTL reader and printer.

@item
Jim Wilson implemented loop strength reduction and some other
loop optimizations.

@item
Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
the support for the SONY NEWS machine.

@item
Charles LaBrec contributed the support for the Integrated Solutions
68020 system.

@item
Michael Tiemann of MCC wrote most of the description of the National
Semiconductor 32000 series cpu.  He also wrote the code for inline
function integration and for the SPARC cpu and Motorola 88000 cpu
and part of the Sun FPA support.

@item
Jan Stein of the Chalmers Computer Society provided support for
Genix, as well as part of the 32000 machine description.

@item
Randy Smith finished the Sun FPA support.

@item
Robert Brown implemented the support for Encore 32000 systems.

@item
David Kashtan of SRI adapted GNU CC to the Vomit-Making System.

@item
Alex Crain provided changes for the 3b1.

@item
Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for
the 9000 series 300.

@item
William Schelter did most of the work on the Intel 80386 support.

@item
Christopher Smith did the port for Convex machines.

@item
Paul Petersen wrote the machine description for the Alliant FX/8.
@end itemize

The following people contributed specially to the version for the
Atari ST.

@itemize @bullet
@item
John R. Dunning did the original port to the Atari ST.

@item
Jwahar R. Bammi improved the port. Jwahar Bammi and Eric Smith put
together and maintain the current libraries. The Atari ST port has greatly
benefited from contributions and ideas of Edgar Roeder, Dale Schumacher,
Kai--Uwe Bloem, Allan Pratt, John Dunning, Henry Spencer and many 
enthusiastic users in the atari community.

@item
Frank Ridderbusch compiled the manual for the Atari ST.
@end itemize

@iftex
@node     Introduction, , , 
@unnumbered Introduction
@cindex Introduction

This manual documents how to install and run the GNU C compiler on the
Atari ST. It does not give an introduction in C or M68000 assembler.
There is enough material on both subjects available. The user, who is
familiar with a C compiler, that runs on a U**x system, should have no
trouble at all to get GNU C running on the Atari ST. This manual was
compiled from existing GNU manuals and various bits and pieces from John
R. Dunning and Jwahar R. Bammi. 

The sections, that describe the compiler driver and the preprocessor are
nearly verbatim copies of sections in the respective manuals. The
original manuals (@strong{Using and Porting GNU CC} and @strong{The C
Preprocessor}), were written by Richard M. Stallmann. I modified these
sections by removing material, which described features of GNU C for
systems like Vaxen or Suns. To keep this manual resonably compact, I
extracted only the sections, which describe the supported command
options (and predefined macros in case of the preprocessor). If the user
is interested in the extensions and details, which are implemented in
GNU C, he has to refer to the original manuals. Whether all described
options are usefull on the Atari has to be decided. 

The facts, which are presented in the assembler and utility sections are
mostly derived from the sources of the repective programs (from a cross
compiler kit by J. R. Bammi based on GNU C 1.31), which were available to
me. Other facts were gathered by try and error. So, these sections may
be a bit shaky.

Please send any comments, corrections, etc concering this manual to

@example
Snail:

Frank Ridderbusch
Sander Str. 17
4790 Paderborn, West Germany

Email:
BIX:  fridder
UUCP: !USA            ...!unido!nixpbe!ridderbusch.pad
       USA  uunet!philabs!linus!nixbur!ridderbusch.pad
@end example

@end iftex
@node     Installing GCC, Memory Requirements, Contributors, Top
@comment  node-name,      next,                previous,     up
@chapter Installing GCC
@cindex Installing GCC
@cindex Installation

The compressed archive of the GNU C compiler binary distribution
contains the 'common' executables of the GNU compiler. That means the
compiler driver (@file{gcc.ttp}), the preprocessor (@file{gcc-cpp.ttp}),
the main body (@file{gcc-cc1.ttp}), the assembler (@file{gcc-as.ttp})
and  the linker (@file{gcc-ld.ttp}). It also contains the following
support programs:@refill

@table @file
@item gcc-ar.ttp
is the object library maintainer.

@item gdb.ttp
is the GNU debugger modified for the Atari ST. John Dunning did the
port to the Atari.

@item sym-ld.ttp
creates the symbol file needed with gdb.

@item gcc-nm.ttp
prints the symbols of a GNU archive or object file.

@item cnm.ttp
prints the symbol table of a GEMDOS executable.

@item fixstk.ttp
@itemx printstk.ttp
are used to modify and print the current stack size of an
executable.

@item toglclr.ttp
TOS 1.4 users can toggle the clear above BSS to end of TPA flag
for the GEMDOS loader.

@item gnu.g
is a sample file for the GULAM PD shell.

@item COPYING
explains your rights and responsibilities as a GNU user.

@item readme
@itemx readme.st
are notes from Jwahar R. Bammi and John R. Dunning.
@end table
@cindex Installing the Executables

All the executables should go in @samp{\gnu\bin\} on your gnu disk, or where
ever the environment variable @code{GCCEXEC} will point at. The executables
assume that you're running an approprate shell, one that will pass
command line arguements using either the Mark Williams or Atari conventions.
Gulam and Master are two such shells, Gemini a
german alternate shareware desktop also works. Other CLI's may also
work. The compiler driver @file{gcc.ttp} should be in the search @code{PATH} of
your shell. The next step is to define @code{GCCEXEC}.
@file{gcc.ttp} uses this variable to locate the preprocessor, compiler,
assembler and the linker. @code{GCCEXEC} contains a
device/dir/partial-pathname. Assuming you also put the executables in
the directory @samp{c:\gnu\bin}, @code{GCCEXEC} would contain
@samp{c:\gnu\bin\gcc-}. The value is the same as you would specify in the
@samp{-B} option to the compiler driver.@refill
@cindex GCCEXEC

Then you should define a variable called @code{TEMP}. During compilation
the ouput of the various stages is kept here. The variable must
@strong{not} contain a trailing backslash. If you have enough memory,
@code{TEMP} should point to a ramdisk.@refill
@cindex TEMP

The next thing to do is to install the libraries. The distributed
archive contains the following libraries:@refill

@cindex Libraries
@table @file
@item README
The obvious.

@item crt0.o
is the startup module.

@item gcrt0.o
is the startup module for profiling runs. Automatically selected by the
compiler driver when you specify the @samp{-pg} option.

@item gnu.olb
@itemx gnu16.olb
are the standard libraries, the usual @samp{libc} on other systems.

@item curses.olb
@itemx curses16.olb
are ports of the BSD curses.

@item gem.olb
@itemx gem16.olb
contain the Atari ST Aes/Vdi bindings.

@item iio.olb
@itemx iio16.olb
contain the integer only @samp{printf} and @samp{scanf} functions.

@item pml.olb
@itemx pml16.olb
are the portable math libraries.

@item widget.olb
@itemx widget16.olb
are a small widget set based on @samp{curses}
@end table
@cindex Installing the Libraries

All these libraries go into a subdirectory described by the environment
variable @code{GNULIB}. Again this variable must @strong{not} contain a
trailing backslash. Staying with the above example, I've set the variable to
@samp{c:\gnu\lib}. The libraries, which have a 16 in their names were
compiled with the @samp{-mshort} option. This makes integers the same
size as shorts.@refill
@cindex GNULIB

The last bit to install are the header files. They are contained in an
archive of their own. The preprocessor now knows about the variable
@code{GNUINC}. Earlier version had to use the @samp{-I@var{prefix}}
option, to get to the header files. According to the above examples, the
files would be put in the directory @file{c:\gnu\include}. @code{GNUINC}
has to be set accordingly.@refill
@cindex Installing the Headerfiles
@cindex GNUINC

With earlier versions of GNU CC it was only allowed to put one path into
the variables @code{GNULIB} and @code{GNUINC}. GCC 1.37 allows you to
put several paths into these variables, which are separated by either a
@code{,} or a @code{;}. All the mentioned paths are searched in order to
locate a specific file. However the startup modules @file{crt0.o} or
@file{gcrt0.o} are
@strong{only} looked for in the first directory specified in
@code{GNULIB}. If the preprocessor can't find a include file in one of
the directories specified by @code{GNUINC}, it will also search the
paths listed in @code{GNULIB}.@refill

The programs, which come with the GCC distribution also understand
filenames, which use the slash (@samp{/}) as a separator. If Gulam
is your favorite CLI you will stick to the backslashes, since you
otherwise lose the feature of command line completition.@refill

If you are using Gulam, you can define @samp{aliases} to reach the
executables under more common names.@refill

@example
alias cc c:\gnu\bin\gcc.ttp
alias ar c:\gnu\bin\gcc-ar.ttp
alias as c:\gnu\bin\gcc-as.ttp
@dots{}
@end example

Now you should be able to say @samp{cc foo.c -o foo.ttp} and the obvious
things should happen. If you still have trouble, compare your settings
with the ones from the sample file @file{gulam.g}. That should give you
the rigth idea.@refill

One additional note to Gulam. @file{crt0.o} is currently set up to
understand the MWC convention of passing long command lines (execpt it
doesn't look into the @code{_io_vector} part). Gulam users should set
@samp{env_style mw}, if you want to give long args lines to
@file{gcc.ttp}.@refill

@node     Memory Requirements, The Compiler Driver, Installing GCC, Top
@comment  node-name,           next,                previous,       up
@unnumberedsec Memory Requirements
@cindex Memory Requirements
@cindex Requirements

GCC loves memory. A lot. It loves to cons structures. Lots of them.
All versions of GCC run in 1 Meg of memory, but to get compile any ``real''
programs atleast 2 Megs  are recommended. In versions before 1.37
the @file{gcc-cc1.ttp} had
1/2 meg stack, and needs it for compiling large files with optimization
turned on. Happily, it doesn't need all that stack for smaller files,
or even big files without the @samp{-O} option, so it should be feasible
to make a compiler with a smaller stack (with @file{fixstk.ttp}).@refill

GCC version 1.37 uses another scheme for memory allocation. The programs
@file{gcc-cpp.ttp} and @file{gcc-cc1.ttp} are setup for 
@code{_stksize == -1L}. This means, that an executable will use all 
available memory, doing mallocs from internal heap (as opposed to the
system heap via @code{Malloc}), with @code{SP} initially set at the top,
and heap starting just above the @code{BSS}. So if the compiler runs out
of memory, you probably need more memory (or get rid of accessories,
tsr's etc and try).

@node     The Compiler Driver, The Preprocessor, Memory Requirements, Top
@comment  node-name,           next,             previous,            up
@chapter Controlling the Compiler Driver
@cindex Compiler Driver
@cindex gcc.ttp

The GNU C compiler uses a command syntax much like the U**x C compiler.
The @file{gcc.ttp} program accepts options and file names as operands.
Multiple single-letter options may @emph{not} be grouped: @samp{-dr} is
very different from @samp{-d -r}.

When you invoke GNU CC, it normally does preprocessing, compilation,
assembly and linking. File names which end in @samp{.c} are taken as C
source to be preprocessed and compiled; file names ending in @samp{.i}
are taken as preprocessor output to be compiled; compiler output files
plus any input files with names ending in @samp{.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 @samp{-c} option says not to run the linker. Then the
output consists of object files output by the assembler.

Other command options are passed on to one stage of processing. Some
options control the preprocessor and others the compiler itself. Yet
other options control the assembler and linker; these are not documented
here, but you rarely need to use any of them.

Here are the options to control the overall compilation process, including
those that say whether to link, whether to assemble, and so on.

@table @samp
@cindex Options (gcc)
@item -o @var{file}
@findex o (gcc)
Place output in file @var{file}. This applies regardless to whatever
sort of output is being produced, whether it be an executable file,
an object file, an assembler file or preprocessed C code.

If @samp{-o} is not specified, the default is to put an executable file
in @file{a.out}, the object file @file{@var{source}.c} in
@file{@var{source}.o}, an assembler file in @file{@var{source}.s}, and
preprocessed C on standard output.@refill

@item -c
@findex c (gcc)
Compile or assemble the source files, but do not link. Produce object
files with names made by replacing @samp{.c} or @samp{.s} with
@samp{.o} at the end of the input file names. Do nothing at all for
object files specified as input.

@item -S
@findex S (gcc)
Compile into assembler code but do not assemble. The assembler output
file name is made by replacing @samp{.c} with @samp{.s} at the end of
the input file name.  Do nothing at all for assembler source files or
object files specified as input.

@item -E
@findex E (gcc)
Run only the C preprocessor. Preprocess all the C source files
specified and output the results to standard output.

@item -v
@findex v (gcc)
Compiler driver program prints the commands it executes as it runs
the preprocessor, compiler proper, assembler and linker. Some of
these are directed to print their own version numbers.

@item -s
@findex s (gcc)
The executable is stripped from the DRI compatible symbol table.
Certain symbolic debuggers like @file{sid.prg} work with this symbol
table. Also the programs @file{printstk.ttp} and @file{fixstk.ttp} (See
@pxref{The Utilities}, for more info) lookup the symbol @samp{_stksize}
in this table.

@item -B@var{prefix}
@findex B (gcc)
Compiler driver program tries @var{prefix} as a prefix for each
program it tries to run. These programs are @file{gcc-cpp.ttp},
@file{gcc-cc1.ttp}, @file{gcc-as.ttp} and @file{gcc-ld.ttp}.

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

The run-time support file @file{gnu.olb} is also searched for using
the @samp{-B} 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, you can do without it.

You can get a similar result from the environment variable
@code{GCCEXEC}. If it is defined, its value is used as a prefix
in the same way. If both the @samp{-B} option and the
@code{GCCEXEC} variable are present, the @samp{-B} option is
used first and the environment variable value second.@refill
@end table

These options control the details of C compilation itself.

@table @samp
@item -ansi
@findex ansi (gcc)
Support all ANSI standard C programs.

This turns off certain features of GNU C that are incompatible with
ANSI C, such as the @code{asm}, @code{inline} and @code{typeof}
keywords, and predefined macros such as @code{unix} and @code{vax}
that identify the type of system you are using. It also enables the
undesirable and rarely used ANSI trigraph feature.@refill

The @samp{-ansi} option does not cause non-ANSI programs to be
rejected gratuitously. For that, @samp{-pedantic} is required in
addition to @samp{-ansi}.

The macro @code{__STRICT_ANSI__} is predefined when the @samp{-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.

@item -traditional
@findex traditional (gcc)
Attempt to support some aspects of traditional C compilers.
Specifically:

@itemize @bullet
@item
All @code{extern} declarations take effect globally even if they
are written inside of a function definition.  This includes implicit
declarations of functions.

@item
The keywords @code{typeof}, @code{inline}, @code{signed}, @code{const}
and @code{volatile} are not recognized.@refill

@item
Comparisons between pointers and integers are always allowed.

@item
Integer types @code{unsigned short} and @code{unsigned char} promote
to @code{unsigned int}.

@item
Out-of-range floating point literals are not an error.

@item
All automatic variables not declared @code{register} are preserved by
@code{longjmp}. Ordinarily, GNU C follows ANSI C: automatic variables
not declared @code{volatile} may be clobbered.

@item
In the preprocessor, comments convert to nothing at all, rather than
to a space. This allows traditional token concatenation.

@item
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 always considers a string constant to end
at a newline.

@item
The predefined macro @code{__STDC__} is not defined when you use
@samp{-traditional}, but @code{__GNUC__} is (since the GNU extensions
which @code{__GNUC__} indicates are not affected by
@samp{-traditional}).  If you need to write header files that work
differently depending on whether @samp{-traditional} is in use, by
testing both of these predefined macros you can distinguish four
situations: GNU C, traditional GNU C, other ANSI C compilers, and
other old C compilers.
@end itemize

@item -O
@findex O (gcc)
Optimize. Optimizing compilation takes somewhat more time, and a lot
more memory for a large function.
Without @samp{-O}, 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 @samp{-O}, only variables declared @code{register} are
allocated in registers. The resulting compiled code is a little worse
than produced by PCC without @samp{-O}.

With @samp{-O}, the compiler tries to reduce code size and execution
time.Some of the @samp{-f} options described below turn specific kinds of
optimization on or off.

@item -g
@findex g (gcc)
Produce debugging information in the operating system's native format
(for DBX or SDB).  GDB also can work with this debugging information.

Unlike most other C compilers, GNU CC allows you to use @samp{-g} with
@samp{-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.

@item -gg
@findex gg (gcc)
Produce debugging information in GDB's own format. This requires the
GNU assembler and linker in order to work.

@item -w
@findex w (gcc)
Inhibit all warning messages.

@item -W
@findex W (gcc)
Print extra warning messages for these events:

@itemize @bullet
@item
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.  They occur only for variables that are
candidates for register allocation.  Therefore, they do not occur
for a variable that is declared @code{volatile}, 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 the flow analysis pass 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:

@example
@{
  int x;
  switch (y)
    @{
    case 1: x = 1;
      break;
    case 2: x = 4;
      break;
    case 3: x = 5;
    @}
  foo (x);
@}
@end example

@noindent
If the value of @code{y} is always 1, 2 or 3, then @code{x} is
always initialized, but GNU CC doesn't know this.  Here is
another common case:

@example
@{
  int save_y;
  if (change_y) save_y = y, y = new_y;
  @dots{}
  if (change_y) y = save_y;
@}
@end example

@noindent
This has no bug because @code{save_y} is used only if it is set.

Some spurious warnings can be avoided if you declare as
@code{volatile} all the functions you use that never return.
@c @xref{Function Attributes}.

@item
A nonvolatile automatic variable might be changed by a call to
@code{longjmp}.  These warnings as well are possible only in
optimizing compilation.

The compiler sees only the calls to @code{setjmp}.  It cannot know
where @code{longjmp} 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 @code{longjmp} cannot
in fact be called at the place which would cause a problem.

@item
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 inspire such a
warning:

@example
foo (a)
@{
  if (a > 0)
    return a;
@}
@end example

Spurious warnings can occur because GNU CC does not realize that
certain functions (including @code{abort} and @code{longjmp})
will never return.

@item
An expression-statement contains no side effects.
@end itemize

In the future, other useful warnings may also be enabled by this
option.

@item -Wimplicit
@findex Wimplicit (gcc)
Warn whenever a function is implicitly declared.

@item -Wreturn-type
@findex Wreturn-type (gcc)
Warn whenever a function is defined with a return-type that defaults
to @code{int}.  Also warn about any @code{return} statement with no
return-value in a function whose return-type is not @code{void}.

@item -Wunused
@findex Wunused (gcc)
Warn whenever a local variable is unused aside from its declaration,
and whenever a function is declared static but never defined.

@item -Wcomment
@findex Wcomment (gcc)
Warn whenever a comment-start sequence @samp{/*} appears in a comment.

@item -Wall
@findex Wall (gcc)
All of the above @samp{-W} options combined.

@item -Wwrite-strings
@findex Wwrite-strings (gcc)
Give string constants the type @code{const char[@var{length}]} so that
copying the address of one into a non-@code{const} @code{char *}
pointer will get a warning.  These warnings will help you find at
compile time code that can try to write into a string constant, but
only if you have been very careful about using @code{const} in
declarations and prototypes.  Otherwise, it will just be a nuisance;
this is why we did not make @samp{-Wall} request these warnings.

@item -p
@findex p (gcc)
Generate extra code to write profile information suitable for the
analysis program @code{prof}.

@item -pg
@findex pg (gcc)
Generate extra code to write profile information suitable for the
analysis program @code{gprof}.

@item -l@var{library}
@findex l (gcc)
Search a standard list of directories for a library named
@var{library}, which is actually a file named
@file{$GNULIB\@var{library}.olb}. The linker uses this file as if it
had been specified precisely by name.@refill

The directories searched include several standard system directories
plus any that you specify with @samp{-L}.

Normally the files found this way are library files---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.  But if the file that is found is an
ordinary object file, it is linked in the usual fashion.  The only
difference between using an @samp{-l} option and specifying a file name
is that @samp{-l} searches several directories.

@item -L@var{dir}
@findex L (gcc)
Add directory @var{dir} to the list of directories to be searched
for @samp{-l}.

@item -nostdlib
@findex nostdlib (gcc)
Don't use the standard system libraries and startup files when
linking. Only the files you specify (plus @file{gnulib}) will be
passed to the linker.

@item -m@var{machinespec}
@findex m (gcc)
Machine-dependent option specifying something about the type of target
machine. These options are defined by the macro
@code{TARGET_SWITCHES} in the machine description. The default for
the options is also defined by that macro, which enables you to change
the defaults.@refill

These are the @samp{-m} options defined in the 68000 machine
description:

@table @samp
@item -m68000
@item -mc68000
@findex m68000 (gcc)
@findex mc68000 (gcc)
Generate output for a 68000. This is the default on the Atari ST.

@item -m68020
@itemx -mc68020
@findex m68020 (gcc)
@findex mc68020 (gcc)
Generate output for a 68020 (rather than a 68000).

@item -m68881
@findex m68881 (gcc)
Generate output containing 68881 instructions for floating point.

@item -msoft-float
@findex msoft-float (gcc)
Generate output containing library calls for floating point. This is the
default on the Atari ST.

@item -mshort
@findex mshort (gcc)
Consider type @code{int} to be 16 bits wide, like @code{short int} and
causes the macro @code{__MSHORT__} to be defined. Using this option
also causes the library @file{@var{library}16.olb} to be linked. (Also
@pxref{Predefined Macros}, for more info)

@item -mnobitfield
@findex mnobitfield (gcc)
Do not use the bit-field instructions.  @samp{-m68000} implies
@samp{-mnobitfield}. This is the default on the Atari ST.

@item -mbitfield
@findex mbitfield (gcc)
Do use the bit-field instructions.  @samp{-m68020} implies
@samp{-mbitfield}.

@item -mrtd
@findex mrtd (gcc)
Use a different function-calling convention, in which functions
that take a fixed number of arguments return with the @code{rtd}
instruction, which pops their arguments while returning. This
saves one instruction in the caller since there is no need to pop
the arguments there.

This calling convention is incompatible with the one normally
used on U**x, so you cannot use it if you need to call libraries
compiled with the U**x compiler.

Also, you must provide function prototypes for all functions that
take variable numbers of arguments (including @code{printf});
otherwise incorrect code will be generated for calls to those
functions.

In addition, seriously incorrect code will result if you call a
function with too many arguments.  (Normally, extra arguments are
harmlessly ignored.)

The @code{rtd} instruction is supported by the 68010 and 68020
processors, but not by the 68000.
@end table

@item -f@var{flag}
Specify machine-independent flags.  Most flags have both positive and
negative forms; the negative form of @samp{-ffoo} would be
@samp{-fno-foo}.  In the table below, only one of the forms is
listed---the one which is not the default.  You can figure out the
other form by either removing @samp{no-} or adding it.

@table @samp
@item -ffloat-store
@findex ffloat-store (gcc)
Do not store floating-point variables in registers.  This
prevents undesirable excess precision on machines such as the
68000 where the floating registers (of the 68881) keep more
precision than a @code{double} is supposed to have.

For most programs, the excess precision does only good, but a few
programs rely on the precise definition of IEEE floating point.
Use @samp{-ffloat-store} for such programs.

@item -fno-asm
@findex fno-asm (gcc)
Do not recognize @code{asm}, @code{inline} or @code{typeof} as a
keyword.  These words may then be used as identifiers.

@item -fno-defer-pop
@findex fno-defer-pop (gcc)
Always pop the arguments to each function call as soon as that
function returns.  Normally the compiler (when optimizing) lets
arguments accumulate on the stack for several function calls and
pops them all at once.

@item -fstrength-reduce
@findex fstrength-reduce (gcc)
Perform the optimizations of loop strength reduction and
elimination of iteration variables.

@item -fcombine-regs
@findex fcombine-regs (gcc)
Allow the combine pass to combine an instruction that copies one
register into another. This might or might not produce better
code when used in addition to @samp{-O}. I am interested in
hearing about the difference this makes.

@item -fforce-mem
@findex fforce-mem (gcc)
Force memory operands to be copied into registers before doing
arithmetic on them.  This may produce better code by making all
memory references potential common subexpressions.  When they are
not common subexpressions, instruction combination should
eliminate the separate register-load.  I am interested in hearing
about the difference this makes.

@item -fforce-addr
@findex fforce-addr (gcc)
Force memory address constants to be copied into registers before
doing arithmetic on them. This may produce better code just as
@samp{-fforce-mem} may.

@item -fomit-frame-pointer
@findex fomit-frame-pointer (gcc)
Don't keep the frame pointer in a register for functions that
don't need one.  This avoids the instructions to save, set up and
restore frame pointers; it also makes an extra register available
in many functions. @strong{It also makes debugging impossible.}

On some machines, such as the Vax, this flag has no effect,
because the standard calling sequence automatically handles the
frame pointer and nothing is saved by pretending it doesn't
exist.  The machine-description macro
@code{FRAME_POINTER_REQUIRED} controls whether a target machine
supports this flag.@refill
@c @xref{Registers}.@refill

@item -finline-functions
@findex finline-functions (gcc)
Integrate all simple functions into their callers. The compiler
heuristically decides which functions are simple enough to be
worth integrating in this way.

If all calls to a given function are integrated, and the function
is declared @code{static}, then the function is normally not
output as assembler code in its own right.

@item -fkeep-inline-functions
@findex fkeep-inline-functions (gcc)
Even if all calls to a given function are integrated, and the
function is declared @code{static}, nevertheless output a
separate run-time callable version of the function.

@item -fwritable-strings
@findex fwritable-strings (gcc)
Store string constants in the writable data segment and don't
uniquize them.  This is for compatibility with old programs which
assume they can write into string constants. Writing into string
constants is a very bad idea; ``constants'' should be constant.

@item -fcond-mismatch
@findex fcond-mismatch (gcc)
Allow conditional expressions with mismatched types in the second and
third arguments. The value of such an expression is void.

@item -fno-function-cse
@findex fno-function-cse (gcc)
Do not put function addresses in registers; make each instruction
that calls a constant function contain the function's address
explicitly.

This option results in less efficient code, but some strange
hacks that alter the assembler output may be confused by the
optimizations performed when this option is not used.

@item -fvolatile
@findex fvolatile (gcc)
Consider all memory references through pointers to be volatile.

@item -fshared-data
@findex fshared-data (gcc)
Requests that the data and non-@code{const} variables of this
compilation be shared data rather than private data.  The distinction
makes sense only on certain operating systems, where shared data is
shared between processes running the same program, while private data
exists in one copy per process.

@item -funsigned-char
@findex funsigned-char (gcc)
Let the type @code{char} be the unsigned, like @code{unsigned char}.

Each kind of machine has a default for what @code{char} should
be. It is either like @code{unsigned char} by default or like
@code{signed char} by default.  (Actually, at present, the
default is always signed.)

The type @code{char} is always a distinct type from either
@code{signed char} or @code{unsigned char}, even though its
behavior is always just like one of those two.

Note that this is equivalent to @samp{-fno-signed-char}, which is the
negative form of @samp{-fsigned-char}.

@item -fsigned-char
@findex fsigned-char (gcc)
Let the type @code{char} be signed, like @code{signed char}.

Note that this is equivalent to @samp{-fno-unsigned-char}, which is
the negative form of @samp{-funsigned-char}.

@item -ffixed-@var{reg}
@findex ffixed- (gcc)
Treat the register named @var{reg} as a fixed register; generated
code should never refer to it (except perhaps as a stack pointer,
frame pointer or in some other fixed role).

@var{reg} must be the name of a register. The register names
accepted are machine-specific and are defined in the
@code{REGISTER_NAMES} macro in the machine description macro
file.

This flag does not have a negative form, because it specifies a
three-way choice.

@item -fcall-used-@var{reg}
@findex fcall-used- (gcc)
Treat the register named @var{reg} as an allocatable register
that is clobbered by function calls.  It may be allocated for
temporaries or variables that do not live across a call.
Functions compiled this way will not save and restore the
register @var{reg}.

Use of this flag for a register that has a fixed pervasive role
in the machine's execution model, such as the stack pointer or
frame pointer, will produce disastrous results.

This flag does not have a negative form, because it specifies a
three-way choice.

@item -fcall-saved-@var{reg}
@findex fcall-saved- (gcc)
Treat the register named @var{reg} as an allocatable register
saved by functions. It may be allocated even for temporaries or
variables that live across a call. Functions compiled this way
will save and restore the register @var{reg} if they use it.

Use of this flag for a register that has a fixed pervasive role
in the machine's execution model, such as the stack pointer or
frame pointer, will produce disastrous results.

A different sort of disaster will result from the use of this
flag for a register in which function values may be returned.

This flag does not have a negative form, because it specifies a
three-way choice.
@end table

@item -pedantic
@findex pedantic (gcc)
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 @samp{-ansi}). 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 @i{use} this option; it exists only to satisfy pedants.
@end table

These options control the C preprocessor, which is run on each C source
file before actual compilation. If you use the @samp{-E} option, nothing
is done except C preprocessing. Some of these options make sense only
together with @samp{-E} because they request preprocessor output that is
not suitable for actual compilation.

@table @samp
@item -C
@findex C (gcc)
Tell the preprocessor not to discard comments. Used with the
@samp{-E} option.

@item -I@var{dir}
@findex I (gcc)
Search directory @var{dir} for include files.

@item -I-
Any directories specified with @samp{-I} options before the @samp{-I-}
option are searched only for the case of @samp{#include "@var{file}"};
they are not searched for @samp{#include <@var{file}>}.

If additional directories are specified with @samp{-I} options after
the @samp{-I-}, these directories are searched for all @samp{#include}
directives. (Ordinarily @emph{all} @samp{-I} directories are used
this way.)

In addition, the @samp{-I-} option inhibits the use of the current
directory as the first search directory for @samp{#include
"@var{file}"}. Therefore, the current directory is searched only if
it is requested explicitly with @samp{-I.}. Specifying both
@samp{-I-} and @samp{-I.} allows you to control precisely which
directories are searched before the current one and which are searched
after.@refill

@item -nostdinc
@findex nostdinc (gcc)
Do not search the standard system directories for header files.  Only
the directories you have specified with @samp{-I} options (and the
current directory, if appropriate) are searched.

Between @samp{-nostdinc} and @samp{-I-}, you can eliminate all
directories from the search path except those you specify.

@item -M
@findex M (gcc)
Tell the preprocessor to output a rule suitable for @code{make}
describing the dependencies of each source file.  For each source
file, the preprocessor outputs one @code{make}-rule whose target is
the object file name for that source file and whose dependencies are
all the files @samp{#include}d in it. This rule may be a single line
or may be continued with @samp{\}-newline if it is long.

@samp{-M} implies @samp{-E}.

@item -MM
@findex MM (gcc)
Like @samp{-M} but the output mentions only the user-header files
included with @samp{#include "@var{file}"}. System header files
included with @samp{#include <@var{file}>} are omitted.

@samp{-MM} implies @samp{-E}.

@item -D@var{macro}
@findex D (gcc)
Define macro @var{macro} with the empty string as its definition.

@item -D@var{macro}=@var{defn}
Define macro @var{macro} as @var{defn}.

@item -U@var{macro}
@findex U (gcc)
Undefine macro @var{macro}.

@item -T
@findex T (gcc)
Support ANSI C trigraphs. You don't want to know about this
brain-damage. The @samp{-ansi} option also has this effect.
@end table

@node     The Preprocessor, Invoking CPP, The Compiler Driver, Top
@comment  node-name,        next,         previous,            up
@chapter The Preprocessor
@cindex Preprocessor
@cindex gcc-cpp.ttp

@ifinfo
Most often when you use the C preprocessor you will not have to invoke
it explicitly: the C compiler will do so automatically. However, the
preprocessor is sometimes useful individually.
@end ifinfo

@menu
* Invoking CPP::       Command options supported by @samp{gcc-cpp.ttp}.
* Predefined Macros::  List of predefined macros
@end menu

@node     Invoking CPP, Predefined Macros, The Preprocessor, The Preprocessor
@comment  node-name,    next,              previous,         up
@section Invoking the C Preprocessor

@iftex
Most often when you use the C preprocessor you will not have to invoke it
explicitly: the C compiler will do so automatically.  However, the
preprocessor is sometimes useful individually.
@end iftex

The C preprocessor expects two file names as arguments, @var{infile} and
@var{outfile}. The preprocessor reads @var{infile} together with any other
files it specifies with @samp{#include}.  All the output generated by the
combined input files is written in @var{outfile}.

Either @var{infile} or @var{outfile} may be @samp{-}, which as @var{infile}
means to read from standard input and as @var{outfile} means to write to
standard output.  Also, if @var{outfile} or both file names are omitted,
the standard output and standard input are used for the omitted file names.

Here is a table of command options accepted by the C preprocessor.  Most
of them can also be given when compiling a C program; they are passed along
automatically to the preprocessor when it is invoked by the compiler.

@table @samp
@cindex Options (cpp)
@item -P
@findex P (cpp)
Inhibit generation of @samp{#}-lines with line-number information in the
output from the preprocessor. This might be useful when running the
preprocessor on something that is not C code and will be sent to a
program which might be confused by the @samp{#}-lines

@item -C
@findex C (cpp)
Do not discard comments: pass them through to the output file.
Comments appearing in arguments of a macro call will be copied to the
output before the expansion of the macro call.

@item -T
@findex T (cpp)
Process ANSI standard trigraph sequences.  These are three-character
sequences, all starting with @samp{??}, that are defined by ANSI C to
stand for single characters.  For example, @samp{??/} stands for
@samp{\}, so @samp{'??/n'} is a character constant for Newline.
Strictly speaking, the GNU C preprocessor does not support all
programs in ANSI Standard C unless @samp{-T} is used, but if you
ever notice the difference it will be with relief.

You don't want to know any more about trigraphs.

@item -pedantic
@findex pedantic (cpp)
Issue warnings required by the ANSI C standard in certain cases such
as when text other than a comment follows @samp{#else} or @samp{#endif}.


@item -I @var{directory}
@findex I (cpp)
Add the directory @var{directory} to the end of the list of
directories to be searched for header files.
@c (@pxref{Include Syntax}).
This can be used to override a system header file, substituting your
own version, since these directories are searched before the system
header file directories.  If you use more than one @samp{-I} option,
the directories are scanned in left-to-right order; the standard
system directories come after.@refill

@item -I-
Any directories specified with @samp{-I} options before the @samp{-I-}
option are searched only for the case of @samp{#include "@var{file}"};
they are not searched for @samp{#include <@var{file}>}.

If additional directories are specified with @samp{-I} options after
the @samp{-I-}, these directories are searched for all @samp{#include}
directives.

In addition, the @samp{-I-} option inhibits the use of the current
directory as the first search directory for @samp{#include "@var{file}"}.
Therefore, the current directory is searched only if it is requested
explicitly with @samp{-I.}.  Specifying both @samp{-I-} and @samp{-I.}
allows you to control precisely which directories are searched before
the current one and which are searched after.

@item -nostdinc
Do not search the standard system directories for header files.
Only the directories you have specified with @samp{-I} options
(and the current directory, if appropriate) are searched.

@item -D @var{name}
@findex D (cpp)
Predefine @var{name} as a macro, with definition @samp{1}.

@item -D @var{name}=@var{definition}
Predefine @var{name} as a macro, with definition @var{definition}.
There are no restrictions on the contents of @var{definition}, but if
you are invoking the preprocessor from a shell or shell-like program
you may need to use the shell's quoting syntax to protect characters
such as spaces that have a meaning in the shell syntax.

@item -U @var{name}
@findex U (cpp)
Do not predefine @var{name}. If both @samp{-U} and @samp{-D} are
specified for one name, the @samp{-U} beats the @samp{-D} and the name
is not predefined.

@item -undef
@findex undef (cpp)
Do not predefine any nonstandard macros.

@item -d
@findex d (cpp)
Instead of outputting the result of preprocessing, output a list of
@samp{#define} commands for all the macros defined during the
execution of the preprocessor.

@item -M
@findex M (cpp)
Instead of outputting the result of preprocessing, output a rule
suitable for @code{make} describing the dependencies of the main
source file.  The preprocessor outputs one @code{make} rule containing
the object file name for that source file, a colon, and the names of
all the included files.  If there are many included files then the
rule is split into several lines using @samp{\}-newline.

This feature is used in automatic updating of makefiles.

@item -MM
@findex MM (cpp)
Like @samp{-M} but mention only the files included with @samp{#include
"@var{file}"}.  System header files included with @samp{#include
<@var{file}>} are omitted.

@item -i @var{file}
@findex i (cpp)
Process @var{file} as input, discarding the resulting output, before
processing the regular input file.  Because the output generated from
@var{file} is discarded, the only effect of @samp{-i @var{file}} is to
make the macros defined in @var{file} available for use in the main
input.
@end table

@node     Predefined Macros, The Assembler, Invoking CPP, The Preprocessor
@comment  node-name,         next,          previous,    up
@section Predefined Macros
@cindex Predefined Macros
@cindex Macros, Predefined

The standard predefined macros are available with the same meanings
regardless of the machine or operating system on which you are using GNU
 C.
Their names all start and end with double underscores.  Those preceding
@code{__GNUC__} in this table are standardized by ANSI C; the rest are
GNU C extensions.

@table @code
@item __FILE__
@cindex __FILE__
This macro expands to the name of the current input file, in the form
of a C string constant.

@item __LINE__
@cindex __LINE__
This macro expands to the current input line number, in the form of a
decimal integer constant.  While we call it a predefined macro, it's
a pretty strange macro, since its ``definition'' changes with each
new line of source code.

This and @samp{__FILE__} are useful in generating an error message to
report an inconsistency detected by the program; the message can state
the source line at which the inconsistency was detected. For example,

@example
fprintf (stderr, "Internal error: negative string length "
                 "%d at %s, line %d.",
         length, __FILE__, __LINE__);
@end example

A @samp{#include} command changes the expansions of @samp{__FILE__}
and @samp{__LINE__} to correspond to the included file.  At the end of
that file, when processing resumes on the input file that contained
the @samp{#include} command, the expansions of @samp{__FILE__} and
@samp{__LINE__} revert to the values they had before the
@samp{#include} (but @samp{__LINE__} is then incremented by one as
processing moves to the line after the @samp{#include}).

The expansions of both @samp{__FILE__} and @samp{__LINE__} are altered
if a @samp{#line} command is used.
@c @xref{Combining Sources}.

@item __DATE__
@cindex __DATE__
This macro expands to a string constant that describes the date on
which the preprocessor is being run.  The string constant contains
eleven characters and looks like @samp{"Jan 29 1987"} or
@w{@samp{"Apr 1 1905"}}.

@item __TIME__
@cindex __TIME__
This macro expands to a string constant that describes the time at
which the preprocessor is being run.  The string constant contains
eight characters and looks like @samp{"23:59:01"}.

@item __STDC__
@cindex __STDC__
This macro expands to the constant 1, to signify that this is ANSI
Standard C. (Whether that is actually true depends on what C compiler
will operate on the output from the preprocessor.)

@item __GNUC__
This macro is defined if and only if this is GNU C.  This macro is
defined only when the entire GNU C compiler is in use; if you invoke
the preprocessor directly, @samp{__GNUC__} is undefined.

@item __STRICT_ANSI__
This macro is defined if and only if the @samp{-ansi} switch was
specified when GNU C was invoked.  Its definition is the null string.
This macro exists primarily to direct certain GNU header files not to
define certain traditional U**x constructs which are incompatible with
ANSI C.

@item __VERSION__
This macro expands to a string which describes the version number of
GNU C.  The string is normally a sequence of decimal numbers separated
by periods, such as @samp{"1.18"}.  The only reasonable use of this
macro is to incorporate it into a string constant.

@item __OPTIMIZE__
This macro is defined in optimizing compilations.  It causes certain
GNU header files to define alternative macro definitions for some
system library functions.  It is unwise to refer to or test the
definition of this macro unless you make very sure that programs will
execute with the same effect regardless.

@item __CHAR_UNSIGNED__
This macro is defined if and only if the data type @code{char} is
unsigned on the target machine.  It exists to cause the standard
header file @file{limit.h} to work correctly.  It is bad practice
to refer to this macro yourself; instead, refer to the standard
macros defined in @file{limit.h}.

@item __MSHORT__
This macro is defined, if @file{gcc.ttp} is invoked with the
@samp{-mshort} option, which causes integers to be 16 bit. Please
carefully examine the prototypes in the @samp{#include <>} headers
for types before using @samp{-mshort}.@refill
@end table

Apart from the above listed macros, there are usually some more to
to indicate what type of system and machine is in use. For example
@samp{unix} is normally defined on all U**x systems. Other macros
decribe more or less the type of CPU the system runs on. GNU CC for
the Atari ST has the following macros predefined.

@itemize @bullet
@item
@samp{atarist}

@item
@samp{gem}

@item
@samp{m68k}
@end itemize

Please keep in mind, that these macros are only defined if the
preprocessor is invoked from the compiler driver @file{gcc.ttp}.

These predefined symbols are not only nonstandard, they are contrary to the
ANSI standard because their names do not start with underscores.  However,
the GNU C preprocessor would be useless if it did not predefine the same
names that are normally predefined on the system and machine you are using.
Even system header files check the predefined names and will generate
incorrect declarations if they do not find the names that are expected.

The @samp{-ansi} option which requests complete support for ANSI C
inhibits the definition of these predefined symbols.

@node     The Assembler, Syntax, Predefined Macros, Top
@comment  node-name,     next,   previous,          up
@chapter The GNU Assembler (GAS)
@cindex Assembler
@cindex gcc-as.ttp

Most of the time you will be programming in C. But there may certain
situations, where it is feasible to write in assembler. Time is usually a
main reason to dive into assembler programming, when you have to squeeze
the last redundant machine cycle out of your routine, to meet certain
time limits. Another reason might be, that you have to do very low level
stuff like fiddling with bits in the registers of a peripheral chip.

If you already have some experience in assembler programming, you might
miss the feature of creating macros. This is not really a lack given the
fact, that the assembler originated from an U**x environment. Under
this operating system there is a tools for nearly every purpose. If you
were in the need of an extensive macros facility, you would use the M4
macro processor. A public domain version of the M4 macro processor
exists. It should be no problem to port it to the Atari with GCC. For
some macro processing tasks you just as well use the C preprocessor.
What I personally miss is the ability to produce a listing.

@menu
* Invoking AS::     Command line options supported by @samp{gcc-as.ttp}.
* Syntax::          Description of the assembler syntax.
* Pseudo Opcodes::  Pseudo Opcodes supported by @samp{gcc-as.ttp}.
@end menu

@node     Invoking AS, Syntax, Syntax, The Assembler    
@comment  node-name,   next,   previous, up
@section Invoking the Assembler
@cindex Invoking the Assembler

@file{gcc-as.ttp} supports the following command line options. The output
is written to @samp{a.out} by default.

@table @samp
@cindex Options (as)
@c @item f
@c @findex f (as)
@c fast - no need for "app"
@item -G
@findex G (as)
assembles the debugging information the C compiler included into the
output. Without this flag the debugging information is otherwise
discarded.

@item -L
@findex L
Normaly all labels, that start with a @samp{L} are discarded and don't
show up as symbols in the object code module. They are local to that
assembler module. If the @samp{-L} option is given, all local labels
will be included in the object code module.

@c @item -l
@c @findex l (as)
@c keep externals to 2 bit offset.
@item -m68000
@itemx -m68010
@itemx -m68020
@findex m68000 (as)
@findex m68010 (as)
@findex m68020 (as)
These options modify the behavior of assembler in respect of the used
CPU. The M68020, for example, allows relative branches with 32-bit
offset.

@item -o@var{filename}
@findex o (as)
writes the output to @var{filename} instead of @samp{a.out}.

@item -R
@findex R (as)
The information, which normally would be assembled into the data section
of the programm, is moved into the text section.

@item -v
@findex v (as)
displays the version of the assembler.

@item -W
@findex W (as)
suppresses all warning messages.
@end table

@node     Syntax,     Pseudo Opcodes, Invoking AS, The Assembler    
@comment  node-name,  next,           previous,    up
@section Syntax
@cindex Syntax

The assembler uses a slightly modified syntax from the one you might 
know from other 68000 assemblers, which use the original Motorola 
syntax. The next sections try to describe the syntax GAS uses.

The most obvious differences are the missing @samp{.} and the usage of
the at sign (@samp{@@}). The original Motorola syntax uses the @samp{.}
to separate the size modifier (@code{b}, @code{w}, @code{l}) from the
main instruction. In Motorola syntax one would write @samp{move.l #1,d0}
to move a long word with value 1 into register @code{d0}. With GAS you
simple write @samp{movel #1,d0}. The @samp{@@} is used to mark an
indirection equivalent to the Motorola parentheses. To move a long word
of value 1 to the location addressed by @code{a0}, you have to write
@samp{movel #1,a0@@}. The equivalent instruction expressed in Motorola
syntax is @samp{move.l #1,(a0)}. The @samp{#} indicates immediate data
in both cases.@refill

@unnumberedsubsec Register Names and Addressing Modes

The register mnemonics are @code{d0}@dots{}@code{d7} for the data registers
and @code{a0}@dots{}@code{a7} or @code{sp} for address register and the stack
pointer. @code{pc} is the program counter, @code{sr} the status register,
@code{ccr} the condition code register and @code{usp} the user stack 
pointer.@refill

The following table shows the operands GAS can parse. (The first part
part describes the used abreviations. The second part shows the addressing
modes with a equivalent C expression.)

@table @code
@item numb:
an 8 bit number

@item numw:
a 16 bit number

@item numl:
a 32 bit number

@item dreg:
data register 0@dots{}7

@item reg:
address or data register

@item areg:
address register 0@dots{}7

@item apc:
address register or PC

@item num:
a 16 or 32 bit number

@item num2:
a 16 or 32 bit number

@item sz:
@code{w} or @code{l}, if omitted, @code{l} is  assumed.

@item scale:
1 2 4 or 8. If omitted, 1 is assumed.
@end table

@noindent
Addressing Modes:
@cindex Addressing Modes

@table @code
@item Immediate Data
@example 
#num                          --> NUM
@end example

@item Data- or Address Register Direct
@example
dreg                          --> dreg
areg                          --> areg
@end example

@item Address Register Indirect
@example
areg@@                         --> *(areg)
@end example

@item Address Register Indirect with Postincrement or Predecrement
@example
areg@@+                        --> *(areg++)
areg@@-                        --> *(--areg)
@end example

@item Address Register (or PC) Indirect with Displacement
@example
apc@@(numw)                    --> *(apc+numw) 
@end example

@item Address Register (or PC) Indirect with Index (8-Bit Displacement)
@itemx (M68020 only)
@example
apc@@(num,reg:sz:scale)        --> *(apc+num+reg*scale)
apc@@(reg:sz:scale)            --> same, with num=0
@end example

@item Memory Indirect Postindexed
@itemx (M68020 only)
@example
apc@@(num)@@(num2,reg:sz:scale) --> *(*(apc+num)+num2+reg*scale)
apc@@(num)@@(reg:sz:scale)      --> same, with num2=0
apc@@(num)@@(num2)              --> *(*(apc+num)+num2)
                                 (previous mode without an index reg)
@end example

@item Memory Indirect Preindexed
@itemx (M68020 only)
@example
apc@@(num,reg:sz:scale)@@(num2) --> *(*(apc+num+reg*scale)+num2)
apc@@(reg:sz:scale)@@(num2)     --> same, with num=0
@end example

@item Absolute Address
@example
num:sz                        --> *(num)
num                           --> *(num) (sz L assumed)
@end example
@end table

@unnumberedsubsec Labels and Identifiers

User defined identifiers are basically defined by the same rules as C
identifier. They may contain the digits 0@dots{}9, the letters A@dots{}z
and the underscore and must not start with a digit. Identifier, which
end with a @samp{:} are labels. A special form of labels starts with a
@samp{L} or consists of only a digit. Both types are local labels, which
disappear, when the assembly is complete (unless the @samp{-L} option
was specified). They can't be used to resolve external references.  The
@samp{L} type label are referenced by their name, just as any other
label. The digit type labels form a special kind of local labels. You
might also call them temporary labels. They are especially usefull when
you have to create small loops, which poll a peripheral or fill a memory
area. They are referenced by appending either a @samp{f}, for a forward
reference, or a @samp{b}, for a backward reference, to the digit. Lets
look at the following example, which is used to split a memory area
starting at @code{0x80000}. All data on an even addresses is copied to
the area starting at @code{0x70000}; all data from odd addresses goes to
the area starting at @code{0x78000}.@refill

@example
start:
        lea     0x80000,a0
        lea     0x70000,a1
        lea     0x78000,a2
        movel   #0x7fff,d5
0:                              | label @samp{0} is defined
        moveb   a0@@+,a1@@+
        moveb   a0@@+,a2@@+
        dbra    d5,0b           | reference of label @samp{0}
        @dots{}
@end example

The label @samp{0} is referenced 3 lines later by @samp{0b}, since the 
reference is backward. You can use the label @samp{0} again at a later
time to construct more such loops. Since this temporary labels are
restricted to one digit in length, you can only build constructs, which
use 10 temporary labels at the same time.

@unnumberedsubsec Comments

The above example also shows, that comments start with a @samp{|}.
@samp{#} is also used to mark a comments. The C compiler and the
preprocessor generate lines that start with a @samp{#}.

@unnumberedsubsec Numerical and String Constants

Numerical values are given the same way as in a C programs. By default
number are taken to be decimal. A leading @samp{0} denotes an octal and
a @samp{0x} a hexadecimal value. Floating point numbers start with a
@samp{0f}. The optional exponent starts with a @samp{e} or @samp{E}. 

String constants are equivalent to C defined. They are enclosed 
in @samp{"}. Some special character constants are defined by @samp{\}
and a following letter. These characters are possible:

@table @code
@item \b
Backspace, Code 0x08
@item \t
Tab, Code 0x09
@item \n
Line Feed, Code 0x0a
@item \f
Form Feed, Code 0x0c
@item \r
Carriage Return, Code 0x0d
@item \\
Backslash itself
@item \"
Double Quote itself
@item \@var{number}
were @var{number} is a octal number with upto 3 digits specifying the
character code.
@end table

@unnumberedsubsec Assignments and Operators

A @samp{=} is used to assign a value to a Symbol.

@example
Lexp_frame = 8
@end example

@noindent
This is equivalent to the @samp{equ} directive other assemblers use.

GAS supports addition (+), subtraction (-), multiplication(*), division
(/), rigth shift (>), left shift (<), and (&), or (|), not (!), xor (^)
and modulo (%) in expressions. The order of precedence is

@example
        Rank    Examples
lowest   0       operand, (expression)
         1       + -
         2       & ^ ! |
         3       * / % < >
@end example

Parentheses are used to coerce the order of evaluation.

@unnumberedsubsec Segments, Location Counters and Labels

A program written in assembly language may be broken into three
different segments; the TEXT, DATA and BSS sections. Pseudo opcodes are
used to switch between the sections. The assembler maintains a location
counter for each segment. When a label is used in the assembler input,
it is assigned the current value of the active location counter. The
location counter is incremented with every byte, that the assembler 
outputs. GAS actually allows you to have more than one TEXT or DATA 
segment. This is so to ease code generation by high level compilers.
The assembler concatenates the different sections in the end to form 
continuous regions of TEXT and/or DATA. When you do assembly programming 
by hand you would stick to the pseudo obcodes @samp{.text} or
@samp{.data}, which use text or data segment with number 0 by default.

@unnumberedsubsec Types

Symbol and labels can be of one of three types. A symbol is @emph{absolute};
when it's values is known at assembly time. A assignment like 
@samp{Lexp_frame = 8} gives the symbol @samp{Lexp_frame} the absolute
value 8. A symbol or label, which contains an offset from the beginning
of a section, is called @emph{relocatable}. The actual value of this symbol
can only be determined after the linking process or when the program is 
running in memory. The third type of symbols are @emph{undefined externals}.
The actual value of this symbol is defined in an other program.

When different types of symbols are combined to form expressions the 
following rules apply: (@code{abs} = absolute, @code{rel} = relocatable,
@code{ext} = undefined external)

@example
abs + abs => abs
abs + rel = rel + abs => rel
abs + ext = ext + abs => ext

abs - abs => abs
rel - abs => rel
ext - abs => ext
rel - rel => abs
(makes only sense, when both relocatable expression are relative to
same segment)
@end example

All other possible operators are only useful to form expressions with
@emph{absolute} values or symbols.

@node     Pseudo Opcodes, The Utilities, Syntax, The Assembler  
@comment  node-name,      next,          previous, up
@section Supported Pseudo Opcodes (Directives)
@cindex Pseudo Opcodes
@cindex Directives

All pseudo opcodes start with a @samp{.}. They are followed by 0, 1 or
more expressions separated by commas (depending on the directive). The
following table omits the pseudo opcodes, which include special 
information for debugging purposes (for GDB).

@table @code
@item .abort
@cindex .abort
aborts the assembly on the point.

@item .align @var{integer}
@cindex .align
aligns the current segment in size to @var{integer} power of 2. The 
maximum value of @var{integer} is 15. The lines

@example
.text
some code @dots{}
.align 10               | 2^10 = 1024
.data
some more code @dots{}
.align 10               | 2^10 = 1024
@end example

will create text and data sections, which both have the size 1024,
allthough the actuall code, that goes into the sections may be smaller.

@item .ascii @var{string}[,@var{string},@dots{}]
@cindex .ascii
includes the @var{string}('s) in the assembly output.

@item .asciz @var{string}[,@var{string},@dots{}]
@cindex .asciz
This directive is the same as above, but additionally appends a
@samp{\0} character to the string.

@item .byte @var{expr}[,@var{expr},@dots{}]
@cindex .byte
puts consecutive bytes with value @var{expr} into the output.

@item .comm @var{identifier},@var{integer}
@cindex .comm
creates a common area of @var{integer} bytes in the current segment,
which is referenced by @var{identifier}. The @var{identifier} is 
visible from the outside of the module. It can therefore be used to
resolve external reference from other modules.

@item .data [@var{integer}]
@cindex .data
switches to DATA section @var{integer}. If @var{integer} is omitted,
data section 0 is selected.

@item .desc
@cindex .desc
this sets the @samp{n_desc} field in the symbol table. it is used to manupulate
debugging information in the object file.

@item .double @var{double}[,@var{double},@dots{}]
@cindex .double
puts consecutive doubles with value @var{double} into the output.

@item .even
@cindex .even
sets the location counter of the current segment to the next even
value.

@item .file
@itemx .line
@cindex .file
@cindex .line
If a file is assembled which was generated by a compiler or preprocessed
by the C preprocessor, the input may contain lines like @samp{# 132 stdio.h}.
These lines are changed by the assembler to the form

@example
.line 132
.file stdio.h
@end example

@item .fill @var{count},@var{size},@var{expr}
@cindex .fill
puts @var{count} areas with @var{size} into the output. Each area
contains the value @var{expr}. @var{size} may be an even number upto or
equal to 8. The line 

@example
.fill 3, 4, 0xa5a
@end example

would put the following byte sequence in the output (@samp{|} is only
used to mark the size of the area.)

@example
00 00 0a 5a | 00 00 0a 5a | 00 00 0a 5a 
@end example

@item .float @var{float}[,@var{float},@dots{}]
@cindex .float
puts consecutive floats with value @var{float} into the output.

@item .globl @var{identifier}[,@var{identifier},@dots{}]
@cindex .globl
When labels or identifiers are assigned, they are only locally defined.
The @code{.globl} directive gives @var{identifier} external scope. The
label can therefore be used to resolve external references from other
modules. @var{identifier} don't have to be assigned in the current 
module, but can be defined in another module.

@item .int @var{expr}[,@var{expr},@dots{}]
@cindex .int
puts consecutive integers (32 bit) with value @var{expr} into the output.

@item .lcomm @var{identifier},@var{integer}
@cindex .lcomm
is basically the same as @code{.comm}, except that area is allocated in
the BSS segment. The scope of @var{identifier} is only local (only 
visible in the module, where it is defined).

@item .long @var{expr}[,@var{expr},@dots{}]
@cindex .long
same as @code{int}.

@item .lsym @var{identifier},@var{expr}
@cindex .lsym
sets the local @var{identifier} to the value of @var{expr}. The 
@var{identifier} is referenced by preceeding it with a @samp{L}.
(@code{L@var{identifier}}) (Wenn I tried this, the linker threw a
bomb. Trying again crashed the system.)

@item .octa
@itemx .quad
@cindex .octa
@cindex .quad
bignums are specified using this construct. The usual octal, hex or
decimal conventions may be used.

@item .org @var{expr}
@cindex .org
sets the location counter of the current segment to @var{expr}.

@item .set @var{identifier},@var{expr}
@cindex .set 
sets @var{identifier} to the value of @var{expr}. If @var{identifier} is
not explicitly marked external by the @code{.globl} directive, is has only
local scope.

@item .short @var{expr}[,@var{expr},@dots{}]
@cindex .short
puts consecutive shorts (16 bit) with value @var{expr} into the output.

@item .space @var{count}, @var{expr}
@cindex .space
puts @var{count} consecutive number of bytes with value @var{expr} into
the output. The line

@example
.space 5,3
@end example

is equivalent to

@example
.byte 3, 3, 3, 3, 3
@end example

The @code{space} directive is a special form of the @code{fill} directive.

@item .text [@var{integer}]
@cindex .text
switches to TEXT section @var{integer}. If @var{integer} is omitted,
text section 0 is selected.
  
@item .word @var{expr}[,@var{expr},@dots{}]
@cindex .word
same as @code{.short}.
@end table

@node     The Utilities, The Linker, Pseudo Opcodes, Top
@comment  node-name,     next,       previous,       up
@chapter The Utilities
@cindex Utilities

This chapter describes the programs, which don't actually convert
the source code into object code, but instead combine several object
code modules to a runnable program or an object code library. Other
programs can be used to print symbol information from either the
object code or the executable. The last group of utility programs
modify the executables in terms of memory usage and startup time.

@menu
Programs, who combine several object code modules.
* The Linker::       Command options supported by @samp{gcc-ld.ttp}
* The Archiver::     Command options supported by @samp{gcc-ar.ttp}

* Listing Symbols::  How to list the symbols from either the object
                      code module or the executable.

* Modifying Executables::
                     Commands to modify an existing executable.
@end menu

@node     The Linker, The Archiver, The Utilities, The Utilities
@comment  node-name,  next,          previous,      up
@section The Linker @file{gcc-ld.ttp}
@cindex Linker
@cindex gcc-ld.ttp

A linker combines several object modules and extracts modules from a
library to produce a runnable program. During this process all undefined
symbol references are resolved. Additionally all sections from the object
modules, which belong to either the TEXT, DATA or BSS are moved to the
correct program segment. For example, all areas of all the object code
modules, which have the type TEXT, are moved to form one large TEXT
section. The same applies to the DATA and BSS sections.

Most of the time you don't have invoke the linker explicitly. The
compiler driver does the job for you. But in case you have to, the
general syntax is:

@example
gcc-ld [@var{options}] $GNULIB\crt0.o @var{file}.o -l@var{library}
@end example

or

@example
gcc-ld [@var{options}] $GNULIB\crt0.o @@var{linkfile} -l@var{library}
@end example

The above syntax assumes that the executable is produced from C source
code, which normally makes it necessary to link a startup module and a
library. If an executable from a self contained assembler text is to be
created, the startup module @file{crt0.o} and the library might be
missing. @file{gcc-ld.ttp} creates a file @file{a.out} by default. The
linker also appends a DRI compatible symbol table to the executable. The
second command line from the above examples uses the character @samp{@@}
to indicate a file, which contains a list of all object modules to be
linked. This is especially useful, if you have a large bunch of modules
to form a program and the command line would otherwise be too short to
specify all names.

@file{gcc-ld.ttp} supports the following command line options.

@table @samp
@cindex Options (ld)
@c item -A
@c findex A (ld)
@c item -D@var{datasize}
@c findex D (ld) specified_data_size
@c item -d
@c findex d (ld) force_common_definition
@c item -e@var{entry_symbol}
@c findex e (ld) entry_symbol
@item -l@var{library}
@findex l (ld)
Search @var{library} to satisfy unresolved references. The environment
variable @code{GNULIB} is used to locate the library. @code{GNULIB} 
contains a @samp{,} or @samp{;} separated list of paths, each path 
without a trailing slash or backslash.
@item -L@var{directory}
@findex L (ld)
Includes @var{directory} in the searchpath to locate a library.

@item -M
@findex M (ld)
During the linking process extensive information about the encountered
symbols is displayed.

@item -o@var{filename}
@findex o (ld)
The resulting output of the linking process is written to
@var{filename} instead to @file{a.out}.

@c item -r
@c findex -r (ld) relocatable_output
@c item -S
@c findex S (ld) strip_symbols = STRIP_DEBUGGER
@item -s
@findex s (ld)
prevents the linker from attaching a DRI compatible symbol table to the
executable. This symbol table is only of limited use, since the symbol
name is restricted to eight characters in length. Actually you have only
seven valid characters, since the C compiler preceeds every symbol it
generates with an underscore.

@c item -T@var{text_start}
@c findex T (ld) text_start, T_flag_specified
@item -t
@findex t (ld)
During the linking process the files loaded and the modules extracted
from a library are displayed.

@c item -u@var{symbol}
@c findex u (ld) sp->referenced = 1
@c item -X
@c findex X (ld) discard_locals = DISCARD_L
@item -x
@findex x (ld)
This option discards all local symbols from the DRI symbol table. All
global symbols are left in place.
@end table

@unnumberedsubsec @file{sym-ld.ttp}
@cindex sym-ld.ttp

@file{sym-ld.ttp} is a special version of the linker. Its sole purpose
is to create a special symbol file used by the GNU debugger. The
following example shows the usage. (@samp{$} is the prompt of a CLI,
@samp{*} is the GDB prompt, @samp{#} marks a comment)@refill

@example
$ gcc -c -gg foo.c     # compile @samp{foo.c}
$ gcc -o foo.prg foo.o # link with normal @file{gcc-ld.ttp}
$ sym-ld  -r -o foo.sym $(GNULIB)\crt0.o foo.o -lgnugdb  (or -lgdb)
                       # link with @file{sym-ld.ttp} to get symbol file
$ gdb
* exec-file foo.prg    # executable (@file{gcc-ld.ttp} linked Atari
                         executable)
* symbol-file foo.sym  # symbols file (@file{sym-ld.ttp} @samp{-r -o} linked)
* run
* <start doing gdb commands here>
 @dots{}
* q
$                      # back
@end example

Note the line in the example, where @file{sym-ld.ttp} is invoked. A
library @file{gnugdb.olb} is used to create the symbol file. This is
just like the normal library @file{gnu.olb} except that is was
compiled with the @samp{-gg} option. If you don't have this library,
use the normal library (@samp{-lgnu}). In this case you can't single
step through library functions at the source level.

@node     The Archiver, Listing Symbols, The Linker, The Utilities
@comment  node-name,    next,            previous,    up
@section The Archiver @file{gcc-ar.ttp}
@cindex Archiver
@cindex gcc-ar.ttp

The archiver's main purpose is to make things in programming life
easier. The archiver combines several object modules into one large
library. At a later time the linker will then retrieve the modules
needed to resolve all references. Without the library you would have to
supply all modules by hand on the command line or the linker would have
to search through all the files to resolve the references (The library
@file{gnu.olb} contains around 150 modules).

The general syntax for invoking @file{gcc-ar.ttp} is:

@example
gcc-ar @var{option} [@var{position}] @var{library} [@var{module}]
@end example

The @var{option} specifies the action to be taken on the @var{library}
or a @var{module} of that @var{library}. @var{option} also includes
modifiers for the action. The optional @var{position} argument is a
member of the @var{library}. It is used, to mark a specific position in
the @var{library}; an @samp{add} operation would than place a new module
before or after that @var{position}. The next argument specifies the
library. The recommended naming convention for the creation of a new
libraries is @file{@var{library}.olb}. If you don't use this convention,
the compiler driver @file{gcc.ttp} will have trouble finding them.
@var{module} is usually an object code file generated by the compiler.

@file{gcc-ar.ttp} supports the following command line options. If you
don't use a @var{position} the named module is appended or moved to the
end of the library

@table @samp
@cindex Options (ar)
@item a
@findex a (ar)
The @samp{add}, @samp{replace} or @samp{move} operation should place the
@var{module} @strong{after} @var{position}.

@item b
@findex b (ar)
The @samp{add}, @samp{replace} or @samp{move} operation should place the
@var{module} @strong{before} @var{position}.

@item c
@findex c (ar)
If the specified @var{library} does not exist, it is silently created.
Without this option @file{gcc-ar.ttp} would give you a notice, that it
created a new library.

@item d
@findex d (ar)
deletes @var{module} from the @var{library}.

@item i
@findex i (ar)
This is the same as option @samp{b}.

@item l
@findex l (ar)
This option is ignored. (Why is there in the first place ??)

@item m
@findex m (ar)
Move a member around inside the library.

@item o
@findex o (ar)
preserves the modification time of a module, that is extracted from the
library.

@item p
@findex p (ar)
This option pipes the specified @var{module} directly to
@samp{<stdout>}.

@item q
@findex q (ar)
A quick append is performed.

@item r
@findex r (ar)
causes @var{module} to be replaced. If the named module is not already
present, it is appended. This is also the default action, when no
@var{option} is given.

@item s
@findex s (ar)
creates member in the library called @samp{__.SYMDEF}, which contains
the table of contents of global symbols in the archive. This table is used by
the linker to quickly extract a module defining a symbol. This feature
of gcc-ar eliminates the need for a @samp{ranlib} utility commonly found
on U**x systems.

@item t
@findex t (ar)
lists the members, that are currently in the @var{library}. If the
option @samp{v} is also given, additional information about file
permissions, user- and group-id's and last modification date of
the members are displayed. Of course, file permissions and user-
and group-id's don't make much sense on the Atari ST.

@item u
@findex u (ar)
If this option is given, an existing module in the library is only
replaced, if the modification time of the new module is newer than the
modification time of the one already in the library.

@item v
@findex v (ar)
gives you some addtional information depending on the operation that
is performed.
@item x
@findex x (ar)
Extract @var{module} from the @var{library}.
@end table

@node     Listing Symbols, Modifying Executables, The Archiver, The Utilities
@comment  node-name,       next,                  previous,     up
@section Listing Symbols
@cindex Listing Symbols

There are two programs available for printing symbols; each for symbols
of a different kind. @file{gcc-nm.ttp} list symbols in GNU object files
and object libraries. @file{cnm.ttp} lists symbols from a DRI compatible
symbol table attached to an executable.

@unnumberedsubsec @file{gcc-nm.ttp}
@cindex gcc-nm.ttp

The output of @file{gcc-nm.ttp} looks like the following sample:

@example
00000870 b _Lbss
         U _alloca
000003b4 t _glob_dir_to_array
00000532 T _glob_filename
00000248 T _glob_vector
         U _malloc
0000086c D _noglob_dot_filenames
         U _opendir
         U _readdir
00000000 t gcc_compiled.
@end example

The first column displays the relative address of that symbol in
the object file. If the symbol has the type @code{U} (undefined
external) the space in left blank. The next column shows the type
of the symbol. In general, symbols, which have an external scope
(visible for other object module) are marked with an uppercase
letter. Symbols, which are local to the object file are marked
with lowercase letters. The following letters are possible:

@table @samp
@cindex Options (nm)
@item C
marks variables which are defined in that source module, but not
initialized. A declaration like

@example
int variable;
@end example

would create a line marked with a @samp{C}. The first column would 
show the size of that variable in bytes instead of the relative 
address in the object module.

@item b
Variables, which are declared with

@example
static int variable;
@end example

are displayed with a @samp{b}.

@item D
marks variables, which are initialized at declaration time. A
declaration like

@example
int variable = 1;
@end example

would show as a line with a @samp{D} in it.

@item d
Variables which are initialized at declaration time declared are
displayed with a @samp{d}. A declaration like

@example
static int variable = 1;
@end example

would create a line marked with a @samp{d}.

@item t,T
mark text (in other words: actual program code). Functions in your C
source, which have the storage class @code{static}, would be display
with a @samp{t}. All other functions in that source module, which are
visible to other modules, would show up with a @samp{T}.

@item U
All functions which are defined in other modules and referenced in
this module, are displayed with a @samp{U}.
@end table

@noindent
The last column shows the symbol name.

@file{gcc-nm.ttp} supports the following command line options.

@table @samp
@item -a
@findex a (nm)
In case a file is compiled with the @samp{-g} or @samp{-gg} option,
special information for debugging purposes is included in the object
code. This information is listed by supplying the @samp{-a} option.

@item -g
@findex g (nm)
This option restricts the output to include only symbols, which have an
external scope.

@item -n
@findex n (nm)
Without any options the output is sorted in ascii order. By supplying
the @samp{-n}, the listing is sorted in numerical order by the addresses
in first column.

@item -o
@findex o (nm)
If this option is given, every output line is preceeded by a filename in
the form @samp{@var{file}:}, naming the file in which the symbol
appears. If the file to be listed, is an archive, the line begins in the
form @samp{@var{library}(@var{member}):}.

@item -p
@findex p (nm)
The symbols are listed in the order as they appear in the object code
module.

@item -r
@findex r (nm)
The output is sorted in reverse ascii order.

@item -s
@findex s (nm)
Archives may contain a special member called @samp{__.SYMDEF}. Don't ask
me about its purpose. Anyway, using this option shows the content of this
member.

@item -u
@findex u (nm)
Only undefined symbols are listed.
@end table

@unnumberedsubsec @file{cnm.ttp}
@cindex cnm.ttp

@file{cnm.ttp} prints the symbols which are attached to an executable.

@node     Modifying Executables, Concept Index, Listing Symbols, The Utilities
@comment  node-name,             next,          previous,        up
@section Modifying the Executables
@cindex Modifying Executables

The programs which are described in the following sections can
be used to modify an already existing executable, but this only
works under the assumption that the symbol table is still attached
to the executable. So if you want to modifiy the memory usage of a
program at a later time, you should keep the unstripped executables
around.@refill

@unnumberedsubsec @samp{printstk.ttp}
@cindex printstk.ttp

@file{printstk.ttp} prints the current stacksize of an exectuable.
It does this by looking up the symbol @code{_stksize} in the
symbol table portion of the file and than prints the values of the
location where @code{_stksize} points to. The usage is:@refill

@example
printstk [@var{filename}]
@end example

If @var{filename} is no specified it defaults to @file{.\gcc-cc1.ttp}.
If @file{printstk.ttp} is used on some of the executables of the GCC
distribution, you should see a value of @samp{-1}, which means that all
available memory is used by the program (at least for the programs
@file{gcc-cpp.ttp} and @file{gcc-cc1.ttp}).@refill

@unnumberedsubsec @samp{fixstk.ttp}
@cindex fixstk.ttp

@file{fixstk.ttp} works basicly the same way as @file{printstk.ttp},
but lets you modify the value at the location @code{_stksize}. The
usage is:@refill

@example
fixstk @var{size} [@var{filename}]
@end example

@var{size} is the stacksize in Bytes, KBytes or MBytes. To specify
@var{size} in Kbytes or Mbytes, append a @samp{K} or a @samp{M} to the
integer number.@refill

@example
fixstk 128K gcc-as.ttp
@end example

@noindent
sets the stacksize of @file{gcc-as.ttp} to 128 Kbytes.
@unnumberedsubsec @samp{toglclr.ttp}
@cindex toglclr.ttp

When TOS launches an application, it clears all memory from above the BBS
to the end of the TPA. With earlier TOS versions (pre TOS 1.4) this
could take quite a considerable amount of time. The clearing algorithm
was improved during the different TOS releases, but it is still used,
although @strong{most} of the existing programs don't need a cleared
memory. Well, most is not all; therefore for compatibilty's sake the
feature will stay in place.

With TOS 1.4 you can keep the gemdos loader from clearing all memory.
The least significant bit of the long word with offset 0x16 in the
program header is used to determine whether the memory should be cleared
or not. Setting this bit to 1 prevents the loader from clearing all memory.
@file{toglclr.ttp} serves exactly that purpose, namely toggling this
bit.@refill

@c Print indices
@node     Concept Index, Command Options, Modifying Executables, Top
@comment  node-name,     next,            previous,              up
@unnumbered Concept Index
@printindex cp

@node     Command Options, , Concept Index, Top
@comment  node-name,  next,  previous,      up
@unnumbered Index of all Command Line Options
@printindex fn

@contents

@bye

@c Local Variables:
@c compile-command: "texinfo gcc-st.texinfo"
@c End:
