This is g77.info, produced by makeinfo version 4.0 from g77.texi.

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* g77: (g77).                  The GNU Fortran compiler.
END-INFO-DIR-ENTRY
   This file documents the use and the internals of the GNU Fortran
(`g77') compiler.  It corresponds to the GCC-3.0 version of `g77'.

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

   Copyright (C) 1995,1996,1997,1998,1999,2000,2001 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.1 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.

   Contributed by James Craig Burley (<craig@jcb-sc.com>).  Inspired by
a first pass at translating `g77-0.5.16/f/DOC' that was contributed to
Craig by David Ronis (<ronis@onsager.chem.mcgill.ca>).


File: g77.info,  Node: Time Intrinsic (VXT),  Next: UMask Intrinsic (function),  Prev: TanD Intrinsic,  Up: Other Intrinsics

Time Intrinsic (VXT)
....................

     CALL Time(TIME)

TIME: `CHARACTER*8'; scalar; INTENT(OUT).

Intrinsic groups: `vxt'.

Description:

   Returns in TIME a character representation of the current time as
obtained from `ctime(3)'.

   Programs making use of this intrinsic might not be Year 10000 (Y10K)
compliant.  For example, the date might appear, to such programs, to
wrap around (change from a larger value to a smaller one) as of the
Year 10000.

   *Note FDate Intrinsic (subroutine)::, for an equivalent routine.

   For information on other intrinsics with the same name: *Note Time
Intrinsic (UNIX)::.


File: g77.info,  Node: UMask Intrinsic (function),  Next: Unlink Intrinsic (function),  Prev: Time Intrinsic (VXT),  Up: Other Intrinsics

UMask Intrinsic (function)
..........................

     UMask(MASK)

UMask: `INTEGER(KIND=1)' function.

MASK: `INTEGER'; scalar; INTENT(IN).

Intrinsic groups: `badu77'.

Description:

   Sets the file creation mask to MASK and returns the old value.  See
`umask(2)'.

   Due to the side effects performed by this intrinsic, the function
form is not recommended.

   For information on other intrinsics with the same name: *Note UMask
Intrinsic (subroutine)::.


File: g77.info,  Node: Unlink Intrinsic (function),  Next: ZExt Intrinsic,  Prev: UMask Intrinsic (function),  Up: Other Intrinsics

Unlink Intrinsic (function)
...........................

     Unlink(FILE)

Unlink: `INTEGER(KIND=1)' function.

FILE: `CHARACTER'; scalar; INTENT(IN).

Intrinsic groups: `badu77'.

Description:

   Unlink the file FILE.  A null character (`CHAR(0)') marks the end of
the name in FILE--otherwise, trailing blanks in FILE are ignored.
Returns 0 on success or a non-zero error code.  See `unlink(2)'.

   Due to the side effects performed by this intrinsic, the function
form is not recommended.

   For information on other intrinsics with the same name: *Note Unlink
Intrinsic (subroutine)::.


File: g77.info,  Node: ZExt Intrinsic,  Prev: Unlink Intrinsic (function),  Up: Other Intrinsics

ZExt Intrinsic
..............

   This intrinsic is not yet implemented.  The name is, however,
reserved as an intrinsic.  Use `EXTERNAL ZExt' to use this name for an
external procedure.


File: g77.info,  Node: Other Compilers,  Next: Other Languages,  Prev: Other Dialects,  Up: Top

Other Compilers
***************

   An individual Fortran source file can be compiled to an object
(`*.o') file instead of to the final program executable.  This allows
several portions of a program to be compiled at different times and
linked together whenever a new version of the program is needed.
However, it introduces the issue of "object compatibility" across the
various object files (and libraries, or `*.a' files) that are linked
together to produce any particular executable file.

   Object compatibility is an issue when combining, in one program,
Fortran code compiled by more than one compiler (or more than one
configuration of a compiler).  If the compilers disagree on how to
transform the names of procedures, there will normally be errors when
linking such programs.  Worse, if the compilers agree on naming, but
disagree on issues like how to pass parameters, return arguments, and
lay out `COMMON' areas, the earliest detected errors might be the
incorrect results produced by the program (and that assumes these
errors are detected, which is not always the case).

   Normally, `g77' generates code that is object-compatible with code
generated by a version of `f2c' configured (with, for example, `f2c.h'
definitions) to be generally compatible with `g77' as built by `gcc'.
(Normally, `f2c' will, by default, conform to the appropriate
configuration, but it is possible that older or perhaps even newer
versions of `f2c', or versions having certain configuration changes to
`f2c' internals, will produce object files that are incompatible with
`g77'.)

   For example, a Fortran string subroutine argument will become two
arguments on the C side: a `char *' and an `int' length.

   Much of this compatibility results from the fact that `g77' uses the
same run-time library, `libf2c', used by `f2c', though `g77' gives its
version the name `libg2c' so as to avoid conflicts when linking,
installing them in the same directories, and so on.

   Other compilers might or might not generate code that is
object-compatible with `libg2c' and current `g77', and some might offer
such compatibility only when explicitly selected via a command-line
option to the compiler.

   _Note: This portion of the documentation definitely needs a lot of
work!_

* Menu:

* Dropping f2c Compatibility::  When speed is more important.
* Compilers Other Than f2c::    Interoperation with code from other compilers.


File: g77.info,  Node: Dropping f2c Compatibility,  Next: Compilers Other Than f2c,  Up: Other Compilers

Dropping `f2c' Compatibility
============================

   Specifying `-fno-f2c' allows `g77' to generate, in some cases,
faster code, by not needing to allow to the possibility of linking with
code compiled by `f2c'.

   For example, this affects how `REAL(KIND=1)', `COMPLEX(KIND=1)', and
`COMPLEX(KIND=2)' functions are called.  With `-fno-f2c', they are
compiled as returning the appropriate `gcc' type (`float', `__complex__
float', `__complex__ double', in many configurations).

   With `-ff2c' in force, they are compiled differently (with perhaps
slower run-time performance) to accommodate the restrictions inherent
in `f2c''s use of K&R C as an intermediate language--`REAL(KIND=1)'
functions return C's `double' type, while `COMPLEX' functions return
`void' and use an extra argument pointing to a place for the functions
to return their values.

   It is possible that, in some cases, leaving `-ff2c' in force might
produce faster code than using `-fno-f2c'.  Feel free to experiment,
but remember to experiment with changing the way _entire programs and
their Fortran libraries are compiled_ at a time, since this sort of
experimentation affects the interface of code generated for a Fortran
source file--that is, it affects object compatibility.

   Note that `f2c' compatibility is a fairly static target to achieve,
though not necessarily perfectly so, since, like `g77', it is still
being improved.  However, specifying `-fno-f2c' causes `g77' to
generate code that will probably be incompatible with code generated by
future versions of `g77' when the same option is in force.  You should
make sure you are always able to recompile complete programs from
source code when upgrading to new versions of `g77' or `f2c',
especially when using options such as `-fno-f2c'.

   Therefore, if you are using `g77' to compile libraries and other
object files for possible future use and you don't want to require
recompilation for future use with subsequent versions of `g77', you
might want to stick with `f2c' compatibility for now, and carefully
watch for any announcements about changes to the `f2c'/`libf2c'
interface that might affect existing programs (thus requiring
recompilation).

   It is probable that a future version of `g77' will not, by default,
generate object files compatible with `f2c', and that version probably
would no longer use `libf2c'.  If you expect to depend on this
compatibility in the long term, use the options `-ff2c -ff2c-library'
when compiling all of the applicable code.  This should cause future
versions of `g77' either to produce compatible code (at the expense of
the availability of some features and performance), or at the very
least, to produce diagnostics.

   (The library `g77' produces will no longer be named `libg2c' when it
is no longer generally compatible with `libf2c'.  It will likely be
referred to, and, if installed as a distinct library, named `libg77',
or some other as-yet-unused name.)


File: g77.info,  Node: Compilers Other Than f2c,  Prev: Dropping f2c Compatibility,  Up: Other Compilers

Compilers Other Than `f2c'
==========================

   On systems with Fortran compilers other than `f2c' and `g77', code
compiled by `g77' is not expected to work well with code compiled by
the native compiler.  (This is true for `f2c'-compiled objects as well.)
Libraries compiled with the native compiler probably will have to be
recompiled with `g77' to be used with `g77'-compiled code.

   Reasons for such incompatibilities include:

   * There might be differences in the way names of Fortran procedures
     are translated for use in the system's object-file format.  For
     example, the statement `CALL FOO' might be compiled by `g77' to
     call a procedure the linker `ld' sees given the name `_foo_',
     while the apparently corresponding statement `SUBROUTINE FOO'
     might be compiled by the native compiler to define the
     linker-visible name `_foo', or `_FOO_', and so on.

   * There might be subtle type mismatches which cause subroutine
     arguments and function return values to get corrupted.

     This is why simply getting `g77' to transform procedure names the
     same way a native compiler does is not usually a good idea--unless
     some effort has been made to ensure that, aside from the way the
     two compilers transform procedure names, everything else about the
     way they generate code for procedure interfaces is identical.

   * Native compilers use libraries of private I/O routines which will
     not be available at link time unless you have the native
     compiler--and you would have to explicitly ask for them.

     For example, on the Sun you would have to add `-L/usr/lang/SCx.x
     -lF77 -lV77' to the link command.


File: g77.info,  Node: Other Languages,  Next: Installation,  Prev: Other Compilers,  Up: Top

Other Languages
***************

   _Note: This portion of the documentation definitely needs a lot of
work!_

* Menu:

* Interoperating with C and C++::


File: g77.info,  Node: Interoperating with C and C++,  Up: Other Languages

Tools and advice for interoperating with C and C++
==================================================

   The following discussion assumes that you are running `g77' in `f2c'
compatibility mode, i.e. not using `-fno-f2c'.  It provides some advice
about quick and simple techniques for linking Fortran and C (or C++),
the most common requirement.  For the full story consult the
description of code generation.  *Note Debugging and Interfacing::.

   When linking Fortran and C, it's usually best to use `g77' to do the
linking so that the correct libraries are included (including the maths
one).  If you're linking with C++ you will want to add `-lstdc++',
`-lg++' or whatever.  If you need to use another driver program (or
`ld' directly), you can find out what linkage options `g77' passes by
running `g77 -v'.

* Menu:

* C Interfacing Tools::
* C Access to Type Information::
* f2c Skeletons and Prototypes::
* C++ Considerations::
* Startup Code::


File: g77.info,  Node: C Interfacing Tools,  Next: C Access to Type Information,  Up: Interoperating with C and C++

C Interfacing Tools
-------------------

   Even if you don't actually use it as a compiler, `f2c' from
`ftp://ftp.netlib.org/f2c/src', can be a useful tool when you're
interfacing (linking) Fortran and C.  *Note Generating Skeletons and
Prototypes with `f2c': f2c Skeletons and Prototypes.

   To use `f2c' for this purpose you only need retrieve and build the
`src' directory from the distribution, consult the `README'
instructions there for machine-specifics, and install the `f2c' program
on your path.

   Something else that might be useful is `cfortran.h' from
`ftp://zebra.desy.de/cfortran'.  This is a fairly general tool which
can be used to generate interfaces for calling in both directions
between Fortran and C.  It can be used in `f2c' mode with
`g77'--consult its documentation for details.


File: g77.info,  Node: C Access to Type Information,  Next: f2c Skeletons and Prototypes,  Prev: C Interfacing Tools,  Up: Interoperating with C and C++

Accessing Type Information in C
-------------------------------

   Generally, C code written to link with `g77' code--calling and/or
being called from Fortran--should `#include <g2c.h>' to define the C
versions of the Fortran types.  Don't assume Fortran `INTEGER' types
correspond to C `int's, for instance; instead, declare them as
`integer', a type defined by `g2c.h'.  `g2c.h' is installed where `gcc'
will find it by default, assuming you use a copy of `gcc' compatible
with `g77', probably built at the same time as `g77'.


File: g77.info,  Node: f2c Skeletons and Prototypes,  Next: C++ Considerations,  Prev: C Access to Type Information,  Up: Interoperating with C and C++

Generating Skeletons and Prototypes with `f2c'
----------------------------------------------

   A simple and foolproof way to write `g77'-callable C routines--e.g.
to interface with an existing library--is to write a file (named, for
example, `fred.f') of dummy Fortran skeletons comprising just the
declaration of the routine(s) and dummy arguments plus `END' statements.
Then run `f2c' on file `fred.f' to produce `fred.c' into which you can
edit useful code, confident the calling sequence is correct, at least.
(There are some errors otherwise commonly made in generating C
interfaces with `f2c' conventions, such as not using `doublereal' as
the return type of a `REAL' `FUNCTION'.)

   `f2c' also can help with calling Fortran from C, using its `-P'
option to generate C prototypes appropriate for calling the Fortran.(1)
If the Fortran code containing any routines to be called from C is in
file `joe.f', use the command `f2c -P joe.f' to generate the file
`joe.P' containing prototype information.  `#include' this in the C
which has to call the Fortran routines to make sure you get it right.

   *Note Arrays (DIMENSION): Arrays, for information on the differences
between the way Fortran (including compilers like `g77') and C handle
arrays.

   ---------- Footnotes ----------

   (1) The files generated like this can also be used for inter-unit
consistency checking of dummy and actual arguments, although the
`ftnchek' tool from `ftp://ftp.netlib.org/fortran' or
`ftp://ftp.dsm.fordham.edu' is probably better for this purpose.


File: g77.info,  Node: C++ Considerations,  Next: Startup Code,  Prev: f2c Skeletons and Prototypes,  Up: Interoperating with C and C++

C++ Considerations
------------------

   `f2c' can be used to generate suitable code for compilation with a
C++ system using the `-C++' option.  The important thing about linking
`g77'-compiled code with C++ is that the prototypes for the `g77'
routines must specify C linkage to avoid name mangling.  So, use an
`extern "C"' declaration.  `f2c''s `-C++' option will take care of this
when generating skeletons or prototype files as above, and also avoid
clashes with C++ reserved words in addition to those in C.


File: g77.info,  Node: Startup Code,  Prev: C++ Considerations,  Up: Interoperating with C and C++

Startup Code
------------

   Unlike with some runtime systems, it shouldn't be necessary (unless
there are bugs) to use a Fortran main program unit to ensure the
runtime--specifically the I/O system--is initialized.

   However, to use the `g77' intrinsics `GETARG' and `IARGC', either
the `main' routine from the `libg2c' library must be used, or the
`f_setarg' routine (new as of `egcs' version 1.1 and `g77' version
0.5.23) must be called with the appropriate `argc' and `argv' arguments
prior to the program calling `GETARG' or `IARGC'.

   To provide more flexibility for mixed-language programming involving
`g77' while allowing for shared libraries, as of `egcs' version 1.1 and
`g77' version 0.5.23, `g77''s `main' routine in `libg2c' does the
following, in order:

  1. Calls `f_setarg' with the incoming `argc' and `argv' arguments, in
     the same order as for `main' itself.

     This sets up the command-line environment for `GETARG' and `IARGC'.

  2. Calls `f_setsig' (with no arguments).

     This sets up the signaling and exception environment.

  3. Calls `f_init' (with no arguments).

     This initializes the I/O environment, though that should not be
     necessary, as all I/O functions in `libf2c' are believed to call
     `f_init' automatically, if necessary.

     (A future version of `g77' might skip this explicit step, to speed
     up normal exit of a program.)

  4. Arranges for `f_exit' to be called (with no arguments) when the
     program exits.

     This ensures that the I/O environment is properly shut down before
     the program exits normally.  Otherwise, output buffers might not
     be fully flushed, scratch files might not be deleted, and so on.

     The simple way `main' does this is to call `f_exit' itself after
     calling `MAIN__' (in the next step).

     However, this does not catch the cases where the program might
     call `exit' directly, instead of using the `EXIT' intrinsic
     (implemented as `exit_' in `libf2c').

     So, `main' attempts to use the operating environment's `onexit' or
     `atexit' facility, if available, to cause `f_exit' to be called
     automatically upon any invocation of `exit'.

  5. Calls `MAIN__' (with no arguments).

     This starts executing the Fortran main program unit for the
     application.  (Both `g77' and `f2c' currently compile a main
     program unit so that its global name is `MAIN__'.)

  6. If no `onexit' or `atexit' is provided by the system, calls
     `f_exit'.

  7. Calls `exit' with a zero argument, to signal a successful program
     termination.

  8. Returns a zero value to the caller, to signal a successful program
     termination, in case `exit' doesn't exit on the system.

   All of the above names are C `extern' names, i.e. not mangled.

   When using the `main' procedure provided by `g77' without a Fortran
main program unit, you need to provide `MAIN__' as the entry point for
your C code.  (Make sure you link the object file that defines that
entry point with the rest of your program.)

   To provide your own `main' procedure in place of `g77''s, make sure
you specify the object file defining that procedure _before_ `-lg2c' on
the `g77' command line.  Since the `-lg2c' option is implicitly
provided, this is usually straightforward.  (Use the `--verbose' option
to see how and where `g77' implicitly adds `-lg2c' in a command line
that will link the program.  Feel free to specify `-lg2c' explicitly,
as appropriate.)

   However, when providing your own `main', make sure you perform the
appropriate tasks in the appropriate order.  For example, if your
`main' does not call `f_setarg', make sure the rest of your application
does not call `GETARG' or `IARGC'.

   And, if your `main' fails to ensure that `f_exit' is called upon
program exit, some files might end up incompletely written, some
scratch files might be left lying around, and some existing files being
written might be left with old data not properly truncated at the end.

   Note that, generally, the `g77' operating environment does not
depend on a procedure named `MAIN__' actually being called prior to any
other `g77'-compiled code.  That is, `MAIN__' does not, itself, set up
any important operating-environment characteristics upon which other
code might depend.  This might change in future versions of `g77', with
appropriate notification in the release notes.

   For more information, consult the source code for the above routines.
These are in `gcc/libf2c/libF77/', named `main.c', `setarg.c',
`setsig.c', `getarg_.c', and `iargc_.c'.

   Also, the file `gcc/gcc/f/com.c' contains the code `g77' uses to
open-code (inline) references to `IARGC'.


File: g77.info,  Node: Installation,  Next: Debugging and Interfacing,  Prev: Other Languages,  Up: Top

Installing GNU Fortran
**********************

   The information describing how to install `g77' is contained in the
GCC installation procedures.


File: g77.info,  Node: Debugging and Interfacing,  Next: Collected Fortran Wisdom,  Prev: Installation,  Up: Top

Debugging and Interfacing
*************************

   GNU Fortran currently generates code that is object-compatible with
the `f2c' converter.  Also, it avoids limitations in the current GBE,
such as the inability to generate a procedure with multiple entry
points, by generating code that is structured differently (in terms of
procedure names, scopes, arguments, and so on) than might be expected.

   As a result, writing code in other languages that calls on, is
called by, or shares in-memory data with `g77'-compiled code generally
requires some understanding of the way `g77' compiles code for various
constructs.

   Similarly, using a debugger to debug `g77'-compiled code, even if
that debugger supports native Fortran debugging, generally requires
this sort of information.

   This section describes some of the basic information on how `g77'
compiles code for constructs involving interfaces to other languages
and to debuggers.

   _Caution:_ Much or all of this information pertains to only the
current release of `g77', sometimes even to using certain compiler
options with `g77' (such as `-fno-f2c').  Do not write code that
depends on this information without clearly marking said code as
nonportable and subject to review for every new release of `g77'.  This
information is provided primarily to make debugging of code generated
by this particular release of `g77' easier for the user, and partly to
make writing (generally nonportable) interface code easier.  Both of
these activities require tracking changes in new version of `g77' as
they are installed, because new versions can change the behaviors
described in this section.

* Menu:

* Main Program Unit::  How `g77' compiles a main program unit.
* Procedures::         How `g77' constructs parameter lists
                       for procedures.
* Functions::          Functions returning floating-point or character data.
* Names::              Naming of user-defined variables, procedures, etc.
* Common Blocks::      Accessing common variables while debugging.
* Local Equivalence Areas::  Accessing `EQUIVALENCE' while debugging.
* Complex Variables::  How `g77' performs complex arithmetic.
* Arrays::             Dealing with (possibly multi-dimensional) arrays.
* Adjustable Arrays::  Special consideration for adjustable arrays.
* Alternate Entry Points::  How `g77' implements alternate `ENTRY'.
* Alternate Returns::  How `g77' handles alternate returns.
* Assigned Statement Labels::  How `g77' handles `ASSIGN'.
* Run-time Library Errors::  Meanings of some `IOSTAT=' values.


File: g77.info,  Node: Main Program Unit,  Next: Procedures,  Up: Debugging and Interfacing

Main Program Unit (PROGRAM)
===========================

   When `g77' compiles a main program unit, it gives it the public
procedure name `MAIN__'.  The `libg2c' library has the actual `main()'
procedure as is typical of C-based environments, and it is this
procedure that performs some initial start-up activity and then calls
`MAIN__'.

   Generally, `g77' and `libg2c' are designed so that you need not
include a main program unit written in Fortran in your program--it can
be written in C or some other language.  Especially for I/O handling,
this is the case, although `g77' version 0.5.16 includes a bug fix for
`libg2c' that solved a problem with using the `OPEN' statement as the
first Fortran I/O activity in a program without a Fortran main program
unit.

   However, if you don't intend to use `g77' (or `f2c') to compile your
main program unit--that is, if you intend to compile a `main()'
procedure using some other language--you should carefully examine the
code for `main()' in `libg2c', found in the source file
`gcc/libf2c/libF77/main.c', to see what kinds of things might need to
be done by your `main()' in order to provide the Fortran environment
your Fortran code is expecting.

   For example, `libg2c''s `main()' sets up the information used by the
`IARGC' and `GETARG' intrinsics.  Bypassing `libg2c''s `main()' without
providing a substitute for this activity would mean that invoking
`IARGC' and `GETARG' would produce undefined results.

   When debugging, one implication of the fact that `main()', which is
the place where the debugged program "starts" from the debugger's point
of view, is in `libg2c' is that you won't be starting your Fortran
program at a point you recognize as your Fortran code.

   The standard way to get around this problem is to set a break point
(a one-time, or temporary, break point will do) at the entrance to
`MAIN__', and then run the program.  A convenient way to do so is to
add the `gdb' command

     tbreak MAIN__

to the file `.gdbinit' in the directory in which you're debugging
(using `gdb').

   After doing this, the debugger will see the current execution point
of the program as at the beginning of the main program unit of your
program.

   Of course, if you really want to set a break point at some other
place in your program and just start the program running, without first
breaking at `MAIN__', that should work fine.


File: g77.info,  Node: Procedures,  Next: Functions,  Prev: Main Program Unit,  Up: Debugging and Interfacing

Procedures (SUBROUTINE and FUNCTION)
====================================

   Currently, `g77' passes arguments via reference--specifically, by
passing a pointer to the location in memory of a variable, array, array
element, a temporary location that holds the result of evaluating an
expression, or a temporary or permanent location that holds the value
of a constant.

   Procedures that accept `CHARACTER' arguments are implemented by
`g77' so that each `CHARACTER' argument has two actual arguments.

   The first argument occupies the expected position in the argument
list and has the user-specified name.  This argument is a pointer to an
array of characters, passed by the caller.

   The second argument is appended to the end of the user-specified
calling sequence and is named `__g77_length_X', where X is the
user-specified name.  This argument is of the C type `ftnlen' (see
`gcc/libf2c/g2c.h.in' for information on that type) and is the number
of characters the caller has allocated in the array pointed to by the
first argument.

   A procedure will ignore the length argument if `X' is not declared
`CHARACTER*(*)', because for other declarations, it knows the length.
Not all callers necessarily "know" this, however, which is why they all
pass the extra argument.

   The contents of the `CHARACTER' argument are specified by the
address passed in the first argument (named after it).  The procedure
can read or write these contents as appropriate.

   When more than one `CHARACTER' argument is present in the argument
list, the length arguments are appended in the order the original
arguments appear.  So `CALL FOO('HI','THERE')' is implemented in C as
`foo("hi","there",2,5);', ignoring the fact that `g77' does not provide
the trailing null bytes on the constant strings (`f2c' does provide
them, but they are unnecessary in a Fortran environment, and you should
not expect them to be there).

   Note that the above information applies to `CHARACTER' variables and
arrays *only*.  It does *not* apply to external `CHARACTER' functions
or to intrinsic `CHARACTER' functions.  That is, no second length
argument is passed to `FOO' in this case:

     CHARACTER X
     EXTERNAL X
     CALL FOO(X)

Nor does `FOO' expect such an argument in this case:

     SUBROUTINE FOO(X)
     CHARACTER X
     EXTERNAL X

   Because of this implementation detail, if a program has a bug such
that there is disagreement as to whether an argument is a procedure,
and the type of the argument is `CHARACTER', subtle symptoms might
appear.


File: g77.info,  Node: Functions,  Next: Names,  Prev: Procedures,  Up: Debugging and Interfacing

Functions (FUNCTION and RETURN)
===============================

   `g77' handles in a special way functions that return the following
types:

   * `CHARACTER'

   * `COMPLEX'

   * `REAL(KIND=1)'

   For `CHARACTER', `g77' implements a subroutine (a C function
returning `void') with two arguments prepended: `__g77_result', which
the caller passes as a pointer to a `char' array expected to hold the
return value, and `__g77_length', which the caller passes as an
`ftnlen' value specifying the length of the return value as declared in
the calling program.  For `CHARACTER*(*)', the called function uses
`__g77_length' to determine the size of the array that `__g77_result'
points to; otherwise, it ignores that argument.

   For `COMPLEX', when `-ff2c' is in force, `g77' implements a
subroutine with one argument prepended: `__g77_result', which the
caller passes as a pointer to a variable of the type of the function.
The called function writes the return value into this variable instead
of returning it as a function value.  When `-fno-f2c' is in force,
`g77' implements a `COMPLEX' function as `gcc''s `__complex__ float' or
`__complex__ double' function (or an emulation thereof, when
`-femulate-complex' is in effect), returning the result of the function
in the same way as `gcc' would.

   For `REAL(KIND=1)', when `-ff2c' is in force, `g77' implements a
function that actually returns `REAL(KIND=2)' (typically C's `double'
type).  When `-fno-f2c' is in force, `REAL(KIND=1)' functions return
`float'.


File: g77.info,  Node: Names,  Next: Common Blocks,  Prev: Functions,  Up: Debugging and Interfacing

Names
=====

   Fortran permits each implementation to decide how to represent names
as far as how they're seen in other contexts, such as debuggers and
when interfacing to other languages, and especially as far as how
casing is handled.

   External names--names of entities that are public, or "accessible",
to all modules in a program--normally have an underscore (`_') appended
by `g77', to generate code that is compatible with `f2c'.  External
names include names of Fortran things like common blocks, external
procedures (subroutines and functions, but not including statement
functions, which are internal procedures), and entry point names.

   However, use of the `-fno-underscoring' option disables this kind of
transformation of external names (though inhibiting the transformation
certainly improves the chances of colliding with incompatible externals
written in other languages--but that might be intentional.

   When `-funderscoring' is in force, any name (external or local) that
already has at least one underscore in it is implemented by `g77' by
appending two underscores.  (This second underscore can be disabled via
the `-fno-second-underscore' option.)  External names are changed this
way for `f2c' compatibility.  Local names are changed this way to avoid
collisions with external names that are different in the source
code--`f2c' does the same thing, but there's no compatibility issue
there except for user expectations while debugging.

   For example:

     Max_Cost = 0

Here, a user would, in the debugger, refer to this variable using the
name `max_cost__' (or `MAX_COST__' or `Max_Cost__', as described below).
(We hope to improve `g77' in this regard in the future--don't write
scripts depending on this behavior!  Also, consider experimenting with
the `-fno-underscoring' option to try out debugging without having to
massage names by hand like this.)

   `g77' provides a number of command-line options that allow the user
to control how case mapping is handled for source files.  The default
is the traditional UNIX model for Fortran compilers--names are mapped
to lower case.  Other command-line options can be specified to map
names to upper case, or to leave them exactly as written in the source
file.

   For example:

     Foo = 9.436

Here, it is normally the case that the variable assigned will be named
`foo'.  This would be the name to enter when using a debugger to access
the variable.

   However, depending on the command-line options specified, the name
implemented by `g77' might instead be `FOO' or even `Foo', thus
affecting how debugging is done.

   Also:

     Call Foo

This would normally call a procedure that, if it were in a separate C
program, be defined starting with the line:

     void foo_()

However, `g77' command-line options could be used to change the casing
of names, resulting in the name `FOO_' or `Foo_' being given to the
procedure instead of `foo_', and the `-fno-underscoring' option could
be used to inhibit the appending of the underscore to the name.


File: g77.info,  Node: Common Blocks,  Next: Local Equivalence Areas,  Prev: Names,  Up: Debugging and Interfacing

Common Blocks (COMMON)
======================

   `g77' names and lays out `COMMON' areas the same way `f2c' does, for
compatibility with `f2c'.

   Currently, `g77' does not emit "true" debugging information for
members of a `COMMON' area, due to an apparent bug in the GBE.

   (As of Version 0.5.19, `g77' emits debugging information for such
members in the form of a constant string specifying the base name of
the aggregate area and the offset of the member in bytes from the start
of the area.  Use the `-fdebug-kludge' option to enable this behavior.
In `gdb', use `set language c' before printing the value of the member,
then `set language fortran' to restore the default language, since
`gdb' doesn't provide a way to print a readable version of a character
string in Fortran language mode.

   This kludge will be removed in a future version of `g77' that, in
conjunction with a contemporary version of `gdb', properly supports
Fortran-language debugging, including access to members of `COMMON'
areas.)

   Version 0.5.26 of `g77' is believed to provide correct and complete
debug information for COMMON BLOCK and EQUIVALENCE items - hence the
`-fdebug-kludge' option has been disabled.

   *Note Options for Code Generation Conventions: Code Gen Options, for
information on the `-fdebug-kludge' option.

   Moreover, `g77' currently implements a `COMMON' area such that its
type is an array of the C `char' data type.

   So, when debugging, you must know the offset into a `COMMON' area
for a particular item in that area, and you have to take into account
the appropriate multiplier for the respective sizes of the types (as
declared in your code) for the items preceding the item in question as
compared to the size of the `char' type.

   For example, using default implicit typing, the statement

     COMMON I(15), R(20), T

results in a public 144-byte `char' array named `_BLNK__' with `I'
placed at `_BLNK__[0]', `R' at `_BLNK__[60]', and `T' at `_BLNK__[140]'.
(This is assuming that the target machine for the compilation has
4-byte `INTEGER(KIND=1)' and `REAL(KIND=1)' types.)


File: g77.info,  Node: Local Equivalence Areas,  Next: Complex Variables,  Prev: Common Blocks,  Up: Debugging and Interfacing

Local Equivalence Areas (EQUIVALENCE)
=====================================

   `g77' treats storage-associated areas involving a `COMMON' block as
explained in the section on common blocks.

   A local `EQUIVALENCE' area is a collection of variables and arrays
connected to each other in any way via `EQUIVALENCE', none of which are
listed in a `COMMON' statement.

   Currently, `g77' does not emit "true" debugging information for
members in a local `EQUIVALENCE' area, due to an apparent bug in the
GBE.

   (As of Version 0.5.19, `g77' does emit debugging information for such
members in the form of a constant string specifying the base name of
the aggregate area and the offset of the member in bytes from the start
of the area.  Use the `-fdebug-kludge' option to enable this behavior.
In `gdb', use `set language c' before printing the value of the member,
then `set language fortran' to restore the default language, since
`gdb' doesn't provide a way to print a readable version of a character
string in Fortran language mode.

   This kludge will be removed in a future version of `g77' that, in
conjunction with a contemporary version of `gdb', properly supports
Fortran-language debugging, including access to members of
`EQUIVALENCE' areas.)

   *Note Options for Code Generation Conventions: Code Gen Options, for
information on the `-fdebug-kludge' option.

   Moreover, `g77' implements a local `EQUIVALENCE' area such that its
type is an array of the C `char' data type.

   The name `g77' gives this array of `char' type is `__g77_equiv_X',
where X is the name of the item that is placed at the beginning (offset
0) of this array.  If more than one such item is placed at the
beginning, X is the name that sorts to the top in an alphabetical sort
of the list of such items.

   When debugging, you must therefore access members of `EQUIVALENCE'
areas by specifying the appropriate `__g77_equiv_X' array section with
the appropriate offset.  See the explanation of debugging `COMMON'
blocks for info applicable to debugging local `EQUIVALENCE' areas.

   (_Note:_ `g77' version 0.5.18 and earlier chose the name for X using
a different method when more than one name was in the list of names of
entities placed at the beginning of the array.  Though the
documentation specified that the first name listed in the `EQUIVALENCE'
statements was chosen for X, `g77' in fact chose the name using a
method that was so complicated, it seemed easier to change it to an
alphabetical sort than to describe the previous method in the
documentation.)


File: g77.info,  Node: Complex Variables,  Next: Arrays,  Prev: Local Equivalence Areas,  Up: Debugging and Interfacing

Complex Variables (COMPLEX)
===========================

   As of 0.5.20, `g77' defaults to handling `COMPLEX' types (and
related intrinsics, constants, functions, and so on) in a manner that
makes direct debugging involving these types in Fortran language mode
difficult.

   Essentially, `g77' implements these types using an internal
construct similar to C's `struct', at least as seen by the `gcc' back
end.

   Currently, the back end, when outputting debugging info with the
compiled code for the assembler to digest, does not detect these
`struct' types as being substitutes for Fortran complex.  As a result,
the Fortran language modes of debuggers such as `gdb' see these types
as C `struct' types, which they might or might not support.

   Until this is fixed, switch to C language mode to work with entities
of `COMPLEX' type and then switch back to Fortran language mode
afterward.  (In `gdb', this is accomplished via `set lang c' and either
`set lang fortran' or `set lang auto'.)


File: g77.info,  Node: Arrays,  Next: Adjustable Arrays,  Prev: Complex Variables,  Up: Debugging and Interfacing

Arrays (DIMENSION)
==================

   Fortran uses "column-major ordering" in its arrays.  This differs
from other languages, such as C, which use "row-major ordering".  The
difference is that, with Fortran, array elements adjacent to each other
in memory differ in the _first_ subscript instead of the last;
`A(5,10,20)' immediately follows `A(4,10,20)', whereas with row-major
ordering it would follow `A(5,10,19)'.

   This consideration affects not only interfacing with and debugging
Fortran code, it can greatly affect how code is designed and written,
especially when code speed and size is a concern.

   Fortran also differs from C, a popular language for interfacing and
to support directly in debuggers, in the way arrays are treated.  In C,
arrays are single-dimensional and have interesting relationships to
pointers, neither of which is true for Fortran.  As a result, dealing
with Fortran arrays from within an environment limited to C concepts
can be challenging.

   For example, accessing the array element `A(5,10,20)' is easy enough
in Fortran (use `A(5,10,20)'), but in C some difficult machinations are
needed.  First, C would treat the A array as a single-dimension array.
Second, C does not understand low bounds for arrays as does Fortran.
Third, C assumes a low bound of zero (0), while Fortran defaults to a
low bound of one (1) and can supports an arbitrary low bound.
Therefore, calculations must be done to determine what the C equivalent
of `A(5,10,20)' would be, and these calculations require knowing the
dimensions of `A'.

   For `DIMENSION A(2:11,21,0:29)', the calculation of the offset of
`A(5,10,20)' would be:

       (5-2)
     + (10-1)*(11-2+1)
     + (20-0)*(11-2+1)*(21-1+1)
     = 4293

So the C equivalent in this case would be `a[4293]'.

   When using a debugger directly on Fortran code, the C equivalent
might not work, because some debuggers cannot understand the notion of
low bounds other than zero.  However, unlike `f2c', `g77' does inform
the GBE that a multi-dimensional array (like `A' in the above example)
is really multi-dimensional, rather than a single-dimensional array, so
at least the dimensionality of the array is preserved.

   Debuggers that understand Fortran should have no trouble with
non-zero low bounds, but for non-Fortran debuggers, especially C
debuggers, the above example might have a C equivalent of `a[4305]'.
This calculation is arrived at by eliminating the subtraction of the
lower bound in the first parenthesized expression on each line--that
is, for `(5-2)' substitute `(5)', for `(10-1)' substitute `(10)', and
for `(20-0)' substitute `(20)'.  Actually, the implication of this can
be that the expression `*(&a[2][1][0] + 4293)' works fine, but that
`a[20][10][5]' produces the equivalent of `*(&a[0][0][0] + 4305)'
because of the missing lower bounds.

   Come to think of it, perhaps the behavior is due to the debugger
internally compensating for the lower bounds by offsetting the base
address of `a', leaving `&a' set lower, in this case, than
`&a[2][1][0]' (the address of its first element as identified by
subscripts equal to the corresponding lower bounds).

   You know, maybe nobody really needs to use arrays.


File: g77.info,  Node: Adjustable Arrays,  Next: Alternate Entry Points,  Prev: Arrays,  Up: Debugging and Interfacing

Adjustable Arrays (DIMENSION)
=============================

   Adjustable and automatic arrays in Fortran require the implementation
(in this case, the `g77' compiler) to "memorize" the expressions that
dimension the arrays each time the procedure is invoked.  This is so
that subsequent changes to variables used in those expressions, made
during execution of the procedure, do not have any effect on the
dimensions of those arrays.

   For example:

     REAL ARRAY(5)
     DATA ARRAY/5*2/
     CALL X(ARRAY, 5)
     END
     SUBROUTINE X(A, N)
     DIMENSION A(N)
     N = 20
     PRINT *, N, A
     END

Here, the implementation should, when running the program, print
something like:

     20   2.  2.  2.  2.  2.

Note that this shows that while the value of `N' was successfully
changed, the size of the `A' array remained at 5 elements.

   To support this, `g77' generates code that executes before any user
code (and before the internally generated computed `GOTO' to handle
alternate entry points, as described below) that evaluates each
(nonconstant) expression in the list of subscripts for an array, and
saves the result of each such evaluation to be used when determining
the size of the array (instead of re-evaluating the expressions).

   So, in the above example, when `X' is first invoked, code is
executed that copies the value of `N' to a temporary.  And that same
temporary serves as the actual high bound for the single dimension of
the `A' array (the low bound being the constant 1).  Since the user
program cannot (legitimately) change the value of the temporary during
execution of the procedure, the size of the array remains constant
during each invocation.

   For alternate entry points, the code `g77' generates takes into
account the possibility that a dummy adjustable array is not actually
passed to the actual entry point being invoked at that time.  In that
case, the public procedure implementing the entry point passes to the
master private procedure implementing all the code for the entry points
a `NULL' pointer where a pointer to that adjustable array would be
expected.  The `g77'-generated code doesn't attempt to evaluate any of
the expressions in the subscripts for an array if the pointer to that
array is `NULL' at run time in such cases.  (Don't depend on this
particular implementation by writing code that purposely passes `NULL'
pointers where the callee expects adjustable arrays, even if you know
the callee won't reference the arrays--nor should you pass `NULL'
pointers for any dummy arguments used in calculating the bounds of such
arrays or leave undefined any values used for that purpose in
COMMON--because the way `g77' implements these things might change in
the future!)

