+++ /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: Aliasing Assumed To Work, Next: Output Assumed To Flush, Prev: Surprising Interpretations of Code, Up: Working Programs
-
-Aliasing Assumed To Work
-------------------------
-
- The `-falias-check', `-fargument-alias', `-fargument-noalias', and
-`-fno-argument-noalias-global' options, introduced in version 0.5.20 and
-`g77''s version 2.7.2.2.f.2 of `gcc', were withdrawn as of `g77'
-version 0.5.23 due to their not being supported by `gcc' version 2.8.
-
- These options control the assumptions regarding aliasing
-(overlapping) of writes and reads to main memory (core) made by the
-`gcc' back end.
-
- The information below still is useful, but applies to only those
-versions of `g77' that support the alias analysis implied by support
-for these options.
-
- These options are effective only when compiling with `-O'
-(specifying any level other than `-O0') or with `-falias-check'.
-
- The default for Fortran code is `-fargument-noalias-global'. (The
-default for C code and code written in other C-based languages is
-`-fargument-alias'. These defaults apply regardless of whether you use
-`g77' or `gcc' to compile your code.)
-
- Note that, on some systems, compiling with `-fforce-addr' in effect
-can produce more optimal code when the default aliasing options are in
-effect (and when optimization is enabled).
-
- If your program is not working when compiled with optimization, it
-is possible it is violating the Fortran standards (77 and 90) by
-relying on the ability to "safely" modify variables and arrays that are
-aliased, via procedure calls, to other variables and arrays, without
-using `EQUIVALENCE' to explicitly set up this kind of aliasing.
-
- (The FORTRAN 77 standard's prohibition of this sort of overlap,
-generally referred to therein as "storage assocation", appears in
-Sections 15.9.3.6. This prohibition allows implementations, such as
-`g77', to, for example, implement the passing of procedures and even
-values in `COMMON' via copy operations into local, perhaps more
-efficiently accessed temporaries at entry to a procedure, and, where
-appropriate, via copy operations back out to their original locations
-in memory at exit from that procedure, without having to take into
-consideration the order in which the local copies are updated by the
-code, among other things.)
-
- To test this hypothesis, try compiling your program with the
-`-fargument-alias' option, which causes the compiler to revert to
-assumptions essentially the same as made by versions of `g77' prior to
-0.5.20.
-
- If the program works using this option, that strongly suggests that
-the bug is in your program. Finding and fixing the bug(s) should
-result in a program that is more standard-conforming and that can be
-compiled by `g77' in a way that results in a faster executable.
-
- (You might want to try compiling with `-fargument-noalias', a kind
-of half-way point, to see if the problem is limited to aliasing between
-dummy arguments and `COMMON' variables--this option assumes that such
-aliasing is not done, while still allowing aliasing among dummy
-arguments.)
-
- An example of aliasing that is invalid according to the standards is
-shown in the following program, which might _not_ produce the expected
-results when executed:
-
- I = 1
- CALL FOO(I, I)
- PRINT *, I
- END
-
- SUBROUTINE FOO(J, K)
- J = J + K
- K = J * K
- PRINT *, J, K
- END
-
- The above program attempts to use the temporary aliasing of the `J'
-and `K' arguments in `FOO' to effect a pathological behavior--the
-simultaneous changing of the values of _both_ `J' and `K' when either
-one of them is written.
-
- The programmer likely expects the program to print these values:
-
- 2 4
- 4
-
- However, since the program is not standard-conforming, an
-implementation's behavior when running it is undefined, because
-subroutine `FOO' modifies at least one of the arguments, and they are
-aliased with each other. (Even if one of the assignment statements was
-deleted, the program would still violate these rules. This kind of
-on-the-fly aliasing is permitted by the standard only when none of the
-aliased items are defined, or written, while the aliasing is in effect.)
-
- As a practical example, an optimizing compiler might schedule the `J
-=' part of the second line of `FOO' _after_ the reading of `J' and `K'
-for the `J * K' expression, resulting in the following output:
-
- 2 2
- 2
-
- Essentially, compilers are promised (by the standard and, therefore,
-by programmers who write code they claim to be standard-conforming)
-that if they cannot detect aliasing via static analysis of a single
-program unit's `EQUIVALENCE' and `COMMON' statements, no such aliasing
-exists. In such cases, compilers are free to assume that an assignment
-to one variable will not change the value of another variable, allowing
-it to avoid generating code to re-read the value of the other variable,
-to re-schedule reads and writes, and so on, to produce a faster
-executable.
-
- The same promise holds true for arrays (as seen by the called
-procedure)--an element of one dummy array cannot be aliased with, or
-overlap, any element of another dummy array or be in a `COMMON' area
-known to the procedure.
-
- (These restrictions apply only when the procedure defines, or writes
-to, one of the aliased variables or arrays.)
-
- Unfortunately, there is no way to find _all_ possible cases of
-violations of the prohibitions against aliasing in Fortran code.
-Static analysis is certainly imperfect, as is run-time analysis, since
-neither can catch all violations. (Static analysis can catch all
-likely violations, and some that might never actually happen, while
-run-time analysis can catch only those violations that actually happen
-during a particular run. Neither approach can cope with programs
-mixing Fortran code with routines written in other languages, however.)
-
- Currently, `g77' provides neither static nor run-time facilities to
-detect any cases of this problem, although other products might.
-Run-time facilities are more likely to be offered by future versions of
-`g77', though patches improving `g77' so that it provides either form
-of detection are welcome.
-
-\1f
-File: g77.info, Node: Output Assumed To Flush, Next: Large File Unit Numbers, Prev: Aliasing Assumed To Work, Up: Working Programs
-
-Output Assumed To Flush
------------------------
-
- For several versions prior to 0.5.20, `g77' configured its version
-of the `libf2c' run-time library so that one of its configuration
-macros, `ALWAYS_FLUSH', was defined.
-
- This was done as a result of a belief that many programs expected
-output to be flushed to the operating system (under UNIX, via the
-`fflush()' library call) with the result that errors, such as disk
-full, would be immediately flagged via the relevant `ERR=' and
-`IOSTAT=' mechanism.
-
- Because of the adverse effects this approach had on the performance
-of many programs, `g77' no longer configures `libf2c' (now named
-`libg2c' in its `g77' incarnation) to always flush output.
-
- If your program depends on this behavior, either insert the
-appropriate `CALL FLUSH' statements, or modify the sources to the
-`libg2c', rebuild and reinstall `g77', and relink your programs with
-the modified library.
-
- (Ideally, `libg2c' would offer the choice at run-time, so that a
-compile-time option to `g77' or `f2c' could result in generating the
-appropriate calls to flushing or non-flushing library routines.)
-
- Some Fortran programs require output (writes) to be flushed to the
-operating system (under UNIX, via the `fflush()' library call) so that
-errors, such as disk full, are immediately flagged via the relevant
-`ERR=' and `IOSTAT=' mechanism, instead of such errors being flagged
-later as subsequent writes occur, forcing the previously written data
-to disk, or when the file is closed.
-
- Essentially, the difference can be viewed as synchronous error
-reporting (immediate flagging of errors during writes) versus
-asynchronous, or, more precisely, buffered error reporting (detection
-of errors might be delayed).
-
- `libg2c' supports flagging write errors immediately when it is built
-with the `ALWAYS_FLUSH' macro defined. This results in a `libg2c' that
-runs slower, sometimes quite a bit slower, under certain
-circumstances--for example, accessing files via the networked file
-system NFS--but the effect can be more reliable, robust file I/O.
-
- If you know that Fortran programs requiring this level of precision
-of error reporting are to be compiled using the version of `g77' you
-are building, you might wish to modify the `g77' source tree so that
-the version of `libg2c' is built with the `ALWAYS_FLUSH' macro defined,
-enabling this behavior.
-
- To do this, find this line in `gcc/libf2c/f2c.h' in your `g77'
-source tree:
-
- /* #define ALWAYS_FLUSH */
-
- Remove the leading `/* ', so the line begins with `#define', and the
-trailing ` */'.
-
- Then build or rebuild `g77' as appropriate.
-
-\1f
-File: g77.info, Node: Large File Unit Numbers, Next: Floating-point precision, Prev: Output Assumed To Flush, Up: Working Programs
-
-Large File Unit Numbers
------------------------
-
- If your program crashes at run time with a message including the
-text `illegal unit number', that probably is a message from the
-run-time library, `libg2c'.
-
- The message means that your program has attempted to use a file unit
-number that is out of the range accepted by `libg2c'. Normally, this
-range is 0 through 99, and the high end of the range is controlled by a
-`libg2c' source-file macro named `MXUNIT'.
-
- If you can easily change your program to use unit numbers in the
-range 0 through 99, you should do so.
-
- As distributed, whether as part of `f2c' or `g77', `libf2c' accepts
-file unit numbers only in the range 0 through 99. For example, a
-statement such as `WRITE (UNIT=100)' causes a run-time crash in
-`libf2c', because the unit number, 100, is out of range.
-
- If you know that Fortran programs at your installation require the
-use of unit numbers higher than 99, you can change the value of the
-`MXUNIT' macro, which represents the maximum unit number, to an
-appropriately higher value.
-
- To do this, edit the file `gcc/libf2c/libI77/fio.h' in your `g77'
-source tree, changing the following line:
-
- #define MXUNIT 100
-
- Change the line so that the value of `MXUNIT' is defined to be at
-least one _greater_ than the maximum unit number used by the Fortran
-programs on your system.
-
- (For example, a program that does `WRITE (UNIT=255)' would require
-`MXUNIT' set to at least 256 to avoid crashing.)
-
- Then build or rebuild `g77' as appropriate.
-
- _Note:_ Changing this macro has _no_ effect on other limits your
-system might place on the number of files open at the same time. That
-is, the macro might allow a program to do `WRITE (UNIT=100)', but the
-library and operating system underlying `libf2c' might disallow it if
-many other files have already been opened (via `OPEN' or implicitly via
-`READ', `WRITE', and so on). Information on how to increase these
-other limits should be found in your system's documentation.
-
-\1f
-File: g77.info, Node: Floating-point precision, Next: Inconsistent Calling Sequences, Prev: Large File Unit Numbers, Up: Working Programs
-
-Floating-point precision
-------------------------
-
- If your program depends on exact IEEE 754 floating-point handling it
-may help on some systems--specifically x86 or m68k hardware--to use the
-`-ffloat-store' option or to reset the precision flag on the
-floating-point unit. *Note Optimize Options::.
-
- However, it might be better simply to put the FPU into double
-precision mode and not take the performance hit of `-ffloat-store'. On
-x86 and m68k GNU systems you can do this with a technique similar to
-that for turning on floating-point exceptions (*note Floating-point
-Exception Handling::). The control word could be set to double
-precision by some code like this one:
- #include <fpu_control.h>
- {
- fpu_control_t cw = (_FPU_DEFAULT & ~_FPU_EXTENDED) | _FPU_DOUBLE;
- _FPU_SETCW(cw);
- }
- (It is not clear whether this has any effect on the operation of the
-GNU maths library, but we have no evidence of it causing trouble.)
-
- Some targets (such as the Alpha) may need special options for full
-IEEE conformance. *Note Hardware Models and Configurations:
-(gcc)Submodel Options.
-
-\1f
-File: g77.info, Node: Inconsistent Calling Sequences, Prev: Floating-point precision, Up: Working Programs
-
-Inconsistent Calling Sequences
-------------------------------
-
- Code containing inconsistent calling sequences in the same file is
-normally rejected--see *Note GLOBALS::. (Use, say, `ftnchek' to ensure
-consistency across source files. *Note Generating Skeletons and
-Prototypes with `f2c': f2c Skeletons and Prototypes.)
-
- Mysterious errors, which may appear to be code generation problems,
-can appear specifically on the x86 architecture with some such
-inconsistencies. On x86 hardware, floating-point return values of
-functions are placed on the floating-point unit's register stack, not
-the normal stack. Thus calling a `REAL' or `DOUBLE PRECISION'
-`FUNCTION' as some other sort of procedure, or vice versa, scrambles
-the floating-point stack. This may break unrelated code executed
-later. Similarly if, say, external C routines are written incorrectly.
-
-\1f
-File: g77.info, Node: Overly Convenient Options, Next: Faster Programs, Prev: Working Programs, Up: Collected Fortran Wisdom
-
-Overly Convenient Command-line Options
-======================================
-
- These options should be used only as a quick-and-dirty way to
-determine how well your program will run under different compilation
-models without having to change the source. Some are more problematic
-than others, depending on how portable and maintainable you want the
-program to be (and, of course, whether you are allowed to change it at
-all is crucial).
-
- You should not continue to use these command-line options to compile
-a given program, but rather should make changes to the source code:
-
-`-finit-local-zero'
- (This option specifies that any uninitialized local variables and
- arrays have default initialization to binary zeros.)
-
- Many other compilers do this automatically, which means lots of
- Fortran code developed with those compilers depends on it.
-
- It is safer (and probably would produce a faster program) to find
- the variables and arrays that need such initialization and provide
- it explicitly via `DATA', so that `-finit-local-zero' is not
- needed.
-
- Consider using `-Wuninitialized' (which requires `-O') to find
- likely candidates, but do not specify `-finit-local-zero' or
- `-fno-automatic', or this technique won't work.
-
-`-fno-automatic'
- (This option specifies that all local variables and arrays are to
- be treated as if they were named in `SAVE' statements.)
-
- Many other compilers do this automatically, which means lots of
- Fortran code developed with those compilers depends on it.
-
- The effect of this is that all non-automatic variables and arrays
- are made static, that is, not placed on the stack or in heap
- storage. This might cause a buggy program to appear to work
- better. If so, rather than relying on this command-line option
- (and hoping all compilers provide the equivalent one), add `SAVE'
- statements to some or all program unit sources, as appropriate.
- Consider using `-Wuninitialized' (which requires `-O') to find
- likely candidates, but do not specify `-finit-local-zero' or
- `-fno-automatic', or this technique won't work.
-
- The default is `-fautomatic', which tells `g77' to try and put
- variables and arrays on the stack (or in fast registers) where
- possible and reasonable. This tends to make programs faster.
-
- _Note:_ Automatic variables and arrays are not affected by this
- option. These are variables and arrays that are _necessarily_
- automatic, either due to explicit statements, or due to the way
- they are declared. Examples include local variables and arrays
- not given the `SAVE' attribute in procedures declared `RECURSIVE',
- and local arrays declared with non-constant bounds (automatic
- arrays). Currently, `g77' supports only automatic arrays, not
- `RECURSIVE' procedures or other means of explicitly specifying
- that variables or arrays are automatic.
-
-`-fGROUP-intrinsics-hide'
- Change the source code to use `EXTERNAL' for any external procedure
- that might be the name of an intrinsic. It is easy to find these
- using `-fGROUP-intrinsics-disable'.
-
-\1f
-File: g77.info, Node: Faster Programs, Prev: Overly Convenient Options, Up: Collected Fortran Wisdom
-
-Faster Programs
-===============
-
- Aside from the usual `gcc' options, such as `-O', `-ffast-math', and
-so on, consider trying some of the following approaches to speed up
-your program (once you get it working).
-
-* Menu:
-
-* Aligned Data::
-* Prefer Automatic Uninitialized Variables::
-* Avoid f2c Compatibility::
-* Use Submodel Options::
-
-\1f
-File: g77.info, Node: Aligned Data, Next: Prefer Automatic Uninitialized Variables, Up: Faster Programs
-
-Aligned Data
-------------
-
- On some systems, such as those with Pentium Pro CPUs, programs that
-make heavy use of `REAL(KIND=2)' (`DOUBLE PRECISION') might run much
-slower than possible due to the compiler not aligning these 64-bit
-values to 64-bit boundaries in memory. (The effect also is present,
-though to a lesser extent, on the 586 (Pentium) architecture.)
-
- The Intel x86 architecture generally ensures that these programs will
-work on all its implementations, but particular implementations (such
-as Pentium Pro) perform better with more strict alignment. (Such
-behavior isn't unique to the Intel x86 architecture.) Other
-architectures might _demand_ 64-bit alignment of 64-bit data.
-
- There are a variety of approaches to use to address this problem:
-
- * Order your `COMMON' and `EQUIVALENCE' areas such that the
- variables and arrays with the widest alignment guidelines come
- first.
-
- For example, on most systems, this would mean placing
- `COMPLEX(KIND=2)', `REAL(KIND=2)', and `INTEGER(KIND=2)' entities
- first, followed by `REAL(KIND=1)', `INTEGER(KIND=1)', and
- `LOGICAL(KIND=1)' entities, then `INTEGER(KIND=6)' entities, and
- finally `CHARACTER' and `INTEGER(KIND=3)' entities.
-
- The reason to use such placement is it makes it more likely that
- your data will be aligned properly, without requiring you to do
- detailed analysis of each aggregate (`COMMON' and `EQUIVALENCE')
- area.
-
- Specifically, on systems where the above guidelines are
- appropriate, placing `CHARACTER' entities before `REAL(KIND=2)'
- entities can work just as well, but only if the number of bytes
- occupied by the `CHARACTER' entities is divisible by the
- recommended alignment for `REAL(KIND=2)'.
-
- By ordering the placement of entities in aggregate areas according
- to the simple guidelines above, you avoid having to carefully
- count the number of bytes occupied by each entity to determine
- whether the actual alignment of each subsequent entity meets the
- alignment guidelines for the type of that entity.
-
- If you don't ensure correct alignment of `COMMON' elements, the
- compiler may be forced by some systems to violate the Fortran
- semantics by adding padding to get `DOUBLE PRECISION' data
- properly aligned. If the unfortunate practice is employed of
- overlaying different types of data in the `COMMON' block, the
- different variants of this block may become misaligned with
- respect to each other. Even if your platform doesn't require
- strict alignment, `COMMON' should be laid out as above for
- portability. (Unfortunately the FORTRAN 77 standard didn't
- anticipate this possible requirement, which is
- compiler-independent on a given platform.)
-
- * Use the (x86-specific) `-malign-double' option when compiling
- programs for the Pentium and Pentium Pro architectures (called 586
- and 686 in the `gcc' configuration subsystem). The warning about
- this in the `gcc' manual isn't generally relevant to Fortran, but
- using it will force `COMMON' to be padded if necessary to align
- `DOUBLE PRECISION' data.
-
- When `DOUBLE PRECISION' data is forcibly aligned in `COMMON' by
- `g77' due to specifying `-malign-double', `g77' issues a warning
- about the need to insert padding.
-
- In this case, each and every program unit that uses the same
- `COMMON' area must specify the same layout of variables and their
- types for that area and be compiled with `-malign-double' as well.
- `g77' will issue warnings in each case, but as long as every
- program unit using that area is compiled with the same warnings,
- the resulting object files should work when linked together unless
- the program makes additional assumptions about `COMMON' area
- layouts that are outside the scope of the FORTRAN 77 standard, or
- uses `EQUIVALENCE' or different layouts in ways that assume no
- padding is ever inserted by the compiler.
-
- * Ensure that `crt0.o' or `crt1.o' on your system guarantees a 64-bit
- aligned stack for `main()'. The recent one from GNU (`glibc2')
- will do this on x86 systems, but we don't know of any other x86
- setups where it will be right. Read your system's documentation
- to determine if it is appropriate to upgrade to a more recent
- version to obtain the optimal alignment.
-
- Progress is being made on making this work "out of the box" on
-future versions of `g77', `gcc', and some of the relevant operating
-systems (such as GNU/Linux).
-
- A package that tests the degree to which a Fortran compiler (such as
-`g77') aligns 64-bit floating-point variables and arrays is available
-at `ftp://alpha.gnu.org/gnu/g77/align/'.
-
-\1f
-File: g77.info, Node: Prefer Automatic Uninitialized Variables, Next: Avoid f2c Compatibility, Prev: Aligned Data, Up: Faster Programs
-
-Prefer Automatic Uninitialized Variables
-----------------------------------------
-
- If you're using `-fno-automatic' already, you probably should change
-your code to allow compilation with `-fautomatic' (the default), to
-allow the program to run faster.
-
- Similarly, you should be able to use `-fno-init-local-zero' (the
-default) instead of `-finit-local-zero'. This is because it is rare
-that every variable affected by these options in a given program
-actually needs to be so affected.
-
- For example, `-fno-automatic', which effectively `SAVE's every local
-non-automatic variable and array, affects even things like `DO'
-iteration variables, which rarely need to be `SAVE'd, and this often
-reduces run-time performances. Similarly, `-fno-init-local-zero'
-forces such variables to be initialized to zero--when `SAVE'd (such as
-when `-fno-automatic'), this by itself generally affects only startup
-time for a program, but when not `SAVE'd, it can slow down the
-procedure every time it is called.
-
- *Note Overly Convenient Command-Line Options: Overly Convenient
-Options, for information on the `-fno-automatic' and
-`-finit-local-zero' options and how to convert their use into selective
-changes in your own code.
-
-\1f
-File: g77.info, Node: Avoid f2c Compatibility, Next: Use Submodel Options, Prev: Prefer Automatic Uninitialized Variables, Up: Faster Programs
-
-Avoid f2c Compatibility
------------------------
-
- If you aren't linking with any code compiled using `f2c', try using
-the `-fno-f2c' option when compiling _all_ the code in your program.
-(Note that `libf2c' is _not_ an example of code that is compiled using
-`f2c'--it is compiled by a C compiler, typically `gcc'.)
-
-\1f
-File: g77.info, Node: Use Submodel Options, Prev: Avoid f2c Compatibility, Up: Faster Programs
-
-Use Submodel Options
---------------------
-
- Using an appropriate `-m' option to generate specific code for your
-CPU may be worthwhile, though it may mean the executable won't run on
-other versions of the CPU that don't support the same instruction set.
-*Note Hardware Models and Configurations: (gcc)Submodel Options. For
-instance on an x86 system the compiler might have been built--as shown
-by `g77 -v'--for the target `i386-pc-linux-gnu', i.e. an `i386' CPU.
-In that case to generate code best optimized for a Pentium you could
-use the option `-march=pentium'.
-
- For recent CPUs that don't have explicit support in the released
-version of `gcc', it _might_ still be possible to get improvements with
-certain `-m' options.
-
- `-fomit-frame-pointer' can help performance on x86 systems and
-others. It will, however, inhibit debugging on the systems on which it
-is not turned on anyway by `-O'.
-
-\1f
-File: g77.info, Node: Trouble, Next: Open Questions, Prev: Collected Fortran Wisdom, Up: Top
-
-Known Causes of Trouble with GNU Fortran
-****************************************
-
- This section describes known problems that affect users of GNU
-Fortran. Most of these are not GNU Fortran bugs per se--if they were,
-we would fix them. But the result for a user might be like the result
-of a bug.
-
- Some of these problems are due to bugs in other software, some are
-missing features that are too much work to add, and some are places
-where people's opinions differ as to what is best.
-
- To find out about major bugs discovered in the current release and
-possible workarounds for them, see `ftp://alpha.gnu.org/g77.plan'.
-
- (Note that some of this portion of the manual is lifted directly
-from the `gcc' manual, with minor modifications to tailor it to users
-of `g77'. Anytime a bug seems to have more to do with the `gcc'
-portion of `g77', see *Note Known Causes of Trouble with GCC:
-(gcc)Trouble.)
-
-* Menu:
-
-* But-bugs:: Bugs really in other programs or elsewhere.
-* Known Bugs:: Bugs known to be in this version of `g77'.
-* Missing Features:: Features we already know we want to add later.
-* Disappointments:: Regrettable things we can't change.
-* Non-bugs:: Things we think are right, but some others disagree.
-* Warnings and Errors:: Which problems in your code get warnings,
- and which get errors.
-
-\1f
-File: g77.info, Node: But-bugs, Next: Known Bugs, Up: Trouble
-
-Bugs Not In GNU Fortran
-=======================
-
- These are bugs to which the maintainers often have to reply, "but
-that isn't a bug in `g77'...". Some of these already are fixed in new
-versions of other software; some still need to be fixed; some are
-problems with how `g77' is installed or is being used; some are the
-result of bad hardware that causes software to misbehave in sometimes
-bizarre ways; some just cannot be addressed at this time until more is
-known about the problem.
-
- Please don't re-report these bugs to the `g77' maintainers--if you
-must remind someone how important it is to you that the problem be
-fixed, talk to the people responsible for the other products identified
-below, but preferably only after you've tried the latest versions of
-those products. The `g77' maintainers have their hands full working on
-just fixing and improving `g77', without serving as a clearinghouse for
-all bugs that happen to affect `g77' users.
-
- *Note Collected Fortran Wisdom::, for information on behavior of
-Fortran programs, and the programs that compile them, that might be
-_thought_ to indicate bugs.
-
-* Menu:
-
-* Signal 11 and Friends:: Strange behavior by any software.
-* Cannot Link Fortran Programs:: Unresolved references.
-* Large Common Blocks:: Problems on older GNU/Linux systems.
-* Debugger Problems:: When the debugger crashes.
-* NeXTStep Problems:: Misbehaving executables.
-* Stack Overflow:: More misbehaving executables.
-* Nothing Happens:: Less behaving executables.
-* Strange Behavior at Run Time:: Executables misbehaving due to
- bugs in your program.
-* Floating-point Errors:: The results look wrong, but....
-
-\1f
-File: g77.info, Node: Signal 11 and Friends, Next: Cannot Link Fortran Programs, Up: But-bugs
-
-Signal 11 and Friends
----------------------
-
- A whole variety of strange behaviors can occur when the software, or
-the way you are using the software, stresses the hardware in a way that
-triggers hardware bugs. This might seem hard to believe, but it
-happens frequently enough that there exist documents explaining in
-detail what the various causes of the problems are, what typical
-symptoms look like, and so on.
-
- Generally these problems are referred to in this document as "signal
-11" crashes, because the Linux kernel, running on the most popular
-hardware (the Intel x86 line), often stresses the hardware more than
-other popular operating systems. When hardware problems do occur under
-GNU/Linux on x86 systems, these often manifest themselves as "signal 11"
-problems, as illustrated by the following diagnostic:
-
- sh# g77 myprog.f
- gcc: Internal compiler error: program f771 got fatal signal 11
- sh#
-
- It is _very_ important to remember that the above message is _not_
-the only one that indicates a hardware problem, nor does it always
-indicate a hardware problem.
-
- In particular, on systems other than those running the Linux kernel,
-the message might appear somewhat or very different, as it will if the
-error manifests itself while running a program other than the `g77'
-compiler. For example, it will appear somewhat different when running
-your program, when running Emacs, and so on.
-
- How to cope with such problems is well beyond the scope of this
-manual.
-
- However, users of Linux-based systems (such as GNU/Linux) should
-review `http://www.bitwizard.nl/sig11/', a source of detailed
-information on diagnosing hardware problems, by recognizing their
-common symptoms.
-
- Users of other operating systems and hardware might find this
-reference useful as well. If you know of similar material for another
-hardware/software combination, please let us know so we can consider
-including a reference to it in future versions of this manual.
-
-\1f
-File: g77.info, Node: Cannot Link Fortran Programs, Next: Large Common Blocks, Prev: Signal 11 and Friends, Up: But-bugs
-
-Cannot Link Fortran Programs
-----------------------------
-
- On some systems, perhaps just those with out-of-date (shared?)
-libraries, unresolved-reference errors happen when linking
-`g77'-compiled programs (which should be done using `g77').
-
- If this happens to you, try appending `-lc' to the command you use
-to link the program, e.g. `g77 foo.f -lc'. `g77' already specifies
-`-lg2c -lm' when it calls the linker, but it cannot also specify `-lc'
-because not all systems have a file named `libc.a'.
-
- It is unclear at this point whether there are legitimately installed
-systems where `-lg2c -lm' is insufficient to resolve code produced by
-`g77'.
-
- If your program doesn't link due to unresolved references to names
-like `_main', make sure you're using the `g77' command to do the link,
-since this command ensures that the necessary libraries are loaded by
-specifying `-lg2c -lm' when it invokes the `gcc' command to do the
-actual link. (Use the `-v' option to discover more about what actually
-happens when you use the `g77' and `gcc' commands.)
-
- Also, try specifying `-lc' as the last item on the `g77' command
-line, in case that helps.
-
-\1f
-File: g77.info, Node: Large Common Blocks, Next: Debugger Problems, Prev: Cannot Link Fortran Programs, Up: But-bugs
-
-Large Common Blocks
--------------------
-
- On some older GNU/Linux systems, programs with common blocks larger
-than 16MB cannot be linked without some kind of error message being
-produced.
-
- This is a bug in older versions of `ld', fixed in more recent
-versions of `binutils', such as version 2.6.
-
-\1f
-File: g77.info, Node: Debugger Problems, Next: NeXTStep Problems, Prev: Large Common Blocks, Up: But-bugs
-
-Debugger Problems
------------------
-
- There are some known problems when using `gdb' on code compiled by
-`g77'. Inadequate investigation as of the release of 0.5.16 results in
-not knowing which products are the culprit, but `gdb-4.14' definitely
-crashes when, for example, an attempt is made to print the contents of
-a `COMPLEX(KIND=2)' dummy array, on at least some GNU/Linux machines,
-plus some others. Attempts to access assumed-size arrays are also
-known to crash recent versions of `gdb'. (`gdb''s Fortran support was
-done for a different compiler and isn't properly compatible with `g77'.)
-
-\1f
-File: g77.info, Node: NeXTStep Problems, Next: Stack Overflow, Prev: Debugger Problems, Up: But-bugs
-
-NeXTStep Problems
------------------
-
- Developers of Fortran code on NeXTStep (all architectures) have to
-watch out for the following problem when writing programs with large,
-statically allocated (i.e. non-stack based) data structures (common
-blocks, saved arrays).
-
- Due to the way the native loader (`/bin/ld') lays out data
-structures in virtual memory, it is very easy to create an executable
-wherein the `__DATA' segment overlaps (has addresses in common) with
-the `UNIX STACK' segment.
-
- This leads to all sorts of trouble, from the executable simply not
-executing, to bus errors. The NeXTStep command line tool `ebadexec'
-points to the problem as follows:
-
- % /bin/ebadexec a.out
- /bin/ebadexec: __LINKEDIT segment (truncated address = 0x3de000
- rounded size = 0x2a000) of executable file: a.out overlaps with UNIX
- STACK segment (truncated address = 0x400000 rounded size =
- 0x3c00000) of executable file: a.out
-
- (In the above case, it is the `__LINKEDIT' segment that overlaps the
-stack segment.)
-
- This can be cured by assigning the `__DATA' segment (virtual)
-addresses beyond the stack segment. A conservative estimate for this
-is from address 6000000 (hexadecimal) onwards--this has always worked
-for me [Toon Moene]:
-
- % g77 -segaddr __DATA 6000000 test.f
- % ebadexec a.out
- ebadexec: file: a.out appears to be executable
- %
-
- Browsing through `gcc/gcc/f/Makefile.in', you will find that the
-`f771' program itself also has to be linked with these flags--it has
-large statically allocated data structures. (Version 0.5.18 reduces
-this somewhat, but probably not enough.)
-
- (The above item was contributed by Toon Moene
-(<toon@moene.indiv.nluug.nl>).)
-
-\1f
-File: g77.info, Node: Stack Overflow, Next: Nothing Happens, Prev: NeXTStep Problems, Up: But-bugs
-
-Stack Overflow
---------------
-
- `g77' code might fail at runtime (probably with a "segmentation
-violation") due to overflowing the stack. This happens most often on
-systems with an environment that provides substantially more heap space
-(for use when arbitrarily allocating and freeing memory) than stack
-space.
-
- Often this can be cured by increasing or removing your shell's limit
-on stack usage, typically using `limit stacksize' (in `csh' and
-derivatives) or `ulimit -s' (in `sh' and derivatives).
-
- Increasing the allowed stack size might, however, require changing
-some operating system or system configuration parameters.
-
- You might be able to work around the problem by compiling with the
-`-fno-automatic' option to reduce stack usage, probably at the expense
-of speed.
-
- `g77', on most machines, puts many variables and arrays on the stack
-where possible, and can be configured (by changing
-`FFECOM_sizeMAXSTACKITEM' in `gcc/gcc/f/com.c') to force smaller-sized
-entities into static storage (saving on stack space) or permit
-larger-sized entities to be put on the stack (which can improve
-run-time performance, as it presents more opportunities for the GBE to
-optimize the generated code).
-
- _Note:_ Putting more variables and arrays on the stack might cause
-problems due to system-dependent limits on stack size. Also, the value
-of `FFECOM_sizeMAXSTACKITEM' has no effect on automatic variables and
-arrays. *Note But-bugs::, for more information. _Note:_ While
-`libg2c' places a limit on the range of Fortran file-unit numbers, the
-underlying library and operating system might impose different kinds of
-limits. For example, some systems limit the number of files
-simultaneously open by a running program. Information on how to
-increase these limits should be found in your system's documentation.
-
- However, if your program uses large automatic arrays (for example,
-has declarations like `REAL A(N)' where `A' is a local array and `N' is
-a dummy or `COMMON' variable that can have a large value), neither use
-of `-fno-automatic', nor changing the cut-off point for `g77' for using
-the stack, will solve the problem by changing the placement of these
-large arrays, as they are _necessarily_ automatic.
-
- `g77' currently provides no means to specify that automatic arrays
-are to be allocated on the heap instead of the stack. So, other than
-increasing the stack size, your best bet is to change your source code
-to avoid large automatic arrays. Methods for doing this currently are
-outside the scope of this document.
-
- (_Note:_ If your system puts stack and heap space in the same memory
-area, such that they are effectively combined, then a stack overflow
-probably indicates a program that is either simply too large for the
-system, or buggy.)
-
-\1f
-File: g77.info, Node: Nothing Happens, Next: Strange Behavior at Run Time, Prev: Stack Overflow, Up: But-bugs
-
-Nothing Happens
----------------
-
- It is occasionally reported that a "simple" program, such as a
-"Hello, World!" program, does nothing when it is run, even though the
-compiler reported no errors, despite the program containing nothing
-other than a simple `PRINT' statement.
-
- This most often happens because the program has been compiled and
-linked on a UNIX system and named `test', though other names can lead
-to similarly unexpected run-time behavior on various systems.
-
- Essentially this problem boils down to giving your program a name
-that is already known to the shell you are using to identify some other
-program, which the shell continues to execute instead of your program
-when you invoke it via, for example:
-
- sh# test
- sh#
-
- Under UNIX and many other system, a simple command name invokes a
-searching mechanism that might well not choose the program located in
-the current working directory if there is another alternative (such as
-the `test' command commonly installed on UNIX systems).
-
- The reliable way to invoke a program you just linked in the current
-directory under UNIX is to specify it using an explicit pathname, as in:
-
- sh# ./test
- Hello, World!
- sh#
-
- Users who encounter this problem should take the time to read up on
-how their shell searches for commands, how to set their search path,
-and so on. The relevant UNIX commands to learn about include `man',
-`info' (on GNU systems), `setenv' (or `set' and `env'), `which', and
-`find'.
-
-\1f
-File: g77.info, Node: Strange Behavior at Run Time, Next: Floating-point Errors, Prev: Nothing Happens, Up: But-bugs
-
-Strange Behavior at Run Time
-----------------------------
-
- `g77' code might fail at runtime with "segmentation violation", "bus
-error", or even something as subtle as a procedure call overwriting a
-variable or array element that it is not supposed to touch.
-
- These can be symptoms of a wide variety of actual bugs that occurred
-earlier during the program's run, but manifested themselves as
-_visible_ problems some time later.
-
- Overflowing the bounds of an array--usually by writing beyond the
-end of it--is one of two kinds of bug that often occurs in Fortran code.
-(Compile your code with the `-fbounds-check' option to catch many of
-these kinds of errors at program run time.)
-
- The other kind of bug is a mismatch between the actual arguments
-passed to a procedure and the dummy arguments as declared by that
-procedure.
-
- Both of these kinds of bugs, and some others as well, can be
-difficult to track down, because the bug can change its behavior, or
-even appear to not occur, when using a debugger.
-
- That is, these bugs can be quite sensitive to data, including data
-representing the placement of other data in memory (that is, pointers,
-such as the placement of stack frames in memory).
-
- `g77' now offers the ability to catch and report some of these
-problems at compile, link, or run time, such as by generating code to
-detect references to beyond the bounds of most arrays (except
-assumed-size arrays), and checking for agreement between calling and
-called procedures. Future improvements are likely to be made in the
-procedure-mismatch area, at least.
-
- In the meantime, finding and fixing the programming bugs that lead
-to these behaviors is, ultimately, the user's responsibility, as
-difficult as that task can sometimes be.
-
- One runtime problem that has been observed might have a simple
-solution. If a formatted `WRITE' produces an endless stream of spaces,
-check that your program is linked against the correct version of the C
-library. The configuration process takes care to account for your
-system's normal `libc' not being ANSI-standard, which will otherwise
-cause this behaviour. If your system's default library is
-ANSI-standard and you subsequently link against a non-ANSI one, there
-might be problems such as this one.
-
- Specifically, on Solaris2 systems, avoid picking up the `BSD'
-library from `/usr/ucblib'.
-
-\1f
-File: g77.info, Node: Floating-point Errors, Prev: Strange Behavior at Run Time, Up: But-bugs
-
-Floating-point Errors
----------------------
-
- Some programs appear to produce inconsistent floating-point results
-compiled by `g77' versus by other compilers.
-
- Often the reason for this behavior is the fact that floating-point
-values are represented on almost all Fortran systems by
-_approximations_, and these approximations are inexact even for
-apparently simple values like 0.1, 0.2, 0.3, 0.4, 0.6, 0.7, 0.8, 0.9,
-1.1, and so on. Most Fortran systems, including all current ports of
-`g77', use binary arithmetic to represent these approximations.
-
- Therefore, the exact value of any floating-point approximation as
-manipulated by `g77'-compiled code is representable by adding some
-combination of the values 1.0, 0.5, 0.25, 0.125, and so on (just keep
-dividing by two) through the precision of the fraction (typically
-around 23 bits for `REAL(KIND=1)', 52 for `REAL(KIND=2)'), then
-multiplying the sum by a integral power of two (in Fortran, by `2**N')
-that typically is between -127 and +128 for `REAL(KIND=1)' and -1023
-and +1024 for `REAL(KIND=2)', then multiplying by -1 if the number is
-negative.
-
- So, a value like 0.2 is exactly represented in decimal--since it is
-a fraction, `2/10', with a denominator that is compatible with the base
-of the number system (base 10). However, `2/10' cannot be represented
-by any finite number of sums of any of 1.0, 0.5, 0.25, and so on, so
-0.2 cannot be exactly represented in binary notation.
-
- (On the other hand, decimal notation can represent any binary number
-in a finite number of digits. Decimal notation cannot do so with
-ternary, or base-3, notation, which would represent floating-point
-numbers as sums of any of `1/1', `1/3', `1/9', and so on. After all,
-no finite number of decimal digits can exactly represent `1/3'.
-Fortunately, few systems use ternary notation.)
-
- Moreover, differences in the way run-time I/O libraries convert
-between these approximations and the decimal representation often used
-by programmers and the programs they write can result in apparent
-differences between results that do not actually exist, or exist to
-such a small degree that they usually are not worth worrying about.
-
- For example, consider the following program:
-
- PRINT *, 0.2
- END
-
- When compiled by `g77', the above program might output `0.20000003',
-while another compiler might produce a executable that outputs `0.2'.
-
- This particular difference is due to the fact that, currently,
-conversion of floating-point values by the `libg2c' library, used by
-`g77', handles only double-precision values.
-
- Since `0.2' in the program is a single-precision value, it is
-converted to double precision (still in binary notation) before being
-converted back to decimal. The conversion to binary appends _binary_
-zero digits to the original value--which, again, is an inexact
-approximation of 0.2--resulting in an approximation that is much less
-exact than is connoted by the use of double precision.
-
- (The appending of binary zero digits has essentially the same effect
-as taking a particular decimal approximation of `1/3', such as
-`0.3333333', and appending decimal zeros to it, producing
-`0.33333330000000000'. Treating the resulting decimal approximation as
-if it really had 18 or so digits of valid precision would make it seem
-a very poor approximation of `1/3'.)
-
- As a result of converting the single-precision approximation to
-double precision by appending binary zeros, the conversion of the
-resulting double-precision value to decimal produces what looks like an
-incorrect result, when in fact the result is _inexact_, and is probably
-no less inaccurate or imprecise an approximation of 0.2 than is
-produced by other compilers that happen to output the converted value
-as "exactly" `0.2'. (Some compilers behave in a way that can make them
-appear to retain more accuracy across a conversion of a single-precision
-constant to double precision. *Note Context-Sensitive Constants::, to
-see why this practice is illusory and even dangerous.)
-
- Note that a more exact approximation of the constant is computed
-when the program is changed to specify a double-precision constant:
-
- PRINT *, 0.2D0
- END
-
- Future versions of `g77' and/or `libg2c' might convert
-single-precision values directly to decimal, instead of converting them
-to double precision first. This would tend to result in output that is
-more consistent with that produced by some other Fortran
-implementations.
-
- A useful source of information on floating-point computation is David
-Goldberg, `What Every Computer Scientist Should Know About
-Floating-Point Arithmetic', Computing Surveys, 23, March 1991, pp.
-5-48. An online version is available at `http://docs.sun.com/', and
-there is a supplemented version, in PostScript form, at
-`http://www.validgh.com/goldberg/paper.ps'.
-
- Information related to the IEEE 754 floating-point standard by a
-leading light can be found at
-`http://http.cs.berkeley.edu/%7Ewkahan/ieee754status/'; see also slides
-from the short course referenced from
-`http://http.cs.berkeley.edu/%7Efateman/'.
-`http://www.linuxsupportline.com/%7Ebillm/' has a brief guide to IEEE
-754, a somewhat x86-GNU/Linux-specific FAQ, and library code for
-GNU/Linux x86 systems.
-
- The supplement to the PostScript-formatted Goldberg document,
-referenced above, is available in HTML format. See `Differences Among
-IEEE 754 Implementations' by Doug Priest, available online at
-`http://www.validgh.com/goldberg/addendum.html'. This document
-explores some of the issues surrounding computing of extended (80-bit)
-results on processors such as the x86, especially when those results
-are arbitrarily truncated to 32-bit or 64-bit values by the compiler as
-"spills".
-
- (_Note:_ `g77' specifically, and `gcc' generally, does arbitrarily
-truncate 80-bit results during spills as of this writing. It is not
-yet clear whether a future version of the GNU compiler suite will offer
-80-bit spills as an option, or perhaps even as the default behavior.)
-
- The GNU C library provides routines for controlling the FPU, and
-other documentation about this.
-
- *Note Floating-point precision::, regarding IEEE 754 conformance.
-
projects / msp430-gcc.git / blobdiff