some g77 doc'toring

Dave Love
Sun Sep 13 10:25:00 GMT 1998

These additions (mainly) could use review.  Some of them (the
optimization attempted explanations and FP stuff) aren't actually
Fortran-specific and my understanding may need correction.  They do
address some fairly FAQs.  The global Hollerith <- hollerith is
consistent with the standard's usage.

There's a general problem with overfull hboxes in the TeX version,
which I haven't addressed.  I'll suggest a new feature for the next
Texinfo which may help somewhat, but probably not enough.

Index: g77.texi
RCS file: /egcs/carton/cvsfiles/egcs/gcc/f/g77.texi,v
retrieving revision 1.18
diff -u -p -u -r1.18 g77.texi
--- g77.texi	1998/09/01 09:13:21	1.18
+++ g77.texi	1998/09/13 17:13:01
@@ -647,7 +647,7 @@ Jonathan Corbet
 Dr.@: Mark Fernyhough
-Takafumi Hayashi (The University of AIzu)---@email{}
+Takafumi Hayashi (The University of Aizu)---@email{}
 Kate Hedstrom
@@ -2638,9 +2638,29 @@ is @samp{-mno-align-double}, not @samp{-
 @item -ffloat-store
 @cindex IEEE conformance
 @cindex conformance, IEEE
-Might help a Fortran program that depends on exact IEEE conformance
-on some machines, but might slow down a program that doesn't.
+@cindex floating point precision
+Might help a Fortran program that depends on exact IEEE conformance on
+some machines, but might slow down a program that doesn't.
+This option is effective when the floating point unit is set to work in
+IEEE 854 `extended precision'---as it typically is on x86 and m68k GNU
+systems---rather than IEEE 754 double precision.  @code{-ffloat-store}
+tries to remove the extra precision by spilling data from floating point
+registers into memory and this typically involves a big performance
+hit.  However, it doesn't affect intermediate results, so that it is
+only partially effective.  `Excess precision' is avoided in code like:
+      a = b + c
+      d = a * e
+@end smallexample
+but not in code like:
+      d = (b + c) * e
+@end smallexample
+@xref{Floating point precision} for another, potentially better way of
+controlling the precision.
 @cindex -fforce-mem option
 @cindex options, -fforce-mem
 @item -fforce-mem
@@ -2704,13 +2724,29 @@ Might improve performance on some code.
 @item -funroll-loops
 @cindex loops, unrolling
 @cindex unrolling loops
-Definitely improves performance on some code.
+@cindex loop optimization
+Typically improves performance on code using indexed @code{DO} loops by
+unrolling them and is probably generally appropriate for Fortran, though
+it is not turned on at any optimization level.  
+Note that outer loop unrolling isn't done specifically; decisions about
+whether to unroll a loop are made on the basis of its instruction count.  
+@c DL: Fixme: This should obviously go somewhere else...
+Also, no loop discovery is done, so only loops written with @code{DO}
+benefit from loop optimizations, including---but not limited
+to---unrolling.  Loops written with @code{IF} and @code{GOTO} will not
+be recognized as such.  This option only unrolls indexed @code{DO}
+loops, not @code{DO WHILE} loops.
 @cindex -funroll-all-loops option
 @cindex options, -funroll-all-loops
+@cindex @code{DO WHILE}
 @item -funroll-all-loops
-@c DL: Is this really true?  What _are_ the semantics of this option?
-Improves performance on some code.
+@c DL: Check my understanding of -funroll-all-loops v. -funroll-loops is correct.
+Probably improves performance on code using @code{DO WHILE} loops by
+unrolling them in addition to indexed @code{DO} loops.  In the absence
+of @code{DO WHILE}, this option is equivalent to @code{-funroll-loops}
+but possibly slower.
 @item -fno-move-all-movables
 @cindex -fno-move-all-movables option
@@ -4137,6 +4173,8 @@ Extensions to the ANSI FORTRAN 77 standa
 * Control Statements::
 * Functions and Subroutines::
 * Scope and Classes of Names::
+* I/O::
+* Fortran 90 Features::
 @end menu
 @node Direction of Language Development
@@ -4593,7 +4631,7 @@ Otherwise, it is treated as an indicator
-The exclamation point appears outside a character or hollerith
+The exclamation point appears outside a character or Hollerith
 Otherwise, the exclamation point is considered part of the
@@ -4612,7 +4650,7 @@ is permitted under the following conditi
 @itemize @bullet
-The semicolon appears outside a character or hollerith
+The semicolon appears outside a character or Hollerith
 Otherwise, the semicolon is considered part of the
@@ -4671,6 +4709,7 @@ for the relevant aspects of GNU Fortran.
 * Statement Labels::
 * Order::
+* Cpp-style directives::
 @end menu
 @node Character Set
@@ -4683,7 +4722,7 @@ Letters include uppercase letters (the t
 of the English alphabet) and lowercase letters (their lowercase
 Generally, lowercase letters may be used in place of uppercase
-letters, though in character and hollerith constants, they
+letters, though in character and Hollerith constants, they
 are distinct.
 Special characters include:
@@ -5010,6 +5049,18 @@ An @code{INCLUDE} directive may be conti
 lines as if it were a statement.
 This permits long names to be used for @var{filename}.
+@node Cpp-style directives
+@subsection Cpp-style directives
+@cindex #
+@cindex preprocessor
+@code{cpp} output-style @code{#} directives @xref{C Preprocessor
+Output,,, cpp, The C Preprocessor}, are recognized by the compiler even
+when the preprocessor isn't run on the input (as it is when compiling
+@samp{.F} files).  (Note the distinction between these @code{cpp}
+@code{#} @emph{output} directives and @code{#line} @emph{input}
 @node Data Types and Constants
 @section Data Types and Constants
@@ -5561,6 +5612,7 @@ is 11, and so on.)
 (Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.)
+@cindex double quoted character constants
 A character constant may be delimited by a pair of double quotes
 (@samp{"}) instead of apostrophes.
 In this case, an apostrophe within the constant represents
@@ -5684,6 +5736,27 @@ The @code{NAMELIST} statement, and relat
 supported by the GNU Fortran language in essentially the same
 way as they are by @code{f2c}.
+This follows Fortran 90 with the restriction that on @code{NAMELIST}
+input, subscripts must have the form
+@var{subscript} [ @code{:} @var{subscript} [ @code{:} @var{stride}]]
+@end smallexample
+&xx x(1:3,8:10:2)=1,2,3,4,5,6/
+@end smallexample
+is allowed, but not, say,
+&xx x(:3,8::2)=1,2,3,4,5,6/
+@end smallexample
+As an extension of the Fortran 90 form, @code{$} and @code{$END} may be
+used in place of @code{&} and @code{/} in @code{NAMELIST} input, so that
+$&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end
+@end smallexample
+could be used instead of the example above.
 @subsection @code{DOUBLE COMPLEX} Statement
@@ -5710,10 +5783,13 @@ for the relevant aspects of GNU Fortran.
 @node DO WHILE
 @subsection DO WHILE
 @cindex DO WHILE
+@cindex DO
 @cindex MIL-STD 1753
 The @code{DO WHILE} statement, a feature of both the MIL-STD 1753 and
 Fortran 90 standards, is provided by the GNU Fortran language.
+The Fortran 90 ``do forever'' statement comprising just @code{DO} is
+also supported.
 @node END DO
 @subsection END DO
@@ -6501,6 +6577,113 @@ for the relevant aspects of GNU Fortran.
 Underscores (@samp{_}) are accepted in symbol names after the first
 character (which must be a letter).
+@node I/O
+@section I/O
+@cindex dollar sign
+A dollar at the end of an output format specification suppresses the
+newline at the end of the output.
+@cindex <> edit descriptor
+@cindex edit descriptor, <>
+Edit descriptors in @code{FORMAT} statements may contain compile-time
+@code{INTEGER} constant expressions in angle brackets, such as
+10    FORMAT (I<WIDTH>)
+@end smallexample
+The @code{OPEN} specifier @code{NAME=} is equivalent to @code{FILE=}.
+These Fortran 90 features are supported: 
+@itemize @bullet
+@cindex Z edit descriptor
+@cindex edit descriptor, Z
+The @code{Z} edit descriptor is supported.
+The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if
+@code{STATUS='SCRATCH'} is supplied and the @code{STATUS='REPLACE'}
+specifier is supported.
+@end itemize
+@node Fortran 90 Features
+@section Fortran 90 Features
+@cindex Fortran 90
+For convenience this section collects a list (probably incomplete) of
+the Fortran 90 features supported by the GNU Fortran language, even if
+they are documented elsewhere.
+@c makeinfo 1.68 objects to the nested parens
+@xref{Characters Lines Sequence,,{Characters, Lines, and Execution Sequence}},
+@end ifnotinfo
+@xref{Characters Lines Sequence},
+@end ifinfo
+for information on additional fixed source form lexical issues.  In
+addition, the free source form is supported through the
+@cindex @samp{-ffree-form}
+@samp{-ffree-form} option.  @xref{Fortran 90} for other Fortran 90
+features be turned on by the
+@cindex @samp{-ff90}
+@samp{-ff90} option.  @xref{Table of Intrinsic Functions} for
+information on the Fortran 90 intrinsics available.
+@table @asis
+@item Automatic arrays in procedures
+@item Character assignments
+@cindex character assignments
+In character assignments, the variable being assigned may occur on the
+right hand side of the assignment.
+@item Character strings
+@cindex double quoted character constants
+Strings may have zero length and substrings of character constants are
+permitted.  Character constants may be enclosed in double quotes
+(@code{"}) as well as single quotes.  @xref{Character Type}.
+@item Construct names
+(Symbolic tags on blocks.)  @xref{Construct Names }.
+@item @code{CYCLE} and @code{EXIT}
+@xref{CYCLE and EXIT,,The @code{CYCLE} and @code{EXIT} Statements}.
+@item @code{DOUBLE COMPLEX}
+@xref{DOUBLE COMPLEX,,@code{DOUBLE COMPLEX} Statement
+@item @code{DO WHILE}
+@xref{DO WHILE}.
+@item @code{END} decoration
+@item @code{END DO}
+@xref{END DO}.
+@item @code{KIND}
+@item @code{IMPLICIT NONE}
+@item @code{INCLUDE} statements
+@item List directed and namelist i/o on internal files
+@item Binary, octal and hexadecimal constants
+These are supported more generally than required by Fortran 90.
+@xref{Integer Type}.
+@item @code{NAMELIST}
+@item @code{OPEN} specifiers
+@code{STATUS='REPLACE'} is supported.
+@item Relational operators
+The operators @code{<}, @code{<=}, @code{==}, @code{/=}, @code{>} and
+@code{>=} may be used instead of @code{.LT.}, @code{.LE.}, @code{.EQ.},
+@code{.NE.}, @code{.GT.} and @code{.GE.} repectively.
+@item @code{SELECT CASE}
+Not fully implemented.  @xref{SELECT CASE on CHARACTER Type,,
+@code{SELECT CASE} on @code{CHARACTER} Type}.
+@item Specification statements
+A limited subset of the Fortran 90 syntax and semantics for variable
+declarations is supported, including @code{KIND}.  @xref{Kind Notation}.
+@code{KIND} is of limited usefulness in the absence of the
+@code{KIND}-related intrinsics.  An example is:
+      INTEGER (KIND=1) :: FOO=1, BAR=2
+@end smallexample
+@code{PARAMETER} and @code{DIMENSION} attributes aren't supported.
+@end table
 @node Other Dialects
 @chapter Other Dialects
@@ -8341,7 +8524,7 @@ prototype information.
 @code{#include} this in the C which has to call
 the Fortran routines to make sure you get it right.
-@xref{Arrays,,Arrays (DIMENSION}, for information on the differences
+@xref{Arrays,,Arrays (DIMENSION)}, for information on the differences
 between the way Fortran (including compilers like @code{g77}) and
 C handle arrays.
@@ -9813,7 +9996,7 @@ The meaning of a @code{DO} loop in Fortr
 in the Fortran standard@dots{}and is quite different from what
 many programmers might expect.
-In particular, Fortran @code{DO} loops are implemented as if
+In particular, Fortran indexed @code{DO} loops are implemented as if
 the number of trips through the loop is calculated @emph{before}
 the loop is entered.
@@ -9997,6 +10180,8 @@ tracking down bugs in such programs.
 * Aliasing Assumed To Work::
 * Output Assumed To Flush::
 * Large File Unit Numbers::
+* Floating point precision::
+* Inconsistent Calling Sequences::
 @end menu
 @node Not My Type
@@ -10414,6 +10599,62 @@ open by a running program.
 Information on how to increase these limits should be found
 in your system's documentation.
+@node Floating point precision
+@subsection Floating point precision
+@cindex IEEE 754
+@cindex IEEE conformance
+@cindex conformance, IEEE
+@cindex 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 @code{-ffloat-store} option or to reset the precision flag on the
+floating point unit @xref{Optimize Options}.
+However, it might be better simply to put the FPU into double precision
+mode and not take the performance hit of @code{-ffloat-store}.  On x86
+and m68k GNU systems you can do this with a similar technique to that
+for turning on floating point exceptions @xref{Floating-point Exception
+Handling}.  The control word could be set to double precision by
+replacing the @code{__setfpucw} call with one like this:
+  __setfpucw ((_FPU_DEFAULT & ~_FPU_EXTENDED) | _FPU_DOUBLE);
+@end smallexample
+(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 @xref{Submodel Options,,Hardware Models and
+Configurations,gcc,Using and Porting GNU CC}.
+@node Inconsistent Calling Sequences
+@subsection Inconsistent Calling Sequences
+@pindex ftnchek
+@cindex floating point errors
+@cindex x86 FPU stack
+Code containing inconsistent calling sequences in the same file is
+normally rejected @xref{GLOBALS}.  (Use, say, @code{ftnchek} to ensure
+consistency across source files 
+@c makeinfo 1.68 objects to the nested parens
+@xref{f2c Skeletons and Prototypes}.)
+@end ifinfo
+@xref{f2c Skeletons and Prototypes,,
+{Generating Skeletons and Prototypes with @code{f2c}}}.)
+@end ifnotinfo
+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 @code{REAL} or @code{DOUBLE PRECISION}
+@code{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
 @node Overly Convenient Options
 @section Overly Convenient Command-line Options
 @cindex overly convenient options
@@ -11251,6 +11492,25 @@ instead of converting them to double pre
 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.  At the time of writing this is available online under
+@uref{} and there is a supplemented version at
+@uref{} .  Information related to the IEEE 754
+floating point standard by a leading light can be found at
+@uref{ }; see also
+slides from the short course referenced from
+@uref{} .
+@uref{} has a brief
+guide to IEEE 754, a somewhat x86 GNU/Linux-specific FAQ and library
+code for GNU/Linux x86 systems.
+@c xref would be different between editions:
+The GNU C library provides routines for controlling the FPU, and other
+documentation about this.
+@xref{Floating point precision}, regarding IEEE 754 conformance.
 @include bugs.texi
 @node Missing Features
@@ -11312,6 +11572,7 @@ Better diagnostics:
 Run-time facilities:
 * Uninitialized Variables at Run Time::
 * Bounds Checking at Run Time::
+* Portable Unformatted Files::
 * Labels Visible to Debugger::
@@ -11653,6 +11914,7 @@ code to specify explicit assembler code.
 @subsection Q Edit Descriptor
 @cindex FORMAT statement
 @cindex Q edit descriptor
+@cindex edit descriptor, Q
 The @code{Q} edit descriptor in @code{FORMAT}s isn't supported.
 (This is meant to get the number of characters remaining in an input record.)
@@ -11730,6 +11992,25 @@ the @code{OPEN}, @code{CLOSE}, and @code
 These extensions are easy to add to @code{g77} itself, but
 require much more work on @code{libg2c}.
+@cindex FORM='PRINT'
+@cindex ANS carriage control
+@cindex carraige control
+@pindex asa
+@pindex fpr
+@code{g77} doesn't support @code{FORM='PRINT'} or an equivalent to
+translate the traditional `carraige control' characters in column 1 of
+output to use backspaces, carriage returns and the like.  However
+programs exist to translate them in output files (or standard output).
+These are typically called either @code{fpr} or @code{asa}.  You can get
+a version of @code{asa} from
+@uref{} for GNU
+systems which will probably build easily on other systems.
+Alternatively, @code{fpr} is in BSD distributions in various archive
+I think both programs can either be used in a pipeline or with files.
 @node ENCODE and DECODE
 @subsection @code{ENCODE} and @code{DECODE}
 @cindex ENCODE statement
@@ -11865,11 +12146,13 @@ END
 @cindex NaN values
 The @code{gcc} backend and, consequently, @code{g77}, currently provides no
-control over whether or not floating-point exceptions are trapped or
+general control over whether or not floating-point exceptions are trapped or
 (Ignoring them typically results in NaN values being
 propagated in systems that conform to IEEE 754.)
-The behaviour is inherited from the system-dependent startup code.
+The behaviour is normally inherited from the system-dependent startup
+code, though some targets, such as the Alpha, have code generation
+options which change the behaviour.
 Most systems provide some C-callable mechanism to change this; this can
 be invoked at startup using @code{gcc}'s @code{constructor} attribute.
@@ -11879,13 +12162,21 @@ on an x86-based GNU system:
 #include <fpu_control.h>
-void __attribute__ ((constructor))
-trapfpe () @{
-  (void) __setfpucw (_FPU_DEFAULT &
-                     ~(_FPU_MASK_IM | _FPU_MASK_ZM | _FPU_MASK_OM));
+static void __attribute__ ((constructor))
+trapfpe ()
+  __setfpucw (_FPU_DEFAULT &
+              ~(_FPU_MASK_IM | _FPU_MASK_ZM | _FPU_MASK_OM));
 @end smallexample
+A convenient trick is to compile this something like:
+gcc -o libtrapfpe.a trapfpe.c
+@end smallexample
+and then use it by adding @code{-trapfpe} to the @code{g77} command line
+when linking.
 @node Nonportable Conversions
 @subsection Nonportable Conversions
 @cindex nonportable conversions
@@ -12099,6 +12390,76 @@ in a fashion similar to @code{f2c}.
 Note that @code{g77} already warns about references to out-of-bounds
 elements of arrays when it detects these at compile time.
+@node Portable Unformatted Files
+@subsection Portable Unformatted Files
+@cindex unformatted files
+@cindex file formats
+@cindex binary data
+@cindex byte ordering
+@code{g77} has no facility for exchanging unformatted files with systems
+using different number formats---even differing only in endianness (byte
+order)---or written by other compilers.  Some compilers provide
+facilities at least for doing byte-swapping during unformatted i/o.
+It is unrealistic to expect to cope with exchanging unformatted files
+with arbitrary other compiler runtimes, but the @code{g77} runtime
+should at least be able to read files written by @code{g77} on systems
+with different number formats, particularly if they differ only in byte
+In case you do need to write a program to translate to or from
+@code{g77} (@code{libf2c}) unformatted files, they are written as
+@table @asis
+@item Sequential
+Unformatted sequential records consist of
+A number giving the length of the record contents;
+the length of record contents again (for backspace).
+@end enumerate
+The record length is of C type
+@code{long}; this means that it is 8 bytes on 64-bit systems such as
+Alpha GNU/Linux and 4 bytes on other systems, such as x86 GNU/Linux.
+Consequently such files cannot be exchanged between 64-bit and 32-bit
+systems, even with the same basic number format.
+@item Direct access
+Unformatted direct access files form a byte stream of length
+@var{records}*@var{recl} bytes, where @var{records} is the maximum
+record number (@code{REC=@var{records}}) written and @var{recl} is the
+record length in bytes specified in the @code{OPEN} statement
+(@code{RECL=@var{recl}}).  Data appear in the records as determined by
+the relevant @code{WRITE} statement.  Dummy records with arbitrary
+contents appear in the file in place of records which haven't been
+@end table
+Thus for exchanging a sequential or direct access unformatted file
+between big- and little-endian 32-bit systems using IEEE 754 floating
+point it would be sufficient to reverse the bytes in consecutive words
+in the file @emph{iff} only @code{REAL*4}, @code{COMPLEX},
+@code{INTEGER*4} and/or @code{LOGICAL*4} data have been written to it by
+If necessary, it is possible to do byte-oriented i/o with @code{g77}'s
+@code{FGETC} and @code{FPUTC} intrinsics.  Byte-swapping can be done in
+Fortran by equivalencing larger sized variables to an @code{INTEGER*1}
+array or a set of scalars.
+@cindex HDF
+@cindex PDB
+If you need to exchange binary data between arbitrary system and
+compiler variations, we recommend using a portable binary format with
+Fortran bindings, such as NCSA's HDF (@uref{} )
+or PACT's PDB@footnote{No, not @emph{that} one.}
+(@uref{} ).  (Unlike,
+say, CDF or XDR, HDF-like systems write in the native number formats and
+only incur overhead when they are read on a system with a different
+format.)  A future @code{g77} runtime library should use such
 @node Labels Visible to Debugger
 @subsection Labels Visible to Debugger
@@ -13499,6 +13860,8 @@ are passed via this mechanism.
 If you want to contribute to @code{g77} by doing research,
 design, specification, documentation, coding, or testing,
 the following information should give you some ideas.
+More relevant information might be available from
+@uref{} .
 * Efficiency::               Make @code{g77} itself compile code faster.
@@ -14377,7 +14740,7 @@ Consecutive keywords must be separated b
 @samp{REALX,Y} is not valid, while @samp{REAL X,Y} is.
 There are no comment lines per se, but @samp{!} starts a
 comment anywhere in a line (other than within a character or
-hollerith constant).
+Hollerith constant).
 @xref{Source Form}, for more information.
@@ -14453,7 +14816,7 @@ someone examining the source file itself
 Examples of errors resulting from preprocessor macro expansion
 include exceeding the line-length limit, improperly starting,
 terminating, or incorporating the apostrophe or double-quote in
-a character constant, improperly forming a hollerith constant,
+a character constant, improperly forming a Hollerith constant,
 and so on.
 @xref{Overall Options,,Options Controlling the Kind of Output},
@@ -14526,8 +14889,11 @@ based on @code{gcc}.
 (It does not occur in @code{egcs}.)
 On AIX 4.1, @code{g77} might not build with the native (non-GNU) tools
-due to a linker bug in coping with the @samp{-bbigtoc} option
-which leads to a @samp{Relocation overflow} error.
+due to a linker bug in coping with the @samp{-bbigtoc} option which
+leads to a @samp{Relocation overflow} error.  The GNU linker is not
+recommended on current AIX versions, though; it was developed under a
+now-unsupported version.  This bug is said to be fixed by `update PTF
+U455193 for APAR IX75823'.
 Compiling with @samp{-mminimal-toc}
 might solve this problem, e.g.@: by adding

More information about the Gcc-patches mailing list