2004-03-21 Zack Weinberg <zack@codesourcery.com>

[pf3gnuchains/gcc-fork.git] / gcc / f / g77.texi

\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename g77.info

@set last-update 2004-03-21
@set copyrights-g77 1995,1996,1997,1998,1999,2000,2001,2002,2003,2004

@include root.texi

@c This tells @include'd files that they're part of the overall G77 doc
@c set.  (They might be part of a higher-level doc set too.)
@set DOC-G77

@c @setfilename useg77.info
@c @setfilename portg77.info
@c To produce the full manual, use the "g77.info" setfilename, and
@c make sure the following do NOT begin with '@c' (and the @clear lines DO)
@set INTERNALS
@set USING
@c To produce a user-only manual, use the "useg77.info" setfilename, and
@c make sure the following does NOT begin with '@c':
@c @clear INTERNALS
@c To produce a porter-only manual, use the "portg77.info" setfilename,
@c and make sure the following does NOT begin with '@c':
@c @clear USING

@ifset INTERNALS
@ifset USING
@settitle Using and Porting GNU Fortran
@end ifset
@end ifset
@c seems reasonable to assume at least one of INTERNALS or USING is set...
@ifclear INTERNALS
@settitle Using GNU Fortran
@end ifclear
@ifclear USING
@settitle Porting GNU Fortran
@end ifclear
@c then again, have some fun
@ifclear INTERNALS
@ifclear USING
@settitle Doing Squat with GNU Fortran
@end ifclear
@end ifclear

@syncodeindex fn cp
@syncodeindex vr cp
@c %**end of header

@c Cause even numbered pages to be printed on the left hand side of
@c the page and odd numbered pages to be printed on the right hand
@c side of the page.  Using this, you can print on both sides of a
@c sheet of paper and have the text on the same part of the sheet.

@c The text on right hand pages is pushed towards the right hand
@c margin and the text on left hand pages is pushed toward the left
@c hand margin.
@c (To provide the reverse effect, set bindingoffset to -0.75in.)

@c @tex
@c \global\bindingoffset=0.75in
@c \global\normaloffset =0.75in
@c @end tex

@copying
Copyright @copyright{} @value{copyrights-g77} Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover
texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
``GNU Free Documentation License''.

(a) The FSF's Front-Cover Text is:

     A GNU Manual

(b) The FSF's Back-Cover Text is:

     You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development.
@end copying

@ifinfo
@dircategory Programming
@direntry
* g77: (g77).                  The GNU Fortran compiler.
@end direntry
@ifset INTERNALS
@ifset USING
This file documents the use and the internals of the GNU Fortran (@command{g77})
compiler.
It corresponds to the @value{which-g77} version of @command{g77}.
@end ifset
@end ifset
@ifclear USING
This file documents the internals of the GNU Fortran (@command{g77}) compiler.
It corresponds to the @value{which-g77} version of @command{g77}.
@end ifclear
@ifclear INTERNALS
This file documents the use of the GNU Fortran (@command{g77}) compiler.
It corresponds to the @value{which-g77} version of @command{g77}.
@end ifclear

Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

@insertcopying
@end ifinfo

Contributed by James Craig Burley (@email{@value{email-burley}}).
Inspired by a first pass at translating @file{g77-0.5.16/f/DOC} that
was contributed to Craig by David Ronis (@email{ronis@@onsager.chem.mcgill.ca}).

@setchapternewpage odd
@titlepage
@ifset INTERNALS
@ifset USING
@center @titlefont{Using and Porting GNU Fortran}

@end ifset
@end ifset
@ifclear INTERNALS
@title Using GNU Fortran
@end ifclear
@ifclear USING
@title Porting GNU Fortran
@end ifclear
@sp 2
@center James Craig Burley
@sp 3
@center Last updated @value{last-update}
@sp 1
@center for version @value{which-g77}
@page
@vskip 0pt plus 1filll
For the @value{which-g77} Version*
@sp 1
Published by the Free Software Foundation @*
59 Temple Place - Suite 330@*
Boston, MA 02111-1307, USA@*
@c Last printed ??ber, 19??.@*
@c Printed copies are available for $? each.@*
@c ISBN ???
@sp 1
@insertcopying
@end titlepage
@summarycontents
@contents
@page

@node Top, Copying,, (DIR)
@top Introduction
@cindex Introduction

@ifset INTERNALS
@ifset USING
This manual documents how to run, install and port @command{g77},
as well as its new features and incompatibilities,
and how to report bugs.
It corresponds to the @value{which-g77} version of @command{g77}.
@end ifset
@end ifset

@ifclear INTERNALS
This manual documents how to run and install @command{g77},
as well as its new features and incompatibilities, and how to report
bugs.
It corresponds to the @value{which-g77} version of @command{g77}.
@end ifclear
@ifclear USING
This manual documents how to port @command{g77},
as well as its new features and incompatibilities,
and how to report bugs.
It corresponds to the @value{which-g77} version of @command{g77}.
@end ifclear

@ifset DEVELOPMENT
@emph{Warning:} This document is still under development,
and might not accurately reflect the @command{g77} code base
of which it is a part.
Efforts are made to keep it somewhat up-to-date,
but they are particularly concentrated
on any version of this information
that is distributed as part of a @emph{released} @command{g77}.

In particular, while this document is intended to apply to
the @value{which-g77} version of @command{g77},
only an official @emph{release} of that version
is expected to contain documentation that is
most consistent with the @command{g77} product in that version.
@end ifset

@menu
* Copying::         GNU General Public License says
                    how you can copy and share GNU Fortran.
* GNU Free Documentation License::
                    How you can copy and share this manual.
* Contributors::    People who have contributed to GNU Fortran.
* Funding::         How to help assure continued work for free software.
* Funding GNU Fortran::  How to help assure continued work on GNU Fortran.
@ifset USING
* Getting Started:: Finding your way around this manual.
* What is GNU Fortran?::  How @command{g77} fits into the universe.
* G77 and GCC::     You can compile Fortran, C, or other programs.
* Invoking G77::    Command options supported by @command{g77}.
* News::            News about recent releases of @command{g77}.
* Changes::         User-visible changes to recent releases of @command{g77}.
* Language::        The GNU Fortran language.
* Compiler::        The GNU Fortran compiler.
* Other Dialects::  Dialects of Fortran supported by @command{g77}.
* Other Compilers:: Fortran compilers other than @command{g77}.
* Other Languages:: Languages other than Fortran.
* Debugging and Interfacing::  How @command{g77} generates code.
* Collected Fortran Wisdom::  How to avoid Trouble.
* Trouble::         If you have trouble with GNU Fortran.
* Open Questions::  Things we'd like to know.
* Bugs::            How, why, and where to report bugs.
* Service::         How to find suppliers of support for GNU Fortran.
@end ifset
@ifset INTERNALS
* Adding Options::  Guidance on teaching @command{g77} about new options.
* Projects::        Projects for @command{g77} internals hackers.
* Front End::       Design and implementation of the @command{g77} front end.
@end ifset

* M: Diagnostics.   Diagnostics produced by @command{g77}.

* Keyword Index::   Index of concepts and symbol names.
@end menu
@c yes, the "M: " @emph{is} intentional -- bad.def references it (CMPAMBIG)!

@include gpl.texi

@include fdl.texi

@node Contributors
@unnumbered Contributors to GNU Fortran
@cindex contributors
@cindex credits

In addition to James Craig Burley, who wrote the front end,
many people have helped create and improve GNU Fortran.

@itemize @bullet
@item
The packaging and compiler portions of GNU Fortran are based largely
on the GCC compiler.
@xref{Contributors,,Contributors to GCC,gcc,Using the GNU Compiler
Collection (GCC)},
for more information.

@item
The run-time library used by GNU Fortran is a repackaged version
of the @code{libf2c} library (combined from the @code{libF77} and
@code{libI77} libraries) provided as part of @command{f2c}, available for
free from @code{netlib} sites on the Internet.

@item
Cygnus Support and The Free Software Foundation contributed
significant money and/or equipment to Craig's efforts.

@item
The following individuals served as alpha testers prior to @command{g77}'s
public release.  This work consisted of testing, researching, sometimes
debugging, and occasionally providing small amounts of code and fixes
for @command{g77}, plus offering plenty of helpful advice to Craig:

@itemize @w{}
@item
Jonathan Corbet
@item
Dr.@: Mark Fernyhough
@item
Takafumi Hayashi (The University of Aizu)---@email{takafumi@@u-aizu.ac.jp}
@item
Kate Hedstrom
@item
Michel Kern (INRIA and Rice University)---@email{Michel.Kern@@inria.fr}
@item
Dr.@: A. O. V. Le Blanc
@item
Dave Love
@item
Rick Lutowski
@item
Toon Moene
@item
Rick Niles
@item
Derk Reefman
@item
Wayne K. Schroll
@item
Bill Thorson
@item
Pedro A. M. Vazquez
@item
Ian Watson
@end itemize

@item
Dave Love (@email{d.love@@dl.ac.uk})
wrote the libU77 part of the run-time library.

@item
Scott Snyder (@email{snyder@@d0sgif.fnal.gov})
provided the patch to add rudimentary support
for @code{INTEGER*1}, @code{INTEGER*2}, and
@code{LOGICAL*1}.
This inspired Craig to add further support,
even though the resulting support
would still be incomplete.
This support is believed to be completed at version 3.4
of @command{gcc} by Roger Sayle (@email{roger@@eyesopen.com}).

@item
David Ronis (@email{ronis@@onsager.chem.mcgill.ca}) inspired
and encouraged Craig to rewrite the documentation in texinfo
format by contributing a first pass at a translation of the
old @file{g77-0.5.16/f/DOC} file.

@item
Toon Moene (@email{toon@@moene.indiv.nluug.nl}) performed
some analysis of generated code as part of an overall project
to improve @command{g77} code generation to at least be as good
as @command{f2c} used in conjunction with @command{gcc}.
So far, this has resulted in the three, somewhat
experimental, options added by @command{g77} to the @command{gcc}
compiler and its back end.

(These, in turn, had made their way into the @code{egcs}
version of the compiler, and do not exist in @command{gcc}
version 2.8 or versions of @command{g77} based on that version
of @command{gcc}.)

@item
John Carr (@email{jfc@@mit.edu}) wrote the alias analysis improvements.

@item
Thanks to Mary Cortani and the staff at Craftwork Solutions
(@email{support@@craftwork.com}) for all of their support.

@item
Many other individuals have helped debug, test, and improve @command{g77}
over the past several years, and undoubtedly more people
will be doing so in the future.
If you have done so, and would like
to see your name listed in the above list, please ask!
The default is that people wish to remain anonymous.
@end itemize

@include funding.texi

@node Funding GNU Fortran
@chapter Funding GNU Fortran
@cindex funding improvements
@cindex improvements, funding

James Craig Burley (@email{@value{email-burley}}), the original author
of @command{g77}, stopped working on it in September 1999
(He has a web page at @uref{@value{www-burley}}.)

GNU Fortran is currently maintained by Toon Moene
(@email{toon@@moene.indiv.nluug.nl}), with the help of countless other
volunteers.

As with other GNU software, funding is important because it can pay for
needed equipment, personnel, and so on.

@cindex FSF, funding the
@cindex funding the FSF
The FSF provides information on the best way to fund ongoing
development of GNU software (such as GNU Fortran) in documents
such as the ``GNUS Bulletin''.
Email @email{gnu@@gnu.org} for information on funding the FSF.

Another important way to support work on GNU Fortran is to volunteer
to help out.

Email @email{@value{email-general}} to volunteer for this work.

However, we strongly expect that there will never be a version 0.6
of @command{g77}.  Work on this compiler has stopped as of the release
of GCC 3.1, except for bug fixing.  @command{g77} will be succeeded by
@command{g95} - see @uref{http://g95.sourceforge.net}.

@xref{Funding,,Funding Free Software}, for more information.

@node Getting Started
@chapter Getting Started
@cindex getting started
@cindex new users
@cindex newbies
@cindex beginners

If you don't need help getting started reading the portions
of this manual that are most important to you, you should skip
this portion of the manual.

If you are new to compilers, especially Fortran compilers, or
new to how compilers are structured under UNIX and UNIX-like
systems, you'll want to see @ref{What is GNU Fortran?}.

If you are new to GNU compilers, or have used only one GNU
compiler in the past and not had to delve into how it lets
you manage various versions and configurations of @command{gcc},
you should see @ref{G77 and GCC}.

Everyone except experienced @command{g77} users should
see @ref{Invoking G77}.

If you're acquainted with previous versions of @command{g77},
you should see @ref{News,,News About GNU Fortran}.
Further, if you've actually used previous versions of @command{g77},
especially if you've written or modified Fortran code to
be compiled by previous versions of @command{g77}, you
should see @ref{Changes}.

If you intend to write or otherwise compile code that is
not already strictly conforming ANSI FORTRAN 77---and this
is probably everyone---you should see @ref{Language}.

If you run into trouble getting Fortran code to compile,
link, run, or work properly, you might find answers
if you see @ref{Debugging and Interfacing},
see @ref{Collected Fortran Wisdom},
and see @ref{Trouble}.
You might also find that the problems you are encountering
are bugs in @command{g77}---see @ref{Bugs}, for information on
reporting them, after reading the other material.

If you need further help with @command{g77}, or with
freely redistributable software in general,
see @ref{Service}.

If you would like to help the @command{g77} project,
see @ref{Funding GNU Fortran}, for information on
helping financially, and see @ref{Projects}, for information
on helping in other ways.

If you're generally curious about the future of
@command{g77}, see @ref{Projects}.
If you're curious about its past,
see @ref{Contributors},
and see @ref{Funding GNU Fortran}.

To see a few of the questions maintainers of @command{g77} have,
and that you might be able to answer,
see @ref{Open Questions}.

@ifset USING
@node What is GNU Fortran?
@chapter What is GNU Fortran?
@cindex concepts, basic
@cindex basic concepts

GNU Fortran, or @command{g77}, is designed initially as a free replacement
for, or alternative to, the UNIX @command{f77} command.
(Similarly, @command{gcc} is designed as a replacement
for the UNIX @command{cc} command.)

@command{g77} also is designed to fit in well with the other
fine GNU compilers and tools.

Sometimes these design goals conflict---in such cases, resolution
often is made in favor of fitting in well with Project GNU.
These cases are usually identified in the appropriate
sections of this manual.

@cindex compilers
As compilers, @command{g77}, @command{gcc}, and @command{f77}
share the following characteristics:

@itemize @bullet
@cindex source code
@cindex file, source
@cindex code, source
@cindex source file
@item
They read a user's program, stored in a file and
containing instructions written in the appropriate
language (Fortran, C, and so on).
This file contains @dfn{source code}.

@cindex translation of user programs
@cindex machine code
@cindex code, machine
@cindex mistakes
@item
They translate the user's program into instructions
a computer can carry out more quickly than it takes
to translate the instructions in the first place.
These instructions are called @dfn{machine code}---code
designed to be efficiently translated and processed
by a machine such as a computer.
Humans usually aren't as good writing machine code
as they are at writing Fortran or C, because
it is easy to make tiny mistakes writing machine code.
When writing Fortran or C, it is easy
to make big mistakes.

@cindex debugger
@cindex bugs, finding
@cindex @command{gdb}, command
@cindex commands, @command{gdb}
@item
They provide information in the generated machine code
that can make it easier to find bugs in the program
(using a debugging tool, called a @dfn{debugger},
such as @command{gdb}).

@cindex libraries
@cindex linking
@cindex @command{ld} command
@cindex commands, @command{ld}
@item
They locate and gather machine code already generated
to perform actions requested by statements in
the user's program.
This machine code is organized
into @dfn{libraries} and is located and gathered
during the @dfn{link} phase of the compilation
process.
(Linking often is thought of as a separate
step, because it can be directly invoked via the
@command{ld} command.
However, the @command{g77} and @command{gcc}
commands, as with most compiler commands, automatically
perform the linking step by calling on @command{ld}
directly, unless asked to not do so by the user.)

@cindex language, incorrect use of
@cindex incorrect use of language
@item
They attempt to diagnose cases where the user's
program contains incorrect usages of the language.
The @dfn{diagnostics} produced by the compiler
indicate the problem and the location in the user's
source file where the problem was first noticed.
The user can use this information to locate and
fix the problem.
@cindex diagnostics, incorrect
@cindex incorrect diagnostics
@cindex error messages, incorrect
@cindex incorrect error messages
(Sometimes an incorrect usage
of the language leads to a situation where the
compiler can no longer make any sense of what
follows---while a human might be able to---and
thus ends up complaining about many ``problems''
it encounters that, in fact, stem from just one
problem, usually the first one reported.)

@cindex warnings
@cindex questionable instructions
@item
They attempt to diagnose cases where the user's
program contains a correct usage of the language,
but instructs the computer to do something questionable.
These diagnostics often are in the form of @dfn{warnings},
instead of the @dfn{errors} that indicate incorrect
usage of the language.
@end itemize

How these actions are performed is generally under the
control of the user.
Using command-line options, the user can specify
how persnickety the compiler is to be regarding
the program (whether to diagnose questionable usage
of the language), how much time to spend making
the generated machine code run faster, and so on.

@cindex components of @command{g77}
@cindex @command{g77}, components of
@command{g77} consists of several components:

@cindex @command{gcc}, command
@cindex commands, @command{gcc}
@itemize @bullet
@item
A modified version of the @command{gcc} command, which also might be
installed as the system's @command{cc} command.
(In many cases, @command{cc} refers to the
system's ``native'' C compiler, which
might be a non-GNU compiler, or an older version
of @command{gcc} considered more stable or that is
used to build the operating system kernel.)

@cindex @command{g77}, command
@cindex commands, @command{g77}
@item
The @command{g77} command itself, which also might be installed as the
system's @command{f77} command.

@cindex libg2c library
@cindex libf2c library
@cindex libraries, libf2c
@cindex libraries, libg2c
@cindex run-time, library
@item
The @code{libg2c} run-time library.
This library contains the machine code needed to support
capabilities of the Fortran language that are not directly
provided by the machine code generated by the @command{g77}
compilation phase.

@code{libg2c} is just the unique name @command{g77} gives
to its version of @code{libf2c} to distinguish it from
any copy of @code{libf2c} installed from @command{f2c}
(or versions of @command{g77} that built @code{libf2c} under
that same name)
on the system.

The maintainer of @code{libf2c} currently is
@email{dmg@@bell-labs.com}.

@cindex @code{f771}, program
@cindex programs, @code{f771}
@cindex assembler
@cindex @command{as} command
@cindex commands, @command{as}
@cindex assembly code
@cindex code, assembly
@item
The compiler itself, internally named @code{f771}.

Note that @code{f771} does not generate machine code directly---it
generates @dfn{assembly code} that is a more readable form
of machine code, leaving the conversion to actual machine code
to an @dfn{assembler}, usually named @command{as}.
@end itemize

@command{gcc} is often thought of as ``the C compiler'' only,
but it does more than that.
Based on command-line options and the names given for files
on the command line, @command{gcc} determines which actions to perform, including
preprocessing, compiling (in a variety of possible languages), assembling,
and linking.

@cindex driver, gcc command as
@cindex @command{gcc}, command as driver
@cindex executable file
@cindex files, executable
@cindex cc1 program
@cindex programs, cc1
@cindex preprocessor
@cindex cpp program
@cindex programs, cpp
For example, the command @samp{gcc foo.c} @dfn{drives} the file
@file{foo.c} through the preprocessor @command{cpp}, then
the C compiler (internally named
@code{cc1}), then the assembler (usually @command{as}), then the linker
(@command{ld}), producing an executable program named @file{a.out} (on
UNIX systems).

@cindex cc1plus program
@cindex programs, cc1plus
As another example, the command @samp{gcc foo.cc} would do much the same as
@samp{gcc foo.c}, but instead of using the C compiler named @code{cc1},
@command{gcc} would use the C++ compiler (named @code{cc1plus}).

@cindex @code{f771}, program
@cindex programs, @code{f771}
In a GNU Fortran installation, @command{gcc} recognizes Fortran source
files by name just like it does C and C++ source files.
It knows to use the Fortran compiler named @code{f771}, instead of
@code{cc1} or @code{cc1plus}, to compile Fortran files.

@cindex @command{gcc}, not recognizing Fortran source
@cindex unrecognized file format
@cindex file format not recognized
Non-Fortran-related operation of @command{gcc} is generally
unaffected by installing the GNU Fortran version of @command{gcc}.
However, without the installed version of @command{gcc} being the
GNU Fortran version, @command{gcc} will not be able to compile
and link Fortran programs---and since @command{g77} uses @command{gcc}
to do most of the actual work, neither will @command{g77}!

@cindex @command{g77}, command
@cindex commands, @command{g77}
The @command{g77} command is essentially just a front-end for
the @command{gcc} command.
Fortran users will normally use @command{g77} instead of @command{gcc},
because @command{g77}
knows how to specify the libraries needed to link with Fortran programs
(@code{libg2c} and @code{lm}).
@command{g77} can still compile and link programs and
source files written in other languages, just like @command{gcc}.

@cindex printing version information
@cindex version information, printing
The command @samp{g77 -v} is a quick
way to display lots of version information for the various programs
used to compile a typical preprocessed Fortran source file---this
produces much more output than @samp{gcc -v} currently does.
(If it produces an error message near the end of the output---diagnostics
from the linker, usually @command{ld}---you might
have an out-of-date @code{libf2c} that improperly handles
complex arithmetic.)
In the output of this command, the line beginning @samp{GNU Fortran Front
End} identifies the version number of GNU Fortran; immediately
preceding that line is a line identifying the version of @command{gcc}
with which that version of @command{g77} was built.

@cindex libf2c library
@cindex libraries, libf2c
The @code{libf2c} library is distributed with GNU Fortran for
the convenience of its users, but is not part of GNU Fortran.
It contains the procedures
needed by Fortran programs while they are running.

@cindex in-line code
@cindex code, in-line
For example, while code generated by @command{g77} is likely
to do additions, subtractions, and multiplications @dfn{in line}---in
the actual compiled code---it is not likely to do trigonometric
functions this way.

Instead, operations like trigonometric
functions are compiled by the @code{f771} compiler
(invoked by @command{g77} when compiling Fortran code) into machine
code that, when run, calls on functions in @code{libg2c}, so
@code{libg2c} must be linked with almost every useful program
having any component compiled by GNU Fortran.
(As mentioned above, the @command{g77} command takes
care of all this for you.)

The @code{f771} program represents most of what is unique to GNU Fortran.
While much of the @code{libg2c} component comes from
the @code{libf2c} component of @command{f2c},
a free Fortran-to-C converter distributed by Bellcore (AT&T),
plus @code{libU77}, provided by Dave Love,
and the @command{g77} command is just a small front-end to @command{gcc},
@code{f771} is a combination of two rather
large chunks of code.

@cindex GNU Back End (GBE)
@cindex GBE
@cindex @command{gcc}, back end
@cindex back end, gcc
@cindex code generator
One chunk is the so-called @dfn{GNU Back End}, or GBE,
which knows how to generate fast code for a wide variety of processors.
The same GBE is used by the C, C++, and Fortran compiler programs @code{cc1},
@code{cc1plus}, and @code{f771}, plus others.
Often the GBE is referred to as the ``gcc back end'' or
even just ``gcc''---in this manual, the term GBE is used
whenever the distinction is important.

@cindex GNU Fortran Front End (FFE)
@cindex FFE
@cindex @command{g77}, front end
@cindex front end, @command{g77}
The other chunk of @code{f771} is the
majority of what is unique about GNU Fortran---the code that knows how
to interpret Fortran programs to determine what they are intending to
do, and then communicate that knowledge to the GBE for actual compilation
of those programs.
This chunk is called the @dfn{Fortran Front End} (FFE).
The @code{cc1} and @code{cc1plus} programs have their own front ends,
for the C and C++ languages, respectively.
These fronts ends are responsible for diagnosing
incorrect usage of their respective languages by the
programs the process, and are responsible for most of
the warnings about questionable constructs as well.
(The GBE handles producing some warnings, like those
concerning possible references to undefined variables.)

Because so much is shared among the compilers for various languages,
much of the behavior and many of the user-selectable options for these
compilers are similar.
For example, diagnostics (error messages and
warnings) are similar in appearance; command-line
options like @option{-Wall} have generally similar effects; and the quality
of generated code (in terms of speed and size) is roughly similar
(since that work is done by the shared GBE).

@node G77 and GCC
@chapter Compile Fortran, C, or Other Programs
@cindex compiling programs
@cindex programs, compiling

@cindex @command{gcc}, command
@cindex commands, @command{gcc}
A GNU Fortran installation includes a modified version of the @command{gcc}
command.

In a non-Fortran installation, @command{gcc} recognizes C, C++,
and Objective-C source files.

In a GNU Fortran installation, @command{gcc} also recognizes Fortran source
files and accepts Fortran-specific command-line options, plus some
command-line options that are designed to cater to Fortran users
but apply to other languages as well.

@xref{G++ and GCC,,Programming Languages Supported by GCC,gcc,Using
the GNU Compiler Collection (GCC)},
for information on the way different languages are handled
by the GCC compiler (@command{gcc}).

@cindex @command{g77}, command
@cindex commands, @command{g77}
Also provided as part of GNU Fortran is the @command{g77} command.
The @command{g77} command is designed to make compiling and linking Fortran
programs somewhat easier than when using the @command{gcc} command for
these tasks.
It does this by analyzing the command line somewhat and changing it
appropriately before submitting it to the @command{gcc} command.

@cindex -v option
@cindex @command{g77} options, -v
@cindex options, -v
Use the @option{-v} option with @command{g77}
to see what is going on---the first line of output is the invocation
of the @command{gcc} command.

@include invoke.texi

@include news.texi

@set USERVISONLY
@include news.texi
@clear USERVISONLY

@node Language
@chapter The GNU Fortran Language

@cindex standard, ANSI FORTRAN 77
@cindex ANSI FORTRAN 77 standard
@cindex reference works
GNU Fortran supports a variety of extensions to, and dialects
of, the Fortran language.
Its primary base is the ANSI FORTRAN 77 standard, currently available on
the network at
@uref{http://www.fortran.com/fortran/F77_std/rjcnf0001.html}
or as monolithic text at
@uref{http://www.fortran.com/fortran/F77_std/f77_std.html}.
It offers some extensions that are popular among users
of UNIX @command{f77} and @command{f2c} compilers, some that
are popular among users of other compilers (such as Digital
products), some that are popular among users of the
newer Fortran 90 standard, and some that are introduced
by GNU Fortran.

@cindex textbooks
(If you need a text on Fortran,
a few freely available electronic references have pointers from
@uref{http://www.fortran.com/F/books.html}.  There is a `cooperative
net project', @cite{User Notes on Fortran Programming} at
@uref{ftp://vms.huji.ac.il/fortran/} and mirrors elsewhere; some of this
material might not apply specifically to @command{g77}.)

Part of what defines a particular implementation of a Fortran
system, such as @command{g77}, is the particular characteristics
of how it supports types, constants, and so on.
Much of this is left up to the implementation by the various
Fortran standards and accepted practice in the industry.

The GNU Fortran @emph{language} is described below.
Much of the material is organized along the same lines
as the ANSI FORTRAN 77 standard itself.

@xref{Other Dialects}, for information on features @command{g77} supports
that are not part of the GNU Fortran language.

@emph{Note}: This portion of the documentation definitely needs a lot
of work!

@menu
Relationship to the ANSI FORTRAN 77 standard:
* Direction of Language Development::  Where GNU Fortran is headed.
* Standard Support::  Degree of support for the standard.

Extensions to the ANSI FORTRAN 77 standard:
* Conformance::
* Notation Used::
* Terms and Concepts::
* Characters Lines Sequence::
* Data Types and Constants::
* Expressions::
* Specification Statements::
* Control Statements::
* Functions and Subroutines::
* Scope and Classes of Names::
* I/O::
* Fortran 90 Features::
@end menu

@node Direction of Language Development
@section Direction of Language Development
@cindex direction of language development
@cindex features, language
@cindex language, features

The purpose of the following description of the GNU Fortran
language is to promote wide portability of GNU Fortran programs.

GNU Fortran is an evolving language, due to the
fact that @command{g77} itself is in beta test.
Some current features of the language might later
be redefined as dialects of Fortran supported by @command{g77}
when better ways to express these features are added to @command{g77},
for example.
Such features would still be supported by
@command{g77}, but would be available only when
one or more command-line options were used.

The GNU Fortran @emph{language} is distinct from the
GNU Fortran @emph{compilation system} (@command{g77}).

For example, @command{g77} supports various dialects of
Fortran---in a sense, these are languages other than
GNU Fortran---though its primary
purpose is to support the GNU Fortran language, which also is
described in its documentation and by its implementation.

On the other hand, non-GNU compilers might offer
support for the GNU Fortran language, and are encouraged
to do so.

Currently, the GNU Fortran language is a fairly fuzzy object.
It represents something of a cross between what @command{g77} accepts
when compiling using the prevailing defaults and what this
document describes as being part of the language.

Future versions of @command{g77} are expected to clarify the
definition of the language in the documentation.
Often, this will mean adding new features to the language, in the form
of both new documentation and new support in @command{g77}.
However, it might occasionally mean removing a feature
from the language itself to ``dialect'' status.
In such a case, the documentation would be adjusted
to reflect the change, and @command{g77} itself would likely be changed
to require one or more command-line options to continue supporting
the feature.

The development of the GNU Fortran language is intended to strike
a balance between:

@itemize @bullet
@item
Serving as a mostly-upwards-compatible language from the
de facto UNIX Fortran dialect as supported by @command{f77}.

@item
Offering new, well-designed language features.
Attributes of such features include
not making existing code any harder to read
(for those who might be unaware that the new
features are not in use) and
not making state-of-the-art
compilers take longer to issue diagnostics,
among others.

@item
Supporting existing, well-written code without gratuitously
rejecting non-standard constructs, regardless of the origin
of the code (its dialect).

@item
Offering default behavior and command-line options to reduce
and, where reasonable, eliminate the need for programmers to make
any modifications to code that already works in existing
production environments.

@item
Diagnosing constructs that have different meanings in different
systems, languages, and dialects, while offering clear,
less ambiguous ways to express each of the different meanings
so programmers can change their code appropriately.
@end itemize

One of the biggest practical challenges for the developers of the
GNU Fortran language is meeting the sometimes contradictory demands
of the above items.

For example, a feature might be widely used in one popular environment,
but the exact same code that utilizes that feature might not work
as expected---perhaps it might mean something entirely different---in
another popular environment.

Traditionally, Fortran compilers---even portable ones---have solved this
problem by simply offering the appropriate feature to users of
the respective systems.
This approach treats users of various Fortran systems and dialects
as remote ``islands'', or camps, of programmers, and assume that these
camps rarely come into contact with each other (or,
especially, with each other's code).

Project GNU takes a radically different approach to software and language
design, in that it assumes that users of GNU software do not necessarily
care what kind of underlying system they are using, regardless
of whether they are using software (at the user-interface
level) or writing it (for example, writing Fortran or C code).

As such, GNU users rarely need consider just what kind of underlying
hardware (or, in many cases, operating system) they are using at any
particular time.
They can use and write software designed for a general-purpose,
widely portable, heterogeneous environment---the GNU environment.

In line with this philosophy, GNU Fortran must evolve into a product
that is widely ported and portable not only in the sense that it can
be successfully built, installed, and run by users, but in the larger
sense that its users can use it in the same way, and expect largely the
same behaviors from it, regardless of the kind of system they are using
at any particular time.

This approach constrains the solutions @command{g77} can use to resolve
conflicts between various camps of Fortran users.
If these two camps disagree about what a particular construct should
mean, @command{g77} cannot simply be changed to treat that particular construct as
having one meaning without comment (such as a warning), lest the users
expecting it to have the other meaning are unpleasantly surprised that
their code misbehaves when executed.

The use of the ASCII backslash character in character constants is
an excellent (and still somewhat unresolved) example of this kind of
controversy.
@xref{Backslash in Constants}.
Other examples are likely to arise in the future, as @command{g77} developers
strive to improve its ability to accept an ever-wider variety of existing
Fortran code without requiring significant modifications to said code.

Development of GNU Fortran is further constrained by the desire
to avoid requiring programmers to change their code.
This is important because it allows programmers, administrators,
and others to more faithfully evaluate and validate @command{g77}
(as an overall product and as new versions are distributed)
without having to support multiple versions of their programs
so that they continue to work the same way on their existing
systems (non-GNU perhaps, but possibly also earlier versions
of @command{g77}).

@node Standard Support
@section ANSI FORTRAN 77 Standard Support
@cindex ANSI FORTRAN 77 support
@cindex standard, support for
@cindex support, FORTRAN 77
@cindex compatibility, FORTRAN 77
@cindex FORTRAN 77 compatibility

GNU Fortran supports ANSI FORTRAN 77 with the following caveats.
In summary, the only ANSI FORTRAN 77 features @command{g77} doesn't
support are those that are probably rarely used in actual code,
some of which are explicitly disallowed by the Fortran 90 standard.

@menu
* No Passing External Assumed-length::  CHAR*(*) CFUNC restriction.
* No Passing Dummy Assumed-length::     CHAR*(*) CFUNC restriction.
* No Pathological Implied-DO::          No @samp{((@dots{}, I=@dots{}), I=@dots{})}.
* No Useless Implied-DO::               No @samp{(A, I=1, 1)}.
@end menu

@node No Passing External Assumed-length
@subsection No Passing External Assumed-length

@command{g77} disallows passing of an external procedure
as an actual argument if the procedure's
type is declared @code{CHARACTER*(*)}.  For example:

@example
CHARACTER*(*) CFUNC
EXTERNAL CFUNC
CALL FOO(CFUNC)
END
@end example

@noindent
It isn't clear whether the standard considers this conforming.

@node No Passing Dummy Assumed-length
@subsection No Passing Dummy Assumed-length

@command{g77} disallows passing of a dummy procedure
as an actual argument if the procedure's
type is declared @code{CHARACTER*(*)}.

@example
SUBROUTINE BAR(CFUNC)
CHARACTER*(*) CFUNC
EXTERNAL CFUNC
CALL FOO(CFUNC)
END
@end example

@noindent
It isn't clear whether the standard considers this conforming.

@node No Pathological Implied-DO
@subsection No Pathological Implied-DO

The @code{DO} variable for an implied-@code{DO} construct in a
@code{DATA} statement may not be used as the @code{DO} variable
for an outer implied-@code{DO} construct.  For example, this
fragment is disallowed by @command{g77}:

@smallexample
DATA ((A(I, I), I= 1, 10), I= 1, 10) /@dots{}/
@end smallexample

@noindent
This also is disallowed by Fortran 90, as it offers no additional
capabilities and would have a variety of possible meanings.

Note that it is @emph{very} unlikely that any production Fortran code
tries to use this unsupported construct.

@node No Useless Implied-DO
@subsection No Useless Implied-DO

An array element initializer in an implied-@code{DO} construct in a
@code{DATA} statement must contain at least one reference to the @code{DO}
variables of each outer implied-@code{DO} construct.  For example,
this fragment is disallowed by @command{g77}:

@smallexample
DATA (A, I= 1, 1) /1./
@end smallexample

@noindent
This also is disallowed by Fortran 90, as FORTRAN 77's more permissive
requirements offer no additional capabilities.
However, @command{g77} doesn't necessarily diagnose all cases
where this requirement is not met.

Note that it is @emph{very} unlikely that any production Fortran code
tries to use this unsupported construct.

@node Conformance
@section Conformance

(The following information augments or overrides the information in
Section 1.4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 1 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

The definition of the GNU Fortran language is akin to that of
the ANSI FORTRAN 77 language in that it does not generally require
conforming implementations to diagnose cases where programs do
not conform to the language.

However, @command{g77} as a compiler is being developed in a way that
is intended to enable it to diagnose such cases in an easy-to-understand
manner.

A program that conforms to the GNU Fortran language should, when
compiled, linked, and executed using a properly installed @command{g77}
system, perform as described by the GNU Fortran language definition.
Reasons for different behavior include, among others:

@itemize @bullet
@item
Use of resources (memory---heap, stack, and so on; disk space; CPU
time; etc.) exceeds those of the system.

@item
Range and/or precision of calculations required by the program
exceeds that of the system.

@item
Excessive reliance on behaviors that are system-dependent
(non-portable Fortran code).

@item
Bugs in the program.

@item
Bug in @command{g77}.

@item
Bugs in the system.
@end itemize

Despite these ``loopholes'', the availability of a clear specification
of the language of programs submitted to @command{g77}, as this document
is intended to provide, is considered an important aspect of providing
a robust, clean, predictable Fortran implementation.

The definition of the GNU Fortran language, while having no special
legal status, can therefore be viewed as a sort of contract, or agreement.
This agreement says, in essence, ``if you write a program in this language,
and run it in an environment (such as a @command{g77} system) that supports
this language, the program should behave in a largely predictable way''.

@node Notation Used
@section Notation Used in This Chapter

(The following information augments or overrides the information in
Section 1.5 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 1 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

In this chapter, ``must'' denotes a requirement, ``may'' denotes permission,
and ``must not'' and ``may not'' denote prohibition.
Terms such as ``might'', ``should'', and ``can'' generally add little or
nothing in the way of weight to the GNU Fortran language itself,
but are used to explain or illustrate the language.

For example:

@display
``The @code{FROBNITZ} statement must precede all executable
statements in a program unit, and may not specify any dummy
arguments.  It may specify local or common variables and arrays.
Its use should be limited to portions of the program designed to
be non-portable and system-specific, because it might cause the
containing program unit to behave quite differently on different
systems.''
@end display

Insofar as the GNU Fortran language is specified,
the requirements and permissions denoted by the above sample statement
are limited to the placement of the statement and the kinds of
things it may specify.
The rest of the statement---the content regarding non-portable portions
of the program and the differing behavior of program units containing
the @code{FROBNITZ} statement---does not pertain the GNU Fortran
language itself.
That content offers advice and warnings about the @code{FROBNITZ}
statement.

@emph{Remember:} The GNU Fortran language definition specifies
both what constitutes a valid GNU Fortran program and how,
given such a program, a valid GNU Fortran implementation is
to interpret that program.

It is @emph{not} incumbent upon a valid GNU Fortran implementation
to behave in any particular way, any consistent way, or any
predictable way when it is asked to interpret input that is
@emph{not} a valid GNU Fortran program.

Such input is said to have @dfn{undefined} behavior when
interpreted by a valid GNU Fortran implementation, though
an implementation may choose to specify behaviors for some
cases of inputs that are not valid GNU Fortran programs.

Other notation used herein is that of the GNU texinfo format,
which is used to generate printed hardcopy, on-line hypertext
(Info), and on-line HTML versions, all from a single source
document.
This notation is used as follows:

@itemize @bullet
@item
Keywords defined by the GNU Fortran language are shown
in uppercase, as in: @code{COMMON}, @code{INTEGER}, and
@code{BLOCK DATA}.

Note that, in practice, many Fortran programs are written
in lowercase---uppercase is used in this manual as a
means to readily distinguish keywords and sample Fortran-related
text from the prose in this document.

@item
Portions of actual sample program, input, or output text
look like this: @samp{Actual program text}.

Generally, uppercase is used for all Fortran-specific and
Fortran-related text, though this does not always include
literal text within Fortran code.

For example: @samp{PRINT *, 'My name is Bob'}.

@item
A metasyntactic variable---that is, a name used in this document
to serve as a placeholder for whatever text is used by the
user or programmer---appears as shown in the following example:

``The @code{INTEGER @var{ivar}} statement specifies that
@var{ivar} is a variable or array of type @code{INTEGER}.''

In the above example, any valid text may be substituted for
the metasyntactic variable @var{ivar} to make the statement
apply to a specific instance, as long as the same text is
substituted for @emph{both} occurrences of @var{ivar}.

@item
Ellipses (``@dots{}'') are used to indicate further text that
is either unimportant or expanded upon further, elsewhere.

@item
Names of data types are in the style of Fortran 90, in most
cases.

@xref{Kind Notation}, for information on the relationship
between Fortran 90 nomenclature (such as @code{INTEGER(KIND=1)})
and the more traditional, less portably concise nomenclature
(such as @code{INTEGER*4}).
@end itemize

@node Terms and Concepts
@section Fortran Terms and Concepts

(The following information augments or overrides the information in
Chapter 2 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 2 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

@menu
* Syntactic Items::
* Statements Comments Lines::
* Scope of Names and Labels::
@end menu

@node Syntactic Items
@subsection Syntactic Items

(Corresponds to Section 2.2 of ANSI X3.9-1978 FORTRAN 77.)

@cindex limits, lengths of names
In GNU Fortran, a symbolic name is at least one character long,
and has no arbitrary upper limit on length.
However, names of entities requiring external linkage (such as
external functions, external subroutines, and @code{COMMON} areas)
might be restricted to some arbitrary length by the system.
Such a restriction is no more constrained than that of one
through six characters.

Underscores (@samp{_}) are accepted in symbol names after the first
character (which must be a letter).

@node Statements Comments Lines
@subsection Statements, Comments, and Lines

(Corresponds to Section 2.3 of ANSI X3.9-1978 FORTRAN 77.)

@cindex trailing comment
@cindex comment
@cindex characters, comment
@cindex !
@cindex exclamation point
@cindex continuation character
@cindex characters, continuation
Use of an exclamation point (@samp{!}) to begin a
trailing comment (a comment that extends to the end of the same
source line) is permitted under the following conditions:

@itemize @bullet
@item
The exclamation point does not appear in column 6.
Otherwise, it is treated as an indicator of a continuation
line.

@item
The exclamation point appears outside a character or Hollerith
constant.
Otherwise, the exclamation point is considered part of the
constant.

@item
The exclamation point appears to the left of any other possible
trailing comment.
That is, a trailing comment may contain exclamation points
in their commentary text.
@end itemize

@cindex ;
@cindex semicolon
@cindex statements, separated by semicolon
Use of a semicolon (@samp{;}) as a statement separator
is permitted under the following conditions:

@itemize @bullet
@item
The semicolon appears outside a character or Hollerith
constant.
Otherwise, the semicolon is considered part of the
constant.

@item
The semicolon appears to the left of a trailing comment.
Otherwise, the semicolon is considered part of that
comment.

@item
Neither a logical @code{IF} statement nor a non-construct
@code{WHERE} statement (a Fortran 90 feature) may be
followed (in the same, possibly continued, line) by
a semicolon used as a statement separator.

This restriction avoids the confusion
that can result when reading a line such as:

@smallexample
IF (VALIDP) CALL FOO; CALL BAR
@end smallexample

@noindent
Some readers might think the @samp{CALL BAR} is executed
only if @samp{VALIDP} is @code{.TRUE.}, while others might
assume its execution is unconditional.

(At present, @command{g77} does not diagnose code that
violates this restriction.)
@end itemize

@node Scope of Names and Labels
@subsection Scope of Symbolic Names and Statement Labels
@cindex scope

(Corresponds to Section 2.9 of ANSI X3.9-1978 FORTRAN 77.)

Included in the list of entities that have a scope of a
program unit are construct names (a Fortran 90 feature).
@xref{Construct Names}, for more information.

@node Characters Lines Sequence
@section Characters, Lines, and Execution Sequence

(The following information augments or overrides the information in
Chapter 3 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 3 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

@menu
* Character Set::
* Lines::
* Continuation Line::
* Statements::
* Statement Labels::
* Order::
* INCLUDE::
* Cpp-style directives::
@end menu

@node Character Set
@subsection GNU Fortran Character Set
@cindex characters

(Corresponds to Section 3.1 of ANSI X3.9-1978 FORTRAN 77.)

Letters include uppercase letters (the twenty-six characters
of the English alphabet) and lowercase letters (their lowercase
equivalent).
Generally, lowercase letters may be used in place of uppercase
letters, though in character and Hollerith constants, they
are distinct.

Special characters include:

@itemize @bullet
@item
@cindex ;
@cindex semicolon
Semicolon (@samp{;})

@item
@cindex !
@cindex exclamation point
Exclamation point (@samp{!})

@item
@cindex "
@cindex double quote
Double quote (@samp{"})

@item
@cindex \
@cindex backslash
Backslash (@samp{\})

@item
@cindex ?
@cindex question mark
Question mark (@samp{?})

@item
@cindex #
@cindex hash mark
@cindex pound sign
Hash mark (@samp{#})

@item
@cindex &
@cindex ampersand
Ampersand (@samp{&})

@item
@cindex %
@cindex percent sign
Percent sign (@samp{%})

@item
@cindex _
@cindex underscore
Underscore (@samp{_})

@item
@cindex <
@cindex open angle
@cindex left angle
@cindex open bracket
@cindex left bracket
Open angle (@samp{<})

@item
@cindex >
@cindex close angle
@cindex right angle
@cindex close bracket
@cindex right bracket
Close angle (@samp{>})

@item
The FORTRAN 77 special characters (@key{SPC}, @samp{=},
@samp{+}, @samp{-}, @samp{*}, @samp{/}, @samp{(},
@samp{)}, @samp{,}, @samp{.}, @samp{$}, @samp{'},
and @samp{:})
@end itemize

@cindex blank
@cindex space
@cindex SPC
Note that this document refers to @key{SPC} as @dfn{space},
while X3.9-1978 FORTRAN 77 refers to it as @dfn{blank}.

@node Lines
@subsection Lines
@cindex lines
@cindex source file format
@cindex source format
@cindex file, source
@cindex source code
@cindex code, source
@cindex fixed form
@cindex free form

(Corresponds to Section 3.2 of ANSI X3.9-1978 FORTRAN 77.)

The way a Fortran compiler views source files depends entirely on the
implementation choices made for the compiler, since those choices
are explicitly left to the implementation by the published Fortran
standards.

The GNU Fortran language mandates a view applicable to UNIX-like
text files---files that are made up of an arbitrary number of lines,
each with an arbitrary number of characters (sometimes called stream-based
files).

This view does not apply to types of files that are specified as
having a particular number of characters on every single line (sometimes
referred to as record-based files).

Because a ``line in a program unit is a sequence of 72 characters'',
to quote X3.9-1978, the GNU Fortran language specifies that a
stream-based text file is translated to GNU Fortran lines as follows:

@itemize @bullet
@item
A newline in the file is the character that represents the end of
a line of text to the underlying system.
For example, on ASCII-based systems, a newline is the @key{NL}
character, which has ASCII value 10 (decimal).

@item
Each newline in the file serves to end the line of text that precedes
it (and that does not contain a newline).

@item
The end-of-file marker (@code{EOF}) also serves to end the line
of text that precedes it (and that does not contain a newline).

@item
@cindex blank
@cindex space
@cindex SPC
Any line of text that is shorter than 72 characters is padded to that length
with spaces (called ``blanks'' in the standard).

@item
Any line of text that is longer than 72 characters is truncated to that
length, but the truncated remainder must consist entirely of spaces.

@item
Characters other than newline and the GNU Fortran character set
are invalid.
@end itemize

For the purposes of the remainder of this description of the GNU
Fortran language, the translation described above has already
taken place, unless otherwise specified.

The result of the above translation is that the source file appears,
in terms of the remainder of this description of the GNU Fortran language,
as if it had an arbitrary
number of 72-character lines, each character being among the GNU Fortran
character set.

For example, if the source file itself has two newlines in a row,
the second newline becomes, after the above translation, a single
line containing 72 spaces.

@node Continuation Line
@subsection Continuation Line
@cindex continuation line, number of
@cindex lines, continuation
@cindex number of continuation lines
@cindex limits, continuation lines

(Corresponds to Section 3.2.3 of ANSI X3.9-1978 FORTRAN 77.)

A continuation line is any line that both

@itemize @bullet
@item
Contains a continuation character, and

@item
Contains only spaces in columns 1 through 5
@end itemize

A continuation character is any character of the GNU Fortran character set
other than space (@key{SPC}) or zero (@samp{0})
in column 6, or a digit (@samp{0} through @samp{9}) in column
7 through 72 of a line that has only spaces to the left of that
digit.

The continuation character is ignored as far as the content of
the statement is concerned.

The GNU Fortran language places no limit on the number of
continuation lines in a statement.
In practice, the limit depends on a variety of factors, such as
available memory, statement content, and so on, but no
GNU Fortran system may impose an arbitrary limit.

@node Statements
@subsection Statements

(Corresponds to Section 3.3 of ANSI X3.9-1978 FORTRAN 77.)

Statements may be written using an arbitrary number of continuation
lines.

Statements may be separated using the semicolon (@samp{;}), except
that the logical @code{IF} and non-construct @code{WHERE} statements
may not be separated from subsequent statements using only a semicolon
as statement separator.

The @code{END PROGRAM}, @code{END SUBROUTINE}, @code{END FUNCTION},
and @code{END BLOCK DATA} statements are alternatives to the @code{END}
statement.
These alternatives may be written as normal statements---they are not
subject to the restrictions of the @code{END} statement.

However, no statement other than @code{END} may have an initial line
that appears to be an @code{END} statement---even @code{END PROGRAM},
for example, must not be written as:

@example
      END
     &PROGRAM
@end example

@node Statement Labels
@subsection Statement Labels

(Corresponds to Section 3.4 of ANSI X3.9-1978 FORTRAN 77.)

A statement separated from its predecessor via a semicolon may be
labeled as follows:

@itemize @bullet
@item
The semicolon is followed by the label for the statement,
which in turn follows the label.

@item
The label must be no more than five digits in length.

@item
The first digit of the label for the statement is not
the first non-space character on a line.
Otherwise, that character is treated as a continuation
character.
@end itemize

A statement may have only one label defined for it.

@node Order
@subsection Order of Statements and Lines

(Corresponds to Section 3.5 of ANSI X3.9-1978 FORTRAN 77.)

Generally, @code{DATA} statements may precede executable statements.
However, specification statements pertaining to any entities
initialized by a @code{DATA} statement must precede that @code{DATA}
statement.
For example,
after @samp{DATA I/1/}, @samp{INTEGER I} is not permitted, but
@samp{INTEGER J} is permitted.

The last line of a program unit may be an @code{END} statement,
or may be:

@itemize @bullet
@item
An @code{END PROGRAM} statement, if the program unit is a main program.

@item
An @code{END SUBROUTINE} statement, if the program unit is a subroutine.

@item
An @code{END FUNCTION} statement, if the program unit is a function.

@item
An @code{END BLOCK DATA} statement, if the program unit is a block data.
@end itemize

@node INCLUDE
@subsection Including Source Text
@cindex INCLUDE directive

Additional source text may be included in the processing of
the source file via the @code{INCLUDE} directive:

@example
INCLUDE @var{filename}
@end example

@noindent
The source text to be included is identified by @var{filename},
which is a literal GNU Fortran character constant.
The meaning and interpretation of @var{filename} depends on the
implementation, but typically is a filename.

(@command{g77} treats it as a filename that it searches for
in the current directory and/or directories specified
via the @option{-I} command-line option.)

The effect of the @code{INCLUDE} directive is as if the
included text directly replaced the directive in the source
file prior to interpretation of the program.
Included text may itself use @code{INCLUDE}.
The depth of nested @code{INCLUDE} references depends on
the implementation, but typically is a positive integer.

This virtual replacement treats the statements and @code{INCLUDE}
directives in the included text as syntactically distinct from
those in the including text.

Therefore, the first non-comment line of the included text
must not be a continuation line.
The included text must therefore have, after the non-comment
lines, either an initial line (statement), an @code{INCLUDE}
directive, or nothing (the end of the included text).

Similarly, the including text may end the @code{INCLUDE}
directive with a semicolon or the end of the line, but it
cannot follow an @code{INCLUDE} directive at the end of its
line with a continuation line.
Thus, the last statement in an included text may not be
continued.

Any statements between two @code{INCLUDE} directives on the
same line are treated as if they appeared in between the
respective included texts.
For example:

@smallexample
INCLUDE 'A'; PRINT *, 'B'; INCLUDE 'C'; END PROGRAM
@end smallexample

@noindent
If the text included by @samp{INCLUDE 'A'} constitutes
a @samp{PRINT *, 'A'} statement and the text included by
@samp{INCLUDE 'C'} constitutes a @samp{PRINT *, 'C'} statement,
then the output of the above sample program would be

@example
A
B
C
@end example

@noindent
(with suitable allowances for how an implementation defines
its handling of output).

Included text must not include itself directly or indirectly,
regardless of whether the @var{filename} used to reference
the text is the same.

Note that @code{INCLUDE} is @emph{not} a statement.
As such, it is neither a non-executable or executable
statement.
However, if the text it includes constitutes one or more
executable statements, then the placement of @code{INCLUDE}
is subject to effectively the same restrictions as those
on executable statements.

An @code{INCLUDE} directive may be continued across multiple
lines as if it were a statement.
This permits long names to be used for @var{filename}.

@node Cpp-style directives
@subsection Cpp-style directives
@cindex #
@cindex preprocessor

@code{cpp} output-style @code{#} directives
(@pxref{C Preprocessor Output,,, cpp, The C Preprocessor})
are recognized by the compiler even
when the preprocessor isn't run on the input (as it is when compiling
@samp{.F} files).  (Note the distinction between these @command{cpp}
@code{#} @emph{output} directives and @code{#line} @emph{input}
directives.)

@node Data Types and Constants
@section Data Types and Constants

(The following information augments or overrides the information in
Chapter 4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 4 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

To more concisely express the appropriate types for
entities, this document uses the more concise
Fortran 90 nomenclature such as @code{INTEGER(KIND=1)}
instead of the more traditional, but less portably concise,
byte-size-based nomenclature such as @code{INTEGER*4},
wherever reasonable.

When referring to generic types---in contexts where the
specific precision and range of a type are not important---this
document uses the generic type names @code{INTEGER}, @code{LOGICAL},
@code{REAL}, @code{COMPLEX}, and @code{CHARACTER}.

In some cases, the context requires specification of a
particular type.
This document uses the @samp{KIND=} notation to accomplish
this throughout, sometimes supplying the more traditional
notation for clarification, though the traditional notation
might not work the same way on all GNU Fortran implementations.

Use of @samp{KIND=} makes this document more concise because
@command{g77} is able to define values for @samp{KIND=} that
have the same meanings on all systems, due to the way the
Fortran 90 standard specifies these values are to be used.

(In particular, that standard permits an implementation to
arbitrarily assign nonnegative values.
There are four distinct sets of assignments: one to the @code{CHARACTER}
type; one to the @code{INTEGER} type; one to the @code{LOGICAL} type;
and the fourth to both the @code{REAL} and @code{COMPLEX} types.
Implementations are free to assign these values in any order,
leave gaps in the ordering of assignments, and assign more than
one value to a representation.)

This makes @samp{KIND=} values superior to the values used
in non-standard statements such as @samp{INTEGER*4}, because
the meanings of the values in those statements vary from machine
to machine, compiler to compiler, even operating system to
operating system.

However, use of @samp{KIND=} is @emph{not} generally recommended
when writing portable code (unless, for example, the code is
going to be compiled only via @command{g77}, which is a widely
ported compiler).
GNU Fortran does not yet have adequate language constructs to
permit use of @samp{KIND=} in a fashion that would make the
code portable to Fortran 90 implementations; and, this construct
is known to @emph{not} be accepted by many popular FORTRAN 77
implementations, so it cannot be used in code that is to be ported
to those.

The distinction here is that this document is able to use
specific values for @samp{KIND=} to concisely document the
types of various operations and operands.

A Fortran program should use the FORTRAN 77 designations for the
appropriate GNU Fortran types---such as @code{INTEGER} for
@code{INTEGER(KIND=1)}, @code{REAL} for @code{REAL(KIND=1)},
and @code{DOUBLE COMPLEX} for @code{COMPLEX(KIND=2)}---and,
where no such designations exist, make use of appropriate
techniques (preprocessor macros, parameters, and so on)
to specify the types in a fashion that may be easily adjusted
to suit each particular implementation to which the program
is ported.
(These types generally won't need to be adjusted for ports of
@command{g77}.)

Further details regarding GNU Fortran data types and constants
are provided below.

@menu
* Types::
* Constants::
* Integer Type::
* Character Type::
@end menu

@node Types
@subsection Data Types

(Corresponds to Section 4.1 of ANSI X3.9-1978 FORTRAN 77.)

GNU Fortran supports these types:

@enumerate
@item
Integer (generic type @code{INTEGER})

@item
Real (generic type @code{REAL})

@item
Double precision

@item
Complex (generic type @code{COMPLEX})

@item
Logical (generic type @code{LOGICAL})

@item
Character (generic type @code{CHARACTER})

@item
Double Complex
@end enumerate

(The types numbered 1 through 6 above are standard FORTRAN 77 types.)

The generic types shown above are referred to in this document
using only their generic type names.
Such references usually indicate that any specific type (kind)
of that generic type is valid.

For example, a context described in this document as accepting
the @code{COMPLEX} type also is likely to accept the
@code{DOUBLE COMPLEX} type.

The GNU Fortran language supports three ways to specify
a specific kind of a generic type.

@menu
* Double Notation::  As in @code{DOUBLE COMPLEX}.
* Star Notation::    As in @code{INTEGER*4}.
* Kind Notation::    As in @code{INTEGER(KIND=1)}.
@end menu

@node Double Notation
@subsubsection Double Notation

The GNU Fortran language supports two uses of the keyword
@code{DOUBLE} to specify a specific kind of type:

@itemize @bullet
@item
@code{DOUBLE PRECISION}, equivalent to @code{REAL(KIND=2)}

@item
@code{DOUBLE COMPLEX}, equivalent to @code{COMPLEX(KIND=2)}
@end itemize

Use one of the above forms where a type name is valid.

While use of this notation is popular, it doesn't scale
well in a language or dialect rich in intrinsic types,
as is the case for the GNU Fortran language (especially
planned future versions of it).

After all, one rarely sees type names such as @samp{DOUBLE INTEGER},
@samp{QUADRUPLE REAL}, or @samp{QUARTER INTEGER}.
Instead, @code{INTEGER*8}, @code{REAL*16}, and @code{INTEGER*1}
often are substituted for these, respectively, even though they
do not always have the same meanings on all systems.
(And, the fact that @samp{DOUBLE REAL} does not exist as such
is an inconsistency.)

Therefore, this document uses ``double notation'' only on occasion
for the benefit of those readers who are accustomed to it.

@node Star Notation
@subsubsection Star Notation
@cindex *@var{n} notation

The following notation specifies the storage size for a type:

@smallexample
@var{generic-type}*@var{n}
@end smallexample

@noindent
@var{generic-type} must be a generic type---one of
@code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL},
or @code{CHARACTER}.
@var{n} must be one or more digits comprising a decimal
integer number greater than zero.

Use the above form where a type name is valid.

The @samp{*@var{n}} notation specifies that the amount of storage
occupied by variables and array elements of that type is @var{n}
times the storage occupied by a @code{CHARACTER*1} variable.

This notation might indicate a different degree of precision and/or
range for such variables and array elements, and the functions that
return values of types using this notation.
It does not limit the precision or range of values of that type
in any particular way---use explicit code to do that.

Further, the GNU Fortran language requires no particular values
for @var{n} to be supported by an implementation via the @samp{*@var{n}}
notation.
@command{g77} supports @code{INTEGER*1} (as @code{INTEGER(KIND=3)})
on all systems, for example,
but not all implementations are required to do so, and @command{g77}
is known to not support @code{REAL*1} on most (or all) systems.

As a result, except for @var{generic-type} of @code{CHARACTER},
uses of this notation should be limited to isolated
portions of a program that are intended to handle system-specific
tasks and are expected to be non-portable.

(Standard FORTRAN 77 supports the @samp{*@var{n}} notation for
only @code{CHARACTER}, where it signifies not only the amount
of storage occupied, but the number of characters in entities
of that type.
However, almost all Fortran compilers have supported this
notation for generic types, though with a variety of meanings
for @var{n}.)

Specifications of types using the @samp{*@var{n}} notation
always are interpreted as specifications of the appropriate
types described in this document using the @samp{KIND=@var{n}}
notation, described below.

While use of this notation is popular, it doesn't serve well
in the context of a widely portable dialect of Fortran, such as
the GNU Fortran language.

For example, even on one particular machine, two or more popular
Fortran compilers might well disagree on the size of a type
declared @code{INTEGER*2} or @code{REAL*16}.
Certainly there
is known to be disagreement over such things among Fortran
compilers on @emph{different} systems.

Further, this notation offers no elegant way to specify sizes
that are not even multiples of the ``byte size'' typically
designated by @code{INTEGER*1}.
Use of ``absurd'' values (such as @code{INTEGER*1000}) would
certainly be possible, but would perhaps be stretching the original
intent of this notation beyond the breaking point in terms
of widespread readability of documentation and code making use
of it.

Therefore, this document uses ``star notation'' only on occasion
for the benefit of those readers who are accustomed to it.

@node Kind Notation
@subsubsection Kind Notation
@cindex KIND= notation

The following notation specifies the kind-type selector of a type:

@smallexample
@var{generic-type}(KIND=@var{n})
@end smallexample

@noindent
Use the above form where a type name is valid.

@var{generic-type} must be a generic type---one of
@code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL},
or @code{CHARACTER}.
@var{n} must be an integer initialization expression that
is a positive, nonzero value.

Programmers are discouraged from writing these values directly
into their code.
Future versions of the GNU Fortran language will offer
facilities that will make the writing of code portable
to @command{g77} @emph{and} Fortran 90 implementations simpler.

However, writing code that ports to existing FORTRAN 77
implementations depends on avoiding the @samp{KIND=} construct.

The @samp{KIND=} construct is thus useful in the context
of GNU Fortran for two reasons:

@itemize @bullet
@item
It provides a means to specify a type in a fashion that
is portable across all GNU Fortran implementations (though
not other FORTRAN 77 and Fortran 90 implementations).

@item
It provides a sort of Rosetta stone for this document to use
to concisely describe the types of various operations and
operands.
@end itemize

The values of @var{n} in the GNU Fortran language are
assigned using a scheme that:

@itemize @bullet
@item
Attempts to maximize the ability of readers
of this document to quickly familiarize themselves
with assignments for popular types

@item
Provides a unique value for each specific desired
meaning

@item
Provides a means to automatically assign new values so
they have a ``natural'' relationship to existing values,
if appropriate, or, if no such relationship exists, will
not interfere with future values assigned on the basis
of such relationships

@item
Avoids using values that are similar to values used
in the existing, popular @samp{*@var{n}} notation,
to prevent readers from expecting that these implied
correspondences work on all GNU Fortran implementations
@end itemize

The assignment system accomplishes this by assigning
to each ``fundamental meaning'' of a specific type a
unique prime number.
Combinations of fundamental meanings---for example, a type
that is two times the size of some other type---are assigned
values of @var{n} that are the products of the values for
those fundamental meanings.

A prime value of @var{n} is never given more than one fundamental
meaning, to avoid situations where some code or system
cannot reasonably provide those meanings in the form of a
single type.

The values of @var{n} assigned so far are:

@table @code
@item KIND=0
This value is reserved for future use.

The planned future use is for this value to designate,
explicitly, context-sensitive kind-type selection.
For example, the expression @samp{1D0 * 0.1_0} would
be equivalent to @samp{1D0 * 0.1D0}.

@item KIND=1
This corresponds to the default types for
@code{REAL}, @code{INTEGER}, @code{LOGICAL}, @code{COMPLEX},
and @code{CHARACTER}, as appropriate.

These are the ``default'' types described in the Fortran 90 standard,
though that standard does not assign any particular @samp{KIND=}
value to these types.

(Typically, these are @code{REAL*4}, @code{INTEGER*4},
@code{LOGICAL*4}, and @code{COMPLEX*8}.)

@item KIND=2
This corresponds to types that occupy twice as much
storage as the default types.
@code{REAL(KIND=2)} is @code{DOUBLE PRECISION} (typically @code{REAL*8}),
@code{COMPLEX(KIND=2)} is @code{DOUBLE COMPLEX} (typically @code{COMPLEX*16}),

These are the ``double precision'' types described in the Fortran 90
standard,
though that standard does not assign any particular @samp{KIND=}
value to these types.

@var{n} of 4 thus corresponds to types that occupy four times
as much storage as the default types, @var{n} of 8 to types that
occupy eight times as much storage, and so on.

The @code{INTEGER(KIND=2)} and @code{LOGICAL(KIND=2)} types
are not necessarily supported by every GNU Fortran implementation.

@item KIND=3
This corresponds to types that occupy as much
storage as the default @code{CHARACTER} type,
which is the same effective type as @code{CHARACTER(KIND=1)}
(making that type effectively the same as @code{CHARACTER(KIND=3)}).

(Typically, these are @code{INTEGER*1} and @code{LOGICAL*1}.)

@var{n} of 6 thus corresponds to types that occupy twice as
much storage as the @var{n}=3 types, @var{n} of 12 to types
that occupy four times as much storage, and so on.

These are not necessarily supported by every GNU Fortran
implementation.

@item KIND=5
This corresponds to types that occupy half the
storage as the default (@var{n}=1) types.

(Typically, these are @code{INTEGER*2} and @code{LOGICAL*2}.)

@var{n} of 25 thus corresponds to types that occupy one-quarter
as much storage as the default types.

These are not necessarily supported by every GNU Fortran
implementation.

@item KIND=7
@cindex pointers
This is valid only as @code{INTEGER(KIND=7)} and
denotes the @code{INTEGER} type that has the smallest
storage size that holds a pointer on the system.

A pointer representable by this type is capable of uniquely
addressing a @code{CHARACTER*1} variable, array, array element,
or substring.

(Typically this is equivalent to @code{INTEGER*4} or,
on 64-bit systems, @code{INTEGER*8}.
In a compatible C implementation, it typically would
be the same size and semantics of the C type @code{void *}.)
@end table

Note that these are @emph{proposed} correspondences and might change
in future versions of @command{g77}---avoid writing code depending
on them while @command{g77}, and therefore the GNU Fortran language
it defines, is in beta testing.

Values not specified in the above list are reserved to
future versions of the GNU Fortran language.

Implementation-dependent meanings will be assigned new,
unique prime numbers so as to not interfere with other
implementation-dependent meanings, and offer the possibility
of increasing the portability of code depending on such
types by offering support for them in other GNU Fortran
implementations.

Other meanings that might be given unique values are:

@itemize @bullet
@item
Types that make use of only half their storage size for
representing precision and range.

For example, some compilers offer options that cause
@code{INTEGER} types to occupy the amount of storage
that would be needed for @code{INTEGER(KIND=2)} types, but the
range remains that of @code{INTEGER(KIND=1)}.

@item
The IEEE single floating-point type.

@item
Types with a specific bit pattern (endianness), such as the
little-endian form of @code{INTEGER(KIND=1)}.
These could permit, conceptually, use of portable code and
implementations on data files written by existing systems.
@end itemize

Future @emph{prime} numbers should be given meanings in as incremental
a fashion as possible, to allow for flexibility and
expressiveness in combining types.

For example, instead of defining a prime number for little-endian
IEEE doubles, one prime number might be assigned the meaning
``little-endian'', another the meaning ``IEEE double'', and the
value of @var{n} for a little-endian IEEE double would thus
naturally be the product of those two respective assigned values.
(It could even be reasonable to have IEEE values result from the
products of prime values denoting exponent and fraction sizes
and meanings, hidden bit usage, availability and representations
of special values such as subnormals, infinities, and Not-A-Numbers
(NaNs), and so on.)

This assignment mechanism, while not inherently required for
future versions of the GNU Fortran language, is worth using
because it could ease management of the ``space'' of supported
types much easier in the long run.

The above approach suggests a mechanism for specifying inheritance
of intrinsic (built-in) types for an entire, widely portable
product line.
It is certainly reasonable that, unlike programmers of other languages
offering inheritance mechanisms that employ verbose names for classes
and subclasses, along with graphical browsers to elucidate the
relationships, Fortran programmers would employ
a mechanism that works by multiplying prime numbers together
and finding the prime factors of such products.

Most of the advantages for the above scheme have been explained
above.
One disadvantage is that it could lead to the defining,
by the GNU Fortran language, of some fairly large prime numbers.
This could lead to the GNU Fortran language being declared
``munitions'' by the United States Department of Defense.

@node Constants
@subsection Constants
@cindex constants
@cindex types, constants

(Corresponds to Section 4.2 of ANSI X3.9-1978 FORTRAN 77.)

A @dfn{typeless constant} has one of the following forms:

@smallexample
'@var{binary-digits}'B
'@var{octal-digits}'O
'@var{hexadecimal-digits}'Z
'@var{hexadecimal-digits}'X
@end smallexample

@noindent
@var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits}
are nonempty strings of characters in the set @samp{01}, @samp{01234567},
and @samp{0123456789ABCDEFabcdef}, respectively.
(The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b}
is 11, and so on.)

A prefix-radix constant, such as @samp{Z'ABCD'}, can optionally be
treated as typeless.  @xref{Fortran Dialect Options,, Options
Controlling Fortran Dialect}, for information on the
@option{-ftypeless-boz} option.

Typeless constants have values that depend on the context in which
they are used.

All other constants, called @dfn{typed constants}, are interpreted---converted
to internal form---according to their inherent type.
Thus, context is @emph{never} a determining factor for the type, and hence
the interpretation, of a typed constant.
(All constants in the ANSI FORTRAN 77 language are typed constants.)

For example, @samp{1} is always type @code{INTEGER(KIND=1)} in GNU
Fortran (called default INTEGER in Fortran 90),
@samp{9.435784839284958} is always type @code{REAL(KIND=1)} (even if the
additional precision specified is lost, and even when used in a
@code{REAL(KIND=2)} context), @samp{1E0} is always type @code{REAL(KIND=2)},
and @samp{1D0} is always type @code{REAL(KIND=2)}.

@node Integer Type
@subsection Integer Type

(Corresponds to Section 4.3 of ANSI X3.9-1978 FORTRAN 77.)

An integer constant also may have one of the following forms:

@smallexample
B'@var{binary-digits}'
O'@var{octal-digits}'
Z'@var{hexadecimal-digits}'
X'@var{hexadecimal-digits}'
@end smallexample

@noindent
@var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits}
are nonempty strings of characters in the set @samp{01}, @samp{01234567},
and @samp{0123456789ABCDEFabcdef}, respectively.
(The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b}
is 11, and so on.)

@node Character Type
@subsection Character Type

(Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.)

@cindex double quoted character constants
A character constant may be delimited by a pair of double quotes
(@samp{"}) instead of apostrophes.
In this case, an apostrophe within the constant represents
a single apostrophe, while a double quote is represented in
the source text of the constant by two consecutive double
quotes with no intervening spaces.

@cindex zero-length CHARACTER
@cindex null CHARACTER strings
@cindex empty CHARACTER strings
@cindex strings, empty
@cindex CHARACTER, null
A character constant may be empty (have a length of zero).

A character constant may include a substring specification,
The value of such a constant is the value of the substring---for
example, the value of @samp{'hello'(3:5)} is the same
as the value of @samp{'llo'}.

@node Expressions
@section Expressions

(The following information augments or overrides the information in
Chapter 6 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 6 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

@menu
* %LOC()::
@end menu

@node %LOC()
@subsection The @code{%LOC()} Construct
@cindex %LOC() construct

@example
%LOC(@var{arg})
@end example

The @code{%LOC()} construct is an expression
that yields the value of the location of its argument,
@var{arg}, in memory.
The size of the type of the expression depends on the system---typically,
it is equivalent to either @code{INTEGER(KIND=1)} or @code{INTEGER(KIND=2)},
though it is actually type @code{INTEGER(KIND=7)}.

The argument to @code{%LOC()} must be suitable as the
left-hand side of an assignment statement.
That is, it may not be a general expression involving
operators such as addition, subtraction, and so on,
nor may it be a constant.

Use of @code{%LOC()} is recommended only for code that
is accessing facilities outside of GNU Fortran, such as
operating system or windowing facilities.
It is best to constrain such uses to isolated portions of
a program---portions that deal specifically and exclusively
with low-level, system-dependent facilities.
Such portions might well provide a portable interface for
use by the program as a whole, but are themselves not
portable, and should be thoroughly tested each time they
are rebuilt using a new compiler or version of a compiler.

Do not depend on @code{%LOC()} returning a pointer that
can be safely used to @emph{define} (change) the argument.
While this might work in some circumstances, it is hard
to predict whether it will continue to work when a program
(that works using this unsafe behavior)
is recompiled using different command-line options or
a different version of @command{g77}.

Generally, @code{%LOC()} is safe when used as an argument
to a procedure that makes use of the value of the corresponding
dummy argument only during its activation, and only when
such use is restricted to referencing (reading) the value
of the argument to @code{%LOC()}.

@emph{Implementation Note:} Currently, @command{g77} passes
arguments (those not passed using a construct such as @code{%VAL()})
by reference or descriptor, depending on the type of
the actual argument.
Thus, given @samp{INTEGER I}, @samp{CALL FOO(I)} would
seem to mean the same thing as @samp{CALL FOO(%VAL(%LOC(I)))}, and
in fact might compile to identical code.

However, @samp{CALL FOO(%VAL(%LOC(I)))} emphatically means
``pass, by value, the address of @samp{I} in memory''.
While @samp{CALL FOO(I)} might use that same approach in a
particular version of @command{g77}, another version or compiler
might choose a different implementation, such as copy-in/copy-out,
to effect the desired behavior---and which will therefore not
necessarily compile to the same code as would
@samp{CALL FOO(%VAL(%LOC(I)))}
using the same version or compiler.

@xref{Debugging and Interfacing}, for detailed information on
how this particular version of @command{g77} implements various
constructs.

@node Specification Statements
@section Specification Statements

(The following information augments or overrides the information in
Chapter 8 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 8 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

@menu
* NAMELIST::
* DOUBLE COMPLEX::
@end menu

@node NAMELIST
@subsection @code{NAMELIST} Statement
@cindex NAMELIST statement
@cindex statements, NAMELIST

The @code{NAMELIST} statement, and related I/O constructs, are
supported by the GNU Fortran language in essentially the same
way as they are by @command{f2c}.

This follows Fortran 90 with the restriction that on @code{NAMELIST}
input, subscripts must have the form
@smallexample
@var{subscript} [ @code{:} @var{subscript} [ @code{:} @var{stride}]]
@end smallexample
i.e.@:
@smallexample
&xx x(1:3,8:10:2)=1,2,3,4,5,6/
@end smallexample
is allowed, but not, say,
@smallexample
&xx x(:3,8::2)=1,2,3,4,5,6/
@end smallexample

As an extension of the Fortran 90 form, @code{$} and @code{$END} may be
used in place of @code{&} and @code{/} in @code{NAMELIST} input, so that
@smallexample
$&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end
@end smallexample
could be used instead of the example above.

@node DOUBLE COMPLEX
@subsection @code{DOUBLE COMPLEX} Statement
@cindex DOUBLE COMPLEX

@code{DOUBLE COMPLEX} is a type-statement (and type) that
specifies the type @code{COMPLEX(KIND=2)} in GNU Fortran.

@node Control Statements
@section Control Statements

(The following information augments or overrides the information in
Chapter 11 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 11 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

@menu
* DO WHILE::
* END DO::
* Construct Names::
* CYCLE and EXIT::
@end menu

@node DO WHILE
@subsection DO WHILE
@cindex DO WHILE
@cindex DO
@cindex MIL-STD 1753

The @code{DO WHILE} statement, a feature of both the MIL-STD 1753 and
Fortran 90 standards, is provided by the GNU Fortran language.
The Fortran 90 ``do forever'' statement comprising just @code{DO} is
also supported.

@node END DO
@subsection END DO
@cindex END DO
@cindex MIL-STD 1753

The @code{END DO} statement is provided by the GNU Fortran language.

This statement is used in one of two ways:

@itemize @bullet
@item
The Fortran 90 meaning, in which it specifies the termination
point of a single @code{DO} loop started with a @code{DO} statement
that specifies no termination label.

@item
The MIL-STD 1753 meaning, in which it specifies the termination
point of one or more @code{DO} loops, all of which start with a
@code{DO} statement that specify the label defined for the
@code{END DO} statement.

This kind of @code{END DO} statement is merely a synonym for
@code{CONTINUE}, except it is permitted only when the statement
is labeled and a target of one or more labeled @code{DO} loops.

It is expected that this use of @code{END DO} will be removed from
the GNU Fortran language in the future, though it is likely that
it will long be supported by @command{g77} as a dialect form.
@end itemize

@node Construct Names
@subsection Construct Names
@cindex construct names

The GNU Fortran language supports construct names as defined
by the Fortran 90 standard.
These names are local to the program unit and are defined
as follows:

@smallexample
@var{construct-name}: @var{block-statement}
@end smallexample

@noindent
Here, @var{construct-name} is the construct name itself;
its definition is connoted by the single colon (@samp{:}); and
@var{block-statement} is an @code{IF}, @code{DO},
or @code{SELECT CASE} statement that begins a block.

A block that is given a construct name must also specify the
same construct name in its termination statement:

@example
END @var{block} @var{construct-name}
@end example

@noindent
Here, @var{block} must be @code{IF}, @code{DO}, or @code{SELECT},
as appropriate.

@node CYCLE and EXIT
@subsection The @code{CYCLE} and @code{EXIT} Statements

@cindex CYCLE statement
@cindex EXIT statement
@cindex statements, CYCLE
@cindex statements, EXIT
The @code{CYCLE} and @code{EXIT} statements specify that
the remaining statements in the current iteration of a
particular active (enclosing) @code{DO} loop are to be skipped.

@code{CYCLE} specifies that these statements are skipped,
but the @code{END DO} statement that marks the end of the
@code{DO} loop be executed---that is, the next iteration,
if any, is to be started.
If the statement marking the end of the @code{DO} loop is
not @code{END DO}---in other words, if the loop is not
a block @code{DO}---the @code{CYCLE} statement does not
execute that statement, but does start the next iteration (if any).

@code{EXIT} specifies that the loop specified by the
@code{DO} construct is terminated.

The @code{DO} loop affected by @code{CYCLE} and @code{EXIT}
is the innermost enclosing @code{DO} loop when the following
forms are used:

@example
CYCLE
EXIT
@end example

Otherwise, the following forms specify the construct name
of the pertinent @code{DO} loop:

@example
CYCLE @var{construct-name}
EXIT @var{construct-name}
@end example

@code{CYCLE} and @code{EXIT} can be viewed as glorified @code{GO TO}
statements.
However, they cannot be easily thought of as @code{GO TO} statements
in obscure cases involving FORTRAN 77 loops.
For example:

@smallexample
      DO 10 I = 1, 5
      DO 10 J = 1, 5
         IF (J .EQ. 5) EXIT
      DO 10 K = 1, 5
         IF (K .EQ. 3) CYCLE
10    PRINT *, 'I=', I, ' J=', J, ' K=', K
20    CONTINUE
@end smallexample

@noindent
In particular, neither the @code{EXIT} nor @code{CYCLE} statements
above are equivalent to a @code{GO TO} statement to either label
@samp{10} or @samp{20}.

To understand the effect of @code{CYCLE} and @code{EXIT} in the
above fragment, it is helpful to first translate it to its equivalent
using only block @code{DO} loops:

@smallexample
      DO I = 1, 5
         DO J = 1, 5
            IF (J .EQ. 5) EXIT
            DO K = 1, 5
               IF (K .EQ. 3) CYCLE
10             PRINT *, 'I=', I, ' J=', J, ' K=', K
            END DO
         END DO
      END DO
20    CONTINUE
@end smallexample

Adding new labels allows translation of @code{CYCLE} and @code{EXIT}
to @code{GO TO} so they may be more easily understood by programmers
accustomed to FORTRAN coding:

@smallexample
      DO I = 1, 5
         DO J = 1, 5
            IF (J .EQ. 5) GOTO 18
            DO K = 1, 5
               IF (K .EQ. 3) GO TO 12
10             PRINT *, 'I=', I, ' J=', J, ' K=', K
12          END DO
         END DO
18    END DO
20    CONTINUE
@end smallexample

@noindent
Thus, the @code{CYCLE} statement in the innermost loop skips over
the @code{PRINT} statement as it begins the next iteration of the
loop, while the @code{EXIT} statement in the middle loop ends that
loop but @emph{not} the outermost loop.

@node Functions and Subroutines
@section Functions and Subroutines

(The following information augments or overrides the information in
Chapter 15 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 15 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

@menu
* %VAL()::
* %REF()::
* %DESCR()::
* Generics and Specifics::
* REAL() and AIMAG() of Complex::
* CMPLX() of DOUBLE PRECISION::
* MIL-STD 1753::
* f77/f2c Intrinsics::
* Table of Intrinsic Functions::
@end menu

@node %VAL()
@subsection The @code{%VAL()} Construct
@cindex %VAL() construct

@example
%VAL(@var{arg})
@end example

The @code{%VAL()} construct specifies that an argument,
@var{arg}, is to be passed by value, instead of by reference
or descriptor.

@code{%VAL()} is restricted to actual arguments in
invocations of external procedures.

Use of @code{%VAL()} is recommended only for code that
is accessing facilities outside of GNU Fortran, such as
operating system or windowing facilities.
It is best to constrain such uses to isolated portions of
a program---portions the deal specifically and exclusively
with low-level, system-dependent facilities.
Such portions might well provide a portable interface for
use by the program as a whole, but are themselves not
portable, and should be thoroughly tested each time they
are rebuilt using a new compiler or version of a compiler.

@emph{Implementation Note:} Currently, @command{g77} passes
all arguments either by reference or by descriptor.

Thus, use of @code{%VAL()} tends to be restricted to cases
where the called procedure is written in a language other
than Fortran that supports call-by-value semantics.
(C is an example of such a language.)

@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)},
for detailed information on
how this particular version of @command{g77} passes arguments
to procedures.

@node %REF()
@subsection The @code{%REF()} Construct
@cindex %REF() construct

@example
%REF(@var{arg})
@end example

The @code{%REF()} construct specifies that an argument,
@var{arg}, is to be passed by reference, instead of by
value or descriptor.

@code{%REF()} is restricted to actual arguments in
invocations of external procedures.

Use of @code{%REF()} is recommended only for code that
is accessing facilities outside of GNU Fortran, such as
operating system or windowing facilities.
It is best to constrain such uses to isolated portions of
a program---portions the deal specifically and exclusively
with low-level, system-dependent facilities.
Such portions might well provide a portable interface for
use by the program as a whole, but are themselves not
portable, and should be thoroughly tested each time they
are rebuilt using a new compiler or version of a compiler.

Do not depend on @code{%REF()} supplying a pointer to the
procedure being invoked.
While that is a likely implementation choice, other
implementation choices are available that preserve Fortran
pass-by-reference semantics without passing a pointer to
the argument, @var{arg}.
(For example, a copy-in/copy-out implementation.)

@emph{Implementation Note:} Currently, @command{g77} passes
all arguments
(other than variables and arrays of type @code{CHARACTER})
by reference.
Future versions of, or dialects supported by, @command{g77} might
not pass @code{CHARACTER} functions by reference.

Thus, use of @code{%REF()} tends to be restricted to cases
where @var{arg} is type @code{CHARACTER} but the called
procedure accesses it via a means other than the method
used for Fortran @code{CHARACTER} arguments.

@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on
how this particular version of @command{g77} passes arguments
to procedures.

@node %DESCR()
@subsection The @code{%DESCR()} Construct
@cindex %DESCR() construct

@example
%DESCR(@var{arg})
@end example

The @code{%DESCR()} construct specifies that an argument,
@var{arg}, is to be passed by descriptor, instead of by
value or reference.

@code{%DESCR()} is restricted to actual arguments in
invocations of external procedures.

Use of @code{%DESCR()} is recommended only for code that
is accessing facilities outside of GNU Fortran, such as
operating system or windowing facilities.
It is best to constrain such uses to isolated portions of
a program---portions the deal specifically and exclusively
with low-level, system-dependent facilities.
Such portions might well provide a portable interface for
use by the program as a whole, but are themselves not
portable, and should be thoroughly tested each time they
are rebuilt using a new compiler or version of a compiler.

Do not depend on @code{%DESCR()} supplying a pointer
and/or a length passed by value
to the procedure being invoked.
While that is a likely implementation choice, other
implementation choices are available that preserve the
pass-by-reference semantics without passing a pointer to
the argument, @var{arg}.
(For example, a copy-in/copy-out implementation.)
And, future versions of @command{g77} might change the
way descriptors are implemented, such as passing a
single argument pointing to a record containing the
pointer/length information instead of passing that same
information via two arguments as it currently does.

@emph{Implementation Note:} Currently, @command{g77} passes
all variables and arrays of type @code{CHARACTER}
by descriptor.
Future versions of, or dialects supported by, @command{g77} might
pass @code{CHARACTER} functions by descriptor as well.

Thus, use of @code{%DESCR()} tends to be restricted to cases
where @var{arg} is not type @code{CHARACTER} but the called
procedure accesses it via a means similar to the method
used for Fortran @code{CHARACTER} arguments.

@xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on
how this particular version of @command{g77} passes arguments
to procedures.

@node Generics and Specifics
@subsection Generics and Specifics
@cindex generic intrinsics
@cindex intrinsics, generic

The ANSI FORTRAN 77 language defines generic and specific
intrinsics.
In short, the distinctions are:

@itemize @bullet
@item
@emph{Specific} intrinsics have
specific types for their arguments and a specific return
type.

@item
@emph{Generic} intrinsics are treated,
on a case-by-case basis in the program's source code,
as one of several possible specific intrinsics.

Typically, a generic intrinsic has a return type that
is determined by the type of one or more of its arguments.
@end itemize

The GNU Fortran language generalizes these concepts somewhat,
especially by providing intrinsic subroutines and generic
intrinsics that are treated as either a specific intrinsic subroutine
or a specific intrinsic function (e.g. @code{SECOND}).

However, GNU Fortran avoids generalizing this concept to
the point where existing code would be accepted as meaning
something possibly different than what was intended.

For example, @code{ABS} is a generic intrinsic, so all working
code written using @code{ABS} of an @code{INTEGER} argument
expects an @code{INTEGER} return value.
Similarly, all such code expects that @code{ABS} of an @code{INTEGER*2}
argument returns an @code{INTEGER*2} return value.

Yet, @code{IABS} is a @emph{specific} intrinsic that accepts only
an @code{INTEGER(KIND=1)} argument.
Code that passes something other than an @code{INTEGER(KIND=1)}
argument to @code{IABS} is not valid GNU Fortran code, because
it is not clear what the author intended.

For example, if @samp{J} is @code{INTEGER(KIND=6)}, @samp{IABS(J)}
is not defined by the GNU Fortran language, because the programmer
might have used that construct to mean any of the following, subtly
different, things:

@itemize @bullet
@item
Convert @samp{J} to @code{INTEGER(KIND=1)} first
(as if @samp{IABS(INT(J))} had been written).

@item
Convert the result of the intrinsic to @code{INTEGER(KIND=1)}
(as if @samp{INT(ABS(J))} had been written).

@item
No conversion (as if @samp{ABS(J)} had been written).
@end itemize

The distinctions matter especially when types and values wider than
@code{INTEGER(KIND=1)} (such as @code{INTEGER(KIND=2)}), or when
operations performing more ``arithmetic'' than absolute-value, are involved.

The following sample program is not a valid GNU Fortran program, but
might be accepted by other compilers.
If so, the output is likely to be revealing in terms of how a given
compiler treats intrinsics (that normally are specific) when they
are given arguments that do not conform to their stated requirements:

@cindex JCB002 program
@smallexample
      PROGRAM JCB002
C Version 1:
C Modified 1999-02-15 (Burley) to delete my email address.
C Modified 1997-05-21 (Burley) to accommodate compilers that implement
C INT(I1-I2) as INT(I1)-INT(I2) given INTEGER*2 I1,I2.
C
C Version 0:
C Written by James Craig Burley 1997-02-20.
C
C Purpose:
C Determine how compilers handle non-standard IDIM
C on INTEGER*2 operands, which presumably can be
C extrapolated into understanding how the compiler
C generally treats specific intrinsics that are passed
C arguments not of the correct types.
C
C If your compiler implements INTEGER*2 and INTEGER
C as the same type, change all INTEGER*2 below to
C INTEGER*1.
C
      INTEGER*2 I0, I4
      INTEGER I1, I2, I3
      INTEGER*2 ISMALL, ILARGE
      INTEGER*2 ITOOLG, ITWO
      INTEGER*2 ITMP
      LOGICAL L2, L3, L4
C
C Find smallest INTEGER*2 number.
C
      ISMALL=0
 10   I0 = ISMALL-1
      IF ((I0 .GE. ISMALL) .OR. (I0+1 .NE. ISMALL)) GOTO 20
      ISMALL = I0
      GOTO 10
 20   CONTINUE
C
C Find largest INTEGER*2 number.
C
      ILARGE=0
 30   I0 = ILARGE+1
      IF ((I0 .LE. ILARGE) .OR. (I0-1 .NE. ILARGE)) GOTO 40
      ILARGE = I0
      GOTO 30
 40   CONTINUE
C
C Multiplying by two adds stress to the situation.
C
      ITWO = 2
C
C Need a number that, added to -2, is too wide to fit in I*2.
C
      ITOOLG = ISMALL
C
C Use IDIM the straightforward way.
C
      I1 = IDIM (ILARGE, ISMALL) * ITWO + ITOOLG
C
C Calculate result for first interpretation.
C
      I2 = (INT (ILARGE) - INT (ISMALL)) * ITWO + ITOOLG
C
C Calculate result for second interpretation.
C
      ITMP = ILARGE - ISMALL
      I3 = (INT (ITMP)) * ITWO + ITOOLG
C
C Calculate result for third interpretation.
C
      I4 = (ILARGE - ISMALL) * ITWO + ITOOLG
C
C Print results.
C
      PRINT *, 'ILARGE=', ILARGE
      PRINT *, 'ITWO=', ITWO
      PRINT *, 'ITOOLG=', ITOOLG
      PRINT *, 'ISMALL=', ISMALL
      PRINT *, 'I1=', I1
      PRINT *, 'I2=', I2
      PRINT *, 'I3=', I3
      PRINT *, 'I4=', I4
      PRINT *
      L2 = (I1 .EQ. I2)
      L3 = (I1 .EQ. I3)
      L4 = (I1 .EQ. I4)
      IF (L2 .AND. .NOT.L3 .AND. .NOT.L4) THEN
         PRINT *, 'Interp 1: IDIM(I*2,I*2) => IDIM(INT(I*2),INT(I*2))'
         STOP
      END IF
      IF (L3 .AND. .NOT.L2 .AND. .NOT.L4) THEN
         PRINT *, 'Interp 2: IDIM(I*2,I*2) => INT(DIM(I*2,I*2))'
         STOP
      END IF
      IF (L4 .AND. .NOT.L2 .AND. .NOT.L3) THEN
         PRINT *, 'Interp 3: IDIM(I*2,I*2) => DIM(I*2,I*2)'
         STOP
      END IF
      PRINT *, 'Results need careful analysis.'
      END
@end smallexample

No future version of the GNU Fortran language
will likely permit specific intrinsic invocations with wrong-typed
arguments (such as @code{IDIM} in the above example), since
it has been determined that disagreements exist among
many production compilers on the interpretation of
such invocations.
These disagreements strongly suggest that Fortran programmers,
and certainly existing Fortran programs, disagree about the
meaning of such invocations.

The first version of @code{JCB002} didn't accommodate some compilers'
treatment of @samp{INT(I1-I2)} where @samp{I1} and @samp{I2} are
@code{INTEGER*2}.
In such a case, these compilers apparently convert both
operands to @code{INTEGER*4} and then do an @code{INTEGER*4} subtraction,
instead of doing an @code{INTEGER*2} subtraction on the
original values in @samp{I1} and @samp{I2}.

However, the results of the careful analyses done on the outputs
of programs compiled by these various compilers show that they
all implement either @samp{Interp 1} or @samp{Interp 2} above.

Specifically, it is believed that the new version of @code{JCB002}
above will confirm that:

@itemize @bullet
@item
Digital Semiconductor (``DEC'') Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5
@command{f77} compilers all implement @samp{Interp 1}.

@item
IRIX 5.3 @command{f77} compiler implements @samp{Interp 2}.

@item
Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3,
and IRIX 6.1 @command{f77} compilers all implement @samp{Interp 3}.
@end itemize

If you get different results than the above for the stated
compilers, or have results for other compilers that might be
worth adding to the above list, please let us know the details
(compiler product, version, machine, results, and so on).

@node REAL() and AIMAG() of Complex
@subsection @code{REAL()} and @code{AIMAG()} of Complex
@cindex @code{Real} intrinsic
@cindex intrinsics, @code{Real}
@cindex @code{AImag} intrinsic
@cindex intrinsics, @code{AImag}

The GNU Fortran language disallows @code{REAL(@var{expr})}
and @code{AIMAG(@var{expr})},
where @var{expr} is any @code{COMPLEX} type other than @code{COMPLEX(KIND=1)},
except when they are used in the following way:

@example
REAL(REAL(@var{expr}))
REAL(AIMAG(@var{expr}))
@end example

@noindent
The above forms explicitly specify that the desired effect
is to convert the real or imaginary part of @var{expr}, which might
be some @code{REAL} type other than @code{REAL(KIND=1)},
to type @code{REAL(KIND=1)},
and have that serve as the value of the expression.

The GNU Fortran language offers clearly named intrinsics to extract the
real and imaginary parts of a complex entity without any
conversion:

@example
REALPART(@var{expr})
IMAGPART(@var{expr})
@end example

To express the above using typical extended FORTRAN 77,
use the following constructs
(when @var{expr} is @code{COMPLEX(KIND=2)}):

@example
DBLE(@var{expr})
DIMAG(@var{expr})
@end example

The FORTRAN 77 language offers no way
to explicitly specify the real and imaginary parts of a complex expression of
arbitrary type, apparently as a result of requiring support for
only one @code{COMPLEX} type (@code{COMPLEX(KIND=1)}).
The concepts of converting an expression to type @code{REAL(KIND=1)} and
of extracting the real part of a complex expression were
thus ``smooshed'' by FORTRAN 77 into a single intrinsic, since
they happened to have the exact same effect in that language
(due to having only one @code{COMPLEX} type).

@emph{Note:} When @option{-ff90} is in effect,
@command{g77} treats @samp{REAL(@var{expr})}, where @var{expr} is of
type @code{COMPLEX}, as @samp{REALPART(@var{expr})},
whereas with @samp{-fugly-complex -fno-f90} in effect, it is
treated as @samp{REAL(REALPART(@var{expr}))}.

@xref{Ugly Complex Part Extraction}, for more information.

@node CMPLX() of DOUBLE PRECISION
@subsection @code{CMPLX()} of @code{DOUBLE PRECISION}
@cindex @code{Cmplx} intrinsic
@cindex intrinsics, @code{Cmplx}

In accordance with Fortran 90 and at least some (perhaps all)
other compilers, the GNU Fortran language defines @code{CMPLX()}
as always returning a result that is type @code{COMPLEX(KIND=1)}.

This means @samp{CMPLX(D1,D2)}, where @samp{D1} and @samp{D2}
are @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}), is treated as:

@example
CMPLX(SNGL(D1), SNGL(D2))
@end example

(It was necessary for Fortran 90 to specify this behavior
for @code{DOUBLE PRECISION} arguments, since that is
the behavior mandated by FORTRAN 77.)

The GNU Fortran language also provides the @code{DCMPLX()} intrinsic,
which is provided by some FORTRAN 77 compilers to construct
a @code{DOUBLE COMPLEX} entity from of @code{DOUBLE PRECISION}
operands.
However, this solution does not scale well when more @code{COMPLEX} types
(having various precisions and ranges) are offered by Fortran implementations.

Fortran 90 extends the @code{CMPLX()} intrinsic by adding
an extra argument used to specify the desired kind of complex
result.
However, this solution is somewhat awkward to use, and
@command{g77} currently does not support it.

The GNU Fortran language provides a simple way to build a complex
value out of two numbers, with the precise type of the value
determined by the types of the two numbers (via the usual
type-promotion mechanism):

@example
COMPLEX(@var{real}, @var{imag})
@end example

When @var{real} and @var{imag} are the same @code{REAL} types, @code{COMPLEX()}
performs no conversion other than to put them together to form a
complex result of the same (complex version of real) type.

@xref{Complex Intrinsic}, for more information.

@node MIL-STD 1753
@subsection MIL-STD 1753 Support
@cindex MIL-STD 1753

The GNU Fortran language includes the MIL-STD 1753 intrinsics
@code{BTEST}, @code{IAND}, @code{IBCLR}, @code{IBITS},
@code{IBSET}, @code{IEOR}, @code{IOR}, @code{ISHFT},
@code{ISHFTC}, @code{MVBITS}, and @code{NOT}.

@node f77/f2c Intrinsics
@subsection @command{f77}/@command{f2c} Intrinsics

The bit-manipulation intrinsics supported by traditional
@command{f77} and by @command{f2c} are available in the GNU Fortran language.
These include @code{AND}, @code{LSHIFT}, @code{OR}, @code{RSHIFT},
and @code{XOR}.

Also supported are the intrinsics @code{CDABS},
@code{CDCOS}, @code{CDEXP}, @code{CDLOG}, @code{CDSIN},
@code{CDSQRT}, @code{DCMPLX}, @code{DCONJG}, @code{DFLOAT},
@code{DIMAG}, @code{DREAL}, and @code{IMAG},
@code{ZABS}, @code{ZCOS}, @code{ZEXP}, @code{ZLOG}, @code{ZSIN},
and @code{ZSQRT}.

@node Table of Intrinsic Functions
@subsection Table of Intrinsic Functions
@cindex intrinsics, table of
@cindex table of intrinsics

(Corresponds to Section 15.10 of ANSI X3.9-1978 FORTRAN 77.)

The GNU Fortran language adds various functions, subroutines, types,
and arguments to the set of intrinsic functions in ANSI FORTRAN 77.
The complete set of intrinsics supported by the GNU Fortran language
is described below.

Note that a name is not treated as that of an intrinsic if it is
specified in an @code{EXTERNAL} statement in the same program unit;
if a command-line option is used to disable the groups to which
the intrinsic belongs; or if the intrinsic is not named in an
@code{INTRINSIC} statement and a command-line option is used to
hide the groups to which the intrinsic belongs.

So, it is recommended that any reference in a program unit to
an intrinsic procedure that is not a standard FORTRAN 77
intrinsic be accompanied by an appropriate @code{INTRINSIC}
statement in that program unit.
This sort of defensive programming makes it more
likely that an implementation will issue a diagnostic rather
than generate incorrect code for such a reference.

The terminology used below is based on that of the Fortran 90
standard, so that the text may be more concise and accurate:

@itemize @bullet
@item
@code{OPTIONAL} means the argument may be omitted.

@item
@samp{A-1, A-2, @dots{}, A-n} means more than one argument
(generally named @samp{A}) may be specified.

@item
@samp{scalar} means the argument must not be an array (must
be a variable or array element, or perhaps a constant if expressions
are permitted).

@item
@samp{DIMENSION(4)} means the argument must be an array having 4 elements.

@item
@code{INTENT(IN)} means the argument must be an expression
(such as a constant or a variable that is defined upon invocation
of the intrinsic).

@item
@code{INTENT(OUT)} means the argument must be definable by the
invocation of the intrinsic (that is, must not be a constant nor
an expression involving operators other than array reference and
substring reference).

@item
@code{INTENT(INOUT)} means the argument must be defined prior to,
and definable by, invocation of the intrinsic (a combination of
the requirements of @code{INTENT(IN)} and @code{INTENT(OUT)}.

@item
@xref{Kind Notation}, for an explanation of @code{KIND}.
@end itemize

@ifinfo
(Note that the empty lines appearing in the menu below
are not intentional---they result from a bug in the
GNU @command{makeinfo} program@dots{}a program that, if it
did not exist, would leave this document in far worse shape!)
@end ifinfo

@c The actual documentation for intrinsics comes from
@c intdoc.texi, which in turn is automatically generated
@c from the internal g77 tables in intrin.def _and_ the
@c largely hand-written text in intdoc.h.  So, if you want
@c to change or add to existing documentation on intrinsics,
@c you probably want to edit intdoc.h.
@c
@set familyF77
@set familyGNU
@set familyASC
@set familyMIL
@set familyF90
@clear familyVXT
@clear familyFVZ
@set familyF2C
@set familyF2U
@clear familyBADU77
@include intdoc.texi

@node Scope and Classes of Names
@section Scope and Classes of Symbolic Names
@cindex symbol names, scope and classes
@cindex scope

(The following information augments or overrides the information in
Chapter 18 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran
language.
Chapter 18 of that document otherwise serves as the basis
for the relevant aspects of GNU Fortran.)

@menu
* Underscores in Symbol Names::
@end menu

@node Underscores in Symbol Names
@subsection Underscores in Symbol Names
@cindex underscore

Underscores (@samp{_}) are accepted in symbol names after the first
character (which must be a letter).

@node I/O
@section I/O

@cindex dollar sign
A dollar sign at the end of an output format specification suppresses
the newline at the end of the output.

@cindex <> edit descriptor
@cindex edit descriptor, <>
Edit descriptors in @code{FORMAT} statements may contain compile-time
@code{INTEGER} constant expressions in angle brackets, such as
@smallexample
10    FORMAT (I<WIDTH>)
@end smallexample

The @code{OPEN} specifier @code{NAME=} is equivalent to @code{FILE=}.

These Fortran 90 features are supported:
@itemize @bullet
@item
@cindex FORMAT descriptors
@cindex Z edit descriptor
@cindex edit descriptor, Z
@cindex O edit descriptor
@cindex edit descriptor, O
The @code{O} and @code{Z} edit descriptors are supported for I/O of
integers in octal and hexadecimal formats, respectively.
@item
The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
@code{STATUS='SCRATCH'} is supplied.  The @code{STATUS='REPLACE'}
specifier is supported.
@end itemize

@node Fortran 90 Features
@section Fortran 90 Features
@cindex Fortran 90
@cindex extensions, from Fortran 90

For convenience this section collects a list (probably incomplete) of
the Fortran 90 features supported by the GNU Fortran language, even if
they are documented elsewhere.
@xref{Characters Lines Sequence,,@asis{Characters, Lines, and Execution Sequence}},
for information on additional fixed source form lexical issues.
@cindex @option{-ffree-form}
Further, the free source form is supported through the
@option{-ffree-form} option.
@cindex @option{-ff90}
Other Fortran 90 features can be turned on by the @option{-ff90} option;
see @ref{Fortran 90}.
For information on the Fortran 90 intrinsics available,
see @ref{Table of Intrinsic Functions}.

@table @asis
@item Automatic arrays in procedures
@item Character assignments
@cindex character assignments
In character assignments, the variable being assigned may occur on the
right hand side of the assignment.
@item Character strings
@cindex double quoted character constants
Strings may have zero length and substrings of character constants are
permitted.  Character constants may be enclosed in double quotes
(@code{"}) as well as single quotes.  @xref{Character Type}.
@item Construct names
(Symbolic tags on blocks.)  @xref{Construct Names}.
@item @code{CYCLE} and @code{EXIT}
@xref{CYCLE and EXIT,,The @code{CYCLE} and @code{EXIT} Statements}.
@item @code{DOUBLE COMPLEX}
@xref{DOUBLE COMPLEX,,@code{DOUBLE COMPLEX} Statement}.
@item @code{DO WHILE}
@xref{DO WHILE}.
@item @code{END} decoration
@xref{Statements}.
@item @code{END DO}
@xref{END DO}.
@item @code{KIND}
@item @code{IMPLICIT NONE}
@item @code{INCLUDE} statements
@xref{INCLUDE}.
@item List-directed and namelist I/O on internal files
@item Binary, octal and hexadecimal constants
These are supported more generally than required by Fortran 90.
@xref{Integer Type}.
@item @samp{O} and @samp{Z} edit descriptors
@item @code{NAMELIST}
@xref{NAMELIST}.
@item @code{OPEN} specifiers
@code{STATUS='REPLACE'} is supported.
The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
@code{STATUS='SCRATCH'} is supplied.
@item @code{FORMAT} edit descriptors
@cindex FORMAT descriptors
@cindex Z edit descriptor
@cindex edit descriptor, Z
The @code{Z} edit descriptor is supported.
@item Relational operators
The operators @code{<}, @code{<=}, @code{==}, @code{/=}, @code{>} and
@code{>=} may be used instead of @code{.LT.}, @code{.LE.}, @code{.EQ.},
@code{.NE.}, @code{.GT.} and @code{.GE.} respectively.
@item @code{SELECT CASE}
Not fully implemented.
@xref{SELECT CASE on CHARACTER Type,, @code{SELECT CASE} on @code{CHARACTER} Type}.
@item Specification statements
A limited subset of the Fortran 90 syntax and semantics for variable
declarations is supported, including @code{KIND}.  @xref{Kind Notation}.
(@code{KIND} is of limited usefulness in the absence of the
@code{KIND}-related intrinsics, since these intrinsics permit writing
more widely portable code.)  An example of supported @code{KIND} usage
is:
@smallexample
INTEGER (KIND=1) :: FOO=1, BAR=2
CHARACTER (LEN=3) FOO
@end smallexample
@code{PARAMETER} and @code{DIMENSION} attributes aren't supported.
@end table

@node Other Dialects
@chapter Other Dialects

GNU Fortran supports a variety of features that are not
considered part of the GNU Fortran language itself, but
are representative of various dialects of Fortran that
@command{g77} supports in whole or in part.

Any of the features listed below might be disallowed by
@command{g77} unless some command-line option is specified.
Currently, some of the features are accepted using the
default invocation of @command{g77}, but that might change
in the future.

@emph{Note: This portion of the documentation definitely needs a lot
of work!}

@menu
* Source Form::       Details of fixed-form and free-form source.
* Trailing Comment::  Use of @samp{/*} to start a comment.
* Debug Line::        Use of @samp{D} in column 1.
* Dollar Signs::      Use of @samp{$} in symbolic names.
* Case Sensitivity::  Uppercase and lowercase in source files.
* VXT Fortran::       @dots{}versus the GNU Fortran language.
* Fortran 90::        @dots{}versus the GNU Fortran language.
* Pedantic Compilation::  Enforcing the standard.
* Distensions::       Misfeatures supported by GNU Fortran.
@end menu

@node Source Form
@section Source Form
@cindex source file format
@cindex source format
@cindex file, source
@cindex source code
@cindex code, source
@cindex fixed form
@cindex free form

GNU Fortran accepts programs written in either fixed form or
free form.

Fixed form
corresponds to ANSI FORTRAN 77 (plus popular extensions, such as
allowing tabs) and Fortran 90's fixed form.

Free form corresponds to
Fortran 90's free form (though possibly not entirely up-to-date, and
without complaining about some things that for which Fortran 90 requires
diagnostics, such as the spaces in the constant in @samp{R = 3 . 1}).

The way a Fortran compiler views source files depends entirely on the
implementation choices made for the compiler, since those choices
are explicitly left to the implementation by the published Fortran
standards.
GNU Fortran currently tries to be somewhat like a few popular compilers
(@command{f2c}, Digital (``DEC'') Fortran, and so on).

This section describes how @command{g77} interprets source lines.

@menu
* Carriage Returns::  Carriage returns ignored.
* Tabs::              Tabs converted to spaces.
* Short Lines::       Short lines padded with spaces (fixed-form only).
* Long Lines::        Long lines truncated.
* Ampersands::        Special Continuation Lines.
@end menu

@node Carriage Returns
@subsection Carriage Returns
@cindex carriage returns

Carriage returns (@samp{\r}) in source lines are ignored.
This is somewhat different from @command{f2c}, which seems to treat them as
spaces outside character/Hollerith constants, and encodes them as @samp{\r}
inside such constants.

@node Tabs
@subsection Tabs
@cindex tab character
@cindex horizontal tab

A source line with a @key{TAB} character anywhere in it is treated as
entirely significant---however long it is---instead of ending in
column 72 (for fixed-form source) or 132 (for free-form source).
This also is different from @command{f2c}, which encodes tabs as
@samp{\t} (the ASCII @key{TAB} character) inside character
and Hollerith constants, but nevertheless seems to treat the column
position as if it had been affected by the canonical tab positioning.

@command{g77} effectively
translates tabs to the appropriate number of spaces (a la the default
for the UNIX @command{expand} command) before doing any other processing, other
than (currently) noting whether a tab was found on a line and using this
information to decide how to interpret the length of the line and continued
constants.

@node Short Lines
@subsection Short Lines
@cindex short source lines
@cindex space, padding with
@cindex source lines, short
@cindex lines, short

Source lines shorter than the applicable fixed-form length are treated as
if they were padded with spaces to that length.
(None of this is relevant to source files written in free form.)

This affects only
continued character and Hollerith constants, and is a different
interpretation than provided by some other popular compilers
(although a bit more consistent with the traditional punched-card
basis of Fortran and the way the Fortran standard expressed fixed
source form).

@command{g77} might someday offer an option to warn about cases where differences
might be seen as a result of this treatment, and perhaps an option to
specify the alternate behavior as well.

Note that this padding cannot apply to lines that are effectively of
infinite length---such lines are specified using command-line options
like @option{-ffixed-line-length-none}, for example.

@node Long Lines
@subsection Long Lines
@cindex long source lines
@cindex truncation, of long lines
@cindex lines, long
@cindex source lines, long

Source lines longer than the applicable length are truncated to that
length.
Currently, @command{g77} does not warn if the truncated characters are
not spaces, to accommodate existing code written for systems that
treated truncated text as commentary (especially in columns 73 through 80).

@xref{Fortran Dialect Options,,Options Controlling Fortran Dialect},
for information on the @option{-ffixed-line-length-@var{n}} option,
which can be used to set the line length applicable to fixed-form
source files.

@node Ampersands
@subsection Ampersand Continuation Line
@cindex ampersand continuation line
@cindex continuation line, ampersand

A @samp{&} in column 1 of fixed-form source denotes an arbitrary-length
continuation line, imitating the behavior of @command{f2c}.

@node Trailing Comment
@section Trailing Comment

@cindex trailing comment
@cindex comment
@cindex characters, comment
@cindex /*
@cindex !
@cindex exclamation point
@command{g77} supports use of @samp{/*} to start a trailing
comment.
In the GNU Fortran language, @samp{!} is used for this purpose.

@samp{/*} is not in the GNU Fortran language
because the use of @samp{/*} in a program might
suggest to some readers that a block, not trailing, comment is
started (and thus ended by @samp{*/}, not end of line),
since that is the meaning of @samp{/*} in C.

Also, such readers might think they can use @samp{//} to start
a trailing comment as an alternative to @samp{/*}, but
@samp{//} already denotes concatenation, and such a ``comment''
might actually result in a program that compiles without
error (though it would likely behave incorrectly).

@node Debug Line
@section Debug Line
@cindex debug line
@cindex comment line, debug

Use of @samp{D} or @samp{d} as the first character (column 1) of
a source line denotes a debug line.

In turn, a debug line is treated as either a comment line
or a normal line, depending on whether debug lines are enabled.

When treated as a comment line, a line beginning with @samp{D} or
@samp{d} is treated as if it the first character was @samp{C} or @samp{c}, respectively.
When treated as a normal line, such a line is treated as if
the first character was @key{SPC} (space).

(Currently, @command{g77} provides no means for treating debug
lines as normal lines.)

@node Dollar Signs
@section Dollar Signs in Symbol Names
@cindex dollar sign
@cindex $

Dollar signs (@samp{$}) are allowed in symbol names (after the first character)
when the @option{-fdollar-ok} option is specified.

@node Case Sensitivity
@section Case Sensitivity
@cindex case sensitivity
@cindex source file format
@cindex code, source
@cindex source code
@cindex uppercase letters
@cindex lowercase letters
@cindex letters, uppercase
@cindex letters, lowercase

GNU Fortran offers the programmer way too much flexibility in deciding
how source files are to be treated vis-a-vis uppercase and lowercase
characters.
There are 66 useful settings that affect case sensitivity, plus 10
settings that are nearly useless, with the remaining 116 settings
being either redundant or useless.

None of these settings have any effect on the contents of comments
(the text after a @samp{c} or @samp{C} in Column 1, for example)
or of character or Hollerith constants.
Note that things like the @samp{E} in the statement
@samp{CALL FOO(3.2E10)} and the @samp{TO} in @samp{ASSIGN 10 TO LAB}
are considered built-in keywords, and so are affected by
these settings.

Low-level switches are identified in this section as follows:

@itemize @w{}
@item A
Source Case Conversion:

@itemize @w{}
@item 0
Preserve (see Note 1)
@item 1
Convert to Upper Case
@item 2
Convert to Lower Case
@end itemize

@item B
Built-in Keyword Matching:

@itemize @w{}
@item 0
Match Any Case (per-character basis)
@item 1
Match Upper Case Only
@item 2
Match Lower Case Only
@item 3
Match InitialCaps Only (see tables for spellings)
@end itemize

@item C
Built-in Intrinsic Matching:

@itemize @w{}
@item 0
Match Any Case (per-character basis)
@item 1
Match Upper Case Only
@item 2
Match Lower Case Only
@item 3
Match InitialCaps Only (see tables for spellings)
@end itemize

@item D
User-defined Symbol Possibilities (warnings only):

@itemize @w{}
@item 0
Allow Any Case (per-character basis)
@item 1
Allow Upper Case Only
@item 2
Allow Lower Case Only
@item 3
Allow InitialCaps Only (see Note 2)
@end itemize
@end itemize

Note 1: @command{g77} eventually will support @code{NAMELIST} in a manner that is
consistent with these source switches---in the sense that input will be
expected to meet the same requirements as source code in terms
of matching symbol names and keywords (for the exponent letters).

Currently, however, @code{NAMELIST} is supported by @code{libg2c},
which uppercases @code{NAMELIST} input and symbol names for matching.
This means not only that @code{NAMELIST} output currently shows symbol
(and keyword) names in uppercase even if lower-case source
conversion (option A2) is selected, but that @code{NAMELIST} cannot be
adequately supported when source case preservation (option A0)
is selected.

If A0 is selected, a warning message will be
output for each @code{NAMELIST} statement to this effect.
The behavior
of the program is undefined at run time if two or more symbol names
appear in a given @code{NAMELIST} such that the names are identical
when converted to upper case (e.g. @samp{NAMELIST /X/ VAR, Var, var}).
For complete and total elegance, perhaps there should be a warning
when option A2 is selected, since the output of NAMELIST is currently
in uppercase but will someday be lowercase (when a @code{libg77} is written),
but that seems to be overkill for a product in beta test.

Note 2: Rules for InitialCaps names are:

@itemize @minus
@item
Must be a single uppercase letter, @strong{or}
@item
Must start with an uppercase letter and contain at least one
lowercase letter.
@end itemize

So @samp{A}, @samp{Ab}, @samp{ABc}, @samp{AbC}, and @samp{Abc} are
valid InitialCaps names, but @samp{AB}, @samp{A2}, and @samp{ABC} are
not.
Note that most, but not all, built-in names meet these
requirements---the exceptions are some of the two-letter format
specifiers, such as @code{BN} and @code{BZ}.

Here are the names of the corresponding command-line options:

@smallexample
A0: -fsource-case-preserve
A1: -fsource-case-upper
A2: -fsource-case-lower

B0: -fmatch-case-any
B1: -fmatch-case-upper
B2: -fmatch-case-lower
B3: -fmatch-case-initcap

C0: -fintrin-case-any
C1: -fintrin-case-upper
C2: -fintrin-case-lower
C3: -fintrin-case-initcap

D0: -fsymbol-case-any
D1: -fsymbol-case-upper
D2: -fsymbol-case-lower
D3: -fsymbol-case-initcap
@end smallexample