@chapter Intrinsic Procedures
@cindex intrinsic procedures
-@comment Missing intrinsics (double check with #19292)
-@comment - MClock
-@comment - Short
-
@menu
* Introduction: Introduction to Intrinsics
* @code{ABORT}: ABORT, Abort the program
* @code{IERRNO}: IERRNO, Function to get the last system error number
* @code{INDEX}: INDEX, Position of a substring within a string
* @code{INT}: INT, Convert to integer type
+* @code{INT2}: INT2, Convert to 16-bit integer type
+* @code{INT8}: INT8, Convert to 64-bit integer type
* @code{IOR}: IOR, Bitwise logical or
* @code{IRAND}: IRAND, Integer pseudo-random number
* @code{ISATTY}: ISATTY, Whether a unit is a terminal device
* @code{LOG}: LOG, Logarithm function
* @code{LOG10}: LOG10, Base 10 logarithm function
* @code{LOGICAL}: LOGICAL, Convert to logical type
+* @code{LONG}: LONG, Convert to integer type
* @code{LSHIFT}: LSHIFT, Left shift bits
* @code{LSTAT}: LSTAT, Get file status
* @code{LTIME}: LTIME, Convert time to local time info
* @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
* @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
* @code{MAXVAL}: MAXVAL, Maximum value of an array
+* @code{MCLOCK}: MCLOCK, Time function
+* @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
* @code{MERGE}: MERGE, Merge arrays
* @code{MIN}: MIN, Minimum value of an argument list
* @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
* @code{SCALE}: SCALE, Scale a real value
* @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
* @code{SECNDS}: SECNDS, Time function
-@comment * @code{SECOND}: SECOND, (?)
-@comment * @code{SECONDS}: SECONDS, (?)
+* @code{SECOND}: SECOND, CPU time function
* @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
* @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
* @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
@end table
+
@node ABS
@section @code{ABS} --- Absolute value
@cindex @code{ABS} intrinsic
@end table
+
@node ACCESS
@section @code{ACCESS} --- Checks file access modes
@cindex @code{ACCESS}
@end table
+
@node ACHAR
@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
@cindex @code{ACHAR} intrinsic
@end table
+
@node ACOSH
@section @code{ACOSH} --- Hyperbolic arccosine function
@cindex @code{ACOSH} intrinsic
+@cindex @code{DACOSH} intrinsic
@cindex hyperbolic arccosine
@cindex hyperbolic cosine (inverse)
@table @asis
@item @emph{Description}:
-@code{ACOSH(X)} computes the area hyperbolic cosine of @var{X} (inverse of @code{COSH(X)}).
+@code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
+@code{COSH(X)}).
@item @emph{Standard}:
GNU extension
END PROGRAM
@end smallexample
+@item @emph{Specific names}:
+@multitable @columnfractions .20 .20 .20 .25
+@item Name @tab Argument @tab Return type @tab Standard
+@item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
+@end multitable
+
@item @emph{See also}:
Inverse function: @ref{COSH}
@end table
@end table
+
@node AND
@section @code{AND} --- Bitwise logical AND
@cindex @code{AND} intrinsic
@end table
+
@node ASINH
@section @code{ASINH} --- Hyperbolic arcsine function
@cindex @code{ASINH} intrinsic
+@cindex @code{DASINH} intrinsic
@cindex hyperbolic arcsine
@cindex hyperbolic sine (inverse)
@table @asis
@item @emph{Description}:
-@code{ASINH(X)} computes the area hyperbolic sine of @var{X} (inverse of @code{SINH(X)}).
+@code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
@item @emph{Standard}:
GNU extension
END PROGRAM
@end smallexample
+@item @emph{Specific names}:
+@multitable @columnfractions .20 .20 .20 .25
+@item Name @tab Argument @tab Return type @tab Standard
+@item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
+@end multitable
+
@item @emph{See also}:
Inverse function: @ref{SINH}
@end table
@table @asis
@item @emph{Description}:
-@code{ATAN2(Y,X)} computes the arctangent of the complex number @math{X + i Y}.
+@code{ATAN2(Y,X)} computes the arctangent of the complex number
+@math{X + i Y}.
@item @emph{Standard}:
F77 and later
@node ATANH
@section @code{ATANH} --- Hyperbolic arctangent function
@cindex @code{ASINH} intrinsic
+@cindex @code{DASINH} intrinsic
@cindex hyperbolic arctangent
@cindex hyperbolic tangent (inverse)
@table @asis
@item @emph{Description}:
-@code{ATANH(X)} computes the area hyperbolic sine of @var{X} (inverse of @code{TANH(X)}).
+@code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
+of @code{TANH(X)}).
@item @emph{Standard}:
GNU extension
END PROGRAM
@end smallexample
+@item @emph{Specific names}:
+@multitable @columnfractions .20 .20 .20 .25
+@item Name @tab Argument @tab Return type @tab Standard
+@item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
+@end multitable
+
@item @emph{See also}:
Inverse function: @ref{TANH}
@end table
-
@node BESJ0
@section @code{BESJ0} --- Bessel function of the first kind of order 0
@cindex @code{BESJ0} intrinsic
@end table
+
@node CHDIR
@section @code{CHDIR} --- Change working directory
@cindex @code{CHDIR} intrinsic
@end table
+
@node CMPLX
@section @code{CMPLX} --- Complex conversion function
@cindex @code{CMPLX} intrinsic
@ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
@end table
+
+
@node CONJG
@section @code{CONJG} --- Complex conjugate function
@cindex @code{CONJG} intrinsic
@section @code{COS} --- Cosine function
@cindex @code{COS} intrinsic
@cindex @code{DCOS} intrinsic
+@cindex @code{CCOS} intrinsic
@cindex @code{ZCOS} intrinsic
@cindex @code{CDCOS} intrinsic
@cindex trigonometric functions
@table @asis
@item @emph{Description}:
-Returns a @code{REAL} value representing the elapsed CPU time in seconds. This
-is useful for testing segments of code to determine execution time.
+Returns a @code{REAL(*)} value representing the elapsed CPU time in
+seconds. This is useful for testing segments of code to determine
+execution time.
@item @emph{Standard}:
F95 and later
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
+@item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
@end multitable
@item @emph{Return value}:
@end table
+
@node CTIME
@section @code{CTIME} --- Convert a time into a string
@cindex @code{CTIME} intrinsic
@section @code{EXP} --- Exponential function
@cindex @code{EXP} intrinsic
@cindex @code{DEXP} intrinsic
+@cindex @code{CEXP} intrinsic
@cindex @code{ZEXP} intrinsic
@cindex @code{CDEXP} intrinsic
@cindex exponential
@end table
+
@node FDATE
@section @code{FDATE} --- Get the current time as a string
@cindex @code{FDATE} intrinsic
@end smallexample
@end table
+
+
@node FLOAT
@section @code{FLOAT} --- Convert integer to default real
@end table
+
@node FGETC
@section @code{FGETC} --- Read a single character in stream mode
@cindex @code{FGETC} intrinsic
@end table
+
@node IAND
@section @code{IAND} --- Bitwise logical and
@cindex @code{IAND} intrinsic
Elemental function
@item @emph{Syntax}:
-@item @code{RESULT = INT(X [, KIND))}
+@code{RESULT = INT(A [, KIND))}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item @var{X} @tab Shall be of type @code{INTEGER(*)},
+@item @var{A} @tab Shall be of type @code{INTEGER(*)},
@code{REAL(*)}, or @code{COMPLEX(*)}.
@item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
expression indicating the kind parameter of
@table @asis
@item (A)
-If @var{X} is of type @code{INTEGER(*)}, @code{INT(X) = X}
+If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
@item (B)
-If @var{X} is of type @code{REAL(*)} and @math{|X| < 1}, @code{INT(X)} equals @var{0}.
-If @math{|X| \geq 1}, then @code{INT(X)} equals the largest integer that does not exceed
-the range of @var{X} and whose sign is the same as the sign of @var{X}.
+If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
+If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
+the range of @var{A} and whose sign is the same as the sign of @var{A}.
@item (C)
-If @var{X} is of type @code{COMPLEX(*)}, rule B is applied to the real part of X.
+If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
@end table
@item @emph{Example}:
@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name @tab Argument @tab Return type @tab Standard
-@item @code{IFIX(X)} @tab @code{REAL(4) X} @tab @code{INTEGER} @tab F77 and later
-@item @code{IDINT(X)} @tab @code{REAL(8) X} @tab @code{INTEGER} @tab F77 and later
+@item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
+@item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
@end multitable
@comment @item @emph{See also}:
+@node INT2
+@section @code{INT2} --- Convert to 16-bit integer type
+@cindex @code{INT2} intrinsic
+@cindex @code{SHORT} intrinsic
+@cindex conversion function (integer)
+
+@table @asis
+@item @emph{Description}:
+Convert to a @code{KIND=2} integer type. This is equivalent to the
+standard @code{INT} intrinsic with an optional argument of
+@code{KIND=2}, and is only included for backwards compatibility.
+
+The @code{SHORT} intrinsic is equivalent to @code{INT2}.
+
+@item @emph{Standard}:
+GNU extension.
+
+@item @emph{Class}:
+Elemental function
+
+@item @emph{Syntax}:
+@code{RESULT = INT2(A)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{A} @tab Shall be of type @code{INTEGER(*)},
+ @code{REAL(*)}, or @code{COMPLEX(*)}.
+@end multitable
+
+@item @emph{Return value}:
+The return value is a @code{INTEGER(2)} variable.
+
+@comment @item @emph{See also}:
+@ref{INT}, @ref{INT8}, @ref{LONG}
+@end table
+
+
+
+@node INT8
+@section @code{INT8} --- Convert to 64-bit integer type
+@cindex @code{INT8} intrinsic
+@cindex conversion function (integer)
+
+@table @asis
+@item @emph{Description}:
+Convert to a @code{KIND=8} integer type. This is equivalent to the
+standard @code{INT} intrinsic with an optional argument of
+@code{KIND=8}, and is only included for backwards compatibility.
+
+@item @emph{Standard}:
+GNU extension.
+
+@item @emph{Class}:
+Elemental function
+
+@item @emph{Syntax}:
+@code{RESULT = INT8(A)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{A} @tab Shall be of type @code{INTEGER(*)},
+ @code{REAL(*)}, or @code{COMPLEX(*)}.
+@end multitable
+
+@item @emph{Return value}:
+The return value is a @code{INTEGER(8)} variable.
+
+@comment @item @emph{See also}:
+@ref{INT}, @ref{INT2}, @ref{LONG}
+@end table
+
+
+
@node IOR
@section @code{IOR} --- Bitwise logical or
@cindex @code{IOR} intrinsic
-
@node IRAND
@section @code{IRAND} --- Integer pseudo-random number
@cindex @code{IRAND} intrinsic
-
@node ISHFT
@section @code{ISHFT} --- Shift bits
@cindex @code{ISHFT} intrinsic
-
@node ISHFTC
@section @code{ISHFTC} --- Shift bits circularly
@cindex @code{ISHFTC} intrinsic
+@node LONG
+@section @code{LONG} --- Convert to integer type
+@cindex @code{LONG} intrinsic
+@cindex conversion function (integer)
+
+@table @asis
+@item @emph{Description}:
+Convert to a @code{KIND=4} integer type, which is the same size as a C
+@code{long} integer. This is equivalent to the standard @code{INT}
+intrinsic with an optional argument of @code{KIND=4}, and is only
+included for backwards compatibility.
+
+@item @emph{Standard}:
+GNU extension.
+
+@item @emph{Class}:
+Elemental function
+
+@item @emph{Syntax}:
+@code{RESULT = LONG(A)}
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{A} @tab Shall be of type @code{INTEGER(*)},
+ @code{REAL(*)}, or @code{COMPLEX(*)}.
+@end multitable
+
+@item @emph{Return value}:
+The return value is a @code{INTEGER(4)} variable.
+
+@comment @item @emph{See also}:
+@ref{INT}, @ref{INT2}, @ref{INT8}
+@end table
+
+
@node LSHIFT
@section @code{LSHIFT} --- Left shift bits
@end table
+
@node LSTAT
@section @code{LSTAT} --- Get file status
@cindex @code{LSTAT} intrinsic
@node MAX
@section @code{MAX} --- Maximum value of an argument list
@cindex @code{MAX} intrinsic
+@cindex @code{MAX0} intrinsic
+@cindex @code{AMAX0} intrinsic
+@cindex @code{MAX1} intrinsic
+@cindex @code{AMAX1} intrinsic
+@cindex @code{DMAX1} intrinsic
@table @asis
@item @emph{Description}:
+@node MCLOCK
+@section @code{MCLOCK} --- Time function
+@cindex @code{MCLOCK} intrinsic
+@cindex time, clock ticks
+@cindex clock ticks
+
+@table @asis
+@item @emph{Description}:
+Returns the number of clock ticks since the start of the process, based
+on the UNIX function @code{clock(3)}.
+
+This intrinsic is not fully portable, such as to systems with 32-bit
+@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
+the values returned by this intrinsic might be, or become, negative, or
+numerically less than previous values, during a single run of the
+compiled program.
+
+@item @emph{Standard}:
+GNU extension
+
+@item @emph{Class}:
+Non-elemental function
+
+@item @emph{Syntax}:
+@code{RESULT = MCLOCK()}
+
+@item @emph{Return value}:
+The return value is a scalar of type @code{INTEGER(4)}, equal to the
+number of clock ticks since the start of the process, or @code{-1} if
+the system does not support @code{clock(3)}.
+
+@item @emph{See also}:
+@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
+
+@end table
+
+
+
+@node MCLOCK8
+@section @code{MCLOCK8} --- Time function (64-bit)
+@cindex @code{MCLOCK8} intrinsic
+@cindex time, current
+@cindex current time
+
+@table @asis
+@item @emph{Description}:
+Returns the number of clock ticks since the start of the process, based
+on the UNIX function @code{clock(3)}.
+
+@emph{Warning:} this intrinsic does not increase the range of the timing
+values over that returned by @code{clock(3)}. On a system with a 32-bit
+@code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
+it is converted to a 64-bit @code{INTEGER(8)} value. That means
+overflows of the 32-bit value can still occur. Therefore, the values
+returned by this intrinsic might be or become negative or numerically
+less than previous values during a single run of the compiled program.
+
+@item @emph{Standard}:
+GNU extension
+
+@item @emph{Class}:
+Non-elemental function
+
+@item @emph{Syntax}:
+@code{RESULT = MCLOCK8()}
+
+@item @emph{Return value}:
+The return value is a scalar of type @code{INTEGER(8)}, equal to the
+number of clock ticks since the start of the process, or @code{-1} if
+the system does not support @code{clock(3)}.
+
+@item @emph{See also}:
+@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
+
+@end table
+
+
+
@node MERGE
@section @code{MERGE} --- Merge variables
@cindex @code{MERGE} intrinsic
@node MIN
@section @code{MIN} --- Minimum value of an argument list
@cindex @code{MIN} intrinsic
+@cindex @code{MIN0} intrinsic
+@cindex @code{AMIN0} intrinsic
+@cindex @code{MIN1} intrinsic
+@cindex @code{AMIN1} intrinsic
+@cindex @code{DMIN1} intrinsic
@table @asis
@item @emph{Description}:
@ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
@end table
+
+
@node MINEXPONENT
@section @code{MINEXPONENT} --- Minimum exponent of a real kind
@cindex @code{MINEXPONENT} intrinsic
@end table
+
@node NOT
@section @code{NOT} --- Logical negation
@cindex @code{NOT} intrinsic
-
@node NULL
@section @code{NULL} --- Function that returns an disassociated pointer
@cindex @code{NULL} intrinsic
-
@node OR
@section @code{OR} --- Bitwise logical OR
@cindex @code{OR} intrinsic
-
@node PACK
@section @code{PACK} --- Pack an array into an array of rank one
@cindex @code{PACK} intrinsic
-
@node RESHAPE
@section @code{RESHAPE} --- Function to reshape an array
@cindex @code{RESHAPE} intrinsic
@end table
+
@node SCAN
@section @code{SCAN} --- Scan a string for the presence of a set of characters
@cindex @code{SCAN} intrinsic
-
@node SECNDS
@section @code{SECNDS} --- Time function
@cindex @code{SECNDS} intrinsic
GNU extension
@item @emph{Class}:
-function
+Non-elemental function
@item @emph{Syntax}:
@code{RESULT = SECNDS (X)}
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
-@item Name @tab Type
-@item @var{T} @tab REAL(4)
-@item @var{X} @tab REAL(4)
+@item @var{T} @tab Shall be of type @code{REAL(4)}.
+@item @var{X} @tab Shall be of type @code{REAL(4)}.
@end multitable
@item @emph{Return value}:
+@node SECOND
+@section @code{SECOND} --- CPU time function
+@cindex @code{SECOND} intrinsic
+@cindex time, elapsed
+@cindex elapsed time
+
+@table @asis
+@item @emph{Description}:
+Returns a @code{REAL(4)} value representing the elapsed CPU time in
+seconds. This provides the same functionality as the standard
+@code{CPU_TIME} intrinsic, and is only included for backwards
+compatibility.
+
+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
+
+@item @emph{Class}:
+Subroutine, non-elemental function
+
+@item @emph{Syntax}:
+@multitable @columnfractions .80
+@item @code{CALL SECOND(TIME)}
+@item @code{TIME = SECOND()}
+@end multitable
+
+@item @emph{Arguments}:
+@multitable @columnfractions .15 .70
+@item @var{TIME} @tab Shall be of type @code{REAL(4)}.
+@end multitable
+
+@item @emph{Return value}:
+In either syntax, @var{TIME} is set to the process's current runtime in
+seconds.
+
+@item @emph{See also}:
+@ref{CPU_TIME}
+
+@end table
+
+
+
@node SELECTED_INT_KIND
@section @code{SELECTED_INT_KIND} --- Choose integer kind
@cindex @code{SELECTED_INT_KIND} intrinsic
@section @code{SIN} --- Sine function
@cindex @code{SIN} intrinsic
@cindex @code{DSIN} intrinsic
+@cindex @code{CSIN} intrinsic
@cindex @code{ZSIN} intrinsic
@cindex @code{CDSIN} intrinsic
@cindex trigonometric functions
-
@node SPREAD
@section @code{SPREAD} --- Add a dimension to an array
@cindex @code{SPREAD} intrinsic
-
@node SQRT
@section @code{SQRT} --- Square-root function
@cindex @code{SQRT} intrinsic
The return value is a scalar of type @code{INTEGER(4)}.
@item @emph{See also}:
-@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME8}
+@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
@end table
The return value is a scalar of type @code{INTEGER(8)}.
@item @emph{See also}:
-@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}
+@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
@end table