@setchapternewpage odd
@titlepage
@title Using GNU Fortran
-@sp 2
-@center The gfortran team
+@versionsubtitle
+@author The @t{gfortran} team
@page
@vskip 0pt plus 1filll
-For the @value{version-GCC} Version
-@sp 1
Published by the Free Software Foundation@*
51 Franklin Street, Fifth Floor@*
Boston, MA 02110-1301, USA@*
* GNU Free Documentation License::
How you can copy and share this manual.
* Funding:: How to help assure continued work for free software.
-* Index:: Index of this documentation.
+* Option Index:: Index of command line options
+* Keyword Index:: Index of concepts
@end menu
@end ifnottex
Fortran) for each file in the source code, and then calls the assembler
and linker as appropriate to produce the compiled output. In a copy of
GCC which has been compiled with Fortran language support enabled,
-@command{gcc} will recognize files with @file{.f}, @file{.f90}, and
-@file{.f95} extensions as Fortran source code, and compile it
+@command{gcc} will recognize files with @file{.f}, @file{.f90}, @file{.f95},
+and @file{.f03} extensions as Fortran source code, and compile it
accordingly. A @command{gfortran} driver program is also provided,
which is identical to @command{gcc} except that it automatically links
the Fortran runtime libraries into the compiled program.
@node GNU Fortran and G77
@section GNU Fortran and G77
@cindex Fortran 77
-@cindex G77
-
-Why do we write a compiler front end from scratch?
-There's a fine Fortran 77 compiler in the
-GNU Compiler Collection that accepts some features
-of the Fortran 90 standard as extensions.
-Why not start from there and revamp it?
-
-One of the reasons is that Craig Burley, the author of G77,
-has decided to stop working on the G77 front end.
-On @uref{http://world.std.com/~burley/g77-why.html,
-Craig explains the reasons for his decision to stop working on G77}
-in one of the pages in his homepage.
-Among the reasons is a lack of interest in improvements to
-@command{g77}.
-Users appear to be quite satisfied with @command{g77} as it is.
-While @command{g77} is still being maintained (by Toon Moene),
-it is unlikely that sufficient people will be willing
-to completely rewrite the existing code.
-
-But there are other reasons to start from scratch.
-Many people, including Craig Burley,
-no longer agreed with certain design decisions in the G77 front end.
-Also, the interface of @command{g77} to the back end is written in
-a style which is confusing and not up to date on recommended practice.
-In fact, a full rewrite had already been planned for GCC 3.0.
-
-When Craig decided to stop,
-it just seemed to be a better idea to start a new project from scratch,
-because it was expected to be easier to maintain code we
-develop ourselves than to do a major overhaul of @command{g77} first,
-and then build a Fortran 95 compiler out of it.
+@cindex @command{g77}
+
+The GNU Fortran compiler is the successor to @command{g77}, the Fortran
+77 front end included in GCC prior to version 4. It is an entirely new
+program that has been designed to provide Fortran 95 support and
+extensibility for future Fortran language standards, as well as providing
+backwards compatibility for Fortran 77 and nearly all of the GNU language
+extensions supported by @command{g77}.
@c ---------------------------------------------------------------------
@node Runtime
@chapter Runtime: Influencing runtime behavior with environment variables
-@cindex Runtime
+@cindex environment variable
The behavior of the @command{gfortran} can be influenced by
environment variables.
* GFORTRAN_STDERR_UNIT:: Unit number for standard error
* GFORTRAN_USE_STDERR:: Send library output to standard error
* GFORTRAN_TMPDIR:: Directory for scratch files
-* GFORTRAN_UNBUFFERED_ALL:: Don't buffer output
+* GFORTRAN_UNBUFFERED_n:: Don't buffer I/O for specific unit.
+* GFORTRAN_UNBUFFERED_ALL:: Don't buffer I/O for all units.
* GFORTRAN_SHOW_LOCUS:: Show location for runtime errors
* GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted
* GFORTRAN_DEFAULT_RECL:: Default record length for new files
* GFORTRAN_LIST_SEPARATOR:: Separator for list output
* GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O
+* GFORTRAN_ERROR_DUMPCORE:: Dump core on run-time errors
+* GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors
@end menu
@node GFORTRAN_STDIN_UNIT
GNU Fortran searches for the environment variable @env{TMP}. If
this is also missing, the default is @file{/tmp}.
+@node GFORTRAN_UNBUFFERED_n
+@section @env{GFORTRAN_UNBUFFERED_n}---Don't buffer I/O on unit n
+
+Environment variables named @env{GFORTRAN_UNBUFFERED_n}, where
+@samp{n} is an integer, control whether I/O on unit @samp{n} is
+unbuffered. If the first letter is @samp{y}, @samp{Y} or @samp{1},
+I/O is unbuffered. This will slow down small sequential reads and
+writes. If the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is
+buffered. This is the default.
+
@node GFORTRAN_UNBUFFERED_ALL
-@section @env{GFORTRAN_UNBUFFERED_ALL}---Don't buffer output
+@section @env{GFORTRAN_UNBUFFERED_ALL}---Don't buffer I/O on all units
-This environment variable controls whether all output is unbuffered.
-If the first letter is @samp{y}, @samp{Y} or @samp{1}, all output is
-unbuffered. This will slow down large writes. If the first letter is
-@samp{n}, @samp{N} or @samp{0}, output is buffered. This is the
-default.
+This environment variable controls whether all I/O is unbuffered. If
+the first letter is @samp{y}, @samp{Y} or @samp{1}, all I/O is
+unbuffered. This will slow down small sequential reads and writes. If
+the first letter is @samp{n}, @samp{N} or @samp{0}, I/O is buffered.
+This is the default.
@node GFORTRAN_SHOW_LOCUS
@section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors
to change the representation of data for unformatted files.
The syntax for the @env{GFORTRAN_CONVERT_UNIT} variable is:
@smallexample
-GFORTRAN_CONVERT_UNIT: mode | mode ';' exception ;
+GFORTRAN_CONVERT_UNIT: mode | mode ';' exception | exception ;
mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ;
exception: mode ':' unit_list | unit_list ;
unit_list: unit_spec | unit_list unit_spec ;
setting a default data representation for the whole program. The
@code{CONVERT} specifier overrides the @option{-fconvert} compile options.
+@emph{Note that the values specified via the GFORTRAN_CONVERT_UNIT
+environment variable will override the CONVERT specifier in the
+open statement}. This is to give control over data formats to
+users who do not have the source code of their program available.
+
+@node GFORTRAN_ERROR_DUMPCORE
+@section @env{GFORTRAN_ERROR_DUMPCORE}---Dump core on run-time errors
+
+If the @env{GFORTRAN_ERROR_DUMPCORE} variable is set to
+@samp{y}, @samp{Y} or @samp{1} (only the first letter is relevant)
+then library run-time errors cause core dumps. To disable the core
+dumps, set the variable to @samp{n}, @samp{N}, @samp{0}. Default
+is not to core dump unless the @option{-fdump-core} compile option
+was used.
+
+@node GFORTRAN_ERROR_BACKTRACE
+@section @env{GFORTRAN_ERROR_BACKTRACE}---Show backtrace on run-time errors
+
+If the @env{GFORTRAN_ERROR_BACKTRACE} variable is set to
+@samp{y}, @samp{Y} or @samp{1} (only the first letter is relevant)
+then a backtrace is printed when a run-time error occurs.
+To disable the backtracing, set the variable to
+@samp{n}, @samp{N}, @samp{0}. Default is not to print a backtrace
+unless the @option{-fbacktrace} compile option
+was used.
@c =====================================================================
@c PART II: LANGUAGE REFERENCE
@code{move_alloc}.
@item
-@cindex Array constructors
+@cindex array, constructors
@cindex @code{[...]}
Array constructors using square brackets. That is, @code{[...]} rather
than @code{(/.../)}.
@item
@cindex @code{FLUSH} statement
+@cindex statement, @code{FLUSH}
@code{FLUSH} statement.
@item
@item
@cindex @code{ENUM} statement
@cindex @code{ENUMERATOR} statement
-@cindex @code{-fshort-enums} option
+@cindex statement, @code{ENUM}
+@cindex statement, @code{ENUMERATOR}
+@opindex @code{fshort-enums}
Support for the declaration of enumeration constants via the
@code{ENUM} and @code{ENUMERATOR} statements. Interoperability with
@command{gcc} is guaranteed also for the case where the
Namelist input/output for internal files.
@item
-@cindex @code{PROTECTED}
+@cindex @code{PROTECTED} statement
+@cindex statement, @code{PROTECTED}
The @code{PROTECTED} statement and attribute.
@item
-@cindex @code{VALUE}
+@cindex @code{VALUE} statement
+@cindex statement, @code{VALUE}
The @code{VALUE} statement and attribute.
@item
-@cindex @code{VOLATILE}
+@cindex @code{VOLATILE} statement
+@cindex statement, @code{VOLATILE}
The @code{VOLATILE} statement and attribute.
@item
-@cindex @code{IMPORT}
+@cindex @code{IMPORT} statement
+@cindex statement, @code{IMPORT}
The @code{IMPORT} statement, allowing to import
host-associated derived types.
@item
-@cindex @code{USE, INTRINSIC}
-@cindex @code{ISO_FORTRAN_ENV}
+@cindex @code{USE, INTRINSIC} statement
+@cindex statement, @code{USE, INTRINSIC}
+@cindex @code{ISO_FORTRAN_ENV} statement
+@cindex statement, @code{ISO_FORTRAN_ENV}
@code{USE} statement with @code{INTRINSIC} and @code{NON_INTRINSIC}
attribute; supported intrinsic modules: @code{ISO_FORTRAN_ENV},
@code{OMP_LIB} and @code{OMP_LIB_KINDS}.
+@item
+Renaming of operators in the @code{USE} statement.
+
+@item
+@cindex ISO C Bindings
+Interoperability with C (ISO C Bindings)
+
@end itemize
* Cray pointers::
* CONVERT specifier::
* OpenMP::
+* Argument list functions::
@end menu
@node Old-style kind specifications
@section Old-style kind specifications
-@cindex Kind specifications
+@cindex kind, old-style
-GNU Fortran allows old-style kind specifications in
-declarations. These look like:
+GNU Fortran allows old-style kind specifications in declarations. These
+look like:
@smallexample
- TYPESPEC*k x,y,z
+ TYPESPEC*size x,y,z
@end smallexample
+@noindent
where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
-etc.), and where @code{k} is a valid kind number for that type. The
-statement then declares @code{x}, @code{y} and @code{z} to be of
-type @code{TYPESPEC} with kind @code{k}. This is equivalent to the
-standard conforming declaration
+etc.), and where @code{size} is a byte count corresponding to the
+storage size of a valid kind for that type. (For @code{COMPLEX}
+variables, @code{size} is the total size of the real and imaginary
+parts.) The statement then declares @code{x}, @code{y} and @code{z} to
+be of type @code{TYPESPEC} with the appropriate kind. This is
+equivalent to the standard-conforming declaration
@smallexample
TYPESPEC(k) x,y,z
@end smallexample
+@noindent
+where @code{k} is equal to @code{size} for most types, but is equal to
+@code{size/2} for the @code{COMPLEX} type.
@node Old-style variable initialization
@section Old-style variable initialization
-@cindex Initialization
GNU Fortran allows old-style initialization of variables of the
form:
something like @code{INTEGER I,J/2,3/} is not valid. This style of
initialization is only allowed in declarations without double colons
(@code{::}); the double colons were introduced in Fortran 90, which also
-introduced a standard syntax for initializating variables in type
+introduced a standard syntax for initializing variables in type
declarations.
Examples of standard-conforming code equivalent to the above example
@node X format descriptor without count field
@section @code{X} format descriptor without count field
-@cindex @code{X} format descriptor without count field
To support legacy codes, GNU Fortran permits the count field of the
@code{X} edit descriptor in @code{FORMAT} statements to be omitted.
@node Commas in FORMAT specifications
@section Commas in @code{FORMAT} specifications
-@cindex Commas in @code{FORMAT} specifications
To support legacy codes, GNU Fortran allows the comma separator
to be omitted immediately before and after character string edit
@node Missing period in FORMAT specifications
@section Missing period in @code{FORMAT} specifications
-@cindex Missing period in @code{FORMAT} specifications
To support legacy codes, GNU Fortran allows missing periods in format
specifications if and only if @option{-std=legacy} is given on the
@node Real array indices
@section Real array indices
-@cindex Real array indices
+@cindex array, indices of type real
As an extension, GNU Fortran allows the use of @code{REAL} expressions
or variables as array indices.
@node Unary operators
@section Unary operators
-@cindex Unary operators
+@cindex operators, unary
As an extension, GNU Fortran allows unary plus and unary minus operators
to appear as the second operand of binary arithmetic operators without
@node Implicitly convert LOGICAL and INTEGER values
@section Implicitly convert @code{LOGICAL} and @code{INTEGER} values
-@cindex Implicitly convert @code{LOGICAL} and @code{INTEGER} values
+@cindex conversion, to integer
+@cindex conversion, to logical
As an extension for backwards compatibility with other compilers, GNU
Fortran allows the implicit conversion of @code{LOGICAL} values to
GNU Fortran supports Hollerith constants in assignments, function
arguments, and @code{DATA} and @code{ASSIGN} statements. A Hollerith
-constant is written as a string of characters preceeded by an integer
+constant is written as a string of characters preceded by an integer
constant indicating the character count, and the letter @code{H} or
@code{h}, and stored in bytewise fashion in a numeric (@code{INTEGER},
@code{REAL}, or @code{complex}) or @code{LOGICAL} variable. The
@node Cray pointers
@section Cray pointers
-@cindex Cray pointers
+@cindex pointer, cray
Cray pointers are part of a non-standard extension that provides a
C-like pointer in Fortran. This is accomplished through a pair of
@uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
OpenMP Application Program Interface v2.5} specification.
+@node Argument list functions
+@section Argument list functions %VAL, %REF and %LOC
+@cindex argument list functions
+@cindex %VAL
+@cindex %REF
+@cindex %LOC
+
+GNU Fortran supports argument list functions @code{%VAL}, @code{%REF}
+and @code{%LOC} statements, for backward compatibility with g77.
+It is recommended that these should be used only for code that is
+accessing facilities outside of GNU Fortran, such as operating system
+or windowing facilities. It is best to constrain such uses to isolated
+portions of a program--portions that deal specifically and exclusively
+with low-level, system-dependent facilities. Such portions might well
+provide a portable interface for use by the program as a whole, but are
+themselves not portable, and should be thoroughly tested each time they
+are rebuilt using a new compiler or version of a compiler.
+
+@code{%VAL} passes a scalar argument by value, @code{%REF} passes it by
+reference and @code{%LOC} passes its memory location. Since gfortran
+already passes scalar arguments by reference, @code{%REF} is in effect
+a do-nothing. @code{%LOC} has the same effect as a fortran pointer.
+
+An example of passing an argument by value to a C subroutine foo.:
+@smallexample
+C
+C prototype void foo_ (float x);
+C
+ external foo
+ real*4 x
+ x = 3.14159
+ call foo (%VAL (x))
+ end
+@end smallexample
+
+For details refer to the g77 manual
+@uref{http://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/index.html#Top}.
+
+Also, the gfortran testsuite c_by_val.f and its partner c_by_val.c are
+worth a look.
+
@c ---------------------------------------------------------------------
@c Intrinsic Procedures
@c ---------------------------------------------------------------------
@include funding.texi
@c ---------------------------------------------------------------------
-@c Index
+@c Indices
@c ---------------------------------------------------------------------
-@node Index
-@unnumbered Index
-
+@node Option Index
+@unnumbered Option Index
+@command{gfortran}'s command line options are indexed here without any
+initial @samp{-} or @samp{--}. Where an option has both positive and
+negative forms (such as -foption and -fno-option), relevant entries in
+the manual are indexed under the most appropriate form; it may sometimes
+be useful to look up both forms.
+@printindex op
+
+@node Keyword Index
+@unnumbered Keyword Index
@printindex cp
@bye