[pf3gnuchains/gcc-fork.git] / gcc / fortran / intrinsic.texi

@ignore
Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
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.3 or
any later version published by the Free Software Foundation; with the
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:

  (1) The intrinsic procedures are to be listed in alphabetical order.
  (2) The generic name is to be used.
  (3) The specific names are included in the function index and in a
      table at the end of the node (See ABS entry).
  (4) Try to maintain the same style for each entry.


@end ignore

@tex
\gdef\acos{\mathop{\rm acos}\nolimits}
\gdef\asin{\mathop{\rm asin}\nolimits}
\gdef\atan{\mathop{\rm atan}\nolimits}
\gdef\acosh{\mathop{\rm acosh}\nolimits}
\gdef\asinh{\mathop{\rm asinh}\nolimits}
\gdef\atanh{\mathop{\rm atanh}\nolimits}
@end tex


@node Intrinsic Procedures
@chapter Intrinsic Procedures
@cindex intrinsic procedures

@menu
* Introduction:         Introduction to Intrinsics
* @code{ABORT}:         ABORT,     Abort the program     
* @code{ABS}:           ABS,       Absolute value     
* @code{ACCESS}:        ACCESS,    Checks file access modes
* @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
* @code{ACOS}:          ACOS,      Arccosine function
* @code{ACOSH}:         ACOSH,     Inverse hyperbolic cosine function
* @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
* @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
* @code{AIMAG}:         AIMAG,     Imaginary part of complex number
* @code{AINT}:          AINT,      Truncate to a whole number
* @code{ALARM}:         ALARM,     Set an alarm clock
* @code{ALL}:           ALL,       Determine if all values are true
* @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
* @code{AND}:           AND,       Bitwise logical AND
* @code{ANINT}:         ANINT,     Nearest whole number
* @code{ANY}:           ANY,       Determine if any values are true
* @code{ASIN}:          ASIN,      Arcsine function
* @code{ASINH}:         ASINH,     Inverse hyperbolic sine function
* @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
* @code{ATAN}:          ATAN,      Arctangent function
* @code{ATAN2}:         ATAN2,     Arctangent function
* @code{ATANH}:         ATANH,     Inverse hyperbolic tangent function
* @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
* @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
* @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
* @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
* @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
* @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
* @code{BGE}:           BGE,       Bitwise greater than or equal to
* @code{BGT}:           BGT,       Bitwise greater than
* @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
* @code{BLE}:           BLE,       Bitwise less than or equal to
* @code{BLT}:           BLT,       Bitwise less than
* @code{BTEST}:         BTEST,     Bit test function
* @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
* @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
* @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{CHMOD}:         CHMOD,     Change access permissions of files
* @code{CMPLX}:         CMPLX,     Complex conversion function
* @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
* @code{COMPLEX}:       COMPLEX,   Complex conversion function
* @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
* @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
* @code{CONJG}:         CONJG,     Complex conjugate function
* @code{COS}:           COS,       Cosine function
* @code{COSH}:          COSH,      Hyperbolic cosine function
* @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
* @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
* @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
* @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
* @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
* @code{DBLE}:          DBLE,      Double precision conversion function
* @code{DCMPLX}:        DCMPLX,    Double complex conversion function
* @code{DIGITS}:        DIGITS,    Significant digits function
* @code{DIM}:           DIM,       Positive difference
* @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
* @code{DPROD}:         DPROD,     Double product function
* @code{DREAL}:         DREAL,     Double real part function
* @code{DSHIFTL}:       DSHIFTL,   Combined left shift
* @code{DSHIFTR}:       DSHIFTR,   Combined right shift
* @code{DTIME}:         DTIME,     Execution time subroutine (or function)
* @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
* @code{EPSILON}:       EPSILON,   Epsilon function
* @code{ERF}:           ERF,       Error function
* @code{ERFC}:          ERFC,      Complementary error function
* @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
* @code{ETIME}:         ETIME,     Execution time subroutine (or function)
* @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
* @code{EXIT}:          EXIT,      Exit the program with status.
* @code{EXP}:           EXP,       Exponential function
* @code{EXPONENT}:      EXPONENT,  Exponent function
* @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF,  Query dynamic type for extension
* @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
* @code{FGET}:          FGET,      Read a single character in stream mode from stdin
* @code{FGETC}:         FGETC,     Read a single character in stream mode
* @code{FLOOR}:         FLOOR,     Integer floor function
* @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
* @code{FNUM}:          FNUM,      File number function
* @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
* @code{FPUTC}:         FPUTC,     Write a single character in stream mode
* @code{FRACTION}:      FRACTION,  Fractional part of the model representation
* @code{FREE}:          FREE,      Memory de-allocation subroutine
* @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
* @code{FSTAT}:         FSTAT,     Get file status
* @code{FTELL}:         FTELL,     Current stream position
* @code{GAMMA}:         GAMMA,     Gamma function
* @code{GERROR}:        GERROR,    Get last system error message
* @code{GETARG}:        GETARG,    Get command line arguments
* @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
* @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
* @code{GETCWD}:        GETCWD,    Get current working directory
* @code{GETENV}:        GETENV,    Get an environmental variable
* @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
* @code{GETGID}:        GETGID,    Group ID function
* @code{GETLOG}:        GETLOG,    Get login name
* @code{GETPID}:        GETPID,    Process ID function
* @code{GETUID}:        GETUID,    User ID function
* @code{GMTIME}:        GMTIME,    Convert time to GMT info
* @code{HOSTNM}:        HOSTNM,    Get system host name
* @code{HUGE}:          HUGE,      Largest number of a kind
* @code{HYPOT}:         HYPOT,     Euclidean distance function
* @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
* @code{IALL}:          IALL,      Bitwise AND of array elements
* @code{IAND}:          IAND,      Bitwise logical and
* @code{IANY}:          IANY,      Bitwise OR of array elements
* @code{IARGC}:         IARGC,     Get the number of command line arguments
* @code{IBCLR}:         IBCLR,     Clear bit
* @code{IBITS}:         IBITS,     Bit extraction
* @code{IBSET}:         IBSET,     Set bit
* @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
* @code{IDATE}:         IDATE,     Current local time (day/month/year)
* @code{IEOR}:          IEOR,      Bitwise logical exclusive or
* @code{IERRNO}:        IERRNO,    Function to get the last system error number
* @code{IMAGE_INDEX}:   IMAGE_INDEX, Cosubscript to image index conversion
* @code{INDEX}:         INDEX intrinsic, 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{IPARITY}:       IPARITY,   Bitwise XOR of array elements
* @code{IRAND}:         IRAND,     Integer pseudo-random number
* @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
* @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
* @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
* @code{ISHFT}:         ISHFT,     Shift bits
* @code{ISHFTC}:        ISHFTC,    Shift bits circularly
* @code{ISNAN}:         ISNAN,     Tests for a NaN
* @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
* @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{LCOBOUND}:      LCOBOUND,  Lower codimension 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{LGE}:           LGE,       Lexical greater than or equal
* @code{LGT}:           LGT,       Lexical greater than
* @code{LINK}:          LINK,      Create a hard link
* @code{LLE}:           LLE,       Lexical less than or equal
* @code{LLT}:           LLT,       Lexical less than
* @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
* @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{LSTAT}:         LSTAT,     Get file status
* @code{LTIME}:         LTIME,     Convert time to local time info
* @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
* @code{MASKL}:         MASKL,     Left justified mask
* @code{MASKR}:         MASKR,     Right justified mask
* @code{MATMUL}:        MATMUL,    matrix multiplication
* @code{MAX}:           MAX,       Maximum value of an argument list
* @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{MERGE_BITS}:    MERGE_BITS, Merge of bits under mask
* @code{MIN}:           MIN,       Minimum value of an argument list
* @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
* @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
* @code{MINVAL}:        MINVAL,    Minimum value of an array
* @code{MOD}:           MOD,       Remainder function
* @code{MODULO}:        MODULO,    Modulo function
* @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
* @code{MVBITS}:        MVBITS,    Move bits from one integer to another
* @code{NEAREST}:       NEAREST,   Nearest representable number
* @code{NEW_LINE}:      NEW_LINE,  New line character
* @code{NINT}:          NINT,      Nearest whole number
* @code{NORM2}:         NORM2,     Euclidean vector norm
* @code{NOT}:           NOT,       Logical negation
* @code{NULL}:          NULL,      Function that returns an disassociated pointer
* @code{NUM_IMAGES}:    NUM_IMAGES, Number of images
* @code{OR}:            OR,        Bitwise logical OR
* @code{PACK}:          PACK,      Pack an array into an array of rank one
* @code{PARITY}:        PARITY,    Reduction with exclusive OR
* @code{PERROR}:        PERROR,    Print system error message
* @code{POPCNT}:        POPCNT,    Number of bits set
* @code{POPPAR}:        POPPAR,    Parity of the number of bits set
* @code{PRECISION}:     PRECISION, Decimal precision of a real kind
* @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
* @code{PRODUCT}:       PRODUCT,   Product of array elements
* @code{RADIX}:         RADIX,     Base of a data model
* @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
* @code{RAN}:           RAN,       Real pseudo-random number
* @code{REAL}:          REAL,      Convert to real type 
* @code{RENAME}:        RENAME,    Rename a file
* @code{REPEAT}:        REPEAT,    Repeated string concatenation
* @code{RESHAPE}:       RESHAPE,   Function to reshape an array
* @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
* @code{RSHIFT}:        RSHIFT,    Right shift bits
* @code{SAME_TYPE_AS}:  SAME_TYPE_AS,  Query dynamic types for equality
* @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
* @code{SECOND}:        SECOND,    CPU time function
* @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
* @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
* @code{SHAPE}:         SHAPE,     Determine the shape of an array
* @code{SHIFTA}:        SHIFTA,    Right shift with fill
* @code{SHIFTL}:        SHIFTL,    Left shift
* @code{SHIFTR}:        SHIFTR,    Right shift
* @code{SIGN}:          SIGN,      Sign copying function
* @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
* @code{SIN}:           SIN,       Sine function
* @code{SINH}:          SINH,      Hyperbolic sine function
* @code{SIZE}:          SIZE,      Function to determine the size of an array
* @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
* @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
* @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
* @code{SPREAD}:        SPREAD,    Add a dimension to an array 
* @code{SQRT}:          SQRT,      Square-root function
* @code{SRAND}:         SRAND,     Reinitialize the random number generator
* @code{STAT}:          STAT,      Get file status
* @code{STORAGE_SIZE}:  STORAGE_SIZE, Storage size in bits
* @code{SUM}:           SUM,       Sum of array elements
* @code{SYMLNK}:        SYMLNK,    Create a symbolic link
* @code{SYSTEM}:        SYSTEM,    Execute a shell command
* @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
* @code{TAN}:           TAN,       Tangent function
* @code{TANH}:          TANH,      Hyperbolic tangent function
* @code{THIS_IMAGE}:    THIS_IMAGE, Cosubscript index of this image
* @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
* @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
* @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
* @code{UCOBOUND}:      UCOBOUND,  Upper codimension bounds of an array
* @code{UMASK}:         UMASK,     Set the file creation mask
* @code{UNLINK}:        UNLINK,    Remove a file from the file system
* @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
* @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
* @code{XOR}:           XOR,       Bitwise logical exclusive or
@end menu

@node Introduction to Intrinsics
@section Introduction to intrinsic procedures

The intrinsic procedures provided by GNU Fortran include all of the
intrinsic procedures required by the Fortran 95 standard, a set of
intrinsic procedures for backwards compatibility with G77, and a
selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
standards.  Any conflict between a description here and a description in
either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
2008 standard is unintentional, and the standard(s) should be considered
authoritative.

The enumeration of the @code{KIND} type parameter is processor defined in
the Fortran 95 standard.  GNU Fortran defines the default integer type and
default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
respectively.  The standard mandates that both data types shall have
another kind, which have more precision.  On typical target architectures
supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
In the description of generic intrinsic procedures, the kind type parameter
will be specified by @code{KIND=*}, and in the description of specific
names for an intrinsic procedure the kind type parameter will be explicitly
given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
brevity the optional @code{KIND=} syntax will be omitted.

Many of the intrinsic procedures take one or more optional arguments.
This document follows the convention used in the Fortran 95 standard,
and denotes such arguments by square brackets.

GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
which can be used to restrict the set of intrinsic procedures to a 
given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
option, and so all intrinsic procedures described here are accepted.  There
is one caveat.  For a select group of intrinsic procedures, @command{g77}
implemented both a function and a subroutine.  Both classes 
have been implemented in @command{gfortran} for backwards compatibility
with @command{g77}.  It is noted here that these functions and subroutines
cannot be intermixed in a given subprogram.  In the descriptions that follow,
the applicable standard for each intrinsic procedure is noted.



@node ABORT
@section @code{ABORT} --- Abort the program
@fnindex ABORT
@cindex program termination, with core dump
@cindex terminate program, with core dump
@cindex core, dump

@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 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

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL ABORT}

@item @emph{Return value}:
Does not return.

@item @emph{Example}:
@smallexample
program test_abort
  integer :: i = 1, j = 2
  if (i /= j) call abort
end program test_abort
@end smallexample

@item @emph{See also}:
@ref{EXIT}, @ref{KILL}

@end table



@node ABS
@section @code{ABS} --- Absolute value
@fnindex ABS
@fnindex CABS
@fnindex DABS
@fnindex IABS
@fnindex ZABS
@fnindex CDABS
@cindex absolute value

@table @asis
@item @emph{Description}:
@code{ABS(A)} computes the absolute value of @code{A}.

@item @emph{Standard}:
Fortran 77 and later, has overloads that are GNU extensions

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ABS(A)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab The type of the argument shall be an @code{INTEGER},
@code{REAL}, or @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and
kind as the argument except the return value is @code{REAL} for a
@code{COMPLEX} argument.

@item @emph{Example}:
@smallexample
program test_abs
  integer :: i = -1
  real :: x = -1.e0
  complex :: z = (-1.e0,0.e0)
  i = abs(i)
  x = abs(x)
  x = abs(z)
end program test_abs
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument            @tab Return type       @tab Standard
@item @code{ABS(A)}   @tab @code{REAL(4) A}    @tab @code{REAL(4)}    @tab Fortran 77 and later
@item @code{CABS(A)}  @tab @code{COMPLEX(4) A} @tab @code{REAL(4)}    @tab Fortran 77 and later
@item @code{DABS(A)}  @tab @code{REAL(8) A}    @tab @code{REAL(8)}    @tab Fortran 77 and later
@item @code{IABS(A)}  @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
@item @code{ZABS(A)}  @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
@item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
@end multitable
@end table



@node ACCESS
@section @code{ACCESS} --- Checks file access modes
@fnindex ACCESS
@cindex file system, access mode

@table @asis
@item @emph{Description}:
@code{ACCESS(NAME, MODE)} checks whether the file @var{NAME} 
exists, is readable, writable or executable. Except for the
executable check, @code{ACCESS} can be replaced by
Fortran 95's @code{INQUIRE}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = ACCESS(NAME, MODE)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
file name. Tailing blank are ignored unless the character @code{achar(0)}
is present, then all characters up to and excluding @code{achar(0)} are
used as file name.
@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
file access mode, may be any concatenation of @code{"r"} (readable),
@code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
for existence.
@end multitable

@item @emph{Return value}:
Returns a scalar @code{INTEGER}, which is @code{0} if the file is
accessible in the given mode; otherwise or if an invalid argument
has been given for @code{MODE} the value @code{1} is returned.

@item @emph{Example}:
@smallexample
program access_test
  implicit none
  character(len=*), parameter :: file  = 'test.dat'
  character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
  if(access(file,' ') == 0) print *, trim(file),' is exists'
  if(access(file,'r') == 0) print *, trim(file),' is readable'
  if(access(file,'w') == 0) print *, trim(file),' is writable'
  if(access(file,'x') == 0) print *, trim(file),' is executable'
  if(access(file2,'rwx') == 0) &
    print *, trim(file2),' is readable, writable and executable'
end program access_test
@end smallexample
@item @emph{Specific names}:
@item @emph{See also}:

@end table



@node ACHAR
@section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence 
@fnindex ACHAR
@cindex @acronym{ASCII} collating sequence
@cindex collating sequence, @acronym{ASCII}

@table @asis
@item @emph{Description}:
@code{ACHAR(I)} returns the character located at position @code{I}
in the @acronym{ASCII} collating sequence.

@item @emph{Standard}:
Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ACHAR(I [, KIND])}

@item @emph{Arguments}:
@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.
@end multitable

@item @emph{Return value}:
The return value is of type @code{CHARACTER} with a length of one.
If the @var{KIND} argument is present, the return value is of the
specified kind and of the default kind otherwise.

@item @emph{Example}:
@smallexample
program test_achar
  character c
  c = achar(32)
end program test_achar
@end smallexample

@item @emph{Note}:
See @ref{ICHAR} for a discussion of converting between numerical values
and formatted string representations.

@item @emph{See also}:
@ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}

@end table



@node ACOS
@section @code{ACOS} --- Arccosine function 
@fnindex ACOS
@fnindex DACOS
@cindex trigonometric function, cosine, inverse
@cindex cosine, inverse

@table @asis
@item @emph{Description}:
@code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).

@item @emph{Standard}:
Fortran 77 and later, for a complex argument Fortran 2008 or later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ACOS(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
less than or equal to one - or the type shall be @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and kind as @var{X}.
The real part of the result is in radians and lies in the range
@math{0 \leq \Re \acos(x) \leq \pi}.

@item @emph{Example}:
@smallexample
program test_acos
  real(8) :: x = 0.866_8
  x = acos(x)
end program test_acos
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument         @tab Return type     @tab Standard
@item @code{ACOS(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}  @tab Fortran 77 and later
@item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}  @tab Fortran 77 and later
@end multitable

@item @emph{See also}:
Inverse function: @ref{COS}

@end table



@node ACOSH
@section @code{ACOSH} --- Inverse hyperbolic cosine function
@fnindex ACOSH
@fnindex DACOSH
@cindex area hyperbolic cosine
@cindex inverse hyperbolic cosine
@cindex hyperbolic function, cosine, inverse
@cindex cosine, hyperbolic, inverse

@table @asis
@item @emph{Description}:
@code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ACOSH(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value has the same type and kind as @var{X}. If @var{X} is
complex, the imaginary part of the result is in radians and lies between
@math{ 0 \leq \Im \acosh(x) \leq \pi}.

@item @emph{Example}:
@smallexample
PROGRAM test_acosh
  REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
  WRITE (*,*) ACOSH(x)
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



@node ADJUSTL
@section @code{ADJUSTL} --- Left adjust a string 
@fnindex ADJUSTL
@cindex string, adjust left
@cindex adjust string

@table @asis
@item @emph{Description}:
@code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
Spaces are inserted at the end of the string as needed.

@item @emph{Standard}:
Fortran 90 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ADJUSTL(STRING)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab The type shall be @code{CHARACTER}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{CHARACTER} and of the same kind as
@var{STRING} where leading spaces are removed and the same number of
spaces are inserted on the end of @var{STRING}.

@item @emph{Example}:
@smallexample
program test_adjustl
  character(len=20) :: str = '   gfortran'
  str = adjustl(str)
  print *, str
end program test_adjustl
@end smallexample

@item @emph{See also}:
@ref{ADJUSTR}, @ref{TRIM}
@end table



@node ADJUSTR
@section @code{ADJUSTR} --- Right adjust a string 
@fnindex ADJUSTR
@cindex string, adjust right
@cindex adjust string

@table @asis
@item @emph{Description}:
@code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
Spaces are inserted at the start of the string as needed.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ADJUSTR(STRING)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STR} @tab The type shall be @code{CHARACTER}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{CHARACTER} and of the same kind as
@var{STRING} where trailing spaces are removed and the same number of
spaces are inserted at the start of @var{STRING}.

@item @emph{Example}:
@smallexample
program test_adjustr
  character(len=20) :: str = 'gfortran'
  str = adjustr(str)
  print *, str
end program test_adjustr
@end smallexample

@item @emph{See also}:
@ref{ADJUSTL}, @ref{TRIM}
@end table



@node AIMAG
@section @code{AIMAG} --- Imaginary part of complex number  
@fnindex AIMAG
@fnindex DIMAG
@fnindex IMAG
@fnindex IMAGPART
@cindex complex numbers, imaginary part

@table @asis
@item @emph{Description}:
@code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
for compatibility with @command{g77}, and their use in new code is 
strongly discouraged.

@item @emph{Standard}:
Fortran 77 and later, has overloads that are GNU extensions

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = AIMAG(Z)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL} with the
kind type parameter of the argument.

@item @emph{Example}:
@smallexample
program test_aimag
  complex(4) z4
  complex(8) z8
  z4 = cmplx(1.e0_4, 0.e0_4)
  z8 = cmplx(0.e0_8, 1.e0_8)
  print *, aimag(z4), dimag(z8)
end program test_aimag
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name               @tab Argument            @tab Return type     @tab Standard
@item @code{AIMAG(Z)}    @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
@item @code{DIMAG(Z)}    @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}  @tab GNU extension
@item @code{IMAG(Z)}     @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
@item @code{IMAGPART(Z)} @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
@end multitable
@end table



@node AINT
@section @code{AINT} --- Truncate to a whole number
@fnindex AINT
@fnindex DINT
@cindex floor
@cindex rounding, floor

@table @asis
@item @emph{Description}:
@code{AINT(A [, KIND])} truncates its argument to a whole number.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = AINT(A [, KIND])} 

@item @emph{Arguments}:
@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.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL} with the kind type parameter of the
argument if the optional @var{KIND} is absent; otherwise, the kind
type parameter will be given by @var{KIND}.  If the magnitude of 
@var{X} is less than one, @code{AINT(X)} returns zero.  If the
magnitude is equal to or greater than one then it returns the largest
whole number that does not exceed its magnitude.  The sign is the same
as the sign of @var{X}. 

@item @emph{Example}:
@smallexample
program test_aint
  real(4) x4
  real(8) x8
  x4 = 1.234E0_4
  x8 = 4.321_8
  print *, aint(x4), dint(x8)
  x8 = aint(x4,8)
end program test_aint
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name           @tab Argument         @tab Return type      @tab Standard
@item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
@item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
@end multitable
@end table



@node ALARM
@section @code{ALARM} --- Execute a routine after a given delay
@fnindex ALARM
@cindex delayed execution

@table @asis
@item @emph{Description}:
@code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
supplied, it will be returned with the number of seconds remaining until
any previously scheduled alarm was due to be delivered, or zero if there
was no previously scheduled alarm.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL ALARM(SECONDS, HANDLER [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SECONDS} @tab The type of the argument shall be a scalar
@code{INTEGER}. It is @code{INTENT(IN)}.
@item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar 
values may be either @code{SIG_IGN=1} to ignore the alarm generated 
or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
@item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
@end multitable

@item @emph{Example}:
@smallexample
program test_alarm
  external handler_print
  integer i
  call alarm (3, handler_print, i)
  print *, i
  call sleep(10)
end program test_alarm
@end smallexample
This will cause the external routine @var{handler_print} to be called
after 3 seconds.
@end table



@node ALL
@section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true 
@fnindex ALL
@cindex array, apply condition
@cindex array, condition testing

@table @asis
@item @emph{Description}:
@code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
in the array along dimension @var{DIM}.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = ALL(MASK [, DIM])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
it shall not be scalar.
@item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
with a value that lies between one and the rank of @var{MASK}.
@end multitable

@item @emph{Return value}:
@code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
the kind type parameter is the same as the kind type parameter of
@var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
an array with the rank of @var{MASK} minus 1.  The shape is determined from
the shape of @var{MASK} where the @var{DIM} dimension is elided. 

@table @asis
@item (A)
@code{ALL(MASK)} is true if all elements of @var{MASK} are true.
It also is true if @var{MASK} has zero size; otherwise, it is false.
@item (B)
If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
is determined by applying @code{ALL} to the array sections.
@end table

@item @emph{Example}:
@smallexample
program test_all
  logical l
  l = all((/.true., .true., .true./))
  print *, l
  call section
  contains
    subroutine section
      integer a(2,3), b(2,3)
      a = 1
      b = 1
      b(2,2) = 2
      print *, all(a .eq. b, 1)
      print *, all(a .eq. b, 2)
    end subroutine section
end program test_all
@end smallexample
@end table



@node ALLOCATED
@section @code{ALLOCATED} --- Status of an allocatable entity
@fnindex ALLOCATED
@cindex allocation, status

@table @asis
@item @emph{Description}:
@code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
status of @var{ARRAY} and @var{SCALAR}, respectively.

@item @emph{Standard}:
Fortran 95 and later.  Note, the @code{SCALAR=} keyword and allocatable
scalar entities are available in Fortran 2003 and later.

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)} 

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
@item @var{SCALAR}   @tab The argument shall be an @code{ALLOCATABLE} scalar.
@end multitable

@item @emph{Return value}:
The return value is a scalar @code{LOGICAL} with the default logical
kind type parameter.  If the argument is allocated, then the result is
@code{.TRUE.}; otherwise, it returns @code{.FALSE.} 

@item @emph{Example}:
@smallexample
program test_allocated
  integer :: i = 4
  real(4), allocatable :: x(:)
  if (.not. allocated(x)) allocate(x(i))
end program test_allocated
@end smallexample
@end table



@node AND
@section @code{AND} --- Bitwise logical AND
@fnindex AND
@cindex bitwise logical and
@cindex logical and, bitwise

@table @asis
@item @emph{Description}:
Bitwise logical @code{AND}.

This intrinsic routine is provided for backwards compatibility with 
GNU Fortran 77.  For integer arguments, programmers should consider
the use of the @ref{IAND} intrinsic defined by the Fortran standard.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Function

@item @emph{Syntax}:
@code{RESULT = AND(I, J)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be either a scalar @code{INTEGER}
type or a scalar @code{LOGICAL} type.
@item @var{J} @tab The type shall be the same as the type of @var{I}.
@end multitable

@item @emph{Return value}:
The return type is either a scalar @code{INTEGER} or a scalar
@code{LOGICAL}.  If the kind type parameters differ, then the
smaller kind type is implicitly converted to larger kind, and the 
return has the larger kind.

@item @emph{Example}:
@smallexample
PROGRAM test_and
  LOGICAL :: T = .TRUE., F = .FALSE.
  INTEGER :: a, b
  DATA a / Z'F' /, b / Z'3' /

  WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
  WRITE (*,*) AND(a, b)
END PROGRAM
@end smallexample

@item @emph{See also}:
Fortran 95 elemental function: @ref{IAND}
@end table



@node ANINT
@section @code{ANINT} --- Nearest whole number
@fnindex ANINT
@fnindex DNINT
@cindex ceiling
@cindex rounding, ceiling

@table @asis
@item @emph{Description}:
@code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ANINT(A [, KIND])}

@item @emph{Arguments}:
@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.
@end multitable

@item @emph{Return value}:
The return value is of type real with the kind type parameter of the
argument if the optional @var{KIND} is absent; otherwise, the kind
type parameter will be given by @var{KIND}.  If @var{A} is greater than
zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
less than or equal to zero then it returns @code{AINT(X-0.5)}.

@item @emph{Example}:
@smallexample
program test_anint
  real(4) x4
  real(8) x8
  x4 = 1.234E0_4
  x8 = 4.321_8
  print *, anint(x4), dnint(x8)
  x8 = anint(x4,8)
end program test_anint
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument         @tab Return type      @tab Standard
@item @code{AINT(A)}  @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
@item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
@end multitable
@end table



@node ANY
@section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true 
@fnindex ANY
@cindex array, apply condition
@cindex array, condition testing

@table @asis
@item @emph{Description}:
@code{ANY(MASK [, DIM])} determines if any of the values in the logical array
@var{MASK} along dimension @var{DIM} are @code{.TRUE.}.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = ANY(MASK [, DIM])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
it shall not be scalar.
@item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
with a value that lies between one and the rank of @var{MASK}.
@end multitable

@item @emph{Return value}:
@code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
the kind type parameter is the same as the kind type parameter of
@var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
an array with the rank of @var{MASK} minus 1.  The shape is determined from
the shape of @var{MASK} where the @var{DIM} dimension is elided. 

@table @asis
@item (A)
@code{ANY(MASK)} is true if any element of @var{MASK} is true;
otherwise, it is false.  It also is false if @var{MASK} has zero size.
@item (B)
If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
is determined by applying @code{ANY} to the array sections.
@end table

@item @emph{Example}:
@smallexample
program test_any
  logical l
  l = any((/.true., .true., .true./))
  print *, l
  call section
  contains
    subroutine section
      integer a(2,3), b(2,3)
      a = 1
      b = 1
      b(2,2) = 2
      print *, any(a .eq. b, 1)
      print *, any(a .eq. b, 2)
    end subroutine section
end program test_any
@end smallexample
@end table



@node ASIN
@section @code{ASIN} --- Arcsine function 
@fnindex ASIN
@fnindex DASIN
@cindex trigonometric function, sine, inverse
@cindex sine, inverse

@table @asis
@item @emph{Description}:
@code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).

@item @emph{Standard}:
Fortran 77 and later, for a complex argument Fortran 2008 or later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ASIN(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
less than or equal to one - or be @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and kind as @var{X}.
The real part of the result is in radians and lies in the range
@math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.

@item @emph{Example}:
@smallexample
program test_asin
  real(8) :: x = 0.866_8
  x = asin(x)
end program test_asin
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{ASIN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
@item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
@end multitable

@item @emph{See also}:
Inverse function: @ref{SIN}

@end table



@node ASINH
@section @code{ASINH} --- Inverse hyperbolic sine function
@fnindex ASINH
@fnindex DASINH
@cindex area hyperbolic sine
@cindex inverse hyperbolic sine
@cindex hyperbolic function, sine, inverse
@cindex sine, hyperbolic, inverse

@table @asis
@item @emph{Description}:
@code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ASINH(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and kind as  @var{X}. If @var{X} is
complex, the imaginary part of the result is in radians and lies between
@math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.

@item @emph{Example}:
@smallexample
PROGRAM test_asinh
  REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
  WRITE (*,*) ASINH(x)
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



@node ASSOCIATED
@section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair 
@fnindex ASSOCIATED
@cindex pointer, status
@cindex association status

@table @asis
@item @emph{Description}:
@code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
@var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = ASSOCIATED(POINTER [, TARGET])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
and it can be of any type.
@item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
a target.  It must have the same type, kind type parameter, and
array rank as @var{POINTER}.
@end multitable
The association status of neither @var{POINTER} nor @var{TARGET} shall be
undefined.

@item @emph{Return value}:
@code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
There are several cases:
@table @asis
@item (A) When the optional @var{TARGET} is not present then
@code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
@item (B) If @var{TARGET} is present and a scalar target, the result is true if
@var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units.  If @var{POINTER} is
disassociated, the result is false.
@item (C) If @var{TARGET} is present and an array target, the result is true if
@var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
are arrays whose elements are not zero-sized storage sequences, and
@var{TARGET} and @var{POINTER} occupy the same storage units in array element
order.
As in case(B), the result is false, if @var{POINTER} is disassociated.
@item (D) If @var{TARGET} is present and an scalar pointer, the result is true
if @var{TARGET} is associated with @var{POINTER}, the target associated with
@var{TARGET} are not zero-sized storage sequences and occupy the same storage
units.
The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
@item (E) If @var{TARGET} is present and an array pointer, the result is true if
target associated with @var{POINTER} and the target associated with @var{TARGET}
have the same shape, are not zero-sized arrays, are arrays whose elements are
not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
the same storage units in array element order.
The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
@end table

@item @emph{Example}:
@smallexample
program test_associated
   implicit none
   real, target  :: tgt(2) = (/1., 2./)
   real, pointer :: ptr(:)
   ptr => tgt
   if (associated(ptr)     .eqv. .false.) call abort
   if (associated(ptr,tgt) .eqv. .false.) call abort
end program test_associated
@end smallexample

@item @emph{See also}:
@ref{NULL}
@end table



@node ATAN
@section @code{ATAN} --- Arctangent function 
@fnindex ATAN
@fnindex DATAN
@cindex trigonometric function, tangent, inverse
@cindex tangent, inverse

@table @asis
@item @emph{Description}:
@code{ATAN(X)} computes the arctangent of @var{X}.

@item @emph{Standard}:
Fortran 77 and later, for a complex argument and for two arguments
Fortran 2008 or later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ATAN(X)}
@code{RESULT = ATAN(Y, X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
if @var{Y} is present, @var{X} shall be REAL.
@item @var{Y} shall be of the same type and kind as @var{X}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and kind as @var{X}.
If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
Otherwise, it the arcus tangent of @var{X}, where the real part of
the result is in radians and lies in the range
@math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.

@item @emph{Example}:
@smallexample
program test_atan
  real(8) :: x = 2.866_8
  x = atan(x)
end program test_atan
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{ATAN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
@item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
@end multitable

@item @emph{See also}:
Inverse function: @ref{TAN}

@end table



@node ATAN2
@section @code{ATAN2} --- Arctangent function 
@fnindex ATAN2
@fnindex DATAN2
@cindex trigonometric function, tangent, inverse
@cindex tangent, inverse

@table @asis
@item @emph{Description}:
@code{ATAN2(Y, X)} computes the principal value of the argument
function of the complex number @math{X + i Y}. This function can
be used to transform from Cartesian into polar coordinates and
allows to determine the angle in the correct quadrant.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ATAN2(Y, X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{Y} @tab The type shall be @code{REAL}.
@item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
If @var{Y} is zero, then @var{X} must be nonzero.
@end multitable

@item @emph{Return value}:
The return value has the same type and kind type parameter as @var{Y}.
It is the principal value of the complex number @math{X + i Y}.  If
@var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
is negative.  Finally, if @var{X} is zero, then the magnitude of the result
is @math{\pi/2}.

@item @emph{Example}:
@smallexample
program test_atan2
  real(4) :: x = 1.e0_4, y = 0.5e0_4
  x = atan2(y,x)
end program test_atan2
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name                @tab Argument            @tab Return type    @tab Standard
@item @code{ATAN2(X, Y)}  @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
@item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
@end multitable
@end table



@node ATANH
@section @code{ATANH} --- Inverse hyperbolic tangent function
@fnindex ATANH
@fnindex DATANH
@cindex area hyperbolic tangent
@cindex inverse hyperbolic tangent
@cindex hyperbolic function, tangent, inverse
@cindex tangent, hyperbolic, inverse

@table @asis
@item @emph{Description}:
@code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ATANH(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value has same type and kind as @var{X}. If @var{X} is
complex, the imaginary part of the result is in radians and lies between
@math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.

@item @emph{Example}:
@smallexample
PROGRAM test_atanh
  REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
  WRITE (*,*) ATANH(x)
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 BESSEL_J0
@section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
@fnindex BESSEL_J0
@fnindex BESJ0
@fnindex DBESJ0
@cindex Bessel function, first kind

@table @asis
@item @emph{Description}:
@code{BESSEL_J0(X)} computes the Bessel function of the first kind of
order 0 of @var{X}. This function is available under the name
@code{BESJ0} as a GNU extension.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESSEL_J0(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL} and lies in the
range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
kind as @var{X}.

@item @emph{Example}:
@smallexample
program test_besj0
  real(8) :: x = 0.0_8
  x = bessel_j0(x)
end program test_besj0
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
@end multitable
@end table



@node BESSEL_J1
@section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
@fnindex BESSEL_J1
@fnindex BESJ1
@fnindex DBESJ1
@cindex Bessel function, first kind

@table @asis
@item @emph{Description}:
@code{BESSEL_J1(X)} computes the Bessel function of the first kind of
order 1 of @var{X}. This function is available under the name
@code{BESJ1} as a GNU extension.

@item @emph{Standard}:
Fortran 2008

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESSEL_J1(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL} and it lies in the
range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
kind as @var{X}.

@item @emph{Example}:
@smallexample
program test_besj1
  real(8) :: x = 1.0_8
  x = bessel_j1(x)
end program test_besj1
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name             @tab Argument          @tab Return type       @tab Standard
@item @code{DBESJ1(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
@end multitable
@end table



@node BESSEL_JN
@section @code{BESSEL_JN} --- Bessel function of the first kind
@fnindex BESSEL_JN
@fnindex BESJN
@fnindex DBESJN
@cindex Bessel function, first kind

@table @asis
@item @emph{Description}:
@code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
order @var{N} of @var{X}. This function is available under the name
@code{BESJN} as a GNU extension.  If @var{N} and @var{X} are arrays,
their ranks and shapes shall conform.  

@code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
of the first kind of the orders @var{N1} to @var{N2}.

@item @emph{Standard}:
Fortran 2008 and later, negative @var{N} is allowed as GNU extension

@item @emph{Class}:
Elemental function, except for the transformational function
@code{BESSEL_JN(N1, N2, X)}

@item @emph{Syntax}:
@code{RESULT = BESSEL_JN(N, X)}
@code{RESULT = BESSEL_JN(N1, N2, X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
@item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
@item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
@item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is a scalar of type @code{REAL}. It has the same
kind as @var{X}.

@item @emph{Note}:
The transformational function uses a recurrence algorithm which might,
for some values of @var{X}, lead to different results than calls to
the elemental function.

@item @emph{Example}:
@smallexample
program test_besjn
  real(8) :: x = 1.0_8
  x = bessel_jn(5,x)
end program test_besjn
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@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



@node BESSEL_Y0
@section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
@fnindex BESSEL_Y0
@fnindex BESY0
@fnindex DBESY0
@cindex Bessel function, second kind

@table @asis
@item @emph{Description}:
@code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
order 0 of @var{X}. This function is available under the name
@code{BESY0} as a GNU extension.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESSEL_Y0(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is a scalar of type @code{REAL}. It has the same
kind as @var{X}.

@item @emph{Example}:
@smallexample
program test_besy0
  real(8) :: x = 0.0_8
  x = bessel_y0(x)
end program test_besy0
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
@end multitable
@end table



@node BESSEL_Y1
@section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
@fnindex BESSEL_Y1
@fnindex BESY1
@fnindex DBESY1
@cindex Bessel function, second kind

@table @asis
@item @emph{Description}:
@code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
order 1 of @var{X}. This function is available under the name
@code{BESY1} as a GNU extension.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESSEL_Y1(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is a scalar of type @code{REAL}. It has the same
kind as @var{X}.

@item @emph{Example}:
@smallexample
program test_besy1
  real(8) :: x = 1.0_8
  x = bessel_y1(x)
end program test_besy1
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
@end multitable
@end table



@node BESSEL_YN
@section @code{BESSEL_YN} --- Bessel function of the second kind
@fnindex BESSEL_YN
@fnindex BESYN
@fnindex DBESYN
@cindex Bessel function, second kind

@table @asis
@item @emph{Description}:
@code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
order @var{N} of @var{X}. This function is available under the name
@code{BESYN} as a GNU extension.  If @var{N} and @var{X} are arrays,
their ranks and shapes shall conform.  

@code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
of the first kind of the orders @var{N1} to @var{N2}.

@item @emph{Standard}:
Fortran 2008 and later, negative @var{N} is allowed as GNU extension

@item @emph{Class}:
Elemental function, except for the transformational function
@code{BESSEL_YN(N1, N2, X)}

@item @emph{Syntax}:
@code{RESULT = BESSEL_YN(N, X)}
@code{RESULT = BESSEL_YN(N1, N2, X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER} .
@item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
@item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
@item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is a scalar of type @code{REAL}. It has the same
kind as @var{X}.

@item @emph{Note}:
The transformational function uses a recurrence algorithm which might,
for some values of @var{X}, lead to different results than calls to
the elemental function.

@item @emph{Example}:
@smallexample
program test_besyn
  real(8) :: x = 1.0_8
  x = bessel_yn(5,x)
end program test_besyn
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name               @tab Argument            @tab Return type     @tab Standard
@item @code{DBESYN(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



@node BGE
@section @code{BGE} --- Bitwise greater than or equal to
@fnindex BGE
@cindex bitwise comparison

@table @asis
@item @emph{Description}:
Determines whether an integral is a bitwise greater than or equal to
another.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BGE(I, J)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab Shall be of @code{INTEGER} type.
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
as @var{I}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.

@item @emph{See also}:
@ref{BGT}, @ref{BLE}, @ref{BLT}
@end table



@node BGT
@section @code{BGT} --- Bitwise greater than
@fnindex BGT
@cindex bitwise comparison

@table @asis
@item @emph{Description}:
Determines whether an integral is a bitwise greater than another.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BGT(I, J)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab Shall be of @code{INTEGER} type.
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
as @var{I}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.

@item @emph{See also}:
@ref{BGE}, @ref{BLE}, @ref{BLT}
@end table



@node BIT_SIZE
@section @code{BIT_SIZE} --- Bit size inquiry function
@fnindex BIT_SIZE
@cindex bits, number of
@cindex size of a variable, in bits

@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}.  The result of @code{BIT_SIZE(I)} is
independent of the actual value of @var{I}.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = BIT_SIZE(I)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER}

@item @emph{Example}:
@smallexample
program test_bit_size
    integer :: i = 123
    integer :: size
    size = bit_size(i)
    print *, size
end program test_bit_size
@end smallexample
@end table



@node BLE
@section @code{BLE} --- Bitwise less than or equal to
@fnindex BLE
@cindex bitwise comparison

@table @asis
@item @emph{Description}:
Determines whether an integral is a bitwise less than or equal to
another.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BLE(I, J)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab Shall be of @code{INTEGER} type.
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
as @var{I}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.

@item @emph{See also}:
@ref{BGT}, @ref{BGE}, @ref{BLT}
@end table



@node BLT
@section @code{BLT} --- Bitwise less than
@fnindex BLT
@cindex bitwise comparison

@table @asis
@item @emph{Description}:
Determines whether an integral is a bitwise less than another.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BLT(I, J)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab Shall be of @code{INTEGER} type.
@item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
as @var{I}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{LOGICAL} and of the default kind.

@item @emph{See also}:
@ref{BGE}, @ref{BGT}, @ref{BLE}
@end table



@node BTEST
@section @code{BTEST} --- Bit test function
@fnindex BTEST
@cindex bits, testing

@table @asis
@item @emph{Description}:
@code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
in @var{I} is set.  The counting of the bits starts at 0.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BTEST(I, POS)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER}.
@item @var{POS} @tab The type shall be @code{INTEGER}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{LOGICAL}

@item @emph{Example}:
@smallexample
program test_btest
    integer :: i = 32768 + 1024 + 64
    integer :: pos
    logical :: bool
    do pos=0,16
        bool = btest(i, pos) 
        print *, pos, bool
    end do
end program test_btest
@end smallexample
@end table


@node C_ASSOCIATED
@section @code{C_ASSOCIATED} --- Status of a C pointer
@fnindex C_ASSOCIATED
@cindex association status, C pointer
@cindex pointer, C association status

@table @asis
@item @emph{Description}:
@code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
@var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.

@item @emph{Standard}:
Fortran 2003 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
@item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{LOGICAL}; it is @code{.false.} if either
@var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
point to different addresses.

@item @emph{Example}:
@smallexample
subroutine association_test(a,b)
  use iso_c_binding, only: c_associated, c_loc, c_ptr
  implicit none
  real, pointer :: a
  type(c_ptr) :: b
  if(c_associated(b, c_loc(a))) &
     stop 'b and a do not point to same target'
end subroutine association_test
@end smallexample

@item @emph{See also}:
@ref{C_LOC}, @ref{C_FUNLOC}
@end table


@node C_FUNLOC
@section @code{C_FUNLOC} --- Obtain the C address of a procedure
@fnindex C_FUNLOC
@cindex pointer, C address of procedures

@table @asis
@item @emph{Description}:
@code{C_FUNLOC(x)} determines the C address of the argument.

@item @emph{Standard}:
Fortran 2003 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = C_FUNLOC(x)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{x} @tab Interoperable function or pointer to such function.
@end multitable

@item @emph{Return value}:
The return value is of type @code{C_FUNPTR} and contains the C address
of the argument.

@item @emph{Example}:
@smallexample
module x
  use iso_c_binding
  implicit none
contains
  subroutine sub(a) bind(c)
    real(c_float) :: a
    a = sqrt(a)+5.0
  end subroutine sub
end module x
program main
  use iso_c_binding
  use x
  implicit none
  interface
    subroutine my_routine(p) bind(c,name='myC_func')
      import :: c_funptr
      type(c_funptr), intent(in) :: p
    end subroutine
  end interface
  call my_routine(c_funloc(sub))
end program main
@end smallexample

@item @emph{See also}:
@ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
@end table


@node C_F_PROCPOINTER
@section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
@fnindex C_F_PROCPOINTER
@cindex pointer, C address of pointers

@table @asis
@item @emph{Description}:
@code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
@var{CPTR} to the Fortran procedure pointer @var{FPTR}.

@item @emph{Standard}:
Fortran 2003 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL C_F_PROCPOINTER(cptr, fptr)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
@code{INTENT(IN)}.
@item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
@code{INTENT(OUT)}.
@end multitable

@item @emph{Example}:
@smallexample
program main
  use iso_c_binding
  implicit none
  abstract interface
    function func(a)
      import :: c_float
      real(c_float), intent(in) :: a
      real(c_float) :: func
    end function
  end interface
  interface
     function getIterFunc() bind(c,name="getIterFunc")
       import :: c_funptr
       type(c_funptr) :: getIterFunc
     end function
  end interface
  type(c_funptr) :: cfunptr
  procedure(func), pointer :: myFunc
  cfunptr = getIterFunc()
  call c_f_procpointer(cfunptr, myFunc)
end program main
@end smallexample

@item @emph{See also}:
@ref{C_LOC}, @ref{C_F_POINTER}
@end table


@node C_F_POINTER
@section @code{C_F_POINTER} --- Convert C into Fortran pointer
@fnindex C_F_POINTER
@cindex pointer, convert C to Fortran

@table @asis
@item @emph{Description}:
@code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
@var{CPTR} to the Fortran pointer @var{FPTR} and specify its
shape.

@item @emph{Standard}:
Fortran 2003 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
@code{INTENT(IN)}.
@item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
@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}.
@end multitable

@item @emph{Example}:
@smallexample
program main
  use iso_c_binding
  implicit none
  interface
    subroutine my_routine(p) bind(c,name='myC_func')
      import :: c_ptr
      type(c_ptr), intent(out) :: p
    end subroutine
  end interface
  type(c_ptr) :: cptr
  real,pointer :: a(:)
  call my_routine(cptr)
  call c_f_pointer(cptr, a, [12])
end program main
@end smallexample

@item @emph{See also}:
@ref{C_LOC}, @ref{C_F_PROCPOINTER}
@end table


@node C_LOC
@section @code{C_LOC} --- Obtain the C address of an object
@fnindex C_LOC
@cindex procedure pointer, convert C to Fortran

@table @asis
@item @emph{Description}:
@code{C_LOC(X)} determines the C address of the argument.

@item @emph{Standard}:
Fortran 2003 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = C_LOC(X)}

@item @emph{Arguments}:
@multitable @columnfractions .10 .75
@item @var{X} @tab  Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.

@end multitable

@item @emph{Return value}:
The return value is of type @code{C_PTR} and contains the C address
of the argument.

@item @emph{Example}:
@smallexample
subroutine association_test(a,b)
  use iso_c_binding, only: c_associated, c_loc, c_ptr
  implicit none
  real, pointer :: a
  type(c_ptr) :: b
  if(c_associated(b, c_loc(a))) &
     stop 'b and a do not point to same target'
end subroutine association_test
@end smallexample

@item @emph{See also}:
@ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
@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}:
Inquiry function of the module @code{ISO_C_BINDING}

@item @emph{Syntax}:
@code{N = C_SIZEOF(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The argument shall be an interoperable data entity.
@end multitable

@item @emph{Return value}:
The return value is of type integer and of the system-dependent kind
@code{C_SIZE_T} (from the @code{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}, @ref{STORAGE_SIZE}
@end table


@node CEILING
@section @code{CEILING} --- Integer ceiling function
@fnindex CEILING
@cindex ceiling
@cindex rounding, ceiling

@table @asis
@item @emph{Description}:
@code{CEILING(A)} returns the least integer greater than or equal to @var{A}.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = CEILING(A [, KIND])}

@item @emph{Arguments}:
@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.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
and a default-kind @code{INTEGER} otherwise.

@item @emph{Example}:
@smallexample
program test_ceiling
    real :: x = 63.29
    real :: y = -63.59
    print *, ceiling(x) ! returns 64
    print *, ceiling(y) ! returns -63
end program test_ceiling
@end smallexample

@item @emph{See also}:
@ref{FLOOR}, @ref{NINT}

@end table



@node CHAR
@section @code{CHAR} --- Character conversion function
@fnindex CHAR
@cindex conversion, to character

@table @asis
@item @emph{Description}:
@code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = CHAR(I [, KIND])}

@item @emph{Arguments}:
@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.
@end multitable

@item @emph{Return value}:
The return value is of type @code{CHARACTER(1)}

@item @emph{Example}:
@smallexample
program test_char
    integer :: i = 74
    character(1) :: c
    c = char(i)
    print *, i, c ! returns 'J'
end program test_char
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name           @tab Argument         @tab Return type             @tab Standard
@item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
@end multitable

@item @emph{Note}:
See @ref{ICHAR} for a discussion of converting between numerical values
and formatted string representations.

@item @emph{See also}:
@ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}

@end table



@node CHDIR
@section @code{CHDIR} --- Change working directory
@fnindex CHDIR
@cindex system, working directory

@table @asis
@item @emph{Description}:
Change current working directory to a specified path.

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, function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{CALL CHDIR(NAME [, STATUS])}
@item @code{STATUS = CHDIR(NAME)}
@end multitable

@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.
@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.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_chdir
  CHARACTER(len=255) :: path
  CALL getcwd(path)
  WRITE(*,*) TRIM(path)
  CALL chdir("/tmp")
  CALL getcwd(path)
  WRITE(*,*) TRIM(path)
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{GETCWD}
@end table



@node CHMOD
@section @code{CHMOD} --- Change access permissions of files
@fnindex CHMOD
@cindex file system, change access mode

@table @asis
@item @emph{Description}:
@code{CHMOD} changes the permissions of a file. This function invokes
@code{/bin/chmod} and might therefore not work on all platforms.

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, function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{CALL CHMOD(NAME, MODE[, STATUS])}
@item @code{STATUS = CHMOD(NAME, MODE)}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70

@item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
file name. Trailing blanks are ignored unless the character
@code{achar(0)} is present, then all characters up to and excluding
@code{achar(0)} are used as the file name.

@item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
file permission. @var{MODE} uses the same syntax as the @var{MODE}
argument of @code{/bin/chmod}.

@item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
@code{0} on success and nonzero otherwise.
@end multitable

@item @emph{Return value}:
In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
otherwise.

@item @emph{Example}:
@code{CHMOD} as subroutine
@smallexample
program chmod_test
  implicit none
  integer :: status
  call chmod('test.dat','u+x',status)
  print *, 'Status: ', status
end program chmod_test
@end smallexample
@code{CHMOD} as function:
@smallexample
program chmod_test
  implicit none
  integer :: status
  status = chmod('test.dat','u+x')
  print *, 'Status: ', status
end program chmod_test
@end smallexample

@end table



@node CMPLX
@section @code{CMPLX} --- Complex conversion function
@fnindex CMPLX
@cindex complex numbers, conversion to
@cindex conversion, to complex

@table @asis
@item @emph{Description}:
@code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
the real component.  If @var{Y} is present it is converted to the imaginary
component.  If @var{Y} is not present then the imaginary component is set to
0.0.  If @var{X} is complex then @var{Y} must not be present.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = CMPLX(X [, Y [, KIND]])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
or @code{COMPLEX}.
@item @var{Y} @tab (Optional; only allowed if @var{X} is not
@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.
@end multitable

@item @emph{Return value}:
The return value is of @code{COMPLEX} type, with a kind equal to
@var{KIND} if it is specified.  If @var{KIND} is not specified, the
result is of the default @code{COMPLEX} kind, regardless of the kinds of
@var{X} and @var{Y}. 

@item @emph{Example}:
@smallexample
program test_cmplx
    integer :: i = 42
    real :: x = 3.14
    complex :: z
    z = cmplx(i, x)
    print *, z, cmplx(x)
end program test_cmplx
@end smallexample

@item @emph{See also}:
@ref{COMPLEX}
@end table



@node COMMAND_ARGUMENT_COUNT
@section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
@fnindex COMMAND_ARGUMENT_COUNT
@cindex command-line arguments
@cindex command-line arguments, number of
@cindex arguments, to program

@table @asis
@item @emph{Description}:
@code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
command line when the containing program was invoked.

@item @emph{Standard}:
Fortran 2003 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = COMMAND_ARGUMENT_COUNT()}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item None
@end multitable

@item @emph{Return value}:
The return value is an @code{INTEGER} of default kind.

@item @emph{Example}:
@smallexample
program test_command_argument_count
    integer :: count
    count = command_argument_count()
    print *, count
end program test_command_argument_count
@end smallexample

@item @emph{See also}:
@ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
@end table



@node COMPILER_OPTIONS
@section @code{COMPILER_OPTIONS} --- Options passed to the compiler
@fnindex COMPILER_OPTIONS
@cindex flags inquiry function
@cindex options inquiry function
@cindex compiler flags inquiry function

@table @asis
@item @emph{Description}:
@code{COMPILER_OPTIONS()} returns a string with the options used for
compiling.

@item @emph{Standard}:
Fortran 2008

@item @emph{Class}:
Inquiry function of the module @code{ISO_FORTRAN_ENV}

@item @emph{Syntax}:
@code{STR = COMPILER_OPTIONS()}

@item @emph{Arguments}:
None.

@item @emph{Return value}:
The return value is a default-kind string with system-dependent length.
It contains the compiler flags used to compile the file, which called
the @code{COMPILER_OPTIONS} intrinsic.

@item @emph{Example}:
@smallexample
   use iso_fortran_env
   print '(4a)', 'This file was compiled by ', &
                 compiler_version(), ' using the the options ', &
                 compiler_options()
   end
@end smallexample

@item @emph{See also}:
@ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
@end table



@node COMPILER_VERSION
@section @code{COMPILER_VERSION} --- Compiler version string
@fnindex COMPILER_VERSION
@cindex compiler, name and version
@cindex version of the compiler

@table @asis
@item @emph{Description}:
@code{COMPILER_VERSION()} returns a string with the name and the
version of the compiler.

@item @emph{Standard}:
Fortran 2008

@item @emph{Class}:
Inquiry function of the module @code{ISO_FORTRAN_ENV}

@item @emph{Syntax}:
@code{STR = COMPILER_VERSION()}

@item @emph{Arguments}:
None.

@item @emph{Return value}:
The return value is a default-kind string with system-dependent length.
It contains the name of the compiler and its version number.

@item @emph{Example}:
@smallexample
   use iso_fortran_env
   print '(4a)', 'This file was compiled by ', &
                 compiler_version(), ' using the the options ', &
                 compiler_options()
   end
@end smallexample

@item @emph{See also}:
@ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
@end table



@node COMPLEX
@section @code{COMPLEX} --- Complex conversion function
@fnindex COMPLEX
@cindex complex numbers, conversion to
@cindex conversion, to complex

@table @asis
@item @emph{Description}:
@code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
to the real component and @var{Y} is converted to the imaginary
component.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = COMPLEX(X, Y)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
@item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
@end multitable

@item @emph{Return value}:
If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
value is of default @code{COMPLEX} type.

If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
type and one is of @code{INTEGER} type, then the return value is of
@code{COMPLEX} type with a kind equal to that of the @code{REAL}
argument with the highest precision.  

@item @emph{Example}:
@smallexample
program test_complex
    integer :: i = 42
    real :: x = 3.14
    print *, complex(i, x)
end program test_complex
@end smallexample

@item @emph{See also}:
@ref{CMPLX}
@end table



@node CONJG
@section @code{CONJG} --- Complex conjugate function 
@fnindex CONJG
@fnindex DCONJG
@cindex complex conjugate

@table @asis
@item @emph{Description}:
@code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
then the result is @code{(x, -y)}

@item @emph{Standard}:
Fortran 77 and later, has overloads that are GNU extensions

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{Z = CONJG(Z)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{Z} @tab The type shall be @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{COMPLEX}.

@item @emph{Example}:
@smallexample
program test_conjg
    complex :: z = (2.0, 3.0)
    complex(8) :: dz = (2.71_8, -3.14_8)
    z= conjg(z)
    print *, z
    dz = dconjg(dz)
    print *, dz
end program test_conjg
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name             @tab Argument             @tab Return type       @tab Standard
@item @code{CONJG(Z)}  @tab @code{COMPLEX Z}     @tab @code{COMPLEX}    @tab GNU extension
@item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)} @tab GNU extension
@end multitable
@end table



@node COS
@section @code{COS} --- Cosine function 
@fnindex COS
@fnindex DCOS
@fnindex CCOS
@fnindex ZCOS
@fnindex CDCOS
@cindex trigonometric function, cosine
@cindex cosine

@table @asis
@item @emph{Description}:
@code{COS(X)} computes the cosine of @var{X}.

@item @emph{Standard}:
Fortran 77 and later, has overloads that are GNU extensions

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = COS(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} or
@code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and kind as @var{X}. The real part
of the result is in radians. If @var{X} is of the type @code{REAL},
the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.

@item @emph{Example}:
@smallexample
program test_cos
  real :: x = 0.0
  x = cos(x)
end program test_cos
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument            @tab Return type       @tab Standard
@item @code{COS(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab Fortran 77 and later
@item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
@item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
@item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
@item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
@end multitable

@item @emph{See also}:
Inverse function: @ref{ACOS}

@end table



@node COSH
@section @code{COSH} --- Hyperbolic cosine function 
@fnindex COSH
@fnindex DCOSH
@cindex hyperbolic cosine
@cindex hyperbolic function, cosine
@cindex cosine, hyperbolic

@table @asis
@item @emph{Description}:
@code{COSH(X)} computes the hyperbolic cosine of @var{X}.

@item @emph{Standard}:
Fortran 77 and later, for a complex argument Fortran 2008 or later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{X = COSH(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value has same type and kind as @var{X}. If @var{X} is
complex, the imaginary part of the result is in radians. If @var{X}
is @code{REAL}, the return value has a lower bound of one,
@math{\cosh (x) \geq 1}.

@item @emph{Example}:
@smallexample
program test_cosh
  real(8) :: x = 1.0_8
  x = cosh(x)
end program test_cosh
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{COSH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
@item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
@end multitable

@item @emph{See also}:
Inverse function: @ref{ACOSH}

@end table



@node COUNT
@section @code{COUNT} --- Count function
@fnindex COUNT
@cindex array, conditionally count elements
@cindex array, element counting
@cindex array, number of elements

@table @asis
@item @emph{Description}:

Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
or, if the @var{DIM} argument is supplied, counts the number of
elements along each row of the array in the @var{DIM} direction.
If the array has zero size, or all of the elements of @var{MASK} are
@code{.FALSE.}, then the result is @code{0}.

@item @emph{Standard}:
Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = COUNT(MASK [, DIM, KIND])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@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.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER} and of kind @var{KIND}. If
@var{KIND} is absent, the return value is of default integer kind.
If @var{DIM} is present, the result is an array with a rank one less
than the rank of @var{ARRAY}, and a size corresponding to the shape
of @var{ARRAY} with the @var{DIM} dimension removed.

@item @emph{Example}:
@smallexample
program test_count
    integer, dimension(2,3) :: a, b
    logical, dimension(2,3) :: mask
    a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
    b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
    print '(3i3)', a(1,:)
    print '(3i3)', a(2,:)
    print *
    print '(3i3)', b(1,:)
    print '(3i3)', b(2,:)
    print *
    mask = a.ne.b
    print '(3l3)', mask(1,:)
    print '(3l3)', mask(2,:)
    print *
    print '(3i3)', count(mask)
    print *
    print '(3i3)', count(mask, 1)
    print *
    print '(3i3)', count(mask, 2)
end program test_count
@end smallexample
@end table



@node CPU_TIME
@section @code{CPU_TIME} --- CPU elapsed time in seconds
@fnindex CPU_TIME
@cindex time, elapsed

@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.

If a time source is available, time will be reported with microsecond
resolution. If no time source is available, @var{TIME} is set to
@code{-1.0}.

Note that @var{TIME} may contain a, system dependent, arbitrary offset
and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
value is meaningless, only differences between subsequent calls to
this subroutine, as shown in the example below, should be used.


@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL CPU_TIME(TIME)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
@end multitable

@item @emph{Return value}:
None

@item @emph{Example}:
@smallexample
program test_cpu_time
    real :: start, finish
    call cpu_time(start)
        ! put code to test here
    call cpu_time(finish)
    print '("Time = ",f6.3," seconds.")',finish-start
end program test_cpu_time
@end smallexample

@item @emph{See also}:
@ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
@end table



@node CSHIFT
@section @code{CSHIFT} --- Circular shift elements of an array
@fnindex CSHIFT
@cindex array, shift circularly
@cindex array, permutation
@cindex array, rotate

@table @asis
@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 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
sections of @var{ARRAY} along the given dimension are shifted.  Elements
shifted out one end of each rank one section are shifted back in the other end.

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY}  @tab Shall be an array of any type.
@item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
@item @var{DIM}    @tab The type shall be @code{INTEGER}.
@end multitable

@item @emph{Return value}:
Returns an array of same type and rank as the @var{ARRAY} argument.

@item @emph{Example}:
@smallexample
program test_cshift
    integer, dimension(3,3) :: a
    a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
    print '(3i3)', a(1,:)
    print '(3i3)', a(2,:)
    print '(3i3)', a(3,:)    
    a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
    print *
    print '(3i3)', a(1,:)
    print '(3i3)', a(2,:)
    print '(3i3)', a(3,:)
end program test_cshift
@end smallexample
@end table



@node CTIME
@section @code{CTIME} --- Convert a time into a string
@fnindex CTIME
@cindex time, conversion to string
@cindex conversion, to string

@table @asis
@item @emph{Description}:
@code{CTIME} converts a system time value, such as returned by
@code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.

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, function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{CALL CTIME(TIME, RESULT)}.
@item @code{RESULT = CTIME(TIME)}, (not recommended).
@end multitable

@item @emph{Arguments}:
@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.
@end multitable

@item @emph{Return value}:
The converted date and time as a string.

@item @emph{Example}:
@smallexample
program test_ctime
    integer(8) :: i
    character(len=30) :: date
    i = time8()

    ! Do something, main part of the program
    
    call ctime(i,date)
    print *, 'Program was started on ', date
end program test_ctime
@end smallexample

@item @emph{See Also}:
@ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
@end table



@node DATE_AND_TIME
@section @code{DATE_AND_TIME} --- Date and time subroutine
@fnindex DATE_AND_TIME
@cindex date, current
@cindex current date
@cindex time, current
@cindex current time

@table @asis
@item @emph{Description}:
@code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
time information from the real-time system clock.  @var{DATE} is
@code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
representing the difference with respect to Coordinated Universal Time (UTC).
Unavailable time and date parameters return blanks.

@var{VALUES} is @code{INTENT(OUT)} and provides the following:

@multitable @columnfractions .15 .30 .40
@item @tab @code{VALUE(1)}: @tab The year
@item @tab @code{VALUE(2)}: @tab The month
@item @tab @code{VALUE(3)}: @tab The day of the month
@item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
@item @tab @code{VALUE(5)}: @tab The hour of the day
@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

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}

@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.
@item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
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.
@item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
@end multitable

@item @emph{Return value}:
None

@item @emph{Example}:
@smallexample
program test_time_and_date
    character(8)  :: date
    character(10) :: time
    character(5)  :: zone
    integer,dimension(8) :: values
    ! using keyword arguments
    call date_and_time(date,time,zone,values)
    call date_and_time(DATE=date,ZONE=zone)
    call date_and_time(TIME=time)
    call date_and_time(VALUES=values)
    print '(a,2x,a,2x,a)', date, time, zone
    print '(8i5))', values
end program test_time_and_date
@end smallexample

@item @emph{See also}:
@ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
@end table



@node DBLE
@section @code{DBLE} --- Double conversion function 
@fnindex DBLE
@cindex conversion, to real

@table @asis
@item @emph{Description}:
@code{DBLE(A)} Converts @var{A} to double precision real type.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = DBLE(A)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
or @code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value is of type double precision real.

@item @emph{Example}:
@smallexample
program test_dble
    real    :: x = 2.18
    integer :: i = 5
    complex :: z = (2.3,1.14)
    print *, dble(x), dble(i), dble(z)
end program test_dble
@end smallexample

@item @emph{See also}:
@ref{REAL}
@end table



@node DCMPLX
@section @code{DCMPLX} --- Double complex conversion function
@fnindex DCMPLX
@cindex complex numbers, conversion to
@cindex conversion, to complex

@table @asis
@item @emph{Description}:
@code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
converted to the real component.  If @var{Y} is present it is converted to the
imaginary component.  If @var{Y} is not present then the imaginary component is
set to 0.0.  If @var{X} is complex then @var{Y} must not be present.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = DCMPLX(X [, Y])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
or @code{COMPLEX}.
@item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
@code{INTEGER} or @code{REAL}. 
@end multitable

@item @emph{Return value}:
The return value is of type @code{COMPLEX(8)}

@item @emph{Example}:
@smallexample
program test_dcmplx
    integer :: i = 42
    real :: x = 3.14
    complex :: z
    z = cmplx(i, x)
    print *, dcmplx(i)
    print *, dcmplx(x)
    print *, dcmplx(z)
    print *, dcmplx(x,i)
end program test_dcmplx
@end smallexample
@end table


@node DIGITS
@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 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}:
Fortran 95 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = DIGITS(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER}.

@item @emph{Example}:
@smallexample
program test_digits
    integer :: i = 12345
    real :: x = 3.143
    real(8) :: y = 2.33
    print *, digits(i)
    print *, digits(x)
    print *, digits(y)
end program test_digits
@end smallexample
@end table



@node DIM
@section @code{DIM} --- Positive difference
@fnindex DIM
@fnindex IDIM
@fnindex DDIM
@cindex positive difference

@table @asis
@item @emph{Description}:
@code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
otherwise returns zero.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = DIM(X, Y)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
@item @var{Y} @tab The type shall be the same type and kind as @var{X}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER} or @code{REAL}.

@item @emph{Example}:
@smallexample
program test_dim
    integer :: i
    real(8) :: x
    i = dim(4, 15)
    x = dim(4.345_8, 2.111_8)
    print *, i
    print *, x
end program test_dim
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name             @tab Argument               @tab Return type       @tab Standard
@item @code{DIM(X,Y)}  @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
@item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
@item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
@end multitable
@end table



@node DOT_PRODUCT
@section @code{DOT_PRODUCT} --- Dot product function
@fnindex DOT_PRODUCT
@cindex dot product
@cindex vector product
@cindex product, vector

@table @asis
@item @emph{Description}:
@code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
either numeric or logical and must be arrays of rank one and of equal size. If
the vectors are @code{INTEGER} or @code{REAL}, the result is
@code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.  

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
@item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
@end multitable

@item @emph{Return value}:
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{Example}:
@smallexample
program test_dot_prod
    integer, dimension(3) :: a, b
    a = (/ 1, 2, 3 /)
    b = (/ 4, 5, 6 /)
    print '(3i3)', a
    print *
    print '(3i3)', b
    print *
    print *, dot_product(a,b)
end program test_dot_prod
@end smallexample
@end table



@node DPROD
@section @code{DPROD} --- Double product function
@fnindex DPROD
@cindex product, double-precision

@table @asis
@item @emph{Description}:
@code{DPROD(X,Y)} returns the product @code{X*Y}.

@item @emph{Standard}:
Fortran 77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = DPROD(X, Y)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}.
@item @var{Y} @tab The type shall be @code{REAL}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL(8)}.

@item @emph{Example}:
@smallexample
program test_dprod
    real :: x = 5.2
    real :: y = 2.3
    real(8) :: d
    d = dprod(x,y)
    print *, d
end program test_dprod
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name              @tab Argument               @tab Return type       @tab Standard
@item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
@end multitable

@end table


@node DREAL
@section @code{DREAL} --- Double real part function
@fnindex DREAL
@cindex complex numbers, real part

@table @asis
@item @emph{Description}:
@code{DREAL(Z)} returns the real part of complex variable @var{Z}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = DREAL(A)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab The type shall be @code{COMPLEX(8)}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL(8)}.

@item @emph{Example}:
@smallexample
program test_dreal
    complex(8) :: z = (1.3_8,7.2_8)
    print *, dreal(z)
end program test_dreal
@end smallexample

@item @emph{See also}:
@ref{AIMAG}

@end table



@node DSHIFTL
@section @code{DSHIFTL} --- Combined left shift
@fnindex DSHIFTL
@cindex left shift, combined
@cindex shift, left

@table @asis
@item @emph{Description}:
@code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
bits of @var{J}, and the remaining bits are the rightmost bits of
@var{I}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = DSHIFTL(I, J, SHIFT)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab Shall be of type @code{INTEGER}.
@item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
as @var{I}.
@item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
@end multitable

@item @emph{Return value}:
The return value has same type and kind as @var{I}.

@item @emph{See also}:
@ref{DSHIFTR}

@end table



@node DSHIFTR
@section @code{DSHIFTR} --- Combined right shift
@fnindex DSHIFTR
@cindex right shift, combined
@cindex shift, right

@table @asis
@item @emph{Description}:
@code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
bits of @var{I}, and the remaining bits are the leftmost bits of
@var{J}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = DSHIFTR(I, J, SHIFT)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab Shall be of type @code{INTEGER}.
@item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
as @var{I}.
@item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
@end multitable

@item @emph{Return value}:
The return value has same type and kind as @var{I}.

@item @emph{See also}:
@ref{DSHIFTL}

@end table



@node DTIME
@section @code{DTIME} --- Execution time subroutine (or function)
@fnindex DTIME
@cindex time, elapsed
@cindex elapsed time

@table @asis
@item @emph{Description}:
@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.

On some systems, the underlying timings are represented using types with
sufficiently small limits that overflows (wrap around) are possible, such as
32-bit types. 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.

Please note, that this implementation is thread safe if used within OpenMP
directives, i.e., its state will be consistent while called from multiple
threads. However, if @code{DTIME} is called from multiple threads, the result
is still the time since the last invocation. This may not give the intended
results. If possible, use @code{CPU_TIME} instead.

This intrinsic is provided in both subroutine and function forms; however,
only one form can be used in any given program unit.

@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:

@multitable @columnfractions .15 .30 .40
@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}:
GNU extension

@item @emph{Class}:
Subroutine, function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{CALL DTIME(VALUES, TIME)}.
@item @code{TIME = DTIME(VALUES)}, (not recommended).
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
@item @var{TIME}@tab The type shall be @code{REAL(4)}.
@end multitable

@item @emph{Return value}:
Elapsed time in seconds since the last invocation or since the start of program
execution if not called before.

@item @emph{Example}:
@smallexample
program test_dtime
    integer(8) :: i, j
    real, dimension(2) :: tarray
    real :: result
    call dtime(tarray, result)
    print *, result
    print *, tarray(1)
    print *, tarray(2)   
    do i=1,100000000    ! Just a delay
        j = i * i - i
    end do
    call dtime(tarray, result)
    print *, result
    print *, tarray(1)
    print *, tarray(2)
end program test_dtime
@end smallexample

@item @emph{See also}:
@ref{CPU_TIME}

@end table



@node EOSHIFT
@section @code{EOSHIFT} --- End-off shift elements of an array
@fnindex EOSHIFT
@cindex array, shift

@table @asis
@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 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 sections of @var{ARRAY} along the given dimension are
shifted.  Elements shifted out one end of each rank one section are dropped.  If
@var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
is copied back in the other end.  If @var{BOUNDARY} is not present then the
following are copied in depending on the type of @var{ARRAY}.

@multitable @columnfractions .15 .80
@item @emph{Array Type} @tab @emph{Boundary Value}
@item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
@item Logical  @tab @code{.FALSE.}.
@item Character(@var{len}) @tab @var{len} blanks.
@end multitable

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@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}.
@end multitable

@item @emph{Return value}:
Returns an array of same type and rank as the @var{ARRAY} argument.

@item @emph{Example}:
@smallexample
program test_eoshift
    integer, dimension(3,3) :: a
    a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
    print '(3i3)', a(1,:)
    print '(3i3)', a(2,:)
    print '(3i3)', a(3,:)    
    a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
    print *
    print '(3i3)', a(1,:)
    print '(3i3)', a(2,:)
    print '(3i3)', a(3,:)
end program test_eoshift
@end smallexample
@end table



@node EPSILON
@section @code{EPSILON} --- Epsilon function
@fnindex EPSILON
@cindex model representation, epsilon

@table @asis
@item @emph{Description}:
@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{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = EPSILON(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}.
@end multitable

@item @emph{Return value}:
The return value is of same type as the argument.

@item @emph{Example}:
@smallexample
program test_epsilon
    real :: x = 3.143
    real(8) :: y = 2.33
    print *, EPSILON(x)
    print *, EPSILON(y)
end program test_epsilon
@end smallexample
@end table



@node ERF
@section @code{ERF} --- Error function 
@fnindex ERF
@cindex error function

@table @asis
@item @emph{Description}:
@code{ERF(X)} computes the error function of @var{X}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ERF(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL}, of the same kind as
@var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.

@item @emph{Example}:
@smallexample
program test_erf
  real(8) :: x = 0.17_8
  x = erf(x)
end program test_erf
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
@end multitable
@end table



@node ERFC
@section @code{ERFC} --- Error function 
@fnindex ERFC
@cindex error function, complementary

@table @asis
@item @emph{Description}:
@code{ERFC(X)} computes the complementary error function of @var{X}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ERFC(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL} and of the same kind as @var{X}.
It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.

@item @emph{Example}:
@smallexample
program test_erfc
  real(8) :: x = 0.17_8
  x = erfc(x)
end program test_erfc
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
@end multitable
@end table



@node ERFC_SCALED
@section @code{ERFC_SCALED} --- Error function 
@fnindex ERFC_SCALED
@cindex error function, complementary, exponentially-scaled

@table @asis
@item @emph{Description}:
@code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
error function of @var{X}.

@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ERFC_SCALED(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL} and of the same kind as @var{X}.

@item @emph{Example}:
@smallexample
program test_erfc_scaled
  real(8) :: x = 0.17_8
  x = erfc_scaled(x)
end program test_erfc_scaled
@end smallexample
@end table



@node ETIME
@section @code{ETIME} --- Execution time subroutine (or function)
@fnindex ETIME
@cindex time, elapsed

@table @asis
@item @emph{Description}:
@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
32-bit types. 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.

This intrinsic is provided in both subroutine and function forms; however,
only one form can be used in any given program unit.

@var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:

@multitable @columnfractions .15 .30 .60
@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}:
GNU extension

@item @emph{Class}:
Subroutine, function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{CALL ETIME(VALUES, TIME)}.
@item @code{TIME = ETIME(VALUES)}, (not recommended).
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
@item @var{TIME}@tab The type shall be @code{REAL(4)}.
@end multitable

@item @emph{Return value}:
Elapsed time in seconds since the start of program execution.

@item @emph{Example}:
@smallexample
program test_etime
    integer(8) :: i, j
    real, dimension(2) :: tarray
    real :: result
    call ETIME(tarray, result)
    print *, result
    print *, tarray(1)
    print *, tarray(2)   
    do i=1,100000000    ! Just a delay
        j = i * i - i
    end do
    call ETIME(tarray, result)
    print *, result
    print *, tarray(1)
    print *, tarray(2)
end program test_etime
@end smallexample

@item @emph{See also}:
@ref{CPU_TIME}

@end table



@node EXECUTE_COMMAND_LINE
@section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
@fnindex EXECUTE_COMMAND_LINE
@cindex system, system call
@cindex command line

@table @asis
@item @emph{Description}:
@code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
asynchronously.

The @code{COMMAND} argument is passed to the shell and executed, using
the C library's @code{system()} call.  (The shell is @code{sh} on Unix
systems, and @code{cmd.exe} on Windows.)  If @code{WAIT} is present and
has the value false, the execution of the command is asynchronous if the
system supports it; otherwise, the command is executed synchronously.

The three last arguments allow the user to get status information.  After
synchronous execution, @code{EXITSTAT} contains the integer exit code of
the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
if the command line was executed (whatever its exit status was).
@code{CMDMSG} is assigned an error message if an error has occurred.


@item @emph{Standard}:
Fortran 2008 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
@item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
@item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
default kind.
@item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
default kind.
@item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
default kind.
@end multitable

@item @emph{Example}:
@smallexample
program test_exec
  integer :: i

  call execute_command_line ("external_prog.exe", exitstat=i)
  print *, "Exit status of external_prog.exe was ", i

  call execute_command_line ("reindex_files.exe", wait=.false.)
  print *, "Now reindexing files in the background"

end program test_exec
@end smallexample


@item @emph{Note}:

Because this intrinsic is implemented in terms of the @code{system()}
function call, its behavior with respect to signaling is processor
dependent. In particular, on POSIX-compliant systems, the SIGINT and
SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
such, if the parent process is terminated, the child process might not be
terminated alongside.


@item @emph{See also}:
@ref{SYSTEM}
@end table



@node EXIT
@section @code{EXIT} --- Exit the program with status. 
@fnindex EXIT
@cindex program termination
@cindex terminate program

@table @asis
@item @emph{Description}:
@code{EXIT} causes immediate termination of the program with status.  If status
is omitted it returns the canonical @emph{success} for the system.  All Fortran
I/O units are closed. 

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL EXIT([STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
@end multitable

@item @emph{Return value}:
@code{STATUS} is passed to the parent process on exit.

@item @emph{Example}:
@smallexample
program test_exit
  integer :: STATUS = 0
  print *, 'This program is going to exit.'
  call EXIT(STATUS)
end program test_exit
@end smallexample

@item @emph{See also}:
@ref{ABORT}, @ref{KILL}
@end table



@node EXP
@section @code{EXP} --- Exponential function 
@fnindex EXP
@fnindex DEXP
@fnindex CEXP
@fnindex ZEXP
@fnindex CDEXP
@cindex exponential function
@cindex logarithmic function, inverse

@table @asis
@item @emph{Description}:
@code{EXP(X)} computes the base @math{e} exponential of @var{X}.

@item @emph{Standard}:
Fortran 77 and later, has overloads that are GNU extensions

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = EXP(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL} or
@code{COMPLEX}.
@end multitable

@item @emph{Return value}:
The return value has same type and kind as @var{X}.

@item @emph{Example}:
@smallexample
program test_exp
  real :: x = 1.0
  x = exp(x)
end program test_exp
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument             @tab Return type         @tab Standard
@item @code{EXP(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}      @tab Fortran 77 and later
@item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
@item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
@item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
@item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
@end multitable
@end table



@node EXPONENT
@section @code{EXPONENT} --- Exponent function 
@fnindex EXPONENT
@cindex real number, exponent
@cindex floating point, exponent

@table @asis
@item @emph{Description}:
@code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
is zero the value returned is zero. 

@item @emph{Standard}:
Fortran 95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = EXPONENT(X)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be @code{REAL}.
@end multitable

@item @emph{Return value}:
The return value is of type default @code{INTEGER}.

@item @emph{Example}:
@smallexample
program test_exponent
  real :: x = 1.0
  integer :: i
  i = exponent(x)
  print *, i
  print *, exponent(0.0)
end program test_exponent
@end smallexample
@end table



@node EXTENDS_TYPE_OF
@section @code{EXTENDS_TYPE_OF} ---  Query dynamic type for extension
@fnindex EXTENDS_TYPE_OF

@table @asis
@item @emph{Description}:
Query dynamic type for extension.

@item @emph{Standard}:
Fortran 2003 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be an object of extensible declared type or
unlimited polymorphic. 
@item @var{MOLD} @tab Shall be an object of extensible declared type or
unlimited polymorphic. 
@end multitable

@item @emph{Return value}:
The return value is a scalar of type default logical. It is true if and only if
the dynamic type of A is an extension type of the dynamic type of MOLD.


@item @emph{See also}:
@ref{SAME_TYPE_AS}
@end table



@node FDATE
@section @code{FDATE} --- Get the current time as a string
@fnindex FDATE
@cindex time, current
@cindex current time
@cindex date, current
@cindex current date

@table @asis
@item @emph{Description}:
@code{FDATE(DATE)} returns the current date (using the same format as
@code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
TIME())}.

This intrinsic is provided in both subroutine and function forms; however,
only one form can be used in any given program unit.

@var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the