@ignore
-Copyright (C) 2005, 2006, 2007, 2008
+Copyright (C) 2005, 2006, 2007, 2008, 2009
Free Software Foundation, Inc.
This is part of the GNU Fortran manual.
For copying conditions, see the file gfortran.texi.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
-Invariant Sections being ``GNU General Public License'' and ``Funding
-Free Software'', the Front-Cover texts being (a) (see below), and with
-the Back-Cover Texts being (b) (see below). A copy of the license is
-included in the gfdl(7) man page.
+Invariant Sections being ``Funding Free Software'', the Front-Cover
+Texts being (a) (see below), and with the Back-Cover Texts being (b)
+(see below). A copy of the license is included in the gfdl(7) man page.
Some basic guidelines for editing this document:
* @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
* @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
* @code{C_LOC}: C_LOC, Obtain the C address of an object
+* @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
* @code{CEILING}: CEILING, Integer ceiling function
* @code{CHAR}: CHAR, Integer-to-character conversion function
* @code{CHDIR}: CHDIR, Change working directory
* @code{KILL}: KILL, Send a signal to a process
* @code{KIND}: KIND, Kind of an entity
* @code{LBOUND}: LBOUND, Lower dimension bounds of an array
+* @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
* @code{LEN}: LEN, Length of a character entity
* @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
-* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
* @code{LGE}: LGE, Lexical greater than or equal
* @code{LGT}: LGT, Lexical greater than
* @code{LINK}: LINK, Create a hard link
* @code{LOC}: LOC, Returns the address of a variable
* @code{LOG}: LOG, Logarithm function
* @code{LOG10}: LOG10, Base 10 logarithm function
+* @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
* @code{LOGICAL}: LOGICAL, Convert to logical type
* @code{LONG}: LONG, Convert to integer type
* @code{LSHIFT}: LSHIFT, Left shift bits
* @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
* @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
* @code{RAND}: RAND, Real pseudo-random number
-* @code{RANGE}: RANGE, Decimal exponent range of a real kind
+* @code{RANGE}: RANGE, Decimal exponent range
* @code{RAN}: RAN, Real pseudo-random number
* @code{REAL}: REAL, Convert to real type
* @code{RENAME}: RENAME, Rename a file
* @code{TIME}: TIME, Time function
* @code{TIME8}: TIME8, Time function (64-bit)
* @code{TINY}: TINY, Smallest positive number of a real kind
+* @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
* @code{TRANSFER}: TRANSFER, Transfer bit patterns
* @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
* @code{TRIM}: TRIM, Remove trailing blank characters of a string
@table @asis
@item @emph{Description}:
@code{ABORT} causes immediate termination of the program. On operating
-systems that support a core dump, @code{ABORT} will produce a core dump,
-which is suitable for debugging purposes.
+systems that support a core dump, @code{ABORT} will produce a core dump even if
+the option @option{-fno-dump-core} is in effect, which is suitable for debugging
+purposes.
+@c TODO: Check if this (with -fno-dump-core) is correct.
@item @emph{Standard}:
GNU extension
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} with a magnitude that is
-less than one.
+less than or equal to one.
@end multitable
@item @emph{Return value}:
Spaces are inserted at the end of the string as needed.
@item @emph{Standard}:
-Fortran 95 and later
+Fortran 90 and later
@item @emph{Class}:
Elemental function
@multitable @columnfractions .15 .70
@item @var{A} @tab The type of the argument shall be @code{REAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
program test_allocated
integer :: i = 4
real(4), allocatable :: x(:)
- if (allocated(x) .eqv. .false.) allocate(x(i))
+ if (.not. allocated(x)) allocate(x(i))
end program test_allocated
@end smallexample
@end table
@multitable @columnfractions .15 .70
@item @var{A} @tab The type of the argument shall be @code{REAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}, and a magnitude that is
-less than one.
+less than or equal to one.
@end multitable
@item @emph{Return value}:
@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name @tab Argument @tab Return type @tab Standard
-@item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
+@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X}, @code{REAL(8) Y} @tab @code{REAL(8)} @tab Fortran 77 and later
@end multitable
@end table
@node BESSEL_J1
-@section @code{BESEL_J1} --- Bessel function of the first kind of order 1
+@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
@fnindex BESSEL_J1
@fnindex BESJ1
@fnindex DBESJ1
@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
-@item Name @tab Argument @tab Return type @tab Standard
-@item @code{DBESJN(X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
-@item @tab @code{REAL(8) X} @tab @tab
+@item Name @tab Argument @tab Return type @tab Standard
+@item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
+@item @tab @code{REAL(8) X} @tab @tab
@end multitable
@end table
@table @asis
@item @emph{Description}:
@code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
-represented by the type of @var{I}.
+represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
+independent of the actual value of @var{I}.
@item @emph{Standard}:
Fortran 95 and later
@table @asis
@item @emph{Description}:
@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
-in @var{I} is set.
+in @var{I} is set. The counting of the bits starts at 0.
@item @emph{Standard}:
Fortran 95 and later
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
- @code{INTENT(IN)}.
+@code{INTENT(IN)}.
@item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
- @code{INTENT(OUT)}.
+@code{INTENT(OUT)}.
@end multitable
@item @emph{Example}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
- @code{INTENT(IN)}.
+@code{INTENT(IN)}.
@item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
- @code{INTENT(OUT)}.
+@code{INTENT(OUT)}.
@item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
- with @code{INTENT(IN)}. It shall be present
- if and only if @var{fptr} is an array. The size
- must be equal to the rank of @var{fptr}.
+with @code{INTENT(IN)}. It shall be present
+if and only if @var{fptr} is an array. The size
+must be equal to the rank of @var{fptr}.
@end multitable
@item @emph{Example}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab Associated scalar pointer or interoperable scalar
- or allocated allocatable variable with @code{TARGET}
- attribute.
+or allocated allocatable variable with @code{TARGET} attribute.
@end multitable
@item @emph{Return value}:
@end table
+@node C_SIZEOF
+@section @code{C_SIZEOF} --- Size in bytes of an expression
+@fnindex C_SIZEOF
+@cindex expression size
+@cindex size of an expression
+
+@table @asis
+@item @emph{Description}:
+@code{C_SIZEOF(X)} calculates the number of bytes of storage the
+expression @code{X} occupies.
+
+@item @emph{Standard}:
+Fortran 2008
+
+@item @emph{Class}:
+Intrinsic function
+
+@item @emph{Syntax}:
+@code{N = C_SIZEOF(X)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{X} @tab The argument shall be of any type, rank or shape.
+@end multitable
+
+@item @emph{Return value}:
+The return value is of type integer and of the system-dependent kind
+@var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
+number of bytes occupied by the argument. If the argument has the
+@code{POINTER} attribute, the number of bytes of the storage area pointed
+to is returned. If the argument is of a derived type with @code{POINTER}
+or @code{ALLOCATABLE} components, the return value doesn't account for
+the sizes of the data pointed to by these components.
+
+@item @emph{Example}:
+@smallexample
+ use iso_c_binding
+ integer(c_int) :: i
+ real(c_float) :: r, s(5)
+ print *, (c_sizeof(s)/c_sizeof(r) == 5)
+ end
+@end smallexample
+The example will print @code{.TRUE.} unless you are using a platform
+where default @code{REAL} variables are unusually padded.
+
+@item @emph{See also}:
+@ref{SIZEOF}
+@end table
+
+
@node CEILING
@section @code{CEILING} --- Integer ceiling function
@fnindex CEILING
@multitable @columnfractions .15 .70
@item @var{A} @tab The type shall be @code{REAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{NAME} @tab The type shall be @code{CHARACTER} of default
- kind and shall specify a valid path within the
- file system.
+kind and shall specify a valid path within the file system.
@item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
- kind. Returns 0 on success, and a system specific
- and nonzero error code otherwise.
+kind. Returns 0 on success, and a system specific and nonzero error code
+otherwise.
@end multitable
@item @emph{Example}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
- or @code{COMPLEX}.
+or @code{COMPLEX}.
@item @var{Y} @tab (Optional; only allowed if @var{X} is not
- @code{COMPLEX}.) May be @code{INTEGER}
- or @code{REAL}.
+@code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@end multitable
@item @emph{Return value}:
-The return value is of type @code{INTEGER(4)}
+The return value is an @code{INTEGER} of default kind.
@item @emph{Example}:
@smallexample
@item @emph{Return value}:
The return value is of type @code{REAL} and it is positive
-(@math{ \cosh (x) \geq 0 }. The return value is of the same
-kind as @var{X}.
+(@math{ \cosh (x) \geq 0 }). For a @code{REAL} argument @var{X},
+@math{ \cosh (x) \geq 1 }.
+The return value is of the same kind as @var{X}.
@item @emph{Example}:
@smallexample
@code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
-omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
+omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
@code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
is the rank of @var{MASK}.
@item @var{MASK} @tab The type shall be @code{LOGICAL}.
@item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Description}:
@code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
@var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
-taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
+taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
by @var{SHIFT} places. If rank is greater than one, then all complete rank one
@multitable @columnfractions .15 .70
@item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
@item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
- of default kind.
+of default kind.
@end multitable
@item @emph{Return value}:
@item @tab @code{VALUE(6)}: @tab The minutes of the hour
@item @tab @code{VALUE(7)}: @tab The seconds of the minute
@item @tab @code{VALUE(8)}: @tab The milliseconds of the second
-@end multitable
+@end multitable
@item @emph{Standard}:
Fortran 95 and later
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
- or larger, and of default kind.
+or larger, and of default kind.
@item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
- or larger, and of default kind.
+or larger, and of default kind.
@item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
- or larger, and of default kind.
+or larger, and of default kind.
@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
- or @code{COMPLEX}.
+or @code{COMPLEX}.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
- or @code{COMPLEX}.
+or @code{COMPLEX}.
@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
- @code{INTEGER} or @code{REAL}.
+@code{INTEGER} or @code{REAL}.
@end multitable
@item @emph{Return value}:
@node DIGITS
-@section @code{DIGITS} --- Significant digits function
+@section @code{DIGITS} --- Significant binary digits function
@fnindex DIGITS
@cindex model representation, significant digits
@table @asis
@item @emph{Description}:
-@code{DIGITS(X)} returns the number of significant digits of the internal model
-representation of @var{X}. For example, on a system using a 32-bit
+@code{DIGITS(X)} returns the number of significant binary digits of the internal
+model representation of @var{X}. For example, on a system using a 32-bit
floating point representation, a default real number would likely return 24.
@item @emph{Standard}:
@end multitable
@item @emph{Return value}:
-If the arguments are numeric, the return value is a scaler of numeric type,
+If the arguments are numeric, the return value is a scalar of numeric type,
@code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
@code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
@table @asis
@item @emph{Description}:
-@code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
-since the start of the process's execution in @var{RESULT}. @var{TARRAY}
-returns the user and system components of this time in @code{TARRAY(1)} and
-@code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
-TARRAY(2)}.
+@code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
+since the start of the process's execution in @var{TIME}. @var{VALUES}
+returns the user and system components of this time in @code{VALUES(1)} and
+@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
+VALUES(2)}.
Subsequent invocations of @code{DTIME} return values accumulated since the
previous invocation.
This intrinsic is provided in both subroutine and function forms; however,
only one form can be used in any given program unit.
-@var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
+@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
@multitable @columnfractions .15 .30 .40
-@item @tab @code{TARRAY(1)}: @tab User time in seconds.
-@item @tab @code{TARRAY(2)}: @tab System time in seconds.
-@item @tab @code{RESULT}: @tab Run time since start in seconds.
+@item @tab @code{VALUES(1)}: @tab User time in seconds.
+@item @tab @code{VALUES(2)}: @tab System time in seconds.
+@item @tab @code{TIME}: @tab Run time since start in seconds.
@end multitable
@item @emph{Standard}:
@item @emph{Syntax}:
@multitable @columnfractions .80
-@item @code{CALL DTIME(TARRAY, RESULT)}.
-@item @code{RESULT = DTIME(TARRAY)}, (not recommended).
+@item @code{CALL DTIME(VALUES, TIME)}.
+@item @code{TIME = DTIME(VALUES)}, (not recommended).
@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
-@item @var{RESULT}@tab The type shall be @code{REAL}.
+@item @var{VALUES}@tab The type shall be @code{REAL, DIMENSION(2)}.
+@item @var{TIME}@tab The type shall be @code{REAL}.
@end multitable
@item @emph{Return value}:
@item @emph{Description}:
@code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
-omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
+omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
@code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
@var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{ARRAY} @tab May be any type, not scaler.
+@item @var{ARRAY} @tab May be any type, not scalar.
@item @var{SHIFT} @tab The type shall be @code{INTEGER}.
@item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
@item @var{DIM} @tab The type shall be @code{INTEGER}.
@table @asis
@item @emph{Description}:
-@code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
+@code{EPSILON(X)} returns the smallest number @var{E} of the same kind
+as @var{X} such that @math{1 + E > 1}.
@item @emph{Standard}:
Fortran 95 and later
@table @asis
@item @emph{Description}:
-@code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
-since the start of the process's execution in @var{RESULT}. @var{TARRAY}
-returns the user and system components of this time in @code{TARRAY(1)} and
-@code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
+@code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
+since the start of the process's execution in @var{TIME}. @var{VALUES}
+returns the user and system components of this time in @code{VALUES(1)} and
+@code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
On some systems, the underlying timings are represented using types with
sufficiently small limits that overflows (wrap around) are possible, such as
This intrinsic is provided in both subroutine and function forms; however,
only one form can be used in any given program unit.
-@var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
+@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
@multitable @columnfractions .15 .30 .60
-@item @tab @code{TARRAY(1)}: @tab User time in seconds.
-@item @tab @code{TARRAY(2)}: @tab System time in seconds.
-@item @tab @code{RESULT}: @tab Run time since start in seconds.
+@item @tab @code{VALUES(1)}: @tab User time in seconds.
+@item @tab @code{VALUES(2)}: @tab System time in seconds.
+@item @tab @code{TIME}: @tab Run time since start in seconds.
@end multitable
@item @emph{Standard}:
@item @emph{Syntax}:
@multitable @columnfractions .80
-@item @code{CALL ETIME(TARRAY, RESULT)}.
-@item @code{RESULT = ETIME(TARRAY)}, (not recommended).
+@item @code{CALL ETIME(VALUES, TIME)}.
+@item @code{TIME = ETIME(VALUES)}, (not recommended).
@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
-@item @var{RESULT}@tab The type shall be @code{REAL}.
+@item @var{VALUES}@tab The type shall be @code{REAL, DIMENSION(2)}.
+@item @var{TIME}@tab The type shall be @code{REAL}.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C} @tab The type shall be @code{CHARACTER} and of default
- kind.
+kind.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
- Returns 0 on success, -1 on end-of-file, and a
- system specific positive error code otherwise.
+Returns 0 on success, -1 on end-of-file, and a system specific positive
+error code otherwise.
@end multitable
@item @emph{Example}:
@multitable @columnfractions .15 .70
@item @var{UNIT} @tab The type shall be @code{INTEGER}.
@item @var{C} @tab The type shall be @code{CHARACTER} and of default
- kind.
+kind.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
- Returns 0 on success, -1 on end-of-file and a
- system specific positive error code otherwise.
+Returns 0 on success, -1 on end-of-file and a system specific positive
+error code otherwise.
@end multitable
@item @emph{Example}:
@multitable @columnfractions .15 .70
@item @var{A} @tab The type shall be @code{REAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C} @tab The type shall be @code{CHARACTER} and of default
- kind.
+kind.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
- Returns 0 on success, -1 on end-of-file and a
- system specific positive error code otherwise.
+Returns 0 on success, -1 on end-of-file and a system specific positive
+error code otherwise.
@end multitable
@item @emph{Example}:
@multitable @columnfractions .15 .70
@item @var{UNIT} @tab The type shall be @code{INTEGER}.
@item @var{C} @tab The type shall be @code{CHARACTER} and of default
- kind.
+kind.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
- Returns 0 on success, -1 on end-of-file and a
- system specific positive error code otherwise.
+Returns 0 on success, -1 on end-of-file and a system specific positive
+error code otherwise.
@end multitable
@item @emph{Example}:
@code{FSTAT} is identical to @ref{STAT}, except that information about an
already opened file is obtained.
-The elements in @code{BUFF} are the same as described by @ref{STAT}.
+The elements in @code{VALUES} are the same as described by @ref{STAT}.
This intrinsic is provided in both subroutine and function forms; however,
only one form can be used in any given program unit.
Subroutine, function
@item @emph{Syntax}:
-@code{CALL FSTAT(UNIT, BUFF [, STATUS])}
+@code{CALL FSTAT(UNIT, VALUES [, STATUS])}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
-@item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
+@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
- on success and a system specific error code otherwise.
+on success and a system specific error code otherwise.
@end multitable
@item @emph{Example}:
Subroutine
@item @emph{Syntax}:
-@code{CALL GET_COMMAND(COMMAND)}
+@code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{COMMAND} @tab Shall be of type @code{CHARACTER} and of default
-kind.
+@item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
+of default kind.
+@item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
+default kind.
+@item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
+default kind.
@end multitable
@item @emph{Return value}:
-Stores the entire command line that was used to invoke the program in
-@var{COMMAND}. If @var{COMMAND} is not large enough, the command will be
-truncated.
+If @var{COMMAND} is present, stores the entire command line that was used
+to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
+assigned the length of the command line. If @var{STATUS} is present, it
+is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
+short to store the command line, or a positive value in case of an error.
@item @emph{Example}:
@smallexample
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER(4)},
- @math{@var{NUMBER} \geq 0}
+@item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
+default kind, @math{@var{NUMBER} \geq 0}
@item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
- and of default kind.
-@item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
-@item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
+and of default kind.
+@item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
+and of default kind.
+@item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
+and of default kind.
@end multitable
@item @emph{Return value}:
@var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
arguments specified at the command line, @var{VALUE} will be filled with blanks.
-If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on systems
-that support this feature). The @var{LENGTH} argument contains the length of the
-@var{NUMBER}-th command line argument. If the argument retrival fails, @var{STATUS}
-is a positiv number; if @var{VALUE} contains a truncated command line argument,
-@var{STATUS} is -1; and otherwise the @var{STATUS} is zero.
+If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
+systems that support this feature). The @var{LENGTH} argument contains the
+length of the @var{NUMBER}-th command line argument. If the argument retrieval
+fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
+command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
+zero.
@item @emph{Example}:
@smallexample
@multitable @columnfractions .15 .70
@item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
- a system specific and nonzero error code otherwise.
+a system specific and nonzero error code otherwise.
@end multitable
@item @emph{Example}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER(1)}.
-@item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER(1)}.
-@item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER(4)}.
-@item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER(4)}.
-@item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL(4)}.
+@item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
+and of default kind.
+@item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
+and of default kind.
+@item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
+and of default kind.
+@item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
+and of default kind.
+@item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
+and of default kind.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{TIME} @tab An @code{INTEGER} scalar expression
- corresponding to a system time, with
- @code{INTENT(IN)}.
+corresponding to a system time, with @code{INTENT(IN)}.
@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
- with @code{INTENT(OUT)}.
+with @code{INTENT(OUT)}.
@end multitable
@item @emph{Return value}:
The elements of @var{VALUES} are assigned as follows:
@enumerate
@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
- seconds
+seconds
@item Minutes after the hour, range 0--59
@item Hours past midnight, range 0--23
@item Day of month, range 0--31
@item Number of days since Sunday, range 0--6
@item Days since January 1
@item Daylight savings indicator: positive if daylight savings is in
- effect, zero if not, and negative if the information is not
- available.
+effect, zero if not, and negative if the information is not available.
@end enumerate
@item @emph{See also}:
@multitable @columnfractions .15 .70
@item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
- Returns 0 on success, or a system specific error
- code otherwise.
+Returns 0 on success, or a system specific error code otherwise.
@end multitable
@item @emph{Return value}:
@multitable @columnfractions .15 .70
@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@multitable @columnfractions .15 .70
@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@table @asis
@item @emph{Description}:
-@code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
+@code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
current local time. The day (in the range 1-31), month (in the range 1-12),
-and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
+and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
The year has four significant digits.
@item @emph{Standard}:
@end multitable
@item @emph{Return value}:
-Does not return.
+Does not return anything.
@item @emph{Example}:
@smallexample
@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
@code{INTENT(IN)}
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be of type @code{INTEGER},
- @code{REAL}, or @code{COMPLEX}.
+@code{REAL}, or @code{COMPLEX}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be of type @code{INTEGER},
- @code{REAL}, or @code{COMPLEX}.
+@code{REAL}, or @code{COMPLEX}.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be of type @code{INTEGER},
- @code{REAL}, or @code{COMPLEX}.
+@code{REAL}, or @code{COMPLEX}.
@end multitable
@item @emph{Return value}:
@end multitable
@item @emph{Return value}:
-Does not return.
+Does not return anything.
@item @emph{Example}:
@item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
@code{INTENT(IN)}
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
- @code{INTEGER(8)}. Returns 0 on success, or a
- system-specific error code otherwise.
+@code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
+otherwise.
@end multitable
@item @emph{See also}:
@item @var{ARRAY} @tab Shall be an array, of any type.
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
+@node LEADZ
+@section @code{LEADZ} --- Number of leading zero bits of an integer
+@fnindex LEADZ
+@cindex zero bits
+
+@table @asis
+@item @emph{Description}:
+@code{LEADZ} returns the number of leading zero bits of an integer.
+
+@item @emph{Standard}:
+Fortran 2008 and later
+
+@item @emph{Class}:
+Elemental function
+
+@item @emph{Syntax}:
+@code{RESULT = LEADZ(I)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{I} @tab Shall be of type @code{INTEGER}.
+@end multitable
+
+@item @emph{Return value}:
+The type of the return value is the default @code{INTEGER}.
+If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
+
+@item @emph{Example}:
+@smallexample
+PROGRAM test_leadz
+ WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
+END PROGRAM
+@end smallexample
+
+@item @emph{See also}:
+@ref{BIT_SIZE}, @ref{TRAILZ}
+@end table
+
+
+
@node LEN
@section @code{LEN} --- Length of a character entity
@fnindex LEN
@item @var{STRING} @tab Shall be a scalar or array of type
@code{CHARACTER}, with @code{INTENT(IN)}
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
with @code{INTENT(IN)}
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Return value}:
The return value is of type @code{REAL} or @code{COMPLEX}.
The kind type parameter is the same as @var{X}.
+If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
+@math{-\pi \leq \omega \leq \pi}.
@item @emph{Example}:
@smallexample
@multitable @columnfractions .15 .70
@item @var{L} @tab The type shall be @code{LOGICAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be of type @code{INTEGER},
- @code{REAL}, or @code{COMPLEX}.
+@code{REAL}, or @code{COMPLEX}.
@end multitable
@item @emph{Return value}:
@table @asis
@item @emph{Description}:
-@code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
-then the link itself is statted, not the file that it refers to.
+@code{LSTAT} is identical to @ref{STAT}, except that if path is a
+symbolic link, then the link itself is statted, not the file that it
+refers to.
-The elements in @code{BUFF} are the same as described by @ref{STAT}.
+The elements in @code{VALUES} are the same as described by @ref{STAT}.
-This intrinsic is provided in both subroutine and function forms; however,
-only one form can be used in any given program unit.
+This intrinsic is provided in both subroutine and function forms;
+however, only one form can be used in any given program unit.
@item @emph{Standard}:
GNU extension
Subroutine, function
@item @emph{Syntax}:
-@code{CALL LSTAT(FILE, BUFF [, STATUS])}
+@code{CALL LSTAT(NAME, VALUES [, STATUS])}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{FILE} @tab The type shall be @code{CHARACTER} of the default
+@item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
kind, a valid path within the file system.
-@item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
+@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
Returns 0 on success and a system specific error code otherwise.
@end multitable
@table @asis
@item @emph{Description}:
-Given a system time value @var{STIME} (as provided by the @code{TIME8()}
-intrinsic), fills @var{TARRAY} with values extracted from it appropriate
+Given a system time value @var{TIME} (as provided by the @code{TIME8()}
+intrinsic), fills @var{VALUES} with values extracted from it appropriate
to the local time zone using @code{localtime(3)}.
@item @emph{Standard}:
Subroutine
@item @emph{Syntax}:
-@code{CALL LTIME(STIME, TARRAY)}
+@code{CALL LTIME(TIME, VALUES)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{STIME} @tab An @code{INTEGER} scalar expression
- corresponding to a system time, with
- @code{INTENT(IN)}.
-@item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
- with @code{INTENT(OUT)}.
+@item @var{TIME} @tab An @code{INTEGER} scalar expression
+corresponding to a system time, with @code{INTENT(IN)}.
+@item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
+with @code{INTENT(OUT)}.
@end multitable
@item @emph{Return value}:
-The elements of @var{TARRAY} are assigned as follows:
+The elements of @var{VALUES} are assigned as follows:
@enumerate
@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
- seconds
+seconds
@item Minutes after the hour, range 0--59
@item Hours past midnight, range 0--23
@item Day of month, range 0--31
@item Number of days since Sunday, range 0--6
@item Days since January 1
@item Daylight savings indicator: positive if daylight savings is in
- effect, zero if not, and negative if the information is not
- available.
+effect, zero if not, and negative if the information is not available.
@end enumerate
@item @emph{See also}:
@item @emph{Example}:
The following example demonstrates the use of @code{MALLOC} and
-@code{FREE} with Cray pointers. This example is intended to run on
-32-bit systems, where the default integer kind is suitable to store
-pointers; on 64-bit systems, ptr_x would need to be declared as
-@code{integer(kind=8)}.
+@code{FREE} with Cray pointers.
@smallexample
program test_malloc
+ implicit none
integer i
- integer ptr_x
real*8 x(*), z
pointer(ptr_x,x)
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MATRIX_A} @tab An array of @code{INTEGER},
- @code{REAL}, @code{COMPLEX}, or
- @code{LOGICAL} type, with a rank of
- one or two.
+@code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
+one or two.
@item @var{MATRIX_B} @tab An array of @code{INTEGER},
- @code{REAL}, or @code{COMPLEX} type if
- @var{MATRIX_A} is of a numeric type;
- otherwise, an array of @code{LOGICAL}
- type. The rank shall be one or two, and the
- first (or only) dimension of @var{MATRIX_B}
- shall be equal to the last (or only)
- dimension of @var{MATRIX_A}.
+@code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
+type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
+or two, and the first (or only) dimension of @var{MATRIX_B} shall be
+equal to the last (or only) dimension of @var{MATRIX_A}.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A1} @tab The type shall be @code{INTEGER} or
- @code{REAL}.
+@code{REAL}.
@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
- as @var{A1}. (As a GNU extension,
- arguments of different kinds are
- permitted.)
+as @var{A1}. (As a GNU extension, arguments of different kinds are
+permitted.)
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
- @code{REAL}, or @code{CHARACTER}.
+@code{REAL}, or @code{CHARACTER}.
@item @var{DIM} @tab (Optional) Shall be a scalar of type
- @code{INTEGER}, with a value between one
- and the rank of @var{ARRAY}, inclusive. It
- may not be an optional dummy argument.
+@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
+inclusive. It may not be an optional dummy argument.
@item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
- and conformable with @var{ARRAY}.
+and conformable with @var{ARRAY}.
@end multitable
@item @emph{Return value}:
each row of the array in the @var{DIM} direction. If @var{MASK} is
present, only the elements for which @var{MASK} is @code{.TRUE.} are
considered. If the array has zero size, or all of the elements of
-@var{MASK} are @code{.FALSE.}, then the result is the most negative
-number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
-a string of nulls if @var{ARRAY} is of character type.
+@var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
+if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
+type.
@item @emph{Standard}:
Fortran 95 and later
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
- @code{REAL}, or @code{CHARACTER}.
+@code{REAL}, or @code{CHARACTER}.
@item @var{DIM} @tab (Optional) Shall be a scalar of type
- @code{INTEGER}, with a value between one
- and the rank of @var{ARRAY}, inclusive. It
- may not be an optional dummy argument.
+@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
+inclusive. It may not be an optional dummy argument.
@item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
- and conformable with @var{ARRAY}.
+and conformable with @var{ARRAY}.
@end multitable
@item @emph{Return value}:
@multitable @columnfractions .15 .70
@item @var{TSOURCE} @tab May be of any type.
@item @var{FSOURCE} @tab Shall be of the same type and type parameters
- as @var{TSOURCE}.
+as @var{TSOURCE}.
@item @var{MASK} @tab Shall be of type @code{LOGICAL}.
@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A1} @tab The type shall be @code{INTEGER} or
- @code{REAL}.
+@code{REAL}.
@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
- as @var{A1}. (As a GNU extension,
- arguments of different kinds are
- permitted.)
+as @var{A1}. (As a GNU extension, arguments of different kinds are
+permitted.)
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
- @code{REAL}, or @code{CHARACTER}.
+@code{REAL}, or @code{CHARACTER}.
@item @var{DIM} @tab (Optional) Shall be a scalar of type
- @code{INTEGER}, with a value between one
- and the rank of @var{ARRAY}, inclusive. It
- may not be an optional dummy argument.
+@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
+inclusive. It may not be an optional dummy argument.
@item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
- and conformable with @var{ARRAY}.
+and conformable with @var{ARRAY}.
@end multitable
@item @emph{Return value}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
- @code{REAL}, or @code{CHARACTER}.
+@code{REAL}, or @code{CHARACTER}.
@item @var{DIM} @tab (Optional) Shall be a scalar of type
- @code{INTEGER}, with a value between one
- and the rank of @var{ARRAY}, inclusive. It
- may not be an optional dummy argument.
+@code{INTEGER}, with a value between one and the rank of @var{ARRAY},
+inclusive. It may not be an optional dummy argument.
@item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
- and conformable with @var{ARRAY}.
+and conformable with @var{ARRAY}.
@end multitable
@item @emph{Return value}:
@table @asis
@item @emph{Description}:
-@code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
-@var{DEST}. @var{SRC} will become deallocated in the process.
+@code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
+@var{TO}. @var{FROM} will become deallocated in the process.
@item @emph{Standard}:
Fortran 2003 and later
Subroutine
@item @emph{Syntax}:
-@code{CALL MOVE_ALLOC(SRC, DEST)}
+@code{CALL MOVE_ALLOC(FROM, TO)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
- of any type and kind.
-@item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
- of the same type, kind and rank as @var{SRC}
+@item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
+of any type and kind.
+@item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
+of the same type, kind and rank as @var{FROM}.
@end multitable
@item @emph{Return value}:
@item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
@item @var{LEN} @tab The type shall be @code{INTEGER}.
@item @var{TO} @tab The type shall be @code{INTEGER}, of the
- same kind as @var{FROM}.
+same kind as @var{FROM}.
@item @var{TOPOS} @tab The type shall be @code{INTEGER}.
@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C} @tab The argument shall be a scalar or array of the
- type @code{CHARACTER}.
+type @code{CHARACTER}.
@end multitable
@item @emph{Return value}:
@table @asis
@item @emph{Description}:
-@code{NINT(X)} rounds its argument to the nearest whole number.
+@code{NINT(A)} rounds its argument to the nearest whole number.
@item @emph{Standard}:
Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
Elemental function
@item @emph{Syntax}:
-@code{RESULT = NINT(X [, KIND])}
+@code{RESULT = NINT(A [, KIND])}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{X} @tab The type of the argument shall be @code{REAL}.
+@item @var{A} @tab The type of the argument shall be @code{REAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
Function
@item @emph{Syntax}:
-@code{RESULT = OR(X, Y)}
+@code{RESULT = OR(I, J)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be either a scalar @code{INTEGER}
+@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
type or a scalar @code{LOGICAL} type.
-@item @var{Y} @tab The type shall be the same as the type of @var{X}.
+@item @var{J} @tab The type shall be the same as the type of @var{J}.
@end multitable
@item @emph{Return value}:
Transformational function
@item @emph{Syntax}:
-@code{RESULT = PRODUCT(ARRAY[, MASK])}
-@code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
+@multitable @columnfractions .80
+@item @code{RESULT = PRODUCT(ARRAY[, MASK])}
+@item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
+@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
Function
@item @emph{Syntax}:
-@code{RESULT = RAND(FLAG)}
+@code{RESULT = RAND(I)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
+@item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
@end multitable
@item @emph{Return value}:
Subroutine
@item @emph{Syntax}:
-@code{CALL RANDOM_SEED(SIZE, PUT, GET)}
+@code{CALL RANDOM_SEED([SIZE, PUT, GET])}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@node RANGE
-@section @code{RANGE} --- Decimal exponent range of a real kind
+@section @code{RANGE} --- Decimal exponent range
@fnindex RANGE
@cindex model representation, range
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
+@item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
+or @code{COMPLEX}.
@end multitable
@item @emph{Return value}:
@table @asis
@item @emph{Description}:
-@code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
-@code{REALPART(X)} function is provided for compatibility with @command{g77},
+@code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
+@code{REALPART} function is provided for compatibility with @command{g77},
and its use is strongly discouraged.
@item @emph{Standard}:
@item @emph{Syntax}:
@multitable @columnfractions .80
-@item @code{RESULT = REAL(X [, KIND])}
+@item @code{RESULT = REAL(A [, KIND])}
@item @code{RESULT = REALPART(Z)}
@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be @code{INTEGER}, @code{REAL}, or
- @code{COMPLEX}.
+@item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
+@code{COMPLEX}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@table @asis
@item (A)
-@code{REAL(X)} is converted to a default real type if @var{X} is an
+@code{REAL(A)} is converted to a default real type if @var{A} is an
integer or real variable.
@item (B)
-@code{REAL(X)} is converted to a real type with the kind type parameter
-of @var{X} if @var{X} is a complex variable.
+@code{REAL(A)} is converted to a real type with the kind type parameter
+of @var{A} if @var{A} is a complex variable.
@item (C)
-@code{REAL(X, KIND)} is converted to a real type with kind type
-parameter @var{KIND} if @var{X} is a complex, integer, or real
+@code{REAL(A, KIND)} is converted to a real type with kind type
+parameter @var{KIND} if @var{A} is a complex, integer, or real
variable.
@end table
@item @var{SET} @tab Shall be of type @code{CHARACTER}.
@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@table @asis
@item @emph{Description}:
-@code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
-type that can represent all values ranging from @math{-10^I} (exclusive)
-to @math{10^I} (exclusive). If there is no integer kind that accommodates
+@code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
+type that can represent all values ranging from @math{-10^R} (exclusive)
+to @math{10^R} (exclusive). If there is no integer kind that accommodates
this range, @code{SELECTED_INT_KIND} returns @math{-1}.
@item @emph{Standard}:
Transformational function
@item @emph{Syntax}:
-@code{RESULT = SELECTED_INT_KIND(I)}
+@code{RESULT = SELECTED_INT_KIND(R)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
+@item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
@end multitable
@item @emph{Example}:
@table @asis
@item @emph{Description}:
-@code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
-with decimal precision greater of at least @code{P} digits and exponent
+@code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
+with decimal precision of at least @code{P} digits and exponent
range greater at least @code{R}.
@item @emph{Standard}:
Transformational function
@item @emph{Syntax}:
-@code{RESULT = SELECTED_REAL_KIND(P, R)}
+@code{RESULT = SELECTED_REAL_KIND([P, R])}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
integer. It has @code{INTENT(OUT)}.
@end multitable
+@c TODO: What should the interface of the handler be? Does it take arguments?
@item @emph{Return value}:
The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
and its value shall be in the range from 1 to n, where n equals the rank
of @var{ARRAY}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@end smallexample
The example will print @code{.TRUE.} unless you are using a platform
where default @code{REAL} variables are unusually padded.
+
+@item @emph{See also}:
+@ref{C_SIZEOF}
@end table
+
@node SLEEP
@section @code{SLEEP} --- Sleep for the specified number of seconds
@fnindex SLEEP
@end multitable
@item @emph{Return value}:
-Does not return.
+Does not return anything.
@item @emph{Example}:
See @code{RAND} and @code{IRAND} for examples.
the file itself, but execute (search) permission is required on all of the
directories in path that lead to the file.
-The elements that are obtained and stored in the array @code{BUFF}:
+The elements that are obtained and stored in the array @code{VALUES}:
@multitable @columnfractions .15 .70
-@item @code{buff(1)} @tab Device ID
-@item @code{buff(2)} @tab Inode number
-@item @code{buff(3)} @tab File mode
-@item @code{buff(4)} @tab Number of links
-@item @code{buff(5)} @tab Owner's uid
-@item @code{buff(6)} @tab Owner's gid
-@item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
-@item @code{buff(8)} @tab File size (bytes)
-@item @code{buff(9)} @tab Last access time
-@item @code{buff(10)} @tab Last modification time
-@item @code{buff(11)} @tab Last file status change time
-@item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
-@item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
+@item @code{VALUES(1)} @tab Device ID
+@item @code{VALUES(2)} @tab Inode number
+@item @code{VALUES(3)} @tab File mode
+@item @code{VALUES(4)} @tab Number of links
+@item @code{VALUES(5)} @tab Owner's uid
+@item @code{VALUES(6)} @tab Owner's gid
+@item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
+@item @code{VALUES(8)} @tab File size (bytes)
+@item @code{VALUES(9)} @tab Last access time
+@item @code{VALUES(10)} @tab Last modification time
+@item @code{VALUES(11)} @tab Last file status change time
+@item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
+@item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
@end multitable
Not all these elements are relevant on all systems.
Subroutine, function
@item @emph{Syntax}:
-@code{CALL STAT(FILE,BUFF[,STATUS])}
+@code{CALL STAT(NAME, VALUES [, STATUS])}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{FILE} @tab The type shall be @code{CHARACTER}, of the
+@item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
default kind and a valid path within the file system.
-@item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
+@item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
- on success and a system specific error code otherwise.
+on success and a system specific error code otherwise.
@end multitable
@item @emph{Example}:
Transformational function
@item @emph{Syntax}:
-@code{RESULT = SUM(ARRAY[, MASK])}
-@code{RESULT = SUM(ARRAY, DIM[, MASK])}
+@multitable @columnfractions .80
+@item @code{RESULT = SUM(ARRAY[, MASK])}
+@item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
+@end multitable
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
+@node TRAILZ
+@section @code{TRAILZ} --- Number of trailing zero bits of an integer
+@fnindex TRAILZ
+@cindex zero bits
+
+@table @asis
+@item @emph{Description}:
+@code{TRAILZ} returns the number of trailing zero bits of an integer.
+
+@item @emph{Standard}:
+Fortran 2008 and later
+
+@item @emph{Class}:
+Elemental function
+
+@item @emph{Syntax}:
+@code{RESULT = TRAILZ(I)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{I} @tab Shall be of type @code{INTEGER}.
+@end multitable
+
+@item @emph{Return value}:
+The type of the return value is the default @code{INTEGER}.
+If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
+
+@item @emph{Example}:
+@smallexample
+PROGRAM test_trailz
+ WRITE (*,*) TRAILZ(8) ! prints 3
+END PROGRAM
+@end smallexample
+
+@item @emph{See also}:
+@ref{BIT_SIZE}, @ref{LEADZ}
+@end table
+
+
+
@node TRANSFER
@section @code{TRANSFER} --- Transfer bit patterns
@fnindex TRANSFER
@item @var{ARRAY} @tab Shall be an array, of any type.
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
@item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
@table @asis
@item @emph{Description}:
-Sets the file creation mask to @var{MASK} and returns the old value in
-argument @var{OLD} if it is supplied. See @code{umask(2)}.
+Sets the file creation mask to @var{MASK}. If called as a function, it
+returns the old value. If called as a subroutine and argument @var{OLD}
+if it is supplied, it is set to the old value. See @code{umask(2)}.
@item @emph{Standard}:
GNU extension
@item @emph{Class}:
-Subroutine
+Subroutine, function
@item @emph{Syntax}:
@code{CALL UMASK(MASK [, OLD])}
+@code{OLD = UMASK(MASK)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
-@item @var{MASK} @tab (Optional) Shall be a scalar of type
- @code{INTEGER}.
+@item @var{OLD} @tab (Optional) Shall be a scalar of type
+@code{INTEGER}.
@end multitable
@end table
@item @var{SET} @tab Shall be of type @code{CHARACTER}.
@item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
@item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
- expression indicating the kind parameter of
- the result.
+expression indicating the kind parameter of the result.
@end multitable
@item @emph{Return value}:
Function
@item @emph{Syntax}:
-@code{RESULT = XOR(X, Y)}
+@code{RESULT = XOR(I, J)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{X} @tab The type shall be either a scalar @code{INTEGER}
+@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
type or a scalar @code{LOGICAL} type.
-@item @var{Y} @tab The type shall be the same as the type of @var{I}.
+@item @var{J} @tab The type shall be the same as the type of @var{I}.
@end multitable
@item @emph{Return value}:
@chapter Intrinsic Modules
@cindex intrinsic Modules
-@c @node ISO_FORTRAN_ENV
+@menu
+* ISO_FORTRAN_ENV::
+* ISO_C_BINDING::
+* OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
+@end menu
+
+@node ISO_FORTRAN_ENV
@section @code{ISO_FORTRAN_ENV}
@table @asis
@item @emph{Standard}:
Identifies the preconnected unit identified by the asterisk
(@code{*}) in @code{READ} statement.
+@item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}
+Kind type parameters to specify an INTEGER type with a storage
+size of 16, 32, and 64 bits. It is negative if a target platform
+does not support the particular kind.
+
@item @code{IOSTAT_END}:
The value assigned to the variable passed to the IOSTAT= specifier of
an input/output statement if an end-of-file condition occurred.
@item @code{OUTPUT_UNIT}:
Identifies the preconnected unit identified by the asterisk
(@code{*}) in @code{WRITE} statement.
+
+@item @code{REAL32}, @code{REAL64}, @code{REAL128}
+Kind type parameters to specify a REAL type with a storage
+size of 32, 64, and 128 bits. It is negative if a target platform
+does not support the particular kind.
@end table
-@c @node ISO_C_BINDING
+
+
+@node ISO_C_BINDING
@section @code{ISO_C_BINDING}
@table @asis
@item @emph{Standard}:
@item @code{C_FUNLOC}
@item @code{C_LOC}
@end table
+@c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
+@c don't really know why.
-The @code{ISO_C_BINDING} module provides the following named constants of the
-type integer, which can be used as KIND type parameter. Note that GNU
-Fortran currently does not support the @code{C_INT_FAST...} KIND type
-parameters (marked by an asterisk (@code{*}) in the list below).
-The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
-and cannot be used as KIND type parameter of the @code{INTEGER} type.
+The @code{ISO_C_BINDING} module provides the following named constants of
+type default integer, which can be used as KIND type parameters.
In addition to the integer named constants required by the Fortran 2003
standard, GNU Fortran provides as an extension named constants for the
@item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
@item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
@item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
-@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
+@item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
@item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
@item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
@item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
@item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
-@item @code{INTEGER}@tab @code{C_INT_LEAST128_T} @tab @code{int_least128_t} @tab Ext.
-@item @code{INTEGER}@tab @code{C_INT_FAST8_T}* @tab @code{int_fast8_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
-@item @code{INTEGER}@tab @code{C_INT_FAST128_T}* @tab @code{int_fast128_t} @tab Ext.
+@item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
+@item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
+@item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
+@item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
+@item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
+@item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
@item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
@item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
@item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
@item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
@end multitable
-Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
+Additionally, the following @code{(CHARACTER(KIND=C_CHAR))} are
defined.
@multitable @columnfractions .20 .45 .15
@item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
@end multitable
-@c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
+@node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
@section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
@table @asis
@item @emph{Standard}:
-OpenMP Application Program Interface v2.5
+OpenMP Application Program Interface v3.0
@end table
below.
For details refer to the actual
-@uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
-OpenMP Application Program Interface v2.5}.
+@uref{http://www.openmp.org/mp-documents/spec30.pdf,
+OpenMP Application Program Interface v3.0}.
@code{OMP_LIB_KINDS} provides the following scalar default-integer
named constants:
@item @code{omp_logical_kind}
@item @code{omp_lock_kind}
@item @code{omp_nest_lock_kind}
+@item @code{omp_sched_kind}
@end table