The present tense is preferred for expressing facts or enduring behavior. Thus we should say "option X does Y" instead of "option X will do Y", reserving the future tense for things that happen at some later time (such as in a future release of GCC, or at run time as explicitly contrasted with compile time).
This set of edits is largely mechanical substitution of phrasing involving "will". I also fixed a few more markup problems noted while editing nearby text and fixed a few instances of awkward wording. gcc/fortran/ChangeLog * gfortran.texi: Use the present tense throughout; fix some markup issues and awkward wording. * invoke.texi: Likewise. --- gcc/fortran/gfortran.texi | 141 +++++++++++++++++++------------------ gcc/fortran/invoke.texi | 143 ++++++++++++++++++++------------------ 2 files changed, 147 insertions(+), 137 deletions(-) diff --git a/gcc/fortran/gfortran.texi b/gcc/fortran/gfortran.texi index 77c5e5235f9..5b27a6dbe30 100644 --- a/gcc/fortran/gfortran.texi +++ b/gcc/fortran/gfortran.texi @@ -634,7 +634,7 @@ The default value is 0. 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 +unbuffered. This slows 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. @@ -644,7 +644,7 @@ This is the default. 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 +slows 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 @@ -674,6 +674,7 @@ be sure to quote spaces, as in @smallexample $ GFORTRAN_LIST_SEPARATOR=' , ' ./a.out @end smallexample +@noindent when @command{a.out} is the compiled Fortran program that you want to run. Default is a single space. @@ -753,7 +754,7 @@ setting a default data representation for the whole program. The @code{CONVERT} specifier overrides the @option{-fconvert} compile options. Note that the values specified via the @env{GFORTRAN_CONVERT_UNIT} -environment variable will override the @code{CONVERT} specifier in the +environment variable override the @code{CONVERT} specifier in the @code{OPEN} statement. This is to give control over data formats to users who do not have the source code of their program available. @@ -889,7 +890,7 @@ See also @ref{Argument passing conventions} and @ref{Interoperability with C}. The Fortran standard does not require the compiler to evaluate all parts of an expression, if they do not contribute to the final result. For logical expressions with @code{.AND.} or @code{.OR.} operators, in particular, GNU -Fortran will optimize out function calls (even to impure functions) if the +Fortran optimizes out function calls (even to impure functions) if the result of the expression can be established without them. However, since not all compilers do that, and such an optimization can potentially modify the program flow and subsequent results, GNU Fortran throws warnings for such @@ -1018,17 +1019,17 @@ where file metadata is written to the directory lazily. This means that, for instance, the @code{dir} command can show a stale size for a file. One can force a directory metadata update by closing the unit, or by calling @code{_commit} on the file descriptor. Note, though, -that @code{_commit} will force all dirty data to stable storage, which +that @code{_commit} forces all dirty data to stable storage, which is often a very slow operation. The Network File System (NFS) implements a relaxed consistency model called open-to-close consistency. Closing a file forces dirty data and metadata to be flushed to the server, and opening a file forces the client to contact the server in order to revalidate cached -data. @code{fsync} will also force a flush of dirty data and metadata +data. @code{fsync} also forces a flush of dirty data and metadata to the server. Similar to @code{open} and @code{close}, acquiring and -releasing @code{fcntl} file locks, if the server supports them, will -also force cache validation and flushing dirty data and metadata. +releasing @code{fcntl} file locks, if the server supports them, +also forces cache validation and flushing dirty data and metadata. @node Files opened without an explicit ACTION= specifier @@ -1058,16 +1059,16 @@ symbolic links, on systems that support them. @item Results of @code{INQUIRE} statements of the ``inquire by file'' form relate to the target of the symbolic link. For example, -@code{INQUIRE(FILE="foo",EXIST=ex)} will set @var{ex} to @var{.true.} if +@code{INQUIRE(FILE="foo",EXIST=ex)} sets @var{ex} to @var{.true.} if @var{foo} is a symbolic link pointing to an existing file, and @var{.false.} if @var{foo} points to an non-existing file (``dangling'' symbolic link). @item Using the @code{OPEN} statement with a @code{STATUS="NEW"} specifier -on a symbolic link will result in an error condition, whether the symbolic +on a symbolic link results in an error condition, whether the symbolic link points to an existing target or is dangling. @item If a symbolic link was connected, using the @code{CLOSE} statement -with a @code{STATUS="DELETE"} specifier will cause the symbolic link itself +with a @code{STATUS="DELETE"} specifier causes the symbolic link itself to be deleted, not its target. @end itemize @@ -1375,8 +1376,8 @@ END PROGRAM test_print @item Expanded namelist reads are permitted. This causes an error if @option{-std=f95} is used. In the following example, the first element -of the array will be given the value 0.00 and the two succeeding -elements will be given the values 1.00 and 2.00. +of the array is given the value 0.00 and the two succeeding +elements are given the values 1.00 and 2.00. @smallexample &MYNML X(1,1) = 0.00 , 1.00 , 2.00 @@ -1439,7 +1440,7 @@ discouraged. To support legacy codes, GNU Fortran allows width to be omitted from format specifications if and only if @option{-fdec-format-defaults} is given on the -command line. Default widths will be used. This is considered non-conforming +command line. Default widths are used. This is considered non-conforming code and is discouraged. @smallexample @@ -1466,9 +1467,9 @@ GNU Fortran accepts real literal constants with an exponent-letter of @samp{Q}, for example, @code{1.23Q45}. The constant is interpreted as a @code{REAL(16)} entity on targets that support this type. If the target does not support @code{REAL(16)} but has a @code{REAL(10)} -type, then the real-literal-constant will be interpreted as a +type, then the real-literal-constant is interpreted as a @code{REAL(10)} entity. In the absence of @code{REAL(16)} and -@code{REAL(10)}, an error will occur. +@code{REAL(10)}, an error occurs. @node BOZ literal constants @subsection BOZ literal constants @@ -1554,7 +1555,7 @@ 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}), @code{LOGICAL} or @code{CHARACTER} variable. -The constant will be padded with spaces or truncated to fit the size of +The constant is padded with spaces or truncated to fit the size of the variable in which it is stored. Examples of valid uses of Hollerith constants: @@ -1570,8 +1571,8 @@ Examples of Hollerith constants: integer*4 a a = 0H ! Invalid, at least one character is needed. a = 4HAB12 ! Valid - a = 8H12345678 ! Valid, but the Hollerith constant will be truncated. - a = 3Hxyz ! Valid, but the Hollerith constant will be padded. + a = 8H12345678 ! Valid, but the Hollerith constant is truncated. + a = 3Hxyz ! Valid, but the Hollerith constant is padded. @end smallexample In general, Hollerith constants were used to provide a rudimentary @@ -1611,7 +1612,7 @@ is a non-standard extension. This feature is enabled using Character literals can be used in @code{DATA} statements and assignments with numeric (@code{INTEGER}, @code{REAL}, or @code{COMPLEX}) or @code{LOGICAL} variables. Like Hollerith constants they are copied byte-wise fashion. The -constant will be padded with spaces or truncated to fit the size of the +constant is padded with spaces or truncated to fit the size of the variable in which it is stored. Examples: @@ -1619,8 +1620,8 @@ Examples: integer*4 x data x / 'abcd' / - x = 'A' ! Will be padded. - x = 'ab1234' ! Will be truncated. + x = 'A' ! Is padded. + x = 'ab1234' ! Is truncated. @end smallexample @@ -1637,6 +1638,7 @@ Pointer/pointee pairs are declared in statements of the form: @smallexample pointer ( <pointer> , <pointee> ) @end smallexample +@noindent or, @smallexample pointer ( <pointer1> , <pointee1> ), ( <pointer2> , <pointee2> ), ... @@ -1660,11 +1662,11 @@ of a pointer, and so the following code is not portable: pointer (ipt, iarr) @end smallexample If a pointer is declared with a kind that is too small, the compiler -will issue a warning; the resulting binary will probably not work +issues a warning; the resulting binary will probably not work correctly, because the memory addresses stored in the pointers may be truncated. It is safer to omit the first line of the above example; -if explicit declaration of ipt's type is omitted, then the compiler -will ensure that ipt is an integer variable large enough to hold a +if explicit declaration of @code{ipt}'s type is omitted, then the compiler +ensures that @code{ipt} is an integer variable large enough to hold a pointer. Pointer arithmetic is valid with Cray pointers, but it is not the same @@ -1682,7 +1684,7 @@ The last statement does not set @code{ipt} to the address of @code{target(1)}, as it would in C pointer arithmetic. Adding @code{1} to @code{ipt} just adds one byte to the address stored in @code{ipt}. -Any expression involving the pointee will be translated to use the +Any expression involving the pointee is translated to use the value stored in the pointer as the base address. To get the address of elements, this extension provides an intrinsic @@ -1707,21 +1709,21 @@ example: ipt = loc(target) @end smallexample As long as @code{ipt} remains unchanged, @code{iarr} is now an alias for -@code{target}. The optimizer, however, will not detect this aliasing, so +@code{target}. The optimizer, however, does not detect this aliasing, so it is unsafe to use @code{iarr} and @code{target} simultaneously. Using a pointee in any way that violates the Fortran aliasing rules or -assumptions is illegal. It is the user's responsibility to avoid doing +assumptions is invalid. It is the user's responsibility to avoid doing this; the compiler works under the assumption that no such aliasing occurs. -Cray pointers will work correctly when there is no aliasing (i.e., when +Cray pointers work correctly when there is no aliasing (i.e., when they are used to access a dynamically allocated block of memory), and also in any routine where a pointee is used, but any variable with which it shares storage is not used. Code that violates these rules may not run as the user intends. This is not a bug in the optimizer; any code -that violates the aliasing rules is illegal. (Note that this is not +that violates the aliasing rules is invalid. (Note that this is not unique to GNU Fortran; any Fortran compiler that supports Cray pointers -will ``incorrectly'' optimize code with illegal aliasing.) +``incorrectly'' optimizes code with invalid aliasing.) There are a number of restrictions on the attributes that can be applied to Cray pointers and pointees. Pointees may not have the @@ -1749,10 +1751,10 @@ example, the following excerpt is valid: @end smallexample A pointer may be modified during the course of a program, and this -will change the location to which the pointee refers. However, when +changes the location to which the pointee refers. However, when pointees are passed as arguments, they are treated as ordinary variables in the invoked function. Subsequent changes to the pointer -will not change the base address of the array that was passed. +do not change the base address of the array that was passed. @node CONVERT specifier @subsection @code{CONVERT} specifier @@ -1799,11 +1801,11 @@ The value of the conversion can be queried by using on IEEE systems of kinds 4 and 8. Conversion between different ``extended double'' types on different architectures such as m68k and x86_64, which GNU Fortran -supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, will -probably not work. +supports as @code{REAL(KIND=10)} and @code{REAL(KIND=16)}, +probably does not work. Note that the values specified via the @env{GFORTRAN_CONVERT_UNIT} -environment variable will override the @code{CONVERT} specifier in the +environment variable overrides the @code{CONVERT} specifier in the @code{OPEN} statement. This is to give control over data formats to users who do not have the source code of their program available. @@ -2047,9 +2049,9 @@ rules and exceptions: Otherwise they may contain no specifiers. @item Structures may contain a special field with the name @code{%FILL}. -This will create an anonymous component which cannot be accessed but occupies +This creates an anonymous component which cannot be accessed but occupies space just as if a component of the same type was declared in its place, useful -for alignment purposes. As an example, the following structure will consist +for alignment purposes. As an example, the following structure consists of at least sixteen bytes: @smallexample @@ -2289,9 +2291,9 @@ storage. These follow the syntax of the Fortran standard @code{SAVE} attribute. @code{STATIC} is exactly equivalent to @code{SAVE}, and specifies that an entity should be allocated in static memory. As an example, @code{STATIC} -local variables will retain their values across multiple calls to a function. +local variables retain their values across multiple calls to a function. -Entities marked @code{AUTOMATIC} will be stack automatic whenever possible. +Entities marked @code{AUTOMATIC} are stack automatic whenever possible. @code{AUTOMATIC} is the default for local variables smaller than @option{-fmax-stack-var-size}, unless @option{-fno-automatic} is given. This attribute overrides @option{-fno-automatic}, @option{-fmax-stack-var-size}, and @@ -2340,7 +2342,7 @@ compatibility. @node TYPE as an alias for PRINT @subsection @code{TYPE} as an alias for @code{PRINT} @cindex type alias print -For compatibility, GNU Fortran will interpret @code{TYPE} statements as +For compatibility, GNU Fortran interprets @code{TYPE} statements as @code{PRINT} statements with the flag @option{-fdec}. With this flag asserted, the following two examples are equivalent: @@ -2396,12 +2398,12 @@ avoided in new code. Consider: print *, i .AND. j @end smallexample -In this example, compiled with @option{-fdec}, GNU Fortran will -replace the @code{.AND.} operation with a call to the intrinsic +In this example, compiled with @option{-fdec}, GNU Fortran +replaces the @code{.AND.} operation with a call to the intrinsic @code{@ref{IAND}} function, yielding the bitwise-and of @code{i} and @code{j}. -Note that this conversion will occur if at least one operand is of integral -type. As a result, a logical operand will be converted to an integer when the +Note that this conversion occurs if at least one operand is of integral +type. As a result, a logical operand is converted to an integer when the other operand is an integer in a logical operation. In this case, @code{.TRUE.} is converted to @code{1} and @code{.FALSE.} to @code{0}. @@ -2767,7 +2769,8 @@ program main print *,v end program main @end smallexample -which will output the number 18446744073709551583. +@noindent +which outputs the number 18446744073709551583. Arithmetic operations work on unsigned integers, except for exponentiation, which is prohibited. Unary minus is not permitted when @code{-pedantic} @@ -3744,8 +3747,8 @@ int main (int argc, char *argv[]) @table @asis @item @emph{Description}: @code{_gfortran_set_fpe} enables floating point exception traps for -the specified exceptions. On most systems, this will result in a -SIGFPE signal being sent and the program being aborted. +the specified exceptions. On most systems, this results in a +@code{SIGFPE} signal being sent and the program being aborted. @item @emph{Syntax}: @code{void _gfortran_set_fpe (int val)} @@ -4456,7 +4459,7 @@ allocated; for lock types and event types, the number of elements. @item @var{desc} @tab intent(inout) The (pseudo) array descriptor. @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; may be @code{NULL} -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be @code{NULL} @item @var{errmsg_len} @tab the buffer size of errmsg. @end multitable @@ -4507,7 +4510,7 @@ int *stat, char *errmsg, size_t errmsg_len)} pointer components of derived type coarrays. The action only deallocates the local memory without deleting the token. @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL @item @var{errmsg_len} @tab the buffer size of errmsg. @end multitable @@ -4578,7 +4581,7 @@ transferred to the remote image @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when it is known at compile time that the @var{dest} and @var{src} either cannot overlap or overlap (fully or partially) such that walking @var{src} and -@var{dest} in element wise element order (honoring the stride value) will not +@var{dest} in elementwise order (honoring the stride value) does not lead to wrong results. Otherwise, the value is @code{true}. @item @var{stat} @tab intent(out) when non-NULL give the result of the operation, i.e., zero on success and non-zero on error. When NULL and an error @@ -4635,7 +4638,7 @@ triplet of the @var{src} argument. @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when it is known at compile time that the @var{dest} and @var{src} either cannot overlap or overlap (fully or partially) such that walking @var{src} and -@var{dest} in element wise element order (honoring the stride value) will not +@var{dest} in elementwise order (honoring the stride value) does not lead to wrong results. Otherwise, the value is @code{true}. @item @var{stat} @tab intent(out) When non-NULL give the result of the operation, i.e., zero on success and non-zero on error. When NULL and an error @@ -4703,7 +4706,7 @@ be transferred to the remote image @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when it is known at compile time that the @var{dest} and @var{src} either cannot overlap or overlap (fully or partially) such that walking @var{src} and -@var{dest} in element wise element order (honoring the stride value) will not +@var{dest} in elementwise order (honoring the stride value) does not lead to wrong results. Otherwise, the value is @code{true}. @item @var{stat} @tab intent(out) when non-NULL give the result of the operation, i.e., zero on success and non-zero on error. When NULL and an error @@ -4753,10 +4756,10 @@ the data given by src. Guaranteed to have at least one entry. @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when it is known at compile time that the @var{dest} and @var{src} either cannot overlap or overlap (fully or partially) such that walking @var{src} and -@var{dest} in element wise element order (honoring the stride value) will not +@var{dest} in elementwise order (honoring the stride value) does not lead to wrong results. Otherwise, the value is @code{true}. @item @var{dst_reallocatable} @tab intent(in) Set when the destination is of -allocatable or pointer type and the refs will allow reallocation, i.e., the ref +allocatable or pointer type and the refs allow reallocation, i.e., the ref is a full array or component ref. @item @var{stat} @tab intent(out) When non-@code{NULL} give the result of the operation, i.e., zero on success and non-zero on error. When @code{NULL} and @@ -4815,7 +4818,7 @@ and when @var{DST_REALLOCATABLE} allows it. @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when it is known at compile time that the @var{dest} and @var{src} either cannot overlap or overlap (fully or partially) such that walking @var{src} and -@var{dest} in element wise element order (honoring the stride value) will not +@var{dest} in elementwise order (honoring the stride value) does not lead to wrong results. Otherwise, the value is @code{true}. @item @var{dst_reallocatable} @tab intent(in) Set when @var{DST} is of allocatable or pointer type and its refs allow reallocation, i.e., the full @@ -4883,7 +4886,7 @@ structure to get the data. @item @var{may_require_tmp} @tab intent(in) The variable is @code{false} when it is known at compile time that the @var{dest} and @var{src} either cannot overlap or overlap (fully or partially) such that walking @var{src} and -@var{dest} in element wise element order (honoring the stride value) will not +@var{dest} in elementwise order (honoring the stride value) does not lead to wrong results. Otherwise, the value is @code{true}. @item @var{dst_stat} @tab intent(out) when non-@code{NULL} give the result of the send-operation, i.e., zero on success and non-zero on error. When @@ -4948,7 +4951,7 @@ positive number. @item @var{acquired_lock} @tab intent(out) If not NULL, it returns whether lock could be obtained. @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -4982,7 +4985,7 @@ scalars, it is always 0. positive number. @item @var{stat} @tab intent(out) For allocatable coarrays, stores the STAT=; may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -5013,7 +5016,7 @@ scalars, it is always 0. @item @var{image_index} @tab intent(in) The ID of the remote image; must be a positive number; zero indicates the current image, when accessed noncoindexed. @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -5050,7 +5053,7 @@ scalars, it is always 0. @item @var{until_count} @tab intent(in) The number of events which have to be available before the function returns. @item @var{stat} @tab intent(out) Stores the STAT=; may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -5123,7 +5126,7 @@ previous segment have completed. @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -5156,7 +5159,7 @@ the next argument. For a zero-sized array, the value is zero. For @item @var{images} @tab intent(in) An array with the images provided by the user. If @var{count} is zero, a NULL pointer is passed. @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -5179,7 +5182,7 @@ all pending memory operations of this image have been completed. @item @emph{Arguments}: @multitable @columnfractions .15 .70 @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -5408,7 +5411,7 @@ broadcasted (on @var{source_image}) or to be received (other images). @item @var{source_image} @tab intent(in) The ID of the image from which the data should be broadcasted. @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg. @end multitable @@ -5439,7 +5442,7 @@ processed. On the destination image(s) the result overwrites the old content. @item @var{result_image} @tab intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images. @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{a_len} @tab intent(in) the string length of argument @var{a} @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @@ -5476,7 +5479,7 @@ processed. On the destination image(s) the result overwrites the old content. @item @var{result_image} @tab intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images. @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{a_len} @tab intent(in) the string length of argument @var{a} @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @@ -5512,7 +5515,7 @@ processed. On the destination image(s) the result overwrites the old content. @item @var{result_image} @tab intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images. @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg @end multitable @@ -5559,7 +5562,7 @@ processed. On the destination image(s) the result overwrites the old content. @item @var{result_image} @tab intent(in) The ID of the image to which the reduced value should be copied to; if zero, it has to be copied to all images. @item @var{stat} @tab intent(out) Stores the status STAT= and may be NULL. -@item @var{errmsg} @tab intent(out) When an error occurs, this will be set to +@item @var{errmsg} @tab intent(out) When an error occurs, this is set to an error message; may be NULL. @item @var{a_len} @tab intent(in) the string length of argument @var{a} @item @var{errmsg_len} @tab intent(in) the buffer size of errmsg diff --git a/gcc/fortran/invoke.texi b/gcc/fortran/invoke.texi index 14e05e229fe..a8c76b43263 100644 --- a/gcc/fortran/invoke.texi +++ b/gcc/fortran/invoke.texi @@ -238,15 +238,15 @@ This option causes all intrinsic procedures (including the GNU-specific extensions) to be accepted. This can be useful with @option{-std=} to force standard-compliance but get access to the full range of intrinsics available with @command{gfortran}. As a consequence, @option{-Wintrinsics-std} -will be ignored and no user-defined procedure with the same name as any -intrinsic will be called except when it is explicitly declared @code{EXTERNAL}. +is ignored and no user-defined procedure with the same name as any +intrinsic is called except when it is explicitly declared @code{EXTERNAL}. @opindex fallow-argument-mismatch @item -fallow-argument-mismatch Some code contains calls to external procedures with mismatches between the calls and the procedure definition, or with mismatches -between different calls. Such code is non-conforming, and will usually -be flagged with an error. This options degrades the error to a +between different calls. Such code is non-conforming, and is usually +flagged with an error. This options degrades the error to a warning, which can only be disabled by disabling all warnings via @option{-w}. Only a single occurrence per argument is flagged by this warning. @option{-fallow-argument-mismatch} is implied by @@ -371,7 +371,7 @@ unexpanded. @cindex private @item -fmodule-private Set the default accessibility of module entities to @code{PRIVATE}. -Use-associated entities will not be accessible unless they are explicitly +Use-associated entities are not accessible unless they are explicitly declared as @code{PUBLIC}. @opindex ffixed-line-length-@var{n} @@ -487,16 +487,16 @@ region, independent of the specified @code{bind} clause. @opindex frange-check @item -fno-range-check Disable range checking on results of simplification of constant -expressions during compilation. For example, GNU Fortran will give +expressions during compilation. For example, GNU Fortran gives an error at compile time when simplifying @code{a = 1. / 0}. -With this option, no error will be given and @code{a} will be assigned +With this option, no error is given and @code{a} is assigned the value @code{+Infinity}. If an expression evaluates to a value outside of the relevant range of [@code{-HUGE()}:@code{HUGE()}], -then the expression will be replaced by @code{-Inf} or @code{+Inf} +then the expression is replaced by @code{-Inf} or @code{+Inf} as appropriate. -Similarly, @code{DATA i/Z'FFFFFFFF'/} will result in an integer overflow -on most systems, but with @option{-fno-range-check} the value will -``wrap around'' and @code{i} will be initialized to @math{-1} instead. +Similarly, @code{DATA i/Z'FFFFFFFF'/} results in an integer overflow +on most systems, but with @option{-fno-range-check} the value +``wraps around'' and @code{i} is initialized to @math{-1} instead. @opindex fdefault-integer-8 @item -fdefault-integer-8 @@ -550,7 +550,7 @@ from promoting @code{DOUBLE PRECISION} and double real constants like @opindex finteger-4-integer-8 @item -finteger-4-integer-8 Promote all @code{INTEGER(KIND=4)} entities to an @code{INTEGER(KIND=8)} -entities. If @code{KIND=8} is unavailable, then an error will be issued. +entities. If @code{KIND=8} is unavailable, then an error is issued. This option should be used with care and may not be suitable for your codes. Areas of possible concern include calls to external procedures, alignment in @code{EQUIVALENCE} and/or @code{COMMON}, generic interfaces, @@ -572,7 +572,7 @@ representation of the translated Fortran code, produced by @itemx -freal-8-real-10 @itemx -freal-8-real-16 Promote all @code{REAL(KIND=M)} entities to @code{REAL(KIND=N)} entities. -If @code{REAL(KIND=N)} is unavailable, then an error will be issued. +If @code{REAL(KIND=N)} is unavailable, then an error is issued. The @code{-freal-4-} flags also affect the default real kind and the @code{-freal-8-} flags also the double-precision real kind. All other real-kind types are unaffected by this option. The promotion is also @@ -599,7 +599,7 @@ which may be one of @samp{f95}, @samp{f2003}, @samp{f2008}, @samp{f2018}, @samp{f2023}, @samp{gnu}, or @samp{legacy}. The default value for @var{std} is @samp{gnu}, which specifies a superset of the latest Fortran standard that includes all of the extensions supported by GNU -Fortran, although warnings will be given for obsolete extensions not +Fortran, although warnings are given for obsolete extensions not recommended for use in new code. The @samp{legacy} value is equivalent but without the warnings for obsolete extensions, and may be useful for old non-standard programs. The @samp{f95}, @samp{f2003}, @@ -704,7 +704,8 @@ Assuming you have no file @file{foo.f90}, the command @smallexample touch foo.f90; gfortran -cpp -E -dM foo.f90 @end smallexample -will show all the predefined macros. +@noindent +shows all the predefined macros. @opindex dD @cindex preprocessor, debugging @@ -740,11 +741,11 @@ of preprocessing. @opindex fworking-directory @cindex preprocessor, working directory @item -fworking-directory -Enable generation of linemarkers in the preprocessor output that will +Enable generation of linemarkers in the preprocessor output that let the compiler know the current working directory at the time of -preprocessing. When this option is enabled, the preprocessor will emit, +preprocessing. When this option is enabled, the preprocessor emits, after the initial linemarker, a second linemarker with the current -working directory followed by two slashes. GCC will use this directory, +working directory followed by two slashes. GCC uses this directory, when it is present in the preprocessed input, as the directory emitted as the current working directory in some debugging information formats. This option is implicitly enabled if debugging information is enabled, @@ -759,7 +760,7 @@ directives are emitted whatsoever. Search @var{dir} for include files, but do it after all directories specified with @option{-I} and the standard system directories have been exhausted. @var{dir} is treated as a system include directory. -If dir begins with @code{=}, then the @code{=} will be replaced by +If dir begins with @code{=}, then the @code{=} is replaced by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. @opindex imultilib @@ -787,7 +788,7 @@ header files. See the @option{--sysroot} option for more information. Search @var{dir} only for header files requested with @code{#include "file"}; they are not searched for @code{#include <file>}, before all directories specified by @option{-I} and before the standard system directories. If -@var{dir} begins with @code{=}, then the @code{=} will be replaced by the +@var{dir} begins with @code{=}, then the @code{=} is replaced by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. @opindex isystem @@ -797,7 +798,7 @@ Search @var{dir} for header files, after all directories specified by @option{-I} but before the standard system directories. Mark it as a system directory, so that it gets the same special treatment as is applied to the standard system directories. If @var{dir} begins with -@code{=}, then the @code{=} will be replaced by the sysroot prefix; +@code{=}, then the @code{=} is replaced by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. @opindex nostdinc @@ -865,7 +866,7 @@ Predefine name as a macro, with definition @code{1}. @item -D@var{name}=@var{definition} The contents of @var{definition} are tokenized and processed as if they appeared during translation phase three in a @code{'#define'} directive. -In particular, the definition will be truncated by embedded newline +In particular, the definition is truncated by embedded newline characters. If you are invoking the preprocessor from a shell or shell-like program @@ -874,7 +875,7 @@ as spaces that have a meaning in the shell syntax. If you wish to define a function-like macro on the command line, write its argument list with surrounding parentheses before the equals sign -(if any). Parentheses are meaningful to most shells, so you will need +(if any). Parentheses are meaningful to most shells, so you need to quote the option. With sh and csh, @code{-D'name(args...)=definition'} works. @@ -893,7 +894,7 @@ stack it is. @item -P Inhibit generation of linemarkers in the output from the preprocessor. This might be useful when running the preprocessor on something that -is not C code, and will be sent to a program which might be confused +is not C code, and is sent to a program which might be confused by the linemarkers. @opindex U@var{name} @@ -914,9 +915,9 @@ with a @option{-D} option. @cindex suppressing warnings Errors are diagnostic messages that report that the GNU Fortran compiler -cannot compile the relevant piece of source code. The compiler will -continue to process the program in an attempt to report further errors -to aid in debugging, but will not produce any compiled output. +cannot compile the relevant piece of source code. The compiler +continues to process the program in an attempt to report further errors +to aid in debugging, but does not produce any compiled output. Warnings are diagnostic messages that report constructions which are not inherently erroneous but which are risky or suggest there is @@ -946,7 +947,7 @@ messages produced. @cindex syntax checking @item -fsyntax-only Check the code for syntax errors, but do not actually compile it. This -will generate module files for each module present in the code, but no +generates module files for each module present in the code, but no other output file. @opindex pedantic @@ -1000,7 +1001,7 @@ if the same actual argument is associated with a dummy argument with @code{INTENT(IN)} and a dummy argument with @code{INTENT(OUT)} in a call with an explicit interface. -The following example will trigger the warning. +The following example triggers the warning. @smallexample interface subroutine bar(a,b) @@ -1044,12 +1045,12 @@ intrinsic @code{ISO_C_Binding} module. This option is implied by @opindex Wcharacter-truncation @cindex warnings, character truncation @item -Wcharacter-truncation -Warn when a character assignment will truncate the assigned string. +Warn when a character assignment truncates the assigned string. @opindex Wline-truncation @cindex warnings, line truncation @item -Wline-truncation -Warn when a source code line will be truncated. This option is +Warn when a source code line is truncated. This option is implied by @option{-Wall}. For free-form source code, the default is @option{-Werror=line-truncation} such that truncations are reported as error. @@ -1117,7 +1118,7 @@ regardless of the selected standard. @cindex warnings, overwrite recursive @item -Wno-overwrite-recursive Do not warn when @option{-fno-automatic} is used with @option{-frecursive}. Recursion -will be broken if the relevant local variables do not have the attribute +is broken if the relevant local variables do not have the attribute @code{AUTOMATIC} explicitly declared. This option can be used to suppress the warning when it is known that recursion is not broken. Useful for build environments that use @option{-Werror}. @@ -1168,7 +1169,7 @@ used in free-form source code, is diagnosed by default.) @item -Wtabs By default, tabs are accepted as whitespace, but tabs are not members of the Fortran Character Set. For continuation lines, a tab followed -by a digit between 1 and 9 is supported. @option{-Wtabs} will cause a +by a digit between 1 and 9 is supported. @option{-Wtabs} causes a warning to be issued if a tab is encountered. Note, @option{-Wtabs} is active for @option{-pedantic}, @option{-std=f95}, @option{-std=f2003}, @option{-std=f2008}, @option{-std=f2018}, @option{-std=f2023} and @@ -1249,7 +1250,7 @@ hot loops, the Fortran 2003 reallocation feature may reduce the performance. If the array is already allocated with the correct shape, consider using a whole-array array-spec (e.g. @code{(:,:,:)}) for the variable on the left-hand side to prevent the reallocation check. Note that in some cases the warning -is shown, even if the compiler will optimize reallocation checks away. For +is shown, even if the compiler optimizes reallocation checks away. For instance, when the right-hand side contains the same variable multiplied by a scalar. See also @option{-frealloc-lhs}. @@ -1323,7 +1324,7 @@ program by using @code{-g} or @code{-ggdb3}. @item -ffpe-trap=@var{list} Specify a list of floating point exception traps to enable. On most systems, if a floating point exception occurs and the trap for that -exception is enabled, a SIGFPE signal will be sent and the program +exception is enabled, a @code{SIGFPE} signal is sent and the program being aborted, producing a core file useful for debugging. @var{list} is a (possibly empty) comma-separated list of either @samp{none} (to clear the set of exceptions to be trapped), or of the following @@ -1342,8 +1343,8 @@ The first three exceptions (@samp{invalid}, @samp{zero}, and has provisions for dealing with these exceptions, enabling traps for these three exceptions is probably a good idea. -If the option is used more than once in the command line, the lists will -be joined: '@code{ffpe-trap=}@var{list1} @code{ffpe-trap=}@var{list2}' +If the option is used more than once in the command line, the lists are +joined: '@code{ffpe-trap=}@var{list1} @code{ffpe-trap=}@var{list2}' is equivalent to @code{ffpe-trap=}@var{list1},@var{list2}. Note that once enabled an exception cannot be disabled (no negative form), @@ -1365,7 +1366,7 @@ of the following exceptions: @samp{invalid}, @samp{zero}, @samp{overflow}, @option{-ffpe-trap} for a description of the exceptions.) If the option is used more than once in the command line, only the -last one will be used. +last one is used. By default, a summary for all exceptions but @samp{inexact} is shown. @@ -1582,6 +1583,7 @@ as auxiliary output files, as specified described under GCC gfortran -save-temps -c foo.F90 @end smallexample +@noindent preprocesses input file @file{foo.F90} to @file{foo.fii}, compiles to an intermediate @file{foo.s}, and then assembles to the (implied) output file @file{foo.o}, whereas: @@ -1590,6 +1592,7 @@ file @file{foo.o}, whereas: gfortran -save-temps -S foo.F @end smallexample +@noindent saves the preprocessor output in @file{foo.fi}, and then compiles to the (implied) output file @file{foo.s}. @@ -1656,7 +1659,7 @@ calling conventions as, calling @code{COMPLEX} or default @code{REAL} functions between program parts which were compiled with different calling conventions will break at execution time. -@emph{Caution:} This will break code which passes intrinsic functions +@emph{Caution:} This breaks code which passes intrinsic functions of type default @code{REAL} or @code{COMPLEX} as actual arguments, as the library implementations use the @option{-fno-f2c} calling conventions. @@ -1720,7 +1723,7 @@ cannot detect disagreements in these other areas. Also, note that with @option{-fno-underscoring}, the lack of appended underscores introduces the very real possibility that a user-defined -external name will conflict with a name in a system library, which +external name conflicts with a name in a system library, which could make finding unresolved-reference bugs quite difficult in some cases---they might occur at program run time, and show up only as buggy behavior at run time. @@ -1760,7 +1763,7 @@ in effect. It is implied by the @option{-ff2c} option. @table @asis @item @samp{none} Disable coarray support; using coarray declarations and image-control -statements will produce a compile-time error. (Default) +statements produces a compile-time error. (Default) @item @samp{single} Single-image mode, i.e. @code{num_images()} is always one. @@ -1827,7 +1830,7 @@ iteration variables. @item @samp{mem} Enable generation of run-time checks for memory allocation. Note: This option does not affect explicit allocations using the -@code{ALLOCATE} statement, which will be always checked. +@code{ALLOCATE} statement, which are always checked. @item @samp{pointer} Enable generation of run-time checks for pointers and allocatables. @@ -1843,7 +1846,8 @@ Example: Assuming you have a file @file{foo.f90}, the command @smallexample gfortran -fcheck=all,no-array-temps foo.f90 @end smallexample -will compile the file with all checks enabled as specified above except +@noindent +compiles the file with all checks enabled as specified above except warnings for generated array temporaries. @@ -1913,7 +1917,7 @@ The default value for @var{n} is 65535. @opindex fmax-stack-var-size @item -fmax-stack-var-size=@var{n} -This option specifies the size in bytes of the largest array that will be put +This option specifies the size in bytes of the largest array that is put on the stack; if the size is exceeded static memory is used (except in procedures marked as @code{RECURSIVE}). Use the option @option{-frecursive} to @@ -1929,9 +1933,9 @@ The default value for @var{n} is 65536. @opindex fstack-arrays @item -fstack-arrays -Adding this option will make the Fortran compiler put all arrays of +Adding this option makes the Fortran compiler put all arrays of unknown size and array temporaries onto stack memory. If your program uses very -large local arrays it is possible that you will have to extend your runtime +large local arrays it is possible that you have to extend your runtime limits for stack memory on some operating systems. This flag is enabled by default at optimization level @option{-Ofast} unless @option{-fmax-stack-var-size} is specified. @@ -1958,9 +1962,9 @@ is noncontiguous. @opindex fshort-enums @item -fshort-enums This option is provided for interoperability with C code that was -compiled with the @option{-fshort-enums} option. It will make +compiled with the @option{-fshort-enums} option. It makes GNU Fortran choose the smallest @code{INTEGER} kind a given -enumerator set will fit in, and give all its enumerators this kind. +enumerator set fits in, and give all its enumerators this kind. @opindex finline-arg-packing @item -finline-arg-packing @@ -1979,7 +1983,7 @@ the call to @code{foo} in end subroutine bar @end smallexample -When @option{-finline-arg-packing} is in effect, this packing will be +When @option{-finline-arg-packing} is in effect, this packing is performed by inline code. This allows for more optimization while increasing code size. @@ -1992,18 +1996,18 @@ can be found by using @option{-Warray-temporaries}. @opindex fexternal-blas @item -fexternal-blas -This option will make @command{gfortran} generate calls to BLAS functions +This option makes @command{gfortran} generate calls to BLAS functions for some matrix operations like @code{MATMUL}, instead of using our own algorithms, if the size of the matrices involved is larger than a given limit (see @option{-fblas-matmul-limit}). This may be profitable if an -optimized vendor BLAS library is available. The BLAS library will have +optimized vendor BLAS library is available. The BLAS library has to be specified at link time. @opindex fblas-matmul-limit @item -fblas-matmul-limit=@var{n} Only significant when @option{-fexternal-blas} is in effect. Matrix multiplication of matrices with size larger than (or equal to) @var{n} -will be performed by calls to BLAS functions, while others will be +is performed by calls to BLAS functions, while others are handled by @command{gfortran} internal algorithms. If the matrices involved are not square, the size comparison is performed using the geometric mean of the dimensions of the argument and result matrices. @@ -2041,11 +2045,11 @@ unconditionally for numeric rank-1 array argument @code{A}. @opindex finline-matmul-limit @item -finline-matmul-limit=@var{n} When front-end optimization is active, some calls to the @code{MATMUL} -intrinsic function will be inlined. This may result in code size +intrinsic function are inlined. This may result in code size increase if the size of the matrix cannot be determined at compile time, as code for both cases is generated. Setting -@code{-finline-matmul-limit=0} will disable inlining in all cases. -Setting this option with a value of @var{n} will produce inline code +@code{-finline-matmul-limit=0} disables inlining in all cases. +Setting this option with a value of @var{n} produces inline code for matrices with size up to @var{n}. If the matrices involved are not square, the size comparison is performed using the geometric mean of the dimensions of the argument and result matrices. @@ -2083,9 +2087,9 @@ the real and imaginary parts of local @code{COMPLEX} variables), @option{-finit-character=@var{n}} (where @var{n} is an ASCII character value) options. -With @option{-finit-derived}, components of derived type variables will be +With @option{-finit-derived}, components of derived type variables are initialized according to these flags. Components whose type is not covered by -an explicit @option{-finit-*} flag will be treated as described above with +an explicit @option{-finit-*} flag are treated as described above with @option{-finit-local-zero}. These options do not initialize @@ -2105,13 +2109,13 @@ use @option{-finit-real=snan}; note, however, that compile-time optimizations may convert them into quiet NaN and that trapping needs to be enabled (e.g. via @option{-ffpe-trap}). -The @option{-finit-integer} option will parse the value into an +The @option{-finit-integer} option parses the value into an integer of type @code{INTEGER(kind=C_LONG)} on the host. Said value is then assigned to the integer variables in the Fortran code, which might result in wraparound if the value is too large for the kind. -Finally, note that enabling any of the @option{-finit-*} options will -silence warnings that would have been emitted by @option{-Wuninitialized} +Finally, note that enabling any of the @option{-finit-*} options +silences warnings that would have been emitted by @option{-Wuninitialized} for the affected local variables. @opindex falign-commons @@ -2154,7 +2158,8 @@ statements, regardless of whether these functions are marked @smallexample a = f(b,c) + f(b,c) @end smallexample -there will only be a single call to @code{f}. This option only works +@noindent +there is only a single call to @code{f}. This option only works if @option{-ffrontend-optimize} is in effect. @opindex frontend-optimize @@ -2197,7 +2202,7 @@ shared by @command{gfortran}, @command{gcc}, and other GNU compilers. @opindex c-prototypes @cindex Generating C prototypes from Fortran BIND(C) enteties @item -fc-prototypes -This option will generate C prototypes from @code{BIND(C)} variable +This option generates C prototypes from @code{BIND(C)} variable declarations, types and procedure interfaces and writes them to standard output. @code{ENUM} is not yet supported. @@ -2213,16 +2218,17 @@ Example of use: @smallexample $ gfortran -fc-prototypes -fsyntax-only foo.f90 > foo.h @end smallexample +@noindent where the C code intended for interoperating with the Fortran code -then uses @code{#include "foo.h"}. +then uses @code{#include "foo.h"}. @opindex c-prototypes-external @cindex Generating C prototypes from external procedures @item -fc-prototypes-external -This option will generate C prototypes from external functions and -subroutines and write them to standard output. This may be useful for +This option generates C prototypes from external functions and +subroutines and writes them to standard output. This may be useful for making sure that C bindings to Fortran code are correct. This option -does not generate prototypes for @code{BIND(C)} procedures, use +does not generate prototypes for @code{BIND(C)} procedures; use @option{-fc-prototypes} for that. The generated prototypes may need inclusion of an appropriate @@ -2232,15 +2238,16 @@ This is primarily meant for legacy code to ensure that existing C bindings match what @command{gfortran} emits. The generated C prototypes should be correct for the current version of the compiler, but may not match what other compilers or earlier versions of -@command{gfortran} need. For new developments, use of the +@command{gfortran} need. For new development, use of the @code{BIND(C)} features is recommended. Example of use: @smallexample $ gfortran -fc-prototypes-external -fsyntax-only foo.f > foo.h @end smallexample +@noindent where the C code intended for interoperating with the Fortran code -then uses @code{#include "foo.h"}. +then uses @code{#include "foo.h"}. @end table @node Environment Variables -- 2.25.1