@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{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}:
@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
@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}:
@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.}.
@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
@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}:
@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{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}:
@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}
+@math{@var{NUMBER} \geq 0}
@item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
- and of default kind.
+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)}.
@end multitable
@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{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}:
@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}:
@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)}.
+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)}.
+with @code{INTENT(OUT)}.
@end multitable
@item @emph{Return value}:
The elements of @var{TARRAY} 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}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
- of any type and kind.
+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}
+of the same type, kind and rank as @var{SRC}.
@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}:
@multitable @columnfractions .15 .70
@item @var{X} @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}:
@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}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab Shall be @code{INTEGER}, @code{REAL}, or
- @code{COMPLEX}.
+@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 @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_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}:
@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.
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{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}:
+@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}:
@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}.
+@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}:
@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
@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
@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