@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@*
* Fortran 2003 status:: Fortran 2003 features supported by GNU Fortran.
* Extensions:: Language extensions implemented by GNU Fortran.
* Intrinsic Procedures:: Intrinsic procedures supported by GNU Fortran.
+* Intrinsic Modules:: Intrinsic modules supported by GNU Fortran.
* Contributing:: How you can help.
* Copying:: GNU General Public License says
* 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
@menu
* About GNU Fortran:: What you should know about the GNU Fortran compiler.
* GNU Fortran and GCC:: You can compile Fortran, C, or other programs.
+* Preprocessing and conditional compilation:: The Fortran preprocessor
* GNU Fortran and G77:: Why we chose to start from scratch.
* Project Status:: Status of GNU Fortran, roadmap, proposed extensions.
* Standards:: Standards supported by GNU Fortran.
Fortran compiler.
+@c ---------------------------------------------------------------------
+@c Preprocessing and conditional compilation
+@c ---------------------------------------------------------------------
+
+@node Preprocessing and conditional compilation
+@section Preprocessing and conditional compilation
+@cindex CPP
+@cindex FPP
+@cindex Conditional compilation
+@cindex Preprocessing
+
+Many Fortran compilers including GNU Fortran allow to pass the source code
+through a C preprocessor (CPP; sometimes also called Fortran preprocessor,
+FPP) to allow for conditional compilation. In case of GNU Fortran
+this is the GNU C Preprocessor in the traditional mode. On systems with
+case-preserving file names, the preprocessor is automatically invoked if the
+file extension is @code{.F}, @code{.F90}, @code{.F95} or @code{.F03};
+otherwise use for fixed-format code the option @code{-x f77-cpp-input}
+and for free-format code @code{-x f95-cpp-input}. Invocation of the
+preprocessor can be suppressed using @code{-x f77} or @code{-x f95}.
+
+If the GNU Fortran invoked the preprocessor, @code{__GFORTRAN__}
+is defined and @code{__GNUC__}, @code{__GNUC_MINOR__} and
+@code{__GNUC_PATCHLEVEL__} can be used to determine the version of the
+compiler. See @ref{Top,,Overview,cpp,The C Preprocessor} for details.
+
+While CPP is the de-facto standard for preprocessing Fortran code,
+Part 3 of the Fortran 95 standard (ISO/IEC 1539-3:1998) defines
+Conditional Compilation, which is not widely used and not directly
+supported by the GNU Fortran compiler. You can use the program coco
+to preprocess such files (@uref{http://users.erols.com/dnagle/coco.html}).
+
+
@c ---------------------------------------------------------------------
@c GNU Fortran and G77
@c ---------------------------------------------------------------------
@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:
@smallexample
TYPESPEC*size x,y,z
@end smallexample
+@noindent
where @code{TYPESPEC} is a basic type (@code{INTEGER}, @code{REAL},
-etc.), and where @code{size} is a byte count corresponding to a valid
-kind for that type. 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
+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:
@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
@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
For details refer to the actual
@uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
-OpenMP Application Program Interface v2.5} specification.
+OpenMP Application Program Interface v2.5} specification and to the
+@ref{Top,,Introduction,libgomp,GNU OpenMP runtime library}.
+
+@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
@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