Merged with mainline at revision 126229.

[official-gcc.git] / gcc / fortran / intrinsic.texi

@ignore
Copyright (C) 2005, 2006, 2007
Free Software Foundation, Inc.
This is part of the GNU Fortran manual.   
For copying conditions, see the file gfortran.texi.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``GNU General Public License'' and ``Funding
Free Software'', the Front-Cover texts being (a) (see below), and with
the Back-Cover Texts being (b) (see below).  A copy of the license is
included in the gfdl(7) man page.


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,     Hyperbolic arccosine 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,     Hyperbolic arcsine 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,     Hyperbolic arctangent function
* @code{BESJ0}:         BESJ0,     Bessel function of the first kind of order 0
* @code{BESJ1}:         BESJ1,     Bessel function of the first kind of order 1
* @code{BESJN}:         BESJN,     Bessel function of the first kind
* @code{BESY0}:         BESY0,     Bessel function of the second kind of order 0
* @code{BESY1}:         BESY1,     Bessel function of the second kind of order 1
* @code{BESYN}:         BESYN,     Bessel function of the second kind
* @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
* @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{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{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{DFLOAT}:        DFLOAT,    Double precision 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{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{ETIME}:         ETIME,     Execution time subroutine (or function)
* @code{EXIT}:          EXIT,      Exit the program with status.
* @code{EXP}:           EXP,       Exponential function
* @code{EXPONENT}:      EXPONENT,  Exponent function
* @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{FLOAT}:         FLOAT,     Convert integer to default real
* @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{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{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
* @code{IAND}:          IAND,      Bitwise logical and
* @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{INDEX}:         INDEX,     Position of a substring within a string
* @code{INT}:           INT,       Convert to integer type
* @code{INT2}:          INT2,      Convert to 16-bit integer type
* @code{INT8}:          INT8,      Convert to 64-bit integer type
* @code{IOR}:           IOR,       Bitwise logical or
* @code{IRAND}:         IRAND,     Integer pseudo-random number
* @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
* @code{ISHFT}:         ISHFT,     Shift bits
* @code{ISHFTC}:        ISHFTC,    Shift bits circularly
* @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{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{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{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{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{NOT}:           NOT,       Logical negation
* @code{NULL}:          NULL,      Function that returns an disassociated pointer
* @code{OR}:            OR,        Bitwise logical OR
* @code{PACK}:          PACK,      Pack an array into an array of rank one
* @code{PERROR}:        PERROR,    Print system error message
* @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 of a real kind
* @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{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_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{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{SNGL}:          SNGL,      Convert double precision real to default real
* @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{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{TIME}:          TIME,      Time function
* @code{TIME8}:         TIME8,     Time function (64-bit)
* @code{TINY}:          TINY,      Smallest positive number of a real kind
* @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{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 small
selection of intrinsic procedures from the Fortran 2003 standard.  Any
conflict between a description here and a description in either the
Fortran 95 standard or the Fortran 2003 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,
which is suitable for debugging purposes.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental 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(X)} computes the absolute value of @code{X}.

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

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @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{CABS(Z)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab F77 and later
@item @code{DABS(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab F77 and later
@item @code{IABS(I)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
@item @code{ZABS(Z)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
@item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @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} 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} 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}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ACHAR(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{CHARACTER} with a length of one.  The
kind type parameter is the same as  @code{KIND('A')}.

@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}:
F77 and 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 be @code{REAL(*)} with a magnitude that is
less than one.
@end multitable

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

@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{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 and later
@end multitable

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

@end table



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

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

@item @emph{Standard}:
GNU extension

@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(*)} with a magnitude that is
greater or equal to one.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL(*)} and it lies in the
range @math{0 \leq \acosh (x) \leq \infty}.

@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(STR)} will left adjust a string by removing leading spaces.
Spaces are inserted at the end of the string as needed.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@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} where leading spaces 
are removed and the same number of spaces are inserted on the end
of @var{STR}.

@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(STR)} will right adjust a string by removing trailing spaces.
Spaces are inserted at the start of the string as needed.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@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} where trailing spaces 
are removed and the same number of spaces are inserted at the start
of @var{STR}.

@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}:
F77 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 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{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(X [, KIND])} truncates its argument to a whole number.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
@item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
                      expression indicating the kind parameter of
                      the result.
@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 the magnitude of 
@var{X} is less than one, then @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{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab F77 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}:
F95 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(X)} checks the status of whether @var{X} is allocated.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

@item @emph{Return value}:
The return value is a scalar @code{LOGICAL} with the default logical
kind type parameter.  If @var{X} is allocated, @code{ALLOCATED(X)}
is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.} 

@item @emph{Example}:
@smallexample
program test_allocated
  integer :: i = 4
  real(4), allocatable :: x(:)
  if (allocated(x) .eqv. .false.) 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}:
Non-elemental 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 @code{INTEGER(*)} or @code{LOGICAL}.
@item @var{J} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
@end multitable

@item @emph{Return value}:
The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
cross-promotion of the arguments. 

@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}:
F95 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(X [, KIND])} rounds its argument to the nearest whole number.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X}    @tab The type of the argument shall be @code{REAL(*)}.
@item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
                      expression indicating the kind parameter of
                      the result.
@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{X} is greater than
zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}.  If @var{X} 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{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab F77 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}:
F95 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}:
F77 and 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 @code{REAL(*)}, and a magnitude that is
less than one.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL(*)} and it lies in the
range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}.  The kind type
parameter is the same as @var{X}.

@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{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 and later
@end multitable

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

@end table



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

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

@item @emph{Standard}:
GNU extension

@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(*)}, with @var{X} a real number.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL(*)} and it lies in the
range @math{-\infty \leq \asinh (x) \leq \infty}.

@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(PTR [, TGT])} determines the status of the pointer @var{PTR}
or if @var{PTR} is associated with the target @var{TGT}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

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

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ATAN(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 it lies in the
range @math{ - \pi / 2 \leq \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{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 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 arctangent of the complex number
@math{X + i Y}.

@item @emph{Standard}:
F77 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{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
@end multitable
@end table



@node ATANH
@section @code{ATANH} --- Hyperbolic arctangent function
@fnindex ASINH
@fnindex DASINH
@cindex area hyperbolic tangent
@cindex hyperbolic arctangent
@cindex hyperbolic function, tangent, inverse
@cindex tangent, hyperbolic, inverse

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

@item @emph{Standard}:
GNU extension

@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(*)} with a magnitude
that is less than or equal to one.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL(*)} and it lies in the
range @math{-\infty \leq \atanh(x) \leq \infty}.

@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 BESJ0
@section @code{BESJ0} --- Bessel function of the first kind of order 0
@fnindex BESJ0
@fnindex DBESJ0
@cindex Bessel function, first kind

@table @asis
@item @emph{Description}:
@code{BESJ0(X)} computes the Bessel function of the first kind of order 0
of @var{X}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESJ0(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.4027... \leq Bessel (0,x) \leq 1}.

@item @emph{Example}:
@smallexample
program test_besj0
  real(8) :: x = 0.0_8
  x = besj0(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 BESJ1
@section @code{BESJ1} --- Bessel function of the first kind of order 1
@fnindex BESJ1
@fnindex DBESJ1
@cindex Bessel function, first kind

@table @asis
@item @emph{Description}:
@code{BESJ1(X)} computes the Bessel function of the first kind of order 1
of @var{X}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESJ1(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 }.

@item @emph{Example}:
@smallexample
program test_besj1
  real(8) :: x = 1.0_8
  x = besj1(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 BESJN
@section @code{BESJN} --- Bessel function of the first kind
@fnindex BESJN
@fnindex DBESJN
@cindex Bessel function, first kind

@table @asis
@item @emph{Description}:
@code{BESJN(N, X)} computes the Bessel function of the first kind of order
@var{N} of @var{X}.

If both arguments are arrays, their ranks and shapes shall conform.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESJN(N, 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{X} @tab Shall be a scalar or an array of type  @code{REAL(*)}.
@end multitable

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

@item @emph{Example}:
@smallexample
program test_besjn
  real(8) :: x = 1.0_8
  x = besjn(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(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 BESY0
@section @code{BESY0} --- Bessel function of the second kind of order 0
@fnindex BESY0
@fnindex DBESY0
@cindex Bessel function, second kind

@table @asis
@item @emph{Description}:
@code{BESY0(X)} computes the Bessel function of the second kind of order 0
of @var{X}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESY0(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(*)}.

@item @emph{Example}:
@smallexample
program test_besy0
  real(8) :: x = 0.0_8
  x = besy0(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 BESY1
@section @code{BESY1} --- Bessel function of the second kind of order 1
@fnindex BESY1
@fnindex DBESY1
@cindex Bessel function, second kind

@table @asis
@item @emph{Description}:
@code{BESY1(X)} computes the Bessel function of the second kind of order 1
of @var{X}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESY1(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(*)}.

@item @emph{Example}:
@smallexample
program test_besy1
  real(8) :: x = 1.0_8
  x = besy1(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 BESYN
@section @code{BESYN} --- Bessel function of the second kind
@fnindex BESYN
@fnindex DBESYN
@cindex Bessel function, second kind

@table @asis
@item @emph{Description}:
@code{BESYN(N, X)} computes the Bessel function of the second kind of order
@var{N} of @var{X}.

If both arguments are arrays, their ranks and shapes shall conform.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = BESYN(N, 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{X} @tab Shall be a scalar or an array of type  @code{REAL(*)}.
@end multitable

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

@item @emph{Example}:
@smallexample
program test_besyn
  real(8) :: x = 1.0_8
  x = besyn(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 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}.

@item @emph{Standard}:
F95 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 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.

@item @emph{Standard}:
F95 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 associatation status, C pointer
@cindex pointer, C associatation status

@table @asis
@item @emph{Description}:
@code{C_ASSOICATED(c_prt1[, c_ptr2])} determines the status of the C pointer @var{c_ptr1}
or if @var{c_ptr1} is associated with the target @var{c_ptr2}.

@item @emph{Standard}:
F2003 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{RESULT = C_ASSOICATED(c_prt1[, c_ptr2])}

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

@item @emph{Return value}:
The return value is of type @code{LOGICAL}; it is @code{.false.} if either
@var{c_ptr1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr2}
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}:
F2003 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}.

Note: Due to the currently lacking support of procedure pointers in GNU Fortran
this function is not fully operable.

@item @emph{Standard}:
F2003 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}:
F2003 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}:
F2003 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{x} @tab Associated scalar pointer or interoperatable scalar
                   or allocated allocatable variable with @code{TARGET}
                   attribute.
@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 CEILING
@section @code{CEILING} --- Integer ceiling function
@fnindex CEILING
@cindex ceiling
@cindex rounding, ceiling

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

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

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

@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}:
F77 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{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, non-elemental 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(*)} 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 non-zero 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, non-elemental 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} 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} 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 non-zero otherwise.
@end multitable

@item @emph{Return value}:
In either syntax, @var{STATUS} is set to @code{0} on success and non-zero
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 non-elemental 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}:
F77 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}:
F2003

@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 of type @code{INTEGER(4)}

@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 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}:
F77 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{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}:
F77 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 type @code{REAL(*)} and it lies in the
range @math{ -1 \leq \cos (x) \leq 1}.  The kind type
parameter is the same as @var{X}.

@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{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab F77 and later
@item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 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}:
F77 and 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(*)}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{REAL(*)} and it is positive
(@math{ \cosh (x) \geq 0 }.

@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{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F77 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}:
@code{COUNT(MASK [, DIM])} counts the number of @code{.TRUE.} elements of
@var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{MASK}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
transformational function

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

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

@item @emph{Return value}:
The return value is of type @code{INTEGER} with rank equal to that of
@var{MASK}.

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

@item @emph{Standard}:
F95 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 scaler 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}:
F95 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

@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}.
@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}:
F95 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(8)} or larger.
@item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
@item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
@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(X)} Converts @var{X} to double precision real type.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @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{DFLOAT}, @ref{FLOAT}, @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 DFLOAT
@section @code{DFLOAT} --- Double conversion function 
@fnindex DFLOAT
@cindex conversion, to real

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

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

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

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

@item @emph{Example}:
@smallexample
program test_dfloat
    integer :: i = 5
    print *, dfloat(i)
end program test_dfloat
@end smallexample

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



@node DIGITS
@section @code{DIGITS} --- Significant digits function
@fnindex DIGITS
@cindex model representation, significant digits

@table @asis
@item @emph{Description}:
@code{DIGITS(X)} returns the number of significant digits of the internal model
representation of @var{X}.  For example, on a system using a 32-bit
floating point representation, a default real number would likely return 24.

@item @emph{Standard}:
F95 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}:
F77 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{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
@item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}    @tab @code{REAL(8)}    @tab F77 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(X,Y)} computes the dot product multiplication of two vectors
@var{X} and @var{Y}.  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(X*Y)}. If the
vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the 
vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
transformational function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
@item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
@end multitable

@item @emph{Return value}:
If the arguments are numeric, the return value is a scaler 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}:
F77 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
@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(Z)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{Z} @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 DTIME
@section @code{DTIME} --- Execution time subroutine (or function)
@fnindex DTIME
@cindex time, elapsed
@cindex elapsed time

@table @asis
@item @emph{Description}:
@code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
returns the user and system components of this time in @code{TARRAY(1)} and
@code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
TARRAY(2)}.

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.

If @code{DTIME} is invoked as a function, it can not be invoked as a
subroutine, and vice versa.

@var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:

@multitable @columnfractions .15 .30 .40
@item @tab @code{TARRAY(1)}: @tab User time in seconds.
@item @tab @code{TARRAY(2)}: @tab System time in seconds.
@item @tab @code{RESULT}: @tab Run time since start in seconds.
@end multitable

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

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

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

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

@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
@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 scaler 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}:
F95 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 scaler.
@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 a nearly negligible number relative to @code{1}.

@item @emph{Standard}:
F95 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}:
GNU Extension

@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(*)}, and it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is a scalar of type @code{REAL(*)} and it is positive
(@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}:
GNU extension

@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(*)}, and it shall be scalar.
@end multitable

@item @emph{Return value}:
The return value is a scalar of type @code{REAL(*)} and it is positive
(@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 ETIME
@section @code{ETIME} --- Execution time subroutine (or function)
@fnindex ETIME
@cindex time, elapsed

@table @asis
@item @emph{Description}:
@code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
returns the user and system components of this time in @code{TARRAY(1)} and
@code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.

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.

If @code{ETIME} is invoked as a function, it can not be invoked as a
subroutine, and vice versa.

@var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:

@multitable @columnfractions .15 .30 .60
@item @tab @code{TARRAY(1)}: @tab User time in seconds.
@item @tab @code{TARRAY(2)}: @tab System time in seconds.
@item @tab @code{RESULT}: @tab Run time since start in seconds.
@end multitable

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
@item @var{RESULT}@tab The type shall be @code{REAL}.
@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 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}:
F77 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{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab F77 and later
@item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab F77 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}:
F95 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 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())}.

If @code{FDATE} is invoked as a function, it can not be invoked as a
subroutine, and vice versa.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

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

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

@item @emph{Return value}:
The current date as a string.

@item @emph{Example}:
@smallexample
program test_fdate
    integer(8) :: i, j
    character(len=30) :: date
    call fdate(date)
    print *, 'Program started on ', date
    do i = 1, 100000000 ! Just a delay
        j = i * i - i
    end do
    call fdate(date)
    print *, 'Program ended on ', date
end program test_fdate
@end smallexample
@end table



@node FLOAT
@section @code{FLOAT} --- Convert integer to default real
@fnindex FLOAT
@cindex conversion, to real

@table @asis
@item @emph{Description}:
@code{FLOAT(I)} converts the integer @var{I} to a default real value.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = FLOAT(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 default @code{REAL}.

@item @emph{Example}:
@smallexample
program test_float
    integer :: i = 1
    if (float(i) /= 1.) call abort
end program test_float
@end smallexample

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



@node FGET
@section @code{FGET} --- Read a single character in stream mode from stdin 
@fnindex FGET
@cindex read character, stream mode
@cindex stream mode, read character
@cindex file operation, read character

@table @asis
@item @emph{Description}:
Read a single character in stream mode from stdin by bypassing normal 
formatted output. Stream I/O should not be mixed with normal record-oriented 
(formatted or unformatted) I/O on the same unit; the results are unpredictable.

This intrinsic routine is provided for backwards compatibility with 
@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
Programmers should consider the use of new stream IO feature in new code 
for future portability. See also @ref{Fortran 2003 status}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL FGET(C [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C}      @tab The type shall be @code{CHARACTER}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
                        Returns 0 on success, -1 on end-of-file, and a
                        system specific positive error code otherwise.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_fget
  INTEGER, PARAMETER :: strlen = 100
  INTEGER :: status, i = 1
  CHARACTER(len=strlen) :: str = ""

  WRITE (*,*) 'Enter text:'
  DO
    CALL fget(str(i:i), status)
    if (status /= 0 .OR. i > strlen) exit
    i = i + 1
  END DO
  WRITE (*,*) TRIM(str)
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
@end table



@node FGETC
@section @code{FGETC} --- Read a single character in stream mode
@fnindex FGETC
@cindex read character, stream mode
@cindex stream mode, read character
@cindex file operation, read character

@table @asis
@item @emph{Description}:
Read a single character in stream mode by bypassing normal formatted output. 
Stream I/O should not be mixed with normal record-oriented (formatted or 
unformatted) I/O on the same unit; the results are unpredictable.

This intrinsic routine is provided for backwards compatibility with 
@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
Programmers should consider the use of new stream IO feature in new code 
for future portability. See also @ref{Fortran 2003 status}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL FGETC(UNIT, C [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT}   @tab The type shall be @code{INTEGER}.
@item @var{C}      @tab The type shall be @code{CHARACTER}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
                        -1 on end-of-file and a system specific positive error code otherwise.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_fgetc
  INTEGER :: fd = 42, status
  CHARACTER :: c

  OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
  DO
    CALL fgetc(fd, c, status)
    IF (status /= 0) EXIT
    call fput(c)
  END DO
  CLOSE(UNIT=fd)
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{FGET}, @ref{FPUT}, @ref{FPUTC}
@end table



@node FLOOR
@section @code{FLOOR} --- Integer floor function
@fnindex FLOOR
@cindex floor
@cindex rounding, floor

@table @asis
@item @emph{Description}:
@code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

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

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

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

@end table



@node FLUSH
@section @code{FLUSH} --- Flush I/O unit(s)
@fnindex FLUSH
@cindex file operation, flush

@table @asis
@item @emph{Description}:
Flushes Fortran unit(s) currently open for output. Without the optional
argument, all units are flushed, otherwise just the unit specified.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL FLUSH(UNIT)}

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

@item @emph{Note}:
Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
statement that should be preferred over the @code{FLUSH} intrinsic.

@end table



@node FNUM
@section @code{FNUM} --- File number function
@fnindex FNUM
@cindex file operation, file number

@table @asis
@item @emph{Description}:
@code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
open Fortran I/O unit @code{UNIT}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT} @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_fnum
  integer :: i
  open (unit=10, status = "scratch")
  i = fnum(10)
  print *, i
  close (10)
end program test_fnum
@end smallexample
@end table



@node FPUT
@section @code{FPUT} --- Write a single character in stream mode to stdout 
@fnindex FPUT
@cindex write character, stream mode
@cindex stream mode, write character
@cindex file operation, write character

@table @asis
@item @emph{Description}:
Write a single character in stream mode to stdout by bypassing normal 
formatted output. Stream I/O should not be mixed with normal record-oriented 
(formatted or unformatted) I/O on the same unit; the results are unpredictable.

This intrinsic routine is provided for backwards compatibility with 
@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
Programmers should consider the use of new stream IO feature in new code 
for future portability. See also @ref{Fortran 2003 status}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL FPUT(C [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C}      @tab The type shall be @code{CHARACTER}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
                        -1 on end-of-file and a system specific positive error code otherwise.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_fput
  CHARACTER(len=10) :: str = "gfortran"
  INTEGER :: i
  DO i = 1, len_trim(str)
    CALL fput(str(i:i))
  END DO
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{FPUTC}, @ref{FGET}, @ref{FGETC}
@end table



@node FPUTC
@section @code{FPUTC} --- Write a single character in stream mode
@fnindex FPUTC
@cindex write character, stream mode
@cindex stream mode, write character
@cindex file operation, write character

@table @asis
@item @emph{Description}:
Write a single character in stream mode by bypassing normal formatted 
output. Stream I/O should not be mixed with normal record-oriented 
(formatted or unformatted) I/O on the same unit; the results are unpredictable.

This intrinsic routine is provided for backwards compatibility with 
@command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
Programmers should consider the use of new stream IO feature in new code 
for future portability. See also @ref{Fortran 2003 status}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL FPUTC(UNIT, C [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT}   @tab The type shall be @code{INTEGER}.
@item @var{C}      @tab The type shall be @code{CHARACTER}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
                        -1 on end-of-file and a system specific positive error code otherwise.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_fputc
  CHARACTER(len=10) :: str = "gfortran"
  INTEGER :: fd = 42, i

  OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
  DO i = 1, len_trim(str)
    CALL fputc(fd, str(i:i))
  END DO
  CLOSE(fd)
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{FPUT}, @ref{FGET}, @ref{FGETC}
@end table



@node FRACTION
@section @code{FRACTION} --- Fractional part of the model representation
@fnindex FRACTION
@cindex real number, fraction
@cindex floating point, fraction

@table @asis
@item @emph{Description}:
@code{FRACTION(X)} returns the fractional part of the model
representation of @code{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

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

@item @emph{Return value}:
The return value is of the same type and kind as the argument.
The fractional part of the model representation of @code{X} is returned;
it is @code{X * RADIX(X)**(-EXPONENT(X))}.

@item @emph{Example}:
@smallexample
program test_fraction
  real :: x
  x = 178.1387e-4
  print *, fraction(x), x * radix(x)**(-exponent(x))
end program test_fraction
@end smallexample

@end table



@node FREE
@section @code{FREE} --- Frees memory
@fnindex FREE
@cindex pointer, cray

@table @asis
@item @emph{Description}:
Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
intrinsic is an extension intended to be used with Cray pointers, and is
provided in GNU Fortran to allow user to compile legacy code. For
new code using Fortran 95 pointers, the memory de-allocation intrinsic is
@code{DEALLOCATE}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL FREE(PTR)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
location of the memory that should be de-allocated.
@end multitable

@item @emph{Return value}:
None

@item @emph{Example}:
See @code{MALLOC} for an example.

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



@node FSEEK
@section @code{FSEEK} --- Low level file positioning subroutine
@fnindex FSEEK
@cindex file operation, seek
@cindex file operation, position

@table @asis
@item @emph{Description}:
Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE} 
is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
if set to 1, @var{OFFSET} is taken to be relative to the current position 
@code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
On error, @var{STATUS} is set to a non-zero value. If @var{STATUS} the seek 
fails silently.

This intrinsic routine is not fully backwards compatible with @command{g77}. 
In @command{g77}, the @code{FSEEK} takes a statement label instead of a 
@var{STATUS} variable. If FSEEK is used in old code, change
@smallexample
  CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
@end smallexample 
to
@smallexample
  INTEGER :: status
  CALL FSEEK(UNIT, OFFSET, WHENCE, status)
  IF (status /= 0) GOTO label
@end smallexample 

Please note that GNU Fortran provides the Fortran 2003 Stream facility.
Programmers should consider the use of new stream IO feature in new code 
for future portability. See also @ref{Fortran 2003 status}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
@item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
@item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
Its value shall be either 0, 1 or 2.
@item @var{STATUS} @tab (Optional) shall be a scalar of type 
@code{INTEGER(4)}.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_fseek
  INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
  INTEGER :: fd, offset, ierr

  ierr   = 0
  offset = 5
  fd     = 10

  OPEN(UNIT=fd, FILE="fseek.test")
  CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
  print *, FTELL(fd), ierr

  CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
  print *, FTELL(fd), ierr

  CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
  print *, FTELL(fd), ierr

  CLOSE(UNIT=fd)
END PROGRAM
@end smallexample

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



@node FSTAT
@section @code{FSTAT} --- Get file status
@fnindex FSTAT
@cindex file system, file status

@table @asis
@item @emph{Description}:
@code{FSTAT} is identical to @ref{STAT}, except that information about an 
already opened file is obtained.

The elements in @code{BUFF} are the same as described by @ref{STAT}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL FSTAT(UNIT, BUFF [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
@item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 
                        on success and a system specific error code otherwise.
@end multitable

@item @emph{Example}:
See @ref{STAT} for an example.

@item @emph{See also}:
To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
@end table



@node FTELL
@section @code{FTELL} --- Current stream position
@fnindex FTELL
@cindex file operation, position

@table @asis
@item @emph{Description}:
Retrieves the current position within an open file.

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 FTELL(UNIT, OFFSET)}
@item @code{OFFSET = FTELL(UNIT)}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
@item @var{UNIT}    @tab Shall of type @code{INTEGER}.
@end multitable

@item @emph{Return value}:
In either syntax, @var{OFFSET} is set to the current offset of unit
number @var{UNIT}, or to @math{-1} if the unit is not currently open.

@item @emph{Example}:
@smallexample
PROGRAM test_ftell
  INTEGER :: i
  OPEN(10, FILE="temp.dat")
  CALL ftell(10,i)
  WRITE(*,*) i
END PROGRAM
@end smallexample

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



@node GERROR
@section @code{GERROR} --- Get last system error message
@fnindex GERROR
@cindex system, error handling

@table @asis
@item @emph{Description}:
Returns the system error message corresponding to the last system error.
This resembles the functionality of @code{strerror(3)} in C.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GERROR(RESULT)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{RESULT}  @tab Shall of type @code{CHARACTER(*)}.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_gerror
  CHARACTER(len=100) :: msg
  CALL gerror(msg)
  WRITE(*,*) msg
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{IERRNO}, @ref{PERROR}
@end table



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

@table @asis
@item @emph{Description}:
Retrieve the @var{N}th argument that was passed on the
command line when the containing program was invoked.

This intrinsic routine is provided for backwards compatibility with 
GNU Fortran 77.  In new code, programmers should consider the use of 
the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003 
standard.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GETARG(N, ARG)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{N}   @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
@item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}. 
@end multitable

@item @emph{Return value}:
After @code{GETARG} returns, the @var{ARG} argument holds the @var{N}th 
command line argument. If @var{ARG} can not hold the argument, it is 
truncated to fit the length of @var{ARG}. If there are less than @var{N}
arguments specified at the command line, @var{ARG} will be filled with blanks.
If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
that support this feature).

@item @emph{Example}:
@smallexample
PROGRAM test_getarg
  INTEGER :: i
  CHARACTER(len=32) :: arg

  DO i = 1, iargc()
    CALL getarg(i, arg)
    WRITE (*,*) arg
  END DO
END PROGRAM
@end smallexample

@item @emph{See also}:
GNU Fortran 77 compatibility function: @ref{IARGC}

F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
@ref{COMMAND_ARGUMENT_COUNT}
@end table



@node GET_COMMAND
@section @code{GET_COMMAND} --- Get the entire command line
@fnindex GET_COMMAND
@cindex command-line arguments
@cindex arguments, to program

@table @asis
@item @emph{Description}:
Retrieve the entire command line that was used to invoke the program.

@item @emph{Standard}:
F2003

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GET_COMMAND(CMD)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}. 
@end multitable

@item @emph{Return value}:
Stores the entire command line that was used to invoke the program in @var{ARG}. 
If @var{ARG} is not large enough, the command will be truncated. 

@item @emph{Example}:
@smallexample
PROGRAM test_get_command
  CHARACTER(len=255) :: cmd
  CALL get_command(cmd)
  WRITE (*,*) TRIM(cmd)
END PROGRAM
@end smallexample

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



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

@table @asis
@item @emph{Description}:
Retrieve the @var{N}th argument that was passed on the
command line when the containing program was invoked.

@item @emph{Standard}:
F2003

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GET_COMMAND_ARGUMENT(N, ARG)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{N}   @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
@item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}. 
@end multitable

@item @emph{Return value}:
After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the 
@var{N}th command line argument. If @var{ARG} can not hold the argument, it is 
truncated to fit the length of @var{ARG}. If there are less than @var{N}
arguments specified at the command line, @var{ARG} will be filled with blanks. 
If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
that support this feature).

@item @emph{Example}:
@smallexample
PROGRAM test_get_command_argument
  INTEGER :: i
  CHARACTER(len=32) :: arg

  i = 0
  DO
    CALL get_command_argument(i, arg)
    IF (LEN_TRIM(arg) == 0) EXIT

    WRITE (*,*) TRIM(arg)
    i = i+1
  END DO
END PROGRAM
@end smallexample

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



@node GETCWD
@section @code{GETCWD} --- Get current working directory
@fnindex GETCWD
@cindex system, working directory

@table @asis
@item @emph{Description}:
Get current working directory.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine.

@item @emph{Syntax}:
@code{CALL GETCWD(CWD [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{CWD}    @tab The type shall be @code{CHARACTER(*)}.
@item @var{STATUS} @tab (Optional) status flag. Returns 0 on success, 
                        a system specific and non-zero error code otherwise.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_getcwd
  CHARACTER(len=255) :: cwd
  CALL getcwd(cwd)
  WRITE(*,*) TRIM(cwd)
END PROGRAM
@end smallexample

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



@node GETENV
@section @code{GETENV} --- Get an environmental variable
@fnindex GETENV
@cindex environment variable

@table @asis
@item @emph{Description}:
Get the @var{VALUE} of the environmental variable @var{ENVVAR}.

This intrinsic routine is provided for backwards compatibility with 
GNU Fortran 77.  In new code, programmers should consider the use of 
the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
2003 standard.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GETENV(ENVVAR, VALUE)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}. 
@item @var{VALUE}  @tab Shall be of type @code{CHARACTER(*)}. 
@end multitable

@item @emph{Return value}:
Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is 
not large enough to hold the data, it is truncated. If @var{ENVVAR}
is not set, @var{VALUE} will be filled with blanks.

@item @emph{Example}:
@smallexample
PROGRAM test_getenv
  CHARACTER(len=255) :: homedir
  CALL getenv("HOME", homedir)
  WRITE (*,*) TRIM(homedir)
END PROGRAM
@end smallexample

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



@node GET_ENVIRONMENT_VARIABLE
@section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
@fnindex GET_ENVIRONMENT_VARIABLE
@cindex environment variable

@table @asis
@item @emph{Description}:
Get the @var{VALUE} of the environmental variable @var{ENVVAR}.

@item @emph{Standard}:
F2003

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}. 
@item @var{VALUE}  @tab Shall be of type @code{CHARACTER(*)}. 
@end multitable

@item @emph{Return value}:
Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is 
not large enough to hold the data, it is truncated. If @var{ENVVAR}
is not set, @var{VALUE} will be filled with blanks.

@item @emph{Example}:
@smallexample
PROGRAM test_getenv
  CHARACTER(len=255) :: homedir
  CALL get_environment_variable("HOME", homedir)
  WRITE (*,*) TRIM(homedir)
END PROGRAM
@end smallexample
@end table



@node GETGID
@section @code{GETGID} --- Group ID function
@fnindex GETGID
@cindex system, group id

@table @asis
@item @emph{Description}:
Returns the numerical group ID of the current process.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
function

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

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


@item @emph{Example}:
See @code{GETPID} for an example.

@item @emph{See also}:
@ref{GETPID}, @ref{GETUID}
@end table



@node GETLOG
@section @code{GETLOG} --- Get login name
@fnindex GETLOG
@cindex system, login name
@cindex login name

@table @asis
@item @emph{Description}:
Gets the username under which the program is running.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GETLOG(LOGIN)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
@end multitable

@item @emph{Return value}:
Stores the current user name in @var{LOGIN}.  (On systems where POSIX
functions @code{geteuid} and @code{getpwuid} are not available, and 
the @code{getlogin} function is not implemented either, this will
return a blank string.)

@item @emph{Example}:
@smallexample
PROGRAM TEST_GETLOG
  CHARACTER(32) :: login
  CALL GETLOG(login)
  WRITE(*,*) login
END PROGRAM
@end smallexample

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



@node GETPID
@section @code{GETPID} --- Process ID function
@fnindex GETPID
@cindex system, process id
@cindex process id

@table @asis
@item @emph{Description}:
Returns the numerical process identifier of the current process.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
function

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

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


@item @emph{Example}:
@smallexample
program info
  print *, "The current process ID is ", getpid()
  print *, "Your numerical user ID is ", getuid()
  print *, "Your numerical group ID is ", getgid()
end program info
@end smallexample

@item @emph{See also}:
@ref{GETGID}, @ref{GETUID}
@end table



@node GETUID
@section @code{GETUID} --- User ID function
@fnindex GETUID
@cindex system, user id
@cindex user id

@table @asis
@item @emph{Description}:
Returns the numerical user ID of the current process.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
function

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

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


@item @emph{Example}:
See @code{GETPID} for an example.

@item @emph{See also}:
@ref{GETPID}, @ref{GETLOG}
@end table



@node GMTIME
@section @code{GMTIME} --- Convert time to GMT info
@fnindex GMTIME
@cindex time, conversion to GMT info

@table @asis
@item @emph{Description}:
Given a system time value @var{STIME} (as provided by the @code{TIME8()}
intrinsic), fills @var{TARRAY} with values extracted from it appropriate
to the UTC time zone (Universal Coordinated Time, also known in some
countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL GMTIME(STIME, TARRAY)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STIME}  @tab An @code{INTEGER(*)} scalar expression
                        corresponding to a system time, with 
                        @code{INTENT(IN)}.
@item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
                        with @code{INTENT(OUT)}.
@end multitable

@item @emph{Return value}:
The elements of @var{TARRAY} are assigned as follows:
@enumerate
@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
      seconds
@item Minutes after the hour, range 0--59
@item Hours past midnight, range 0--23
@item Day of month, range 0--31
@item Number of months since January, range 0--12
@item Years since 1900
@item Number of days since Sunday, range 0--6
@item Days since January 1
@item Daylight savings indicator: positive if daylight savings is in
      effect, zero if not, and negative if the information is not
      available.
@end enumerate

@item @emph{See also}:
@ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}

@end table



@node HOSTNM
@section @code{HOSTNM} --- Get system host name
@fnindex HOSTNM
@cindex system, host name

@table @asis
@item @emph{Description}:
Retrieves the host name of the system on which the program is running.

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 HOSTNM(NAME[, STATUS])}
@item @code{STATUS = HOSTNM(NAME)}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{NAME}    @tab Shall of type @code{CHARACTER(*)}.
@item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
                         Returns 0 on success, or a system specific error
                         code otherwise.
@end multitable

@item @emph{Return value}:
In either syntax, @var{NAME} is set to the current hostname if it can
be obtained, or to a blank string otherwise.

@end table



@node HUGE
@section @code{HUGE} --- Largest number of a kind
@fnindex HUGE
@cindex limits, largest number
@cindex model representation, largest number

@table @asis
@item @emph{Description}:
@code{HUGE(X)} returns the largest number that is not an infinity in
the model of the type of @code{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

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

@item @emph{Example}:
@smallexample
program test_huge_tiny
  print *, huge(0), huge(0.0), huge(0.0d0)
  print *, tiny(0.0), tiny(0.0d0)
end program test_huge_tiny
@end smallexample
@end table



@node IACHAR
@section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence 
@fnindex IACHAR
@cindex @acronym{ASCII} collating sequence
@cindex collating sequence, @acronym{ASCII}
@cindex conversion, to integer

@table @asis
@item @emph{Description}:
@code{IACHAR(C)} returns the code for the @acronym{ASCII} character
in the first character position of @code{C}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
@end multitable

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

@item @emph{Example}:
@smallexample
program test_iachar
  integer i
  i = iachar(' ')
end program test_iachar
@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{ACHAR}, @ref{CHAR}, @ref{ICHAR}

@end table



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

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

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER(*)}.
@item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
kind as @var{I}.  (As a GNU extension, different kinds are also 
permitted.)
@end multitable

@item @emph{Return value}:
The return type is @code{INTEGER(*)}, of the same kind as the
arguments.  (If the argument kinds differ, it is of the same kind as
the larger argument.)

@item @emph{Example}:
@smallexample
PROGRAM test_iand
  INTEGER :: a, b
  DATA a / Z'F' /, b / Z'3' /
  WRITE (*,*) IAND(a, b)
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}

@end table



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

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

This intrinsic routine is provided for backwards compatibility with 
GNU Fortran 77.  In new code, programmers should consider the use of 
the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003 
standard.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental Function

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

@item @emph{Arguments}:
None.

@item @emph{Return value}:
The number of command line arguments, type @code{INTEGER(4)}.

@item @emph{Example}:
See @ref{GETARG}

@item @emph{See also}:
GNU Fortran 77 compatibility subroutine: @ref{GETARG}

F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
@ref{COMMAND_ARGUMENT_COUNT}
@end table



@node IBCLR
@section @code{IBCLR} --- Clear bit
@fnindex IBCLR
@cindex bits, unset
@cindex bits, clear

@table @asis
@item @emph{Description}:
@code{IBCLR} returns the value of @var{I} with the bit at position
@var{POS} set to zero.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = IBCLR(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{INTEGER(*)} and of the same kind as
@var{I}.

@item @emph{See also}:
@ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}

@end table



@node IBITS
@section @code{IBITS} --- Bit extraction
@fnindex IBITS
@cindex bits, get
@cindex bits, extract

@table @asis
@item @emph{Description}:
@code{IBITS} extracts a field of length @var{LEN} from @var{I},
starting from bit position @var{POS} and extending left for @var{LEN}
bits.  The result is right-justified and the remaining bits are
zeroed.  The value of @code{POS+LEN} must be less than or equal to the
value @code{BIT_SIZE(I)}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@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(*)}.
@item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER(*)} and of the same kind as
@var{I}.

@item @emph{See also}:
@ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
@end table



@node IBSET
@section @code{IBSET} --- Set bit
@fnindex IBSET
@cindex bits, set

@table @asis
@item @emph{Description}:
@code{IBSET} returns the value of @var{I} with the bit at position
@var{POS} set to one.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = IBSET(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{INTEGER(*)} and of the same kind as
@var{I}.

@item @emph{See also}:
@ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}

@end table



@node ICHAR
@section @code{ICHAR} --- Character-to-integer conversion function
@fnindex ICHAR
@cindex conversion, to integer

@table @asis
@item @emph{Description}:
@code{ICHAR(C)} returns the code for the character in the first character
position of @code{C} in the system's native character set.
The correspondence between characters and their codes is not necessarily
the same across different GNU Fortran implementations.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
@end multitable

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

@item @emph{Example}:
@smallexample
program test_ichar
  integer i
  i = ichar(' ')
end program test_ichar
@end smallexample

@item @emph{Note}:
No intrinsic exists to convert between a numeric value and a formatted
character string representation -- for instance, given the
@code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
@code{REAL} value with the value 154, or vice versa. Instead, this
functionality is provided by internal-file I/O, as in the following
example:
@smallexample
program read_val
  integer value
  character(len=10) string, string2
  string = '154'
  
  ! Convert a string to a numeric value
  read (string,'(I10)') value
  print *, value
  
  ! Convert a value to a formatted string
  write (string2,'(I10)') value
  print *, string2
end program read_val
@end smallexample

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

@end table



@node IDATE
@section @code{IDATE} --- Get current local time subroutine (day/month/year) 
@fnindex IDATE
@cindex date, current
@cindex current date

@table @asis
@item @emph{Description}:
@code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the  
current local time. The day (in the range 1-31), month (in the range 1-12), 
and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively. 
The year has four significant digits.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL IDATE(TARRAY)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
the kind shall be the default integer kind.
@end multitable

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

@item @emph{Example}:
@smallexample
program test_idate
  integer, dimension(3) :: tarray
  call idate(tarray)
  print *, tarray(1)
  print *, tarray(2)
  print *, tarray(3)
end program test_idate
@end smallexample
@end table



@node IEOR
@section @code{IEOR} --- Bitwise logical exclusive or
@fnindex IEOR
@cindex bitwise logical exclusive or
@cindex logical exclusive or, bitwise

@table @asis
@item @emph{Description}:
@code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
@var{J}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER(*)}.
@item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
kind as @var{I}.  (As a GNU extension, different kinds are also 
permitted.)
@end multitable

@item @emph{Return value}:
The return type is @code{INTEGER(*)}, of the same kind as the
arguments.  (If the argument kinds differ, it is of the same kind as
the larger argument.)

@item @emph{See also}:
@ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
@end table



@node IERRNO
@section @code{IERRNO} --- Get the last system error number
@fnindex IERRNO
@cindex system, error handling

@table @asis
@item @emph{Description}:
Returns the last system error number, as given by the C @code{errno()}
function.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Arguments}:
None.

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

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



@node INDEX
@section @code{INDEX} --- Position of a substring within a string
@fnindex INDEX
@cindex substring position
@cindex string, find substring

@table @asis
@item @emph{Description}:
Returns the position of the start of the first occurrence of string
@var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
@var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If 
the @var{BACK} argument is present and true, the return value is the
start of the last occurrence rather than the first.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = INDEX(STRING, SUBSTRING [, BACK])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
@code{INTENT(IN)}
@item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
@code{INTENT(IN)}
@item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
@code{INTENT(IN)}
@end multitable

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

@item @emph{See also}:
@ref{SCAN}, @ref{VERIFY}
@end table



@node INT
@section @code{INT} --- Convert to integer type
@fnindex INT
@fnindex IFIX
@fnindex IDINT
@cindex conversion, to integer

@table @asis
@item @emph{Description}:
Convert to integer type

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A}    @tab Shall be of type @code{INTEGER(*)},
                      @code{REAL(*)}, or @code{COMPLEX(*)}.
@item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
                      expression indicating the kind parameter of
                      the result.
@end multitable

@item @emph{Return value}:
These functions return a @code{INTEGER(*)} variable or array under 
the following rules: 

@table @asis
@item (A)
If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A} 
@item (B)
If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}. 
If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed 
the range of @var{A} and whose sign is the same as the sign of @var{A}.
@item (C)
If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
@end table

@item @emph{Example}:
@smallexample
program test_int
  integer :: i = 42
  complex :: z = (-3.7, 1.0)
  print *, int(i)
  print *, int(z), int(z,8)
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{IFIX(A)}   @tab @code{REAL(4) A}    @tab @code{INTEGER}    @tab F77 and later
@item @code{IDINT(A)}  @tab @code{REAL(8) A}    @tab @code{INTEGER}    @tab F77 and later
@end multitable

@end table



@node INT2
@section @code{INT2} --- Convert to 16-bit integer type
@fnindex INT2
@fnindex SHORT
@cindex conversion, to integer

@table @asis
@item @emph{Description}:
Convert to a @code{KIND=2} integer type. This is equivalent to the
standard @code{INT} intrinsic with an optional argument of
@code{KIND=2}, and is only included for backwards compatibility.

The @code{SHORT} intrinsic is equivalent to @code{INT2}.

@item @emph{Standard}:
GNU extension.

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A}    @tab Shall be of type @code{INTEGER(*)},
                      @code{REAL(*)}, or @code{COMPLEX(*)}.
@end multitable

@item @emph{Return value}:
The return value is a @code{INTEGER(2)} variable.

@item @emph{See also}:
@ref{INT}, @ref{INT8}, @ref{LONG}
@end table



@node INT8
@section @code{INT8} --- Convert to 64-bit integer type
@fnindex INT8
@cindex conversion, to integer

@table @asis
@item @emph{Description}:
Convert to a @code{KIND=8} integer type. This is equivalent to the
standard @code{INT} intrinsic with an optional argument of
@code{KIND=8}, and is only included for backwards compatibility.

@item @emph{Standard}:
GNU extension.

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A}    @tab Shall be of type @code{INTEGER(*)},
                      @code{REAL(*)}, or @code{COMPLEX(*)}.
@end multitable

@item @emph{Return value}:
The return value is a @code{INTEGER(8)} variable.

@item @emph{See also}:
@ref{INT}, @ref{INT2}, @ref{LONG}
@end table



@node IOR
@section @code{IOR} --- Bitwise logical or
@fnindex IOR
@cindex bitwise logical or
@cindex logical or, bitwise

@table @asis
@item @emph{Description}:
@code{IEOR} returns the bitwise boolean OR of @var{I} and
@var{J}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER(*)}.
@item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
kind as @var{I}.  (As a GNU extension, different kinds are also 
permitted.)
@end multitable

@item @emph{Return value}:
The return type is @code{INTEGER(*)}, of the same kind as the
arguments.  (If the argument kinds differ, it is of the same kind as
the larger argument.)

@item @emph{See also}:
@ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
@end table



@node IRAND
@section @code{IRAND} --- Integer pseudo-random number
@fnindex IRAND
@cindex random number generation

@table @asis
@item @emph{Description}:
@code{IRAND(FLAG)} returns a pseudo-random number from a uniform
distribution between 0 and a system-dependent limit (which is in most
cases 2147483647). If @var{FLAG} is 0, the next number
in the current sequence is returned; if @var{FLAG} is 1, the generator
is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
it is used as a new seed with @code{SRAND}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
@end multitable

@item @emph{Return value}:
The return value is of @code{INTEGER(kind=4)} type.

@item @emph{Example}:
@smallexample
program test_irand
  integer,parameter :: seed = 86456
  
  call srand(seed)
  print *, irand(), irand(), irand(), irand()
  print *, irand(seed), irand(), irand(), irand()
end program test_irand
@end smallexample

@end table



@node ISATTY
@section @code{ISATTY} --- Whether a unit is a terminal device.
@fnindex ISATTY
@cindex system, terminal

@table @asis
@item @emph{Description}:
Determine whether a unit is connected to a terminal device.

@item @emph{Standard}:
GNU extension.

@item @emph{Class}:
Non-elemental function.

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
@end multitable

@item @emph{Return value}:
Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal 
device, @code{.FALSE.} otherwise.

@item @emph{Example}:
@smallexample
PROGRAM test_isatty
  INTEGER(kind=1) :: unit
  DO unit = 1, 10
    write(*,*) isatty(unit=unit)
  END DO
END PROGRAM
@end smallexample
@item @emph{See also}:
@ref{TTYNAM}
@end table



@node ISHFT
@section @code{ISHFT} --- Shift bits
@fnindex ISHFT
@cindex bits, shift

@table @asis
@item @emph{Description}:
@code{ISHFT} returns a value corresponding to @var{I} with all of the
bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
zero corresponds to a left shift, a value of zero corresponds to no
shift, and a value less than zero corresponds to a right shift.  If the
absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
value is undefined.  Bits shifted out from the left end or right end are
lost; zeros are shifted in from the opposite end.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

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

@item @emph{Return value}:
The return value is of type @code{INTEGER(*)} and of the same kind as
@var{I}.

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



@node ISHFTC
@section @code{ISHFTC} --- Shift bits circularly
@fnindex ISHFTC
@cindex bits, shift circular

@table @asis
@item @emph{Description}:
@code{ISHFTC} returns a value corresponding to @var{I} with the
rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
is, bits shifted out one end are shifted into the opposite end.  A value
of @var{SHIFT} greater than zero corresponds to a left shift, a value of
zero corresponds to no shift, and a value less than zero corresponds to
a right shift.  The absolute value of @var{SHIFT} must be less than
@var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
equivalent to @code{BIT_SIZE(I)}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = ISHFTC(I, SHIFT [, SIZE])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab The type shall be @code{INTEGER(*)}.
@item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
@item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
the value must be greater than zero and less than or equal to
@code{BIT_SIZE(I)}.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER(*)} and of the same kind as
@var{I}.

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



@node ITIME
@section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds) 
@fnindex ITIME
@cindex time, current
@cindex current time

@table @asis
@item @emph{Description}:
@code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the  
current local time. The hour (in the range 1-24), minute (in the range 1-60), 
and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY}, 
respectively.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL ITIME(TARRAY)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
and the kind shall be the default integer kind.
@end multitable

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


@item @emph{Example}:
@smallexample
program test_itime
  integer, dimension(3) :: tarray
  call itime(tarray)
  print *, tarray(1)
  print *, tarray(2)
  print *, tarray(3)
end program test_itime
@end smallexample
@end table



@node KILL
@section @code{KILL} --- Send a signal to a process
@fnindex KILL

@table @asis
@item @emph{Description}:
@item @emph{Standard}:
Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
See @code{kill(2)}.

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL KILL(PID, SIGNAL [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
@code{INTENT(IN)}
@item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
@code{INTENT(IN)}
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
                        @code{INTEGER(8)}. Returns 0 on success, or a
                        system-specific error code otherwise.
@end multitable

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



@node KIND
@section @code{KIND} --- Kind of an entity
@fnindex KIND
@cindex kind

@table @asis
@item @emph{Description}:
@code{KIND(X)} returns the kind value of the entity @var{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
@code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
@end multitable

@item @emph{Return value}:
The return value is a scalar of type @code{INTEGER} and of the default
integer kind.

@item @emph{Example}:
@smallexample
program test_kind
  integer,parameter :: kc = kind(' ')
  integer,parameter :: kl = kind(.true.)

  print *, "The default character kind is ", kc
  print *, "The default logical kind is ", kl
end program test_kind
@end smallexample

@end table



@node LBOUND
@section @code{LBOUND} --- Lower dimension bounds of an array
@fnindex LBOUND
@cindex array, lower bound

@table @asis
@item @emph{Description}:
Returns the lower bounds of an array, or a single lower bound
along the @var{DIM} dimension.
@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array, of any type.
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
@end multitable

@item @emph{Return value}:
If @var{DIM} is absent, the result is an array of the lower bounds of
@var{ARRAY}.  If @var{DIM} is present, the result is a scalar
corresponding to the lower bound of the array along that dimension.  If
@var{ARRAY} is an expression rather than a whole array or array
structure component, or if it has a zero extent along the relevant
dimension, the lower bound is taken to be 1.

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



@node LEN
@section @code{LEN} --- Length of a character entity
@fnindex LEN
@cindex string, length

@table @asis
@item @emph{Description}:
Returns the length of a character string.  If @var{STRING} is an array,
the length of an element of @var{STRING} is returned.  Note that
@var{STRING} need not be defined when this intrinsic is invoked, since
only the length, not the content, of @var{STRING} is needed.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Inquiry function

@item @emph{Syntax}:
@code{L = LEN(STRING)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab Shall be a scalar or array of type
@code{CHARACTER(*)}, with @code{INTENT(IN)}
@end multitable

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

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



@node LEN_TRIM
@section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
@fnindex LEN_TRIM
@cindex string, length, without trailing whitespace

@table @asis
@item @emph{Description}:
Returns the length of a character string, ignoring any trailing blanks.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
with @code{INTENT(IN)}
@end multitable

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

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



@node LGE
@section @code{LGE} --- Lexical greater than or equal
@fnindex LGE
@cindex lexical comparison of strings
@cindex string, comparison

@table @asis
@item @emph{Description}:
Determines whether one string is lexically greater than or equal to
another string, where the two strings are interpreted as containing
ASCII character codes.  If the String A and String B are not the same
length, the shorter is compared as if spaces were appended to it to form
a value that has the same length as the longer.

In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
that the latter use the processor's character ordering (which is not
ASCII on some targets), whereas the former always use the ASCII
ordering.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = LGE(STRING_A, STRING_B)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
@end multitable

@item @emph{Return value}:
Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
otherwise, based on the ASCII ordering.

@item @emph{See also}:
@ref{LGT}, @ref{LLE}, @ref{LLT}
@end table



@node LGT
@section @code{LGT} --- Lexical greater than
@fnindex LGT
@cindex lexical comparison of strings
@cindex string, comparison

@table @asis
@item @emph{Description}:
Determines whether one string is lexically greater than another string,
where the two strings are interpreted as containing ASCII character
codes.  If the String A and String B are not the same length, the
shorter is compared as if spaces were appended to it to form a value
that has the same length as the longer.

In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
that the latter use the processor's character ordering (which is not
ASCII on some targets), whereas the former always use the ASCII
ordering.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = LGT(STRING_A, STRING_B)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
@end multitable

@item @emph{Return value}:
Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
otherwise, based on the ASCII ordering.

@item @emph{See also}:
@ref{LGE}, @ref{LLE}, @ref{LLT}
@end table



@node LINK
@section @code{LINK} --- Create a hard link
@fnindex LINK
@cindex file system, create link
@cindex file system, hard link

@table @asis
@item @emph{Description}:
Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
character (@code{CHAR(0)}) can be used to mark the end of the names in
@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
names are ignored.  If the @var{STATUS} argument is supplied, it
contains 0 on success or a nonzero error code upon return; see
@code{link(2)}.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
@end multitable

@item @emph{See also}:
@ref{SYMLNK}, @ref{UNLINK}
@end table



@node LLE
@section @code{LLE} --- Lexical less than or equal
@fnindex LLE
@cindex lexical comparison of strings
@cindex string, comparison

@table @asis
@item @emph{Description}:
Determines whether one string is lexically less than or equal to another
string, where the two strings are interpreted as containing ASCII
character codes.  If the String A and String B are not the same length,
the shorter is compared as if spaces were appended to it to form a value
that has the same length as the longer.

In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
that the latter use the processor's character ordering (which is not
ASCII on some targets), whereas the former always use the ASCII
ordering.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = LLE(STRING_A, STRING_B)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
@end multitable

@item @emph{Return value}:
Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
otherwise, based on the ASCII ordering.

@item @emph{See also}:
@ref{LGE}, @ref{LGT}, @ref{LLT}
@end table



@node LLT
@section @code{LLT} --- Lexical less than
@fnindex LLT
@cindex lexical comparison of strings
@cindex string, comparison

@table @asis
@item @emph{Description}:
Determines whether one string is lexically less than another string,
where the two strings are interpreted as containing ASCII character
codes.  If the String A and String B are not the same length, the
shorter is compared as if spaces were appended to it to form a value
that has the same length as the longer.

In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
@code{LLE}, and @code{LLT} differ from the corresponding intrinsic
operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
that the latter use the processor's character ordering (which is not
ASCII on some targets), whereas the former always use the ASCII
ordering.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = LLT(STRING_A, STRING_B)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
@item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
@end multitable

@item @emph{Return value}:
Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
otherwise, based on the ASCII ordering.

@item @emph{See also}:
@ref{LGE}, @ref{LGT}, @ref{LLE}
@end table



@node LNBLNK
@section @code{LNBLNK} --- Index of the last non-blank character in a string
@fnindex LNBLNK
@cindex string, find non-blank character

@table @asis
@item @emph{Description}:
Returns the length of a character string, ignoring any trailing blanks.
This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
included for backwards compatibility.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
with @code{INTENT(IN)}
@end multitable

@item @emph{Return value}:
The return value is of @code{INTEGER(kind=4)} type.

@item @emph{See also}:
@ref{INDEX}, @ref{LEN_TRIM}
@end table



@node LOC
@section @code{LOC} --- Returns the address of a variable
@fnindex LOC
@cindex location of a variable in memory

@table @asis
@item @emph{Description}:
@code{LOC(X)} returns the address of @var{X} as an integer.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab Variable of any type.
@end multitable

@item @emph{Return value}:
The return value is of type @code{INTEGER}, with a @code{KIND}
corresponding to the size (in bytes) of a memory address on the target
machine.

@item @emph{Example}:
@smallexample
program test_loc
  integer :: i
  real :: r
  i = loc(r)
  print *, i
end program test_loc
@end smallexample
@end table



@node LOG
@section @code{LOG} --- Logarithm function
@fnindex LOG
@fnindex ALOG
@fnindex DLOG
@fnindex CLOG
@fnindex ZLOG
@fnindex CDLOG
@cindex exponential function, inverse
@cindex logarithmic function

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

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = LOG(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 type @code{REAL(*)} or @code{COMPLEX(*)}.
The kind type parameter is the same as @var{X}.

@item @emph{Example}:
@smallexample
program test_log
  real(8) :: x = 1.0_8
  complex :: z = (1.0, 2.0)
  x = log(x)
  z = log(z)
end program test_log
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
@item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
@item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
@item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
@item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
@end multitable
@end table



@node LOG10
@section @code{LOG10} --- Base 10 logarithm function
@fnindex LOG10
@fnindex ALOG10
@fnindex DLOG10
@cindex exponential function, inverse
@cindex logarithmic function

@table @asis
@item @emph{Description}:
@code{LOG10(X)} computes the base 10 logarithm of @var{X}.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = LOG10(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(*)} or @code{COMPLEX(*)}.
The kind type parameter is the same as @var{X}.

@item @emph{Example}:
@smallexample
program test_log10
  real(8) :: x = 10.0_8
  x = log10(x)
end program test_log10
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab F95 and later
@item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab F95 and later
@end multitable
@end table



@node LOGICAL
@section @code{LOGICAL} --- Convert to logical type
@fnindex LOGICAL
@cindex conversion, to logical

@table @asis
@item @emph{Description}:
Converts one kind of @code{LOGICAL} variable to another.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{L}    @tab The type shall be @code{LOGICAL(*)}.
@item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
                      expression indicating the kind parameter of
                      the result.
@end multitable

@item @emph{Return value}:
The return value is a @code{LOGICAL} value equal to @var{L}, with a
kind corresponding to @var{KIND}, or of the default logical kind if
@var{KIND} is not given.

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



@node LONG
@section @code{LONG} --- Convert to integer type
@fnindex LONG
@cindex conversion, to integer

@table @asis
@item @emph{Description}:
Convert to a @code{KIND=4} integer type, which is the same size as a C
@code{long} integer.  This is equivalent to the standard @code{INT}
intrinsic with an optional argument of @code{KIND=4}, and is only
included for backwards compatibility.

@item @emph{Standard}:
GNU extension.

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A}    @tab Shall be of type @code{INTEGER(*)},
                      @code{REAL(*)}, or @code{COMPLEX(*)}.
@end multitable

@item @emph{Return value}:
The return value is a @code{INTEGER(4)} variable.

@item @emph{See also}:
@ref{INT}, @ref{INT2}, @ref{INT8}
@end table



@node LSHIFT
@section @code{LSHIFT} --- Left shift bits
@fnindex LSHIFT
@cindex bits, shift left

@table @asis
@item @emph{Description}:
@code{LSHIFT} returns a value corresponding to @var{I} with all of the
bits shifted left by @var{SHIFT} places.  If the absolute value of
@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 
Bits shifted out from the left end are lost; zeros are shifted in from
the opposite end.

This function has been superseded by the @code{ISHFT} intrinsic, which
is standard in Fortran 95 and later.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

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

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

@item @emph{Return value}:
The return value is of type @code{INTEGER(*)} and of the same kind as
@var{I}.

@item @emph{See also}:
@ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}

@end table



@node LSTAT
@section @code{LSTAT} --- Get file status
@fnindex LSTAT
@cindex file system, file status

@table @asis
@item @emph{Description}:
@code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link, 
then the link itself is statted, not the file that it refers to.

The elements in @code{BUFF} are the same as described by @ref{STAT}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL LSTAT(FILE, BUFF [, STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{FILE}   @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
@item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 
                        on success and a system specific error code otherwise.
@end multitable

@item @emph{Example}:
See @ref{STAT} for an example.

@item @emph{See also}:
To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
@end table



@node LTIME
@section @code{LTIME} --- Convert time to local time info
@fnindex LTIME
@cindex time, conversion to local time info

@table @asis
@item @emph{Description}:
Given a system time value @var{STIME} (as provided by the @code{TIME8()}
intrinsic), fills @var{TARRAY} with values extracted from it appropriate
to the local time zone using @code{localtime(3)}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL LTIME(STIME, TARRAY)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STIME}  @tab An @code{INTEGER(*)} scalar expression
                        corresponding to a system time, with 
                        @code{INTENT(IN)}.
@item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
                        with @code{INTENT(OUT)}.
@end multitable

@item @emph{Return value}:
The elements of @var{TARRAY} are assigned as follows:
@enumerate
@item Seconds after the minute, range 0--59 or 0--61 to allow for leap
      seconds
@item Minutes after the hour, range 0--59
@item Hours past midnight, range 0--23
@item Day of month, range 0--31
@item Number of months since January, range 0--12
@item Years since 1900
@item Number of days since Sunday, range 0--6
@item Days since January 1
@item Daylight savings indicator: positive if daylight savings is in
      effect, zero if not, and negative if the information is not
      available.
@end enumerate

@item @emph{See also}:
@ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}

@end table



@node MALLOC
@section @code{MALLOC} --- Allocate dynamic memory
@fnindex MALLOC
@cindex pointer, cray

@table @asis
@item @emph{Description}:
@code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
returns the address of the allocated memory. The @code{MALLOC} intrinsic
is an extension intended to be used with Cray pointers, and is provided
in GNU Fortran to allow the user to compile legacy code. For new code
using Fortran 95 pointers, the memory allocation intrinsic is
@code{ALLOCATE}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

@item @emph{Syntax}:
@code{PTR = MALLOC(SIZE)}

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

@item @emph{Return value}:
The return value is of type @code{INTEGER(K)}, with @var{K} such that
variables of type @code{INTEGER(K)} have the same size as
C pointers (@code{sizeof(void *)}).

@item @emph{Example}:
The following example demonstrates the use of @code{MALLOC} and
@code{FREE} with Cray pointers. This example is intended to run on
32-bit systems, where the default integer kind is suitable to store
pointers; on 64-bit systems, ptr_x would need to be declared as
@code{integer(kind=8)}.

@smallexample
program test_malloc
  integer i
  integer ptr_x
  real*8 x(*), z
  pointer(ptr_x,x)

  ptr_x = malloc(20*8)
  do i = 1, 20
    x(i) = sqrt(1.0d0 / i)
  end do
  z = 0
  do i = 1, 20
    z = z + x(i)
    print *, z
  end do
  call free(ptr_x)
end program test_malloc
@end smallexample

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



@node MATMUL
@section @code{MATMUL} --- matrix multiplication
@fnindex MATMUL
@cindex matrix multiplication
@cindex product, matrix

@table @asis
@item @emph{Description}:
Performs a matrix multiplication on numeric or logical arguments.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
                          @code{REAL(*)}, @code{COMPLEX(*)}, or
                          @code{LOGICAL(*)} type, with a rank of
                          one or two.
@item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
                          @code{REAL(*)}, or @code{COMPLEX(*)} type if
                          @var{MATRIX_A} is of a numeric type;
                          otherwise, an array of @code{LOGICAL(*)}
                          type. The rank shall be one or two, and the
                          first (or only) dimension of @var{MATRIX_B}
                          shall be equal to the last (or only)
                          dimension of @var{MATRIX_A}.
@end multitable

@item @emph{Return value}:
The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
kind of the result follow the usual type and kind promotion rules, as
for the @code{*} or @code{.AND.} operators.

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



@node MAX
@section @code{MAX} --- Maximum value of an argument list
@fnindex MAX
@fnindex MAX0
@fnindex AMAX0
@fnindex MAX1
@fnindex AMAX1
@fnindex DMAX1
@cindex maximum value

@table @asis
@item @emph{Description}:
Returns the argument with the largest (most positive) value.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = MAX(A1, A2 [, A3 [, ...]])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A1}          @tab The type shall be @code{INTEGER(*)} or
                             @code{REAL(*)}.
@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
                             as @var{A1}.  (As a GNU extension, 
                             arguments of different kinds are
                             permitted.)
@end multitable

@item @emph{Return value}:
The return value corresponds to the maximum value among the arguments,
and has the same type and kind as the first argument.

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name             @tab Argument            @tab Return type         @tab Standard
@item @code{MAX0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab F77 and later
@item @code{AMAX0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
@item @code{MAX1(X)}   @tab @code{REAL(*) X}    @tab @code{INT(MAX(X))}  @tab F77 and later
@item @code{AMAX1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab F77 and later
@item @code{DMAX1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab F77 and later
@end multitable

@item @emph{See also}:
@ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}

@end table



@node MAXEXPONENT
@section @code{MAXEXPONENT} --- Maximum exponent of a real kind
@fnindex MAXEXPONENT
@cindex model representation, maximum exponent

@table @asis
@item @emph{Description}:
@code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
type of @code{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

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

@item @emph{Example}:
@smallexample
program exponents
  real(kind=4) :: x
  real(kind=8) :: y

  print *, minexponent(x), maxexponent(x)
  print *, minexponent(y), maxexponent(y)
end program exponents
@end smallexample
@end table



@node MAXLOC
@section @code{MAXLOC} --- Location of the maximum value within an array
@fnindex MAXLOC
@cindex array, location of maximum element

@table @asis
@item @emph{Description}:
Determines the location of the element in the array with the maximum
value, or, if the @var{DIM} argument is supplied, determines the
locations of the maximum element along each row of the array in the
@var{DIM} direction.  If @var{MASK} is present, only the elements for
which @var{MASK} is @code{.TRUE.} are considered.  If more than one
element in the array has the maximum value, the location returned is
that of the first such element in array element order.  If the array has
zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
and all of the elements of @var{MASK} along a given row are zero, the
result value for that row is zero.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
@item @code{RESULT = MAXLOC(ARRAY [, MASK])}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
                       @code{REAL(*)}, or @code{CHARACTER(*)}.
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
                       @code{INTEGER(*)}, with a value between one
                       and the rank of @var{ARRAY}, inclusive.  It
                       may not be an optional dummy argument.
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
                       and conformable with @var{ARRAY}.
@end multitable

@item @emph{Return value}:
If @var{DIM} is absent, the result is a rank-one array with a length
equal to the rank of @var{ARRAY}.  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 size of @var{ARRAY} with the @var{DIM}
dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
of one, the result is a scalar.  In all cases, the result is of default
@code{INTEGER} type.

@item @emph{See also}:
@ref{MAX}, @ref{MAXVAL}

@end table



@node MAXVAL
@section @code{MAXVAL} --- Maximum value of an array
@fnindex MAXVAL
@cindex array, maximum value
@cindex maximum value

@table @asis
@item @emph{Description}:
Determines the maximum value of the elements in an array value, or, if
the @var{DIM} argument is supplied, determines the maximum value along
each row of the array in the @var{DIM} direction.  If @var{MASK} is
present, only the elements for which @var{MASK} is @code{.TRUE.} are
considered.  If the array has zero size, or all of the elements of
@var{MASK} are @code{.FALSE.}, then the result is the most negative
number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
a string of nulls if @var{ARRAY} is of character type.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
@item @code{RESULT = MAXVAL(ARRAY [, MASK])}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
                       @code{REAL(*)}, or @code{CHARACTER(*)}.
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
                       @code{INTEGER(*)}, with a value between one
                       and the rank of @var{ARRAY}, inclusive.  It
                       may not be an optional dummy argument.
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
                       and conformable with @var{ARRAY}.
@end multitable

@item @emph{Return value}:
If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
is a scalar.  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 size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
cases, the result is of the same type and kind as @var{ARRAY}.

@item @emph{See also}:
@ref{MAX}, @ref{MAXLOC}
@end table



@node MCLOCK
@section @code{MCLOCK} --- Time function
@fnindex MCLOCK
@cindex time, clock ticks
@cindex clock ticks

@table @asis
@item @emph{Description}:
Returns the number of clock ticks since the start of the process, based
on the UNIX function @code{clock(3)}.

This intrinsic is not fully portable, such as to systems with 32-bit
@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
the values returned by this intrinsic might be, or become, negative, or
numerically less than previous values, during a single run of the
compiled program.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Return value}:
The return value is a scalar of type @code{INTEGER(4)}, equal to the
number of clock ticks since the start of the process, or @code{-1} if
the system does not support @code{clock(3)}.

@item @emph{See also}:
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}

@end table



@node MCLOCK8
@section @code{MCLOCK8} --- Time function (64-bit)
@fnindex MCLOCK8
@cindex time, clock ticks
@cindex clock ticks

@table @asis
@item @emph{Description}:
Returns the number of clock ticks since the start of the process, based
on the UNIX function @code{clock(3)}.

@emph{Warning:} this intrinsic does not increase the range of the timing
values over that returned by @code{clock(3)}. On a system with a 32-bit
@code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
it is converted to a 64-bit @code{INTEGER(8)} value. That means
overflows of the 32-bit value can still occur. Therefore, the values
returned by this intrinsic might be or become negative or numerically
less than previous values during a single run of the compiled program.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Return value}:
The return value is a scalar of type @code{INTEGER(8)}, equal to the
number of clock ticks since the start of the process, or @code{-1} if
the system does not support @code{clock(3)}.

@item @emph{See also}:
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}

@end table



@node MERGE
@section @code{MERGE} --- Merge variables
@fnindex MERGE
@cindex array, merge arrays
@cindex array, combine arrays

@table @asis
@item @emph{Description}:
Select values from two arrays according to a logical mask.  The result
is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
@var{FSOURCE} if it is @code{.FALSE.}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{TSOURCE} @tab May be of any type.
@item @var{FSOURCE} @tab Shall be of the same type and type parameters
                         as @var{TSOURCE}.
@item @var{MASK}    @tab Shall be of type @code{LOGICAL(*)}.
@end multitable

@item @emph{Return value}:
The result is of the same type and type parameters as @var{TSOURCE}.

@end table



@node MIN
@section @code{MIN} --- Minimum value of an argument list
@fnindex MIN
@fnindex MIN0
@fnindex AMIN0
@fnindex MIN1
@fnindex AMIN1
@fnindex DMIN1
@cindex minimum value

@table @asis
@item @emph{Description}:
Returns the argument with the smallest (most negative) value.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = MIN(A1, A2 [, A3, ...])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A1}          @tab The type shall be @code{INTEGER(*)} or
                             @code{REAL(*)}.
@item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
                             as @var{A1}.  (As a GNU extension, 
                             arguments of different kinds are
                             permitted.)
@end multitable

@item @emph{Return value}:
The return value corresponds to the maximum value among the arguments,
and has the same type and kind as the first argument.

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name             @tab Argument            @tab Return type         @tab Standard
@item @code{MIN0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab F77 and later
@item @code{AMIN0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
@item @code{MIN1(X)}   @tab @code{REAL(*) X}    @tab @code{INT(MIN(X))}  @tab F77 and later
@item @code{AMIN1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab F77 and later
@item @code{DMIN1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab F77 and later
@end multitable

@item @emph{See also}:
@ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
@end table



@node MINEXPONENT
@section @code{MINEXPONENT} --- Minimum exponent of a real kind
@fnindex MINEXPONENT
@cindex model representation, minimum exponent

@table @asis
@item @emph{Description}:
@code{MINEXPONENT(X)} returns the minimum exponent in the model of the
type of @code{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

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

@item @emph{Example}:
See @code{MAXEXPONENT} for an example.
@end table



@node MINLOC
@section @code{MINLOC} --- Location of the minimum value within an array
@fnindex MINLOC
@cindex array, location of minimum element

@table @asis
@item @emph{Description}:
Determines the location of the element in the array with the minimum
value, or, if the @var{DIM} argument is supplied, determines the
locations of the minimum element along each row of the array in the
@var{DIM} direction.  If @var{MASK} is present, only the elements for
which @var{MASK} is @code{.TRUE.} are considered.  If more than one
element in the array has the minimum value, the location returned is
that of the first such element in array element order.  If the array has
zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
and all of the elements of @var{MASK} along a given row are zero, the
result value for that row is zero.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
@item @code{RESULT = MINLOC(ARRAY [, MASK])}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
                       @code{REAL(*)}, or @code{CHARACTER(*)}.
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
                       @code{INTEGER(*)}, with a value between one
                       and the rank of @var{ARRAY}, inclusive.  It
                       may not be an optional dummy argument.
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
                       and conformable with @var{ARRAY}.
@end multitable

@item @emph{Return value}:
If @var{DIM} is absent, the result is a rank-one array with a length
equal to the rank of @var{ARRAY}.  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 size of @var{ARRAY} with the @var{DIM}
dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
of one, the result is a scalar.  In all cases, the result is of default
@code{INTEGER} type.

@item @emph{See also}:
@ref{MIN}, @ref{MINVAL}

@end table



@node MINVAL
@section @code{MINVAL} --- Minimum value of an array
@fnindex MINVAL
@cindex array, minimum value
@cindex minimum value

@table @asis
@item @emph{Description}:
Determines the minimum value of the elements in an array value, or, if
the @var{DIM} argument is supplied, determines the minimum value along
each row of the array in the @var{DIM} direction.  If @var{MASK} is
present, only the elements for which @var{MASK} is @code{.TRUE.} are
considered.  If the array has zero size, or all of the elements of
@var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
@var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
@var{ARRAY} is of character type.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
@item @code{RESULT = MINVAL(ARRAY [, MASK])}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
                       @code{REAL(*)}, or @code{CHARACTER(*)}.
@item @var{DIM}   @tab (Optional) Shall be a scalar of type
                       @code{INTEGER(*)}, with a value between one
                       and the rank of @var{ARRAY}, inclusive.  It
                       may not be an optional dummy argument.
@item @var{MASK}  @tab Shall be an array of type @code{LOGICAL(*)},
                       and conformable with @var{ARRAY}.
@end multitable

@item @emph{Return value}:
If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
is a scalar.  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 size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
cases, the result is of the same type and kind as @var{ARRAY}.

@item @emph{See also}:
@ref{MIN}, @ref{MINLOC}

@end table



@node MOD
@section @code{MOD} --- Remainder function
@fnindex MOD
@fnindex AMOD
@fnindex DMOD
@cindex remainder
@cindex division, remainder

@table @asis
@item @emph{Description}:
@code{MOD(A,P)} computes the remainder of the division of A by P. It is
calculated as @code{A - (INT(A/P) * P)}.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = MOD(A, P)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
@item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
equal to zero
@end multitable

@item @emph{Return value}:
The kind of the return value is the result of cross-promoting
the kinds of the arguments.

@item @emph{Example}:
@smallexample
program test_mod
  print *, mod(17,3)
  print *, mod(17.5,5.5)
  print *, mod(17.5d0,5.5)
  print *, mod(17.5,5.5d0)

  print *, mod(-17,3)
  print *, mod(-17.5,5.5)
  print *, mod(-17.5d0,5.5)
  print *, mod(-17.5,5.5d0)

  print *, mod(17,-3)
  print *, mod(17.5,-5.5)
  print *, mod(17.5d0,-5.5)
  print *, mod(17.5,-5.5d0)
end program test_mod
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name             @tab Arguments      @tab Return type    @tab Standard
@item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
@item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
@end multitable
@end table



@node MODULO
@section @code{MODULO} --- Modulo function
@fnindex MODULO
@cindex modulo
@cindex division, modulo

@table @asis
@item @emph{Description}:
@code{MODULO(A,P)} computes the @var{A} modulo @var{P}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = MODULO(A, P)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
@item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
@end multitable

@item @emph{Return value}:
The type and kind of the result are those of the arguments.
@table @asis
@item If @var{A} and @var{P} are of type @code{INTEGER}:
@code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
@var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
(exclusive).
@item If @var{A} and @var{P} are of type @code{REAL}:
@code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
@end table
In all cases, if @var{P} is zero the result is processor-dependent.

@item @emph{Example}:
@smallexample
program test_modulo
  print *, modulo(17,3)
  print *, modulo(17.5,5.5)

  print *, modulo(-17,3)
  print *, modulo(-17.5,5.5)

  print *, modulo(17,-3)
  print *, modulo(17.5,-5.5)
end program
@end smallexample

@end table



@node MOVE_ALLOC
@section @code{MOVE_ALLOC} --- Move allocation from one object to another
@fnindex MOVE_ALLOC
@cindex moving allocation
@cindex allocation, moving

@table @asis
@item @emph{Description}:
@code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
@var{DEST}.  @var{SRC} will become deallocated in the process.

@item @emph{Standard}:
F2003 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL MOVE_ALLOC(SRC, DEST)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SRC}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
                      of any type and kind.
@item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
                      of the same type, kind and rank as @var{SRC}
@end multitable

@item @emph{Return value}:
None

@item @emph{Example}:
@smallexample
program test_move_alloc
    integer, allocatable :: a(:), b(:)

    allocate(a(3))
    a = [ 1, 2, 3 ]
    call move_alloc(a, b)
    print *, allocated(a), allocated(b)
    print *, b
end program test_move_alloc
@end smallexample
@end table



@node MVBITS
@section @code{MVBITS} --- Move bits from one integer to another
@fnindex MVBITS
@cindex bits, move

@table @asis
@item @emph{Description}:
Moves @var{LEN} bits from positions @var{FROMPOS} through
@code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
@code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
affected by the movement of bits is unchanged. The values of
@code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
@code{BIT_SIZE(FROM)}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental subroutine

@item @emph{Syntax}:
@code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{FROM}    @tab The type shall be @code{INTEGER(*)}.
@item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
@item @var{LEN}     @tab The type shall be @code{INTEGER(*)}.
@item @var{TO}      @tab The type shall be @code{INTEGER(*)}, of the
                         same kind as @var{FROM}.
@item @var{TOPOS}   @tab The type shall be @code{INTEGER(*)}.
@end multitable

@item @emph{See also}:
@ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
@end table



@node NEAREST
@section @code{NEAREST} --- Nearest representable number
@fnindex NEAREST
@cindex real number, nearest different
@cindex floating point, nearest different

@table @asis
@item @emph{Description}:
@code{NEAREST(X, S)} returns the processor-representable number nearest
to @code{X} in the direction indicated by the sign of @code{S}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = NEAREST(X, S)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab Shall be of type @code{REAL}.
@item @var{S} @tab (Optional) shall be of type @code{REAL} and
not equal to zero.
@end multitable

@item @emph{Return value}:
The return value is of the same type as @code{X}. If @code{S} is
positive, @code{NEAREST} returns the processor-representable number
greater than @code{X} and nearest to it. If @code{S} is negative,
@code{NEAREST} returns the processor-representable number smaller than
@code{X} and nearest to it.

@item @emph{Example}:
@smallexample
program test_nearest
  real :: x, y
  x = nearest(42.0, 1.0)
  y = nearest(42.0, -1.0)
  write (*,"(3(G20.15))") x, y, x - y
end program test_nearest
@end smallexample
@end table



@node NEW_LINE
@section @code{NEW_LINE} --- New line character
@fnindex NEW_LINE
@cindex newline
@cindex output, newline

@table @asis
@item @emph{Description}:
@code{NEW_LINE(C)} returns the new-line character.

@item @emph{Standard}:
F2003 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{C}    @tab The argument shall be a scalar or array of the
                      type @code{CHARACTER}.
@end multitable

@item @emph{Return value}:
Returns a @var{CHARACTER} scalar of length one with the new-line character of
the same kind as parameter @var{C}.

@item @emph{Example}:
@smallexample
program newline
  implicit none
  write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
end program newline
@end smallexample
@end table



@node NINT
@section @code{NINT} --- Nearest whole number
@fnindex NINT
@fnindex IDNINT
@cindex rounding, nearest whole number

@table @asis
@item @emph{Description}:
@code{NINT(X)} rounds its argument to the nearest whole number.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

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

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

@item @emph{Return value}:
Returns @var{A} with the fractional portion of its magnitude eliminated by
rounding to the nearest whole number and with its sign preserved,
converted to an @code{INTEGER} of the default kind.

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

@item @emph{Specific names}:
@multitable @columnfractions .25 .25 .25
@item Name             @tab Argument         @tab Standard
@item @code{IDNINT(X)} @tab @code{REAL(8)}   @tab F95 and later
@end multitable

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

@end table



@node NOT
@section @code{NOT} --- Logical negation
@fnindex NOT
@cindex bits, negate
@cindex bitwise logical not
@cindex logical not, bitwise

@table @asis
@item @emph{Description}:
@code{NOT} returns the bitwise boolean inverse of @var{I}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = NOT(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 type is @code{INTEGER(*)}, of the same kind as the
argument.

@item @emph{See also}:
@ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}

@end table



@node NULL
@section @code{NULL} --- Function that returns an disassociated pointer
@fnindex NULL
@cindex pointer, status
@cindex pointer, disassociated

@table @asis
@item @emph{Description}:
Returns a disassociated pointer.

If @var{MOLD} is present, a dissassociated pointer of the same type is
returned, otherwise the type is determined by context.

In Fortran 95, @var{MOLD} is optional. Please note that F2003 includes
cases where it is required.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{PTR => NULL([MOLD])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MOLD} @tab (Optional) shall be a pointer of any association
status and of any type.
@end multitable

@item @emph{Return value}:
A disassociated pointer.

@item @emph{Example}:
@smallexample
REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
@end smallexample

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



@node OR
@section @code{OR} --- Bitwise logical OR
@fnindex OR
@cindex bitwise logical or
@cindex logical or, bitwise

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

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
@item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
@end multitable

@item @emph{Return value}:
The return type is either @code{INTEGER(*)} or @code{LOGICAL} 
after cross-promotion of the arguments.

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

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

@item @emph{See also}:
F95 elemental function: @ref{IOR}
@end table



@node PACK
@section @code{PACK} --- Pack an array into an array of rank one
@fnindex PACK
@cindex array, packing
@cindex array, reduce dimension
@cindex array, gather elements

@table @asis
@item @emph{Description}:
Stores the elements of @var{ARRAY} in an array of rank one.

The beginning of the resulting array is made up of elements whose @var{MASK} 
equals @code{TRUE}. Afterwards, positions are filled with elements taken from
@var{VECTOR}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = PACK(ARRAY, MASK[,VECTOR]}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY}  @tab Shall be an array of any type.
@item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and 
of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL} 
scalar.
@item @var{VECTOR} @tab (Optional) shall be an array of the same type 
as @var{ARRAY} and of rank one. If present, the number of elements in 
@var{VECTOR} shall be equal to or greater than the number of true elements 
in @var{MASK}. If @var{MASK} is scalar, the number of elements in 
@var{VECTOR} shall be equal to or greater than the number of elements in
@var{ARRAY}.
@end multitable

@item @emph{Return value}:
The result is an array of rank one and the same type as that of @var{ARRAY}.
If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
number of @code{TRUE} values in @var{MASK} otherwise.

@item @emph{Example}:
Gathering non-zero elements from an array:
@smallexample
PROGRAM test_pack_1
  INTEGER :: m(6)
  m = (/ 1, 0, 0, 0, 5, 0 /)
  WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
END PROGRAM
@end smallexample

Gathering non-zero elements from an array and appending elements from @var{VECTOR}:
@smallexample
PROGRAM test_pack_2
  INTEGER :: m(4)
  m = (/ 1, 0, 0, 2 /)
  WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
END PROGRAM
@end smallexample

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



@node PERROR
@section @code{PERROR} --- Print system error message
@fnindex PERROR
@cindex system, error handling

@table @asis
@item @emph{Description}:
Prints (on the C @code{stderr} stream) a newline-terminated error
message corresponding to the last system error. This is prefixed by
@var{STRING}, a colon and a space. See @code{perror(3)}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL PERROR(STRING)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
@end multitable

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



@node PRECISION
@section @code{PRECISION} --- Decimal precision of a real kind
@fnindex PRECISION
@cindex model representation, precision

@table @asis
@item @emph{Description}:
@code{PRECISION(X)} returns the decimal precision in the model of the
type of @code{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

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

@item @emph{Example}:
@smallexample
program prec_and_range
  real(kind=4) :: x(2)
  complex(kind=8) :: y

  print *, precision(x), range(x)
  print *, precision(y), range(y)
end program prec_and_range
@end smallexample
@end table



@node PRESENT
@section @code{PRESENT} --- Determine whether an optional dummy argument is specified
@fnindex PRESENT

@table @asis
@item @emph{Description}:
Determines whether an optional dummy argument is present.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab May be of any type and may be a pointer, scalar or array
value, or a dummy procedure. It shall be the name of an optional dummy argument
accessible within the current subroutine or function.
@end multitable

@item @emph{Return value}:
Returns either @code{TRUE} if the optional argument @var{A} is present, or
@code{FALSE} otherwise.

@item @emph{Example}:
@smallexample
PROGRAM test_present
  WRITE(*,*) f(), f(42)      ! "F T"
CONTAINS
  LOGICAL FUNCTION f(x)
    INTEGER, INTENT(IN), OPTIONAL :: x
    f = PRESENT(x)
  END FUNCTION
END PROGRAM
@end smallexample
@end table



@node PRODUCT
@section @code{PRODUCT} --- Product of array elements
@fnindex PRODUCT
@cindex array, product
@cindex array, multiply elements
@cindex array, conditionally multiply elements
@cindex multiply array elements

@table @asis
@item @emph{Description}:
Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
the corresponding element in @var{MASK} is @code{TRUE}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)}, 
@code{REAL(*)} or @code{COMPLEX(*)}.
@item @var{DIM}   @tab (Optional) shall be a scalar of type 
@code{INTEGER} with a value in the range from 1 to n, where n 
equals the rank of @var{ARRAY}.
@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL} 
and either be a scalar or an array of the same shape as @var{ARRAY}.
@end multitable

@item @emph{Return value}:
The result is of the same type as @var{ARRAY}.

If @var{DIM} is absent, a scalar with the product of all elements in 
@var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals 
the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with 
dimension @var{DIM} dropped is returned.


@item @emph{Example}:
@smallexample
PROGRAM test_product
  INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
  print *, PRODUCT(x)                    ! all elements, product = 120
  print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
END PROGRAM
@end smallexample

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



@node RADIX
@section @code{RADIX} --- Base of a model number
@fnindex RADIX
@cindex model representation, base
@cindex model representation, radix

@table @asis
@item @emph{Description}:
@code{RADIX(X)} returns the base of the model representing the entity @var{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

@item @emph{Return value}:
The return value is a scalar of type @code{INTEGER} and of the default
integer kind.

@item @emph{Example}:
@smallexample
program test_radix
  print *, "The radix for the default integer kind is", radix(0)
  print *, "The radix for the default real kind is", radix(0.0)
end program test_radix
@end smallexample

@end table



@node RAN
@section @code{RAN} --- Real pseudo-random number
@fnindex RAN
@cindex random number generation

@table @asis
@item @emph{Description}:
For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
provided as an alias for @code{RAND}.  See @ref{RAND} for complete
documentation.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

@item @emph{See also}:
@ref{RAND}, @ref{RANDOM_NUMBER}
@end table



@node RAND
@section @code{RAND} --- Real pseudo-random number
@fnindex RAND
@cindex random number generation

@table @asis
@item @emph{Description}:
@code{RAND(FLAG)} returns a pseudo-random number from a uniform
distribution between 0 and 1. If @var{FLAG} is 0, the next number
in the current sequence is returned; if @var{FLAG} is 1, the generator
is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
it is used as a new seed with @code{SRAND}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
@end multitable

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

@item @emph{Example}:
@smallexample
program test_rand
  integer,parameter :: seed = 86456
  
  call srand(seed)
  print *, rand(), rand(), rand(), rand()
  print *, rand(seed), rand(), rand(), rand()
end program test_rand
@end smallexample

@item @emph{See also}:
@ref{SRAND}, @ref{RANDOM_NUMBER}

@end table



@node RANDOM_NUMBER
@section @code{RANDOM_NUMBER} --- Pseudo-random number
@fnindex RANDOM_NUMBER
@cindex random number generation

@table @asis
@item @emph{Description}:
Returns a single pseudorandom number or an array of pseudorandom numbers
from the uniform distribution over the range @math{ 0 \leq x < 1}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{RANDOM_NUMBER(HARVEST)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
@end multitable

@item @emph{Example}:
@smallexample
program test_random_number
  REAL :: r(5,5)
  CALL init_random_seed()         ! see example of RANDOM_SEED
  CALL RANDOM_NUMBER(r)
end program
@end smallexample

@item @emph{Note}:
The implemented random number generator is thread safe if used within
OpenMP directives, i. e. its state will be consistent while called from
multiple threads. Please note that the currently implemented KISS generator 
does not create random numbers in parallel from multiple sources, but in
sequence from a single source. If your OpenMP-enabled application heavily
relies on random numbers, you should consider employing a dedicated parallel
random number generator instead.

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



@node RANDOM_SEED
@section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
@fnindex RANDOM_SEED
@cindex random number generation, seeding
@cindex seeding a random number generator

@table @asis
@item @emph{Description}:
Restarts or queries the state of the pseudorandom number generator used by 
@code{RANDOM_NUMBER}.

If @code{RANDOM_SEED} is called without arguments, it is initialized to
a default state. The example below shows how to initialize the random 
seed based on the system's time.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL RANDOM_SEED(SIZE, PUT, GET)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SIZE} @tab (Optional) Shall be a scalar and of type default 
@code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size 
of the arrays used with the @var{PUT} and @var{GET} arguments.
@item @var{PUT}  @tab (Optional) Shall be an array of type default 
@code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of 
the array must be larger than or equal to the number returned by the 
@var{SIZE} argument.
@item @var{GET}  @tab (Optional) Shall be an array of type default 
@code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size 
of the array must be larger than or equal to the number returned by 
the @var{SIZE} argument.
@end multitable

@item @emph{Example}:
@smallexample
SUBROUTINE init_random_seed()
  INTEGER :: i, n, clock
  INTEGER, DIMENSION(:), ALLOCATABLE :: seed

  CALL RANDOM_SEED(size = n)
  ALLOCATE(seed(n))

  CALL SYSTEM_CLOCK(COUNT=clock)

  seed = clock + 37 * (/ (i - 1, i = 1, n) /)
  CALL RANDOM_SEED(PUT = seed)

  DEALLOCATE(seed)
END SUBROUTINE
@end smallexample

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



@node RANGE
@section @code{RANGE} --- Decimal exponent range of a real kind
@fnindex RANGE
@cindex model representation, range

@table @asis
@item @emph{Description}:
@code{RANGE(X)} returns the decimal exponent range in the model of the
type of @code{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

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

@item @emph{Example}:
See @code{PRECISION} for an example.
@end table



@node REAL
@section @code{REAL} --- Convert to real type 
@fnindex REAL
@fnindex REALPART
@cindex conversion, to real
@cindex complex numbers, real part

@table @asis
@item @emph{Description}:
@code{REAL(X [, KIND])} converts its argument @var{X} to a real type.  The
@code{REALPART(X)} function is provided for compatibility with @command{g77},
and its use is strongly discouraged.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{RESULT = REAL(X [, KIND])}
@item @code{RESULT = REALPART(Z)}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X}    @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
                      @code{COMPLEX(*)}.
@item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
                      expression indicating the kind parameter of
                      the result.
@end multitable

@item @emph{Return value}:
These functions return a @code{REAL(*)} variable or array under
the following rules: 

@table @asis
@item (A)
@code{REAL(X)} is converted to a default real type if @var{X} is an 
integer or real variable.
@item (B)
@code{REAL(X)} is converted to a real type with the kind type parameter
of @var{X} if @var{X} is a complex variable.
@item (C)
@code{REAL(X, KIND)} is converted to a real type with kind type
parameter @var{KIND} if @var{X} is a complex, integer, or real
variable.
@end table

@item @emph{Example}:
@smallexample
program test_real
  complex :: x = (1.0, 2.0)
  print *, real(x), real(x,8), realpart(x)
end program test_real
@end smallexample

@item @emph{See also}:
@ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}

@end table



@node RENAME
@section @code{RENAME} --- Rename a file
@fnindex RENAME
@cindex file system, rename file

@table @asis
@item @emph{Description}:
Renames a file from file @var{PATH1} to @var{PATH2}. A null
character (@code{CHAR(0)}) can be used to mark the end of the names in
@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
names are ignored.  If the @var{STATUS} argument is supplied, it
contains 0 on success or a nonzero error code upon return; see
@code{rename(2)}.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
@end multitable

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

@end table



@node REPEAT
@section @code{REPEAT} --- Repeated string concatenation 
@fnindex REPEAT
@cindex string, repeat
@cindex string, concatenate

@table @asis
@item @emph{Description}:
Concatenates @var{NCOPIES} copies of a string.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = REPEAT(STRING, NCOPIES)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER(*)}.
@item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
@end multitable

@item @emph{Return value}:
A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies 
of @var{STRING}.

@item @emph{Example}:
@smallexample
program test_repeat
  write(*,*) repeat("x", 5)   ! "xxxxx"
end program
@end smallexample
@end table



@node RESHAPE
@section @code{RESHAPE} --- Function to reshape an array
@fnindex RESHAPE
@cindex array, change dimensions
@cindex array, transmogrify

@table @asis
@item @emph{Description}:
Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
the new array may be padded with elements from @var{PAD} or permuted
as defined by @var{ORDER}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SOURCE} @tab Shall be an array of any type.
@item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an 
array of rank one. Its values must be positive or zero.
@item @var{PAD}    @tab (Optional) shall be an array of the same 
type as @var{SOURCE}.
@item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
and an array of the same shape as @var{SHAPE}. Its values shall
be a permutation of the numbers from 1 to n, where n is the size of 
@var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
be assumed.
@end multitable

@item @emph{Return value}:
The result is an array of shape @var{SHAPE} with the same type as 
@var{SOURCE}. 

@item @emph{Example}:
@smallexample
PROGRAM test_reshape
  INTEGER, DIMENSION(4) :: x
  WRITE(*,*) SHAPE(x)                       ! prints "4"
  WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
END PROGRAM
@end smallexample

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



@node RRSPACING
@section @code{RRSPACING} --- Reciprocal of the relative spacing
@fnindex RRSPACING
@cindex real number, relative spacing
@cindex floating point, relative spacing


@table @asis
@item @emph{Description}:
@code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
model numbers near @var{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

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

@item @emph{Return value}:
The return value is of the same type and kind as @var{X}.
The value returned is equal to
@code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.

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



@node RSHIFT
@section @code{RSHIFT} --- Right shift bits
@fnindex RSHIFT
@cindex bits, shift right

@table @asis
@item @emph{Description}:
@code{RSHIFT} returns a value corresponding to @var{I} with all of the
bits shifted right by @var{SHIFT} places.  If the absolute value of
@var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined. 
Bits shifted out from the left end are lost; zeros are shifted in from
the opposite end.

This function has been superseded by the @code{ISHFT} intrinsic, which
is standard in Fortran 95 and later.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

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

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

@item @emph{Return value}:
The return value is of type @code{INTEGER(*)} and of the same kind as
@var{I}.

@item @emph{See also}:
@ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}

@end table



@node SCALE
@section @code{SCALE} --- Scale a real value
@fnindex SCALE
@cindex real number, scale
@cindex floating point, scale

@table @asis
@item @emph{Description}:
@code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = SCALE(X, I)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type of the argument shall be a @code{REAL}.
@item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and kind as @var{X}.
Its value is @code{X * RADIX(X)**I}.

@item @emph{Example}:
@smallexample
program test_scale
  real :: x = 178.1387e-4
  integer :: i = 5
  print *, scale(x,i), x*radix(x)**i
end program test_scale
@end smallexample

@end table



@node SCAN
@section @code{SCAN} --- Scan a string for the presence of a set of characters
@fnindex SCAN
@cindex string, find subset

@table @asis
@item @emph{Description}:
Scans a @var{STRING} for any of the characters in a @var{SET} 
of characters.

If @var{BACK} is either absent or equals @code{FALSE}, this function
returns the position of the leftmost character of @var{STRING} that is
in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
is returned. If no character of @var{SET} is found in @var{STRING}, the 
result is zero.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = SCAN(STRING, SET[, BACK])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
@item @var{SET}    @tab Shall be of type @code{CHARACTER(*)}.
@item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
@end multitable

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

@item @emph{Example}:
@smallexample
PROGRAM test_scan
  WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
  WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
  WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{INDEX}, @ref{VERIFY}
@end table



@node SECNDS
@section @code{SECNDS} --- Time function
@fnindex SECNDS
@cindex time, elapsed
@cindex elapsed time

@table @asis
@item @emph{Description}:
@code{SECNDS(X)} gets the time in seconds from the real-time system clock.
@var{X} is a reference time, also in seconds. If this is zero, the time in
seconds from midnight is returned. This function is non-standard and its
use is discouraged.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{T}     @tab Shall be of type @code{REAL(4)}.
@item @var{X}     @tab Shall be of type @code{REAL(4)}.
@end multitable

@item @emph{Return value}:
None

@item @emph{Example}:
@smallexample
program test_secnds
    integer :: i
    real(4) :: t1, t2
    print *, secnds (0.0)   ! seconds since midnight
    t1 = secnds (0.0)       ! reference time
    do i = 1, 10000000      ! do something
    end do
    t2 = secnds (t1)        ! elapsed time
    print *, "Something took ", t2, " seconds."
end program test_secnds
@end smallexample
@end table



@node SECOND
@section @code{SECOND} --- CPU time function
@fnindex SECOND
@cindex time, elapsed
@cindex elapsed time

@table @asis
@item @emph{Description}:
Returns a @code{REAL(4)} value representing the elapsed CPU time in
seconds.  This provides the same functionality as the standard
@code{CPU_TIME} intrinsic, and is only included for backwards
compatibility.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{CALL SECOND(TIME)}
@item @code{TIME = SECOND()}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
@end multitable

@item @emph{Return value}:
In either syntax, @var{TIME} is set to the process's current runtime in
seconds.

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

@end table



@node SELECTED_INT_KIND
@section @code{SELECTED_INT_KIND} --- Choose integer kind
@fnindex SELECTED_INT_KIND
@cindex integer kind
@cindex kind, integer

@table @asis
@item @emph{Description}:
@code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
type that can represent all values ranging from @math{-10^I} (exclusive)
to @math{10^I} (exclusive). If there is no integer kind that accommodates
this range, @code{SELECTED_INT_KIND} returns @math{-1}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
@end multitable

@item @emph{Example}:
@smallexample
program large_integers
  integer,parameter :: k5 = selected_int_kind(5)
  integer,parameter :: k15 = selected_int_kind(15)
  integer(kind=k5) :: i5
  integer(kind=k15) :: i15

  print *, huge(i5), huge(i15)

  ! The following inequalities are always true
  print *, huge(i5) >= 10_k5**5-1
  print *, huge(i15) >= 10_k15**15-1
end program large_integers
@end smallexample
@end table



@node SELECTED_REAL_KIND
@section @code{SELECTED_REAL_KIND} --- Choose real kind
@fnindex SELECTED_REAL_KIND
@cindex real kind
@cindex kind, real

@table @asis
@item @emph{Description}:
@code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
with decimal precision greater of at least @code{P} digits and exponent
range greater at least @code{R}. 

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = SELECTED_REAL_KIND(P, R)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
@item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
@end multitable
At least one argument shall be present.

@item @emph{Return value}:

@code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
a real data type with decimal precision of at least @code{P} digits and a
decimal exponent range of at least @code{R}. If more than one real data
type meet the criteria, the kind of the data type with the smallest
decimal precision is returned. If no real data type matches the criteria,
the result is
@table @asis
@item -1 if the processor does not support a real data type with a
precision greater than or equal to @code{P}
@item -2 if the processor does not support a real type with an exponent
range greater than or equal to @code{R}
@item -3 if neither is supported.
@end table

@item @emph{Example}:
@smallexample
program real_kinds
  integer,parameter :: p6 = selected_real_kind(6)
  integer,parameter :: p10r100 = selected_real_kind(10,100)
  integer,parameter :: r400 = selected_real_kind(r=400)
  real(kind=p6) :: x
  real(kind=p10r100) :: y
  real(kind=r400) :: z

  print *, precision(x), range(x)
  print *, precision(y), range(y)
  print *, precision(z), range(z)
end program real_kinds
@end smallexample
@end table



@node SET_EXPONENT
@section @code{SET_EXPONENT} --- Set the exponent of the model
@fnindex SET_EXPONENT
@cindex real number, set exponent
@cindex floating point, set exponent

@table @asis
@item @emph{Description}:
@code{SET_EXPONENT(X, I)} returns the real number whose fractional part
is that that of @var{X} and whose exponent part is @var{I}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = SET_EXPONENT(X, I)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab Shall be of type @code{REAL}.
@item @var{I} @tab Shall be of type @code{INTEGER}.
@end multitable

@item @emph{Return value}:
The return value is of the same type and kind as @var{X}.
The real number whose fractional part
is that that of @var{X} and whose exponent part if @var{I} is returned;
it is @code{FRACTION(X) * RADIX(X)**I}.

@item @emph{Example}:
@smallexample
PROGRAM test_setexp
  REAL :: x = 178.1387e-4
  INTEGER :: i = 17
  PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
END PROGRAM
@end smallexample

@end table



@node SHAPE
@section @code{SHAPE} --- Determine the shape of an array
@fnindex SHAPE
@cindex array, shape

@table @asis
@item @emph{Description}:
Determines the shape of an array.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SOURCE} @tab Shall be an array or scalar of any type. 
If @var{SOURCE} is a pointer it must be associated and allocatable 
arrays must be allocated.
@end multitable

@item @emph{Return value}:
An @code{INTEGER} array of rank one with as many elements as @var{SOURCE} 
has dimensions. The elements of the resulting array correspond to the extend
of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
the result is the rank one array of size zero.

@item @emph{Example}:
@smallexample
PROGRAM test_shape
  INTEGER, DIMENSION(-1:1, -1:2) :: A
  WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
  WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{RESHAPE}, @ref{SIZE}
@end table



@node SIGN
@section @code{SIGN} --- Sign copying function
@fnindex SIGN
@fnindex ISIGN
@fnindex DSIGN
@cindex sign copying

@table @asis
@item @emph{Description}:
@code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = SIGN(A, B)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
@item @var{B} @tab Shall be of the same type and kind as @var{A}
@end multitable

@item @emph{Return value}:
The kind of the return value is that of @var{A} and @var{B}.
If @math{B\ge 0} then the result is @code{ABS(A)}, else
it is @code{-ABS(A)}.

@item @emph{Example}:
@smallexample
program test_sign
  print *, sign(-12,1)
  print *, sign(-12,0)
  print *, sign(-12,-1)

  print *, sign(-12.,1.)
  print *, sign(-12.,0.)
  print *, sign(-12.,-1.)
end program test_sign
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name              @tab Arguments      @tab Return type    @tab Standard
@item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
@item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
@end multitable
@end table



@node SIGNAL
@section @code{SIGNAL} --- Signal handling subroutine (or function)
@fnindex SIGNAL
@cindex system, signal handling

@table @asis
@item @emph{Description}:
@code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
@var{HANDLER} to be executed with a single integer argument when signal
@var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
turn off handling of signal @var{NUMBER} or revert to its default
action.  See @code{signal(2)}.

If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
is supplied, it is set to the value returned by @code{signal(2)}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
@item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
@code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
@code{INTEGER}. It is @code{INTENT(IN)}.
@item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
integer. It has @code{INTENT(OUT)}.
@end multitable

@item @emph{Return value}:
The @code{SIGNAL} function returns the value returned by @code{signal(2)}.

@item @emph{Example}:
@smallexample
program test_signal
  intrinsic signal
  external handler_print

  call signal (12, handler_print)
  call signal (10, 1)

  call sleep (30)
end program test_signal
@end smallexample
@end table



@node SIN
@section @code{SIN} --- Sine function 
@fnindex SIN
@fnindex DSIN
@fnindex CSIN
@fnindex ZSIN
@fnindex CDSIN
@cindex trigonometric function, sine
@cindex sine

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

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = SIN(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_sin
  real :: x = 0.0
  x = sin(x)
end program test_sin
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name            @tab Argument          @tab Return type       @tab Standard
@item @code{DSIN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
@item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
@item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
@item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
@end multitable

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



@node SINH
@section @code{SINH} --- Hyperbolic sine function 
@fnindex SINH
@fnindex DSINH
@cindex hyperbolic sine
@cindex hyperbolic function, sine
@cindex sine, hyperbolic

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

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = SINH(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(*)}.

@item @emph{Example}:
@smallexample
program test_sinh
  real(8) :: x = - 1.0_8
  x = sinh(x)
end program test_sinh
@end smallexample

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

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



@node SIZE
@section @code{SIZE} --- Determine the size of an array
@fnindex SIZE
@cindex array, size
@cindex array, number of elements
@cindex array, count elements

@table @asis
@item @emph{Description}:
Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
or the total number of elements in @var{ARRAY} if @var{DIM} is absent.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
a pointer it must be associated and allocatable arrays must be allocated.
@item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER} 
and its value shall be in the range from 1 to n, where n equals the rank 
of @var{ARRAY}.
@end multitable

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

@item @emph{Example}:
@smallexample
PROGRAM test_size
  WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{SHAPE}, @ref{RESHAPE}
@end table


@node SIZEOF
@section @code{SIZEOF} --- Size in bytes of an expression
@fnindex SIZEOF
@cindex expression size
@cindex size of an expression

@table @asis
@item @emph{Description}:
@code{SIZEOF(X)} calculates the number of bytes of storage the
expression @code{X} occupies.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Intrinsic function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The argument shall be of any type, rank or shape.
@end multitable

@item @emph{Return value}:
The return value is of type integer.  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
   integer :: i
   real :: r, s(5)
   print *, (sizeof(s)/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.
@end table

@node SLEEP
@section @code{SLEEP} --- Sleep for the specified number of seconds
@fnindex SLEEP
@cindex delayed execution

@table @asis
@item @emph{Description}:
Calling this subroutine causes the process to pause for @var{SECONDS} seconds.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL SLEEP(SECONDS)}

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

@item @emph{Example}:
@smallexample
program test_sleep
  call sleep(5)
end
@end smallexample
@end table



@node SNGL
@section @code{SNGL} --- Convert double precision real to default real
@fnindex SNGL
@cindex conversion, to real

@table @asis
@item @emph{Description}:
@code{SNGL(A)} converts the double precision real @var{A}
to a default real value. This is an archaic form of @code{REAL}
that is specific to one type for @var{A}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Elemental function

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

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

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

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



@node SPACING
@section @code{SPACING} --- Smallest distance between two numbers of a given type
@fnindex SPACING
@cindex real number, relative spacing
@cindex floating point, relative spacing

@table @asis
@item @emph{Description}:
Determines the distance between the argument @var{X} and the nearest 
adjacent number of the same type.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab Shall be of type @code{REAL(*)}.
@end multitable

@item @emph{Return value}:
The result is of the same type as the input argument @var{X}.

@item @emph{Example}:
@smallexample
PROGRAM test_spacing
  INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
  INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)

  WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
  WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
END PROGRAM
@end smallexample

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



@node SPREAD
@section @code{SPREAD} --- Add a dimension to an array
@fnindex SPREAD
@cindex array, increase dimension
@cindex array, duplicate elements
@cindex array, duplicate dimensions

@table @asis
@item @emph{Description}:
Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified 
dimension @var{DIM}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SOURCE}  @tab Shall be a scalar or an array of any type and 
a rank less than seven.
@item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a 
value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
@item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
@end multitable

@item @emph{Return value}:
The result is an array of the same type as @var{SOURCE} and has rank n+1
where n equals the rank of @var{SOURCE}.

@item @emph{Example}:
@smallexample
PROGRAM test_spread
  INTEGER :: a = 1, b(2) = (/ 1, 2 /)
  WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
  WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
END PROGRAM
@end smallexample

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



@node SQRT
@section @code{SQRT} --- Square-root function
@fnindex SQRT
@fnindex DSQRT
@fnindex CSQRT
@fnindex ZSQRT
@fnindex CDSQRT
@cindex root
@cindex square-root

@table @asis
@item @emph{Description}:
@code{SQRT(X)} computes the square root of @var{X}.

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = SQRT(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 type @code{REAL(*)} or @code{COMPLEX(*)}.
The kind type parameter is the same as @var{X}.

@item @emph{Example}:
@smallexample
program test_sqrt
  real(8) :: x = 2.0_8
  complex :: z = (1.0, 2.0)
  x = sqrt(x)
  z = sqrt(z)
end program test_sqrt
@end smallexample

@item @emph{Specific names}:
@multitable @columnfractions .20 .20 .20 .25
@item Name             @tab Argument             @tab Return type          @tab Standard
@item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab F95 and later
@item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab F95 and later
@item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
@item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
@end multitable
@end table



@node SRAND
@section @code{SRAND} --- Reinitialize the random number generator
@fnindex SRAND
@cindex random number generation, seeding
@cindex seeding a random number generator

@table @asis
@item @emph{Description}:
@code{SRAND} reinitializes the pseudo-random number generator
called by @code{RAND} and @code{IRAND}. The new seed used by the
generator is specified by the required argument @var{SEED}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL SRAND(SEED)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
@end multitable

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

@item @emph{Example}:
See @code{RAND} and @code{IRAND} for examples.

@item @emph{Notes}:
The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
to generate pseudo-random numbers. Please note that in
GNU Fortran, these two sets of intrinsics (@code{RAND},
@code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
@code{RANDOM_SEED} on the other hand) access two independent
pseudo-random number generators.

@item @emph{See also}:
@ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}

@end table



@node STAT
@section @code{STAT} --- Get file status
@fnindex STAT
@cindex file system, file status

@table @asis
@item @emph{Description}:
This function returns information about a file. No permissions are required on 
the file itself, but execute (search) permission is required on all of the 
directories in path that lead to the file.

The elements that are obtained and stored in the array @code{BUFF}:
@multitable @columnfractions .15 .70
@item @code{buff(1)}   @tab  Device ID 
@item @code{buff(2)}   @tab  Inode number 
@item @code{buff(3)}   @tab  File mode 
@item @code{buff(4)}   @tab  Number of links 
@item @code{buff(5)}   @tab  Owner's uid 
@item @code{buff(6)}   @tab  Owner's gid 
@item @code{buff(7)}   @tab  ID of device containing directory entry for file (0 if not available) 
@item @code{buff(8)}   @tab  File size (bytes) 
@item @code{buff(9)}   @tab  Last access time 
@item @code{buff(10)}  @tab  Last modification time 
@item @code{buff(11)}  @tab  Last file status change time 
@item @code{buff(12)}  @tab  Preferred I/O block size (-1 if not available) 
@item @code{buff(13)}  @tab  Number of blocks allocated (-1 if not available)
@end multitable

Not all these elements are relevant on all systems. 
If an element is not relevant, it is returned as 0.


@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental subroutine

@item @emph{Syntax}:
@code{CALL STAT(FILE,BUFF[,STATUS])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{FILE}   @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
@item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
@item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0 
                        on success and a system specific error code otherwise.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_stat
  INTEGER, DIMENSION(13) :: buff
  INTEGER :: status

  CALL STAT("/etc/passwd", buff, status)

  IF (status == 0) THEN
    WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
    WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
    WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
    WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
    WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
    WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
    WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
    WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
    WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
    WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
    WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
    WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
    WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
  END IF
END PROGRAM
@end smallexample

@item @emph{See also}:
To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
@end table



@node SUM
@section @code{SUM} --- Sum of array elements
@fnindex SUM
@cindex array, sum
@cindex array, add elements
@cindex array, conditionally add elements
@cindex sum array elements

@table @asis
@item @emph{Description}:
Adds the elements of @var{ARRAY} along dimension @var{DIM} if
the corresponding element in @var{MASK} is @code{TRUE}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)}, 
@code{REAL(*)} or @code{COMPLEX(*)}.
@item @var{DIM}   @tab (Optional) shall be a scalar of type 
@code{INTEGER} with a value in the range from 1 to n, where n 
equals the rank of @var{ARRAY}.
@item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL} 
and either be a scalar or an array of the same shape as @var{ARRAY}.
@end multitable

@item @emph{Return value}:
The result is of the same type as @var{ARRAY}.

If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
is returned. Otherwise, an array of rank n-1, where n equals the rank of 
@var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM} 
dropped is returned.

@item @emph{Example}:
@smallexample
PROGRAM test_sum
  INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
  print *, SUM(x)                        ! all elements, sum = 15
  print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
END PROGRAM
@end smallexample

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



@node SYMLNK
@section @code{SYMLNK} --- Create a symbolic link
@fnindex SYMLNK
@cindex file system, create link
@cindex file system, soft link

@table @asis
@item @emph{Description}:
Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
character (@code{CHAR(0)}) can be used to mark the end of the names in
@var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
names are ignored.  If the @var{STATUS} argument is supplied, it
contains 0 on success or a nonzero error code upon return; see
@code{symlink(2)}.  If the system does not supply @code{symlink(2)}, 
@code{ENOSYS} is returned.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
@item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
@end multitable

@item @emph{See also}:
@ref{LINK}, @ref{UNLINK}

@end table



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

@table @asis
@item @emph{Description}:
Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
argument @var{STATUS} is present, it contains the value returned by
@code{system(3)}, which is presumably 0 if the shell command succeeded.
Note that which shell is used to invoke the command is system-dependent
and environment-dependent.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
@item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
@end multitable

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



@node SYSTEM_CLOCK
@section @code{SYSTEM_CLOCK} --- Time function
@fnindex SYSTEM_CLOCK
@cindex time, clock ticks
@cindex clock ticks

@table @asis
@item @emph{Description}:
Determines the @var{COUNT} of milliseconds of wall clock time since 
the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX}, 
@var{COUNT_RATE} determines the number of clock ticks per second.
@var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to 
@command{gfortran}.

If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
@var{COUNT_RATE} and @var{COUNT_MAX} are set to zero 

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}

@item @emph{Arguments}:
@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{COUNT}      @tab (Optional) shall be a scalar of type default 
@code{INTEGER} with @code{INTENT(OUT)}.
@item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default 
@code{INTEGER} with @code{INTENT(OUT)}.
@item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type default 
@code{INTEGER} with @code{INTENT(OUT)}.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_system_clock
  INTEGER :: count, count_rate, count_max
  CALL SYSTEM_CLOCK(count, count_rate, count_max)
  WRITE(*,*) count, count_rate, count_max
END PROGRAM
@end smallexample

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



@node TAN
@section @code{TAN} --- Tangent function
@fnindex TAN
@fnindex DTAN
@cindex trigonometric function, tangent
@cindex tangent

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

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = TAN(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(*)}.  The kind type parameter is
the same as @var{X}.

@item @emph{Example}:
@smallexample
program test_tan
  real(8) :: x = 0.165_8
  x = tan(x)
end program test_tan
@end smallexample

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

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



@node TANH
@section @code{TANH} --- Hyperbolic tangent function 
@fnindex TANH
@fnindex DTANH
@cindex hyperbolic tangent
@cindex hyperbolic function, tangent
@cindex tangent, hyperbolic

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

@item @emph{Standard}:
F77 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{X = TANH(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 lies in the range
@math{ - 1 \leq tanh(x) \leq 1 }.

@item @emph{Example}:
@smallexample
program test_tanh
  real(8) :: x = 2.1_8
  x = tanh(x)
end program test_tanh
@end smallexample

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

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



@node TIME
@section @code{TIME} --- Time function
@fnindex TIME
@cindex time, current
@cindex current time

@table @asis
@item @emph{Description}:
Returns the current time encoded as an integer (in the manner of the
UNIX function @code{time(3)}). This value is suitable for passing to
@code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.

This intrinsic is not fully portable, such as to systems with 32-bit
@code{INTEGER} types but supporting times wider than 32 bits. Therefore,
the values returned by this intrinsic might be, or become, negative, or
numerically less than previous values, during a single run of the
compiled program.

See @ref{TIME8}, for information on a similar intrinsic that might be
portable to more GNU Fortran implementations, though to fewer Fortran
compilers.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Return value}:
The return value is a scalar of type @code{INTEGER(4)}.

@item @emph{See also}:
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}

@end table



@node TIME8
@section @code{TIME8} --- Time function (64-bit)
@fnindex TIME8
@cindex time, current
@cindex current time

@table @asis
@item @emph{Description}:
Returns the current time encoded as an integer (in the manner of the
UNIX function @code{time(3)}). This value is suitable for passing to
@code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.

@emph{Warning:} this intrinsic does not increase the range of the timing
values over that returned by @code{time(3)}. On a system with a 32-bit
@code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
it is converted to a 64-bit @code{INTEGER(8)} value. That means
overflows of the 32-bit value can still occur. Therefore, the values
returned by this intrinsic might be or become negative or numerically
less than previous values during a single run of the compiled program.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

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

@item @emph{See also}:
@ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}

@end table



@node TINY
@section @code{TINY} --- Smallest positive number of a real kind
@fnindex TINY
@cindex limits, smallest number
@cindex model representation, smallest number

@table @asis
@item @emph{Description}:
@code{TINY(X)} returns the smallest positive (non zero) number
in the model of the type of @code{X}.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

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

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

@item @emph{Example}:
See @code{HUGE} for an example.
@end table



@node TRANSFER
@section @code{TRANSFER} --- Transfer bit patterns
@fnindex TRANSFER
@cindex bits, move
@cindex type cast

@table @asis
@item @emph{Description}:
Interprets the bitwise representation of @var{SOURCE} in memory as if it
is the representation of a variable or array of the same type and type
parameters as @var{MOLD}.

This is approximately equivalent to the C concept of @emph{casting} one
type to another.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{SOURCE} @tab Shall be a scalar or an array of any type.
@item @var{MOLD}   @tab Shall be a scalar or an array of any type.
@item @var{SIZE}   @tab (Optional) shall be a scalar of type 
@code{INTEGER}.
@end multitable

@item @emph{Return value}:
The result has the same type as @var{MOLD}, with the bit level
representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
but @var{MOLD} is an array (of any size or shape), the result is a one-
dimensional array of the minimum length needed to contain the entirety
of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
and @var{MOLD} is a scalar, the result is a scalar.

If the bitwise representation of the result is longer than that of
@var{SOURCE}, then the leading bits of the result correspond to those of
@var{SOURCE} and any trailing bits are filled arbitrarily.

When the resulting bit representation does not correspond to a valid
representation of a variable of the same type as @var{MOLD}, the results
are undefined, and subsequent operations on the result cannot be
guaranteed to produce sensible behavior.  For example, it is possible to
create @code{LOGICAL} variables for which @code{@var{VAR}} and
@code{.NOT.@var{VAR}} both appear to be true.

@item @emph{Example}:
@smallexample
PROGRAM test_transfer
  integer :: x = 2143289344
  print *, transfer(x, 1.0)    ! prints "NaN" on i686
END PROGRAM
@end smallexample
@end table



@node TRANSPOSE
@section @code{TRANSPOSE} --- Transpose an array of rank two
@fnindex TRANSPOSE
@cindex array, transpose
@cindex matrix, transpose
@cindex transpose

@table @asis
@item @emph{Description}:
Transpose an array of rank two. Element (i, j) of the result has the value 
@code{MATRIX(j, i)}, for all i, j.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
@end multitable

@item @emph{Return value}:
The result has the the same type as @var{MATRIX}, and has shape 
@code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
@end table



@node TRIM
@section @code{TRIM} --- Remove trailing blank characters of a string
@fnindex TRIM
@cindex string, remove trailing whitespace

@table @asis
@item @emph{Description}:
Removes trailing blank characters of a string.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
@end multitable

@item @emph{Return value}:
A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
less the number of trailing blanks.

@item @emph{Example}:
@smallexample
PROGRAM test_trim
  CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
  WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
END PROGRAM
@end smallexample

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



@node TTYNAM
@section @code{TTYNAM} --- Get the name of a terminal device.
@fnindex TTYNAM
@cindex system, terminal

@table @asis
@item @emph{Description}:
Get the name of a terminal device. For more information, 
see @code{ttyname(3)}.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

@item @emph{Syntax}:
@multitable @columnfractions .80
@item @code{CALL TTYNAM(UNIT, NAME)}
@item @code{NAME = TTYNAM(UNIT)}
@end multitable

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
@item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
@end multitable

@item @emph{Example}:
@smallexample
PROGRAM test_ttynam
  INTEGER :: unit
  DO unit = 1, 10
    IF (isatty(unit=unit)) write(*,*) ttynam(unit)
  END DO
END PROGRAM
@end smallexample

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



@node UBOUND
@section @code{UBOUND} --- Upper dimension bounds of an array
@fnindex UBOUND
@cindex array, upper bound

@table @asis
@item @emph{Description}:
Returns the upper bounds of an array, or a single upper bound
along the @var{DIM} dimension.
@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Inquiry function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{ARRAY} @tab Shall be an array, of any type.
@item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
@end multitable

@item @emph{Return value}:
If @var{DIM} is absent, the result is an array of the upper bounds of
@var{ARRAY}.  If @var{DIM} is present, the result is a scalar
corresponding to the upper bound of the array along that dimension.  If
@var{ARRAY} is an expression rather than a whole array or array
structure component, or if it has a zero extent along the relevant
dimension, the upper bound is taken to be the number of elements along
the relevant dimension.

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



@node UMASK
@section @code{UMASK} --- Set the file creation mask
@fnindex UMASK
@cindex file system, file creation mask

@table @asis
@item @emph{Description}:
Sets the file creation mask to @var{MASK} and returns the old value in
argument @var{OLD} if it is supplied. See @code{umask(2)}.

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine

@item @emph{Syntax}:
@code{CALL UMASK(MASK [, OLD])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
@item @var{MASK} @tab (Optional) Shall be a scalar of type
                      @code{INTEGER(*)}.
@end multitable

@end table



@node UNLINK
@section @code{UNLINK} --- Remove a file from the file system
@fnindex UNLINK
@cindex file system, remove file

@table @asis
@item @emph{Description}:
Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
used to mark the end of the name in @var{PATH}; otherwise, trailing
blanks in the file name are ignored.  If the @var{STATUS} argument is
supplied, it contains 0 on success or a nonzero error code upon return;
see @code{unlink(2)}.

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Subroutine, non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
@item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
@end multitable

@item @emph{See also}:
@ref{LINK}, @ref{SYMLNK}
@end table



@node UNPACK
@section @code{UNPACK} --- Unpack an array of rank one into an array
@fnindex UNPACK
@cindex array, unpacking
@cindex array, increase dimension
@cindex array, scatter elements

@table @asis
@item @emph{Description}:
Store the elements of @var{VECTOR} in an array of higher rank.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Transformational function

@item @emph{Syntax}:
@code{RESULT = UNPACK(VECTOR, MASK, FIELD)}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{VECTOR} @tab Shall be an array of any type and rank one. It 
shall have at least as many elements as @var{MASK} has @code{TRUE} values.
@item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
@item @var{FIELD}  @tab Shall be of the sam type as @var{VECTOR} and have
the same shape as @var{MASK}.
@end multitable

@item @emph{Return value}:
The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
of @var{MASK} replaced by values from @var{VECTOR} in array element order.

@item @emph{Example}:
@smallexample
PROGRAM test_unpack
  integer :: vector(2)  = (/1,1/)
  logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
  integer :: field(2,2) = 0, unity(2,2)

  ! result: unity matrix
  unity = unpack(vector, reshape(mask, (/2,2/)), field)
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{PACK}, @ref{SPREAD}
@end table



@node VERIFY
@section @code{VERIFY} --- Scan a string for the absence of a set of characters
@fnindex VERIFY
@cindex string, find missing set

@table @asis
@item @emph{Description}:
Verifies that all the characters in a @var{SET} are present in a @var{STRING}.

If @var{BACK} is either absent or equals @code{FALSE}, this function
returns the position of the leftmost character of @var{STRING} that is
not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
is returned. If all characters of @var{SET} are found in @var{STRING}, the 
result is zero.

@item @emph{Standard}:
F95 and later

@item @emph{Class}:
Elemental function

@item @emph{Syntax}:
@code{RESULT = VERFIY(STRING, SET[, BACK])}

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
@item @var{SET}    @tab Shall be of type @code{CHARACTER(*)}.
@item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
@end multitable

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

@item @emph{Example}:
@smallexample
PROGRAM test_verify
  WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
  WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
  WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
  WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
  WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
END PROGRAM
@end smallexample

@item @emph{See also}:
@ref{SCAN}, @ref{INDEX}
@end table



@node XOR
@section @code{XOR} --- Bitwise logical exclusive OR
@fnindex XOR
@cindex bitwise logical exclusive or
@cindex logical exclusive or, bitwise

@table @asis
@item @emph{Description}:
Bitwise logical exclusive or. 

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

@item @emph{Standard}:
GNU extension

@item @emph{Class}:
Non-elemental function

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

@item @emph{Arguments}:
@multitable @columnfractions .15 .70
@item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
@item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
@end multitable

@item @emph{Return value}:
The return type is either @code{INTEGER(*)} or @code{LOGICAL}
after cross-promotion of the arguments.

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

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

@item @emph{See also}:
F95 elemental function: @ref{IEOR}
@end table