+++ /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: 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.
-
-\1f
-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!)
-
-\1f
-File: g77.info, Node: Alternate Entry Points, Next: Alternate Returns, Prev: Adjustable Arrays, Up: Debugging and Interfacing
-
-Alternate Entry Points (ENTRY)
-==============================
-
- The GBE does not understand the general concept of alternate entry
-points as Fortran provides via the ENTRY statement. `g77' gets around
-this by using an approach to compiling procedures having at least one
-`ENTRY' statement that is almost identical to the approach used by
-`f2c'. (An alternate approach could be used that would probably
-generate faster, but larger, code that would also be a bit easier to
-debug.)
-
- Information on how `g77' implements `ENTRY' is provided for those
-trying to debug such code. The choice of implementation seems unlikely
-to affect code (compiled in other languages) that interfaces to such
-code.
-
- `g77' compiles exactly one public procedure for the primary entry
-point of a procedure plus each `ENTRY' point it specifies, as usual.
-That is, in terms of the public interface, there is no difference
-between
-
- SUBROUTINE X
- END
- SUBROUTINE Y
- END
-
-and:
-
- SUBROUTINE X
- ENTRY Y
- END
-
- The difference between the above two cases lies in the code compiled
-for the `X' and `Y' procedures themselves, plus the fact that, for the
-second case, an extra internal procedure is compiled.
-
- For every Fortran procedure with at least one `ENTRY' statement,
-`g77' compiles an extra procedure named `__g77_masterfun_X', where X is
-the name of the primary entry point (which, in the above case, using
-the standard compiler options, would be `x_' in C).
-
- This extra procedure is compiled as a private procedure--that is, a
-procedure not accessible by name to separately compiled modules. It
-contains all the code in the program unit, including the code for the
-primary entry point plus for every entry point. (The code for each
-public procedure is quite short, and explained later.)
-
- The extra procedure has some other interesting characteristics.
-
- The argument list for this procedure is invented by `g77'. It
-contains a single integer argument named `__g77_which_entrypoint',
-passed by value (as in Fortran's `%VAL()' intrinsic), specifying the
-entry point index--0 for the primary entry point, 1 for the first entry
-point (the first `ENTRY' statement encountered), 2 for the second entry
-point, and so on.
-
- It also contains, for functions returning `CHARACTER' and (when
-`-ff2c' is in effect) `COMPLEX' functions, and for functions returning
-different types among the `ENTRY' statements (e.g. `REAL FUNCTION R()'
-containing `ENTRY I()'), an argument named `__g77_result' that is
-expected at run time to contain a pointer to where to store the result
-of the entry point. For `CHARACTER' functions, this storage area is an
-array of the appropriate number of characters; for `COMPLEX' functions,
-it is the appropriate area for the return type; for
-multiple-return-type functions, it is a union of all the supported
-return types (which cannot include `CHARACTER', since combining
-`CHARACTER' and non-`CHARACTER' return types via `ENTRY' in a single
-function is not supported by `g77').
-
- For `CHARACTER' functions, the `__g77_result' argument is followed
-by yet another argument named `__g77_length' that, at run time,
-specifies the caller's expected length of the returned value. Note
-that only `CHARACTER*(*)' functions and entry points actually make use
-of this argument, even though it is always passed by all callers of
-public `CHARACTER' functions (since the caller does not generally know
-whether such a function is `CHARACTER*(*)' or whether there are any
-other callers that don't have that information).
-
- The rest of the argument list is the union of all the arguments
-specified for all the entry points (in their usual forms, e.g.
-`CHARACTER' arguments have extra length arguments, all appended at the
-end of this list). This is considered the "master list" of arguments.
-
- The code for this procedure has, before the code for the first
-executable statement, code much like that for the following Fortran
-statement:
-
- GOTO (100000,100001,100002), __g77_which_entrypoint
- 100000 ...code for primary entry point...
- 100001 ...code immediately following first ENTRY statement...
- 100002 ...code immediately following second ENTRY statement...
-
-(Note that invalid Fortran statement labels and variable names are used
-in the above example to highlight the fact that it represents code
-generated by the `g77' internals, not code to be written by the user.)
-
- It is this code that, when the procedure is called, picks which
-entry point to start executing.
-
- Getting back to the public procedures (`x' and `Y' in the original
-example), those procedures are fairly simple. Their interfaces are
-just like they would be if they were self-contained procedures (without
-`ENTRY'), of course, since that is what the callers expect. Their code
-consists of simply calling the private procedure, described above, with
-the appropriate extra arguments (the entry point index, and perhaps a
-pointer to a multiple-type- return variable, local to the public
-procedure, that contains all the supported returnable non-character
-types). For arguments that are not listed for a given entry point that
-are listed for other entry points, and therefore that are in the
-"master list" for the private procedure, null pointers (in C, the
-`NULL' macro) are passed. Also, for entry points that are part of a
-multiple-type- returning function, code is compiled after the call of
-the private procedure to extract from the multi-type union the
-appropriate result, depending on the type of the entry point in
-question, returning that result to the original caller.
-
- When debugging a procedure containing alternate entry points, you
-can either set a break point on the public procedure itself (e.g. a
-break point on `X' or `Y') or on the private procedure that contains
-most of the pertinent code (e.g. `__g77_masterfun_X'). If you do the
-former, you should use the debugger's command to "step into" the called
-procedure to get to the actual code; with the latter approach, the
-break point leaves you right at the actual code, skipping over the
-public entry point and its call to the private procedure (unless you
-have set a break point there as well, of course).
-
- Further, the list of dummy arguments that is visible when the
-private procedure is active is going to be the expanded version of the
-list for whichever particular entry point is active, as explained
-above, and the way in which return values are handled might well be
-different from how they would be handled for an equivalent single-entry
-function.
-
-\1f
-File: g77.info, Node: Alternate Returns, Next: Assigned Statement Labels, Prev: Alternate Entry Points, Up: Debugging and Interfacing
-
-Alternate Returns (SUBROUTINE and RETURN)
-=========================================
-
- Subroutines with alternate returns (e.g. `SUBROUTINE X(*)' and `CALL
-X(*50)') are implemented by `g77' as functions returning the C `int'
-type. The actual alternate-return arguments are omitted from the
-calling sequence. Instead, the caller uses the return value to do a
-rough equivalent of the Fortran computed-`GOTO' statement, as in `GOTO
-(50), X()' in the example above (where `X' is quietly declared as an
-`INTEGER(KIND=1)' function), and the callee just returns whatever
-integer is specified in the `RETURN' statement for the subroutine For
-example, `RETURN 1' is implemented as `X = 1' followed by `RETURN' in
-C, and `RETURN' by itself is `X = 0' and `RETURN').
-
-\1f
-File: g77.info, Node: Assigned Statement Labels, Next: Run-time Library Errors, Prev: Alternate Returns, Up: Debugging and Interfacing
-
-Assigned Statement Labels (ASSIGN and GOTO)
-===========================================
-
- For portability to machines where a pointer (such as to a label,
-which is how `g77' implements `ASSIGN' and its relatives, the
-assigned-`GOTO' and assigned-`FORMAT'-I/O statements) is wider
-(bitwise) than an `INTEGER(KIND=1)', `g77' uses a different memory
-location to hold the `ASSIGN'ed value of a variable than it does the
-numerical value in that variable, unless the variable is wide enough
-(can hold enough bits).
-
- In particular, while `g77' implements
-
- I = 10
-
-as, in C notation, `i = 10;', it implements
-
- ASSIGN 10 TO I
-
-as, in GNU's extended C notation (for the label syntax),
-`__g77_ASSIGN_I = &&L10;' (where `L10' is just a massaging of the
-Fortran label `10' to make the syntax C-like; `g77' doesn't actually
-generate the name `L10' or any other name like that, since debuggers
-cannot access labels anyway).
-
- While this currently means that an `ASSIGN' statement does not
-overwrite the numeric contents of its target variable, _do not_ write
-any code depending on this feature. `g77' has already changed this
-implementation across versions and might do so in the future. This
-information is provided only to make debugging Fortran programs
-compiled with the current version of `g77' somewhat easier. If there's
-no debugger-visible variable named `__g77_ASSIGN_I' in a program unit
-that does `ASSIGN 10 TO I', that probably means `g77' has decided it
-can store the pointer to the label directly into `I' itself.
-
- *Note Ugly Assigned Labels::, for information on a command-line
-option to force `g77' to use the same storage for both normal and
-assigned-label uses of a variable.
-
-\1f
-File: g77.info, Node: Run-time Library Errors, Prev: Assigned Statement Labels, Up: Debugging and Interfacing
-
-Run-time Library Errors
-=======================
-
- The `libg2c' library currently has the following table to relate
-error code numbers, returned in `IOSTAT=' variables, to messages. This
-information should, in future versions of this document, be expanded
-upon to include detailed descriptions of each message.
-
- In line with good coding practices, any of the numbers in the list
-below should _not_ be directly written into Fortran code you write.
-Instead, make a separate `INCLUDE' file that defines `PARAMETER' names
-for them, and use those in your code, so you can more easily change the
-actual numbers in the future.
-
- The information below is culled from the definition of `F_err' in
-`f/runtime/libI77/err.c' in the `g77' source tree.
-
- 100: "error in format"
- 101: "illegal unit number"
- 102: "formatted io not allowed"
- 103: "unformatted io not allowed"
- 104: "direct io not allowed"
- 105: "sequential io not allowed"
- 106: "can't backspace file"
- 107: "null file name"
- 108: "can't stat file"
- 109: "unit not connected"
- 110: "off end of record"
- 111: "truncation failed in endfile"
- 112: "incomprehensible list input"
- 113: "out of free space"
- 114: "unit not connected"
- 115: "read unexpected character"
- 116: "bad logical input field"
- 117: "bad variable type"
- 118: "bad namelist name"
- 119: "variable not in namelist"
- 120: "no end record"
- 121: "variable count incorrect"
- 122: "subscript for scalar variable"
- 123: "invalid array section"
- 124: "substring out of bounds"
- 125: "subscript out of bounds"
- 126: "can't read file"
- 127: "can't write file"
- 128: "'new' file exists"
- 129: "can't append to file"
- 130: "non-positive record number"
- 131: "I/O started while already doing I/O"
-
-\1f
-File: g77.info, Node: Collected Fortran Wisdom, Next: Trouble, Prev: Debugging and Interfacing, Up: Top
-
-Collected Fortran Wisdom
-************************
-
- Most users of `g77' can be divided into two camps:
-
- * Those writing new Fortran code to be compiled by `g77'.
-
- * Those using `g77' to compile existing, "legacy" code.
-
- Users writing new code generally understand most of the necessary
-aspects of Fortran to write "mainstream" code, but often need help
-deciding how to handle problems, such as the construction of libraries
-containing `BLOCK DATA'.
-
- Users dealing with "legacy" code sometimes don't have much
-experience with Fortran, but believe that the code they're compiling
-already works when compiled by other compilers (and might not
-understand why, as is sometimes the case, it doesn't work when compiled
-by `g77').
-
- The following information is designed to help users do a better job
-coping with existing, "legacy" Fortran code, and with writing new code
-as well.
-
-* Menu:
-
-* Advantages Over f2c:: If `f2c' is so great, why `g77'?
-* Block Data and Libraries:: How `g77' solves a common problem.
-* Loops:: Fortran `DO' loops surprise many people.
-* Working Programs:: Getting programs to work should be done first.
-* Overly Convenient Options:: Temptations to avoid, habits to not form.
-* Faster Programs:: Everybody wants these, but at what cost?
-
-\1f
-File: g77.info, Node: Advantages Over f2c, Next: Block Data and Libraries, Up: Collected Fortran Wisdom
-
-Advantages Over f2c
-===================
-
- Without `f2c', `g77' would have taken much longer to do and probably
-not been as good for quite a while. Sometimes people who notice how
-much `g77' depends on, and documents encouragement to use, `f2c' ask
-why `g77' was created if `f2c' already existed.
-
- This section gives some basic answers to these questions, though it
-is not intended to be comprehensive.
-
-* Menu:
-
-* Language Extensions:: Features used by Fortran code.
-* Diagnostic Abilities:: Abilities to spot problems early.
-* Compiler Options:: Features helpful to accommodate legacy code, etc.
-* Compiler Speed:: Speed of the compilation process.
-* Program Speed:: Speed of the generated, optimized code.
-* Ease of Debugging:: Debugging ease-of-use at the source level.
-* Character and Hollerith Constants:: A byte saved is a byte earned.
-
-\1f
-File: g77.info, Node: Language Extensions, Next: Diagnostic Abilities, Up: Advantages Over f2c
-
-Language Extensions
--------------------
-
- `g77' offers several extensions to FORTRAN 77 language that `f2c'
-doesn't:
-
- * Automatic arrays
-
- * `CYCLE' and `EXIT'
-
- * Construct names
-
- * `SELECT CASE'
-
- * `KIND=' and `LEN=' notation
-
- * Semicolon as statement separator
-
- * Constant expressions in `FORMAT' statements (such as
- `FORMAT(I<J>)', where `J' is a `PARAMETER' named constant)
-
- * `MvBits' intrinsic
-
- * `libU77' (Unix-compatibility) library, with routines known to
- compiler as intrinsics (so they work even when compiler options
- are used to change the interfaces used by Fortran routines)
-
- `g77' also implements iterative `DO' loops so that they work even in
-the presence of certain "extreme" inputs, unlike `f2c'. *Note Loops::.
-
- However, `f2c' offers a few that `g77' doesn't, such as:
-
- * Intrinsics in `PARAMETER' statements
-
- * Array bounds expressions (such as `REAL M(N(2))')
-
- * `AUTOMATIC' statement
-
- It is expected that `g77' will offer some or all of these missing
-features at some time in the future.
-
-\1f
-File: g77.info, Node: Diagnostic Abilities, Next: Compiler Options, Prev: Language Extensions, Up: Advantages Over f2c
-
-Diagnostic Abilities
---------------------
-
- `g77' offers better diagnosis of problems in `FORMAT' statements.
-`f2c' doesn't, for example, emit any diagnostic for
-`FORMAT(XZFAJG10324)', leaving that to be diagnosed, at run time, by
-the `libf2c' run-time library.
-
-\1f
-File: g77.info, Node: Compiler Options, Next: Compiler Speed, Prev: Diagnostic Abilities, Up: Advantages Over f2c
-
-Compiler Options
-----------------
-
- `g77' offers compiler options that `f2c' doesn't, most of which are
-designed to more easily accommodate legacy code:
-
- * Two that control the automatic appending of extra underscores to
- external names
-
- * One that allows dollar signs (`$') in symbol names
-
- * A variety that control acceptance of various "ugly" constructs
-
- * Several that specify acceptable use of upper and lower case in the
- source code
-
- * Many that enable, disable, delete, or hide groups of intrinsics
-
- * One to specify the length of fixed-form source lines (normally 72)
-
- * One to specify the the source code is written in Fortran-90-style
- free-form
-
- However, `f2c' offers a few that `g77' doesn't, like an option to
-have `REAL' default to `REAL*8'. It is expected that `g77' will offer
-all of the missing options pertinent to being a Fortran compiler at
-some time in the future.
-
-\1f
-File: g77.info, Node: Compiler Speed, Next: Program Speed, Prev: Compiler Options, Up: Advantages Over f2c
-
-Compiler Speed
---------------
-
- Saving the steps of writing and then rereading C code is a big reason
-why `g77' should be able to compile code much faster than using `f2c'
-in conjunction with the equivalent invocation of `gcc'.
-
- However, due to `g77''s youth, lots of self-checking is still being
-performed. As a result, this improvement is as yet unrealized (though
-the potential seems to be there for quite a big speedup in the future).
-It is possible that, as of version 0.5.18, `g77' is noticeably faster
-compiling many Fortran source files than using `f2c' in conjunction
-with `gcc'.
-
-\1f
-File: g77.info, Node: Program Speed, Next: Ease of Debugging, Prev: Compiler Speed, Up: Advantages Over f2c
-
-Program Speed
--------------
-
- `g77' has the potential to better optimize code than `f2c', even
-when `gcc' is used to compile the output of `f2c', because `f2c' must
-necessarily translate Fortran into a somewhat lower-level language (C)
-that cannot preserve all the information that is potentially useful for
-optimization, while `g77' can gather, preserve, and transmit that
-information directly to the GBE.
-
- For example, `g77' implements `ASSIGN' and assigned `GOTO' using
-direct assignment of pointers to labels and direct jumps to labels,
-whereas `f2c' maps the assigned labels to integer values and then uses
-a C `switch' statement to encode the assigned `GOTO' statements.
-
- However, as is typical, theory and reality don't quite match, at
-least not in all cases, so it is still the case that `f2c' plus `gcc'
-can generate code that is faster than `g77'.
-
- Version 0.5.18 of `g77' offered default settings and options, via
-patches to the `gcc' back end, that allow for better program speed,
-though some of these improvements also affected the performance of
-programs translated by `f2c' and then compiled by `g77''s version of
-`gcc'.
-
- Version 0.5.20 of `g77' offers further performance improvements, at
-least one of which (alias analysis) is not generally applicable to
-`f2c' (though `f2c' could presumably be changed to also take advantage
-of this new capability of the `gcc' back end, assuming this is made
-available in an upcoming release of `gcc').
-
-\1f
-File: g77.info, Node: Ease of Debugging, Next: Character and Hollerith Constants, Prev: Program Speed, Up: Advantages Over f2c
-
-Ease of Debugging
------------------
-
- Because `g77' compiles directly to assembler code like `gcc',
-instead of translating to an intermediate language (C) as does `f2c',
-support for debugging can be better for `g77' than `f2c'.
-
- However, although `g77' might be somewhat more "native" in terms of
-debugging support than `f2c' plus `gcc', there still are a lot of
-things "not quite right". Many of the important ones should be
-resolved in the near future.
-
- For example, `g77' doesn't have to worry about reserved names like
-`f2c' does. Given `FOR = WHILE', `f2c' must necessarily translate this
-to something _other_ than `for = while;', because C reserves those
-words.
-
- However, `g77' does still uses things like an extra level of
-indirection for `ENTRY'-laden procedures--in this case, because the
-back end doesn't yet support multiple entry points.
-
- Another example is that, given
-
- COMMON A, B
- EQUIVALENCE (B, C)
-
-the `g77' user should be able to access the variables directly, by name,
-without having to traverse C-like structures and unions, while `f2c' is
-unlikely to ever offer this ability (due to limitations in the C
-language).
-
- However, due to apparent bugs in the back end, `g77' currently
-doesn't take advantage of this facility at all--it doesn't emit any
-debugging information for `COMMON' and `EQUIVALENCE' areas, other than
-information on the array of `char' it creates (and, in the case of
-local `EQUIVALENCE', names) for each such area.
-
- Yet another example is arrays. `g77' represents them to the debugger
-using the same "dimensionality" as in the source code, while `f2c' must
-necessarily convert them all to one-dimensional arrays to fit into the
-confines of the C language. However, the level of support offered by
-debuggers for interactive Fortran-style access to arrays as compiled by
-`g77' can vary widely. In some cases, it can actually be an advantage
-that `f2c' converts everything to widely supported C semantics.
-
- In fairness, `g77' could do many of the things `f2c' does to get
-things working at least as well as `f2c'--for now, the developers
-prefer making `g77' work the way they think it is supposed to, and
-finding help improving the other products (the back end of `gcc';
-`gdb'; and so on) to get things working properly.
-
-\1f
-File: g77.info, Node: Character and Hollerith Constants, Prev: Ease of Debugging, Up: Advantages Over f2c
-
-Character and Hollerith Constants
----------------------------------
-
- To avoid the extensive hassle that would be needed to avoid this,
-`f2c' uses C character constants to encode character and Hollerith
-constants. That means a constant like `'HELLO'' is translated to
-`"hello"' in C, which further means that an extra null byte is present
-at the end of the constant. This null byte is superfluous.
-
- `g77' does not generate such null bytes. This represents significant
-savings of resources, such as on systems where `/dev/null' or
-`/dev/zero' represent bottlenecks in the systems' performance, because
-`g77' simply asks for fewer zeros from the operating system than `f2c'.
-(Avoiding spurious use of zero bytes, each byte typically have eight
-zero bits, also reduces the liabilities in case Microsoft's rumored
-patent on the digits 0 and 1 is upheld.)
-
-\1f
-File: g77.info, Node: Block Data and Libraries, Next: Loops, Prev: Advantages Over f2c, Up: Collected Fortran Wisdom
-
-Block Data and Libraries
-========================
-
- To ensure that block data program units are linked, especially a
-concern when they are put into libraries, give each one a name (as in
-`BLOCK DATA FOO') and make sure there is an `EXTERNAL FOO' statement in
-every program unit that uses any common block initialized by the
-corresponding `BLOCK DATA'. `g77' currently compiles a `BLOCK DATA' as
-if it were a `SUBROUTINE', that is, it generates an actual procedure
-having the appropriate name. The procedure does nothing but return
-immediately if it happens to be called. For `EXTERNAL FOO', where
-`FOO' is not otherwise referenced in the same program unit, `g77'
-assumes there exists a `BLOCK DATA FOO' in the program and ensures that
-by generating a reference to it so the linker will make sure it is
-present. (Specifically, `g77' outputs in the data section a static
-pointer to the external name `FOO'.)
-
- The implementation `g77' currently uses to make this work is one of
-the few things not compatible with `f2c' as currently shipped. `f2c'
-currently does nothing with `EXTERNAL FOO' except issue a warning that
-`FOO' is not otherwise referenced, and, for `BLOCK DATA FOO', `f2c'
-doesn't generate a dummy procedure with the name `FOO'. The upshot is
-that you shouldn't mix `f2c' and `g77' in this particular case. If you
-use `f2c' to compile `BLOCK DATA FOO', then any `g77'-compiled program
-unit that says `EXTERNAL FOO' will result in an unresolved reference
-when linked. If you do the opposite, then `FOO' might not be linked in
-under various circumstances (such as when `FOO' is in a library, or
-you're using a "clever" linker--so clever, it produces a broken program
-with little or no warning by omitting initializations of global data
-because they are contained in unreferenced procedures).
-
- The changes you make to your code to make `g77' handle this
-situation, however, appear to be a widely portable way to handle it.
-That is, many systems permit it (as they should, since the FORTRAN 77
-standard permits `EXTERNAL FOO' when `FOO' is a block data program
-unit), and of the ones that might not link `BLOCK DATA FOO' under some
-circumstances, most of them appear to do so once `EXTERNAL FOO' is
-present in the appropriate program units.
-
- Here is the recommended approach to modifying a program containing a
-program unit such as the following:
-
- BLOCK DATA FOO
- COMMON /VARS/ X, Y, Z
- DATA X, Y, Z / 3., 4., 5. /
- END
-
-If the above program unit might be placed in a library module, then
-ensure that every program unit in every program that references that
-particular `COMMON' area uses the `EXTERNAL' statement to force the
-area to be initialized.
-
- For example, change a program unit that starts with
-
- INTEGER FUNCTION CURX()
- COMMON /VARS/ X, Y, Z
- CURX = X
- END
-
-so that it uses the `EXTERNAL' statement, as in:
-
- INTEGER FUNCTION CURX()
- COMMON /VARS/ X, Y, Z
- EXTERNAL FOO
- CURX = X
- END
-
-That way, `CURX' is compiled by `g77' (and many other compilers) so
-that the linker knows it must include `FOO', the `BLOCK DATA' program
-unit that sets the initial values for the variables in `VAR', in the
-executable program.
-
-\1f
-File: g77.info, Node: Loops, Next: Working Programs, Prev: Block Data and Libraries, Up: Collected Fortran Wisdom
-
-Loops
-=====
-
- The meaning of a `DO' loop in Fortran is precisely specified in the
-Fortran standard...and is quite different from what many programmers
-might expect.
-
- In particular, Fortran iterative `DO' loops are implemented as if
-the number of trips through the loop is calculated _before_ the loop is
-entered.
-
- The number of trips for a loop is calculated from the START, END,
-and INCREMENT values specified in a statement such as:
-
- DO ITER = START, END, INCREMENT
-
-The trip count is evaluated using a fairly simple formula based on the
-three values following the `=' in the statement, and it is that trip
-count that is effectively decremented during each iteration of the loop.
-If, at the beginning of an iteration of the loop, the trip count is
-zero or negative, the loop terminates. The per-loop-iteration
-modifications to ITER are not related to determining whether to
-terminate the loop.
-
- There are two important things to remember about the trip count:
-
- * It can be _negative_, in which case it is treated as if it was
- zero--meaning the loop is not executed at all.
-
- * The type used to _calculate_ the trip count is the same type as
- ITER, but the final calculation, and thus the type of the trip
- count itself, always is `INTEGER(KIND=1)'.
-
- These two items mean that there are loops that cannot be written in
-straightforward fashion using the Fortran `DO'.
-
- For example, on a system with the canonical 32-bit two's-complement
-implementation of `INTEGER(KIND=1)', the following loop will not work:
-
- DO I = -2000000000, 2000000000
-
-Although the START and END values are well within the range of
-`INTEGER(KIND=1)', the _trip count_ is not. The expected trip count is
-40000000001, which is outside the range of `INTEGER(KIND=1)' on many
-systems.
-
- Instead, the above loop should be constructed this way:
-
- I = -2000000000
- DO
- IF (I .GT. 2000000000) EXIT
- ...
- I = I + 1
- END DO
-
-The simple `DO' construct and the `EXIT' statement (used to leave the
-innermost loop) are F90 features that `g77' supports.
-
- Some Fortran compilers have buggy implementations of `DO', in that
-they don't follow the standard. They implement `DO' as a
-straightforward translation to what, in C, would be a `for' statement.
-Instead of creating a temporary variable to hold the trip count as
-calculated at run time, these compilers use the iteration variable ITER
-to control whether the loop continues at each iteration.
-
- The bug in such an implementation shows up when the trip count is
-within the range of the type of ITER, but the magnitude of `ABS(END) +
-ABS(INCR)' exceeds that range. For example:
-
- DO I = 2147483600, 2147483647
-
-A loop started by the above statement will work as implemented by
-`g77', but the use, by some compilers, of a more C-like implementation
-akin to
-
- for (i = 2147483600; i <= 2147483647; ++i)
-
-produces a loop that does not terminate, because `i' can never be
-greater than 2147483647, since incrementing it beyond that value
-overflows `i', setting it to -2147483648. This is a large, negative
-number that still is less than 2147483647.
-
- Another example of unexpected behavior of `DO' involves using a
-nonintegral iteration variable ITER, that is, a `REAL' variable.
-Consider the following program:
-
- DATA BEGIN, END, STEP /.1, .31, .007/
- DO 10 R = BEGIN, END, STEP
- IF (R .GT. END) PRINT *, R, ' .GT. ', END, '!!'
- PRINT *,R
- 10 CONTINUE
- PRINT *,'LAST = ',R
- IF (R .LE. END) PRINT *, R, ' .LE. ', END, '!!'
- END
-
-A C-like view of `DO' would hold that the two "exclamatory" `PRINT'
-statements are never executed. However, this is the output of running
-the above program as compiled by `g77' on a GNU/Linux ix86 system:
-
- .100000001
- .107000001
- .114
- .120999999
- ...
- .289000005
- .296000004
- .303000003
- LAST = .310000002
- .310000002 .LE. .310000002!!
-
- Note that one of the two checks in the program turned up an apparent
-violation of the programmer's expectation--yet, the loop is correctly
-implemented by `g77', in that it has 30 iterations. This trip count of
-30 is correct when evaluated using the floating-point representations
-for the BEGIN, END, and INCR values (.1, .31, .007) on GNU/Linux ix86
-are used. On other systems, an apparently more accurate trip count of
-31 might result, but, nevertheless, `g77' is faithfully following the
-Fortran standard, and the result is not what the author of the sample
-program above apparently expected. (Such other systems might, for
-different values in the `DATA' statement, violate the other
-programmer's expectation, for example.)
-
- Due to this combination of imprecise representation of
-floating-point values and the often-misunderstood interpretation of
-`DO' by standard-conforming compilers such as `g77', use of `DO' loops
-with `REAL' iteration variables is not recommended. Such use can be
-caught by specifying `-Wsurprising'. *Note Warning Options::, for more
-information on this option.
-
-\1f
-File: g77.info, Node: Working Programs, Next: Overly Convenient Options, Prev: Loops, Up: Collected Fortran Wisdom
-
-Working Programs
-================
-
- Getting Fortran programs to work in the first place can be quite a
-challenge--even when the programs already work on other systems, or
-when using other compilers.
-
- `g77' offers some facilities that might be useful for tracking down
-bugs in such programs.
-
-* Menu:
-
-* Not My Type::
-* Variables Assumed To Be Zero::
-* Variables Assumed To Be Saved::
-* Unwanted Variables::
-* Unused Arguments::
-* Surprising Interpretations of Code::
-* Aliasing Assumed To Work::
-* Output Assumed To Flush::
-* Large File Unit Numbers::
-* Floating-point precision::
-* Inconsistent Calling Sequences::
-
-\1f
-File: g77.info, Node: Not My Type, Next: Variables Assumed To Be Zero, Up: Working Programs
-
-Not My Type
------------
-
- A fruitful source of bugs in Fortran source code is use, or mis-use,
-of Fortran's implicit-typing feature, whereby the type of a variable,
-array, or function is determined by the first character of its name.
-
- Simple cases of this include statements like `LOGX=9.227', without a
-statement such as `REAL LOGX'. In this case, `LOGX' is implicitly
-given `INTEGER(KIND=1)' type, with the result of the assignment being
-that it is given the value `9'.
-
- More involved cases include a function that is defined starting with
-a statement like `DOUBLE PRECISION FUNCTION IPS(...)'. Any caller of
-this function that does not also declare `IPS' as type `DOUBLE
-PRECISION' (or, in GNU Fortran, `REAL(KIND=2)') is likely to assume it
-returns `INTEGER', or some other type, leading to invalid results or
-even program crashes.
-
- The `-Wimplicit' option might catch failures to properly specify the
-types of variables, arrays, and functions in the code.
-
- However, in code that makes heavy use of Fortran's implicit-typing
-facility, this option might produce so many warnings about cases that
-are working, it would be hard to find the one or two that represent
-bugs. This is why so many experienced Fortran programmers strongly
-recommend widespread use of the `IMPLICIT NONE' statement, despite it
-not being standard FORTRAN 77, to completely turn off implicit typing.
-(`g77' supports `IMPLICIT NONE', as do almost all FORTRAN 77 compilers.)
-
- Note that `-Wimplicit' catches only implicit typing of _names_. It
-does not catch implicit typing of expressions such as `X**(2/3)'. Such
-expressions can be buggy as well--in fact, `X**(2/3)' is equivalent to
-`X**0', due to the way Fortran expressions are given types and then
-evaluated. (In this particular case, the programmer probably wanted
-`X**(2./3.)'.)
-
-\1f
-File: g77.info, Node: Variables Assumed To Be Zero, Next: Variables Assumed To Be Saved, Prev: Not My Type, Up: Working Programs
-
-Variables Assumed To Be Zero
-----------------------------
-
- Many Fortran programs were developed on systems that provided
-automatic initialization of all, or some, variables and arrays to zero.
-As a result, many of these programs depend, sometimes inadvertently, on
-this behavior, though to do so violates the Fortran standards.
-
- You can ask `g77' for this behavior by specifying the
-`-finit-local-zero' option when compiling Fortran code. (You might
-want to specify `-fno-automatic' as well, to avoid code-size inflation
-for non-optimized compilations.)
-
- Note that a program that works better when compiled with the
-`-finit-local-zero' option is almost certainly depending on a
-particular system's, or compiler's, tendency to initialize some
-variables to zero. It might be worthwhile finding such cases and
-fixing them, using techniques such as compiling with the `-O
--Wuninitialized' options using `g77'.
-
-\1f
-File: g77.info, Node: Variables Assumed To Be Saved, Next: Unwanted Variables, Prev: Variables Assumed To Be Zero, Up: Working Programs
-
-Variables Assumed To Be Saved
------------------------------
-
- Many Fortran programs were developed on systems that saved the
-values of all, or some, variables and arrays across procedure calls.
-As a result, many of these programs depend, sometimes inadvertently, on
-being able to assign a value to a variable, perform a `RETURN' to a
-calling procedure, and, upon subsequent invocation, reference the
-previously assigned variable to obtain the value.
-
- They expect this despite not using the `SAVE' statement to specify
-that the value in a variable is expected to survive procedure returns
-and calls. Depending on variables and arrays to retain values across
-procedure calls without using `SAVE' to require it violates the Fortran
-standards.
-
- You can ask `g77' to assume `SAVE' is specified for all relevant
-(local) variables and arrays by using the `-fno-automatic' option.
-
- Note that a program that works better when compiled with the
-`-fno-automatic' option is almost certainly depending on not having to
-use the `SAVE' statement as required by the Fortran standard. It might
-be worthwhile finding such cases and fixing them, using techniques such
-as compiling with the `-O -Wuninitialized' options using `g77'.
-
-\1f
-File: g77.info, Node: Unwanted Variables, Next: Unused Arguments, Prev: Variables Assumed To Be Saved, Up: Working Programs
-
-Unwanted Variables
-------------------
-
- The `-Wunused' option can find bugs involving implicit typing,
-sometimes more easily than using `-Wimplicit' in code that makes heavy
-use of implicit typing. An unused variable or array might indicate
-that the spelling for its declaration is different from that of its
-intended uses.
-
- Other than cases involving typos, unused variables rarely indicate
-actual bugs in a program. However, investigating such cases thoroughly
-has, on occasion, led to the discovery of code that had not been
-completely written--where the programmer wrote declarations as needed
-for the whole algorithm, wrote some or even most of the code for that
-algorithm, then got distracted and forgot that the job was not complete.
-
-\1f
-File: g77.info, Node: Unused Arguments, Next: Surprising Interpretations of Code, Prev: Unwanted Variables, Up: Working Programs
-
-Unused Arguments
-----------------
-
- As with unused variables, It is possible that unused arguments to a
-procedure might indicate a bug. Compile with `-W -Wunused' option to
-catch cases of unused arguments.
-
- Note that `-W' also enables warnings regarding overflow of
-floating-point constants under certain circumstances.
-
-\1f
-File: g77.info, Node: Surprising Interpretations of Code, Next: Aliasing Assumed To Work, Prev: Unused Arguments, Up: Working Programs
-
-Surprising Interpretations of Code
-----------------------------------
-
- The `-Wsurprising' option can help find bugs involving expression
-evaluation or in the way `DO' loops with non-integral iteration
-variables are handled. Cases found by this option might indicate a
-difference of interpretation between the author of the code involved,
-and a standard-conforming compiler such as `g77'. Such a difference
-might produce actual bugs.
-
- In any case, changing the code to explicitly do what the programmer
-might have expected it to do, so `g77' and other compilers are more
-likely to follow the programmer's expectations, might be worthwhile,
-especially if such changes make the program work better.
-
projects / msp430-gcc.git / blobdiff