+++ /dev/null
-This is g77.info, produced by makeinfo version 4.5 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.2.3 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,2002 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>).
-
-\1f
-File: g77.info, Node: QExtD Intrinsic, Next: QFloat Intrinsic, Prev: QExt Intrinsic, Up: Other Intrinsics
-
-QExtD Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QExtD' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QFloat Intrinsic, Next: QInt Intrinsic, Prev: QExtD Intrinsic, Up: Other Intrinsics
-
-QFloat Intrinsic
-................
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QFloat' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QInt Intrinsic, Next: QLog Intrinsic, Prev: QFloat Intrinsic, Up: Other Intrinsics
-
-QInt Intrinsic
-..............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QInt' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QLog Intrinsic, Next: QLog10 Intrinsic, Prev: QInt Intrinsic, Up: Other Intrinsics
-
-QLog Intrinsic
-..............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QLog' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QLog10 Intrinsic, Next: QMax1 Intrinsic, Prev: QLog Intrinsic, Up: Other Intrinsics
-
-QLog10 Intrinsic
-................
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QLog10' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QMax1 Intrinsic, Next: QMin1 Intrinsic, Prev: QLog10 Intrinsic, Up: Other Intrinsics
-
-QMax1 Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QMax1' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QMin1 Intrinsic, Next: QMod Intrinsic, Prev: QMax1 Intrinsic, Up: Other Intrinsics
-
-QMin1 Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QMin1' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QMod Intrinsic, Next: QNInt Intrinsic, Prev: QMin1 Intrinsic, Up: Other Intrinsics
-
-QMod Intrinsic
-..............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QMod' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QNInt Intrinsic, Next: QSin Intrinsic, Prev: QMod Intrinsic, Up: Other Intrinsics
-
-QNInt Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QNInt' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QSin Intrinsic, Next: QSinD Intrinsic, Prev: QNInt Intrinsic, Up: Other Intrinsics
-
-QSin Intrinsic
-..............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QSin' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QSinD Intrinsic, Next: QSinH Intrinsic, Prev: QSin Intrinsic, Up: Other Intrinsics
-
-QSinD Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QSinD' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QSinH Intrinsic, Next: QSqRt Intrinsic, Prev: QSinD Intrinsic, Up: Other Intrinsics
-
-QSinH Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QSinH' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QSqRt Intrinsic, Next: QTan Intrinsic, Prev: QSinH Intrinsic, Up: Other Intrinsics
-
-QSqRt Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QSqRt' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QTan Intrinsic, Next: QTanD Intrinsic, Prev: QSqRt Intrinsic, Up: Other Intrinsics
-
-QTan Intrinsic
-..............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QTan' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QTanD Intrinsic, Next: QTanH Intrinsic, Prev: QTan Intrinsic, Up: Other Intrinsics
-
-QTanD Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QTanD' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: QTanH Intrinsic, Next: Rename Intrinsic (function), Prev: QTanD Intrinsic, Up: Other Intrinsics
-
-QTanH Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL QTanH' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: Rename Intrinsic (function), Next: Secnds Intrinsic, Prev: QTanH Intrinsic, Up: Other Intrinsics
-
-Rename Intrinsic (function)
-...........................
-
- Rename(PATH1, PATH2)
-
-Rename: `INTEGER(KIND=1)' function.
-
-PATH1: `CHARACTER'; scalar; INTENT(IN).
-
-PATH2: `CHARACTER'; scalar; INTENT(IN).
-
-Intrinsic groups: `badu77'.
-
-Description:
-
- Renames the file PATH1 to PATH2. A null character (`CHAR(0)') marks
-the end of the names in PATH1 and PATH2--otherwise, trailing blanks in
-PATH1 and PATH2 are ignored. See `rename(2)'. Returns 0 on success or
-a non-zero error code.
-
- 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 Rename
-Intrinsic (subroutine)::.
-
-\1f
-File: g77.info, Node: Secnds Intrinsic, Next: Signal Intrinsic (function), Prev: Rename Intrinsic (function), Up: Other Intrinsics
-
-Secnds Intrinsic
-................
-
- Secnds(T)
-
-Secnds: `REAL(KIND=1)' function.
-
-T: `REAL(KIND=1)'; scalar; INTENT(IN).
-
-Intrinsic groups: `vxt'.
-
-Description:
-
- Returns the local time in seconds since midnight minus the value T.
-
- This values returned by this intrinsic become numerically less than
-previous values (they wrap around) during a single run of the compiler
-program, under normal circumstances (such as running through the
-midnight hour).
-
-\1f
-File: g77.info, Node: Signal Intrinsic (function), Next: SinD Intrinsic, Prev: Secnds Intrinsic, Up: Other Intrinsics
-
-Signal Intrinsic (function)
-...........................
-
- Signal(NUMBER, HANDLER)
-
-Signal: `INTEGER(KIND=7)' function.
-
-NUMBER: `INTEGER'; scalar; INTENT(IN).
-
-HANDLER: Signal handler (`INTEGER FUNCTION' or `SUBROUTINE') or
-dummy/global `INTEGER(KIND=1)' scalar.
-
-Intrinsic groups: `badu77'.
-
-Description:
-
- If HANDLER is a an `EXTERNAL' routine, arranges for it to be invoked
-with a single integer argument (of system-dependent length) when signal
-NUMBER occurs. If HANDLER is an integer, it can be used to turn off
-handling of signal NUMBER or revert to its default action. See
-`signal(2)'.
-
- Note that HANDLER will be called using C conventions, so the value
-of its argument in Fortran terms is obtained by applying `%LOC()' (or
-LOC()) to it.
-
- The value returned by `signal(2)' is returned.
-
- Due to the side effects performed by this intrinsic, the function
-form is not recommended.
-
- _Warning:_ If the returned value is stored in an `INTEGER(KIND=1)'
-(default `INTEGER') argument, truncation of the original return value
-occurs on some systems (such as Alphas, which have 64-bit pointers but
-32-bit default integers), with no warning issued by `g77' under normal
-circumstances.
-
- Therefore, the following code fragment might silently fail on some
-systems:
-
- INTEGER RTN
- EXTERNAL MYHNDL
- RTN = SIGNAL(SIGNUM, MYHNDL)
- ...
- ! Restore original handler:
- RTN = SIGNAL(SIGNUM, RTN)
-
- The reason for the failure is that `RTN' might not hold all the
-information on the original handler for the signal, thus restoring an
-invalid handler. This bug could manifest itself as a spurious run-time
-failure at an arbitrary point later during the program's execution, for
-example.
-
- _Warning:_ Use of the `libf2c' run-time library function `signal_'
-directly (such as via `EXTERNAL SIGNAL') requires use of the `%VAL()'
-construct to pass an `INTEGER' value (such as `SIG_IGN' or `SIG_DFL')
-for the HANDLER argument.
-
- However, while `RTN = SIGNAL(SIGNUM, %VAL(SIG_IGN))' works when
-`SIGNAL' is treated as an external procedure (and resolves, at link
-time, to `libf2c''s `signal_' routine), this construct is not valid
-when `SIGNAL' is recognized as the intrinsic of that name.
-
- Therefore, for maximum portability and reliability, code such
-references to the `SIGNAL' facility as follows:
-
- INTRINSIC SIGNAL
- ...
- RTN = SIGNAL(SIGNUM, SIG_IGN)
-
- `g77' will compile such a call correctly, while other compilers will
-generally either do so as well or reject the `INTRINSIC SIGNAL'
-statement via a diagnostic, allowing you to take appropriate action.
-
- For information on other intrinsics with the same name: *Note Signal
-Intrinsic (subroutine)::.
-
-\1f
-File: g77.info, Node: SinD Intrinsic, Next: SnglQ Intrinsic, Prev: Signal Intrinsic (function), Up: Other Intrinsics
-
-SinD Intrinsic
-..............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL SinD' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: SnglQ Intrinsic, Next: SymLnk Intrinsic (function), Prev: SinD Intrinsic, Up: Other Intrinsics
-
-SnglQ Intrinsic
-...............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL SnglQ' to use this name for an
-external procedure.
-
-\1f
-File: g77.info, Node: SymLnk Intrinsic (function), Next: System Intrinsic (function), Prev: SnglQ Intrinsic, Up: Other Intrinsics
-
-SymLnk Intrinsic (function)
-...........................
-
- SymLnk(PATH1, PATH2)
-
-SymLnk: `INTEGER(KIND=1)' function.
-
-PATH1: `CHARACTER'; scalar; INTENT(IN).
-
-PATH2: `CHARACTER'; scalar; INTENT(IN).
-
-Intrinsic groups: `badu77'.
-
-Description:
-
- Makes a symbolic link from file PATH1 to PATH2. A null character
-(`CHAR(0)') marks the end of the names in PATH1 and PATH2--otherwise,
-trailing blanks in PATH1 and PATH2 are ignored. Returns 0 on success
-or a non-zero error code (`ENOSYS' if the system does not provide
-`symlink(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 SymLnk
-Intrinsic (subroutine)::.
-
-\1f
-File: g77.info, Node: System Intrinsic (function), Next: TanD Intrinsic, Prev: SymLnk Intrinsic (function), Up: Other Intrinsics
-
-System Intrinsic (function)
-...........................
-
- System(COMMAND)
-
-System: `INTEGER(KIND=1)' function.
-
-COMMAND: `CHARACTER'; scalar; INTENT(IN).
-
-Intrinsic groups: `badu77'.
-
-Description:
-
- Passes the command COMMAND to a shell (see `system(3)'). Returns
-the value returned by `system(3)', presumably 0 if the shell command
-succeeded. Note that which shell is used to invoke the command is
-system-dependent and environment-dependent.
-
- Due to the side effects performed by this intrinsic, the function
-form is not recommended. However, the function form can be valid in
-cases where the actual side effects performed by the call are
-unimportant to the application.
-
- For example, on a UNIX system, `SAME = SYSTEM('cmp a b')' does not
-perform any side effects likely to be important to the program, so the
-programmer would not care if the actual system call (and invocation of
-`cmp') was optimized away in a situation where the return value could
-be determined otherwise, or was not actually needed (`SAME' not
-actually referenced after the sample assignment statement).
-
- For information on other intrinsics with the same name: *Note System
-Intrinsic (subroutine)::.
-
-\1f
-File: g77.info, Node: TanD Intrinsic, Next: Time Intrinsic (VXT), Prev: System Intrinsic (function), Up: Other Intrinsics
-
-TanD Intrinsic
-..............
-
- This intrinsic is not yet implemented. The name is, however,
-reserved as an intrinsic. Use `EXTERNAL TanD' to use this name for an
-external procedure.
-
-\1f
-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)::.
-
-\1f
-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)::.
-
-\1f
-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)::.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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.)
-
-\1f
-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.
-
-\1f
-File: g77.info, Node: Other Languages, Next: Debugging and Interfacing, 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++::
-
-\1f
-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::
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-File: g77.info, Node: Debugging and Interfacing, Next: Collected Fortran Wisdom, Prev: Other Languages, 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.
-
-\1f
-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.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.
-
-\1f
-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'.
-
-\1f
-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.
-
- (_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.)
-
-\1f
-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'.)
-
projects / msp430-gcc.git / blobdiff