From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1498) id 33AF9385840B; Thu, 4 Nov 2021 16:54:02 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 33AF9385840B MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="utf-8" From: Sandra Loosemore To: gcc-cvs@gcc.gnu.org Subject: [gcc r12-4915] Fortran manual: Combine standard conformance docs in one place. X-Act-Checkin: gcc X-Git-Author: Sandra Loosemore X-Git-Refname: refs/heads/master X-Git-Oldrev: d3f7a2fa64f8777cb7eae1b99ff80fbe717095ac X-Git-Newrev: 2b1c757d835372d4454b3760b5fbf793bd372529 Message-Id: <20211104165402.33AF9385840B@sourceware.org> Date: Thu, 4 Nov 2021 16:54:02 +0000 (GMT) X-BeenThere: gcc-cvs@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-cvs mailing list List-Unsubscribe: , List-Archive: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 04 Nov 2021 16:54:02 -0000 https://gcc.gnu.org/g:2b1c757d835372d4454b3760b5fbf793bd372529 commit r12-4915-g2b1c757d835372d4454b3760b5fbf793bd372529 Author: Sandra Loosemore Date: Fri Oct 29 17:16:40 2021 -0700 Fortran manual: Combine standard conformance docs in one place. Discussion of conformance with various revisions of the Fortran standard was split between two separate parts of the manual. This patch moves it all to the introductory chapter. 2021-11-01 Sandra Loosemore gcc/fortran/ * gfortran.texi (Standards): Move discussion of specific standard versions here.... (Fortran standards status): ...from here, and delete this node. Diff: --- gcc/fortran/gfortran.texi | 508 +++++++++++++++++++++++----------------------- 1 file changed, 250 insertions(+), 258 deletions(-) diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi index 0ace382ec3c..26cf44fde4b 100644 --- a/gcc/fortran/gfortran.texi +++ b/gcc/fortran/gfortran.texi @@ -180,7 +180,6 @@ Part I: Invoking GNU Fortran * Runtime:: Influencing runtime behavior with environment variables. Part II: Language Reference -* Fortran standards status:: Fortran 2003, 2008 and 2018 features supported by GNU Fortran. * Compiler Characteristics:: User-visible implementation details. * Extensions:: Language extensions implemented by GNU Fortran. * Mixed-Language Programming:: Interoperability with C @@ -524,7 +523,10 @@ Fortran 2008 and Fortran 2018. @cindex Standards @menu -* Varying Length Character Strings:: +* Fortran 95 status:: +* Fortran 2003 status:: +* Fortran 2008 status:: +* Fortran 2018 status:: @end menu The GNU Fortran compiler implements @@ -547,8 +549,8 @@ There also is support for the OpenACC specification (targeting version 2.6, @uref{http://www.openacc.org/}). See @uref{https://gcc.gnu.org/wiki/OpenACC} for more information. -@node Varying Length Character Strings -@subsection Varying Length Character Strings +@node Fortran 95 status +@subsection Fortran 95 status @cindex Varying length character strings @cindex Varying length strings @cindex strings, varying length @@ -565,257 +567,8 @@ the features of @code{ISO_VARYING_STRING} and should be considered as replacement. (Namely, allocatable or pointers of the type @code{character(len=:)}.) - -@c ===================================================================== -@c PART I: INVOCATION REFERENCE -@c ===================================================================== - -@tex -\part{I}{Invoking GNU Fortran} -@end tex - -@c --------------------------------------------------------------------- -@c Compiler Options -@c --------------------------------------------------------------------- - -@include invoke.texi - - -@c --------------------------------------------------------------------- -@c Runtime -@c --------------------------------------------------------------------- - -@node Runtime -@chapter Runtime: Influencing runtime behavior with environment variables -@cindex environment variable - -The behavior of the @command{gfortran} can be influenced by -environment variables. - -Malformed environment variables are silently ignored. - -@menu -* TMPDIR:: Directory for scratch files -* GFORTRAN_STDIN_UNIT:: Unit number for standard input -* GFORTRAN_STDOUT_UNIT:: Unit number for standard output -* GFORTRAN_STDERR_UNIT:: Unit number for standard error -* GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units -* GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units. -* GFORTRAN_SHOW_LOCUS:: Show location for runtime errors -* GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted -* GFORTRAN_LIST_SEPARATOR:: Separator for list output -* GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O -* GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors -* GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files -* GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files -@end menu - -@node TMPDIR -@section @env{TMPDIR}---Directory for scratch files - -When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to -create the file in one of the potential directories by testing each -directory in the order below. - -@enumerate -@item -The environment variable @env{TMPDIR}, if it exists. - -@item -On the MinGW target, the directory returned by the @code{GetTempPath} -function. Alternatively, on the Cygwin target, the @env{TMP} and -@env{TEMP} environment variables, if they exist, in that order. - -@item -The @code{P_tmpdir} macro if it is defined, otherwise the directory -@file{/tmp}. -@end enumerate - -@node GFORTRAN_STDIN_UNIT -@section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input - -This environment variable can be used to select the unit number -preconnected to standard input. This must be a positive integer. -The default value is 5. - -@node GFORTRAN_STDOUT_UNIT -@section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output - -This environment variable can be used to select the unit number -preconnected to standard output. This must be a positive integer. -The default value is 6. - -@node GFORTRAN_STDERR_UNIT -@section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error - -This environment variable can be used to select the unit number -preconnected to standard error. This must be a positive integer. -The default value is 0. - -@node GFORTRAN_UNBUFFERED_ALL -@section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units - -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_UNBUFFERED_PRECONNECTED -@section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units - -The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls -whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) 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_SHOW_LOCUS -@section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors - -If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and -line numbers for runtime errors are printed. If the first letter is -@samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers -for runtime errors. The default is to print the location. - -@node GFORTRAN_OPTIONAL_PLUS -@section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted - -If the first letter is @samp{y}, @samp{Y} or @samp{1}, -a plus sign is printed -where permitted by the Fortran standard. If the first letter -is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed -in most cases. Default is not to print plus signs. - -@node GFORTRAN_LIST_SEPARATOR -@section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output - -This environment variable specifies the separator when writing -list-directed output. It may contain any number of spaces and -at most one comma. If you specify this on the command line, -be sure to quote spaces, as in -@smallexample -$ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out -@end smallexample -when @command{a.out} is the compiled Fortran program that you want to run. -Default is a single space. - -@node GFORTRAN_CONVERT_UNIT -@section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O - -By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible -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 | exception ; -mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ; -exception: mode ':' unit_list | unit_list ; -unit_list: unit_spec | unit_list unit_spec ; -unit_spec: INTEGER | INTEGER '-' INTEGER ; -@end smallexample -The variable consists of an optional default mode, followed by -a list of optional exceptions, which are separated by semicolons -from the preceding default and each other. Each exception consists -of a format and a comma-separated list of units. Valid values for -the modes are the same as for the @code{CONVERT} specifier: - -@itemize @w{} -@item @code{NATIVE} Use the native format. This is the default. -@item @code{SWAP} Swap between little- and big-endian. -@item @code{LITTLE_ENDIAN} Use the little-endian format -for unformatted files. -@item @code{BIG_ENDIAN} Use the big-endian format for unformatted files. -@end itemize -A missing mode for an exception is taken to mean @code{BIG_ENDIAN}. -Examples of values for @env{GFORTRAN_CONVERT_UNIT} are: -@itemize @w{} -@item @code{'big_endian'} Do all unformatted I/O in big_endian mode. -@item @code{'little_endian;native:10-20,25'} Do all unformatted I/O -in little_endian mode, except for units 10 to 20 and 25, which are in -native format. -@item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native. -@end itemize - -Setting the environment variables should be done on the command -line or via the @command{export} -command for @command{sh}-compatible shells and via @command{setenv} -for @command{csh}-compatible shells. - -Example for @command{sh}: -@smallexample -$ gfortran foo.f90 -$ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out -@end smallexample - -Example code for @command{csh}: -@smallexample -% gfortran foo.f90 -% setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20' -% ./a.out -@end smallexample - -Using anything but the native representation for unformatted data -carries a significant speed overhead. If speed in this area matters -to you, it is best if you use this only for data that needs to be -portable. - -@xref{CONVERT specifier}, for an alternative way to specify the -data representation for unformatted files. @xref{Runtime Options}, for -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_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 serious run-time error occurs. To disable -the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}. -Default is to print a backtrace unless the @option{-fno-backtrace} -compile option was used. - -@node GFORTRAN_FORMATTED_BUFFER_SIZE -@section @env{GFORTRAN_FORMATTED_BUFFER_SIZE}---Set buffer size for formatted I/O - -The @env{GFORTRAN_FORMATTED_BUFFER_SIZE} environment variable -specifies buffer size in bytes to be used for formatted output. -The default value is 8192. - -@node GFORTRAN_UNFORMATTED_BUFFER_SIZE -@section @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE}---Set buffer size for unformatted I/O - -The @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE} environment variable -specifies buffer size in bytes to be used for unformatted output. -The default value is 131072. - -@c ===================================================================== -@c PART II: LANGUAGE REFERENCE -@c ===================================================================== - -@tex -\part{II}{Language Reference} -@end tex - -@c --------------------------------------------------------------------- -@c Fortran standards status -@c --------------------------------------------------------------------- - -@node Fortran standards status -@chapter Fortran standards status - -@menu -* Fortran 2003 status:: -* Fortran 2008 status:: -* Fortran 2018 status:: -@end menu - @node Fortran 2003 status -@section Fortran 2003 status +@subsection Fortran 2003 status GNU Fortran supports several Fortran 2003 features; an incomplete list can be found below. See also the @@ -992,7 +745,7 @@ Renaming of operators in the @code{USE} statement. @node Fortran 2008 status -@section Fortran 2008 status +@subsection Fortran 2008 status The latest version of the Fortran standard is ISO/IEC 1539-1:2010, informally known as Fortran 2008. The official version is available from International @@ -1112,7 +865,7 @@ arrays are supported for named constants (@code{PARAMETER}). @node Fortran 2018 status -@section Status of Fortran 2018 support +@subsection Status of Fortran 2018 support @itemize @item ERROR STOP in a PURE procedure @@ -1131,7 +884,7 @@ specifier now conforms to Fortran 2018. @end itemize -@subsection TS 29113 Status (Further Interoperability with C) +@subsubsection TS 29113 Status (Further Interoperability with C) GNU Fortran supports some of the new features of the Technical Specification (TS) 29113 on Further Interoperability of Fortran with C. @@ -1162,7 +915,7 @@ done in the library. The include file ISO_Fortran_binding.h is can be found in -@subsection TS 18508 Status (Additional Parallel Features) +@subsubsection TS 18508 Status (Additional Parallel Features) GNU Fortran supports the following new features of the Technical Specification 18508 on Additional Parallel Features in Fortran: @@ -1183,6 +936,245 @@ polymorphic components. @end itemize + + +@c ===================================================================== +@c PART I: INVOCATION REFERENCE +@c ===================================================================== + +@tex +\part{I}{Invoking GNU Fortran} +@end tex + +@c --------------------------------------------------------------------- +@c Compiler Options +@c --------------------------------------------------------------------- + +@include invoke.texi + + +@c --------------------------------------------------------------------- +@c Runtime +@c --------------------------------------------------------------------- + +@node Runtime +@chapter Runtime: Influencing runtime behavior with environment variables +@cindex environment variable + +The behavior of the @command{gfortran} can be influenced by +environment variables. + +Malformed environment variables are silently ignored. + +@menu +* TMPDIR:: Directory for scratch files +* GFORTRAN_STDIN_UNIT:: Unit number for standard input +* GFORTRAN_STDOUT_UNIT:: Unit number for standard output +* GFORTRAN_STDERR_UNIT:: Unit number for standard error +* GFORTRAN_UNBUFFERED_ALL:: Do not buffer I/O for all units +* GFORTRAN_UNBUFFERED_PRECONNECTED:: Do not buffer I/O for preconnected units. +* GFORTRAN_SHOW_LOCUS:: Show location for runtime errors +* GFORTRAN_OPTIONAL_PLUS:: Print leading + where permitted +* GFORTRAN_LIST_SEPARATOR:: Separator for list output +* GFORTRAN_CONVERT_UNIT:: Set endianness for unformatted I/O +* GFORTRAN_ERROR_BACKTRACE:: Show backtrace on run-time errors +* GFORTRAN_FORMATTED_BUFFER_SIZE:: Buffer size for formatted files +* GFORTRAN_UNFORMATTED_BUFFER_SIZE:: Buffer size for unformatted files +@end menu + +@node TMPDIR +@section @env{TMPDIR}---Directory for scratch files + +When opening a file with @code{STATUS='SCRATCH'}, GNU Fortran tries to +create the file in one of the potential directories by testing each +directory in the order below. + +@enumerate +@item +The environment variable @env{TMPDIR}, if it exists. + +@item +On the MinGW target, the directory returned by the @code{GetTempPath} +function. Alternatively, on the Cygwin target, the @env{TMP} and +@env{TEMP} environment variables, if they exist, in that order. + +@item +The @code{P_tmpdir} macro if it is defined, otherwise the directory +@file{/tmp}. +@end enumerate + +@node GFORTRAN_STDIN_UNIT +@section @env{GFORTRAN_STDIN_UNIT}---Unit number for standard input + +This environment variable can be used to select the unit number +preconnected to standard input. This must be a positive integer. +The default value is 5. + +@node GFORTRAN_STDOUT_UNIT +@section @env{GFORTRAN_STDOUT_UNIT}---Unit number for standard output + +This environment variable can be used to select the unit number +preconnected to standard output. This must be a positive integer. +The default value is 6. + +@node GFORTRAN_STDERR_UNIT +@section @env{GFORTRAN_STDERR_UNIT}---Unit number for standard error + +This environment variable can be used to select the unit number +preconnected to standard error. This must be a positive integer. +The default value is 0. + +@node GFORTRAN_UNBUFFERED_ALL +@section @env{GFORTRAN_UNBUFFERED_ALL}---Do not buffer I/O on all units + +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_UNBUFFERED_PRECONNECTED +@section @env{GFORTRAN_UNBUFFERED_PRECONNECTED}---Do not buffer I/O on preconnected units + +The environment variable named @env{GFORTRAN_UNBUFFERED_PRECONNECTED} controls +whether I/O on a preconnected unit (i.e.@: STDOUT or STDERR) 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_SHOW_LOCUS +@section @env{GFORTRAN_SHOW_LOCUS}---Show location for runtime errors + +If the first letter is @samp{y}, @samp{Y} or @samp{1}, filename and +line numbers for runtime errors are printed. If the first letter is +@samp{n}, @samp{N} or @samp{0}, do not print filename and line numbers +for runtime errors. The default is to print the location. + +@node GFORTRAN_OPTIONAL_PLUS +@section @env{GFORTRAN_OPTIONAL_PLUS}---Print leading + where permitted + +If the first letter is @samp{y}, @samp{Y} or @samp{1}, +a plus sign is printed +where permitted by the Fortran standard. If the first letter +is @samp{n}, @samp{N} or @samp{0}, a plus sign is not printed +in most cases. Default is not to print plus signs. + +@node GFORTRAN_LIST_SEPARATOR +@section @env{GFORTRAN_LIST_SEPARATOR}---Separator for list output + +This environment variable specifies the separator when writing +list-directed output. It may contain any number of spaces and +at most one comma. If you specify this on the command line, +be sure to quote spaces, as in +@smallexample +$ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out +@end smallexample +when @command{a.out} is the compiled Fortran program that you want to run. +Default is a single space. + +@node GFORTRAN_CONVERT_UNIT +@section @env{GFORTRAN_CONVERT_UNIT}---Set endianness for unformatted I/O + +By setting the @env{GFORTRAN_CONVERT_UNIT} variable, it is possible +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 | exception ; +mode: 'native' | 'swap' | 'big_endian' | 'little_endian' ; +exception: mode ':' unit_list | unit_list ; +unit_list: unit_spec | unit_list unit_spec ; +unit_spec: INTEGER | INTEGER '-' INTEGER ; +@end smallexample +The variable consists of an optional default mode, followed by +a list of optional exceptions, which are separated by semicolons +from the preceding default and each other. Each exception consists +of a format and a comma-separated list of units. Valid values for +the modes are the same as for the @code{CONVERT} specifier: + +@itemize @w{} +@item @code{NATIVE} Use the native format. This is the default. +@item @code{SWAP} Swap between little- and big-endian. +@item @code{LITTLE_ENDIAN} Use the little-endian format +for unformatted files. +@item @code{BIG_ENDIAN} Use the big-endian format for unformatted files. +@end itemize +A missing mode for an exception is taken to mean @code{BIG_ENDIAN}. +Examples of values for @env{GFORTRAN_CONVERT_UNIT} are: +@itemize @w{} +@item @code{'big_endian'} Do all unformatted I/O in big_endian mode. +@item @code{'little_endian;native:10-20,25'} Do all unformatted I/O +in little_endian mode, except for units 10 to 20 and 25, which are in +native format. +@item @code{'10-20'} Units 10 to 20 are big-endian, the rest is native. +@end itemize + +Setting the environment variables should be done on the command +line or via the @command{export} +command for @command{sh}-compatible shells and via @command{setenv} +for @command{csh}-compatible shells. + +Example for @command{sh}: +@smallexample +$ gfortran foo.f90 +$ GFORTRAN_CONVERT_UNIT='big_endian;native:10-20' ./a.out +@end smallexample + +Example code for @command{csh}: +@smallexample +% gfortran foo.f90 +% setenv GFORTRAN_CONVERT_UNIT 'big_endian;native:10-20' +% ./a.out +@end smallexample + +Using anything but the native representation for unformatted data +carries a significant speed overhead. If speed in this area matters +to you, it is best if you use this only for data that needs to be +portable. + +@xref{CONVERT specifier}, for an alternative way to specify the +data representation for unformatted files. @xref{Runtime Options}, for +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_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 serious run-time error occurs. To disable +the backtracing, set the variable to @samp{n}, @samp{N}, @samp{0}. +Default is to print a backtrace unless the @option{-fno-backtrace} +compile option was used. + +@node GFORTRAN_FORMATTED_BUFFER_SIZE +@section @env{GFORTRAN_FORMATTED_BUFFER_SIZE}---Set buffer size for formatted I/O + +The @env{GFORTRAN_FORMATTED_BUFFER_SIZE} environment variable +specifies buffer size in bytes to be used for formatted output. +The default value is 8192. + +@node GFORTRAN_UNFORMATTED_BUFFER_SIZE +@section @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE}---Set buffer size for unformatted I/O + +The @env{GFORTRAN_UNFORMATTED_BUFFER_SIZE} environment variable +specifies buffer size in bytes to be used for unformatted output. +The default value is 131072. + +@c ===================================================================== +@c PART II: LANGUAGE REFERENCE +@c ===================================================================== + +@tex +\part{II}{Language Reference} +@end tex + + + @c --------------------------------------------------------------------- @c Compiler Characteristics @c ---------------------------------------------------------------------