gcc/fortran/intrinsic.texi

   1 @ignore
   2 Copyright (C) 2005, 2006, 2007, 2008
   3 Free Software Foundation, Inc.
   4 This is part of the GNU Fortran manual.
   5 For copying conditions, see the file gfortran.texi.
   6
   7 Permission is granted to copy, distribute and/or modify this document
   8 under the terms of the GNU Free Documentation License, Version 1.2 or
   9 any later version published by the Free Software Foundation; with the
  10 Invariant Sections being ``GNU General Public License'' and ``Funding
  11 Free Software'', the Front-Cover texts being (a) (see below), and with
  12 the Back-Cover Texts being (b) (see below).  A copy of the license is
  13 included in the gfdl(7) man page.
  14
  15
  16 Some basic guidelines for editing this document:
  17
  18   (1) The intrinsic procedures are to be listed in alphabetical order.
  19   (2) The generic name is to be used.
  20   (3) The specific names are included in the function index and in a
  21       table at the end of the node (See ABS entry).
  22   (4) Try to maintain the same style for each entry.
  23
  24
  25 @end ignore
  26
  27 @tex
  28 \gdef\acos{\mathop{\rm acos}\nolimits}
  29 \gdef\asin{\mathop{\rm asin}\nolimits}
  30 \gdef\atan{\mathop{\rm atan}\nolimits}
  31 \gdef\acosh{\mathop{\rm acosh}\nolimits}
  32 \gdef\asinh{\mathop{\rm asinh}\nolimits}
  33 \gdef\atanh{\mathop{\rm atanh}\nolimits}
  34 @end tex
  35
  36
  37 @node Intrinsic Procedures
  38 @chapter Intrinsic Procedures
  39 @cindex intrinsic procedures
  40
  41 @menu
  42 * Introduction:         Introduction to Intrinsics
  43 * @code{ABORT}:         ABORT,     Abort the program
  44 * @code{ABS}:           ABS,       Absolute value
  45 * @code{ACCESS}:        ACCESS,    Checks file access modes
  46 * @code{ACHAR}:         ACHAR,     Character in @acronym{ASCII} collating sequence
  47 * @code{ACOS}:          ACOS,      Arccosine function
  48 * @code{ACOSH}:         ACOSH,     Hyperbolic arccosine function
  49 * @code{ADJUSTL}:       ADJUSTL,   Left adjust a string
  50 * @code{ADJUSTR}:       ADJUSTR,   Right adjust a string
  51 * @code{AIMAG}:         AIMAG,     Imaginary part of complex number
  52 * @code{AINT}:          AINT,      Truncate to a whole number
  53 * @code{ALARM}:         ALARM,     Set an alarm clock
  54 * @code{ALL}:           ALL,       Determine if all values are true
  55 * @code{ALLOCATED}:     ALLOCATED, Status of allocatable entity
  56 * @code{AND}:           AND,       Bitwise logical AND
  57 * @code{ANINT}:         ANINT,     Nearest whole number
  58 * @code{ANY}:           ANY,       Determine if any values are true
  59 * @code{ASIN}:          ASIN,      Arcsine function
  60 * @code{ASINH}:         ASINH,     Hyperbolic arcsine function
  61 * @code{ASSOCIATED}:    ASSOCIATED, Status of a pointer or pointer/target pair
  62 * @code{ATAN}:          ATAN,      Arctangent function
  63 * @code{ATAN2}:         ATAN2,     Arctangent function
  64 * @code{ATANH}:         ATANH,     Hyperbolic arctangent function
  65 * @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
  66 * @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
  67 * @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
  68 * @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
  69 * @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
  70 * @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
  71 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  72 * @code{BTEST}:         BTEST,     Bit test function
  73 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
  74 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
  75 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
  76 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
  77 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
  78 * @code{CEILING}:       CEILING,   Integer ceiling function
  79 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
  80 * @code{CHDIR}:         CHDIR,     Change working directory
  81 * @code{CHMOD}:         CHMOD,     Change access permissions of files
  82 * @code{CMPLX}:         CMPLX,     Complex conversion function
  83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
  84 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
  85 * @code{CONJG}:         CONJG,     Complex conjugate function
  86 * @code{COS}:           COS,       Cosine function
  87 * @code{COSH}:          COSH,      Hyperbolic cosine function
  88 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
  89 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  90 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
  91 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
  92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
  93 * @code{DBLE}:          DBLE,      Double precision conversion function
  94 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
  95 * @code{DFLOAT}:        DFLOAT,    Double precision conversion function
  96 * @code{DIGITS}:        DIGITS,    Significant digits function
  97 * @code{DIM}:           DIM,       Positive difference
  98 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
  99 * @code{DPROD}:         DPROD,     Double product function
 100 * @code{DREAL}:         DREAL,     Double real part function
 101 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 102 * @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
 103 * @code{EPSILON}:       EPSILON,   Epsilon function
 104 * @code{ERF}:           ERF,       Error function
 105 * @code{ERFC}:          ERFC,      Complementary error function
 106 * @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
 107 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
 108 * @code{EXIT}:          EXIT,      Exit the program with status.
 109 * @code{EXP}:           EXP,       Exponential function
 110 * @code{EXPONENT}:      EXPONENT,  Exponent function
 111 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
 112 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
 113 * @code{FGETC}:         FGETC,     Read a single character in stream mode
 114 * @code{FLOAT}:         FLOAT,     Convert integer to default real
 115 * @code{FLOOR}:         FLOOR,     Integer floor function
 116 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
 117 * @code{FNUM}:          FNUM,      File number function
 118 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
 119 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
 120 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
 121 * @code{FREE}:          FREE,      Memory de-allocation subroutine
 122 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
 123 * @code{FSTAT}:         FSTAT,     Get file status
 124 * @code{FTELL}:         FTELL,     Current stream position
 125 * @code{GAMMA}:         GAMMA,     Gamma function
 126 * @code{GERROR}:        GERROR,    Get last system error message
 127 * @code{GETARG}:        GETARG,    Get command line arguments
 128 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
 129 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
 130 * @code{GETCWD}:        GETCWD,    Get current working directory
 131 * @code{GETENV}:        GETENV,    Get an environmental variable
 132 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
 133 * @code{GETGID}:        GETGID,    Group ID function
 134 * @code{GETLOG}:        GETLOG,    Get login name
 135 * @code{GETPID}:        GETPID,    Process ID function
 136 * @code{GETUID}:        GETUID,    User ID function
 137 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
 138 * @code{HOSTNM}:        HOSTNM,    Get system host name
 139 * @code{HUGE}:          HUGE,      Largest number of a kind
 140 * @code{HYPOT}:         HYPOT,     Euclidian distance function
 141 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
 142 * @code{IAND}:          IAND,      Bitwise logical and
 143 * @code{IARGC}:         IARGC,     Get the number of command line arguments
 144 * @code{IBCLR}:         IBCLR,     Clear bit
 145 * @code{IBITS}:         IBITS,     Bit extraction
 146 * @code{IBSET}:         IBSET,     Set bit
 147 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
 148 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
 149 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
 150 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
 151 * @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
 152 * @code{INT}:           INT,       Convert to integer type
 153 * @code{INT2}:          INT2,      Convert to 16-bit integer type
 154 * @code{INT8}:          INT8,      Convert to 64-bit integer type
 155 * @code{IOR}:           IOR,       Bitwise logical or
 156 * @code{IRAND}:         IRAND,     Integer pseudo-random number
 157 * @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
 158 * @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
 159 * @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
 160 * @code{ISHFT}:         ISHFT,     Shift bits
 161 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
 162 * @code{ISNAN}:         ISNAN,     Tests for a NaN
 163 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
 164 * @code{KILL}:          KILL,      Send a signal to a process
 165 * @code{KIND}:          KIND,      Kind of an entity
 166 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
 167 * @code{LEN}:           LEN,       Length of a character entity
 168 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
 169 * @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
 170 * @code{LGE}:           LGE,       Lexical greater than or equal
 171 * @code{LGT}:           LGT,       Lexical greater than
 172 * @code{LINK}:          LINK,      Create a hard link
 173 * @code{LLE}:           LLE,       Lexical less than or equal
 174 * @code{LLT}:           LLT,       Lexical less than
 175 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
 176 * @code{LOC}:           LOC,       Returns the address of a variable
 177 * @code{LOG}:           LOG,       Logarithm function
 178 * @code{LOG10}:         LOG10,     Base 10 logarithm function
 179 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
 180 * @code{LONG}:          LONG,      Convert to integer type
 181 * @code{LSHIFT}:        LSHIFT,    Left shift bits
 182 * @code{LSTAT}:         LSTAT,     Get file status
 183 * @code{LTIME}:         LTIME,     Convert time to local time info
 184 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
 185 * @code{MATMUL}:        MATMUL,    matrix multiplication
 186 * @code{MAX}:           MAX,       Maximum value of an argument list
 187 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
 188 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
 189 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
 190 * @code{MCLOCK}:        MCLOCK,    Time function
 191 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
 192 * @code{MERGE}:         MERGE,     Merge arrays
 193 * @code{MIN}:           MIN,       Minimum value of an argument list
 194 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
 195 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
 196 * @code{MINVAL}:        MINVAL,    Minimum value of an array
 197 * @code{MOD}:           MOD,       Remainder function
 198 * @code{MODULO}:        MODULO,    Modulo function
 199 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
 200 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
 201 * @code{NEAREST}:       NEAREST,   Nearest representable number
 202 * @code{NEW_LINE}:      NEW_LINE,  New line character
 203 * @code{NINT}:          NINT,      Nearest whole number
 204 * @code{NOT}:           NOT,       Logical negation
 205 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
 206 * @code{OR}:            OR,        Bitwise logical OR
 207 * @code{PACK}:          PACK,      Pack an array into an array of rank one
 208 * @code{PERROR}:        PERROR,    Print system error message
 209 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
 210 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
 211 * @code{PRODUCT}:       PRODUCT,   Product of array elements
 212 * @code{RADIX}:         RADIX,     Base of a data model
 213 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
 214 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
 215 * @code{RAND}:          RAND,      Real pseudo-random number
 216 * @code{RANGE}:         RANGE,     Decimal exponent range of a real kind
 217 * @code{RAN}:           RAN,       Real pseudo-random number
 218 * @code{REAL}:          REAL,      Convert to real type
 219 * @code{RENAME}:        RENAME,    Rename a file
 220 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
 221 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
 222 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
 223 * @code{RSHIFT}:        RSHIFT,    Right shift bits
 224 * @code{SCALE}:         SCALE,     Scale a real value
 225 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
 226 * @code{SECNDS}:        SECNDS,    Time function
 227 * @code{SECOND}:        SECOND,    CPU time function
 228 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
 229 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
 230 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
 231 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
 232 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
 233 * @code{SIGN}:          SIGN,      Sign copying function
 234 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
 235 * @code{SIN}:           SIN,       Sine function
 236 * @code{SINH}:          SINH,      Hyperbolic sine function
 237 * @code{SIZE}:          SIZE,      Function to determine the size of an array
 238 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
 239 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
 240 * @code{SNGL}:          SNGL,      Convert double precision real to default real
 241 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
 242 * @code{SPREAD}:        SPREAD,    Add a dimension to an array
 243 * @code{SQRT}:          SQRT,      Square-root function
 244 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
 245 * @code{STAT}:          STAT,      Get file status
 246 * @code{SUM}:           SUM,       Sum of array elements
 247 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
 248 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
 249 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
 250 * @code{TAN}:           TAN,       Tangent function
 251 * @code{TANH}:          TANH,      Hyperbolic tangent function
 252 * @code{TIME}:          TIME,      Time function
 253 * @code{TIME8}:         TIME8,     Time function (64-bit)
 254 * @code{TINY}:          TINY,      Smallest positive number of a real kind
 255 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
 256 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
 257 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
 258 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
 259 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
 260 * @code{UMASK}:         UMASK,     Set the file creation mask
 261 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
 262 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
 263 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
 264 * @code{XOR}:           XOR,       Bitwise logical exclusive or
 265 @end menu
 266
 267 @node Introduction to Intrinsics
 268 @section Introduction to intrinsic procedures
 269
 270 The intrinsic procedures provided by GNU Fortran include all of the
 271 intrinsic procedures required by the Fortran 95 standard, a set of
 272 intrinsic procedures for backwards compatibility with G77, and a
 273 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
 274 standards.  Any conflict between a description here and a description in
 275 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
 276 2008 standard is unintentional, and the standard(s) should be considered
 277 authoritative.
 278
 279 The enumeration of the @code{KIND} type parameter is processor defined in
 280 the Fortran 95 standard.  GNU Fortran defines the default integer type and
 281 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 282 respectively.  The standard mandates that both data types shall have
 283 another kind, which have more precision.  On typical target architectures
 284 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 285 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 286 In the description of generic intrinsic procedures, the kind type parameter
 287 will be specified by @code{KIND=*}, and in the description of specific
 288 names for an intrinsic procedure the kind type parameter will be explicitly
 289 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 290 brevity the optional @code{KIND=} syntax will be omitted.
 291
 292 Many of the intrinsic procedures take one or more optional arguments.
 293 This document follows the convention used in the Fortran 95 standard,
 294 and denotes such arguments by square brackets.
 295
 296 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
 297 which can be used to restrict the set of intrinsic procedures to a
 298 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 299 option, and so all intrinsic procedures described here are accepted.  There
 300 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 301 implemented both a function and a subroutine.  Both classes
 302 have been implemented in @command{gfortran} for backwards compatibility
 303 with @command{g77}.  It is noted here that these functions and subroutines
 304 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 305 the applicable standard for each intrinsic procedure is noted.
 306
 307
 308
 309 @node ABORT
 310 @section @code{ABORT} --- Abort the program
 311 @fnindex ABORT
 312 @cindex program termination, with core dump
 313 @cindex terminate program, with core dump
 314 @cindex core, dump
 315
 316 @table @asis
 317 @item @emph{Description}:
 318 @code{ABORT} causes immediate termination of the program.  On operating
 319 systems that support a core dump, @code{ABORT} will produce a core dump,
 320 which is suitable for debugging purposes.
 321
 322 @item @emph{Standard}:
 323 GNU extension
 324
 325 @item @emph{Class}:
 326 Subroutine
 327
 328 @item @emph{Syntax}:
 329 @code{CALL ABORT}
 330
 331 @item @emph{Return value}:
 332 Does not return.
 333
 334 @item @emph{Example}:
 335 @smallexample
 336 program test_abort
 337   integer :: i = 1, j = 2
 338   if (i /= j) call abort
 339 end program test_abort
 340 @end smallexample
 341
 342 @item @emph{See also}:
 343 @ref{EXIT}, @ref{KILL}
 344
 345 @end table
 346
 347
 348
 349 @node ABS
 350 @section @code{ABS} --- Absolute value
 351 @fnindex ABS
 352 @fnindex CABS
 353 @fnindex DABS
 354 @fnindex IABS
 355 @fnindex ZABS
 356 @fnindex CDABS
 357 @cindex absolute value
 358
 359 @table @asis
 360 @item @emph{Description}:
 361 @code{ABS(A)} computes the absolute value of @code{A}.
 362
 363 @item @emph{Standard}:
 364 Fortran 77 and later, has overloads that are GNU extensions
 365
 366 @item @emph{Class}:
 367 Elemental function
 368
 369 @item @emph{Syntax}:
 370 @code{RESULT = ABS(A)}
 371
 372 @item @emph{Arguments}:
 373 @multitable @columnfractions .15 .70
 374 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
 375 @code{REAL}, or @code{COMPLEX}.
 376 @end multitable
 377
 378 @item @emph{Return value}:
 379 The return value is of the same type and
 380 kind as the argument except the return value is @code{REAL} for a
 381 @code{COMPLEX} argument.
 382
 383 @item @emph{Example}:
 384 @smallexample
 385 program test_abs
 386   integer :: i = -1
 387   real :: x = -1.e0
 388   complex :: z = (-1.e0,0.e0)
 389   i = abs(i)
 390   x = abs(x)
 391   x = abs(z)
 392 end program test_abs
 393 @end smallexample
 394
 395 @item @emph{Specific names}:
 396 @multitable @columnfractions .20 .20 .20 .25
 397 @item Name            @tab Argument            @tab Return type       @tab Standard
 398 @item @code{CABS(A)}  @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)}    @tab Fortran 77 and later
 399 @item @code{DABS(A)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}    @tab Fortran 77 and later
 400 @item @code{IABS(A)}  @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
 401 @item @code{ZABS(A)}  @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
 402 @item @code{CDABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
 403 @end multitable
 404 @end table
 405
 406
 407
 408 @node ACCESS
 409 @section @code{ACCESS} --- Checks file access modes
 410 @fnindex ACCESS
 411 @cindex file system, access mode
 412
 413 @table @asis
 414 @item @emph{Description}:
 415 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
 416 exists, is readable, writable or executable. Except for the
 417 executable check, @code{ACCESS} can be replaced by
 418 Fortran 95's @code{INQUIRE}.
 419
 420 @item @emph{Standard}:
 421 GNU extension
 422
 423 @item @emph{Class}:
 424 Inquiry function
 425
 426 @item @emph{Syntax}:
 427 @code{RESULT = ACCESS(NAME, MODE)}
 428
 429 @item @emph{Arguments}:
 430 @multitable @columnfractions .15 .70
 431 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
 432 file name. Tailing blank are ignored unless the character @code{achar(0)}
 433 is present, then all characters up to and excluding @code{achar(0)} are
 434 used as file name.
 435 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
 436 file access mode, may be any concatenation of @code{"r"} (readable),
 437 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
 438 for existence.
 439 @end multitable
 440
 441 @item @emph{Return value}:
 442 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
 443 accessible in the given mode; otherwise or if an invalid argument
 444 has been given for @code{MODE} the value @code{1} is returned.
 445
 446 @item @emph{Example}:
 447 @smallexample
 448 program access_test
 449   implicit none
 450   character(len=*), parameter :: file  = 'test.dat'
 451   character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
 452   if(access(file,' ') == 0) print *, trim(file),' is exists'
 453   if(access(file,'r') == 0) print *, trim(file),' is readable'
 454   if(access(file,'w') == 0) print *, trim(file),' is writable'
 455   if(access(file,'x') == 0) print *, trim(file),' is executable'
 456   if(access(file2,'rwx') == 0) &
 457     print *, trim(file2),' is readable, writable and executable'
 458 end program access_test
 459 @end smallexample
 460 @item @emph{Specific names}:
 461 @item @emph{See also}:
 462
 463 @end table
 464
 465
 466
 467 @node ACHAR
 468 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
 469 @fnindex ACHAR
 470 @cindex @acronym{ASCII} collating sequence
 471 @cindex collating sequence, @acronym{ASCII}
 472
 473 @table @asis
 474 @item @emph{Description}:
 475 @code{ACHAR(I)} returns the character located at position @code{I}
 476 in the @acronym{ASCII} collating sequence.
 477
 478 @item @emph{Standard}:
 479 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
 480
 481 @item @emph{Class}:
 482 Elemental function
 483
 484 @item @emph{Syntax}:
 485 @code{RESULT = ACHAR(I [, KIND])}
 486
 487 @item @emph{Arguments}:
 488 @multitable @columnfractions .15 .70
 489 @item @var{I}    @tab The type shall be @code{INTEGER}.
 490 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 491                       expression indicating the kind parameter of
 492                       the result.
 493 @end multitable
 494
 495 @item @emph{Return value}:
 496 The return value is of type @code{CHARACTER} with a length of one.
 497 If the @var{KIND} argument is present, the return value is of the
 498 specified kind and of the default kind otherwise.
 499
 500 @item @emph{Example}:
 501 @smallexample
 502 program test_achar
 503   character c
 504   c = achar(32)
 505 end program test_achar
 506 @end smallexample
 507
 508 @item @emph{Note}:
 509 See @ref{ICHAR} for a discussion of converting between numerical values
 510 and formatted string representations.
 511
 512 @item @emph{See also}:
 513 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
 514
 515 @end table
 516
 517
 518
 519 @node ACOS
 520 @section @code{ACOS} --- Arccosine function
 521 @fnindex ACOS
 522 @fnindex DACOS
 523 @cindex trigonometric function, cosine, inverse
 524 @cindex cosine, inverse
 525
 526 @table @asis
 527 @item @emph{Description}:
 528 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
 529
 530 @item @emph{Standard}:
 531 Fortran 77 and later
 532
 533 @item @emph{Class}:
 534 Elemental function
 535
 536 @item @emph{Syntax}:
 537 @code{RESULT = ACOS(X)}
 538
 539 @item @emph{Arguments}:
 540 @multitable @columnfractions .15 .70
 541 @item @var{X} @tab The type shall be @code{REAL} with a magnitude that is
 542 less than one.
 543 @end multitable
 544
 545 @item @emph{Return value}:
 546 The return value is of type @code{REAL} and it lies in the
 547 range @math{ 0 \leq \acos(x) \leq \pi}. The return value if of the same
 548 kind as @var{X}.
 549
 550 @item @emph{Example}:
 551 @smallexample
 552 program test_acos
 553   real(8) :: x = 0.866_8
 554   x = acos(x)
 555 end program test_acos
 556 @end smallexample
 557
 558 @item @emph{Specific names}:
 559 @multitable @columnfractions .20 .20 .20 .25
 560 @item Name            @tab Argument          @tab Return type       @tab Standard
 561 @item @code{DACOS(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
 562 @end multitable
 563
 564 @item @emph{See also}:
 565 Inverse function: @ref{COS}
 566
 567 @end table
 568
 569
 570
 571 @node ACOSH
 572 @section @code{ACOSH} --- Hyperbolic arccosine function
 573 @fnindex ACOSH
 574 @fnindex DACOSH
 575 @cindex area hyperbolic cosine
 576 @cindex hyperbolic arccosine
 577 @cindex hyperbolic function, cosine, inverse
 578 @cindex cosine, hyperbolic, inverse
 579
 580 @table @asis
 581 @item @emph{Description}:
 582 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
 583 @code{COSH(X)}).
 584
 585 @item @emph{Standard}:
 586 Fortran 2008 and later
 587
 588 @item @emph{Class}:
 589 Elemental function
 590
 591 @item @emph{Syntax}:
 592 @code{RESULT = ACOSH(X)}
 593
 594 @item @emph{Arguments}:
 595 @multitable @columnfractions .15 .70
 596 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
 597 @end multitable
 598
 599 @item @emph{Return value}:
 600 The return value has the same type and kind as @var{X}
 601
 602 @item @emph{Example}:
 603 @smallexample
 604 PROGRAM test_acosh
 605   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
 606   WRITE (*,*) ACOSH(x)
 607 END PROGRAM
 608 @end smallexample
 609
 610 @item @emph{Specific names}:
 611 @multitable @columnfractions .20 .20 .20 .25
 612 @item Name             @tab Argument          @tab Return type       @tab Standard
 613 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
 614 @end multitable
 615
 616 @item @emph{See also}:
 617 Inverse function: @ref{COSH}
 618 @end table
 619
 620
 621
 622 @node ADJUSTL
 623 @section @code{ADJUSTL} --- Left adjust a string
 624 @fnindex ADJUSTL
 625 @cindex string, adjust left
 626 @cindex adjust string
 627
 628 @table @asis
 629 @item @emph{Description}:
 630 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
 631 Spaces are inserted at the end of the string as needed.
 632
 633 @item @emph{Standard}:
 634 Fortran 95 and later
 635
 636 @item @emph{Class}:
 637 Elemental function
 638
 639 @item @emph{Syntax}:
 640 @code{RESULT = ADJUSTL(STRING)}
 641
 642 @item @emph{Arguments}:
 643 @multitable @columnfractions .15 .70
 644 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
 645 @end multitable
 646
 647 @item @emph{Return value}:
 648 The return value is of type @code{CHARACTER} and of the same kind as
 649 @var{STRING} where leading spaces are removed and the same number of
 650 spaces are inserted on the end of @var{STRING}.
 651
 652 @item @emph{Example}:
 653 @smallexample
 654 program test_adjustl
 655   character(len=20) :: str = '   gfortran'
 656   str = adjustl(str)
 657   print *, str
 658 end program test_adjustl
 659 @end smallexample
 660
 661 @item @emph{See also}:
 662 @ref{ADJUSTR}, @ref{TRIM}
 663 @end table
 664
 665
 666
 667 @node ADJUSTR
 668 @section @code{ADJUSTR} --- Right adjust a string
 669 @fnindex ADJUSTR
 670 @cindex string, adjust right
 671 @cindex adjust string
 672
 673 @table @asis
 674 @item @emph{Description}:
 675 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
 676 Spaces are inserted at the start of the string as needed.
 677
 678 @item @emph{Standard}:
 679 Fortran 95 and later
 680
 681 @item @emph{Class}:
 682 Elemental function
 683
 684 @item @emph{Syntax}:
 685 @code{RESULT = ADJUSTR(STRING)}
 686
 687 @item @emph{Arguments}:
 688 @multitable @columnfractions .15 .70
 689 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 690 @end multitable
 691
 692 @item @emph{Return value}:
 693 The return value is of type @code{CHARACTER} and of the same kind as
 694 @var{STRING} where trailing spaces are removed and the same number of
 695 spaces are inserted at the start of @var{STRING}.
 696
 697 @item @emph{Example}:
 698 @smallexample
 699 program test_adjustr
 700   character(len=20) :: str = 'gfortran'
 701   str = adjustr(str)
 702   print *, str
 703 end program test_adjustr
 704 @end smallexample
 705
 706 @item @emph{See also}:
 707 @ref{ADJUSTL}, @ref{TRIM}
 708 @end table
 709
 710
 711
 712 @node AIMAG
 713 @section @code{AIMAG} --- Imaginary part of complex number
 714 @fnindex AIMAG
 715 @fnindex DIMAG
 716 @fnindex IMAG
 717 @fnindex IMAGPART
 718 @cindex complex numbers, imaginary part
 719
 720 @table @asis
 721 @item @emph{Description}:
 722 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
 723 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
 724 for compatibility with @command{g77}, and their use in new code is
 725 strongly discouraged.
 726
 727 @item @emph{Standard}:
 728 Fortran 77 and later, has overloads that are GNU extensions
 729
 730 @item @emph{Class}:
 731 Elemental function
 732
 733 @item @emph{Syntax}:
 734 @code{RESULT = AIMAG(Z)}
 735
 736 @item @emph{Arguments}:
 737 @multitable @columnfractions .15 .70
 738 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
 739 @end multitable
 740
 741 @item @emph{Return value}:
 742 The return value is of type @code{REAL} with the
 743 kind type parameter of the argument.
 744
 745 @item @emph{Example}:
 746 @smallexample
 747 program test_aimag
 748   complex(4) z4
 749   complex(8) z8
 750   z4 = cmplx(1.e0_4, 0.e0_4)
 751   z8 = cmplx(0.e0_8, 1.e0_8)
 752   print *, aimag(z4), dimag(z8)
 753 end program test_aimag
 754 @end smallexample
 755
 756 @item @emph{Specific names}:
 757 @multitable @columnfractions .20 .20 .20 .25
 758 @item Name            @tab Argument            @tab Return type       @tab Standard
 759 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}    @tab GNU extension
 760 @item @code{IMAG(Z)}  @tab @code{COMPLEX Z} @tab @code{REAL}    @tab GNU extension
 761 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
 762 @end multitable
 763 @end table
 764
 765
 766
 767 @node AINT
 768 @section @code{AINT} --- Truncate to a whole number
 769 @fnindex AINT
 770 @fnindex DINT
 771 @cindex floor
 772 @cindex rounding, floor
 773
 774 @table @asis
 775 @item @emph{Description}:
 776 @code{AINT(A [, KIND])} truncates its argument to a whole number.
 777
 778 @item @emph{Standard}:
 779 Fortran 77 and later
 780
 781 @item @emph{Class}:
 782 Elemental function
 783
 784 @item @emph{Syntax}:
 785 @code{RESULT = AINT(A [, KIND])}
 786
 787 @item @emph{Arguments}:
 788 @multitable @columnfractions .15 .70
 789 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
 790 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 791                       expression indicating the kind parameter of
 792                       the result.
 793 @end multitable
 794
 795 @item @emph{Return value}:
 796 The return value is of type @code{REAL} with the kind type parameter of the
 797 argument if the optional @var{KIND} is absent; otherwise, the kind
 798 type parameter will be given by @var{KIND}.  If the magnitude of
 799 @var{X} is less than one, @code{AINT(X)} returns zero.  If the
 800 magnitude is equal to or greater than one then it returns the largest
 801 whole number that does not exceed its magnitude.  The sign is the same
 802 as the sign of @var{X}.
 803
 804 @item @emph{Example}:
 805 @smallexample
 806 program test_aint
 807   real(4) x4
 808   real(8) x8
 809   x4 = 1.234E0_4
 810   x8 = 4.321_8
 811   print *, aint(x4), dint(x8)
 812   x8 = aint(x4,8)
 813 end program test_aint
 814 @end smallexample
 815
 816 @item @emph{Specific names}:
 817 @multitable @columnfractions .20 .20 .20 .25
 818 @item Name           @tab Argument         @tab Return type      @tab Standard
 819 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}   @tab Fortran 77 and later
 820 @end multitable
 821 @end table
 822
 823
 824
 825 @node ALARM
 826 @section @code{ALARM} --- Execute a routine after a given delay
 827 @fnindex ALARM
 828 @cindex delayed execution
 829
 830 @table @asis
 831 @item @emph{Description}:
 832 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
 833 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
 834 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
 835 supplied, it will be returned with the number of seconds remaining until
 836 any previously scheduled alarm was due to be delivered, or zero if there
 837 was no previously scheduled alarm.
 838
 839 @item @emph{Standard}:
 840 GNU extension
 841
 842 @item @emph{Class}:
 843 Subroutine
 844
 845 @item @emph{Syntax}:
 846 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
 847
 848 @item @emph{Arguments}:
 849 @multitable @columnfractions .15 .70
 850 @item @var{SECONDS} @tab The type of the argument shall be a scalar
 851 @code{INTEGER}. It is @code{INTENT(IN)}.
 852 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
 853 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
 854 values may be either @code{SIG_IGN=1} to ignore the alarm generated
 855 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
 856 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
 857 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
 858 @end multitable
 859
 860 @item @emph{Example}:
 861 @smallexample
 862 program test_alarm
 863   external handler_print
 864   integer i
 865   call alarm (3, handler_print, i)
 866   print *, i
 867   call sleep(10)
 868 end program test_alarm
 869 @end smallexample
 870 This will cause the external routine @var{handler_print} to be called
 871 after 3 seconds.
 872 @end table
 873
 874
 875
 876 @node ALL
 877 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
 878 @fnindex ALL
 879 @cindex array, apply condition
 880 @cindex array, condition testing
 881
 882 @table @asis
 883 @item @emph{Description}:
 884 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
 885 in the array along dimension @var{DIM}.
 886
 887 @item @emph{Standard}:
 888 Fortran 95 and later
 889
 890 @item @emph{Class}:
 891 Transformational function
 892
 893 @item @emph{Syntax}:
 894 @code{RESULT = ALL(MASK [, DIM])}
 895
 896 @item @emph{Arguments}:
 897 @multitable @columnfractions .15 .70
 898 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
 899 it shall not be scalar.
 900 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 901 with a value that lies between one and the rank of @var{MASK}.
 902 @end multitable
 903
 904 @item @emph{Return value}:
 905 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
 906 the kind type parameter is the same as the kind type parameter of
 907 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
 908 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 909 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 910
 911 @table @asis
 912 @item (A)
 913 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
 914 It also is true if @var{MASK} has zero size; otherwise, it is false.
 915 @item (B)
 916 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
 917 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
 918 is determined by applying @code{ALL} to the array sections.
 919 @end table
 920
 921 @item @emph{Example}:
 922 @smallexample
 923 program test_all
 924   logical l
 925   l = all((/.true., .true., .true./))
 926   print *, l
 927   call section
 928   contains
 929     subroutine section
 930       integer a(2,3), b(2,3)
 931       a = 1
 932       b = 1
 933       b(2,2) = 2
 934       print *, all(a .eq. b, 1)
 935       print *, all(a .eq. b, 2)
 936     end subroutine section
 937 end program test_all
 938 @end smallexample
 939 @end table
 940
 941
 942
 943 @node ALLOCATED
 944 @section @code{ALLOCATED} --- Status of an allocatable entity
 945 @fnindex ALLOCATED
 946 @cindex allocation, status
 947
 948 @table @asis
 949 @item @emph{Description}:
 950 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
 951
 952 @item @emph{Standard}:
 953 Fortran 95 and later
 954
 955 @item @emph{Class}:
 956 Inquiry function
 957
 958 @item @emph{Syntax}:
 959 @code{RESULT = ALLOCATED(ARRAY)}
 960
 961 @item @emph{Arguments}:
 962 @multitable @columnfractions .15 .70
 963 @item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
 964 @end multitable
 965
 966 @item @emph{Return value}:
 967 The return value is a scalar @code{LOGICAL} with the default logical
 968 kind type parameter.  If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
 969 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
 970
 971 @item @emph{Example}:
 972 @smallexample
 973 program test_allocated
 974   integer :: i = 4
 975   real(4), allocatable :: x(:)
 976   if (allocated(x) .eqv. .false.) allocate(x(i))
 977 end program test_allocated
 978 @end smallexample
 979 @end table
 980
 981
 982
 983 @node AND
 984 @section @code{AND} --- Bitwise logical AND
 985 @fnindex AND
 986 @cindex bitwise logical and
 987 @cindex logical and, bitwise
 988
 989 @table @asis
 990 @item @emph{Description}:
 991 Bitwise logical @code{AND}.
 992
 993 This intrinsic routine is provided for backwards compatibility with
 994 GNU Fortran 77.  For integer arguments, programmers should consider
 995 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
 996
 997 @item @emph{Standard}:
 998 GNU extension
 999
1000 @item @emph{Class}:
1001 Function
1002
1003 @item @emph{Syntax}:
1004 @code{RESULT = AND(I, J)}
1005
1006 @item @emph{Arguments}:
1007 @multitable @columnfractions .15 .70
1008 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1009 type or a scalar @code{LOGICAL} type.
1010 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1011 @end multitable
1012
1013 @item @emph{Return value}:
1014 The return type is either a scalar @code{INTEGER} or a scalar
1015 @code{LOGICAL}.  If the kind type parameters differ, then the
1016 smaller kind type is implicitly converted to larger kind, and the
1017 return has the larger kind.
1018
1019 @item @emph{Example}:
1020 @smallexample
1021 PROGRAM test_and
1022   LOGICAL :: T = .TRUE., F = .FALSE.
1023   INTEGER :: a, b
1024   DATA a / Z'F' /, b / Z'3' /
1025
1026   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1027   WRITE (*,*) AND(a, b)
1028 END PROGRAM
1029 @end smallexample
1030
1031 @item @emph{See also}:
1032 Fortran 95 elemental function: @ref{IAND}
1033 @end table
1034
1035
1036
1037 @node ANINT
1038 @section @code{ANINT} --- Nearest whole number
1039 @fnindex ANINT
1040 @fnindex DNINT
1041 @cindex ceiling
1042 @cindex rounding, ceiling
1043
1044 @table @asis
1045 @item @emph{Description}:
1046 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1047
1048 @item @emph{Standard}:
1049 Fortran 77 and later
1050
1051 @item @emph{Class}:
1052 Elemental function
1053
1054 @item @emph{Syntax}:
1055 @code{RESULT = ANINT(A [, KIND])}
1056
1057 @item @emph{Arguments}:
1058 @multitable @columnfractions .15 .70
1059 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
1060 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1061                       expression indicating the kind parameter of
1062                       the result.
1063 @end multitable
1064
1065 @item @emph{Return value}:
1066 The return value is of type real with the kind type parameter of the
1067 argument if the optional @var{KIND} is absent; otherwise, the kind
1068 type parameter will be given by @var{KIND}.  If @var{A} is greater than
1069 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1070 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1071
1072 @item @emph{Example}:
1073 @smallexample
1074 program test_anint
1075   real(4) x4
1076   real(8) x8
1077   x4 = 1.234E0_4
1078   x8 = 4.321_8
1079   print *, anint(x4), dnint(x8)
1080   x8 = anint(x4,8)
1081 end program test_anint
1082 @end smallexample
1083
1084 @item @emph{Specific names}:
1085 @multitable @columnfractions .20 .20 .20 .25
1086 @item Name            @tab Argument         @tab Return type      @tab Standard
1087 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1088 @end multitable
1089 @end table
1090
1091
1092
1093 @node ANY
1094 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1095 @fnindex ANY
1096 @cindex array, apply condition
1097 @cindex array, condition testing
1098
1099 @table @asis
1100 @item @emph{Description}:
1101 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1102 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1103
1104 @item @emph{Standard}:
1105 Fortran 95 and later
1106
1107 @item @emph{Class}:
1108 Transformational function
1109
1110 @item @emph{Syntax}:
1111 @code{RESULT = ANY(MASK [, DIM])}
1112
1113 @item @emph{Arguments}:
1114 @multitable @columnfractions .15 .70
1115 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1116 it shall not be scalar.
1117 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1118 with a value that lies between one and the rank of @var{MASK}.
1119 @end multitable
1120
1121 @item @emph{Return value}:
1122 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1123 the kind type parameter is the same as the kind type parameter of
1124 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1125 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1126 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1127
1128 @table @asis
1129 @item (A)
1130 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1131 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1132 @item (B)
1133 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1134 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1135 is determined by applying @code{ANY} to the array sections.
1136 @end table
1137
1138 @item @emph{Example}:
1139 @smallexample
1140 program test_any
1141   logical l
1142   l = any((/.true., .true., .true./))
1143   print *, l
1144   call section
1145   contains
1146     subroutine section
1147       integer a(2,3), b(2,3)
1148       a = 1
1149       b = 1
1150       b(2,2) = 2
1151       print *, any(a .eq. b, 1)
1152       print *, any(a .eq. b, 2)
1153     end subroutine section
1154 end program test_any
1155 @end smallexample
1156 @end table
1157
1158
1159
1160 @node ASIN
1161 @section @code{ASIN} --- Arcsine function
1162 @fnindex ASIN
1163 @fnindex DASIN
1164 @cindex trigonometric function, sine, inverse
1165 @cindex sine, inverse
1166
1167 @table @asis
1168 @item @emph{Description}:
1169 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1170
1171 @item @emph{Standard}:
1172 Fortran 77 and later
1173
1174 @item @emph{Class}:
1175 Elemental function
1176
1177 @item @emph{Syntax}:
1178 @code{RESULT = ASIN(X)}
1179
1180 @item @emph{Arguments}:
1181 @multitable @columnfractions .15 .70
1182 @item @var{X} @tab The type shall be @code{REAL}, and a magnitude that is
1183 less than one.
1184 @end multitable
1185
1186 @item @emph{Return value}:
1187 The return value is of type @code{REAL} and it lies in the
1188 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}.  The kind type
1189 parameter is the same as @var{X}.
1190
1191 @item @emph{Example}:
1192 @smallexample
1193 program test_asin
1194   real(8) :: x = 0.866_8
1195   x = asin(x)
1196 end program test_asin
1197 @end smallexample
1198
1199 @item @emph{Specific names}:
1200 @multitable @columnfractions .20 .20 .20 .25
1201 @item Name            @tab Argument          @tab Return type       @tab Standard
1202 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1203 @end multitable
1204
1205 @item @emph{See also}:
1206 Inverse function: @ref{SIN}
1207
1208 @end table
1209
1210
1211
1212 @node ASINH
1213 @section @code{ASINH} --- Hyperbolic arcsine function
1214 @fnindex ASINH
1215 @fnindex DASINH
1216 @cindex area hyperbolic sine
1217 @cindex hyperbolic arcsine
1218 @cindex hyperbolic function, sine, inverse
1219 @cindex sine, hyperbolic, inverse
1220
1221 @table @asis
1222 @item @emph{Description}:
1223 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1224
1225 @item @emph{Standard}:
1226 Fortran 2008 and later
1227
1228 @item @emph{Class}:
1229 Elemental function
1230
1231 @item @emph{Syntax}:
1232 @code{RESULT = ASINH(X)}
1233
1234 @item @emph{Arguments}:
1235 @multitable @columnfractions .15 .70
1236 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1237 @end multitable
1238
1239 @item @emph{Return value}:
1240 The return value is of the same type and kind as  @var{X}.
1241
1242 @item @emph{Example}:
1243 @smallexample
1244 PROGRAM test_asinh
1245   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1246   WRITE (*,*) ASINH(x)
1247 END PROGRAM
1248 @end smallexample
1249
1250 @item @emph{Specific names}:
1251 @multitable @columnfractions .20 .20 .20 .25
1252 @item Name             @tab Argument          @tab Return type       @tab Standard
1253 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1254 @end multitable
1255
1256 @item @emph{See also}:
1257 Inverse function: @ref{SINH}
1258 @end table
1259
1260
1261
1262 @node ASSOCIATED
1263 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1264 @fnindex ASSOCIATED
1265 @cindex pointer, status
1266 @cindex association status
1267
1268 @table @asis
1269 @item @emph{Description}:
1270 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1271 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1272
1273 @item @emph{Standard}:
1274 Fortran 95 and later
1275
1276 @item @emph{Class}:
1277 Inquiry function
1278
1279 @item @emph{Syntax}:
1280 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1281
1282 @item @emph{Arguments}:
1283 @multitable @columnfractions .15 .70
1284 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1285 and it can be of any type.
1286 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1287 a target.  It must have the same type, kind type parameter, and
1288 array rank as @var{POINTER}.
1289 @end multitable
1290 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1291 undefined.
1292
1293 @item @emph{Return value}:
1294 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1295 There are several cases:
1296 @table @asis
1297 @item (A) When the optional @var{TARGET} is not present then
1298 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1299 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1300 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units.  If @var{POINTER} is
1301 disassociated, the result is false.
1302 @item (C) If @var{TARGET} is present and an array target, the result is true if
1303 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1304 are arrays whose elements are not zero-sized storage sequences, and
1305 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1306 order.
1307 As in case(B), the result is false, if @var{POINTER} is disassociated.
1308 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1309 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1310 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1311 units.
1312 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1313 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1314 target associated with @var{POINTER} and the target associated with @var{TARGET}
1315 have the same shape, are not zero-sized arrays, are arrays whose elements are
1316 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1317 the same storage units in array element order.
1318 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1319 @end table
1320
1321 @item @emph{Example}:
1322 @smallexample
1323 program test_associated
1324    implicit none
1325    real, target  :: tgt(2) = (/1., 2./)
1326    real, pointer :: ptr(:)
1327    ptr => tgt
1328    if (associated(ptr)     .eqv. .false.) call abort
1329    if (associated(ptr,tgt) .eqv. .false.) call abort
1330 end program test_associated
1331 @end smallexample
1332
1333 @item @emph{See also}:
1334 @ref{NULL}
1335 @end table
1336
1337
1338
1339 @node ATAN
1340 @section @code{ATAN} --- Arctangent function
1341 @fnindex ATAN
1342 @fnindex DATAN
1343 @cindex trigonometric function, tangent, inverse
1344 @cindex tangent, inverse
1345
1346 @table @asis
1347 @item @emph{Description}:
1348 @code{ATAN(X)} computes the arctangent of @var{X}.
1349
1350 @item @emph{Standard}:
1351 Fortran 77 and later
1352
1353 @item @emph{Class}:
1354 Elemental function
1355
1356 @item @emph{Syntax}:
1357 @code{RESULT = ATAN(X)}
1358
1359 @item @emph{Arguments}:
1360 @multitable @columnfractions .15 .70
1361 @item @var{X} @tab The type shall be @code{REAL}.
1362 @end multitable
1363
1364 @item @emph{Return value}:
1365 The return value is of type @code{REAL} and it lies in the
1366 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1367
1368 @item @emph{Example}:
1369 @smallexample
1370 program test_atan
1371   real(8) :: x = 2.866_8
1372   x = atan(x)
1373 end program test_atan
1374 @end smallexample
1375
1376 @item @emph{Specific names}:
1377 @multitable @columnfractions .20 .20 .20 .25
1378 @item Name            @tab Argument          @tab Return type       @tab Standard
1379 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1380 @end multitable
1381
1382 @item @emph{See also}:
1383 Inverse function: @ref{TAN}
1384
1385 @end table
1386
1387
1388
1389 @node ATAN2
1390 @section @code{ATAN2} --- Arctangent function
1391 @fnindex ATAN2
1392 @fnindex DATAN2
1393 @cindex trigonometric function, tangent, inverse
1394 @cindex tangent, inverse
1395
1396 @table @asis
1397 @item @emph{Description}:
1398 @code{ATAN2(Y, X)} computes the arctangent of the complex number
1399 @math{X + i Y}.
1400
1401 @item @emph{Standard}:
1402 Fortran 77 and later
1403
1404 @item @emph{Class}:
1405 Elemental function
1406
1407 @item @emph{Syntax}:
1408 @code{RESULT = ATAN2(Y, X)}
1409
1410 @item @emph{Arguments}:
1411 @multitable @columnfractions .15 .70
1412 @item @var{Y} @tab The type shall be @code{REAL}.
1413 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1414 If @var{Y} is zero, then @var{X} must be nonzero.
1415 @end multitable
1416
1417 @item @emph{Return value}:
1418 The return value has the same type and kind type parameter as @var{Y}.
1419 It is the principal value of the complex number @math{X + i Y}.  If
1420 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1421 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1422 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1423 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1424 is @math{\pi/2}.
1425
1426 @item @emph{Example}:
1427 @smallexample
1428 program test_atan2
1429   real(4) :: x = 1.e0_4, y = 0.5e0_4
1430   x = atan2(y,x)
1431 end program test_atan2
1432 @end smallexample
1433
1434 @item @emph{Specific names}:
1435 @multitable @columnfractions .20 .20 .20 .25
1436 @item Name            @tab Argument          @tab Return type    @tab Standard
1437 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1438 @end multitable
1439 @end table
1440
1441
1442
1443 @node ATANH
1444 @section @code{ATANH} --- Hyperbolic arctangent function
1445 @fnindex ASINH
1446 @fnindex DASINH
1447 @cindex area hyperbolic tangent
1448 @cindex hyperbolic arctangent
1449 @cindex hyperbolic function, tangent, inverse
1450 @cindex tangent, hyperbolic, inverse
1451
1452 @table @asis
1453 @item @emph{Description}:
1454 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1455 of @code{TANH(X)}).
1456
1457 @item @emph{Standard}:
1458 Fortran 2008 and later
1459
1460 @item @emph{Class}:
1461 Elemental function
1462
1463 @item @emph{Syntax}:
1464 @code{RESULT = ATANH(X)}
1465
1466 @item @emph{Arguments}:
1467 @multitable @columnfractions .15 .70
1468 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1469 @end multitable
1470
1471 @item @emph{Return value}:
1472 The return value has same type and kind as @var{X}.
1473
1474 @item @emph{Example}:
1475 @smallexample
1476 PROGRAM test_atanh
1477   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1478   WRITE (*,*) ATANH(x)
1479 END PROGRAM
1480 @end smallexample
1481
1482 @item @emph{Specific names}:
1483 @multitable @columnfractions .20 .20 .20 .25
1484 @item Name             @tab Argument          @tab Return type       @tab Standard
1485 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1486 @end multitable
1487
1488 @item @emph{See also}:
1489 Inverse function: @ref{TANH}
1490 @end table
1491
1492
1493
1494 @node BESSEL_J0
1495 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1496 @fnindex BESSEL_J0
1497 @fnindex BESJ0
1498 @fnindex DBESJ0
1499 @cindex Bessel function, first kind
1500
1501 @table @asis
1502 @item @emph{Description}:
1503 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1504 order 0 of @var{X}. This function is available under the name
1505 @code{BESJ0} as a GNU extension.
1506
1507 @item @emph{Standard}:
1508 Fortran 2008 and later
1509
1510 @item @emph{Class}:
1511 Elemental function
1512
1513 @item @emph{Syntax}:
1514 @code{RESULT = BESSEL_J0(X)}
1515
1516 @item @emph{Arguments}:
1517 @multitable @columnfractions .15 .70
1518 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1519 @end multitable
1520
1521 @item @emph{Return value}:
1522 The return value is of type @code{REAL} and lies in the
1523 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1524 kind as @var{X}.
1525
1526 @item @emph{Example}:
1527 @smallexample
1528 program test_besj0
1529   real(8) :: x = 0.0_8
1530   x = bessel_j0(x)
1531 end program test_besj0
1532 @end smallexample
1533
1534 @item @emph{Specific names}:
1535 @multitable @columnfractions .20 .20 .20 .25
1536 @item Name            @tab Argument          @tab Return type       @tab Standard
1537 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1538 @end multitable
1539 @end table
1540
1541
1542
1543 @node BESSEL_J1
1544 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1545 @fnindex BESSEL_J1
1546 @fnindex BESJ1
1547 @fnindex DBESJ1
1548 @cindex Bessel function, first kind
1549
1550 @table @asis
1551 @item @emph{Description}:
1552 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1553 order 1 of @var{X}. This function is available under the name
1554 @code{BESJ1} as a GNU extension.
1555
1556 @item @emph{Standard}:
1557 Fortran 2008
1558
1559 @item @emph{Class}:
1560 Elemental function
1561
1562 @item @emph{Syntax}:
1563 @code{RESULT = BESSEL_J1(X)}
1564
1565 @item @emph{Arguments}:
1566 @multitable @columnfractions .15 .70
1567 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1568 @end multitable
1569
1570 @item @emph{Return value}:
1571 The return value is of type @code{REAL} and it lies in the
1572 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1573 kind as @var{X}.
1574
1575 @item @emph{Example}:
1576 @smallexample
1577 program test_besj1
1578   real(8) :: x = 1.0_8
1579   x = bessel_j1(x)
1580 end program test_besj1
1581 @end smallexample
1582
1583 @item @emph{Specific names}:
1584 @multitable @columnfractions .20 .20 .20 .25
1585 @item Name            @tab Argument          @tab Return type       @tab Standard
1586 @item @code{DBESJ1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1587 @end multitable
1588 @end table
1589
1590
1591
1592 @node BESSEL_JN
1593 @section @code{BESSEL_JN} --- Bessel function of the first kind
1594 @fnindex BESSEL_JN
1595 @fnindex BESJN
1596 @fnindex DBESJN
1597 @cindex Bessel function, first kind
1598
1599 @table @asis
1600 @item @emph{Description}:
1601 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1602 order @var{N} of @var{X}. This function is available under the name
1603 @code{BESJN} as a GNU extension.
1604
1605 If both arguments are arrays, their ranks and shapes shall conform.
1606
1607 @item @emph{Standard}:
1608 Fortran 2008 and later
1609
1610 @item @emph{Class}:
1611 Elemental function
1612
1613 @item @emph{Syntax}:
1614 @code{RESULT = BESSEL_JN(N, X)}
1615
1616 @item @emph{Arguments}:
1617 @multitable @columnfractions .15 .70
1618 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1619 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1620 @end multitable
1621
1622 @item @emph{Return value}:
1623 The return value is a scalar of type @code{REAL}. It has the same
1624 kind as @var{X}.
1625
1626 @item @emph{Example}:
1627 @smallexample
1628 program test_besjn
1629   real(8) :: x = 1.0_8
1630   x = bessel_jn(5,x)
1631 end program test_besjn
1632 @end smallexample
1633
1634 @item @emph{Specific names}:
1635 @multitable @columnfractions .20 .20 .20 .25
1636 @item Name             @tab Argument            @tab Return type       @tab Standard
1637 @item @code{DBESJN(X)} @tab @code{INTEGER N} @tab @code{REAL(8)}    @tab GNU extension
1638 @item                  @tab @code{REAL(8) X}    @tab                   @tab
1639 @end multitable
1640 @end table
1641
1642
1643
1644 @node BESSEL_Y0
1645 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1646 @fnindex BESSEL_Y0
1647 @fnindex BESY0
1648 @fnindex DBESY0
1649 @cindex Bessel function, second kind
1650
1651 @table @asis
1652 @item @emph{Description}:
1653 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1654 order 0 of @var{X}. This function is available under the name
1655 @code{BESY0} as a GNU extension.
1656
1657 @item @emph{Standard}:
1658 Fortran 2008 and later
1659
1660 @item @emph{Class}:
1661 Elemental function
1662
1663 @item @emph{Syntax}:
1664 @code{RESULT = BESSEL_Y0(X)}
1665
1666 @item @emph{Arguments}:
1667 @multitable @columnfractions .15 .70
1668 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1669 @end multitable
1670
1671 @item @emph{Return value}:
1672 The return value is a scalar of type @code{REAL}. It has the same
1673 kind as @var{X}.
1674
1675 @item @emph{Example}:
1676 @smallexample
1677 program test_besy0
1678   real(8) :: x = 0.0_8
1679   x = bessel_y0(x)
1680 end program test_besy0
1681 @end smallexample
1682
1683 @item @emph{Specific names}:
1684 @multitable @columnfractions .20 .20 .20 .25
1685 @item Name            @tab Argument          @tab Return type       @tab Standard
1686 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1687 @end multitable
1688 @end table
1689
1690
1691
1692 @node BESSEL_Y1
1693 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1694 @fnindex BESSEL_Y1
1695 @fnindex BESY1
1696 @fnindex DBESY1
1697 @cindex Bessel function, second kind
1698
1699 @table @asis
1700 @item @emph{Description}:
1701 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1702 order 1 of @var{X}. This function is available under the name
1703 @code{BESY1} as a GNU extension.
1704
1705 @item @emph{Standard}:
1706 Fortran 2008 and later
1707
1708 @item @emph{Class}:
1709 Elemental function
1710
1711 @item @emph{Syntax}:
1712 @code{RESULT = BESSEL_Y1(X)}
1713
1714 @item @emph{Arguments}:
1715 @multitable @columnfractions .15 .70
1716 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1717 @end multitable
1718
1719 @item @emph{Return value}:
1720 The return value is a scalar of type @code{REAL}. It has the same
1721 kind as @var{X}.
1722
1723 @item @emph{Example}:
1724 @smallexample
1725 program test_besy1
1726   real(8) :: x = 1.0_8
1727   x = bessel_y1(x)
1728 end program test_besy1
1729 @end smallexample
1730
1731 @item @emph{Specific names}:
1732 @multitable @columnfractions .20 .20 .20 .25
1733 @item Name            @tab Argument          @tab Return type       @tab Standard
1734 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1735 @end multitable
1736 @end table
1737
1738
1739
1740 @node BESSEL_YN
1741 @section @code{BESSEL_YN} --- Bessel function of the second kind
1742 @fnindex BESSEL_YN
1743 @fnindex BESYN
1744 @fnindex DBESYN
1745 @cindex Bessel function, second kind
1746
1747 @table @asis
1748 @item @emph{Description}:
1749 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1750 order @var{N} of @var{X}. This function is available under the name
1751 @code{BESYN} as a GNU extension.
1752
1753 If both arguments are arrays, their ranks and shapes shall conform.
1754
1755 @item @emph{Standard}:
1756 Fortran 2008 and later
1757
1758 @item @emph{Class}:
1759 Elemental function
1760
1761 @item @emph{Syntax}:
1762 @code{RESULT = BESSEL_YN(N, X)}
1763
1764 @item @emph{Arguments}:
1765 @multitable @columnfractions .15 .70
1766 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1767 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL}.
1768 @end multitable
1769
1770 @item @emph{Return value}:
1771 The return value is a scalar of type @code{REAL}. It has the same
1772 kind as @var{X}.
1773
1774 @item @emph{Example}:
1775 @smallexample
1776 program test_besyn
1777   real(8) :: x = 1.0_8
1778   x = bessel_yn(5,x)
1779 end program test_besyn
1780 @end smallexample
1781
1782 @item @emph{Specific names}:
1783 @multitable @columnfractions .20 .20 .20 .25
1784 @item Name               @tab Argument            @tab Return type     @tab Standard
1785 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1786 @item                    @tab @code{REAL(8)    X} @tab                 @tab
1787 @end multitable
1788 @end table
1789
1790
1791
1792 @node BIT_SIZE
1793 @section @code{BIT_SIZE} --- Bit size inquiry function
1794 @fnindex BIT_SIZE
1795 @cindex bits, number of
1796 @cindex size of a variable, in bits
1797
1798 @table @asis
1799 @item @emph{Description}:
1800 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1801 represented by the type of @var{I}.
1802
1803 @item @emph{Standard}:
1804 Fortran 95 and later
1805
1806 @item @emph{Class}:
1807 Inquiry function
1808
1809 @item @emph{Syntax}:
1810 @code{RESULT = BIT_SIZE(I)}
1811
1812 @item @emph{Arguments}:
1813 @multitable @columnfractions .15 .70
1814 @item @var{I} @tab The type shall be @code{INTEGER}.
1815 @end multitable
1816
1817 @item @emph{Return value}:
1818 The return value is of type @code{INTEGER}
1819
1820 @item @emph{Example}:
1821 @smallexample
1822 program test_bit_size
1823     integer :: i = 123
1824     integer :: size
1825     size = bit_size(i)
1826     print *, size
1827 end program test_bit_size
1828 @end smallexample
1829 @end table
1830
1831
1832
1833 @node BTEST
1834 @section @code{BTEST} --- Bit test function
1835 @fnindex BTEST
1836 @cindex bits, testing
1837
1838 @table @asis
1839 @item @emph{Description}:
1840 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1841 in @var{I} is set.
1842
1843 @item @emph{Standard}:
1844 Fortran 95 and later
1845
1846 @item @emph{Class}:
1847 Elemental function
1848
1849 @item @emph{Syntax}:
1850 @code{RESULT = BTEST(I, POS)}
1851
1852 @item @emph{Arguments}:
1853 @multitable @columnfractions .15 .70
1854 @item @var{I} @tab The type shall be @code{INTEGER}.
1855 @item @var{POS} @tab The type shall be @code{INTEGER}.
1856 @end multitable
1857
1858 @item @emph{Return value}:
1859 The return value is of type @code{LOGICAL}
1860
1861 @item @emph{Example}:
1862 @smallexample
1863 program test_btest
1864     integer :: i = 32768 + 1024 + 64
1865     integer :: pos
1866     logical :: bool
1867     do pos=0,16
1868         bool = btest(i, pos)
1869         print *, pos, bool
1870     end do
1871 end program test_btest
1872 @end smallexample
1873 @end table
1874
1875
1876 @node C_ASSOCIATED
1877 @section @code{C_ASSOCIATED} --- Status of a C pointer
1878 @fnindex C_ASSOCIATED
1879 @cindex association status, C pointer
1880 @cindex pointer, C association status
1881
1882 @table @asis
1883 @item @emph{Description}:
1884 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1885 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1886
1887 @item @emph{Standard}:
1888 Fortran 2003 and later
1889
1890 @item @emph{Class}:
1891 Inquiry function
1892
1893 @item @emph{Syntax}:
1894 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1895
1896 @item @emph{Arguments}:
1897 @multitable @columnfractions .15 .70
1898 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1899 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1900 @end multitable
1901
1902 @item @emph{Return value}:
1903 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1904 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1905 point to different addresses.
1906
1907 @item @emph{Example}:
1908 @smallexample
1909 subroutine association_test(a,b)
1910   use iso_c_binding, only: c_associated, c_loc, c_ptr
1911   implicit none
1912   real, pointer :: a
1913   type(c_ptr) :: b
1914   if(c_associated(b, c_loc(a))) &
1915      stop 'b and a do not point to same target'
1916 end subroutine association_test
1917 @end smallexample
1918
1919 @item @emph{See also}:
1920 @ref{C_LOC}, @ref{C_FUNLOC}
1921 @end table
1922
1923
1924 @node C_FUNLOC
1925 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1926 @fnindex C_FUNLOC
1927 @cindex pointer, C address of procedures
1928
1929 @table @asis
1930 @item @emph{Description}:
1931 @code{C_FUNLOC(x)} determines the C address of the argument.
1932
1933 @item @emph{Standard}:
1934 Fortran 2003 and later
1935
1936 @item @emph{Class}:
1937 Inquiry function
1938
1939 @item @emph{Syntax}:
1940 @code{RESULT = C_FUNLOC(x)}
1941
1942 @item @emph{Arguments}:
1943 @multitable @columnfractions .15 .70
1944 @item @var{x} @tab Interoperable function or pointer to such function.
1945 @end multitable
1946
1947 @item @emph{Return value}:
1948 The return value is of type @code{C_FUNPTR} and contains the C address
1949 of the argument.
1950
1951 @item @emph{Example}:
1952 @smallexample
1953 module x
1954   use iso_c_binding
1955   implicit none
1956 contains
1957   subroutine sub(a) bind(c)
1958     real(c_float) :: a
1959     a = sqrt(a)+5.0
1960   end subroutine sub
1961 end module x
1962 program main
1963   use iso_c_binding
1964   use x
1965   implicit none
1966   interface
1967     subroutine my_routine(p) bind(c,name='myC_func')
1968       import :: c_funptr
1969       type(c_funptr), intent(in) :: p
1970     end subroutine
1971   end interface
1972   call my_routine(c_funloc(sub))
1973 end program main
1974 @end smallexample
1975
1976 @item @emph{See also}:
1977 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1978 @end table
1979
1980
1981 @node C_F_PROCPOINTER
1982 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1983 @fnindex C_F_PROCPOINTER
1984 @cindex pointer, C address of pointers
1985
1986 @table @asis
1987 @item @emph{Description}:
1988 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
1989 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
1990
1991 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1992 this function is not fully operable.
1993
1994 @item @emph{Standard}:
1995 Fortran 2003 and later
1996
1997 @item @emph{Class}:
1998 Subroutine
1999
2000 @item @emph{Syntax}:
2001 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2002
2003 @item @emph{Arguments}:
2004 @multitable @columnfractions .15 .70
2005 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2006                        @code{INTENT(IN)}.
2007 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2008                        @code{INTENT(OUT)}.
2009 @end multitable
2010
2011 @item @emph{Example}:
2012 @smallexample
2013 program main
2014   use iso_c_binding
2015   implicit none
2016   abstract interface
2017     function func(a)
2018       import :: c_float
2019       real(c_float), intent(in) :: a
2020       real(c_float) :: func
2021     end function
2022   end interface
2023   interface
2024      function getIterFunc() bind(c,name="getIterFunc")
2025        import :: c_funptr
2026        type(c_funptr) :: getIterFunc
2027      end function
2028   end interface
2029   type(c_funptr) :: cfunptr
2030   procedure(func), pointer :: myFunc
2031   cfunptr = getIterFunc()
2032   call c_f_procpointer(cfunptr, myFunc)
2033 end program main
2034 @end smallexample
2035
2036 @item @emph{See also}:
2037 @ref{C_LOC}, @ref{C_F_POINTER}
2038 @end table
2039
2040
2041 @node C_F_POINTER
2042 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2043 @fnindex C_F_POINTER
2044 @cindex pointer, convert C to Fortran
2045
2046 @table @asis
2047 @item @emph{Description}:
2048 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2049 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2050 shape.
2051
2052 @item @emph{Standard}:
2053 Fortran 2003 and later
2054
2055 @item @emph{Class}:
2056 Subroutine
2057
2058 @item @emph{Syntax}:
2059 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2060
2061 @item @emph{Arguments}:
2062 @multitable @columnfractions .15 .70
2063 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2064                        @code{INTENT(IN)}.
2065 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2066                        @code{INTENT(OUT)}.
2067 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2068                        with @code{INTENT(IN)}. It shall be present
2069                        if and only if @var{fptr} is an array. The size
2070                        must be equal to the rank of @var{fptr}.
2071 @end multitable
2072
2073 @item @emph{Example}:
2074 @smallexample
2075 program main
2076   use iso_c_binding
2077   implicit none
2078   interface
2079     subroutine my_routine(p) bind(c,name='myC_func')
2080       import :: c_ptr
2081       type(c_ptr), intent(out) :: p
2082     end subroutine
2083   end interface
2084   type(c_ptr) :: cptr
2085   real,pointer :: a(:)
2086   call my_routine(cptr)
2087   call c_f_pointer(cptr, a, [12])
2088 end program main
2089 @end smallexample
2090
2091 @item @emph{See also}:
2092 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2093 @end table
2094
2095
2096 @node C_LOC
2097 @section @code{C_LOC} --- Obtain the C address of an object
2098 @fnindex C_LOC
2099 @cindex procedure pointer, convert C to Fortran
2100
2101 @table @asis
2102 @item @emph{Description}:
2103 @code{C_LOC(X)} determines the C address of the argument.
2104
2105 @item @emph{Standard}:
2106 Fortran 2003 and later
2107
2108 @item @emph{Class}:
2109 Inquiry function
2110
2111 @item @emph{Syntax}:
2112 @code{RESULT = C_LOC(X)}
2113
2114 @item @emph{Arguments}:
2115 @multitable @columnfractions .15 .70
2116 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2117                    or allocated allocatable variable with @code{TARGET}
2118                    attribute.
2119 @end multitable
2120
2121 @item @emph{Return value}:
2122 The return value is of type @code{C_PTR} and contains the C address
2123 of the argument.
2124
2125 @item @emph{Example}:
2126 @smallexample
2127 subroutine association_test(a,b)
2128   use iso_c_binding, only: c_associated, c_loc, c_ptr
2129   implicit none
2130   real, pointer :: a
2131   type(c_ptr) :: b
2132   if(c_associated(b, c_loc(a))) &
2133      stop 'b and a do not point to same target'
2134 end subroutine association_test
2135 @end smallexample
2136
2137 @item @emph{See also}:
2138 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2139 @end table
2140
2141
2142 @node CEILING
2143 @section @code{CEILING} --- Integer ceiling function
2144 @fnindex CEILING
2145 @cindex ceiling
2146 @cindex rounding, ceiling
2147
2148 @table @asis
2149 @item @emph{Description}:
2150 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2151
2152 @item @emph{Standard}:
2153 Fortran 95 and later
2154
2155 @item @emph{Class}:
2156 Elemental function
2157
2158 @item @emph{Syntax}:
2159 @code{RESULT = CEILING(A [, KIND])}
2160
2161 @item @emph{Arguments}:
2162 @multitable @columnfractions .15 .70
2163 @item @var{A} @tab The type shall be @code{REAL}.
2164 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2165                       expression indicating the kind parameter of
2166                       the result.
2167 @end multitable
2168
2169 @item @emph{Return value}:
2170 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2171 and a default-kind @code{INTEGER} otherwise.
2172
2173 @item @emph{Example}:
2174 @smallexample
2175 program test_ceiling
2176     real :: x = 63.29
2177     real :: y = -63.59
2178     print *, ceiling(x) ! returns 64
2179     print *, ceiling(y) ! returns -63
2180 end program test_ceiling
2181 @end smallexample
2182
2183 @item @emph{See also}:
2184 @ref{FLOOR}, @ref{NINT}
2185
2186 @end table
2187
2188
2189
2190 @node CHAR
2191 @section @code{CHAR} --- Character conversion function
2192 @fnindex CHAR
2193 @cindex conversion, to character
2194
2195 @table @asis
2196 @item @emph{Description}:
2197 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2198
2199 @item @emph{Standard}:
2200 Fortran 77 and later
2201
2202 @item @emph{Class}:
2203 Elemental function
2204
2205 @item @emph{Syntax}:
2206 @code{RESULT = CHAR(I [, KIND])}
2207
2208 @item @emph{Arguments}:
2209 @multitable @columnfractions .15 .70
2210 @item @var{I} @tab The type shall be @code{INTEGER}.
2211 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2212                       expression indicating the kind parameter of
2213                       the result.
2214 @end multitable
2215
2216 @item @emph{Return value}:
2217 The return value is of type @code{CHARACTER(1)}
2218
2219 @item @emph{Example}:
2220 @smallexample
2221 program test_char
2222     integer :: i = 74
2223     character(1) :: c
2224     c = char(i)
2225     print *, i, c ! returns 'J'
2226 end program test_char
2227 @end smallexample
2228
2229 @item @emph{Note}:
2230 See @ref{ICHAR} for a discussion of converting between numerical values
2231 and formatted string representations.
2232
2233 @item @emph{See also}:
2234 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2235
2236 @end table
2237
2238
2239
2240 @node CHDIR
2241 @section @code{CHDIR} --- Change working directory
2242 @fnindex CHDIR
2243 @cindex system, working directory
2244
2245 @table @asis
2246 @item @emph{Description}:
2247 Change current working directory to a specified path.
2248
2249 This intrinsic is provided in both subroutine and function forms; however,
2250 only one form can be used in any given program unit.
2251
2252 @item @emph{Standard}:
2253 GNU extension
2254
2255 @item @emph{Class}:
2256 Subroutine, function
2257
2258 @item @emph{Syntax}:
2259 @multitable @columnfractions .80
2260 @item @code{CALL CHDIR(NAME [, STATUS])}
2261 @item @code{STATUS = CHDIR(NAME)}
2262 @end multitable
2263
2264 @item @emph{Arguments}:
2265 @multitable @columnfractions .15 .70
2266 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2267                         kind and shall specify a valid path within the
2268                         file system.
2269 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2270                         kind.  Returns 0 on success, and a system specific
2271                         and nonzero error code otherwise.
2272 @end multitable
2273
2274 @item @emph{Example}:
2275 @smallexample
2276 PROGRAM test_chdir
2277   CHARACTER(len=255) :: path
2278   CALL getcwd(path)
2279   WRITE(*,*) TRIM(path)
2280   CALL chdir("/tmp")
2281   CALL getcwd(path)
2282   WRITE(*,*) TRIM(path)
2283 END PROGRAM
2284 @end smallexample
2285
2286 @item @emph{See also}:
2287 @ref{GETCWD}
2288 @end table
2289
2290
2291
2292 @node CHMOD
2293 @section @code{CHMOD} --- Change access permissions of files
2294 @fnindex CHMOD
2295 @cindex file system, change access mode
2296
2297 @table @asis
2298 @item @emph{Description}:
2299 @code{CHMOD} changes the permissions of a file. This function invokes
2300 @code{/bin/chmod} and might therefore not work on all platforms.
2301
2302 This intrinsic is provided in both subroutine and function forms; however,
2303 only one form can be used in any given program unit.
2304
2305 @item @emph{Standard}:
2306 GNU extension
2307
2308 @item @emph{Class}:
2309 Subroutine, function
2310
2311 @item @emph{Syntax}:
2312 @multitable @columnfractions .80
2313 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2314 @item @code{STATUS = CHMOD(NAME, MODE)}
2315 @end multitable
2316
2317 @item @emph{Arguments}:
2318 @multitable @columnfractions .15 .70
2319
2320 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2321 file name. Trailing blanks are ignored unless the character
2322 @code{achar(0)} is present, then all characters up to and excluding
2323 @code{achar(0)} are used as the file name.
2324
2325 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2326 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2327 argument of @code{/bin/chmod}.
2328
2329 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2330 @code{0} on success and nonzero otherwise.
2331 @end multitable
2332
2333 @item @emph{Return value}:
2334 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2335 otherwise.
2336
2337 @item @emph{Example}:
2338 @code{CHMOD} as subroutine
2339 @smallexample
2340 program chmod_test
2341   implicit none
2342   integer :: status
2343   call chmod('test.dat','u+x',status)
2344   print *, 'Status: ', status
2345 end program chmod_test
2346 @end smallexample
2347 @code{CHMOD} as function:
2348 @smallexample
2349 program chmod_test
2350   implicit none
2351   integer :: status
2352   status = chmod('test.dat','u+x')
2353   print *, 'Status: ', status
2354 end program chmod_test
2355 @end smallexample
2356
2357 @end table
2358
2359
2360
2361 @node CMPLX
2362 @section @code{CMPLX} --- Complex conversion function
2363 @fnindex CMPLX
2364 @cindex complex numbers, conversion to
2365 @cindex conversion, to complex
2366
2367 @table @asis
2368 @item @emph{Description}:
2369 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2370 the real component.  If @var{Y} is present it is converted to the imaginary
2371 component.  If @var{Y} is not present then the imaginary component is set to
2372 0.0.  If @var{X} is complex then @var{Y} must not be present.
2373
2374 @item @emph{Standard}:
2375 Fortran 77 and later
2376
2377 @item @emph{Class}:
2378 Elemental function
2379
2380 @item @emph{Syntax}:
2381 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2382
2383 @item @emph{Arguments}:
2384 @multitable @columnfractions .15 .70
2385 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2386                    or @code{COMPLEX}.
2387 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2388                    @code{COMPLEX}.)  May be @code{INTEGER}
2389                    or @code{REAL}.
2390 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2391                       expression indicating the kind parameter of
2392                       the result.
2393 @end multitable
2394
2395 @item @emph{Return value}:
2396 The return value is of @code{COMPLEX} type, with a kind equal to
2397 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2398 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2399 @var{X} and @var{Y}.
2400
2401 @item @emph{Example}:
2402 @smallexample
2403 program test_cmplx
2404     integer :: i = 42
2405     real :: x = 3.14
2406     complex :: z
2407     z = cmplx(i, x)
2408     print *, z, cmplx(x)
2409 end program test_cmplx
2410 @end smallexample
2411
2412 @item @emph{See also}:
2413 @ref{COMPLEX}
2414 @end table
2415
2416
2417
2418 @node COMMAND_ARGUMENT_COUNT
2419 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2420 @fnindex COMMAND_ARGUMENT_COUNT
2421 @cindex command-line arguments
2422 @cindex command-line arguments, number of
2423 @cindex arguments, to program
2424
2425 @table @asis
2426 @item @emph{Description}:
2427 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2428 command line when the containing program was invoked.
2429
2430 @item @emph{Standard}:
2431 Fortran 2003 and later
2432
2433 @item @emph{Class}:
2434 Inquiry function
2435
2436 @item @emph{Syntax}:
2437 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2438
2439 @item @emph{Arguments}:
2440 @multitable @columnfractions .15 .70
2441 @item None
2442 @end multitable
2443
2444 @item @emph{Return value}:
2445 The return value is of type @code{INTEGER(4)}
2446
2447 @item @emph{Example}:
2448 @smallexample
2449 program test_command_argument_count
2450     integer :: count
2451     count = command_argument_count()
2452     print *, count
2453 end program test_command_argument_count
2454 @end smallexample
2455
2456 @item @emph{See also}:
2457 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2458 @end table
2459
2460
2461
2462 @node COMPLEX
2463 @section @code{COMPLEX} --- Complex conversion function
2464 @fnindex COMPLEX
2465 @cindex complex numbers, conversion to
2466 @cindex conversion, to complex
2467
2468 @table @asis
2469 @item @emph{Description}:
2470 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2471 to the real component and @var{Y} is converted to the imaginary
2472 component.
2473
2474 @item @emph{Standard}:
2475 GNU extension
2476
2477 @item @emph{Class}:
2478 Elemental function
2479
2480 @item @emph{Syntax}:
2481 @code{RESULT = COMPLEX(X, Y)}
2482
2483 @item @emph{Arguments}:
2484 @multitable @columnfractions .15 .70
2485 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2486 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2487 @end multitable
2488
2489 @item @emph{Return value}:
2490 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2491 value is of default @code{COMPLEX} type.
2492
2493 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2494 type and one is of @code{INTEGER} type, then the return value is of
2495 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2496 argument with the highest precision.
2497
2498 @item @emph{Example}:
2499 @smallexample
2500 program test_complex
2501     integer :: i = 42
2502     real :: x = 3.14
2503     print *, complex(i, x)
2504 end program test_complex
2505 @end smallexample
2506
2507 @item @emph{See also}:
2508 @ref{CMPLX}
2509 @end table
2510
2511
2512
2513 @node CONJG
2514 @section @code{CONJG} --- Complex conjugate function
2515 @fnindex CONJG
2516 @fnindex DCONJG
2517 @cindex complex conjugate
2518
2519 @table @asis
2520 @item @emph{Description}:
2521 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2522 then the result is @code{(x, -y)}
2523
2524 @item @emph{Standard}:
2525 Fortran 77 and later, has overloads that are GNU extensions
2526
2527 @item @emph{Class}:
2528 Elemental function
2529
2530 @item @emph{Syntax}:
2531 @code{Z = CONJG(Z)}
2532
2533 @item @emph{Arguments}:
2534 @multitable @columnfractions .15 .70
2535 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2536 @end multitable
2537
2538 @item @emph{Return value}:
2539 The return value is of type @code{COMPLEX}.
2540
2541 @item @emph{Example}:
2542 @smallexample
2543 program test_conjg
2544     complex :: z = (2.0, 3.0)
2545     complex(8) :: dz = (2.71_8, -3.14_8)
2546     z= conjg(z)
2547     print *, z
2548     dz = dconjg(dz)
2549     print *, dz
2550 end program test_conjg
2551 @end smallexample
2552
2553 @item @emph{Specific names}:
2554 @multitable @columnfractions .20 .20 .20 .25
2555 @item Name             @tab Argument             @tab Return type          @tab Standard
2556 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)}    @tab GNU extension
2557 @end multitable
2558 @end table
2559
2560
2561
2562 @node COS
2563 @section @code{COS} --- Cosine function
2564 @fnindex COS
2565 @fnindex DCOS
2566 @fnindex CCOS
2567 @fnindex ZCOS
2568 @fnindex CDCOS
2569 @cindex trigonometric function, cosine
2570 @cindex cosine
2571
2572 @table @asis
2573 @item @emph{Description}:
2574 @code{COS(X)} computes the cosine of @var{X}.
2575
2576 @item @emph{Standard}:
2577 Fortran 77 and later, has overloads that are GNU extensions
2578
2579 @item @emph{Class}:
2580 Elemental function
2581
2582 @item @emph{Syntax}:
2583 @code{RESULT = COS(X)}
2584
2585 @item @emph{Arguments}:
2586 @multitable @columnfractions .15 .70
2587 @item @var{X} @tab The type shall be @code{REAL} or
2588 @code{COMPLEX}.
2589 @end multitable
2590
2591 @item @emph{Return value}:
2592 The return value is of type @code{REAL} and it lies in the
2593 range @math{ -1 \leq \cos (x) \leq 1}.  The kind type
2594 parameter is the same as @var{X}.
2595
2596 @item @emph{Example}:
2597 @smallexample
2598 program test_cos
2599   real :: x = 0.0
2600   x = cos(x)
2601 end program test_cos
2602 @end smallexample
2603
2604 @item @emph{Specific names}:
2605 @multitable @columnfractions .20 .20 .20 .25
2606 @item Name            @tab Argument            @tab Return type       @tab Standard
2607 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2608 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2609 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2610 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2611 @end multitable
2612
2613 @item @emph{See also}:
2614 Inverse function: @ref{ACOS}
2615
2616 @end table
2617
2618
2619
2620 @node COSH
2621 @section @code{COSH} --- Hyperbolic cosine function
2622 @fnindex COSH
2623 @fnindex DCOSH
2624 @cindex hyperbolic cosine
2625 @cindex hyperbolic function, cosine
2626 @cindex cosine, hyperbolic
2627
2628 @table @asis
2629 @item @emph{Description}:
2630 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2631
2632 @item @emph{Standard}:
2633 Fortran 77 and later
2634
2635 @item @emph{Class}:
2636 Elemental function
2637
2638 @item @emph{Syntax}:
2639 @code{X = COSH(X)}
2640
2641 @item @emph{Arguments}:
2642 @multitable @columnfractions .15 .70
2643 @item @var{X} @tab The type shall be @code{REAL}.
2644 @end multitable
2645
2646 @item @emph{Return value}:
2647 The return value is of type @code{REAL} and it is positive
2648 (@math{ \cosh (x) \geq 0 }. The return value is of the same
2649 kind as @var{X}.
2650
2651 @item @emph{Example}:
2652 @smallexample
2653 program test_cosh
2654   real(8) :: x = 1.0_8
2655   x = cosh(x)
2656 end program test_cosh
2657 @end smallexample
2658
2659 @item @emph{Specific names}:
2660 @multitable @columnfractions .20 .20 .20 .25
2661 @item Name            @tab Argument          @tab Return type       @tab Standard
2662 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
2663 @end multitable
2664
2665 @item @emph{See also}:
2666 Inverse function: @ref{ACOSH}
2667
2668 @end table
2669
2670
2671
2672 @node COUNT
2673 @section @code{COUNT} --- Count function
2674 @fnindex COUNT
2675 @cindex array, conditionally count elements
2676 @cindex array, element counting
2677 @cindex array, number of elements
2678
2679 @table @asis
2680 @item @emph{Description}:
2681
2682 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2683 elements of @var{MASK} along the dimension of @var{DIM}.  If @var{DIM} is
2684 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
2685 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2686 is the rank of @var{MASK}.
2687
2688 @item @emph{Standard}:
2689 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2690
2691 @item @emph{Class}:
2692 Transformational function
2693
2694 @item @emph{Syntax}:
2695 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2696
2697 @item @emph{Arguments}:
2698 @multitable @columnfractions .15 .70
2699 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2700 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
2701 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2702                       expression indicating the kind parameter of
2703                       the result.
2704 @end multitable
2705
2706 @item @emph{Return value}:
2707 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2708 @var{KIND} is absent, the return value is of default integer kind.
2709 The result has a rank equal to that of @var{MASK}.
2710
2711 @item @emph{Example}:
2712 @smallexample
2713 program test_count
2714     integer, dimension(2,3) :: a, b
2715     logical, dimension(2,3) :: mask
2716     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2717     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2718     print '(3i3)', a(1,:)
2719     print '(3i3)', a(2,:)
2720     print *
2721     print '(3i3)', b(1,:)
2722     print '(3i3)', b(2,:)
2723     print *
2724     mask = a.ne.b
2725     print '(3l3)', mask(1,:)
2726     print '(3l3)', mask(2,:)
2727     print *
2728     print '(3i3)', count(mask)
2729     print *
2730     print '(3i3)', count(mask, 1)
2731     print *
2732     print '(3i3)', count(mask, 2)
2733 end program test_count
2734 @end smallexample
2735 @end table
2736
2737
2738
2739 @node CPU_TIME
2740 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2741 @fnindex CPU_TIME
2742 @cindex time, elapsed
2743
2744 @table @asis
2745 @item @emph{Description}:
2746 Returns a @code{REAL} value representing the elapsed CPU time in
2747 seconds.  This is useful for testing segments of code to determine
2748 execution time.
2749
2750 If a time source is available, time will be reported with microsecond
2751 resolution. If no time source is available, @var{TIME} is set to
2752 @code{-1.0}.
2753
2754 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2755 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2756 value is meaningless, only differences between subsequent calls to
2757 this subroutine, as shown in the example below, should be used.
2758
2759
2760 @item @emph{Standard}:
2761 Fortran 95 and later
2762
2763 @item @emph{Class}:
2764 Subroutine
2765
2766 @item @emph{Syntax}:
2767 @code{CALL CPU_TIME(TIME)}
2768
2769 @item @emph{Arguments}:
2770 @multitable @columnfractions .15 .70
2771 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2772 @end multitable
2773
2774 @item @emph{Return value}:
2775 None
2776
2777 @item @emph{Example}:
2778 @smallexample
2779 program test_cpu_time
2780     real :: start, finish
2781     call cpu_time(start)
2782         ! put code to test here
2783     call cpu_time(finish)
2784     print '("Time = ",f6.3," seconds.")',finish-start
2785 end program test_cpu_time
2786 @end smallexample
2787
2788 @item @emph{See also}:
2789 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2790 @end table
2791
2792
2793
2794 @node CSHIFT
2795 @section @code{CSHIFT} --- Circular shift elements of an array
2796 @fnindex CSHIFT
2797 @cindex array, shift circularly
2798 @cindex array, permutation
2799 @cindex array, rotate
2800
2801 @table @asis
2802 @item @emph{Description}:
2803 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2804 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
2805 taken to be @code{1}.  @var{DIM} is a scaler of type @code{INTEGER} in the
2806 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2807 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2808 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
2809 sections of @var{ARRAY} along the given dimension are shifted.  Elements
2810 shifted out one end of each rank one section are shifted back in the other end.
2811
2812 @item @emph{Standard}:
2813 Fortran 95 and later
2814
2815 @item @emph{Class}:
2816 Transformational function
2817
2818 @item @emph{Syntax}:
2819 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2820
2821 @item @emph{Arguments}:
2822 @multitable @columnfractions .15 .70
2823 @item @var{ARRAY}  @tab Shall be an array of any type.
2824 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
2825 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
2826 @end multitable
2827
2828 @item @emph{Return value}:
2829 Returns an array of same type and rank as the @var{ARRAY} argument.
2830
2831 @item @emph{Example}:
2832 @smallexample
2833 program test_cshift
2834     integer, dimension(3,3) :: a
2835     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2836     print '(3i3)', a(1,:)
2837     print '(3i3)', a(2,:)
2838     print '(3i3)', a(3,:)
2839     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2840     print *
2841     print '(3i3)', a(1,:)
2842     print '(3i3)', a(2,:)
2843     print '(3i3)', a(3,:)
2844 end program test_cshift
2845 @end smallexample
2846 @end table
2847
2848
2849
2850 @node CTIME
2851 @section @code{CTIME} --- Convert a time into a string
2852 @fnindex CTIME
2853 @cindex time, conversion to string
2854 @cindex conversion, to string
2855
2856 @table @asis
2857 @item @emph{Description}:
2858 @code{CTIME} converts a system time value, such as returned by
2859 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2860
2861 This intrinsic is provided in both subroutine and function forms; however,
2862 only one form can be used in any given program unit.
2863
2864 @item @emph{Standard}:
2865 GNU extension
2866
2867 @item @emph{Class}:
2868 Subroutine, function
2869
2870 @item @emph{Syntax}:
2871 @multitable @columnfractions .80
2872 @item @code{CALL CTIME(TIME, RESULT)}.
2873 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2874 @end multitable
2875
2876 @item @emph{Arguments}:
2877 @multitable @columnfractions .15 .70
2878 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
2879 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
2880                          of default kind.
2881 @end multitable
2882
2883 @item @emph{Return value}:
2884 The converted date and time as a string.
2885
2886 @item @emph{Example}:
2887 @smallexample
2888 program test_ctime
2889     integer(8) :: i
2890     character(len=30) :: date
2891     i = time8()
2892
2893     ! Do something, main part of the program
2894
2895     call ctime(i,date)
2896     print *, 'Program was started on ', date
2897 end program test_ctime
2898 @end smallexample
2899
2900 @item @emph{See Also}:
2901 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2902 @end table
2903
2904
2905
2906 @node DATE_AND_TIME
2907 @section @code{DATE_AND_TIME} --- Date and time subroutine
2908 @fnindex DATE_AND_TIME
2909 @cindex date, current
2910 @cindex current date
2911 @cindex time, current
2912 @cindex current time
2913
2914 @table @asis
2915 @item @emph{Description}:
2916 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2917 time information from the real-time system clock.  @var{DATE} is
2918 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
2919 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2920 representing the difference with respect to Coordinated Universal Time (UTC).
2921 Unavailable time and date parameters return blanks.
2922
2923 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2924
2925 @multitable @columnfractions .15 .30 .40
2926 @item @tab @code{VALUE(1)}: @tab The year
2927 @item @tab @code{VALUE(2)}: @tab The month
2928 @item @tab @code{VALUE(3)}: @tab The day of the month
2929 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2930 @item @tab @code{VALUE(5)}: @tab The hour of the day
2931 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2932 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2933 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2934 @end multitable
2935
2936 @item @emph{Standard}:
2937 Fortran 95 and later
2938
2939 @item @emph{Class}:
2940 Subroutine
2941
2942 @item @emph{Syntax}:
2943 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2944
2945 @item @emph{Arguments}:
2946 @multitable @columnfractions .15 .70
2947 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
2948                                   or larger, and of default kind.
2949 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
2950                                   or larger, and of default kind.
2951 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
2952                                   or larger, and of default kind.
2953 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2954 @end multitable
2955
2956 @item @emph{Return value}:
2957 None
2958
2959 @item @emph{Example}:
2960 @smallexample
2961 program test_time_and_date
2962     character(8)  :: date
2963     character(10) :: time
2964     character(5)  :: zone
2965     integer,dimension(8) :: values
2966     ! using keyword arguments
2967     call date_and_time(date,time,zone,values)
2968     call date_and_time(DATE=date,ZONE=zone)
2969     call date_and_time(TIME=time)
2970     call date_and_time(VALUES=values)
2971     print '(a,2x,a,2x,a)', date, time, zone
2972     print '(8i5))', values
2973 end program test_time_and_date
2974 @end smallexample
2975
2976 @item @emph{See also}:
2977 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2978 @end table
2979
2980
2981
2982 @node DBLE
2983 @section @code{DBLE} --- Double conversion function
2984 @fnindex DBLE
2985 @cindex conversion, to real
2986
2987 @table @asis
2988 @item @emph{Description}:
2989 @code{DBLE(A)} Converts @var{A} to double precision real type.
2990
2991 @item @emph{Standard}:
2992 Fortran 77 and later
2993
2994 @item @emph{Class}:
2995 Elemental function
2996
2997 @item @emph{Syntax}:
2998 @code{RESULT = DBLE(A)}
2999
3000 @item @emph{Arguments}:
3001 @multitable @columnfractions .15 .70
3002 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3003                    or @code{COMPLEX}.
3004 @end multitable
3005
3006 @item @emph{Return value}:
3007 The return value is of type double precision real.
3008
3009 @item @emph{Example}:
3010 @smallexample
3011 program test_dble
3012     real    :: x = 2.18
3013     integer :: i = 5
3014     complex :: z = (2.3,1.14)
3015     print *, dble(x), dble(i), dble(z)
3016 end program test_dble
3017 @end smallexample
3018
3019 @item @emph{See also}:
3020 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3021 @end table
3022
3023
3024
3025 @node DCMPLX
3026 @section @code{DCMPLX} --- Double complex conversion function
3027 @fnindex DCMPLX
3028 @cindex complex numbers, conversion to
3029 @cindex conversion, to complex
3030
3031 @table @asis
3032 @item @emph{Description}:
3033 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3034 converted to the real component.  If @var{Y} is present it is converted to the
3035 imaginary component.  If @var{Y} is not present then the imaginary component is
3036 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3037
3038 @item @emph{Standard}:
3039 GNU extension
3040
3041 @item @emph{Class}:
3042 Elemental function
3043
3044 @item @emph{Syntax}:
3045 @code{RESULT = DCMPLX(X [, Y])}
3046
3047 @item @emph{Arguments}:
3048 @multitable @columnfractions .15 .70
3049 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3050                    or @code{COMPLEX}.
3051 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3052                    @code{INTEGER} or @code{REAL}.
3053 @end multitable
3054
3055 @item @emph{Return value}:
3056 The return value is of type @code{COMPLEX(8)}
3057
3058 @item @emph{Example}:
3059 @smallexample
3060 program test_dcmplx
3061     integer :: i = 42
3062     real :: x = 3.14
3063     complex :: z
3064     z = cmplx(i, x)
3065     print *, dcmplx(i)
3066     print *, dcmplx(x)
3067     print *, dcmplx(z)
3068     print *, dcmplx(x,i)
3069 end program test_dcmplx
3070 @end smallexample
3071 @end table
3072
3073
3074
3075 @node DFLOAT
3076 @section @code{DFLOAT} --- Double conversion function
3077 @fnindex DFLOAT
3078 @cindex conversion, to real
3079
3080 @table @asis
3081 @item @emph{Description}:
3082 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3083
3084 @item @emph{Standard}:
3085 GNU extension
3086
3087 @item @emph{Class}:
3088 Elemental function
3089
3090 @item @emph{Syntax}:
3091 @code{RESULT = DFLOAT(A)}
3092
3093 @item @emph{Arguments}:
3094 @multitable @columnfractions .15 .70
3095 @item @var{A} @tab The type shall be @code{INTEGER}.
3096 @end multitable
3097
3098 @item @emph{Return value}:
3099 The return value is of type double precision real.
3100
3101 @item @emph{Example}:
3102 @smallexample
3103 program test_dfloat
3104     integer :: i = 5
3105     print *, dfloat(i)
3106 end program test_dfloat
3107 @end smallexample
3108
3109 @item @emph{See also}:
3110 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3111 @end table
3112
3113
3114
3115 @node DIGITS
3116 @section @code{DIGITS} --- Significant digits function
3117 @fnindex DIGITS
3118 @cindex model representation, significant digits
3119
3120 @table @asis
3121 @item @emph{Description}:
3122 @code{DIGITS(X)} returns the number of significant digits of the internal model
3123 representation of @var{X}.  For example, on a system using a 32-bit
3124 floating point representation, a default real number would likely return 24.
3125
3126 @item @emph{Standard}:
3127 Fortran 95 and later
3128
3129 @item @emph{Class}:
3130 Inquiry function
3131
3132 @item @emph{Syntax}:
3133 @code{RESULT = DIGITS(X)}
3134
3135 @item @emph{Arguments}:
3136 @multitable @columnfractions .15 .70
3137 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3138 @end multitable
3139
3140 @item @emph{Return value}:
3141 The return value is of type @code{INTEGER}.
3142
3143 @item @emph{Example}:
3144 @smallexample
3145 program test_digits
3146     integer :: i = 12345
3147     real :: x = 3.143
3148     real(8) :: y = 2.33
3149     print *, digits(i)
3150     print *, digits(x)
3151     print *, digits(y)
3152 end program test_digits
3153 @end smallexample
3154 @end table
3155
3156
3157
3158 @node DIM
3159 @section @code{DIM} --- Positive difference
3160 @fnindex DIM
3161 @fnindex IDIM
3162 @fnindex DDIM
3163 @cindex positive difference
3164
3165 @table @asis
3166 @item @emph{Description}:
3167 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3168 otherwise returns zero.
3169
3170 @item @emph{Standard}:
3171 Fortran 77 and later
3172
3173 @item @emph{Class}:
3174 Elemental function
3175
3176 @item @emph{Syntax}:
3177 @code{RESULT = DIM(X, Y)}
3178
3179 @item @emph{Arguments}:
3180 @multitable @columnfractions .15 .70
3181 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3182 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3183 @end multitable
3184
3185 @item @emph{Return value}:
3186 The return value is of type @code{INTEGER} or @code{REAL}.
3187
3188 @item @emph{Example}:
3189 @smallexample
3190 program test_dim
3191     integer :: i
3192     real(8) :: x
3193     i = dim(4, 15)
3194     x = dim(4.345_8, 2.111_8)
3195     print *, i
3196     print *, x
3197 end program test_dim
3198 @end smallexample
3199
3200 @item @emph{Specific names}:
3201 @multitable @columnfractions .20 .20 .20 .25
3202 @item Name             @tab Argument              @tab Return type       @tab Standard
3203 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3204 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3205 @end multitable
3206 @end table
3207
3208
3209
3210 @node DOT_PRODUCT
3211 @section @code{DOT_PRODUCT} --- Dot product function
3212 @fnindex DOT_PRODUCT
3213 @cindex dot product
3214 @cindex vector product
3215 @cindex product, vector
3216
3217 @table @asis
3218 @item @emph{Description}:
3219 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3220 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3221 either numeric or logical and must be arrays of rank one and of equal size. If
3222 the vectors are @code{INTEGER} or @code{REAL}, the result is
3223 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3224 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3225 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3226
3227 @item @emph{Standard}:
3228 Fortran 95 and later
3229
3230 @item @emph{Class}:
3231 Transformational function
3232
3233 @item @emph{Syntax}:
3234 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3235
3236 @item @emph{Arguments}:
3237 @multitable @columnfractions .15 .70
3238 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3239 @item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
3240 @end multitable
3241
3242 @item @emph{Return value}:
3243 If the arguments are numeric, the return value is a scaler of numeric type,
3244 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3245 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3246
3247 @item @emph{Example}:
3248 @smallexample
3249 program test_dot_prod
3250     integer, dimension(3) :: a, b
3251     a = (/ 1, 2, 3 /)
3252     b = (/ 4, 5, 6 /)
3253     print '(3i3)', a
3254     print *
3255     print '(3i3)', b
3256     print *
3257     print *, dot_product(a,b)
3258 end program test_dot_prod
3259 @end smallexample
3260 @end table
3261
3262
3263
3264 @node DPROD
3265 @section @code{DPROD} --- Double product function
3266 @fnindex DPROD
3267 @cindex product, double-precision
3268
3269 @table @asis
3270 @item @emph{Description}:
3271 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3272
3273 @item @emph{Standard}:
3274 Fortran 77 and later
3275
3276 @item @emph{Class}:
3277 Elemental function
3278
3279 @item @emph{Syntax}:
3280 @code{RESULT = DPROD(X, Y)}
3281
3282 @item @emph{Arguments}:
3283 @multitable @columnfractions .15 .70
3284 @item @var{X} @tab The type shall be @code{REAL}.
3285 @item @var{Y} @tab The type shall be @code{REAL}.
3286 @end multitable
3287
3288 @item @emph{Return value}:
3289 The return value is of type @code{REAL(8)}.
3290
3291 @item @emph{Example}:
3292 @smallexample
3293 program test_dprod
3294     real :: x = 5.2
3295     real :: y = 2.3
3296     real(8) :: d
3297     d = dprod(x,y)
3298     print *, d
3299 end program test_dprod
3300 @end smallexample
3301 @end table
3302
3303
3304
3305 @node DREAL
3306 @section @code{DREAL} --- Double real part function
3307 @fnindex DREAL
3308 @cindex complex numbers, real part
3309
3310 @table @asis
3311 @item @emph{Description}:
3312 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3313
3314 @item @emph{Standard}:
3315 GNU extension
3316
3317 @item @emph{Class}:
3318 Elemental function
3319
3320 @item @emph{Syntax}:
3321 @code{RESULT = DREAL(A)}
3322
3323 @item @emph{Arguments}:
3324 @multitable @columnfractions .15 .70
3325 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3326 @end multitable
3327
3328 @item @emph{Return value}:
3329 The return value is of type @code{REAL(8)}.
3330
3331 @item @emph{Example}:
3332 @smallexample
3333 program test_dreal
3334     complex(8) :: z = (1.3_8,7.2_8)
3335     print *, dreal(z)
3336 end program test_dreal
3337 @end smallexample
3338
3339 @item @emph{See also}:
3340 @ref{AIMAG}
3341
3342 @end table
3343
3344
3345
3346 @node DTIME
3347 @section @code{DTIME} --- Execution time subroutine (or function)
3348 @fnindex DTIME
3349 @cindex time, elapsed
3350 @cindex elapsed time
3351
3352 @table @asis
3353 @item @emph{Description}:
3354 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3355 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
3356 returns the user and system components of this time in @code{TARRAY(1)} and
3357 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3358 TARRAY(2)}.
3359
3360 Subsequent invocations of @code{DTIME} return values accumulated since the
3361 previous invocation.
3362
3363 On some systems, the underlying timings are represented using types with
3364 sufficiently small limits that overflows (wrap around) are possible, such as
3365 32-bit types. Therefore, the values returned by this intrinsic might be, or
3366 become, negative, or numerically less than previous values, during a single
3367 run of the compiled program.
3368
3369 Please note, that this implementation is thread safe if used within OpenMP
3370 directives, i.e., its state will be consistent while called from multiple
3371 threads. However, if @code{DTIME} is called from multiple threads, the result
3372 is still the time since the last invocation. This may not give the intended
3373 results. If possible, use @code{CPU_TIME} instead.
3374
3375 This intrinsic is provided in both subroutine and function forms; however,
3376 only one form can be used in any given program unit.
3377
3378 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3379
3380 @multitable @columnfractions .15 .30 .40
3381 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3382 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3383 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3384 @end multitable
3385
3386 @item @emph{Standard}:
3387 GNU extension
3388
3389 @item @emph{Class}:
3390 Subroutine, function
3391
3392 @item @emph{Syntax}:
3393 @multitable @columnfractions .80
3394 @item @code{CALL DTIME(TARRAY, RESULT)}.
3395 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3396 @end multitable
3397
3398 @item @emph{Arguments}:
3399 @multitable @columnfractions .15 .70
3400 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3401 @item @var{RESULT}@tab The type shall be @code{REAL}.
3402 @end multitable
3403
3404 @item @emph{Return value}:
3405 Elapsed time in seconds since the last invocation or since the start of program
3406 execution if not called before.
3407
3408 @item @emph{Example}:
3409 @smallexample
3410 program test_dtime
3411     integer(8) :: i, j
3412     real, dimension(2) :: tarray
3413     real :: result
3414     call dtime(tarray, result)
3415     print *, result
3416     print *, tarray(1)
3417     print *, tarray(2)
3418     do i=1,100000000    ! Just a delay
3419         j = i * i - i
3420     end do
3421     call dtime(tarray, result)
3422     print *, result
3423     print *, tarray(1)
3424     print *, tarray(2)
3425 end program test_dtime
3426 @end smallexample
3427
3428 @item @emph{See also}:
3429 @ref{CPU_TIME}
3430
3431 @end table
3432
3433
3434
3435 @node EOSHIFT
3436 @section @code{EOSHIFT} --- End-off shift elements of an array
3437 @fnindex EOSHIFT
3438 @cindex array, shift
3439
3440 @table @asis
3441 @item @emph{Description}:
3442 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3443 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3444 omitted it is taken to be @code{1}.  @var{DIM} is a scaler of type
3445 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3446 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3447 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3448 then all complete rank one sections of @var{ARRAY} along the given dimension are
3449 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3450 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3451 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3452 following are copied in depending on the type of @var{ARRAY}.
3453
3454 @multitable @columnfractions .15 .80
3455 @item @emph{Array Type} @tab @emph{Boundary Value}
3456 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3457 @item Logical  @tab @code{.FALSE.}.
3458 @item Character(@var{len}) @tab @var{len} blanks.
3459 @end multitable
3460
3461 @item @emph{Standard}:
3462 Fortran 95 and later
3463
3464 @item @emph{Class}:
3465 Transformational function
3466
3467 @item @emph{Syntax}:
3468 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3469
3470 @item @emph{Arguments}:
3471 @multitable @columnfractions .15 .70
3472 @item @var{ARRAY}  @tab May be any type, not scaler.
3473 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3474 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3475 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3476 @end multitable
3477
3478 @item @emph{Return value}:
3479 Returns an array of same type and rank as the @var{ARRAY} argument.
3480
3481 @item @emph{Example}:
3482 @smallexample
3483 program test_eoshift
3484     integer, dimension(3,3) :: a
3485     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3486     print '(3i3)', a(1,:)
3487     print '(3i3)', a(2,:)
3488     print '(3i3)', a(3,:)
3489     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3490     print *
3491     print '(3i3)', a(1,:)
3492     print '(3i3)', a(2,:)
3493     print '(3i3)', a(3,:)
3494 end program test_eoshift
3495 @end smallexample
3496 @end table
3497
3498
3499
3500 @node EPSILON
3501 @section @code{EPSILON} --- Epsilon function
3502 @fnindex EPSILON
3503 @cindex model representation, epsilon
3504
3505 @table @asis
3506 @item @emph{Description}:
3507 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3508
3509 @item @emph{Standard}:
3510 Fortran 95 and later
3511
3512 @item @emph{Class}:
3513 Inquiry function
3514
3515 @item @emph{Syntax}:
3516 @code{RESULT = EPSILON(X)}
3517
3518 @item @emph{Arguments}:
3519 @multitable @columnfractions .15 .70
3520 @item @var{X} @tab The type shall be @code{REAL}.
3521 @end multitable
3522
3523 @item @emph{Return value}:
3524 The return value is of same type as the argument.
3525
3526 @item @emph{Example}:
3527 @smallexample
3528 program test_epsilon
3529     real :: x = 3.143
3530     real(8) :: y = 2.33
3531     print *, EPSILON(x)
3532     print *, EPSILON(y)
3533 end program test_epsilon
3534 @end smallexample
3535 @end table
3536
3537
3538
3539 @node ERF
3540 @section @code{ERF} --- Error function
3541 @fnindex ERF
3542 @cindex error function
3543
3544 @table @asis
3545 @item @emph{Description}:
3546 @code{ERF(X)} computes the error function of @var{X}.
3547
3548 @item @emph{Standard}:
3549 Fortran 2008 and later
3550
3551 @item @emph{Class}:
3552 Elemental function
3553
3554 @item @emph{Syntax}:
3555 @code{RESULT = ERF(X)}
3556
3557 @item @emph{Arguments}:
3558 @multitable @columnfractions .15 .70
3559 @item @var{X} @tab The type shall be @code{REAL}.
3560 @end multitable
3561
3562 @item @emph{Return value}:
3563 The return value is of type @code{REAL}, of the same kind as
3564 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3565
3566 @item @emph{Example}:
3567 @smallexample
3568 program test_erf
3569   real(8) :: x = 0.17_8
3570   x = erf(x)
3571 end program test_erf
3572 @end smallexample
3573
3574 @item @emph{Specific names}:
3575 @multitable @columnfractions .20 .20 .20 .25
3576 @item Name            @tab Argument          @tab Return type       @tab Standard
3577 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3578 @end multitable
3579 @end table
3580
3581
3582
3583 @node ERFC
3584 @section @code{ERFC} --- Error function
3585 @fnindex ERFC
3586 @cindex error function, complementary
3587
3588 @table @asis
3589 @item @emph{Description}:
3590 @code{ERFC(X)} computes the complementary error function of @var{X}.
3591
3592 @item @emph{Standard}:
3593 Fortran 2008 and later
3594
3595 @item @emph{Class}:
3596 Elemental function
3597
3598 @item @emph{Syntax}:
3599 @code{RESULT = ERFC(X)}
3600
3601 @item @emph{Arguments}:
3602 @multitable @columnfractions .15 .70
3603 @item @var{X} @tab The type shall be @code{REAL}.
3604 @end multitable
3605
3606 @item @emph{Return value}:
3607 The return value is of type @code{REAL} and of the same kind as @var{X}.
3608 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3609
3610 @item @emph{Example}:
3611 @smallexample
3612 program test_erfc
3613   real(8) :: x = 0.17_8
3614   x = erfc(x)
3615 end program test_erfc
3616 @end smallexample
3617
3618 @item @emph{Specific names}:
3619 @multitable @columnfractions .20 .20 .20 .25
3620 @item Name            @tab Argument          @tab Return type       @tab Standard
3621 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3622 @end multitable
3623 @end table
3624
3625
3626
3627 @node ERFC_SCALED
3628 @section @code{ERFC_SCALED} --- Error function
3629 @fnindex ERFC_SCALED
3630 @cindex error function, complementary, exponentially-scaled
3631
3632 @table @asis
3633 @item @emph{Description}:
3634 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3635 error function of @var{X}.
3636
3637 @item @emph{Standard}:
3638 Fortran 2008 and later
3639
3640 @item @emph{Class}:
3641 Elemental function
3642
3643 @item @emph{Syntax}:
3644 @code{RESULT = ERFC_SCALED(X)}
3645
3646 @item @emph{Arguments}:
3647 @multitable @columnfractions .15 .70
3648 @item @var{X} @tab The type shall be @code{REAL}.
3649 @end multitable
3650
3651 @item @emph{Return value}:
3652 The return value is of type @code{REAL} and of the same kind as @var{X}.
3653
3654 @item @emph{Example}:
3655 @smallexample
3656 program test_erfc_scaled
3657   real(8) :: x = 0.17_8
3658   x = erfc_scaled(x)
3659 end program test_erfc_scaled
3660 @end smallexample
3661 @end table
3662
3663
3664
3665 @node ETIME
3666 @section @code{ETIME} --- Execution time subroutine (or function)
3667 @fnindex ETIME
3668 @cindex time, elapsed
3669
3670 @table @asis
3671 @item @emph{Description}:
3672 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3673 since the start of the process's execution in @var{RESULT}.  @var{TARRAY}
3674 returns the user and system components of this time in @code{TARRAY(1)} and
3675 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3676
3677 On some systems, the underlying timings are represented using types with
3678 sufficiently small limits that overflows (wrap around) are possible, such as
3679 32-bit types. Therefore, the values returned by this intrinsic might be, or
3680 become, negative, or numerically less than previous values, during a single
3681 run of the compiled program.
3682
3683 This intrinsic is provided in both subroutine and function forms; however,
3684 only one form can be used in any given program unit.
3685
3686 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3687
3688 @multitable @columnfractions .15 .30 .60
3689 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3690 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3691 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3692 @end multitable
3693
3694 @item @emph{Standard}:
3695 GNU extension
3696
3697 @item @emph{Class}:
3698 Subroutine, function
3699
3700 @item @emph{Syntax}:
3701 @multitable @columnfractions .80
3702 @item @code{CALL ETIME(TARRAY, RESULT)}.
3703 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3704 @end multitable
3705
3706 @item @emph{Arguments}:
3707 @multitable @columnfractions .15 .70
3708 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3709 @item @var{RESULT}@tab The type shall be @code{REAL}.
3710 @end multitable
3711
3712 @item @emph{Return value}:
3713 Elapsed time in seconds since the start of program execution.
3714
3715 @item @emph{Example}:
3716 @smallexample
3717 program test_etime
3718     integer(8) :: i, j
3719     real, dimension(2) :: tarray
3720     real :: result
3721     call ETIME(tarray, result)
3722     print *, result
3723     print *, tarray(1)
3724     print *, tarray(2)
3725     do i=1,100000000    ! Just a delay
3726         j = i * i - i
3727     end do
3728     call ETIME(tarray, result)
3729     print *, result
3730     print *, tarray(1)
3731     print *, tarray(2)
3732 end program test_etime
3733 @end smallexample
3734
3735 @item @emph{See also}:
3736 @ref{CPU_TIME}
3737
3738 @end table
3739
3740
3741
3742 @node EXIT
3743 @section @code{EXIT} --- Exit the program with status.
3744 @fnindex EXIT
3745 @cindex program termination
3746 @cindex terminate program
3747
3748 @table @asis
3749 @item @emph{Description}:
3750 @code{EXIT} causes immediate termination of the program with status.  If status
3751 is omitted it returns the canonical @emph{success} for the system.  All Fortran
3752 I/O units are closed.
3753
3754 @item @emph{Standard}:
3755 GNU extension
3756
3757 @item @emph{Class}:
3758 Subroutine
3759
3760 @item @emph{Syntax}:
3761 @code{CALL EXIT([STATUS])}
3762
3763 @item @emph{Arguments}:
3764 @multitable @columnfractions .15 .70
3765 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3766 @end multitable
3767
3768 @item @emph{Return value}:
3769 @code{STATUS} is passed to the parent process on exit.
3770
3771 @item @emph{Example}:
3772 @smallexample
3773 program test_exit
3774   integer :: STATUS = 0
3775   print *, 'This program is going to exit.'
3776   call EXIT(STATUS)
3777 end program test_exit
3778 @end smallexample
3779
3780 @item @emph{See also}:
3781 @ref{ABORT}, @ref{KILL}
3782 @end table
3783
3784
3785
3786 @node EXP
3787 @section @code{EXP} --- Exponential function
3788 @fnindex EXP
3789 @fnindex DEXP
3790 @fnindex CEXP
3791 @fnindex ZEXP
3792 @fnindex CDEXP
3793 @cindex exponential function
3794 @cindex logarithmic function, inverse
3795
3796 @table @asis
3797 @item @emph{Description}:
3798 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3799
3800 @item @emph{Standard}:
3801 Fortran 77 and later, has overloads that are GNU extensions
3802
3803 @item @emph{Class}:
3804 Elemental function
3805
3806 @item @emph{Syntax}:
3807 @code{RESULT = EXP(X)}
3808
3809 @item @emph{Arguments}:
3810 @multitable @columnfractions .15 .70
3811 @item @var{X} @tab The type shall be @code{REAL} or
3812 @code{COMPLEX}.
3813 @end multitable
3814
3815 @item @emph{Return value}:
3816 The return value has same type and kind as @var{X}.
3817
3818 @item @emph{Example}:
3819 @smallexample
3820 program test_exp
3821   real :: x = 1.0
3822   x = exp(x)
3823 end program test_exp
3824 @end smallexample
3825
3826 @item @emph{Specific names}:
3827 @multitable @columnfractions .20 .20 .20 .25
3828 @item Name            @tab Argument             @tab Return type         @tab Standard
3829 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
3830 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
3831 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3832 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
3833 @end multitable
3834 @end table
3835
3836
3837
3838 @node EXPONENT
3839 @section @code{EXPONENT} --- Exponent function
3840 @fnindex EXPONENT
3841 @cindex real number, exponent
3842 @cindex floating point, exponent
3843
3844 @table @asis
3845 @item @emph{Description}:
3846 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3847 is zero the value returned is zero.
3848
3849 @item @emph{Standard}:
3850 Fortran 95 and later
3851
3852 @item @emph{Class}:
3853 Elemental function
3854
3855 @item @emph{Syntax}:
3856 @code{RESULT = EXPONENT(X)}
3857
3858 @item @emph{Arguments}:
3859 @multitable @columnfractions .15 .70
3860 @item @var{X} @tab The type shall be @code{REAL}.
3861 @end multitable
3862
3863 @item @emph{Return value}:
3864 The return value is of type default @code{INTEGER}.
3865
3866 @item @emph{Example}:
3867 @smallexample
3868 program test_exponent
3869   real :: x = 1.0
3870   integer :: i
3871   i = exponent(x)
3872   print *, i
3873   print *, exponent(0.0)
3874 end program test_exponent
3875 @end smallexample
3876 @end table
3877
3878
3879
3880 @node FDATE
3881 @section @code{FDATE} --- Get the current time as a string
3882 @fnindex FDATE
3883 @cindex time, current
3884 @cindex current time
3885 @cindex date, current
3886 @cindex current date
3887
3888 @table @asis
3889 @item @emph{Description}:
3890 @code{FDATE(DATE)} returns the current date (using the same format as
3891 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3892 TIME())}.
3893
3894 This intrinsic is provided in both subroutine and function forms; however,
3895 only one form can be used in any given program unit.
3896
3897 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3898 default kind.
3899
3900 @item @emph{Standard}:
3901 GNU extension
3902
3903 @item @emph{Class}:
3904 Subroutine, function
3905
3906 @item @emph{Syntax}:
3907 @multitable @columnfractions .80
3908 @item @code{CALL FDATE(DATE)}.
3909 @item @code{DATE = FDATE()}, (not recommended).
3910 @end multitable
3911
3912 @item @emph{Arguments}:
3913 @multitable @columnfractions .15 .70
3914 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3915 default kind
3916 @end multitable
3917
3918 @item @emph{Return value}:
3919 The current date as a string.
3920
3921 @item @emph{Example}:
3922 @smallexample
3923 program test_fdate
3924     integer(8) :: i, j
3925     character(len=30) :: date
3926     call fdate(date)
3927     print *, 'Program started on ', date
3928     do i = 1, 100000000 ! Just a delay
3929         j = i * i - i
3930     end do
3931     call fdate(date)
3932     print *, 'Program ended on ', date
3933 end program test_fdate
3934 @end smallexample
3935 @end table
3936
3937
3938
3939 @node FLOAT
3940 @section @code{FLOAT} --- Convert integer to default real
3941 @fnindex FLOAT
3942 @cindex conversion, to real
3943
3944 @table @asis
3945 @item @emph{Description}:
3946 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
3947
3948 @item @emph{Standard}:
3949 Fortran 77 and later
3950
3951 @item @emph{Class}:
3952 Elemental function
3953
3954 @item @emph{Syntax}:
3955 @code{RESULT = FLOAT(A)}
3956
3957 @item @emph{Arguments}:
3958 @multitable @columnfractions .15 .70
3959 @item @var{A} @tab The type shall be @code{INTEGER}.
3960 @end multitable
3961
3962 @item @emph{Return value}:
3963 The return value is of type default @code{REAL}.
3964
3965 @item @emph{Example}:
3966 @smallexample
3967 program test_float
3968     integer :: i = 1
3969     if (float(i) /= 1.) call abort
3970 end program test_float
3971 @end smallexample
3972
3973 @item @emph{See also}:
3974 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3975 @end table
3976
3977
3978
3979 @node FGET
3980 @section @code{FGET} --- Read a single character in stream mode from stdin
3981 @fnindex FGET
3982 @cindex read character, stream mode
3983 @cindex stream mode, read character
3984 @cindex file operation, read character
3985
3986 @table @asis
3987 @item @emph{Description}:
3988 Read a single character in stream mode from stdin by bypassing normal
3989 formatted output. Stream I/O should not be mixed with normal record-oriented
3990 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3991
3992 This intrinsic is provided in both subroutine and function forms; however,
3993 only one form can be used in any given program unit.
3994
3995 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
3996 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
3997 Programmers should consider the use of new stream IO feature in new code
3998 for future portability. See also @ref{Fortran 2003 status}.
3999
4000 @item @emph{Standard}:
4001 GNU extension
4002
4003 @item @emph{Class}:
4004 Subroutine, function
4005
4006 @item @emph{Syntax}:
4007 @code{CALL FGET(C [, STATUS])}
4008
4009 @item @emph{Arguments}:
4010 @multitable @columnfractions .15 .70
4011 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4012                         kind.
4013 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4014                         Returns 0 on success, -1 on end-of-file, and a
4015                         system specific positive error code otherwise.
4016 @end multitable
4017
4018 @item @emph{Example}:
4019 @smallexample
4020 PROGRAM test_fget
4021   INTEGER, PARAMETER :: strlen = 100
4022   INTEGER :: status, i = 1
4023   CHARACTER(len=strlen) :: str = ""
4024
4025   WRITE (*,*) 'Enter text:'
4026   DO
4027     CALL fget(str(i:i), status)
4028     if (status /= 0 .OR. i > strlen) exit
4029     i = i + 1
4030   END DO
4031   WRITE (*,*) TRIM(str)
4032 END PROGRAM
4033 @end smallexample
4034
4035 @item @emph{See also}:
4036 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4037 @end table
4038
4039
4040
4041 @node FGETC
4042 @section @code{FGETC} --- Read a single character in stream mode
4043 @fnindex FGETC
4044 @cindex read character, stream mode
4045 @cindex stream mode, read character
4046 @cindex file operation, read character
4047
4048 @table @asis
4049 @item @emph{Description}:
4050 Read a single character in stream mode by bypassing normal formatted output.
4051 Stream I/O should not be mixed with normal record-oriented (formatted or
4052 unformatted) I/O on the same unit; the results are unpredictable.
4053
4054 This intrinsic is provided in both subroutine and function forms; however,
4055 only one form can be used in any given program unit.
4056
4057 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4058 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4059 Programmers should consider the use of new stream IO feature in new code
4060 for future portability. See also @ref{Fortran 2003 status}.
4061
4062 @item @emph{Standard}:
4063 GNU extension
4064
4065 @item @emph{Class}:
4066 Subroutine, function
4067
4068 @item @emph{Syntax}:
4069 @code{CALL FGETC(UNIT, C [, STATUS])}
4070
4071 @item @emph{Arguments}:
4072 @multitable @columnfractions .15 .70
4073 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4074 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4075                         kind.
4076 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4077                         Returns 0 on success, -1 on end-of-file and a
4078                         system specific positive error code otherwise.
4079 @end multitable
4080
4081 @item @emph{Example}:
4082 @smallexample
4083 PROGRAM test_fgetc
4084   INTEGER :: fd = 42, status
4085   CHARACTER :: c
4086
4087   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4088   DO
4089     CALL fgetc(fd, c, status)
4090     IF (status /= 0) EXIT
4091     call fput(c)
4092   END DO
4093   CLOSE(UNIT=fd)
4094 END PROGRAM
4095 @end smallexample
4096
4097 @item @emph{See also}:
4098 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4099 @end table
4100
4101
4102
4103 @node FLOOR
4104 @section @code{FLOOR} --- Integer floor function
4105 @fnindex FLOOR
4106 @cindex floor
4107 @cindex rounding, floor
4108
4109 @table @asis
4110 @item @emph{Description}:
4111 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4112
4113 @item @emph{Standard}:
4114 Fortran 95 and later
4115
4116 @item @emph{Class}:
4117 Elemental function
4118
4119 @item @emph{Syntax}:
4120 @code{RESULT = FLOOR(A [, KIND])}
4121
4122 @item @emph{Arguments}:
4123 @multitable @columnfractions .15 .70
4124 @item @var{A} @tab The type shall be @code{REAL}.
4125 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4126                       expression indicating the kind parameter of
4127                       the result.
4128 @end multitable
4129
4130 @item @emph{Return value}:
4131 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4132 and of default-kind @code{INTEGER} otherwise.
4133
4134 @item @emph{Example}:
4135 @smallexample
4136 program test_floor
4137     real :: x = 63.29
4138     real :: y = -63.59
4139     print *, floor(x) ! returns 63
4140     print *, floor(y) ! returns -64
4141 end program test_floor
4142 @end smallexample
4143
4144 @item @emph{See also}:
4145 @ref{CEILING}, @ref{NINT}
4146
4147 @end table
4148
4149
4150
4151 @node FLUSH
4152 @section @code{FLUSH} --- Flush I/O unit(s)
4153 @fnindex FLUSH
4154 @cindex file operation, flush
4155
4156 @table @asis
4157 @item @emph{Description}:
4158 Flushes Fortran unit(s) currently open for output. Without the optional
4159 argument, all units are flushed, otherwise just the unit specified.
4160
4161 @item @emph{Standard}:
4162 GNU extension
4163
4164 @item @emph{Class}:
4165 Subroutine
4166
4167 @item @emph{Syntax}:
4168 @code{CALL FLUSH(UNIT)}
4169
4170 @item @emph{Arguments}:
4171 @multitable @columnfractions .15 .70
4172 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4173 @end multitable
4174
4175 @item @emph{Note}:
4176 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4177 statement that should be preferred over the @code{FLUSH} intrinsic.
4178
4179 @end table
4180
4181
4182
4183 @node FNUM
4184 @section @code{FNUM} --- File number function
4185 @fnindex FNUM
4186 @cindex file operation, file number
4187
4188 @table @asis
4189 @item @emph{Description}:
4190 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4191 open Fortran I/O unit @code{UNIT}.
4192
4193 @item @emph{Standard}:
4194 GNU extension
4195
4196 @item @emph{Class}:
4197 Function
4198
4199 @item @emph{Syntax}:
4200 @code{RESULT = FNUM(UNIT)}
4201
4202 @item @emph{Arguments}:
4203 @multitable @columnfractions .15 .70
4204 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4205 @end multitable
4206
4207 @item @emph{Return value}:
4208 The return value is of type @code{INTEGER}
4209
4210 @item @emph{Example}:
4211 @smallexample
4212 program test_fnum
4213   integer :: i
4214   open (unit=10, status = "scratch")
4215   i = fnum(10)
4216   print *, i
4217   close (10)
4218 end program test_fnum
4219 @end smallexample
4220 @end table
4221
4222
4223
4224 @node FPUT
4225 @section @code{FPUT} --- Write a single character in stream mode to stdout
4226 @fnindex FPUT
4227 @cindex write character, stream mode
4228 @cindex stream mode, write character
4229 @cindex file operation, write character
4230
4231 @table @asis
4232 @item @emph{Description}:
4233 Write a single character in stream mode to stdout by bypassing normal
4234 formatted output. Stream I/O should not be mixed with normal record-oriented
4235 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4236
4237 This intrinsic is provided in both subroutine and function forms; however,
4238 only one form can be used in any given program unit.
4239
4240 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4241 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4242 Programmers should consider the use of new stream IO feature in new code
4243 for future portability. See also @ref{Fortran 2003 status}.
4244
4245 @item @emph{Standard}:
4246 GNU extension
4247
4248 @item @emph{Class}:
4249 Subroutine, function
4250
4251 @item @emph{Syntax}:
4252 @code{CALL FPUT(C [, STATUS])}
4253
4254 @item @emph{Arguments}:
4255 @multitable @columnfractions .15 .70
4256 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4257                         kind.
4258 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4259                         Returns 0 on success, -1 on end-of-file and a
4260                         system specific positive error code otherwise.
4261 @end multitable
4262
4263 @item @emph{Example}:
4264 @smallexample
4265 PROGRAM test_fput
4266   CHARACTER(len=10) :: str = "gfortran"
4267   INTEGER :: i
4268   DO i = 1, len_trim(str)
4269     CALL fput(str(i:i))
4270   END DO
4271 END PROGRAM
4272 @end smallexample
4273
4274 @item @emph{See also}:
4275 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4276 @end table
4277
4278
4279
4280 @node FPUTC
4281 @section @code{FPUTC} --- Write a single character in stream mode
4282 @fnindex FPUTC
4283 @cindex write character, stream mode
4284 @cindex stream mode, write character
4285 @cindex file operation, write character
4286
4287 @table @asis
4288 @item @emph{Description}:
4289 Write a single character in stream mode by bypassing normal formatted
4290 output. Stream I/O should not be mixed with normal record-oriented
4291 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4292
4293 This intrinsic is provided in both subroutine and function forms; however,
4294 only one form can be used in any given program unit.
4295
4296 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4297 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4298 Programmers should consider the use of new stream IO feature in new code
4299 for future portability. See also @ref{Fortran 2003 status}.
4300
4301 @item @emph{Standard}:
4302 GNU extension
4303
4304 @item @emph{Class}:
4305 Subroutine, function
4306
4307 @item @emph{Syntax}:
4308 @code{CALL FPUTC(UNIT, C [, STATUS])}
4309
4310 @item @emph{Arguments}:
4311 @multitable @columnfractions .15 .70
4312 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4313 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4314                         kind.
4315 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4316                         Returns 0 on success, -1 on end-of-file and a
4317                         system specific positive error code otherwise.
4318 @end multitable
4319
4320 @item @emph{Example}:
4321 @smallexample
4322 PROGRAM test_fputc
4323   CHARACTER(len=10) :: str = "gfortran"
4324   INTEGER :: fd = 42, i
4325
4326   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4327   DO i = 1, len_trim(str)
4328     CALL fputc(fd, str(i:i))
4329   END DO
4330   CLOSE(fd)
4331 END PROGRAM
4332 @end smallexample
4333
4334 @item @emph{See also}:
4335 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4336 @end table
4337
4338
4339
4340 @node FRACTION
4341 @section @code{FRACTION} --- Fractional part of the model representation
4342 @fnindex FRACTION
4343 @cindex real number, fraction
4344 @cindex floating point, fraction
4345
4346 @table @asis
4347 @item @emph{Description}:
4348 @code{FRACTION(X)} returns the fractional part of the model
4349 representation of @code{X}.
4350
4351 @item @emph{Standard}:
4352 Fortran 95 and later
4353
4354 @item @emph{Class}:
4355 Elemental function
4356
4357 @item @emph{Syntax}:
4358 @code{Y = FRACTION(X)}
4359
4360 @item @emph{Arguments}:
4361 @multitable @columnfractions .15 .70
4362 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4363 @end multitable
4364
4365 @item @emph{Return value}:
4366 The return value is of the same type and kind as the argument.
4367 The fractional part of the model representation of @code{X} is returned;
4368 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4369
4370 @item @emph{Example}:
4371 @smallexample
4372 program test_fraction
4373   real :: x
4374   x = 178.1387e-4
4375   print *, fraction(x), x * radix(x)**(-exponent(x))
4376 end program test_fraction
4377 @end smallexample
4378
4379 @end table
4380
4381
4382
4383 @node FREE
4384 @section @code{FREE} --- Frees memory
4385 @fnindex FREE
4386 @cindex pointer, cray
4387
4388 @table @asis
4389 @item @emph{Description}:
4390 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4391 intrinsic is an extension intended to be used with Cray pointers, and is
4392 provided in GNU Fortran to allow user to compile legacy code. For
4393 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4394 @code{DEALLOCATE}.
4395
4396 @item @emph{Standard}:
4397 GNU extension
4398
4399 @item @emph{Class}:
4400 Subroutine
4401
4402 @item @emph{Syntax}:
4403 @code{CALL FREE(PTR)}
4404
4405 @item @emph{Arguments}:
4406 @multitable @columnfractions .15 .70
4407 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4408 location of the memory that should be de-allocated.
4409 @end multitable
4410
4411 @item @emph{Return value}:
4412 None
4413
4414 @item @emph{Example}:
4415 See @code{MALLOC} for an example.
4416
4417 @item @emph{See also}:
4418 @ref{MALLOC}
4419 @end table
4420
4421
4422
4423 @node FSEEK
4424 @section @code{FSEEK} --- Low level file positioning subroutine
4425 @fnindex FSEEK
4426 @cindex file operation, seek
4427 @cindex file operation, position
4428
4429 @table @asis
4430 @item @emph{Description}:
4431 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4432 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4433 if set to 1, @var{OFFSET} is taken to be relative to the current position
4434 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4435 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4436 fails silently.
4437
4438 This intrinsic routine is not fully backwards compatible with @command{g77}.
4439 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4440 @var{STATUS} variable. If FSEEK is used in old code, change
4441 @smallexample
4442   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4443 @end smallexample
4444 to
4445 @smallexample
4446   INTEGER :: status
4447   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4448   IF (status /= 0) GOTO label
4449 @end smallexample
4450
4451 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4452 Programmers should consider the use of new stream IO feature in new code
4453 for future portability. See also @ref{Fortran 2003 status}.
4454
4455 @item @emph{Standard}:
4456 GNU extension
4457
4458 @item @emph{Class}:
4459 Subroutine
4460
4461 @item @emph{Syntax}:
4462 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4463
4464 @item @emph{Arguments}:
4465 @multitable @columnfractions .15 .70
4466 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
4467 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4468 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4469 Its value shall be either 0, 1 or 2.
4470 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4471 @code{INTEGER(4)}.
4472 @end multitable
4473
4474 @item @emph{Example}:
4475 @smallexample
4476 PROGRAM test_fseek
4477   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4478   INTEGER :: fd, offset, ierr
4479
4480   ierr   = 0
4481   offset = 5
4482   fd     = 10
4483
4484   OPEN(UNIT=fd, FILE="fseek.test")
4485   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
4486   print *, FTELL(fd), ierr
4487
4488   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
4489   print *, FTELL(fd), ierr
4490
4491   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
4492   print *, FTELL(fd), ierr
4493
4494   CLOSE(UNIT=fd)
4495 END PROGRAM
4496 @end smallexample
4497
4498 @item @emph{See also}:
4499 @ref{FTELL}
4500 @end table
4501
4502
4503
4504 @node FSTAT
4505 @section @code{FSTAT} --- Get file status
4506 @fnindex FSTAT
4507 @cindex file system, file status
4508
4509 @table @asis
4510 @item @emph{Description}:
4511 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4512 already opened file is obtained.
4513
4514 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4515
4516 This intrinsic is provided in both subroutine and function forms; however,
4517 only one form can be used in any given program unit.
4518
4519 @item @emph{Standard}:
4520 GNU extension
4521
4522 @item @emph{Class}:
4523 Subroutine, function
4524
4525 @item @emph{Syntax}:
4526 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4527
4528 @item @emph{Arguments}:
4529 @multitable @columnfractions .15 .70
4530 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
4531 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4532 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4533                         on success and a system specific error code otherwise.
4534 @end multitable
4535
4536 @item @emph{Example}:
4537 See @ref{STAT} for an example.
4538
4539 @item @emph{See also}:
4540 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4541 @end table
4542
4543
4544
4545 @node FTELL
4546 @section @code{FTELL} --- Current stream position
4547 @fnindex FTELL
4548 @cindex file operation, position
4549
4550 @table @asis
4551 @item @emph{Description}:
4552 Retrieves the current position within an open file.
4553
4554 This intrinsic is provided in both subroutine and function forms; however,
4555 only one form can be used in any given program unit.
4556
4557 @item @emph{Standard}:
4558 GNU extension
4559
4560 @item @emph{Class}:
4561 Subroutine, function
4562
4563 @item @emph{Syntax}:
4564 @multitable @columnfractions .80
4565 @item @code{CALL FTELL(UNIT, OFFSET)}
4566 @item @code{OFFSET = FTELL(UNIT)}
4567 @end multitable
4568
4569 @item @emph{Arguments}:
4570 @multitable @columnfractions .15 .70
4571 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
4572 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
4573 @end multitable
4574
4575 @item @emph{Return value}:
4576 In either syntax, @var{OFFSET} is set to the current offset of unit
4577 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4578
4579 @item @emph{Example}:
4580 @smallexample
4581 PROGRAM test_ftell
4582   INTEGER :: i
4583   OPEN(10, FILE="temp.dat")
4584   CALL ftell(10,i)
4585   WRITE(*,*) i
4586 END PROGRAM
4587 @end smallexample
4588
4589 @item @emph{See also}:
4590 @ref{FSEEK}
4591 @end table
4592
4593
4594
4595 @node GAMMA
4596 @section @code{GAMMA} --- Gamma function
4597 @fnindex GAMMA
4598 @fnindex DGAMMA
4599 @cindex Gamma function
4600 @cindex Factorial function
4601
4602 @table @asis
4603 @item @emph{Description}:
4604 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4605 integer values of @var{X} the Gamma function simplifies to the factorial
4606 function @math{\Gamma(x)=(x-1)!}.
4607
4608 @tex
4609 $$
4610 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4611 $$
4612 @end tex
4613
4614 @item @emph{Standard}:
4615 Fortran 2008 and later
4616
4617 @item @emph{Class}:
4618 Elemental function
4619
4620 @item @emph{Syntax}:
4621 @code{X = GAMMA(X)}
4622
4623 @item @emph{Arguments}:
4624 @multitable @columnfractions .15 .70
4625 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4626 nor a negative integer.
4627 @end multitable
4628
4629 @item @emph{Return value}:
4630 The return value is of type @code{REAL} of the same kind as @var{X}.
4631
4632 @item @emph{Example}:
4633 @smallexample
4634 program test_gamma
4635   real :: x = 1.0
4636   x = gamma(x) ! returns 1.0
4637 end program test_gamma
4638 @end smallexample
4639
4640 @item @emph{Specific names}:
4641 @multitable @columnfractions .20 .20 .20 .25
4642 @item Name             @tab Argument         @tab Return type       @tab Standard
4643 @item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
4644 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
4645 @end multitable
4646
4647 @item @emph{See also}:
4648 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4649
4650 @end table
4651
4652
4653
4654 @node GERROR
4655 @section @code{GERROR} --- Get last system error message
4656 @fnindex GERROR
4657 @cindex system, error handling
4658
4659 @table @asis
4660 @item @emph{Description}:
4661 Returns the system error message corresponding to the last system error.
4662 This resembles the functionality of @code{strerror(3)} in C.
4663
4664 @item @emph{Standard}:
4665 GNU extension
4666
4667 @item @emph{Class}:
4668 Subroutine
4669
4670 @item @emph{Syntax}:
4671 @code{CALL GERROR(RESULT)}
4672
4673 @item @emph{Arguments}:
4674 @multitable @columnfractions .15 .70
4675 @item @var{RESULT}  @tab Shall of type @code{CHARACTER} and of default
4676 @end multitable
4677
4678 @item @emph{Example}:
4679 @smallexample
4680 PROGRAM test_gerror
4681   CHARACTER(len=100) :: msg
4682   CALL gerror(msg)
4683   WRITE(*,*) msg
4684 END PROGRAM
4685 @end smallexample
4686
4687 @item @emph{See also}:
4688 @ref{IERRNO}, @ref{PERROR}
4689 @end table
4690
4691
4692
4693 @node GETARG
4694 @section @code{GETARG} --- Get command line arguments
4695 @fnindex GETARG
4696 @cindex command-line arguments
4697 @cindex arguments, to program
4698
4699 @table @asis
4700 @item @emph{Description}:
4701 Retrieve the @var{POS}-th argument that was passed on the
4702 command line when the containing program was invoked.
4703
4704 This intrinsic routine is provided for backwards compatibility with
4705 GNU Fortran 77.  In new code, programmers should consider the use of
4706 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4707 standard.
4708
4709 @item @emph{Standard}:
4710 GNU extension
4711
4712 @item @emph{Class}:
4713 Subroutine
4714
4715 @item @emph{Syntax}:
4716 @code{CALL GETARG(POS, VALUE)}
4717
4718 @item @emph{Arguments}:
4719 @multitable @columnfractions .15 .70
4720 @item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
4721 the default integer kind; @math{@var{POS} \geq 0}
4722 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4723 kind.
4724 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4725 @end multitable
4726
4727 @item @emph{Return value}:
4728 After @code{GETARG} returns, the @var{VALUE} argument holds the
4729 @var{POS}th command line argument. If @var{VALUE} can not hold the
4730 argument, it is truncated to fit the length of @var{VALUE}. If there are
4731 less than @var{POS} arguments specified at the command line, @var{VALUE}
4732 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4733 to the name of the program (on systems that support this feature).
4734
4735 @item @emph{Example}:
4736 @smallexample
4737 PROGRAM test_getarg
4738   INTEGER :: i
4739   CHARACTER(len=32) :: arg
4740
4741   DO i = 1, iargc()
4742     CALL getarg(i, arg)
4743     WRITE (*,*) arg
4744   END DO
4745 END PROGRAM
4746 @end smallexample
4747
4748 @item @emph{See also}:
4749 GNU Fortran 77 compatibility function: @ref{IARGC}
4750
4751 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4752 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4753 @end table
4754
4755
4756
4757 @node GET_COMMAND
4758 @section @code{GET_COMMAND} --- Get the entire command line
4759 @fnindex GET_COMMAND
4760 @cindex command-line arguments
4761 @cindex arguments, to program
4762
4763 @table @asis
4764 @item @emph{Description}:
4765 Retrieve the entire command line that was used to invoke the program.
4766
4767 @item @emph{Standard}:
4768 Fortran 2003 and later
4769
4770 @item @emph{Class}:
4771 Subroutine
4772
4773 @item @emph{Syntax}:
4774 @code{CALL GET_COMMAND(COMMAND)}
4775
4776 @item @emph{Arguments}:
4777 @multitable @columnfractions .15 .70
4778 @item @var{COMMAND} @tab Shall be of type @code{CHARACTER} and of default
4779 kind.
4780 @end multitable
4781
4782 @item @emph{Return value}:
4783 Stores the entire command line that was used to invoke the program in
4784 @var{COMMAND}. If @var{COMMAND} is not large enough, the command will be
4785 truncated.
4786
4787 @item @emph{Example}:
4788 @smallexample
4789 PROGRAM test_get_command
4790   CHARACTER(len=255) :: cmd
4791   CALL get_command(cmd)
4792   WRITE (*,*) TRIM(cmd)
4793 END PROGRAM
4794 @end smallexample
4795
4796 @item @emph{See also}:
4797 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4798 @end table
4799
4800
4801
4802 @node GET_COMMAND_ARGUMENT
4803 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4804 @fnindex GET_COMMAND_ARGUMENT
4805 @cindex command-line arguments
4806 @cindex arguments, to program
4807
4808 @table @asis
4809 @item @emph{Description}:
4810 Retrieve the @var{NUMBER}-th argument that was passed on the
4811 command line when the containing program was invoked.
4812
4813 @item @emph{Standard}:
4814 Fortran 2003 and later
4815
4816 @item @emph{Class}:
4817 Subroutine
4818
4819 @item @emph{Syntax}:
4820 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4821
4822 @item @emph{Arguments}:
4823 @multitable @columnfractions .15 .70
4824 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER(4)},
4825                         @math{@var{NUMBER} \geq 0}
4826 @item @var{VALUE}  @tab Shall be a scalar of type @code{CHARACTER}
4827                         and of default kind.
4828 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
4829 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
4830 @end multitable
4831
4832 @item @emph{Return value}:
4833 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4834 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4835 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4836 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4837 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on systems
4838 that support this feature). The @var{LENGTH} argument contains the length of the
4839 @var{NUMBER}-th command line argument. If the argument retrival fails, @var{STATUS}
4840 is a positiv number; if @var{VALUE} contains a truncated command line argument,
4841 @var{STATUS} is -1; and otherwise the @var{STATUS} is zero.
4842
4843 @item @emph{Example}:
4844 @smallexample
4845 PROGRAM test_get_command_argument
4846   INTEGER :: i
4847   CHARACTER(len=32) :: arg
4848
4849   i = 0
4850   DO
4851     CALL get_command_argument(i, arg)
4852     IF (LEN_TRIM(arg) == 0) EXIT
4853
4854     WRITE (*,*) TRIM(arg)
4855     i = i+1
4856   END DO
4857 END PROGRAM
4858 @end smallexample
4859
4860 @item @emph{See also}:
4861 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4862 @end table
4863
4864
4865
4866 @node GETCWD
4867 @section @code{GETCWD} --- Get current working directory
4868 @fnindex GETCWD
4869 @cindex system, working directory
4870
4871 @table @asis
4872 @item @emph{Description}:
4873 Get current working directory.
4874
4875 This intrinsic is provided in both subroutine and function forms; however,
4876 only one form can be used in any given program unit.
4877
4878 @item @emph{Standard}:
4879 GNU extension
4880
4881 @item @emph{Class}:
4882 Subroutine, function
4883
4884 @item @emph{Syntax}:
4885 @code{CALL GETCWD(C [, STATUS])}
4886
4887 @item @emph{Arguments}:
4888 @multitable @columnfractions .15 .70
4889 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4890 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4891                         a system specific and nonzero error code otherwise.
4892 @end multitable
4893
4894 @item @emph{Example}:
4895 @smallexample
4896 PROGRAM test_getcwd
4897   CHARACTER(len=255) :: cwd
4898   CALL getcwd(cwd)
4899   WRITE(*,*) TRIM(cwd)
4900 END PROGRAM
4901 @end smallexample
4902
4903 @item @emph{See also}:
4904 @ref{CHDIR}
4905 @end table
4906
4907
4908
4909 @node GETENV
4910 @section @code{GETENV} --- Get an environmental variable
4911 @fnindex GETENV
4912 @cindex environment variable
4913
4914 @table @asis
4915 @item @emph{Description}:
4916 Get the @var{VALUE} of the environmental variable @var{NAME}.
4917
4918 This intrinsic routine is provided for backwards compatibility with
4919 GNU Fortran 77.  In new code, programmers should consider the use of
4920 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4921 2003 standard.
4922
4923 @item @emph{Standard}:
4924 GNU extension
4925
4926 @item @emph{Class}:
4927 Subroutine
4928
4929 @item @emph{Syntax}:
4930 @code{CALL GETENV(NAME, VALUE)}
4931
4932 @item @emph{Arguments}:
4933 @multitable @columnfractions .15 .70
4934 @item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
4935 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
4936 @end multitable
4937
4938 @item @emph{Return value}:
4939 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
4940 not large enough to hold the data, it is truncated. If @var{NAME}
4941 is not set, @var{VALUE} will be filled with blanks.
4942
4943 @item @emph{Example}:
4944 @smallexample
4945 PROGRAM test_getenv
4946   CHARACTER(len=255) :: homedir
4947   CALL getenv("HOME", homedir)
4948   WRITE (*,*) TRIM(homedir)
4949 END PROGRAM
4950 @end smallexample
4951
4952 @item @emph{See also}:
4953 @ref{GET_ENVIRONMENT_VARIABLE}
4954 @end table
4955
4956
4957
4958 @node GET_ENVIRONMENT_VARIABLE
4959 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4960 @fnindex GET_ENVIRONMENT_VARIABLE
4961 @cindex environment variable
4962
4963 @table @asis
4964 @item @emph{Description}:
4965 Get the @var{VALUE} of the environmental variable @var{NAME}.
4966
4967 @item @emph{Standard}:
4968 Fortran 2003 and later
4969
4970 @item @emph{Class}:
4971 Subroutine
4972
4973 @item @emph{Syntax}:
4974 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
4975
4976 @item @emph{Arguments}:
4977 @multitable @columnfractions .15 .70
4978 @item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER(1)}.
4979 @item @var{VALUE}     @tab Shall be a scalar of type @code{CHARACTER(1)}.
4980 @item @var{LENGTH}    @tab Shall be a scalar of type @code{INTEGER(4)}.
4981 @item @var{STATUS}    @tab Shall be a scalar of type @code{INTEGER(4)}.
4982 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL(4)}.
4983 @end multitable
4984
4985 @item @emph{Return value}:
4986 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
4987 not large enough to hold the data, it is truncated. If @var{NAME}
4988 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
4989 contains the length needed for storing the environment variable @var{NAME}
4990 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
4991 but too short for the environment variable; it is 1 if the environment
4992 variable does not exist and 2 if the processor does not support environment
4993 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
4994 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
4995 are significant; otherwise they are not part of the environment variable
4996 name.
4997
4998 @item @emph{Example}:
4999 @smallexample
5000 PROGRAM test_getenv
5001   CHARACTER(len=255) :: homedir
5002   CALL get_environment_variable("HOME", homedir)
5003   WRITE (*,*) TRIM(homedir)
5004 END PROGRAM
5005 @end smallexample
5006 @end table
5007
5008
5009
5010 @node GETGID
5011 @section @code{GETGID} --- Group ID function
5012 @fnindex GETGID
5013 @cindex system, group id
5014
5015 @table @asis
5016 @item @emph{Description}:
5017 Returns the numerical group ID of the current process.
5018
5019 @item @emph{Standard}:
5020 GNU extension
5021
5022 @item @emph{Class}:
5023 Function
5024
5025 @item @emph{Syntax}:
5026 @code{RESULT = GETGID()}
5027
5028 @item @emph{Return value}:
5029 The return value of @code{GETGID} is an @code{INTEGER} of the default
5030 kind.
5031
5032
5033 @item @emph{Example}:
5034 See @code{GETPID} for an example.
5035
5036 @item @emph{See also}:
5037 @ref{GETPID}, @ref{GETUID}
5038 @end table
5039
5040
5041
5042 @node GETLOG
5043 @section @code{GETLOG} --- Get login name
5044 @fnindex GETLOG
5045 @cindex system, login name
5046 @cindex login name
5047
5048 @table @asis
5049 @item @emph{Description}:
5050 Gets the username under which the program is running.
5051
5052 @item @emph{Standard}:
5053 GNU extension
5054
5055 @item @emph{Class}:
5056 Subroutine
5057
5058 @item @emph{Syntax}:
5059 @code{CALL GETLOG(C)}
5060
5061 @item @emph{Arguments}:
5062 @multitable @columnfractions .15 .70
5063 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5064 @end multitable
5065
5066 @item @emph{Return value}:
5067 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5068 functions @code{geteuid} and @code{getpwuid} are not available, and
5069 the @code{getlogin} function is not implemented either, this will
5070 return a blank string.)
5071
5072 @item @emph{Example}:
5073 @smallexample
5074 PROGRAM TEST_GETLOG
5075   CHARACTER(32) :: login
5076   CALL GETLOG(login)
5077   WRITE(*,*) login
5078 END PROGRAM
5079 @end smallexample
5080
5081 @item @emph{See also}:
5082 @ref{GETUID}
5083 @end table
5084
5085
5086
5087 @node GETPID
5088 @section @code{GETPID} --- Process ID function
5089 @fnindex GETPID
5090 @cindex system, process id
5091 @cindex process id
5092
5093 @table @asis
5094 @item @emph{Description}:
5095 Returns the numerical process identifier of the current process.
5096
5097 @item @emph{Standard}:
5098 GNU extension
5099
5100 @item @emph{Class}:
5101 Function
5102
5103 @item @emph{Syntax}:
5104 @code{RESULT = GETPID()}
5105
5106 @item @emph{Return value}:
5107 The return value of @code{GETPID} is an @code{INTEGER} of the default
5108 kind.
5109
5110
5111 @item @emph{Example}:
5112 @smallexample
5113 program info
5114   print *, "The current process ID is ", getpid()
5115   print *, "Your numerical user ID is ", getuid()
5116   print *, "Your numerical group ID is ", getgid()
5117 end program info
5118 @end smallexample
5119
5120 @item @emph{See also}:
5121 @ref{GETGID}, @ref{GETUID}
5122 @end table
5123
5124
5125
5126 @node GETUID
5127 @section @code{GETUID} --- User ID function
5128 @fnindex GETUID
5129 @cindex system, user id
5130 @cindex user id
5131
5132 @table @asis
5133 @item @emph{Description}:
5134 Returns the numerical user ID of the current process.
5135
5136 @item @emph{Standard}:
5137 GNU extension
5138
5139 @item @emph{Class}:
5140 Function
5141
5142 @item @emph{Syntax}:
5143 @code{RESULT = GETUID()}
5144
5145 @item @emph{Return value}:
5146 The return value of @code{GETUID} is an @code{INTEGER} of the default
5147 kind.
5148
5149
5150 @item @emph{Example}:
5151 See @code{GETPID} for an example.
5152
5153 @item @emph{See also}:
5154 @ref{GETPID}, @ref{GETLOG}
5155 @end table
5156
5157
5158
5159 @node GMTIME
5160 @section @code{GMTIME} --- Convert time to GMT info
5161 @fnindex GMTIME
5162 @cindex time, conversion to GMT info
5163
5164 @table @asis
5165 @item @emph{Description}:
5166 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5167 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5168 to the UTC time zone (Universal Coordinated Time, also known in some
5169 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5170
5171 @item @emph{Standard}:
5172 GNU extension
5173
5174 @item @emph{Class}:
5175 Subroutine
5176
5177 @item @emph{Syntax}:
5178 @code{CALL GMTIME(TIME, VALUES)}
5179
5180 @item @emph{Arguments}:
5181 @multitable @columnfractions .15 .70
5182 @item @var{TIME}   @tab An @code{INTEGER} scalar expression
5183                         corresponding to a system time, with
5184                         @code{INTENT(IN)}.
5185 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5186                         with @code{INTENT(OUT)}.
5187 @end multitable
5188
5189 @item @emph{Return value}:
5190 The elements of @var{VALUES} are assigned as follows:
5191 @enumerate
5192 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5193       seconds
5194 @item Minutes after the hour, range 0--59
5195 @item Hours past midnight, range 0--23
5196 @item Day of month, range 0--31
5197 @item Number of months since January, range 0--12
5198 @item Years since 1900
5199 @item Number of days since Sunday, range 0--6
5200 @item Days since January 1
5201 @item Daylight savings indicator: positive if daylight savings is in
5202       effect, zero if not, and negative if the information is not
5203       available.
5204 @end enumerate
5205
5206 @item @emph{See also}:
5207 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5208
5209 @end table
5210
5211
5212
5213 @node HOSTNM
5214 @section @code{HOSTNM} --- Get system host name
5215 @fnindex HOSTNM
5216 @cindex system, host name
5217
5218 @table @asis
5219 @item @emph{Description}:
5220 Retrieves the host name of the system on which the program is running.
5221
5222 This intrinsic is provided in both subroutine and function forms; however,
5223 only one form can be used in any given program unit.
5224
5225 @item @emph{Standard}:
5226 GNU extension
5227
5228 @item @emph{Class}:
5229 Subroutine, function
5230
5231 @item @emph{Syntax}:
5232 @multitable @columnfractions .80
5233 @item @code{CALL HOSTNM(C [, STATUS])}
5234 @item @code{STATUS = HOSTNM(NAME)}
5235 @end multitable
5236
5237 @item @emph{Arguments}:
5238 @multitable @columnfractions .15 .70
5239 @item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
5240 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5241                          Returns 0 on success, or a system specific error
5242                          code otherwise.
5243 @end multitable
5244
5245 @item @emph{Return value}:
5246 In either syntax, @var{NAME} is set to the current hostname if it can
5247 be obtained, or to a blank string otherwise.
5248
5249 @end table
5250
5251
5252
5253 @node HUGE
5254 @section @code{HUGE} --- Largest number of a kind
5255 @fnindex HUGE
5256 @cindex limits, largest number
5257 @cindex model representation, largest number
5258
5259 @table @asis
5260 @item @emph{Description}:
5261 @code{HUGE(X)} returns the largest number that is not an infinity in
5262 the model of the type of @code{X}.
5263
5264 @item @emph{Standard}:
5265 Fortran 95 and later
5266
5267 @item @emph{Class}:
5268 Inquiry function
5269
5270 @item @emph{Syntax}:
5271 @code{RESULT = HUGE(X)}
5272
5273 @item @emph{Arguments}:
5274 @multitable @columnfractions .15 .70
5275 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5276 @end multitable
5277
5278 @item @emph{Return value}:
5279 The return value is of the same type and kind as @var{X}
5280
5281 @item @emph{Example}:
5282 @smallexample
5283 program test_huge_tiny
5284   print *, huge(0), huge(0.0), huge(0.0d0)
5285   print *, tiny(0.0), tiny(0.0d0)
5286 end program test_huge_tiny
5287 @end smallexample
5288 @end table
5289
5290
5291
5292 @node HYPOT
5293 @section @code{HYPOT} --- Euclidean distance function
5294 @fnindex HYPOT
5295 @cindex Euclidean distance
5296
5297 @table @asis
5298 @item @emph{Description}:
5299 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5300 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5301
5302 @item @emph{Standard}:
5303 Fortran 2008 and later
5304
5305 @item @emph{Class}:
5306 Elemental function
5307
5308 @item @emph{Syntax}:
5309 @code{RESULT = HYPOT(X, Y)}
5310
5311 @item @emph{Arguments}:
5312 @multitable @columnfractions .15 .70
5313 @item @var{X} @tab The type shall be @code{REAL}.
5314 @item @var{Y} @tab The type and kind type parameter shall be the same as
5315 @var{X}.
5316 @end multitable
5317
5318 @item @emph{Return value}:
5319 The return value has the same type and kind type parameter as @var{X}.
5320
5321 @item @emph{Example}:
5322 @smallexample
5323 program test_hypot
5324   real(4) :: x = 1.e0_4, y = 0.5e0_4
5325   x = hypot(x,y)
5326 end program test_hypot
5327 @end smallexample
5328 @end table
5329
5330
5331
5332 @node IACHAR
5333 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5334 @fnindex IACHAR
5335 @cindex @acronym{ASCII} collating sequence
5336 @cindex collating sequence, @acronym{ASCII}
5337 @cindex conversion, to integer
5338
5339 @table @asis
5340 @item @emph{Description}:
5341 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5342 in the first character position of @code{C}.
5343
5344 @item @emph{Standard}:
5345 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5346
5347 @item @emph{Class}:
5348 Elemental function
5349
5350 @item @emph{Syntax}:
5351 @code{RESULT = IACHAR(C [, KIND])}
5352
5353 @item @emph{Arguments}:
5354 @multitable @columnfractions .15 .70
5355 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5356 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5357                       expression indicating the kind parameter of
5358                       the result.
5359 @end multitable
5360
5361 @item @emph{Return value}:
5362 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5363 @var{KIND} is absent, the return value is of default integer kind.
5364
5365 @item @emph{Example}:
5366 @smallexample
5367 program test_iachar
5368   integer i
5369   i = iachar(' ')
5370 end program test_iachar
5371 @end smallexample
5372
5373 @item @emph{Note}:
5374 See @ref{ICHAR} for a discussion of converting between numerical values
5375 and formatted string representations.
5376
5377 @item @emph{See also}:
5378 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5379
5380 @end table
5381
5382
5383
5384 @node IAND
5385 @section @code{IAND} --- Bitwise logical and
5386 @fnindex IAND
5387 @cindex bitwise logical and
5388 @cindex logical and, bitwise
5389
5390 @table @asis
5391 @item @emph{Description}:
5392 Bitwise logical @code{AND}.
5393
5394 @item @emph{Standard}:
5395 Fortran 95 and later
5396
5397 @item @emph{Class}:
5398 Elemental function
5399
5400 @item @emph{Syntax}:
5401 @code{RESULT = IAND(I, J)}
5402
5403 @item @emph{Arguments}:
5404 @multitable @columnfractions .15 .70
5405 @item @var{I} @tab The type shall be @code{INTEGER}.
5406 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5407 kind as @var{I}.  (As a GNU extension, different kinds are also
5408 permitted.)
5409 @end multitable
5410
5411 @item @emph{Return value}:
5412 The return type is @code{INTEGER}, of the same kind as the
5413 arguments.  (If the argument kinds differ, it is of the same kind as
5414 the larger argument.)
5415
5416 @item @emph{Example}:
5417 @smallexample
5418 PROGRAM test_iand
5419   INTEGER :: a, b
5420   DATA a / Z'F' /, b / Z'3' /
5421   WRITE (*,*) IAND(a, b)
5422 END PROGRAM
5423 @end smallexample
5424
5425 @item @emph{See also}:
5426 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5427
5428 @end table
5429
5430
5431
5432 @node IARGC
5433 @section @code{IARGC} --- Get the number of command line arguments
5434 @fnindex IARGC
5435 @cindex command-line arguments
5436 @cindex command-line arguments, number of
5437 @cindex arguments, to program
5438
5439 @table @asis
5440 @item @emph{Description}:
5441 @code{IARGC()} returns the number of arguments passed on the
5442 command line when the containing program was invoked.
5443
5444 This intrinsic routine is provided for backwards compatibility with
5445 GNU Fortran 77.  In new code, programmers should consider the use of
5446 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5447 standard.
5448
5449 @item @emph{Standard}:
5450 GNU extension
5451
5452 @item @emph{Class}:
5453 Function
5454
5455 @item @emph{Syntax}:
5456 @code{RESULT = IARGC()}
5457
5458 @item @emph{Arguments}:
5459 None.
5460
5461 @item @emph{Return value}:
5462 The number of command line arguments, type @code{INTEGER(4)}.
5463
5464 @item @emph{Example}:
5465 See @ref{GETARG}
5466
5467 @item @emph{See also}:
5468 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5469
5470 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5471 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5472 @end table
5473
5474
5475
5476 @node IBCLR
5477 @section @code{IBCLR} --- Clear bit
5478 @fnindex IBCLR
5479 @cindex bits, unset
5480 @cindex bits, clear
5481
5482 @table @asis
5483 @item @emph{Description}:
5484 @code{IBCLR} returns the value of @var{I} with the bit at position
5485 @var{POS} set to zero.
5486
5487 @item @emph{Standard}:
5488 Fortran 95 and later
5489
5490 @item @emph{Class}:
5491 Elemental function
5492
5493 @item @emph{Syntax}:
5494 @code{RESULT = IBCLR(I, POS)}
5495
5496 @item @emph{Arguments}:
5497 @multitable @columnfractions .15 .70
5498 @item @var{I} @tab The type shall be @code{INTEGER}.
5499 @item @var{POS} @tab The type shall be @code{INTEGER}.
5500 @end multitable
5501
5502 @item @emph{Return value}:
5503 The return value is of type @code{INTEGER} and of the same kind as
5504 @var{I}.
5505
5506 @item @emph{See also}:
5507 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5508
5509 @end table
5510
5511
5512
5513 @node IBITS
5514 @section @code{IBITS} --- Bit extraction
5515 @fnindex IBITS
5516 @cindex bits, get
5517 @cindex bits, extract
5518
5519 @table @asis
5520 @item @emph{Description}:
5521 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5522 starting from bit position @var{POS} and extending left for @var{LEN}
5523 bits.  The result is right-justified and the remaining bits are
5524 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
5525 value @code{BIT_SIZE(I)}.
5526
5527 @item @emph{Standard}:
5528 Fortran 95 and later
5529
5530 @item @emph{Class}:
5531 Elemental function
5532
5533 @item @emph{Syntax}:
5534 @code{RESULT = IBITS(I, POS, LEN)}
5535
5536 @item @emph{Arguments}:
5537 @multitable @columnfractions .15 .70
5538 @item @var{I}   @tab The type shall be @code{INTEGER}.
5539 @item @var{POS} @tab The type shall be @code{INTEGER}.
5540 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5541 @end multitable
5542
5543 @item @emph{Return value}:
5544 The return value is of type @code{INTEGER} and of the same kind as
5545 @var{I}.
5546
5547 @item @emph{See also}:
5548 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5549 @end table
5550
5551
5552
5553 @node IBSET
5554 @section @code{IBSET} --- Set bit
5555 @fnindex IBSET
5556 @cindex bits, set
5557
5558 @table @asis
5559 @item @emph{Description}:
5560 @code{IBSET} returns the value of @var{I} with the bit at position
5561 @var{POS} set to one.
5562
5563 @item @emph{Standard}:
5564 Fortran 95 and later
5565
5566 @item @emph{Class}:
5567 Elemental function
5568
5569 @item @emph{Syntax}:
5570 @code{RESULT = IBSET(I, POS)}
5571
5572 @item @emph{Arguments}:
5573 @multitable @columnfractions .15 .70
5574 @item @var{I} @tab The type shall be @code{INTEGER}.
5575 @item @var{POS} @tab The type shall be @code{INTEGER}.
5576 @end multitable
5577
5578 @item @emph{Return value}:
5579 The return value is of type @code{INTEGER} and of the same kind as
5580 @var{I}.
5581
5582 @item @emph{See also}:
5583 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5584
5585 @end table
5586
5587
5588
5589 @node ICHAR
5590 @section @code{ICHAR} --- Character-to-integer conversion function
5591 @fnindex ICHAR
5592 @cindex conversion, to integer
5593
5594 @table @asis
5595 @item @emph{Description}:
5596 @code{ICHAR(C)} returns the code for the character in the first character
5597 position of @code{C} in the system's native character set.
5598 The correspondence between characters and their codes is not necessarily
5599 the same across different GNU Fortran implementations.
5600
5601 @item @emph{Standard}:
5602 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5603
5604 @item @emph{Class}:
5605 Elemental function
5606
5607 @item @emph{Syntax}:
5608 @code{RESULT = ICHAR(C [, KIND])}
5609
5610 @item @emph{Arguments}:
5611 @multitable @columnfractions .15 .70
5612 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5613 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5614                       expression indicating the kind parameter of
5615                       the result.
5616 @end multitable
5617
5618 @item @emph{Return value}:
5619 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5620 @var{KIND} is absent, the return value is of default integer kind.
5621
5622 @item @emph{Example}:
5623 @smallexample
5624 program test_ichar
5625   integer i
5626   i = ichar(' ')
5627 end program test_ichar
5628 @end smallexample
5629
5630 @item @emph{Note}:
5631 No intrinsic exists to convert between a numeric value and a formatted
5632 character string representation -- for instance, given the
5633 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5634 @code{REAL} value with the value 154, or vice versa. Instead, this
5635 functionality is provided by internal-file I/O, as in the following
5636 example:
5637 @smallexample
5638 program read_val
5639   integer value
5640   character(len=10) string, string2
5641   string = '154'
5642
5643   ! Convert a string to a numeric value
5644   read (string,'(I10)') value
5645   print *, value
5646
5647   ! Convert a value to a formatted string
5648   write (string2,'(I10)') value
5649   print *, string2
5650 end program read_val
5651 @end smallexample
5652
5653 @item @emph{See also}:
5654 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5655
5656 @end table
5657
5658
5659
5660 @node IDATE
5661 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5662 @fnindex IDATE
5663 @cindex date, current
5664 @cindex current date
5665
5666 @table @asis
5667 @item @emph{Description}:
5668 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5669 current local time. The day (in the range 1-31), month (in the range 1-12),
5670 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5671 The year has four significant digits.
5672
5673 @item @emph{Standard}:
5674 GNU extension
5675
5676 @item @emph{Class}:
5677 Subroutine
5678
5679 @item @emph{Syntax}:
5680 @code{CALL IDATE(VALUES)}
5681
5682 @item @emph{Arguments}:
5683 @multitable @columnfractions .15 .70
5684 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5685 the kind shall be the default integer kind.
5686 @end multitable
5687
5688 @item @emph{Return value}:
5689 Does not return.
5690
5691 @item @emph{Example}:
5692 @smallexample
5693 program test_idate
5694   integer, dimension(3) :: tarray
5695   call idate(tarray)
5696   print *, tarray(1)
5697   print *, tarray(2)
5698   print *, tarray(3)
5699 end program test_idate
5700 @end smallexample
5701 @end table
5702
5703
5704
5705 @node IEOR
5706 @section @code{IEOR} --- Bitwise logical exclusive or
5707 @fnindex IEOR
5708 @cindex bitwise logical exclusive or
5709 @cindex logical exclusive or, bitwise
5710
5711 @table @asis
5712 @item @emph{Description}:
5713 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5714 @var{J}.
5715
5716 @item @emph{Standard}:
5717 Fortran 95 and later
5718
5719 @item @emph{Class}:
5720 Elemental function
5721
5722 @item @emph{Syntax}:
5723 @code{RESULT = IEOR(I, J)}
5724
5725 @item @emph{Arguments}:
5726 @multitable @columnfractions .15 .70
5727 @item @var{I} @tab The type shall be @code{INTEGER}.
5728 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5729 kind as @var{I}.  (As a GNU extension, different kinds are also
5730 permitted.)
5731 @end multitable
5732
5733 @item @emph{Return value}:
5734 The return type is @code{INTEGER}, of the same kind as the
5735 arguments.  (If the argument kinds differ, it is of the same kind as
5736 the larger argument.)
5737
5738 @item @emph{See also}:
5739 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5740 @end table
5741
5742
5743
5744 @node IERRNO
5745 @section @code{IERRNO} --- Get the last system error number
5746 @fnindex IERRNO
5747 @cindex system, error handling
5748
5749 @table @asis
5750 @item @emph{Description}:
5751 Returns the last system error number, as given by the C @code{errno()}
5752 function.
5753
5754 @item @emph{Standard}:
5755 GNU extension
5756
5757 @item @emph{Class}:
5758 Function
5759
5760 @item @emph{Syntax}:
5761 @code{RESULT = IERRNO()}
5762
5763 @item @emph{Arguments}:
5764 None.
5765
5766 @item @emph{Return value}:
5767 The return value is of type @code{INTEGER} and of the default integer
5768 kind.
5769
5770 @item @emph{See also}:
5771 @ref{PERROR}
5772 @end table
5773
5774
5775
5776 @node INDEX intrinsic
5777 @section @code{INDEX} --- Position of a substring within a string
5778 @fnindex INDEX
5779 @cindex substring position
5780 @cindex string, find substring
5781
5782 @table @asis
5783 @item @emph{Description}:
5784 Returns the position of the start of the first occurrence of string
5785 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
5786 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
5787 the @var{BACK} argument is present and true, the return value is the
5788 start of the last occurrence rather than the first.
5789
5790 @item @emph{Standard}:
5791 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5792
5793 @item @emph{Class}:
5794 Elemental function
5795
5796 @item @emph{Syntax}:
5797 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5798
5799 @item @emph{Arguments}:
5800 @multitable @columnfractions .15 .70
5801 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5802 @code{INTENT(IN)}
5803 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5804 @code{INTENT(IN)}
5805 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5806 @code{INTENT(IN)}
5807 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5808                       expression indicating the kind parameter of
5809                       the result.
5810 @end multitable
5811
5812 @item @emph{Return value}:
5813 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5814 @var{KIND} is absent, the return value is of default integer kind.
5815
5816 @item @emph{See also}:
5817 @ref{SCAN}, @ref{VERIFY}
5818 @end table
5819
5820
5821
5822 @node INT
5823 @section @code{INT} --- Convert to integer type
5824 @fnindex INT
5825 @fnindex IFIX
5826 @fnindex IDINT
5827 @cindex conversion, to integer
5828
5829 @table @asis
5830 @item @emph{Description}:
5831 Convert to integer type
5832
5833 @item @emph{Standard}:
5834 Fortran 77 and later
5835
5836 @item @emph{Class}:
5837 Elemental function
5838
5839 @item @emph{Syntax}:
5840 @code{RESULT = INT(A [, KIND))}
5841
5842 @item @emph{Arguments}:
5843 @multitable @columnfractions .15 .70
5844 @item @var{A}    @tab Shall be of type @code{INTEGER},
5845                       @code{REAL}, or @code{COMPLEX}.
5846 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5847                       expression indicating the kind parameter of
5848                       the result.
5849 @end multitable
5850
5851 @item @emph{Return value}:
5852 These functions return a @code{INTEGER} variable or array under
5853 the following rules:
5854
5855 @table @asis
5856 @item (A)
5857 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5858 @item (B)
5859 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5860 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5861 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5862 @item (C)
5863 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5864 @end table
5865
5866 @item @emph{Example}:
5867 @smallexample
5868 program test_int
5869   integer :: i = 42
5870   complex :: z = (-3.7, 1.0)
5871   print *, int(i)
5872   print *, int(z), int(z,8)
5873 end program
5874 @end smallexample
5875
5876 @item @emph{Specific names}:
5877 @multitable @columnfractions .20 .20 .20 .25
5878 @item Name             @tab Argument            @tab Return type       @tab Standard
5879 @item @code{IFIX(A)}   @tab @code{REAL(4) A}    @tab @code{INTEGER}    @tab Fortran 77 and later
5880 @item @code{IDINT(A)}  @tab @code{REAL(8) A}    @tab @code{INTEGER}    @tab Fortran 77 and later
5881 @end multitable
5882
5883 @end table
5884
5885
5886
5887 @node INT2
5888 @section @code{INT2} --- Convert to 16-bit integer type
5889 @fnindex INT2
5890 @fnindex SHORT
5891 @cindex conversion, to integer
5892
5893 @table @asis
5894 @item @emph{Description}:
5895 Convert to a @code{KIND=2} integer type. This is equivalent to the
5896 standard @code{INT} intrinsic with an optional argument of
5897 @code{KIND=2}, and is only included for backwards compatibility.
5898
5899 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5900
5901 @item @emph{Standard}:
5902 GNU extension
5903
5904 @item @emph{Class}:
5905 Elemental function
5906
5907 @item @emph{Syntax}:
5908 @code{RESULT = INT2(A)}
5909
5910 @item @emph{Arguments}:
5911 @multitable @columnfractions .15 .70
5912 @item @var{A}    @tab Shall be of type @code{INTEGER},
5913                       @code{REAL}, or @code{COMPLEX}.
5914 @end multitable
5915
5916 @item @emph{Return value}:
5917 The return value is a @code{INTEGER(2)} variable.
5918
5919 @item @emph{See also}:
5920 @ref{INT}, @ref{INT8}, @ref{LONG}
5921 @end table
5922
5923
5924
5925 @node INT8
5926 @section @code{INT8} --- Convert to 64-bit integer type
5927 @fnindex INT8
5928 @cindex conversion, to integer
5929
5930 @table @asis
5931 @item @emph{Description}:
5932 Convert to a @code{KIND=8} integer type. This is equivalent to the
5933 standard @code{INT} intrinsic with an optional argument of
5934 @code{KIND=8}, and is only included for backwards compatibility.
5935
5936 @item @emph{Standard}:
5937 GNU extension
5938
5939 @item @emph{Class}:
5940 Elemental function
5941
5942 @item @emph{Syntax}:
5943 @code{RESULT = INT8(A)}
5944
5945 @item @emph{Arguments}:
5946 @multitable @columnfractions .15 .70
5947 @item @var{A}    @tab Shall be of type @code{INTEGER},
5948                       @code{REAL}, or @code{COMPLEX}.
5949 @end multitable
5950
5951 @item @emph{Return value}:
5952 The return value is a @code{INTEGER(8)} variable.
5953
5954 @item @emph{See also}:
5955 @ref{INT}, @ref{INT2}, @ref{LONG}
5956 @end table
5957
5958
5959
5960 @node IOR
5961 @section @code{IOR} --- Bitwise logical or
5962 @fnindex IOR
5963 @cindex bitwise logical or
5964 @cindex logical or, bitwise
5965
5966 @table @asis
5967 @item @emph{Description}:
5968 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
5969 @var{J}.
5970
5971 @item @emph{Standard}:
5972 Fortran 95 and later
5973
5974 @item @emph{Class}:
5975 Elemental function
5976
5977 @item @emph{Syntax}:
5978 @code{RESULT = IOR(I, J)}
5979
5980 @item @emph{Arguments}:
5981 @multitable @columnfractions .15 .70
5982 @item @var{I} @tab The type shall be @code{INTEGER}.
5983 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5984 kind as @var{I}.  (As a GNU extension, different kinds are also
5985 permitted.)
5986 @end multitable
5987
5988 @item @emph{Return value}:
5989 The return type is @code{INTEGER}, of the same kind as the
5990 arguments.  (If the argument kinds differ, it is of the same kind as
5991 the larger argument.)
5992
5993 @item @emph{See also}:
5994 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5995 @end table
5996
5997
5998
5999 @node IRAND
6000 @section @code{IRAND} --- Integer pseudo-random number
6001 @fnindex IRAND
6002 @cindex random number generation
6003
6004 @table @asis
6005 @item @emph{Description}:
6006 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6007 distribution between 0 and a system-dependent limit (which is in most
6008 cases 2147483647). If @var{FLAG} is 0, the next number
6009 in the current sequence is returned; if @var{FLAG} is 1, the generator
6010 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6011 it is used as a new seed with @code{SRAND}.
6012
6013 This intrinsic routine is provided for backwards compatibility with
6014 GNU Fortran 77. It implements a simple modulo generator as provided
6015 by @command{g77}. For new code, one should consider the use of
6016 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6017
6018 @item @emph{Standard}:
6019 GNU extension
6020
6021 @item @emph{Class}:
6022 Function
6023
6024 @item @emph{Syntax}:
6025 @code{RESULT = IRAND(I)}
6026
6027 @item @emph{Arguments}:
6028 @multitable @columnfractions .15 .70
6029 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6030 @end multitable
6031
6032 @item @emph{Return value}:
6033 The return value is of @code{INTEGER(kind=4)} type.
6034
6035 @item @emph{Example}:
6036 @smallexample
6037 program test_irand
6038   integer,parameter :: seed = 86456
6039
6040   call srand(seed)
6041   print *, irand(), irand(), irand(), irand()
6042   print *, irand(seed), irand(), irand(), irand()
6043 end program test_irand
6044 @end smallexample
6045
6046 @end table
6047
6048
6049
6050 @node IS_IOSTAT_END
6051 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6052 @fnindex IS_IOSTAT_END
6053 @cindex IOSTAT, end of file
6054
6055 @table @asis
6056 @item @emph{Description}:
6057 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6058 status ``end of file''. The function is equivalent to comparing the variable
6059 with the @code{IOSTAT_END} parameter of the intrinsic module
6060 @code{ISO_FORTRAN_ENV}.
6061
6062 @item @emph{Standard}:
6063 Fortran 2003 and later
6064
6065 @item @emph{Class}:
6066 Elemental function
6067
6068 @item @emph{Syntax}:
6069 @code{RESULT = IS_IOSTAT_END(I)}
6070
6071 @item @emph{Arguments}:
6072 @multitable @columnfractions .15 .70
6073 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6074 @end multitable
6075
6076 @item @emph{Return value}:
6077 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6078 @var{I} has the value which indicates an end of file condition for
6079 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6080
6081 @item @emph{Example}:
6082 @smallexample
6083 PROGRAM iostat
6084   IMPLICIT NONE
6085   INTEGER :: stat, i
6086   OPEN(88, FILE='test.dat')
6087   READ(88, *, IOSTAT=stat) i
6088   IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6089 END PROGRAM
6090 @end smallexample
6091 @end table
6092
6093
6094
6095 @node IS_IOSTAT_EOR
6096 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6097 @fnindex IS_IOSTAT_EOR
6098 @cindex IOSTAT, end of record
6099
6100 @table @asis
6101 @item @emph{Description}:
6102 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6103 status ``end of record''. The function is equivalent to comparing the
6104 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6105 @code{ISO_FORTRAN_ENV}.
6106
6107 @item @emph{Standard}:
6108 Fortran 2003 and later
6109
6110 @item @emph{Class}:
6111 Elemental function
6112
6113 @item @emph{Syntax}:
6114 @code{RESULT = IS_IOSTAT_EOR(I)}
6115
6116 @item @emph{Arguments}:
6117 @multitable @columnfractions .15 .70
6118 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6119 @end multitable
6120
6121 @item @emph{Return value}:
6122 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6123 @var{I} has the value which indicates an end of file condition for
6124 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6125
6126 @item @emph{Example}:
6127 @smallexample
6128 PROGRAM iostat
6129   IMPLICIT NONE
6130   INTEGER :: stat, i(50)
6131   OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6132   READ(88, IOSTAT=stat) i
6133   IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6134 END PROGRAM
6135 @end smallexample
6136 @end table
6137
6138
6139
6140 @node ISATTY
6141 @section @code{ISATTY} --- Whether a unit is a terminal device.
6142 @fnindex ISATTY
6143 @cindex system, terminal
6144
6145 @table @asis
6146 @item @emph{Description}:
6147 Determine whether a unit is connected to a terminal device.
6148
6149 @item @emph{Standard}:
6150 GNU extension
6151
6152 @item @emph{Class}:
6153 Function
6154
6155 @item @emph{Syntax}:
6156 @code{RESULT = ISATTY(UNIT)}
6157
6158 @item @emph{Arguments}:
6159 @multitable @columnfractions .15 .70
6160 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6161 @end multitable
6162
6163 @item @emph{Return value}:
6164 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6165 device, @code{.FALSE.} otherwise.
6166
6167 @item @emph{Example}:
6168 @smallexample
6169 PROGRAM test_isatty
6170   INTEGER(kind=1) :: unit
6171   DO unit = 1, 10
6172     write(*,*) isatty(unit=unit)
6173   END DO
6174 END PROGRAM
6175 @end smallexample
6176 @item @emph{See also}:
6177 @ref{TTYNAM}
6178 @end table
6179
6180
6181
6182 @node ISHFT
6183 @section @code{ISHFT} --- Shift bits
6184 @fnindex ISHFT
6185 @cindex bits, shift
6186
6187 @table @asis
6188 @item @emph{Description}:
6189 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6190 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
6191 zero corresponds to a left shift, a value of zero corresponds to no
6192 shift, and a value less than zero corresponds to a right shift.  If the
6193 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6194 value is undefined.  Bits shifted out from the left end or right end are
6195 lost; zeros are shifted in from the opposite end.
6196
6197 @item @emph{Standard}:
6198 Fortran 95 and later
6199
6200 @item @emph{Class}:
6201 Elemental function
6202
6203 @item @emph{Syntax}:
6204 @code{RESULT = ISHFT(I, SHIFT)}
6205
6206 @item @emph{Arguments}:
6207 @multitable @columnfractions .15 .70
6208 @item @var{I} @tab The type shall be @code{INTEGER}.
6209 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6210 @end multitable
6211
6212 @item @emph{Return value}:
6213 The return value is of type @code{INTEGER} and of the same kind as
6214 @var{I}.
6215
6216 @item @emph{See also}:
6217 @ref{ISHFTC}
6218 @end table
6219
6220
6221
6222 @node ISHFTC
6223 @section @code{ISHFTC} --- Shift bits circularly
6224 @fnindex ISHFTC
6225 @cindex bits, shift circular
6226
6227 @table @asis
6228 @item @emph{Description}:
6229 @code{ISHFTC} returns a value corresponding to @var{I} with the
6230 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6231 is, bits shifted out one end are shifted into the opposite end.  A value
6232 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6233 zero corresponds to no shift, and a value less than zero corresponds to
6234 a right shift.  The absolute value of @var{SHIFT} must be less than
6235 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
6236 equivalent to @code{BIT_SIZE(I)}.
6237
6238 @item @emph{Standard}:
6239 Fortran 95 and later
6240
6241 @item @emph{Class}:
6242 Elemental function
6243
6244 @item @emph{Syntax}:
6245 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6246
6247 @item @emph{Arguments}:
6248 @multitable @columnfractions .15 .70
6249 @item @var{I} @tab The type shall be @code{INTEGER}.
6250 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6251 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6252 the value must be greater than zero and less than or equal to
6253 @code{BIT_SIZE(I)}.
6254 @end multitable
6255
6256 @item @emph{Return value}:
6257 The return value is of type @code{INTEGER} and of the same kind as
6258 @var{I}.
6259
6260 @item @emph{See also}:
6261 @ref{ISHFT}
6262 @end table
6263
6264
6265
6266 @node ISNAN
6267 @section @code{ISNAN} --- Test for a NaN
6268 @fnindex ISNAN
6269 @cindex IEEE, ISNAN
6270
6271 @table @asis
6272 @item @emph{Description}:
6273 @code{ISNAN} tests whether a floating-point value is an IEEE
6274 Not-a-Number (NaN).
6275 @item @emph{Standard}:
6276 GNU extension
6277
6278 @item @emph{Class}:
6279 Elemental function
6280
6281 @item @emph{Syntax}:
6282 @code{ISNAN(X)}
6283
6284 @item @emph{Arguments}:
6285 @multitable @columnfractions .15 .70
6286 @item @var{X} @tab Variable of the type @code{REAL}.
6287
6288 @end multitable
6289
6290 @item @emph{Return value}:
6291 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6292 if @var{X} is a NaN and @code{FALSE} otherwise.
6293
6294 @item @emph{Example}:
6295 @smallexample
6296 program test_nan
6297   implicit none
6298   real :: x
6299   x = -1.0
6300   x = sqrt(x)
6301   if (isnan(x)) stop '"x" is a NaN'
6302 end program test_nan
6303 @end smallexample
6304 @end table
6305
6306
6307
6308 @node ITIME
6309 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6310 @fnindex ITIME
6311 @cindex time, current
6312 @cindex current time
6313
6314 @table @asis
6315 @item @emph{Description}:
6316 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6317 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6318 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6319 respectively.
6320
6321 @item @emph{Standard}:
6322 GNU extension
6323
6324 @item @emph{Class}:
6325 Subroutine
6326
6327 @item @emph{Syntax}:
6328 @code{CALL ITIME(VALUES)}
6329
6330 @item @emph{Arguments}:
6331 @multitable @columnfractions .15 .70
6332 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6333 and the kind shall be the default integer kind.
6334 @end multitable
6335
6336 @item @emph{Return value}:
6337 Does not return.
6338
6339
6340 @item @emph{Example}:
6341 @smallexample
6342 program test_itime
6343   integer, dimension(3) :: tarray
6344   call itime(tarray)
6345   print *, tarray(1)
6346   print *, tarray(2)
6347   print *, tarray(3)
6348 end program test_itime
6349 @end smallexample
6350 @end table
6351
6352
6353
6354 @node KILL
6355 @section @code{KILL} --- Send a signal to a process
6356 @fnindex KILL
6357
6358 @table @asis
6359 @item @emph{Description}:
6360 @item @emph{Standard}:
6361 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6362 See @code{kill(2)}.
6363
6364 This intrinsic is provided in both subroutine and function forms; however,
6365 only one form can be used in any given program unit.
6366
6367 @item @emph{Class}:
6368 Subroutine, function
6369
6370 @item @emph{Syntax}:
6371 @code{CALL KILL(C, VALUE [, STATUS])}
6372
6373 @item @emph{Arguments}:
6374 @multitable @columnfractions .15 .70
6375 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6376 @code{INTENT(IN)}
6377 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6378 @code{INTENT(IN)}
6379 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6380                         @code{INTEGER(8)}. Returns 0 on success, or a
6381                         system-specific error code otherwise.
6382 @end multitable
6383
6384 @item @emph{See also}:
6385 @ref{ABORT}, @ref{EXIT}
6386 @end table
6387
6388
6389
6390 @node KIND
6391 @section @code{KIND} --- Kind of an entity
6392 @fnindex KIND
6393 @cindex kind
6394
6395 @table @asis
6396 @item @emph{Description}:
6397 @code{KIND(X)} returns the kind value of the entity @var{X}.
6398
6399 @item @emph{Standard}:
6400 Fortran 95 and later
6401
6402 @item @emph{Class}:
6403 Inquiry function
6404
6405 @item @emph{Syntax}:
6406 @code{K = KIND(X)}
6407
6408 @item @emph{Arguments}:
6409 @multitable @columnfractions .15 .70
6410 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6411 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6412 @end multitable
6413
6414 @item @emph{Return value}:
6415 The return value is a scalar of type @code{INTEGER} and of the default
6416 integer kind.
6417
6418 @item @emph{Example}:
6419 @smallexample
6420 program test_kind
6421   integer,parameter :: kc = kind(' ')
6422   integer,parameter :: kl = kind(.true.)
6423
6424   print *, "The default character kind is ", kc
6425   print *, "The default logical kind is ", kl
6426 end program test_kind
6427 @end smallexample
6428
6429 @end table
6430
6431
6432
6433 @node LBOUND
6434 @section @code{LBOUND} --- Lower dimension bounds of an array
6435 @fnindex LBOUND
6436 @cindex array, lower bound
6437
6438 @table @asis
6439 @item @emph{Description}:
6440 Returns the lower bounds of an array, or a single lower bound
6441 along the @var{DIM} dimension.
6442 @item @emph{Standard}:
6443 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6444
6445 @item @emph{Class}:
6446 Inquiry function
6447
6448 @item @emph{Syntax}:
6449 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6450
6451 @item @emph{Arguments}:
6452 @multitable @columnfractions .15 .70
6453 @item @var{ARRAY} @tab Shall be an array, of any type.
6454 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6455 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6456                       expression indicating the kind parameter of
6457                       the result.
6458 @end multitable
6459
6460 @item @emph{Return value}:
6461 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6462 @var{KIND} is absent, the return value is of default integer kind.
6463 If @var{DIM} is absent, the result is an array of the lower bounds of
6464 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
6465 corresponding to the lower bound of the array along that dimension.  If
6466 @var{ARRAY} is an expression rather than a whole array or array
6467 structure component, or if it has a zero extent along the relevant
6468 dimension, the lower bound is taken to be 1.
6469
6470 @item @emph{See also}:
6471 @ref{UBOUND}
6472 @end table
6473
6474
6475
6476 @node LEN
6477 @section @code{LEN} --- Length of a character entity
6478 @fnindex LEN
6479 @cindex string, length
6480
6481 @table @asis
6482 @item @emph{Description}:
6483 Returns the length of a character string.  If @var{STRING} is an array,
6484 the length of an element of @var{STRING} is returned.  Note that
6485 @var{STRING} need not be defined when this intrinsic is invoked, since
6486 only the length, not the content, of @var{STRING} is needed.
6487
6488 @item @emph{Standard}:
6489 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6490
6491 @item @emph{Class}:
6492 Inquiry function
6493
6494 @item @emph{Syntax}:
6495 @code{L = LEN(STRING [, KIND])}
6496
6497 @item @emph{Arguments}:
6498 @multitable @columnfractions .15 .70
6499 @item @var{STRING} @tab Shall be a scalar or array of type
6500 @code{CHARACTER}, with @code{INTENT(IN)}
6501 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6502                       expression indicating the kind parameter of
6503                       the result.
6504 @end multitable
6505
6506 @item @emph{Return value}:
6507 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6508 @var{KIND} is absent, the return value is of default integer kind.
6509
6510 @item @emph{See also}:
6511 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6512 @end table
6513
6514
6515
6516 @node LEN_TRIM
6517 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6518 @fnindex LEN_TRIM
6519 @cindex string, length, without trailing whitespace
6520
6521 @table @asis
6522 @item @emph{Description}:
6523 Returns the length of a character string, ignoring any trailing blanks.
6524
6525 @item @emph{Standard}:
6526 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6527
6528 @item @emph{Class}:
6529 Elemental function
6530
6531 @item @emph{Syntax}:
6532 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6533
6534 @item @emph{Arguments}:
6535 @multitable @columnfractions .15 .70
6536 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6537 with @code{INTENT(IN)}
6538 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6539                       expression indicating the kind parameter of
6540                       the result.
6541 @end multitable
6542
6543 @item @emph{Return value}:
6544 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6545 @var{KIND} is absent, the return value is of default integer kind.
6546
6547 @item @emph{See also}:
6548 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6549 @end table
6550
6551
6552
6553 @node LGE
6554 @section @code{LGE} --- Lexical greater than or equal
6555 @fnindex LGE
6556 @cindex lexical comparison of strings
6557 @cindex string, comparison
6558
6559 @table @asis
6560 @item @emph{Description}:
6561 Determines whether one string is lexically greater than or equal to
6562 another string, where the two strings are interpreted as containing
6563 ASCII character codes.  If the String A and String B are not the same
6564 length, the shorter is compared as if spaces were appended to it to form
6565 a value that has the same length as the longer.
6566
6567 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6568 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6569 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6570 that the latter use the processor's character ordering (which is not
6571 ASCII on some targets), whereas the former always use the ASCII
6572 ordering.
6573
6574 @item @emph{Standard}:
6575 Fortran 77 and later
6576
6577 @item @emph{Class}:
6578 Elemental function
6579
6580 @item @emph{Syntax}:
6581 @code{RESULT = LGE(STRING_A, STRING_B)}
6582
6583 @item @emph{Arguments}:
6584 @multitable @columnfractions .15 .70
6585 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6586 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6587 @end multitable
6588
6589 @item @emph{Return value}:
6590 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6591 otherwise, based on the ASCII ordering.
6592
6593 @item @emph{See also}:
6594 @ref{LGT}, @ref{LLE}, @ref{LLT}
6595 @end table
6596
6597
6598
6599 @node LGT
6600 @section @code{LGT} --- Lexical greater than
6601 @fnindex LGT
6602 @cindex lexical comparison of strings
6603 @cindex string, comparison
6604
6605 @table @asis
6606 @item @emph{Description}:
6607 Determines whether one string is lexically greater than another string,
6608 where the two strings are interpreted as containing ASCII character
6609 codes.  If the String A and String B are not the same length, the
6610 shorter is compared as if spaces were appended to it to form a value
6611 that has the same length as the longer.
6612
6613 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6614 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6615 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6616 that the latter use the processor's character ordering (which is not
6617 ASCII on some targets), whereas the former always use the ASCII
6618 ordering.
6619
6620 @item @emph{Standard}:
6621 Fortran 77 and later
6622
6623 @item @emph{Class}:
6624 Elemental function
6625
6626 @item @emph{Syntax}:
6627 @code{RESULT = LGT(STRING_A, STRING_B)}
6628
6629 @item @emph{Arguments}:
6630 @multitable @columnfractions .15 .70
6631 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6632 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6633 @end multitable
6634
6635 @item @emph{Return value}:
6636 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6637 otherwise, based on the ASCII ordering.
6638
6639 @item @emph{See also}:
6640 @ref{LGE}, @ref{LLE}, @ref{LLT}
6641 @end table
6642
6643
6644
6645 @node LINK
6646 @section @code{LINK} --- Create a hard link
6647 @fnindex LINK
6648 @cindex file system, create link
6649 @cindex file system, hard link
6650
6651 @table @asis
6652 @item @emph{Description}:
6653 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6654 character (@code{CHAR(0)}) can be used to mark the end of the names in
6655 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6656 names are ignored.  If the @var{STATUS} argument is supplied, it
6657 contains 0 on success or a nonzero error code upon return; see
6658 @code{link(2)}.
6659
6660 This intrinsic is provided in both subroutine and function forms;
6661 however, only one form can be used in any given program unit.
6662
6663 @item @emph{Standard}:
6664 GNU extension
6665
6666 @item @emph{Class}:
6667 Subroutine, function
6668
6669 @item @emph{Syntax}:
6670 @multitable @columnfractions .80
6671 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6672 @item @code{STATUS = LINK(PATH1, PATH2)}
6673 @end multitable
6674
6675 @item @emph{Arguments}:
6676 @multitable @columnfractions .15 .70
6677 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6678 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6679 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6680 @end multitable
6681
6682 @item @emph{See also}:
6683 @ref{SYMLNK}, @ref{UNLINK}
6684 @end table
6685
6686
6687
6688 @node LLE
6689 @section @code{LLE} --- Lexical less than or equal
6690 @fnindex LLE
6691 @cindex lexical comparison of strings
6692 @cindex string, comparison
6693
6694 @table @asis
6695 @item @emph{Description}:
6696 Determines whether one string is lexically less than or equal to another
6697 string, where the two strings are interpreted as containing ASCII
6698 character codes.  If the String A and String B are not the same length,
6699 the shorter is compared as if spaces were appended to it to form a value
6700 that has the same length as the longer.
6701
6702 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6703 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6704 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6705 that the latter use the processor's character ordering (which is not
6706 ASCII on some targets), whereas the former always use the ASCII
6707 ordering.
6708
6709 @item @emph{Standard}:
6710 Fortran 77 and later
6711
6712 @item @emph{Class}:
6713 Elemental function
6714
6715 @item @emph{Syntax}:
6716 @code{RESULT = LLE(STRING_A, STRING_B)}
6717
6718 @item @emph{Arguments}:
6719 @multitable @columnfractions .15 .70
6720 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6721 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6722 @end multitable
6723
6724 @item @emph{Return value}:
6725 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6726 otherwise, based on the ASCII ordering.
6727
6728 @item @emph{See also}:
6729 @ref{LGE}, @ref{LGT}, @ref{LLT}
6730 @end table
6731
6732
6733
6734 @node LLT
6735 @section @code{LLT} --- Lexical less than
6736 @fnindex LLT
6737 @cindex lexical comparison of strings
6738 @cindex string, comparison
6739
6740 @table @asis
6741 @item @emph{Description}:
6742 Determines whether one string is lexically less than another string,
6743 where the two strings are interpreted as containing ASCII character
6744 codes.  If the String A and String B are not the same length, the
6745 shorter is compared as if spaces were appended to it to form a value
6746 that has the same length as the longer.
6747
6748 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6749 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6750 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6751 that the latter use the processor's character ordering (which is not
6752 ASCII on some targets), whereas the former always use the ASCII
6753 ordering.
6754
6755 @item @emph{Standard}:
6756 Fortran 77 and later
6757
6758 @item @emph{Class}:
6759 Elemental function
6760
6761 @item @emph{Syntax}:
6762 @code{RESULT = LLT(STRING_A, STRING_B)}
6763
6764 @item @emph{Arguments}:
6765 @multitable @columnfractions .15 .70
6766 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6767 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6768 @end multitable
6769
6770 @item @emph{Return value}:
6771 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6772 otherwise, based on the ASCII ordering.
6773
6774 @item @emph{See also}:
6775 @ref{LGE}, @ref{LGT}, @ref{LLE}
6776 @end table
6777
6778
6779
6780 @node LNBLNK
6781 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6782 @fnindex LNBLNK
6783 @cindex string, find non-blank character
6784
6785 @table @asis
6786 @item @emph{Description}:
6787 Returns the length of a character string, ignoring any trailing blanks.
6788 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6789 included for backwards compatibility.
6790
6791 @item @emph{Standard}:
6792 GNU extension
6793
6794 @item @emph{Class}:
6795 Elemental function
6796
6797 @item @emph{Syntax}:
6798 @code{RESULT = LNBLNK(STRING)}
6799
6800 @item @emph{Arguments}:
6801 @multitable @columnfractions .15 .70
6802 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6803 with @code{INTENT(IN)}
6804 @end multitable
6805
6806 @item @emph{Return value}:
6807 The return value is of @code{INTEGER(kind=4)} type.
6808
6809 @item @emph{See also}:
6810 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6811 @end table
6812
6813
6814
6815 @node LOC
6816 @section @code{LOC} --- Returns the address of a variable
6817 @fnindex LOC
6818 @cindex location of a variable in memory
6819
6820 @table @asis
6821 @item @emph{Description}:
6822 @code{LOC(X)} returns the address of @var{X} as an integer.
6823
6824 @item @emph{Standard}:
6825 GNU extension
6826
6827 @item @emph{Class}:
6828 Inquiry function
6829
6830 @item @emph{Syntax}:
6831 @code{RESULT = LOC(X)}
6832
6833 @item @emph{Arguments}:
6834 @multitable @columnfractions .15 .70
6835 @item @var{X} @tab Variable of any type.
6836 @end multitable
6837
6838 @item @emph{Return value}:
6839 The return value is of type @code{INTEGER}, with a @code{KIND}
6840 corresponding to the size (in bytes) of a memory address on the target
6841 machine.
6842
6843 @item @emph{Example}:
6844 @smallexample
6845 program test_loc
6846   integer :: i
6847   real :: r
6848   i = loc(r)
6849   print *, i
6850 end program test_loc
6851 @end smallexample
6852 @end table
6853
6854
6855
6856 @node LOG
6857 @section @code{LOG} --- Logarithm function
6858 @fnindex LOG
6859 @fnindex ALOG
6860 @fnindex DLOG
6861 @fnindex CLOG
6862 @fnindex ZLOG
6863 @fnindex CDLOG
6864 @cindex exponential function, inverse
6865 @cindex logarithmic function
6866
6867 @table @asis
6868 @item @emph{Description}:
6869 @code{LOG(X)} computes the logarithm of @var{X}.
6870
6871 @item @emph{Standard}:
6872 Fortran 77 and later
6873
6874 @item @emph{Class}:
6875 Elemental function
6876
6877 @item @emph{Syntax}:
6878 @code{RESULT = LOG(X)}
6879
6880 @item @emph{Arguments}:
6881 @multitable @columnfractions .15 .70
6882 @item @var{X} @tab The type shall be @code{REAL} or
6883 @code{COMPLEX}.
6884 @end multitable
6885
6886 @item @emph{Return value}:
6887 The return value is of type @code{REAL} or @code{COMPLEX}.
6888 The kind type parameter is the same as @var{X}.
6889
6890 @item @emph{Example}:
6891 @smallexample
6892 program test_log
6893   real(8) :: x = 1.0_8
6894   complex :: z = (1.0, 2.0)
6895   x = log(x)
6896   z = log(z)
6897 end program test_log
6898 @end smallexample
6899
6900 @item @emph{Specific names}:
6901 @multitable @columnfractions .20 .20 .20 .25
6902 @item Name            @tab Argument          @tab Return type       @tab Standard
6903 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
6904 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
6905 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
6906 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6907 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
6908 @end multitable
6909 @end table
6910
6911
6912
6913 @node LOG10
6914 @section @code{LOG10} --- Base 10 logarithm function
6915 @fnindex LOG10
6916 @fnindex ALOG10
6917 @fnindex DLOG10
6918 @cindex exponential function, inverse
6919 @cindex logarithmic function
6920
6921 @table @asis
6922 @item @emph{Description}:
6923 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6924
6925 @item @emph{Standard}:
6926 Fortran 77 and later
6927
6928 @item @emph{Class}:
6929 Elemental function
6930
6931 @item @emph{Syntax}:
6932 @code{RESULT = LOG10(X)}
6933
6934 @item @emph{Arguments}:
6935 @multitable @columnfractions .15 .70
6936 @item @var{X} @tab The type shall be @code{REAL}.
6937 @end multitable
6938
6939 @item @emph{Return value}:
6940 The return value is of type @code{REAL} or @code{COMPLEX}.
6941 The kind type parameter is the same as @var{X}.
6942
6943 @item @emph{Example}:
6944 @smallexample
6945 program test_log10
6946   real(8) :: x = 10.0_8
6947   x = log10(x)
6948 end program test_log10
6949 @end smallexample
6950
6951 @item @emph{Specific names}:
6952 @multitable @columnfractions .20 .20 .20 .25
6953 @item Name            @tab Argument          @tab Return type       @tab Standard
6954 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
6955 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
6956 @end multitable
6957 @end table
6958
6959
6960
6961 @node LOG_GAMMA
6962 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
6963 @fnindex LOG_GAMMA
6964 @fnindex LGAMMA
6965 @fnindex ALGAMA
6966 @fnindex DLGAMA
6967 @cindex Gamma function, logarithm of
6968
6969 @table @asis
6970 @item @emph{Description}:
6971 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
6972 of the Gamma (@math{\Gamma}) function.
6973
6974 @item @emph{Standard}:
6975 Fortran 2008 and later
6976
6977 @item @emph{Class}:
6978 Elemental function
6979
6980 @item @emph{Syntax}:
6981 @code{X = LOG_GAMMA(X)}
6982
6983 @item @emph{Arguments}:
6984 @multitable @columnfractions .15 .70
6985 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6986 nor a negative integer.
6987 @end multitable
6988
6989 @item @emph{Return value}:
6990 The return value is of type @code{REAL} of the same kind as @var{X}.
6991
6992 @item @emph{Example}:
6993 @smallexample
6994 program test_log_gamma
6995   real :: x = 1.0
6996   x = lgamma(x) ! returns 0.0
6997 end program test_log_gamma
6998 @end smallexample
6999
7000 @item @emph{Specific names}:
7001 @multitable @columnfractions .20 .20 .20 .25
7002 @item Name             @tab Argument         @tab Return type       @tab Standard
7003 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7004 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7005 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
7006 @end multitable
7007
7008 @item @emph{See also}:
7009 Gamma function: @ref{GAMMA}
7010
7011 @end table
7012
7013
7014
7015 @node LOGICAL
7016 @section @code{LOGICAL} --- Convert to logical type
7017 @fnindex LOGICAL
7018 @cindex conversion, to logical
7019
7020 @table @asis
7021 @item @emph{Description}:
7022 Converts one kind of @code{LOGICAL} variable to another.
7023
7024 @item @emph{Standard}:
7025 Fortran 95 and later
7026
7027 @item @emph{Class}:
7028 Elemental function
7029
7030 @item @emph{Syntax}:
7031 @code{RESULT = LOGICAL(L [, KIND])}
7032
7033 @item @emph{Arguments}:
7034 @multitable @columnfractions .15 .70
7035 @item @var{L}    @tab The type shall be @code{LOGICAL}.
7036 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7037                       expression indicating the kind parameter of
7038                       the result.
7039 @end multitable
7040
7041 @item @emph{Return value}:
7042 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7043 kind corresponding to @var{KIND}, or of the default logical kind if
7044 @var{KIND} is not given.
7045
7046 @item @emph{See also}:
7047 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7048 @end table
7049
7050
7051
7052 @node LONG
7053 @section @code{LONG} --- Convert to integer type
7054 @fnindex LONG
7055 @cindex conversion, to integer
7056
7057 @table @asis
7058 @item @emph{Description}:
7059 Convert to a @code{KIND=4} integer type, which is the same size as a C
7060 @code{long} integer.  This is equivalent to the standard @code{INT}
7061 intrinsic with an optional argument of @code{KIND=4}, and is only
7062 included for backwards compatibility.
7063
7064 @item @emph{Standard}:
7065 GNU extension
7066
7067 @item @emph{Class}:
7068 Elemental function
7069
7070 @item @emph{Syntax}:
7071 @code{RESULT = LONG(A)}
7072
7073 @item @emph{Arguments}:
7074 @multitable @columnfractions .15 .70
7075 @item @var{A}    @tab Shall be of type @code{INTEGER},
7076                       @code{REAL}, or @code{COMPLEX}.
7077 @end multitable
7078
7079 @item @emph{Return value}:
7080 The return value is a @code{INTEGER(4)} variable.
7081
7082 @item @emph{See also}:
7083 @ref{INT}, @ref{INT2}, @ref{INT8}
7084 @end table
7085
7086
7087
7088 @node LSHIFT
7089 @section @code{LSHIFT} --- Left shift bits
7090 @fnindex LSHIFT
7091 @cindex bits, shift left
7092
7093 @table @asis
7094 @item @emph{Description}:
7095 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7096 bits shifted left by @var{SHIFT} places.  If the absolute value of
7097 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7098 Bits shifted out from the left end are lost; zeros are shifted in from
7099 the opposite end.
7100
7101 This function has been superseded by the @code{ISHFT} intrinsic, which
7102 is standard in Fortran 95 and later.
7103
7104 @item @emph{Standard}:
7105 GNU extension
7106
7107 @item @emph{Class}:
7108 Elemental function
7109
7110 @item @emph{Syntax}:
7111 @code{RESULT = LSHIFT(I, SHIFT)}
7112
7113 @item @emph{Arguments}:
7114 @multitable @columnfractions .15 .70
7115 @item @var{I} @tab The type shall be @code{INTEGER}.
7116 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7117 @end multitable
7118
7119 @item @emph{Return value}:
7120 The return value is of type @code{INTEGER} and of the same kind as
7121 @var{I}.
7122
7123 @item @emph{See also}:
7124 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7125
7126 @end table
7127
7128
7129
7130 @node LSTAT
7131 @section @code{LSTAT} --- Get file status
7132 @fnindex LSTAT
7133 @cindex file system, file status
7134
7135 @table @asis
7136 @item @emph{Description}:
7137 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
7138 then the link itself is statted, not the file that it refers to.
7139
7140 The elements in @code{BUFF} are the same as described by @ref{STAT}.
7141
7142 This intrinsic is provided in both subroutine and function forms; however,
7143 only one form can be used in any given program unit.
7144
7145 @item @emph{Standard}:
7146 GNU extension
7147
7148 @item @emph{Class}:
7149 Subroutine, function
7150
7151 @item @emph{Syntax}:
7152 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
7153
7154 @item @emph{Arguments}:
7155 @multitable @columnfractions .15 .70
7156 @item @var{FILE}   @tab The type shall be @code{CHARACTER} of the default
7157 kind, a valid path within the file system.
7158 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7159 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7160 Returns 0 on success and a system specific error code otherwise.
7161 @end multitable
7162
7163 @item @emph{Example}:
7164 See @ref{STAT} for an example.
7165
7166 @item @emph{See also}:
7167 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7168 @end table
7169
7170
7171
7172 @node LTIME
7173 @section @code{LTIME} --- Convert time to local time info
7174 @fnindex LTIME
7175 @cindex time, conversion to local time info
7176
7177 @table @asis
7178 @item @emph{Description}:
7179 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
7180 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
7181 to the local time zone using @code{localtime(3)}.
7182
7183 @item @emph{Standard}:
7184 GNU extension
7185
7186 @item @emph{Class}:
7187 Subroutine
7188
7189 @item @emph{Syntax}:
7190 @code{CALL LTIME(STIME, TARRAY)}
7191
7192 @item @emph{Arguments}:
7193 @multitable @columnfractions .15 .70
7194 @item @var{STIME}  @tab An @code{INTEGER} scalar expression
7195                         corresponding to a system time, with
7196                         @code{INTENT(IN)}.
7197 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
7198                         with @code{INTENT(OUT)}.
7199 @end multitable
7200
7201 @item @emph{Return value}:
7202 The elements of @var{TARRAY} are assigned as follows:
7203 @enumerate
7204 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7205       seconds
7206 @item Minutes after the hour, range 0--59
7207 @item Hours past midnight, range 0--23
7208 @item Day of month, range 0--31
7209 @item Number of months since January, range 0--12
7210 @item Years since 1900
7211 @item Number of days since Sunday, range 0--6
7212 @item Days since January 1
7213 @item Daylight savings indicator: positive if daylight savings is in
7214       effect, zero if not, and negative if the information is not
7215       available.
7216 @end enumerate
7217
7218 @item @emph{See also}:
7219 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7220
7221 @end table
7222
7223
7224
7225 @node MALLOC
7226 @section @code{MALLOC} --- Allocate dynamic memory
7227 @fnindex MALLOC
7228 @cindex pointer, cray
7229
7230 @table @asis
7231 @item @emph{Description}:
7232 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7233 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7234 is an extension intended to be used with Cray pointers, and is provided
7235 in GNU Fortran to allow the user to compile legacy code. For new code
7236 using Fortran 95 pointers, the memory allocation intrinsic is
7237 @code{ALLOCATE}.
7238
7239 @item @emph{Standard}:
7240 GNU extension
7241
7242 @item @emph{Class}:
7243 Function
7244
7245 @item @emph{Syntax}:
7246 @code{PTR = MALLOC(SIZE)}
7247
7248 @item @emph{Arguments}:
7249 @multitable @columnfractions .15 .70
7250 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7251 @end multitable
7252
7253 @item @emph{Return value}:
7254 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7255 variables of type @code{INTEGER(K)} have the same size as
7256 C pointers (@code{sizeof(void *)}).
7257
7258 @item @emph{Example}:
7259 The following example demonstrates the use of @code{MALLOC} and
7260 @code{FREE} with Cray pointers. This example is intended to run on
7261 32-bit systems, where the default integer kind is suitable to store
7262 pointers; on 64-bit systems, ptr_x would need to be declared as
7263 @code{integer(kind=8)}.
7264
7265 @smallexample
7266 program test_malloc
7267   integer i
7268   integer ptr_x
7269   real*8 x(*), z
7270   pointer(ptr_x,x)
7271
7272   ptr_x = malloc(20*8)
7273   do i = 1, 20
7274     x(i) = sqrt(1.0d0 / i)
7275   end do
7276   z = 0
7277   do i = 1, 20
7278     z = z + x(i)
7279     print *, z
7280   end do
7281   call free(ptr_x)
7282 end program test_malloc
7283 @end smallexample
7284
7285 @item @emph{See also}:
7286 @ref{FREE}
7287 @end table
7288
7289
7290
7291 @node MATMUL
7292 @section @code{MATMUL} --- matrix multiplication
7293 @fnindex MATMUL
7294 @cindex matrix multiplication
7295 @cindex product, matrix
7296
7297 @table @asis
7298 @item @emph{Description}:
7299 Performs a matrix multiplication on numeric or logical arguments.
7300
7301 @item @emph{Standard}:
7302 Fortran 95 and later
7303
7304 @item @emph{Class}:
7305 Transformational function
7306
7307 @item @emph{Syntax}:
7308 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7309
7310 @item @emph{Arguments}:
7311 @multitable @columnfractions .15 .70
7312 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7313                           @code{REAL}, @code{COMPLEX}, or
7314                           @code{LOGICAL} type, with a rank of
7315                           one or two.
7316 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7317                           @code{REAL}, or @code{COMPLEX} type if
7318                           @var{MATRIX_A} is of a numeric type;
7319                           otherwise, an array of @code{LOGICAL}
7320                           type. The rank shall be one or two, and the
7321                           first (or only) dimension of @var{MATRIX_B}
7322                           shall be equal to the last (or only)
7323                           dimension of @var{MATRIX_A}.
7324 @end multitable
7325
7326 @item @emph{Return value}:
7327 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
7328 kind of the result follow the usual type and kind promotion rules, as
7329 for the @code{*} or @code{.AND.} operators.
7330
7331 @item @emph{See also}:
7332 @end table
7333
7334
7335
7336 @node MAX
7337 @section @code{MAX} --- Maximum value of an argument list
7338 @fnindex MAX
7339 @fnindex MAX0
7340 @fnindex AMAX0
7341 @fnindex MAX1
7342 @fnindex AMAX1
7343 @fnindex DMAX1
7344 @cindex maximum value
7345
7346 @table @asis
7347 @item @emph{Description}:
7348 Returns the argument with the largest (most positive) value.
7349
7350 @item @emph{Standard}:
7351 Fortran 77 and later
7352
7353 @item @emph{Class}:
7354 Elemental function
7355
7356 @item @emph{Syntax}:
7357 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7358
7359 @item @emph{Arguments}:
7360 @multitable @columnfractions .15 .70
7361 @item @var{A1}          @tab The type shall be @code{INTEGER} or
7362                              @code{REAL}.
7363 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7364                              as @var{A1}.  (As a GNU extension,
7365                              arguments of different kinds are
7366                              permitted.)
7367 @end multitable
7368
7369 @item @emph{Return value}:
7370 The return value corresponds to the maximum value among the arguments,
7371 and has the same type and kind as the first argument.
7372
7373 @item @emph{Specific names}:
7374 @multitable @columnfractions .20 .20 .20 .25
7375 @item Name             @tab Argument            @tab Return type         @tab Standard
7376 @item @code{MAX0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
7377 @item @code{AMAX0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7378 @item @code{MAX1(X)}   @tab @code{REAL X}    @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
7379 @item @code{AMAX1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab Fortran 77 and later
7380 @item @code{DMAX1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab Fortran 77 and later
7381 @end multitable
7382
7383 @item @emph{See also}:
7384 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7385
7386 @end table
7387
7388
7389
7390 @node MAXEXPONENT
7391 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7392 @fnindex MAXEXPONENT
7393 @cindex model representation, maximum exponent
7394
7395 @table @asis
7396 @item @emph{Description}:
7397 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7398 type of @code{X}.
7399
7400 @item @emph{Standard}:
7401 Fortran 95 and later
7402
7403 @item @emph{Class}:
7404 Inquiry function
7405
7406 @item @emph{Syntax}:
7407 @code{RESULT = MAXEXPONENT(X)}
7408
7409 @item @emph{Arguments}:
7410 @multitable @columnfractions .15 .70
7411 @item @var{X} @tab Shall be of type @code{REAL}.
7412 @end multitable
7413
7414 @item @emph{Return value}:
7415 The return value is of type @code{INTEGER} and of the default integer
7416 kind.
7417
7418 @item @emph{Example}:
7419 @smallexample
7420 program exponents
7421   real(kind=4) :: x
7422   real(kind=8) :: y
7423
7424   print *, minexponent(x), maxexponent(x)
7425   print *, minexponent(y), maxexponent(y)
7426 end program exponents
7427 @end smallexample
7428 @end table
7429
7430
7431
7432 @node MAXLOC
7433 @section @code{MAXLOC} --- Location of the maximum value within an array
7434 @fnindex MAXLOC
7435 @cindex array, location of maximum element
7436
7437 @table @asis
7438 @item @emph{Description}:
7439 Determines the location of the element in the array with the maximum
7440 value, or, if the @var{DIM} argument is supplied, determines the
7441 locations of the maximum element along each row of the array in the
7442 @var{DIM} direction.  If @var{MASK} is present, only the elements for
7443 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
7444 element in the array has the maximum value, the location returned is
7445 that of the first such element in array element order.  If the array has
7446 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7447 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
7448 and all of the elements of @var{MASK} along a given row are zero, the
7449 result value for that row is zero.
7450
7451 @item @emph{Standard}:
7452 Fortran 95 and later
7453
7454 @item @emph{Class}:
7455 Transformational function
7456
7457 @item @emph{Syntax}:
7458 @multitable @columnfractions .80
7459 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7460 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7461 @end multitable
7462
7463 @item @emph{Arguments}:
7464 @multitable @columnfractions .15 .70
7465 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7466                        @code{REAL}, or @code{CHARACTER}.
7467 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7468                        @code{INTEGER}, with a value between one
7469                        and the rank of @var{ARRAY}, inclusive.  It
7470                        may not be an optional dummy argument.
7471 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7472                        and conformable with @var{ARRAY}.
7473 @end multitable
7474
7475 @item @emph{Return value}:
7476 If @var{DIM} is absent, the result is a rank-one array with a length
7477 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
7478 is an array with a rank one less than the rank of @var{ARRAY}, and a
7479 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7480 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
7481 of one, the result is a scalar.  In all cases, the result is of default
7482 @code{INTEGER} type.
7483
7484 @item @emph{See also}:
7485 @ref{MAX}, @ref{MAXVAL}
7486
7487 @end table
7488
7489
7490
7491 @node MAXVAL
7492 @section @code{MAXVAL} --- Maximum value of an array
7493 @fnindex MAXVAL
7494 @cindex array, maximum value
7495 @cindex maximum value
7496
7497 @table @asis
7498 @item @emph{Description}:
7499 Determines the maximum value of the elements in an array value, or, if
7500 the @var{DIM} argument is supplied, determines the maximum value along
7501 each row of the array in the @var{DIM} direction.  If @var{MASK} is
7502 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7503 considered.  If the array has zero size, or all of the elements of
7504 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7505 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7506 a string of nulls if @var{ARRAY} is of character type.
7507
7508 @item @emph{Standard}:
7509 Fortran 95 and later
7510
7511 @item @emph{Class}:
7512 Transformational function
7513
7514 @item @emph{Syntax}:
7515 @multitable @columnfractions .80
7516 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7517 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7518 @end multitable
7519
7520 @item @emph{Arguments}:
7521 @multitable @columnfractions .15 .70
7522 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7523                        @code{REAL}, or @code{CHARACTER}.
7524 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7525                        @code{INTEGER}, with a value between one
7526                        and the rank of @var{ARRAY}, inclusive.  It
7527                        may not be an optional dummy argument.
7528 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7529                        and conformable with @var{ARRAY}.
7530 @end multitable
7531
7532 @item @emph{Return value}:
7533 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7534 is a scalar.  If @var{DIM} is present, the result is an array with a
7535 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7536 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
7537 cases, the result is of the same type and kind as @var{ARRAY}.
7538
7539 @item @emph{See also}:
7540 @ref{MAX}, @ref{MAXLOC}
7541 @end table
7542
7543
7544
7545 @node MCLOCK
7546 @section @code{MCLOCK} --- Time function
7547 @fnindex MCLOCK
7548 @cindex time, clock ticks
7549 @cindex clock ticks
7550
7551 @table @asis
7552 @item @emph{Description}:
7553 Returns the number of clock ticks since the start of the process, based
7554 on the UNIX function @code{clock(3)}.
7555
7556 This intrinsic is not fully portable, such as to systems with 32-bit
7557 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7558 the values returned by this intrinsic might be, or become, negative, or
7559 numerically less than previous values, during a single run of the
7560 compiled program.
7561
7562 @item @emph{Standard}:
7563 GNU extension
7564
7565 @item @emph{Class}:
7566 Function
7567
7568 @item @emph{Syntax}:
7569 @code{RESULT = MCLOCK()}
7570
7571 @item @emph{Return value}:
7572 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7573 number of clock ticks since the start of the process, or @code{-1} if
7574 the system does not support @code{clock(3)}.
7575
7576 @item @emph{See also}:
7577 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7578
7579 @end table
7580
7581
7582
7583 @node MCLOCK8
7584 @section @code{MCLOCK8} --- Time function (64-bit)
7585 @fnindex MCLOCK8
7586 @cindex time, clock ticks
7587 @cindex clock ticks
7588
7589 @table @asis
7590 @item @emph{Description}:
7591 Returns the number of clock ticks since the start of the process, based
7592 on the UNIX function @code{clock(3)}.
7593
7594 @emph{Warning:} this intrinsic does not increase the range of the timing
7595 values over that returned by @code{clock(3)}. On a system with a 32-bit
7596 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7597 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7598 overflows of the 32-bit value can still occur. Therefore, the values
7599 returned by this intrinsic might be or become negative or numerically
7600 less than previous values during a single run of the compiled program.
7601
7602 @item @emph{Standard}:
7603 GNU extension
7604
7605 @item @emph{Class}:
7606 Function
7607
7608 @item @emph{Syntax}:
7609 @code{RESULT = MCLOCK8()}
7610
7611 @item @emph{Return value}:
7612 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7613 number of clock ticks since the start of the process, or @code{-1} if
7614 the system does not support @code{clock(3)}.
7615
7616 @item @emph{See also}:
7617 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7618
7619 @end table
7620
7621
7622
7623 @node MERGE
7624 @section @code{MERGE} --- Merge variables
7625 @fnindex MERGE
7626 @cindex array, merge arrays
7627 @cindex array, combine arrays
7628
7629 @table @asis
7630 @item @emph{Description}:
7631 Select values from two arrays according to a logical mask.  The result
7632 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7633 @var{FSOURCE} if it is @code{.FALSE.}.
7634
7635 @item @emph{Standard}:
7636 Fortran 95 and later
7637
7638 @item @emph{Class}:
7639 Elemental function
7640
7641 @item @emph{Syntax}:
7642 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7643
7644 @item @emph{Arguments}:
7645 @multitable @columnfractions .15 .70
7646 @item @var{TSOURCE} @tab May be of any type.
7647 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7648                          as @var{TSOURCE}.
7649 @item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
7650 @end multitable
7651
7652 @item @emph{Return value}:
7653 The result is of the same type and type parameters as @var{TSOURCE}.
7654
7655 @end table
7656
7657
7658
7659 @node MIN
7660 @section @code{MIN} --- Minimum value of an argument list
7661 @fnindex MIN
7662 @fnindex MIN0
7663 @fnindex AMIN0
7664 @fnindex MIN1
7665 @fnindex AMIN1
7666 @fnindex DMIN1
7667 @cindex minimum value
7668
7669 @table @asis
7670 @item @emph{Description}:
7671 Returns the argument with the smallest (most negative) value.
7672
7673 @item @emph{Standard}:
7674 Fortran 77 and later
7675
7676 @item @emph{Class}:
7677 Elemental function
7678
7679 @item @emph{Syntax}:
7680 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7681
7682 @item @emph{Arguments}:
7683 @multitable @columnfractions .15 .70
7684 @item @var{A1}          @tab The type shall be @code{INTEGER} or
7685                              @code{REAL}.
7686 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7687                              as @var{A1}.  (As a GNU extension,
7688                              arguments of different kinds are
7689                              permitted.)
7690 @end multitable
7691
7692 @item @emph{Return value}:
7693 The return value corresponds to the maximum value among the arguments,
7694 and has the same type and kind as the first argument.
7695
7696 @item @emph{Specific names}:
7697 @multitable @columnfractions .20 .20 .20 .25
7698 @item Name             @tab Argument            @tab Return type         @tab Standard
7699 @item @code{MIN0(I)}   @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
7700 @item @code{AMIN0(I)}  @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7701 @item @code{MIN1(X)}   @tab @code{REAL X}    @tab @code{INT(MIN(X))}  @tab Fortran 77 and later
7702 @item @code{AMIN1(X)}  @tab @code{REAL(4)    X} @tab @code{REAL(4)}      @tab Fortran 77 and later
7703 @item @code{DMIN1(X)}  @tab @code{REAL(8)    X} @tab @code{REAL(8)}      @tab Fortran 77 and later
7704 @end multitable
7705
7706 @item @emph{See also}:
7707 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7708 @end table
7709
7710
7711
7712 @node MINEXPONENT
7713 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7714 @fnindex MINEXPONENT
7715 @cindex model representation, minimum exponent
7716
7717 @table @asis
7718 @item @emph{Description}:
7719 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7720 type of @code{X}.
7721
7722 @item @emph{Standard}:
7723 Fortran 95 and later
7724
7725 @item @emph{Class}:
7726 Inquiry function
7727
7728 @item @emph{Syntax}:
7729 @code{RESULT = MINEXPONENT(X)}
7730
7731 @item @emph{Arguments}:
7732 @multitable @columnfractions .15 .70
7733 @item @var{X} @tab Shall be of type @code{REAL}.
7734 @end multitable
7735
7736 @item @emph{Return value}:
7737 The return value is of type @code{INTEGER} and of the default integer
7738 kind.
7739
7740 @item @emph{Example}:
7741 See @code{MAXEXPONENT} for an example.
7742 @end table
7743
7744
7745
7746 @node MINLOC
7747 @section @code{MINLOC} --- Location of the minimum value within an array
7748 @fnindex MINLOC
7749 @cindex array, location of minimum element
7750
7751 @table @asis
7752 @item @emph{Description}:
7753 Determines the location of the element in the array with the minimum
7754 value, or, if the @var{DIM} argument is supplied, determines the
7755 locations of the minimum element along each row of the array in the
7756 @var{DIM} direction.  If @var{MASK} is present, only the elements for
7757 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
7758 element in the array has the minimum value, the location returned is
7759 that of the first such element in array element order.  If the array has
7760 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7761 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
7762 and all of the elements of @var{MASK} along a given row are zero, the
7763 result value for that row is zero.
7764
7765 @item @emph{Standard}:
7766 Fortran 95 and later
7767
7768 @item @emph{Class}:
7769 Transformational function
7770
7771 @item @emph{Syntax}:
7772 @multitable @columnfractions .80
7773 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7774 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7775 @end multitable
7776
7777 @item @emph{Arguments}:
7778 @multitable @columnfractions .15 .70
7779 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7780                        @code{REAL}, or @code{CHARACTER}.
7781 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7782                        @code{INTEGER}, with a value between one
7783                        and the rank of @var{ARRAY}, inclusive.  It
7784                        may not be an optional dummy argument.
7785 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7786                        and conformable with @var{ARRAY}.
7787 @end multitable
7788
7789 @item @emph{Return value}:
7790 If @var{DIM} is absent, the result is a rank-one array with a length
7791 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
7792 is an array with a rank one less than the rank of @var{ARRAY}, and a
7793 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7794 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
7795 of one, the result is a scalar.  In all cases, the result is of default
7796 @code{INTEGER} type.
7797
7798 @item @emph{See also}:
7799 @ref{MIN}, @ref{MINVAL}
7800
7801 @end table
7802
7803
7804
7805 @node MINVAL
7806 @section @code{MINVAL} --- Minimum value of an array
7807 @fnindex MINVAL
7808 @cindex array, minimum value
7809 @cindex minimum value
7810
7811 @table @asis
7812 @item @emph{Description}:
7813 Determines the minimum value of the elements in an array value, or, if
7814 the @var{DIM} argument is supplied, determines the minimum value along
7815 each row of the array in the @var{DIM} direction.  If @var{MASK} is
7816 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7817 considered.  If the array has zero size, or all of the elements of
7818 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7819 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7820 @var{ARRAY} is of character type.
7821
7822 @item @emph{Standard}:
7823 Fortran 95 and later
7824
7825 @item @emph{Class}:
7826 Transformational function
7827
7828 @item @emph{Syntax}:
7829 @multitable @columnfractions .80
7830 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7831 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7832 @end multitable
7833
7834 @item @emph{Arguments}:
7835 @multitable @columnfractions .15 .70
7836 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7837                        @code{REAL}, or @code{CHARACTER}.
7838 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
7839                        @code{INTEGER}, with a value between one
7840                        and the rank of @var{ARRAY}, inclusive.  It
7841                        may not be an optional dummy argument.
7842 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
7843                        and conformable with @var{ARRAY}.
7844 @end multitable
7845
7846 @item @emph{Return value}:
7847 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7848 is a scalar.  If @var{DIM} is present, the result is an array with a
7849 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7850 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
7851 cases, the result is of the same type and kind as @var{ARRAY}.
7852
7853 @item @emph{See also}:
7854 @ref{MIN}, @ref{MINLOC}
7855
7856 @end table
7857
7858
7859
7860 @node MOD
7861 @section @code{MOD} --- Remainder function
7862 @fnindex MOD
7863 @fnindex AMOD
7864 @fnindex DMOD
7865 @cindex remainder
7866 @cindex division, remainder
7867
7868 @table @asis
7869 @item @emph{Description}:
7870 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7871 calculated as @code{A - (INT(A/P) * P)}.
7872
7873 @item @emph{Standard}:
7874 Fortran 77 and later
7875
7876 @item @emph{Class}:
7877 Elemental function
7878
7879 @item @emph{Syntax}:
7880 @code{RESULT = MOD(A, P)}
7881
7882 @item @emph{Arguments}:
7883 @multitable @columnfractions .15 .70
7884 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7885 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7886 equal to zero
7887 @end multitable
7888
7889 @item @emph{Return value}:
7890 The kind of the return value is the result of cross-promoting
7891 the kinds of the arguments.
7892
7893 @item @emph{Example}:
7894 @smallexample
7895 program test_mod
7896   print *, mod(17,3)
7897   print *, mod(17.5,5.5)
7898   print *, mod(17.5d0,5.5)
7899   print *, mod(17.5,5.5d0)
7900
7901   print *, mod(-17,3)
7902   print *, mod(-17.5,5.5)
7903   print *, mod(-17.5d0,5.5)
7904   print *, mod(-17.5,5.5d0)
7905
7906   print *, mod(17,-3)
7907   print *, mod(17.5,-5.5)
7908   print *, mod(17.5d0,-5.5)
7909   print *, mod(17.5,-5.5d0)
7910 end program test_mod
7911 @end smallexample
7912
7913 @item @emph{Specific names}:
7914 @multitable @columnfractions .20 .20 .20 .25
7915 @item Name             @tab Arguments      @tab Return type    @tab Standard
7916 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
7917 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
7918 @end multitable
7919 @end table
7920
7921
7922
7923 @node MODULO
7924 @section @code{MODULO} --- Modulo function
7925 @fnindex MODULO
7926 @cindex modulo
7927 @cindex division, modulo
7928
7929 @table @asis
7930 @item @emph{Description}:
7931 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7932
7933 @item @emph{Standard}:
7934 Fortran 95 and later
7935
7936 @item @emph{Class}:
7937 Elemental function
7938
7939 @item @emph{Syntax}:
7940 @code{RESULT = MODULO(A, P)}
7941
7942 @item @emph{Arguments}:
7943 @multitable @columnfractions .15 .70
7944 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7945 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7946 @end multitable
7947
7948 @item @emph{Return value}:
7949 The type and kind of the result are those of the arguments.
7950 @table @asis
7951 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7952 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7953 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7954 (exclusive).
7955 @item If @var{A} and @var{P} are of type @code{REAL}:
7956 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7957 @end table
7958 In all cases, if @var{P} is zero the result is processor-dependent.
7959
7960 @item @emph{Example}:
7961 @smallexample
7962 program test_modulo
7963   print *, modulo(17,3)
7964   print *, modulo(17.5,5.5)
7965
7966   print *, modulo(-17,3)
7967   print *, modulo(-17.5,5.5)
7968
7969   print *, modulo(17,-3)
7970   print *, modulo(17.5,-5.5)
7971 end program
7972 @end smallexample
7973
7974 @end table
7975
7976
7977
7978 @node MOVE_ALLOC
7979 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7980 @fnindex MOVE_ALLOC
7981 @cindex moving allocation
7982 @cindex allocation, moving
7983
7984 @table @asis
7985 @item @emph{Description}:
7986 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7987 @var{DEST}.  @var{SRC} will become deallocated in the process.
7988
7989 @item @emph{Standard}:
7990 Fortran 2003 and later
7991
7992 @item @emph{Class}:
7993 Subroutine
7994
7995 @item @emph{Syntax}:
7996 @code{CALL MOVE_ALLOC(SRC, DEST)}
7997
7998 @item @emph{Arguments}:
7999 @multitable @columnfractions .15 .70
8000 @item @var{SRC}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8001                       of any type and kind.
8002 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8003                       of the same type, kind and rank as @var{SRC}
8004 @end multitable
8005
8006 @item @emph{Return value}:
8007 None
8008
8009 @item @emph{Example}:
8010 @smallexample
8011 program test_move_alloc
8012     integer, allocatable :: a(:), b(:)
8013
8014     allocate(a(3))
8015     a = [ 1, 2, 3 ]
8016     call move_alloc(a, b)
8017     print *, allocated(a), allocated(b)
8018     print *, b
8019 end program test_move_alloc
8020 @end smallexample
8021 @end table
8022
8023
8024
8025 @node MVBITS
8026 @section @code{MVBITS} --- Move bits from one integer to another
8027 @fnindex MVBITS
8028 @cindex bits, move
8029
8030 @table @asis
8031 @item @emph{Description}:
8032 Moves @var{LEN} bits from positions @var{FROMPOS} through
8033 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8034 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8035 affected by the movement of bits is unchanged. The values of
8036 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8037 @code{BIT_SIZE(FROM)}.
8038
8039 @item @emph{Standard}:
8040 Fortran 95 and later
8041
8042 @item @emph{Class}:
8043 Elemental subroutine
8044
8045 @item @emph{Syntax}:
8046 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8047
8048 @item @emph{Arguments}:
8049 @multitable @columnfractions .15 .70
8050 @item @var{FROM}    @tab The type shall be @code{INTEGER}.
8051 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8052 @item @var{LEN}     @tab The type shall be @code{INTEGER}.
8053 @item @var{TO}      @tab The type shall be @code{INTEGER}, of the
8054                          same kind as @var{FROM}.
8055 @item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
8056 @end multitable
8057
8058 @item @emph{See also}:
8059 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8060 @end table
8061
8062
8063
8064 @node NEAREST
8065 @section @code{NEAREST} --- Nearest representable number
8066 @fnindex NEAREST
8067 @cindex real number, nearest different
8068 @cindex floating point, nearest different
8069
8070 @table @asis
8071 @item @emph{Description}:
8072 @code{NEAREST(X, S)} returns the processor-representable number nearest
8073 to @code{X} in the direction indicated by the sign of @code{S}.
8074
8075 @item @emph{Standard}:
8076 Fortran 95 and later
8077
8078 @item @emph{Class}:
8079 Elemental function
8080
8081 @item @emph{Syntax}:
8082 @code{RESULT = NEAREST(X, S)}
8083
8084 @item @emph{Arguments}:
8085 @multitable @columnfractions .15 .70
8086 @item @var{X} @tab Shall be of type @code{REAL}.
8087 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8088 not equal to zero.
8089 @end multitable
8090
8091 @item @emph{Return value}:
8092 The return value is of the same type as @code{X}. If @code{S} is
8093 positive, @code{NEAREST} returns the processor-representable number
8094 greater than @code{X} and nearest to it. If @code{S} is negative,
8095 @code{NEAREST} returns the processor-representable number smaller than
8096 @code{X} and nearest to it.
8097
8098 @item @emph{Example}:
8099 @smallexample
8100 program test_nearest
8101   real :: x, y
8102   x = nearest(42.0, 1.0)
8103   y = nearest(42.0, -1.0)
8104   write (*,"(3(G20.15))") x, y, x - y
8105 end program test_nearest
8106 @end smallexample
8107 @end table
8108
8109
8110
8111 @node NEW_LINE
8112 @section @code{NEW_LINE} --- New line character
8113 @fnindex NEW_LINE
8114 @cindex newline
8115 @cindex output, newline
8116
8117 @table @asis
8118 @item @emph{Description}:
8119 @code{NEW_LINE(C)} returns the new-line character.
8120
8121 @item @emph{Standard}:
8122 Fortran 2003 and later
8123
8124 @item @emph{Class}:
8125 Inquiry function
8126
8127 @item @emph{Syntax}:
8128 @code{RESULT = NEW_LINE(C)}
8129
8130 @item @emph{Arguments}:
8131 @multitable @columnfractions .15 .70
8132 @item @var{C}    @tab The argument shall be a scalar or array of the
8133                       type @code{CHARACTER}.
8134 @end multitable
8135
8136 @item @emph{Return value}:
8137 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8138 the same kind as parameter @var{C}.
8139
8140 @item @emph{Example}:
8141 @smallexample
8142 program newline
8143   implicit none
8144   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8145 end program newline
8146 @end smallexample
8147 @end table
8148
8149
8150
8151 @node NINT
8152 @section @code{NINT} --- Nearest whole number
8153 @fnindex NINT
8154 @fnindex IDNINT
8155 @cindex rounding, nearest whole number
8156
8157 @table @asis
8158 @item @emph{Description}:
8159 @code{NINT(X)} rounds its argument to the nearest whole number.
8160
8161 @item @emph{Standard}:
8162 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8163
8164 @item @emph{Class}:
8165 Elemental function
8166
8167 @item @emph{Syntax}:
8168 @code{RESULT = NINT(X [, KIND])}
8169
8170 @item @emph{Arguments}:
8171 @multitable @columnfractions .15 .70
8172 @item @var{X}    @tab The type of the argument shall be @code{REAL}.
8173 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8174                       expression indicating the kind parameter of
8175                       the result.
8176 @end multitable
8177
8178 @item @emph{Return value}:
8179 Returns @var{A} with the fractional portion of its magnitude eliminated by
8180 rounding to the nearest whole number and with its sign preserved,
8181 converted to an @code{INTEGER} of the default kind.
8182
8183 @item @emph{Example}:
8184 @smallexample
8185 program test_nint
8186   real(4) x4
8187   real(8) x8
8188   x4 = 1.234E0_4
8189   x8 = 4.321_8
8190   print *, nint(x4), idnint(x8)
8191 end program test_nint
8192 @end smallexample
8193
8194 @item @emph{Specific names}:
8195 @multitable @columnfractions .25 .25 .25
8196 @item Name             @tab Argument         @tab Standard
8197 @item @code{IDNINT(X)} @tab @code{REAL(8)}   @tab Fortran 95 and later
8198 @end multitable
8199
8200 @item @emph{See also}:
8201 @ref{CEILING}, @ref{FLOOR}
8202
8203 @end table
8204
8205
8206
8207 @node NOT
8208 @section @code{NOT} --- Logical negation
8209 @fnindex NOT
8210 @cindex bits, negate
8211 @cindex bitwise logical not
8212 @cindex logical not, bitwise
8213
8214 @table @asis
8215 @item @emph{Description}:
8216 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8217
8218 @item @emph{Standard}:
8219 Fortran 95 and later
8220
8221 @item @emph{Class}:
8222 Elemental function
8223
8224 @item @emph{Syntax}:
8225 @code{RESULT = NOT(I)}
8226
8227 @item @emph{Arguments}:
8228 @multitable @columnfractions .15 .70
8229 @item @var{I} @tab The type shall be @code{INTEGER}.
8230 @end multitable
8231
8232 @item @emph{Return value}:
8233 The return type is @code{INTEGER}, of the same kind as the
8234 argument.
8235
8236 @item @emph{See also}:
8237 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8238
8239 @end table
8240
8241
8242
8243 @node NULL
8244 @section @code{NULL} --- Function that returns an disassociated pointer
8245 @fnindex NULL
8246 @cindex pointer, status
8247 @cindex pointer, disassociated
8248
8249 @table @asis
8250 @item @emph{Description}:
8251 Returns a disassociated pointer.
8252
8253 If @var{MOLD} is present, a dissassociated pointer of the same type is
8254 returned, otherwise the type is determined by context.
8255
8256 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8257 includes cases where it is required.
8258
8259 @item @emph{Standard}:
8260 Fortran 95 and later
8261
8262 @item @emph{Class}:
8263 Transformational function
8264
8265 @item @emph{Syntax}:
8266 @code{PTR => NULL([MOLD])}
8267
8268 @item @emph{Arguments}:
8269 @multitable @columnfractions .15 .70
8270 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8271 status and of any type.
8272 @end multitable
8273
8274 @item @emph{Return value}:
8275 A disassociated pointer.
8276
8277 @item @emph{Example}:
8278 @smallexample
8279 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8280 @end smallexample
8281
8282 @item @emph{See also}:
8283 @ref{ASSOCIATED}
8284 @end table
8285
8286
8287
8288 @node OR
8289 @section @code{OR} --- Bitwise logical OR
8290 @fnindex OR
8291 @cindex bitwise logical or
8292 @cindex logical or, bitwise
8293
8294 @table @asis
8295 @item @emph{Description}:
8296 Bitwise logical @code{OR}.
8297
8298 This intrinsic routine is provided for backwards compatibility with
8299 GNU Fortran 77.  For integer arguments, programmers should consider
8300 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8301
8302 @item @emph{Standard}:
8303 GNU extension
8304
8305 @item @emph{Class}:
8306 Function
8307
8308 @item @emph{Syntax}:
8309 @code{RESULT = OR(X, Y)}
8310
8311 @item @emph{Arguments}:
8312 @multitable @columnfractions .15 .70
8313 @item @var{X} @tab The type shall be either a scalar @code{INTEGER}
8314 type or a scalar @code{LOGICAL} type.
8315 @item @var{Y} @tab The type shall be the same as the type of @var{X}.
8316 @end multitable
8317
8318 @item @emph{Return value}:
8319 The return type is either a scalar @code{INTEGER} or a scalar
8320 @code{LOGICAL}.  If the kind type parameters differ, then the
8321 smaller kind type is implicitly converted to larger kind, and the
8322 return has the larger kind.
8323
8324 @item @emph{Example}:
8325 @smallexample
8326 PROGRAM test_or
8327   LOGICAL :: T = .TRUE., F = .FALSE.
8328   INTEGER :: a, b
8329   DATA a / Z'F' /, b / Z'3' /
8330
8331   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8332   WRITE (*,*) OR(a, b)
8333 END PROGRAM
8334 @end smallexample
8335
8336 @item @emph{See also}:
8337 Fortran 95 elemental function: @ref{IOR}
8338 @end table
8339
8340
8341
8342 @node PACK
8343 @section @code{PACK} --- Pack an array into an array of rank one
8344 @fnindex PACK
8345 @cindex array, packing
8346 @cindex array, reduce dimension
8347 @cindex array, gather elements
8348
8349 @table @asis
8350 @item @emph{Description}:
8351 Stores the elements of @var{ARRAY} in an array of rank one.
8352
8353 The beginning of the resulting array is made up of elements whose @var{MASK}
8354 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8355 @var{VECTOR}.
8356
8357 @item @emph{Standard}:
8358 Fortran 95 and later
8359
8360 @item @emph{Class}:
8361 Transformational function
8362
8363 @item @emph{Syntax}:
8364 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8365
8366 @item @emph{Arguments}:
8367 @multitable @columnfractions .15 .70
8368 @item @var{ARRAY}  @tab Shall be an array of any type.
8369 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
8370 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8371 scalar.
8372 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8373 as @var{ARRAY} and of rank one. If present, the number of elements in
8374 @var{VECTOR} shall be equal to or greater than the number of true elements
8375 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8376 @var{VECTOR} shall be equal to or greater than the number of elements in
8377 @var{ARRAY}.
8378 @end multitable
8379
8380 @item @emph{Return value}:
8381 The result is an array of rank one and the same type as that of @var{ARRAY}.
8382 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8383 number of @code{TRUE} values in @var{MASK} otherwise.
8384
8385 @item @emph{Example}:
8386 Gathering nonzero elements from an array:
8387 @smallexample
8388 PROGRAM test_pack_1
8389   INTEGER :: m(6)
8390   m = (/ 1, 0, 0, 0, 5, 0 /)
8391   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
8392 END PROGRAM
8393 @end smallexample
8394
8395 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8396 @smallexample
8397 PROGRAM test_pack_2
8398   INTEGER :: m(4)
8399   m = (/ 1, 0, 0, 2 /)
8400   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
8401 END PROGRAM
8402 @end smallexample
8403
8404 @item @emph{See also}:
8405 @ref{UNPACK}
8406 @end table
8407
8408
8409
8410 @node PERROR
8411 @section @code{PERROR} --- Print system error message
8412 @fnindex PERROR
8413 @cindex system, error handling
8414
8415 @table @asis
8416 @item @emph{Description}:
8417 Prints (on the C @code{stderr} stream) a newline-terminated error
8418 message corresponding to the last system error. This is prefixed by
8419 @var{STRING}, a colon and a space. See @code{perror(3)}.
8420
8421 @item @emph{Standard}:
8422 GNU extension
8423
8424 @item @emph{Class}:
8425 Subroutine
8426
8427 @item @emph{Syntax}:
8428 @code{CALL PERROR(STRING)}
8429
8430 @item @emph{Arguments}:
8431 @multitable @columnfractions .15 .70
8432 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8433 default kind.
8434 @end multitable
8435
8436 @item @emph{See also}:
8437 @ref{IERRNO}
8438 @end table
8439
8440
8441
8442 @node PRECISION
8443 @section @code{PRECISION} --- Decimal precision of a real kind
8444 @fnindex PRECISION
8445 @cindex model representation, precision
8446
8447 @table @asis
8448 @item @emph{Description}:
8449 @code{PRECISION(X)} returns the decimal precision in the model of the
8450 type of @code{X}.
8451
8452 @item @emph{Standard}:
8453 Fortran 95 and later
8454
8455 @item @emph{Class}:
8456 Inquiry function
8457
8458 @item @emph{Syntax}:
8459 @code{RESULT = PRECISION(X)}
8460
8461 @item @emph{Arguments}:
8462 @multitable @columnfractions .15 .70
8463 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8464 @end multitable
8465
8466 @item @emph{Return value}:
8467 The return value is of type @code{INTEGER} and of the default integer
8468 kind.
8469
8470 @item @emph{Example}:
8471 @smallexample
8472 program prec_and_range
8473   real(kind=4) :: x(2)
8474   complex(kind=8) :: y
8475
8476   print *, precision(x), range(x)
8477   print *, precision(y), range(y)
8478 end program prec_and_range
8479 @end smallexample
8480 @end table
8481
8482
8483
8484 @node PRESENT
8485 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8486 @fnindex PRESENT
8487
8488 @table @asis
8489 @item @emph{Description}:
8490 Determines whether an optional dummy argument is present.
8491
8492 @item @emph{Standard}:
8493 Fortran 95 and later
8494
8495 @item @emph{Class}:
8496 Inquiry function
8497
8498 @item @emph{Syntax}:
8499 @code{RESULT = PRESENT(A)}
8500
8501 @item @emph{Arguments}:
8502 @multitable @columnfractions .15 .70
8503 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8504 value, or a dummy procedure. It shall be the name of an optional dummy argument
8505 accessible within the current subroutine or function.
8506 @end multitable
8507
8508 @item @emph{Return value}:
8509 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8510 @code{FALSE} otherwise.
8511
8512 @item @emph{Example}:
8513 @smallexample
8514 PROGRAM test_present
8515   WRITE(*,*) f(), f(42)      ! "F T"
8516 CONTAINS
8517   LOGICAL FUNCTION f(x)
8518     INTEGER, INTENT(IN), OPTIONAL :: x
8519     f = PRESENT(x)
8520   END FUNCTION
8521 END PROGRAM
8522 @end smallexample
8523 @end table
8524
8525
8526
8527 @node PRODUCT
8528 @section @code{PRODUCT} --- Product of array elements
8529 @fnindex PRODUCT
8530 @cindex array, product
8531 @cindex array, multiply elements
8532 @cindex array, conditionally multiply elements
8533 @cindex multiply array elements
8534
8535 @table @asis
8536 @item @emph{Description}:
8537 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8538 the corresponding element in @var{MASK} is @code{TRUE}.
8539
8540 @item @emph{Standard}:
8541 Fortran 95 and later
8542
8543 @item @emph{Class}:
8544 Transformational function
8545
8546 @item @emph{Syntax}:
8547 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8548 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8549
8550 @item @emph{Arguments}:
8551 @multitable @columnfractions .15 .70
8552 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8553 @code{REAL} or @code{COMPLEX}.
8554 @item @var{DIM}   @tab (Optional) shall be a scalar of type
8555 @code{INTEGER} with a value in the range from 1 to n, where n
8556 equals the rank of @var{ARRAY}.
8557 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
8558 and either be a scalar or an array of the same shape as @var{ARRAY}.
8559 @end multitable
8560
8561 @item @emph{Return value}:
8562 The result is of the same type as @var{ARRAY}.
8563
8564 If @var{DIM} is absent, a scalar with the product of all elements in
8565 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8566 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8567 dimension @var{DIM} dropped is returned.
8568
8569
8570 @item @emph{Example}:
8571 @smallexample
8572 PROGRAM test_product
8573   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8574   print *, PRODUCT(x)                    ! all elements, product = 120
8575   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8576 END PROGRAM
8577 @end smallexample
8578
8579 @item @emph{See also}:
8580 @ref{SUM}
8581 @end table
8582
8583
8584
8585 @node RADIX
8586 @section @code{RADIX} --- Base of a model number
8587 @fnindex RADIX
8588 @cindex model representation, base
8589 @cindex model representation, radix
8590
8591 @table @asis
8592 @item @emph{Description}:
8593 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8594
8595 @item @emph{Standard}:
8596 Fortran 95 and later
8597
8598 @item @emph{Class}:
8599 Inquiry function
8600
8601 @item @emph{Syntax}:
8602 @code{RESULT = RADIX(X)}
8603
8604 @item @emph{Arguments}:
8605 @multitable @columnfractions .15 .70
8606 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8607 @end multitable
8608
8609 @item @emph{Return value}:
8610 The return value is a scalar of type @code{INTEGER} and of the default
8611 integer kind.
8612
8613 @item @emph{Example}:
8614 @smallexample
8615 program test_radix
8616   print *, "The radix for the default integer kind is", radix(0)
8617   print *, "The radix for the default real kind is", radix(0.0)
8618 end program test_radix
8619 @end smallexample
8620
8621 @end table
8622
8623
8624
8625 @node RAN
8626 @section @code{RAN} --- Real pseudo-random number
8627 @fnindex RAN
8628 @cindex random number generation
8629
8630 @table @asis
8631 @item @emph{Description}:
8632 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8633 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
8634 documentation.
8635
8636 @item @emph{Standard}:
8637 GNU extension
8638
8639 @item @emph{Class}:
8640 Function
8641
8642 @item @emph{See also}:
8643 @ref{RAND}, @ref{RANDOM_NUMBER}
8644 @end table
8645
8646
8647
8648 @node RAND
8649 @section @code{RAND} --- Real pseudo-random number
8650 @fnindex RAND
8651 @cindex random number generation
8652
8653 @table @asis
8654 @item @emph{Description}:
8655 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8656 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8657 in the current sequence is returned; if @var{FLAG} is 1, the generator
8658 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8659 it is used as a new seed with @code{SRAND}.
8660
8661 This intrinsic routine is provided for backwards compatibility with
8662 GNU Fortran 77. It implements a simple modulo generator as provided
8663 by @command{g77}. For new code, one should consider the use of
8664 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8665
8666 @item @emph{Standard}:
8667 GNU extension
8668
8669 @item @emph{Class}:
8670 Function
8671
8672 @item @emph{Syntax}:
8673 @code{RESULT = RAND(FLAG)}
8674
8675 @item @emph{Arguments}:
8676 @multitable @columnfractions .15 .70
8677 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8678 @end multitable
8679
8680 @item @emph{Return value}:
8681 The return value is of @code{REAL} type and the default kind.
8682
8683 @item @emph{Example}:
8684 @smallexample
8685 program test_rand
8686   integer,parameter :: seed = 86456
8687
8688   call srand(seed)
8689   print *, rand(), rand(), rand(), rand()
8690   print *, rand(seed), rand(), rand(), rand()
8691 end program test_rand
8692 @end smallexample
8693
8694 @item @emph{See also}:
8695 @ref{SRAND}, @ref{RANDOM_NUMBER}
8696
8697 @end table
8698
8699
8700
8701 @node RANDOM_NUMBER
8702 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8703 @fnindex RANDOM_NUMBER
8704 @cindex random number generation
8705
8706 @table @asis
8707 @item @emph{Description}:
8708 Returns a single pseudorandom number or an array of pseudorandom numbers
8709 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8710
8711 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8712 Stupid) random number generator (RNG). This RNG combines:
8713 @enumerate
8714 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8715 with a period of @math{2^{32}},
8716 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8717 @item  Two 16-bit multiply-with-carry generators with a period of
8718 @math{597273182964842497 > 2^{59}}.
8719 @end enumerate
8720 The overall period exceeds @math{2^{123}}.
8721
8722 Please note, this RNG is thread safe if used within OpenMP directives,
8723 i.e., its state will be consistent while called from multiple threads.
8724 However, the KISS generator does not create random numbers in parallel
8725 from multiple sources, but in sequence from a single source. If an
8726 OpenMP-enabled application heavily relies on random numbers, one should
8727 consider employing a dedicated parallel random number generator instead.
8728
8729 @item @emph{Standard}:
8730 Fortran 95 and later
8731
8732 @item @emph{Class}:
8733 Subroutine
8734
8735 @item @emph{Syntax}:
8736 @code{RANDOM_NUMBER(HARVEST)}
8737
8738 @item @emph{Arguments}:
8739 @multitable @columnfractions .15 .70
8740 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
8741 @end multitable
8742
8743 @item @emph{Example}:
8744 @smallexample
8745 program test_random_number
8746   REAL :: r(5,5)
8747   CALL init_random_seed()         ! see example of RANDOM_SEED
8748   CALL RANDOM_NUMBER(r)
8749 end program
8750 @end smallexample
8751
8752 @item @emph{See also}:
8753 @ref{RANDOM_SEED}
8754 @end table
8755
8756
8757
8758 @node RANDOM_SEED
8759 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8760 @fnindex RANDOM_SEED
8761 @cindex random number generation, seeding
8762 @cindex seeding a random number generator
8763
8764 @table @asis
8765 @item @emph{Description}:
8766 Restarts or queries the state of the pseudorandom number generator used by
8767 @code{RANDOM_NUMBER}.
8768
8769 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8770 a default state. The example below shows how to initialize the random
8771 seed based on the system's time.
8772
8773 @item @emph{Standard}:
8774 Fortran 95 and later
8775
8776 @item @emph{Class}:
8777 Subroutine
8778
8779 @item @emph{Syntax}:
8780 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8781
8782 @item @emph{Arguments}:
8783 @multitable @columnfractions .15 .70
8784 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8785 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8786 of the arrays used with the @var{PUT} and @var{GET} arguments.
8787 @item @var{PUT}  @tab (Optional) Shall be an array of type default
8788 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8789 the array must be larger than or equal to the number returned by the
8790 @var{SIZE} argument.
8791 @item @var{GET}  @tab (Optional) Shall be an array of type default
8792 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8793 of the array must be larger than or equal to the number returned by
8794 the @var{SIZE} argument.
8795 @end multitable
8796
8797 @item @emph{Example}:
8798 @smallexample
8799 SUBROUTINE init_random_seed()
8800   INTEGER :: i, n, clock
8801   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8802
8803   CALL RANDOM_SEED(size = n)
8804   ALLOCATE(seed(n))
8805
8806   CALL SYSTEM_CLOCK(COUNT=clock)
8807
8808   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8809   CALL RANDOM_SEED(PUT = seed)
8810
8811   DEALLOCATE(seed)
8812 END SUBROUTINE
8813 @end smallexample
8814
8815 @item @emph{See also}:
8816 @ref{RANDOM_NUMBER}
8817 @end table
8818
8819
8820
8821 @node RANGE
8822 @section @code{RANGE} --- Decimal exponent range of a real kind
8823 @fnindex RANGE
8824 @cindex model representation, range
8825
8826 @table @asis
8827 @item @emph{Description}:
8828 @code{RANGE(X)} returns the decimal exponent range in the model of the
8829 type of @code{X}.
8830
8831 @item @emph{Standard}:
8832 Fortran 95 and later
8833
8834 @item @emph{Class}:
8835 Inquiry function
8836
8837 @item @emph{Syntax}:
8838 @code{RESULT = RANGE(X)}
8839
8840 @item @emph{Arguments}:
8841 @multitable @columnfractions .15 .70
8842 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8843 @end multitable
8844
8845 @item @emph{Return value}:
8846 The return value is of type @code{INTEGER} and of the default integer
8847 kind.
8848
8849 @item @emph{Example}:
8850 See @code{PRECISION} for an example.
8851 @end table
8852
8853
8854
8855 @node REAL
8856 @section @code{REAL} --- Convert to real type
8857 @fnindex REAL
8858 @fnindex REALPART
8859 @cindex conversion, to real
8860 @cindex complex numbers, real part
8861
8862 @table @asis
8863 @item @emph{Description}:
8864 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type.  The
8865 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8866 and its use is strongly discouraged.
8867
8868 @item @emph{Standard}:
8869 Fortran 77 and later
8870
8871 @item @emph{Class}:
8872 Elemental function
8873
8874 @item @emph{Syntax}:
8875 @multitable @columnfractions .80
8876 @item @code{RESULT = REAL(X [, KIND])}
8877 @item @code{RESULT = REALPART(Z)}
8878 @end multitable
8879
8880 @item @emph{Arguments}:
8881 @multitable @columnfractions .15 .70
8882 @item @var{X}    @tab Shall be @code{INTEGER}, @code{REAL}, or
8883                       @code{COMPLEX}.
8884 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8885                       expression indicating the kind parameter of
8886                       the result.
8887 @end multitable
8888
8889 @item @emph{Return value}:
8890 These functions return a @code{REAL} variable or array under
8891 the following rules:
8892
8893 @table @asis
8894 @item (A)
8895 @code{REAL(X)} is converted to a default real type if @var{X} is an
8896 integer or real variable.
8897 @item (B)
8898 @code{REAL(X)} is converted to a real type with the kind type parameter
8899 of @var{X} if @var{X} is a complex variable.
8900 @item (C)
8901 @code{REAL(X, KIND)} is converted to a real type with kind type
8902 parameter @var{KIND} if @var{X} is a complex, integer, or real
8903 variable.
8904 @end table
8905
8906 @item @emph{Example}:
8907 @smallexample
8908 program test_real
8909   complex :: x = (1.0, 2.0)
8910   print *, real(x), real(x,8), realpart(x)
8911 end program test_real
8912 @end smallexample
8913
8914 @item @emph{See also}:
8915 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8916
8917 @end table
8918
8919
8920
8921 @node RENAME
8922 @section @code{RENAME} --- Rename a file
8923 @fnindex RENAME
8924 @cindex file system, rename file
8925
8926 @table @asis
8927 @item @emph{Description}:
8928 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8929 character (@code{CHAR(0)}) can be used to mark the end of the names in
8930 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8931 names are ignored.  If the @var{STATUS} argument is supplied, it
8932 contains 0 on success or a nonzero error code upon return; see
8933 @code{rename(2)}.
8934
8935 This intrinsic is provided in both subroutine and function forms;
8936 however, only one form can be used in any given program unit.
8937
8938 @item @emph{Standard}:
8939 GNU extension
8940
8941 @item @emph{Class}:
8942 Subroutine, function
8943
8944 @item @emph{Syntax}:
8945 @multitable @columnfractions .80
8946 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8947 @item @code{STATUS = RENAME(PATH1, PATH2)}
8948 @end multitable
8949
8950 @item @emph{Arguments}:
8951 @multitable @columnfractions .15 .70
8952 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8953 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8954 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8955 @end multitable
8956
8957 @item @emph{See also}:
8958 @ref{LINK}
8959
8960 @end table
8961
8962
8963
8964 @node REPEAT
8965 @section @code{REPEAT} --- Repeated string concatenation
8966 @fnindex REPEAT
8967 @cindex string, repeat
8968 @cindex string, concatenate
8969
8970 @table @asis
8971 @item @emph{Description}:
8972 Concatenates @var{NCOPIES} copies of a string.
8973
8974 @item @emph{Standard}:
8975 Fortran 95 and later
8976
8977 @item @emph{Class}:
8978 Transformational function
8979
8980 @item @emph{Syntax}:
8981 @code{RESULT = REPEAT(STRING, NCOPIES)}
8982
8983 @item @emph{Arguments}:
8984 @multitable @columnfractions .15 .70
8985 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
8986 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
8987 @end multitable
8988
8989 @item @emph{Return value}:
8990 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8991 of @var{STRING}.
8992
8993 @item @emph{Example}:
8994 @smallexample
8995 program test_repeat
8996   write(*,*) repeat("x", 5)   ! "xxxxx"
8997 end program
8998 @end smallexample
8999 @end table
9000
9001
9002
9003 @node RESHAPE
9004 @section @code{RESHAPE} --- Function to reshape an array
9005 @fnindex RESHAPE
9006 @cindex array, change dimensions
9007 @cindex array, transmogrify
9008
9009 @table @asis
9010 @item @emph{Description}:
9011 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9012 the new array may be padded with elements from @var{PAD} or permuted
9013 as defined by @var{ORDER}.
9014
9015 @item @emph{Standard}:
9016 Fortran 95 and later
9017
9018 @item @emph{Class}:
9019 Transformational function
9020
9021 @item @emph{Syntax}:
9022 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9023
9024 @item @emph{Arguments}:
9025 @multitable @columnfractions .15 .70
9026 @item @var{SOURCE} @tab Shall be an array of any type.
9027 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
9028 array of rank one. Its values must be positive or zero.
9029 @item @var{PAD}    @tab (Optional) shall be an array of the same
9030 type as @var{SOURCE}.
9031 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
9032 and an array of the same shape as @var{SHAPE}. Its values shall
9033 be a permutation of the numbers from 1 to n, where n is the size of
9034 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9035 be assumed.
9036 @end multitable
9037
9038 @item @emph{Return value}:
9039 The result is an array of shape @var{SHAPE} with the same type as
9040 @var{SOURCE}.
9041
9042 @item @emph{Example}:
9043 @smallexample
9044 PROGRAM test_reshape
9045   INTEGER, DIMENSION(4) :: x
9046   WRITE(*,*) SHAPE(x)                       ! prints "4"
9047   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
9048 END PROGRAM
9049 @end smallexample
9050
9051 @item @emph{See also}:
9052 @ref{SHAPE}
9053 @end table
9054
9055
9056
9057 @node RRSPACING
9058 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9059 @fnindex RRSPACING
9060 @cindex real number, relative spacing
9061 @cindex floating point, relative spacing
9062
9063
9064 @table @asis
9065 @item @emph{Description}:
9066 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
9067 model numbers near @var{X}.
9068
9069 @item @emph{Standard}:
9070 Fortran 95 and later
9071
9072 @item @emph{Class}:
9073 Elemental function
9074
9075 @item @emph{Syntax}:
9076 @code{RESULT = RRSPACING(X)}
9077
9078 @item @emph{Arguments}:
9079 @multitable @columnfractions .15 .70
9080 @item @var{X} @tab Shall be of type @code{REAL}.
9081 @end multitable
9082
9083 @item @emph{Return value}:
9084 The return value is of the same type and kind as @var{X}.
9085 The value returned is equal to
9086 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9087
9088 @item @emph{See also}:
9089 @ref{SPACING}
9090 @end table
9091
9092
9093
9094 @node RSHIFT
9095 @section @code{RSHIFT} --- Right shift bits
9096 @fnindex RSHIFT
9097 @cindex bits, shift right
9098
9099 @table @asis
9100 @item @emph{Description}:
9101 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9102 bits shifted right by @var{SHIFT} places.  If the absolute value of
9103 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9104 Bits shifted out from the left end are lost; zeros are shifted in from
9105 the opposite end.
9106
9107 This function has been superseded by the @code{ISHFT} intrinsic, which
9108 is standard in Fortran 95 and later.
9109
9110 @item @emph{Standard}:
9111 GNU extension
9112
9113 @item @emph{Class}:
9114 Elemental function
9115
9116 @item @emph{Syntax}:
9117 @code{RESULT = RSHIFT(I, SHIFT)}
9118
9119 @item @emph{Arguments}:
9120 @multitable @columnfractions .15 .70
9121 @item @var{I} @tab The type shall be @code{INTEGER}.
9122 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9123 @end multitable
9124
9125 @item @emph{Return value}:
9126 The return value is of type @code{INTEGER} and of the same kind as
9127 @var{I}.
9128
9129 @item @emph{See also}:
9130 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9131
9132 @end table
9133
9134
9135
9136 @node SCALE
9137 @section @code{SCALE} --- Scale a real value
9138 @fnindex SCALE
9139 @cindex real number, scale
9140 @cindex floating point, scale
9141
9142 @table @asis
9143 @item @emph{Description}:
9144 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9145
9146 @item @emph{Standard}:
9147 Fortran 95 and later
9148
9149 @item @emph{Class}:
9150 Elemental function
9151
9152 @item @emph{Syntax}:
9153 @code{RESULT = SCALE(X, I)}
9154
9155 @item @emph{Arguments}:
9156 @multitable @columnfractions .15 .70
9157 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9158 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9159 @end multitable
9160
9161 @item @emph{Return value}:
9162 The return value is of the same type and kind as @var{X}.
9163 Its value is @code{X * RADIX(X)**I}.
9164
9165 @item @emph{Example}:
9166 @smallexample
9167 program test_scale
9168   real :: x = 178.1387e-4
9169   integer :: i = 5
9170   print *, scale(x,i), x*radix(x)**i
9171 end program test_scale
9172 @end smallexample
9173
9174 @end table
9175
9176
9177
9178 @node SCAN
9179 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9180 @fnindex SCAN
9181 @cindex string, find subset
9182
9183 @table @asis
9184 @item @emph{Description}:
9185 Scans a @var{STRING} for any of the characters in a @var{SET}
9186 of characters.
9187
9188 If @var{BACK} is either absent or equals @code{FALSE}, this function
9189 returns the position of the leftmost character of @var{STRING} that is
9190 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9191 is returned. If no character of @var{SET} is found in @var{STRING}, the
9192 result is zero.
9193
9194 @item @emph{Standard}:
9195 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9196
9197 @item @emph{Class}:
9198 Elemental function
9199
9200 @item @emph{Syntax}:
9201 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9202
9203 @item @emph{Arguments}:
9204 @multitable @columnfractions .15 .70
9205 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9206 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
9207 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
9208 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
9209                         expression indicating the kind parameter of
9210                       the result.
9211 @end multitable
9212
9213 @item @emph{Return value}:
9214 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9215 @var{KIND} is absent, the return value is of default integer kind.
9216
9217 @item @emph{Example}:
9218 @smallexample
9219 PROGRAM test_scan
9220   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
9221   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
9222   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
9223 END PROGRAM
9224 @end smallexample
9225
9226 @item @emph{See also}:
9227 @ref{INDEX intrinsic}, @ref{VERIFY}
9228 @end table
9229
9230
9231
9232 @node SECNDS
9233 @section @code{SECNDS} --- Time function
9234 @fnindex SECNDS
9235 @cindex time, elapsed
9236 @cindex elapsed time
9237
9238 @table @asis
9239 @item @emph{Description}:
9240 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9241 @var{X} is a reference time, also in seconds. If this is zero, the time in
9242 seconds from midnight is returned. This function is non-standard and its
9243 use is discouraged.
9244
9245 @item @emph{Standard}:
9246 GNU extension
9247
9248 @item @emph{Class}:
9249 Function
9250
9251 @item @emph{Syntax}:
9252 @code{RESULT = SECNDS (X)}
9253
9254 @item @emph{Arguments}:
9255 @multitable @columnfractions .15 .70
9256 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
9257 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
9258 @end multitable
9259
9260 @item @emph{Return value}:
9261 None
9262
9263 @item @emph{Example}:
9264 @smallexample
9265 program test_secnds
9266     integer :: i
9267     real(4) :: t1, t2
9268     print *, secnds (0.0)   ! seconds since midnight
9269     t1 = secnds (0.0)       ! reference time
9270     do i = 1, 10000000      ! do something
9271     end do
9272     t2 = secnds (t1)        ! elapsed time
9273     print *, "Something took ", t2, " seconds."
9274 end program test_secnds
9275 @end smallexample
9276 @end table
9277
9278
9279
9280 @node SECOND
9281 @section @code{SECOND} --- CPU time function
9282 @fnindex SECOND
9283 @cindex time, elapsed
9284 @cindex elapsed time
9285
9286 @table @asis
9287 @item @emph{Description}:
9288 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9289 seconds.  This provides the same functionality as the standard
9290 @code{CPU_TIME} intrinsic, and is only included for backwards
9291 compatibility.
9292
9293 This intrinsic is provided in both subroutine and function forms;
9294 however, only one form can be used in any given program unit.
9295
9296 @item @emph{Standard}:
9297 GNU extension
9298
9299 @item @emph{Class}:
9300 Subroutine, function
9301
9302 @item @emph{Syntax}:
9303 @multitable @columnfractions .80
9304 @item @code{CALL SECOND(TIME)}
9305 @item @code{TIME = SECOND()}
9306 @end multitable
9307
9308 @item @emph{Arguments}:
9309 @multitable @columnfractions .15 .70
9310 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
9311 @end multitable
9312
9313 @item @emph{Return value}:
9314 In either syntax, @var{TIME} is set to the process's current runtime in
9315 seconds.
9316
9317 @item @emph{See also}:
9318 @ref{CPU_TIME}
9319
9320 @end table
9321
9322
9323
9324 @node SELECTED_CHAR_KIND
9325 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9326 @fnindex SELECTED_CHAR_KIND
9327 @cindex character kind
9328 @cindex kind, character
9329
9330 @table @asis
9331 @item @emph{Description}:
9332
9333 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9334 set named @var{NAME}, if a character set with such a name is supported,
9335 or @math{-1} otherwise. Currently, supported character sets include
9336 ``ASCII'' and ``DEFAULT'', which are equivalent.
9337
9338 @item @emph{Standard}:
9339 Fortran 2003 and later
9340
9341 @item @emph{Class}:
9342 Transformational function
9343
9344 @item @emph{Syntax}:
9345 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9346
9347 @item @emph{Arguments}:
9348 @multitable @columnfractions .15 .70
9349 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9350 @end multitable
9351
9352 @item @emph{Example}:
9353 @smallexample
9354 program ascii_kind
9355   integer,parameter :: ascii = selected_char_kind("ascii")
9356   character(kind=ascii, len=26) :: s
9357
9358   s = ascii_"abcdefghijklmnopqrstuvwxyz"
9359   print *, s
9360 end program ascii_kind
9361 @end smallexample
9362 @end table
9363
9364
9365
9366 @node SELECTED_INT_KIND
9367 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9368 @fnindex SELECTED_INT_KIND
9369 @cindex integer kind
9370 @cindex kind, integer
9371
9372 @table @asis
9373 @item @emph{Description}:
9374 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
9375 type that can represent all values ranging from @math{-10^I} (exclusive)
9376 to @math{10^I} (exclusive). If there is no integer kind that accommodates
9377 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9378
9379 @item @emph{Standard}:
9380 Fortran 95 and later
9381
9382 @item @emph{Class}:
9383 Transformational function
9384
9385 @item @emph{Syntax}:
9386 @code{RESULT = SELECTED_INT_KIND(I)}
9387
9388 @item @emph{Arguments}:
9389 @multitable @columnfractions .15 .70
9390 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
9391 @end multitable
9392
9393 @item @emph{Example}:
9394 @smallexample
9395 program large_integers
9396   integer,parameter :: k5 = selected_int_kind(5)
9397   integer,parameter :: k15 = selected_int_kind(15)
9398   integer(kind=k5) :: i5
9399   integer(kind=k15) :: i15
9400
9401   print *, huge(i5), huge(i15)
9402
9403   ! The following inequalities are always true
9404   print *, huge(i5) >= 10_k5**5-1
9405   print *, huge(i15) >= 10_k15**15-1
9406 end program large_integers
9407 @end smallexample
9408 @end table
9409
9410
9411
9412 @node SELECTED_REAL_KIND
9413 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9414 @fnindex SELECTED_REAL_KIND
9415 @cindex real kind
9416 @cindex kind, real
9417
9418 @table @asis
9419 @item @emph{Description}:
9420 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
9421 with decimal precision greater of at least @code{P} digits and exponent
9422 range greater at least @code{R}.
9423
9424 @item @emph{Standard}:
9425 Fortran 95 and later
9426
9427 @item @emph{Class}:
9428 Transformational function
9429
9430 @item @emph{Syntax}:
9431 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9432
9433 @item @emph{Arguments}:
9434 @multitable @columnfractions .15 .70
9435 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9436 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9437 @end multitable
9438 At least one argument shall be present.
9439
9440 @item @emph{Return value}:
9441
9442 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9443 a real data type with decimal precision of at least @code{P} digits and a
9444 decimal exponent range of at least @code{R}. If more than one real data
9445 type meet the criteria, the kind of the data type with the smallest
9446 decimal precision is returned. If no real data type matches the criteria,
9447 the result is
9448 @table @asis
9449 @item -1 if the processor does not support a real data type with a
9450 precision greater than or equal to @code{P}
9451 @item -2 if the processor does not support a real type with an exponent
9452 range greater than or equal to @code{R}
9453 @item -3 if neither is supported.
9454 @end table
9455
9456 @item @emph{Example}:
9457 @smallexample
9458 program real_kinds
9459   integer,parameter :: p6 = selected_real_kind(6)
9460   integer,parameter :: p10r100 = selected_real_kind(10,100)
9461   integer,parameter :: r400 = selected_real_kind(r=400)
9462   real(kind=p6) :: x
9463   real(kind=p10r100) :: y
9464   real(kind=r400) :: z
9465
9466   print *, precision(x), range(x)
9467   print *, precision(y), range(y)
9468   print *, precision(z), range(z)
9469 end program real_kinds
9470 @end smallexample
9471 @end table
9472
9473
9474
9475 @node SET_EXPONENT
9476 @section @code{SET_EXPONENT} --- Set the exponent of the model
9477 @fnindex SET_EXPONENT
9478 @cindex real number, set exponent
9479 @cindex floating point, set exponent
9480
9481 @table @asis
9482 @item @emph{Description}:
9483 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9484 is that that of @var{X} and whose exponent part is @var{I}.
9485
9486 @item @emph{Standard}:
9487 Fortran 95 and later
9488
9489 @item @emph{Class}:
9490 Elemental function
9491
9492 @item @emph{Syntax}:
9493 @code{RESULT = SET_EXPONENT(X, I)}
9494
9495 @item @emph{Arguments}:
9496 @multitable @columnfractions .15 .70
9497 @item @var{X} @tab Shall be of type @code{REAL}.
9498 @item @var{I} @tab Shall be of type @code{INTEGER}.
9499 @end multitable
9500
9501 @item @emph{Return value}:
9502 The return value is of the same type and kind as @var{X}.
9503 The real number whose fractional part
9504 is that that of @var{X} and whose exponent part if @var{I} is returned;
9505 it is @code{FRACTION(X) * RADIX(X)**I}.
9506
9507 @item @emph{Example}:
9508 @smallexample
9509 PROGRAM test_setexp
9510   REAL :: x = 178.1387e-4
9511   INTEGER :: i = 17
9512   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9513 END PROGRAM
9514 @end smallexample
9515
9516 @end table
9517
9518
9519
9520 @node SHAPE
9521 @section @code{SHAPE} --- Determine the shape of an array
9522 @fnindex SHAPE
9523 @cindex array, shape
9524
9525 @table @asis
9526 @item @emph{Description}:
9527 Determines the shape of an array.
9528
9529 @item @emph{Standard}:
9530 Fortran 95 and later
9531
9532 @item @emph{Class}:
9533 Inquiry function
9534
9535 @item @emph{Syntax}:
9536 @code{RESULT = SHAPE(SOURCE)}
9537
9538 @item @emph{Arguments}:
9539 @multitable @columnfractions .15 .70
9540 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9541 If @var{SOURCE} is a pointer it must be associated and allocatable
9542 arrays must be allocated.
9543 @end multitable
9544
9545 @item @emph{Return value}:
9546 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9547 has dimensions. The elements of the resulting array correspond to the extend
9548 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9549 the result is the rank one array of size zero.
9550
9551 @item @emph{Example}:
9552 @smallexample
9553 PROGRAM test_shape
9554   INTEGER, DIMENSION(-1:1, -1:2) :: A
9555   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
9556   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
9557 END PROGRAM
9558 @end smallexample
9559
9560 @item @emph{See also}:
9561 @ref{RESHAPE}, @ref{SIZE}
9562 @end table
9563
9564
9565
9566 @node SIGN
9567 @section @code{SIGN} --- Sign copying function
9568 @fnindex SIGN
9569 @fnindex ISIGN
9570 @fnindex DSIGN
9571 @cindex sign copying
9572
9573 @table @asis
9574 @item @emph{Description}:
9575 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9576
9577 @item @emph{Standard}:
9578 Fortran 77 and later
9579
9580 @item @emph{Class}:
9581 Elemental function
9582
9583 @item @emph{Syntax}:
9584 @code{RESULT = SIGN(A, B)}
9585
9586 @item @emph{Arguments}:
9587 @multitable @columnfractions .15 .70
9588 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9589 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9590 @end multitable
9591
9592 @item @emph{Return value}:
9593 The kind of the return value is that of @var{A} and @var{B}.
9594 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9595 it is @code{-ABS(A)}.
9596
9597 @item @emph{Example}:
9598 @smallexample
9599 program test_sign
9600   print *, sign(-12,1)
9601   print *, sign(-12,0)
9602   print *, sign(-12,-1)
9603
9604   print *, sign(-12.,1.)
9605   print *, sign(-12.,0.)
9606   print *, sign(-12.,-1.)
9607 end program test_sign
9608 @end smallexample
9609
9610 @item @emph{Specific names}:
9611 @multitable @columnfractions .20 .20 .20 .25
9612 @item Name              @tab Arguments      @tab Return type    @tab Standard
9613 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9614 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9615 @end multitable
9616 @end table
9617
9618
9619
9620 @node SIGNAL
9621 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9622 @fnindex SIGNAL
9623 @cindex system, signal handling
9624
9625 @table @asis
9626 @item @emph{Description}:
9627 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9628 @var{HANDLER} to be executed with a single integer argument when signal
9629 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
9630 turn off handling of signal @var{NUMBER} or revert to its default
9631 action.  See @code{signal(2)}.
9632
9633 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9634 is supplied, it is set to the value returned by @code{signal(2)}.
9635
9636 @item @emph{Standard}:
9637 GNU extension
9638
9639 @item @emph{Class}:
9640 Subroutine, function
9641
9642 @item @emph{Syntax}:
9643 @multitable @columnfractions .80
9644 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9645 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9646 @end multitable
9647
9648 @item @emph{Arguments}:
9649 @multitable @columnfractions .15 .70
9650 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9651 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9652 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9653 @code{INTEGER}. It is @code{INTENT(IN)}.
9654 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9655 integer. It has @code{INTENT(OUT)}.
9656 @end multitable
9657
9658 @item @emph{Return value}:
9659 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9660
9661 @item @emph{Example}:
9662 @smallexample
9663 program test_signal
9664   intrinsic signal
9665   external handler_print
9666
9667   call signal (12, handler_print)
9668   call signal (10, 1)
9669
9670   call sleep (30)
9671 end program test_signal
9672 @end smallexample
9673 @end table
9674
9675
9676
9677 @node SIN
9678 @section @code{SIN} --- Sine function
9679 @fnindex SIN
9680 @fnindex DSIN
9681 @fnindex CSIN
9682 @fnindex ZSIN
9683 @fnindex CDSIN
9684 @cindex trigonometric function, sine
9685 @cindex sine
9686
9687 @table @asis
9688 @item @emph{Description}:
9689 @code{SIN(X)} computes the sine of @var{X}.
9690
9691 @item @emph{Standard}:
9692 Fortran 77 and later
9693
9694 @item @emph{Class}:
9695 Elemental function
9696
9697 @item @emph{Syntax}:
9698 @code{RESULT = SIN(X)}
9699
9700 @item @emph{Arguments}:
9701 @multitable @columnfractions .15 .70
9702 @item @var{X} @tab The type shall be @code{REAL} or
9703 @code{COMPLEX}.
9704 @end multitable
9705
9706 @item @emph{Return value}:
9707 The return value has same type and kind as @var{X}.
9708
9709 @item @emph{Example}:
9710 @smallexample
9711 program test_sin
9712   real :: x = 0.0
9713   x = sin(x)
9714 end program test_sin
9715 @end smallexample
9716
9717 @item @emph{Specific names}:
9718 @multitable @columnfractions .20 .20 .20 .25
9719 @item Name            @tab Argument          @tab Return type       @tab Standard
9720 @item @code{DSIN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
9721 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
9722 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
9723 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
9724 @end multitable
9725
9726 @item @emph{See also}:
9727 @ref{ASIN}
9728 @end table
9729
9730
9731
9732 @node SINH
9733 @section @code{SINH} --- Hyperbolic sine function
9734 @fnindex SINH
9735 @fnindex DSINH
9736 @cindex hyperbolic sine
9737 @cindex hyperbolic function, sine
9738 @cindex sine, hyperbolic
9739
9740 @table @asis
9741 @item @emph{Description}:
9742 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9743
9744 @item @emph{Standard}:
9745 Fortran 95 and later
9746
9747 @item @emph{Class}:
9748 Elemental function
9749
9750 @item @emph{Syntax}:
9751 @code{RESULT = SINH(X)}
9752
9753 @item @emph{Arguments}:
9754 @multitable @columnfractions .15 .70
9755 @item @var{X} @tab The type shall be @code{REAL}.
9756 @end multitable
9757
9758 @item @emph{Return value}:
9759 The return value is of type @code{REAL}.
9760
9761 @item @emph{Example}:
9762 @smallexample
9763 program test_sinh
9764   real(8) :: x = - 1.0_8
9765   x = sinh(x)
9766 end program test_sinh
9767 @end smallexample
9768
9769 @item @emph{Specific names}:
9770 @multitable @columnfractions .20 .20 .20 .25
9771 @item Name            @tab Argument          @tab Return type       @tab Standard
9772 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
9773 @end multitable
9774
9775 @item @emph{See also}:
9776 @ref{ASINH}
9777 @end table
9778
9779
9780
9781 @node SIZE
9782 @section @code{SIZE} --- Determine the size of an array
9783 @fnindex SIZE
9784 @cindex array, size
9785 @cindex array, number of elements
9786 @cindex array, count elements
9787
9788 @table @asis
9789 @item @emph{Description}:
9790 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9791 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9792
9793 @item @emph{Standard}:
9794 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9795
9796 @item @emph{Class}:
9797 Inquiry function
9798
9799 @item @emph{Syntax}:
9800 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9801
9802 @item @emph{Arguments}:
9803 @multitable @columnfractions .15 .70
9804 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9805 a pointer it must be associated and allocatable arrays must be allocated.
9806 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
9807 and its value shall be in the range from 1 to n, where n equals the rank
9808 of @var{ARRAY}.
9809 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9810                       expression indicating the kind parameter of
9811                       the result.
9812 @end multitable
9813
9814 @item @emph{Return value}:
9815 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9816 @var{KIND} is absent, the return value is of default integer kind.
9817
9818 @item @emph{Example}:
9819 @smallexample
9820 PROGRAM test_size
9821   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
9822 END PROGRAM
9823 @end smallexample
9824
9825 @item @emph{See also}:
9826 @ref{SHAPE}, @ref{RESHAPE}
9827 @end table
9828
9829
9830 @node SIZEOF
9831 @section @code{SIZEOF} --- Size in bytes of an expression
9832 @fnindex SIZEOF
9833 @cindex expression size
9834 @cindex size of an expression
9835
9836 @table @asis
9837 @item @emph{Description}:
9838 @code{SIZEOF(X)} calculates the number of bytes of storage the
9839 expression @code{X} occupies.
9840
9841 @item @emph{Standard}:
9842 GNU extension
9843
9844 @item @emph{Class}:
9845 Intrinsic function
9846
9847 @item @emph{Syntax}:
9848 @code{N = SIZEOF(X)}
9849
9850 @item @emph{Arguments}:
9851 @multitable @columnfractions .15 .70
9852 @item @var{X} @tab The argument shall be of any type, rank or shape.
9853 @end multitable
9854
9855 @item @emph{Return value}:
9856 The return value is of type integer and of the system-dependent kind
9857 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9858 number of bytes occupied by the argument.  If the argument has the
9859 @code{POINTER} attribute, the number of bytes of the storage area pointed
9860 to is returned.  If the argument is of a derived type with @code{POINTER}
9861 or @code{ALLOCATABLE} components, the return value doesn't account for
9862 the sizes of the data pointed to by these components.
9863
9864 @item @emph{Example}:
9865 @smallexample
9866    integer :: i
9867    real :: r, s(5)
9868    print *, (sizeof(s)/sizeof(r) == 5)
9869    end
9870 @end smallexample
9871 The example will print @code{.TRUE.} unless you are using a platform
9872 where default @code{REAL} variables are unusually padded.
9873 @end table
9874
9875 @node SLEEP
9876 @section @code{SLEEP} --- Sleep for the specified number of seconds
9877 @fnindex SLEEP
9878 @cindex delayed execution
9879
9880 @table @asis
9881 @item @emph{Description}:
9882 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9883
9884 @item @emph{Standard}:
9885 GNU extension
9886
9887 @item @emph{Class}:
9888 Subroutine
9889
9890 @item @emph{Syntax}:
9891 @code{CALL SLEEP(SECONDS)}
9892
9893 @item @emph{Arguments}:
9894 @multitable @columnfractions .15 .70
9895 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9896 @end multitable
9897
9898 @item @emph{Example}:
9899 @smallexample
9900 program test_sleep
9901   call sleep(5)
9902 end
9903 @end smallexample
9904 @end table
9905
9906
9907
9908 @node SNGL
9909 @section @code{SNGL} --- Convert double precision real to default real
9910 @fnindex SNGL
9911 @cindex conversion, to real
9912
9913 @table @asis
9914 @item @emph{Description}:
9915 @code{SNGL(A)} converts the double precision real @var{A}
9916 to a default real value. This is an archaic form of @code{REAL}
9917 that is specific to one type for @var{A}.
9918
9919 @item @emph{Standard}:
9920 Fortran 77 and later
9921
9922 @item @emph{Class}:
9923 Elemental function
9924
9925 @item @emph{Syntax}:
9926 @code{RESULT = SNGL(A)}
9927
9928 @item @emph{Arguments}:
9929 @multitable @columnfractions .15 .70
9930 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9931 @end multitable
9932
9933 @item @emph{Return value}:
9934 The return value is of type default @code{REAL}.
9935
9936 @item @emph{See also}:
9937 @ref{DBLE}
9938 @end table
9939
9940
9941
9942 @node SPACING
9943 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9944 @fnindex SPACING
9945 @cindex real number, relative spacing
9946 @cindex floating point, relative spacing
9947
9948 @table @asis
9949 @item @emph{Description}:
9950 Determines the distance between the argument @var{X} and the nearest
9951 adjacent number of the same type.
9952
9953 @item @emph{Standard}:
9954 Fortran 95 and later
9955
9956 @item @emph{Class}:
9957 Elemental function
9958
9959 @item @emph{Syntax}:
9960 @code{RESULT = SPACING(X)}
9961
9962 @item @emph{Arguments}:
9963 @multitable @columnfractions .15 .70
9964 @item @var{X} @tab Shall be of type @code{REAL}.
9965 @end multitable
9966
9967 @item @emph{Return value}:
9968 The result is of the same type as the input argument @var{X}.
9969
9970 @item @emph{Example}:
9971 @smallexample
9972 PROGRAM test_spacing
9973   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9974   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9975
9976   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
9977   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
9978 END PROGRAM
9979 @end smallexample
9980
9981 @item @emph{See also}:
9982 @ref{RRSPACING}
9983 @end table
9984
9985
9986
9987 @node SPREAD
9988 @section @code{SPREAD} --- Add a dimension to an array
9989 @fnindex SPREAD
9990 @cindex array, increase dimension
9991 @cindex array, duplicate elements
9992 @cindex array, duplicate dimensions
9993
9994 @table @asis
9995 @item @emph{Description}:
9996 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9997 dimension @var{DIM}.
9998
9999 @item @emph{Standard}:
10000 Fortran 95 and later
10001
10002 @item @emph{Class}:
10003 Transformational function
10004
10005 @item @emph{Syntax}:
10006 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10007
10008 @item @emph{Arguments}:
10009 @multitable @columnfractions .15 .70
10010 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
10011 a rank less than seven.
10012 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
10013 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10014 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10015 @end multitable
10016
10017 @item @emph{Return value}:
10018 The result is an array of the same type as @var{SOURCE} and has rank n+1
10019 where n equals the rank of @var{SOURCE}.
10020
10021 @item @emph{Example}:
10022 @smallexample
10023 PROGRAM test_spread
10024   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10025   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
10026   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
10027 END PROGRAM
10028 @end smallexample
10029
10030 @item @emph{See also}:
10031 @ref{UNPACK}
10032 @end table
10033
10034
10035
10036 @node SQRT
10037 @section @code{SQRT} --- Square-root function
10038 @fnindex SQRT
10039 @fnindex DSQRT
10040 @fnindex CSQRT
10041 @fnindex ZSQRT
10042 @fnindex CDSQRT
10043 @cindex root
10044 @cindex square-root
10045
10046 @table @asis
10047 @item @emph{Description}:
10048 @code{SQRT(X)} computes the square root of @var{X}.
10049
10050 @item @emph{Standard}:
10051 Fortran 77 and later
10052
10053 @item @emph{Class}:
10054 Elemental function
10055
10056 @item @emph{Syntax}:
10057 @code{RESULT = SQRT(X)}
10058
10059 @item @emph{Arguments}:
10060 @multitable @columnfractions .15 .70
10061 @item @var{X} @tab The type shall be @code{REAL} or
10062 @code{COMPLEX}.
10063 @end multitable
10064
10065 @item @emph{Return value}:
10066 The return value is of type @code{REAL} or @code{COMPLEX}.
10067 The kind type parameter is the same as @var{X}.
10068
10069 @item @emph{Example}:
10070 @smallexample
10071 program test_sqrt
10072   real(8) :: x = 2.0_8
10073   complex :: z = (1.0, 2.0)
10074   x = sqrt(x)
10075   z = sqrt(z)
10076 end program test_sqrt
10077 @end smallexample
10078
10079 @item @emph{Specific names}:
10080 @multitable @columnfractions .20 .20 .20 .25
10081 @item Name             @tab Argument             @tab Return type          @tab Standard
10082 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
10083 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
10084 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
10085 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
10086 @end multitable
10087 @end table
10088
10089
10090
10091 @node SRAND
10092 @section @code{SRAND} --- Reinitialize the random number generator
10093 @fnindex SRAND
10094 @cindex random number generation, seeding
10095 @cindex seeding a random number generator
10096
10097 @table @asis
10098 @item @emph{Description}:
10099 @code{SRAND} reinitializes the pseudo-random number generator
10100 called by @code{RAND} and @code{IRAND}. The new seed used by the
10101 generator is specified by the required argument @var{SEED}.
10102
10103 @item @emph{Standard}:
10104 GNU extension
10105
10106 @item @emph{Class}:
10107 Subroutine
10108
10109 @item @emph{Syntax}:
10110 @code{CALL SRAND(SEED)}
10111
10112 @item @emph{Arguments}:
10113 @multitable @columnfractions .15 .70
10114 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10115 @end multitable
10116
10117 @item @emph{Return value}:
10118 Does not return.
10119
10120 @item @emph{Example}:
10121 See @code{RAND} and @code{IRAND} for examples.
10122
10123 @item @emph{Notes}:
10124 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10125 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10126 to generate pseudo-random numbers. Please note that in
10127 GNU Fortran, these two sets of intrinsics (@code{RAND},
10128 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10129 @code{RANDOM_SEED} on the other hand) access two independent
10130 pseudo-random number generators.
10131
10132 @item @emph{See also}:
10133 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10134
10135 @end table
10136
10137
10138
10139 @node STAT
10140 @section @code{STAT} --- Get file status
10141 @fnindex STAT
10142 @cindex file system, file status
10143
10144 @table @asis
10145 @item @emph{Description}:
10146 This function returns information about a file. No permissions are required on
10147 the file itself, but execute (search) permission is required on all of the
10148 directories in path that lead to the file.
10149
10150 The elements that are obtained and stored in the array @code{BUFF}:
10151 @multitable @columnfractions .15 .70
10152 @item @code{buff(1)}   @tab  Device ID
10153 @item @code{buff(2)}   @tab  Inode number
10154 @item @code{buff(3)}   @tab  File mode
10155 @item @code{buff(4)}   @tab  Number of links
10156 @item @code{buff(5)}   @tab  Owner's uid
10157 @item @code{buff(6)}   @tab  Owner's gid
10158 @item @code{buff(7)}   @tab  ID of device containing directory entry for file (0 if not available)
10159 @item @code{buff(8)}   @tab  File size (bytes)
10160 @item @code{buff(9)}   @tab  Last access time
10161 @item @code{buff(10)}  @tab  Last modification time
10162 @item @code{buff(11)}  @tab  Last file status change time
10163 @item @code{buff(12)}  @tab  Preferred I/O block size (-1 if not available)
10164 @item @code{buff(13)}  @tab  Number of blocks allocated (-1 if not available)
10165 @end multitable
10166
10167 Not all these elements are relevant on all systems.
10168 If an element is not relevant, it is returned as 0.
10169
10170 This intrinsic is provided in both subroutine and function forms; however,
10171 only one form can be used in any given program unit.
10172
10173 @item @emph{Standard}:
10174 GNU extension
10175
10176 @item @emph{Class}:
10177 Subroutine, function
10178
10179 @item @emph{Syntax}:
10180 @code{CALL STAT(FILE,BUFF[,STATUS])}
10181
10182 @item @emph{Arguments}:
10183 @multitable @columnfractions .15 .70
10184 @item @var{FILE}   @tab The type shall be @code{CHARACTER}, of the
10185 default kind and a valid path within the file system.
10186 @item @var{BUFF}   @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10187 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10188                         on success and a system specific error code otherwise.
10189 @end multitable
10190
10191 @item @emph{Example}:
10192 @smallexample
10193 PROGRAM test_stat
10194   INTEGER, DIMENSION(13) :: buff
10195   INTEGER :: status
10196
10197   CALL STAT("/etc/passwd", buff, status)
10198
10199   IF (status == 0) THEN
10200     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
10201     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
10202     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
10203     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
10204     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
10205     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
10206     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
10207     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
10208     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
10209     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
10210     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10211     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
10212     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10213   END IF
10214 END PROGRAM
10215 @end smallexample
10216
10217 @item @emph{See also}:
10218 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10219 @end table
10220
10221
10222
10223 @node SUM
10224 @section @code{SUM} --- Sum of array elements
10225 @fnindex SUM
10226 @cindex array, sum
10227 @cindex array, add elements
10228 @cindex array, conditionally add elements
10229 @cindex sum array elements
10230
10231 @table @asis
10232 @item @emph{Description}:
10233 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10234 the corresponding element in @var{MASK} is @code{TRUE}.
10235
10236 @item @emph{Standard}:
10237 Fortran 95 and later
10238
10239 @item @emph{Class}:
10240 Transformational function
10241
10242 @item @emph{Syntax}:
10243 @code{RESULT = SUM(ARRAY[, MASK])}
10244 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10245
10246 @item @emph{Arguments}:
10247 @multitable @columnfractions .15 .70
10248 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10249 @code{REAL} or @code{COMPLEX}.
10250 @item @var{DIM}   @tab (Optional) shall be a scalar of type
10251 @code{INTEGER} with a value in the range from 1 to n, where n
10252 equals the rank of @var{ARRAY}.
10253 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
10254 and either be a scalar or an array of the same shape as @var{ARRAY}.
10255 @end multitable
10256
10257 @item @emph{Return value}:
10258 The result is of the same type as @var{ARRAY}.
10259
10260 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10261 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10262 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10263 dropped is returned.
10264
10265 @item @emph{Example}:
10266 @smallexample
10267 PROGRAM test_sum
10268   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10269   print *, SUM(x)                        ! all elements, sum = 15
10270   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
10271 END PROGRAM
10272 @end smallexample
10273
10274 @item @emph{See also}:
10275 @ref{PRODUCT}
10276 @end table
10277
10278
10279
10280 @node SYMLNK
10281 @section @code{SYMLNK} --- Create a symbolic link
10282 @fnindex SYMLNK
10283 @cindex file system, create link
10284 @cindex file system, soft link
10285
10286 @table @asis
10287 @item @emph{Description}:
10288 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10289 character (@code{CHAR(0)}) can be used to mark the end of the names in
10290 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10291 names are ignored.  If the @var{STATUS} argument is supplied, it
10292 contains 0 on success or a nonzero error code upon return; see
10293 @code{symlink(2)}.  If the system does not supply @code{symlink(2)},
10294 @code{ENOSYS} is returned.
10295
10296 This intrinsic is provided in both subroutine and function forms;
10297 however, only one form can be used in any given program unit.
10298
10299 @item @emph{Standard}:
10300 GNU extension
10301
10302 @item @emph{Class}:
10303 Subroutine, function
10304
10305 @item @emph{Syntax}:
10306 @multitable @columnfractions .80
10307 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10308 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10309 @end multitable
10310
10311 @item @emph{Arguments}:
10312 @multitable @columnfractions .15 .70
10313 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10314 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10315 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10316 @end multitable
10317
10318 @item @emph{See also}:
10319 @ref{LINK}, @ref{UNLINK}
10320
10321 @end table
10322
10323
10324
10325 @node SYSTEM
10326 @section @code{SYSTEM} --- Execute a shell command
10327 @fnindex SYSTEM
10328 @cindex system, system call
10329
10330 @table @asis
10331 @item @emph{Description}:
10332 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10333 argument @var{STATUS} is present, it contains the value returned by
10334 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10335 Note that which shell is used to invoke the command is system-dependent
10336 and environment-dependent.
10337
10338 This intrinsic is provided in both subroutine and function forms;
10339 however, only one form can be used in any given program unit.
10340
10341 @item @emph{Standard}:
10342 GNU extension
10343
10344 @item @emph{Class}:
10345 Subroutine, function
10346
10347 @item @emph{Syntax}:
10348 @multitable @columnfractions .80
10349 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10350 @item @code{STATUS = SYSTEM(COMMAND)}
10351 @end multitable
10352
10353 @item @emph{Arguments}:
10354 @multitable @columnfractions .15 .70
10355 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10356 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
10357 @end multitable
10358
10359 @item @emph{See also}:
10360 @end table
10361
10362
10363
10364 @node SYSTEM_CLOCK
10365 @section @code{SYSTEM_CLOCK} --- Time function
10366 @fnindex SYSTEM_CLOCK
10367 @cindex time, clock ticks
10368 @cindex clock ticks
10369
10370 @table @asis
10371 @item @emph{Description}:
10372 Determines the @var{COUNT} of milliseconds of wall clock time since
10373 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10374 @var{COUNT_RATE} determines the number of clock ticks per second.
10375 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10376 @command{gfortran}.
10377
10378 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10379 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10380
10381 @item @emph{Standard}:
10382 Fortran 95 and later
10383
10384 @item @emph{Class}:
10385 Subroutine
10386
10387 @item @emph{Syntax}:
10388 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10389
10390 @item @emph{Arguments}:
10391 @item @emph{Arguments}:
10392 @multitable @columnfractions .15 .70
10393 @item @var{COUNT}      @tab (Optional) shall be a scalar of type default
10394 @code{INTEGER} with @code{INTENT(OUT)}.
10395 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10396 @code{INTEGER} with @code{INTENT(OUT)}.
10397 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type default
10398 @code{INTEGER} with @code{INTENT(OUT)}.
10399 @end multitable
10400
10401 @item @emph{Example}:
10402 @smallexample
10403 PROGRAM test_system_clock
10404   INTEGER :: count, count_rate, count_max
10405   CALL SYSTEM_CLOCK(count, count_rate, count_max)
10406   WRITE(*,*) count, count_rate, count_max
10407 END PROGRAM
10408 @end smallexample
10409
10410 @item @emph{See also}:
10411 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10412 @end table
10413
10414
10415
10416 @node TAN
10417 @section @code{TAN} --- Tangent function
10418 @fnindex TAN
10419 @fnindex DTAN
10420 @cindex trigonometric function, tangent
10421 @cindex tangent
10422
10423 @table @asis
10424 @item @emph{Description}:
10425 @code{TAN(X)} computes the tangent of @var{X}.
10426
10427 @item @emph{Standard}:
10428 Fortran 77 and later
10429
10430 @item @emph{Class}:
10431 Elemental function
10432
10433 @item @emph{Syntax}:
10434 @code{RESULT = TAN(X)}
10435
10436 @item @emph{Arguments}:
10437 @multitable @columnfractions .15 .70
10438 @item @var{X} @tab The type shall be @code{REAL}.
10439 @end multitable
10440
10441 @item @emph{Return value}:
10442 The return value is of type @code{REAL}.  The kind type parameter is
10443 the same as @var{X}.
10444
10445 @item @emph{Example}:
10446 @smallexample
10447 program test_tan
10448   real(8) :: x = 0.165_8
10449   x = tan(x)
10450 end program test_tan
10451 @end smallexample
10452
10453 @item @emph{Specific names}:
10454 @multitable @columnfractions .20 .20 .20 .25
10455 @item Name            @tab Argument          @tab Return type       @tab Standard
10456 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
10457 @end multitable
10458
10459 @item @emph{See also}:
10460 @ref{ATAN}
10461 @end table
10462
10463
10464
10465 @node TANH
10466 @section @code{TANH} --- Hyperbolic tangent function
10467 @fnindex TANH
10468 @fnindex DTANH
10469 @cindex hyperbolic tangent
10470 @cindex hyperbolic function, tangent
10471 @cindex tangent, hyperbolic
10472
10473 @table @asis
10474 @item @emph{Description}:
10475 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10476
10477 @item @emph{Standard}:
10478 Fortran 77 and later
10479
10480 @item @emph{Class}:
10481 Elemental function
10482
10483 @item @emph{Syntax}:
10484 @code{X = TANH(X)}
10485
10486 @item @emph{Arguments}:
10487 @multitable @columnfractions .15 .70
10488 @item @var{X} @tab The type shall be @code{REAL}.
10489 @end multitable
10490
10491 @item @emph{Return value}:
10492 The return value is of type @code{REAL} and lies in the range
10493 @math{ - 1 \leq tanh(x) \leq 1 }.
10494
10495 @item @emph{Example}:
10496 @smallexample
10497 program test_tanh
10498   real(8) :: x = 2.1_8
10499   x = tanh(x)
10500 end program test_tanh
10501 @end smallexample
10502
10503 @item @emph{Specific names}:
10504 @multitable @columnfractions .20 .20 .20 .25
10505 @item Name            @tab Argument          @tab Return type       @tab Standard
10506 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
10507 @end multitable
10508
10509 @item @emph{See also}:
10510 @ref{ATANH}
10511 @end table
10512
10513
10514
10515 @node TIME
10516 @section @code{TIME} --- Time function
10517 @fnindex TIME
10518 @cindex time, current
10519 @cindex current time
10520
10521 @table @asis
10522 @item @emph{Description}:
10523 Returns the current time encoded as an integer (in the manner of the
10524 UNIX function @code{time(3)}). This value is suitable for passing to
10525 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10526
10527 This intrinsic is not fully portable, such as to systems with 32-bit
10528 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10529 the values returned by this intrinsic might be, or become, negative, or
10530 numerically less than previous values, during a single run of the
10531 compiled program.
10532
10533 See @ref{TIME8}, for information on a similar intrinsic that might be
10534 portable to more GNU Fortran implementations, though to fewer Fortran
10535 compilers.
10536
10537 @item @emph{Standard}:
10538 GNU extension
10539
10540 @item @emph{Class}:
10541 Function
10542
10543 @item @emph{Syntax}:
10544 @code{RESULT = TIME()}
10545
10546 @item @emph{Return value}:
10547 The return value is a scalar of type @code{INTEGER(4)}.
10548
10549 @item @emph{See also}:
10550 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10551
10552 @end table
10553
10554
10555
10556 @node TIME8
10557 @section @code{TIME8} --- Time function (64-bit)
10558 @fnindex TIME8
10559 @cindex time, current
10560 @cindex current time
10561
10562 @table @asis
10563 @item @emph{Description}:
10564 Returns the current time encoded as an integer (in the manner of the
10565 UNIX function @code{time(3)}). This value is suitable for passing to
10566 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10567
10568 @emph{Warning:} this intrinsic does not increase the range of the timing
10569 values over that returned by @code{time(3)}. On a system with a 32-bit
10570 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10571 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10572 overflows of the 32-bit value can still occur. Therefore, the values
10573 returned by this intrinsic might be or become negative or numerically
10574 less than previous values during a single run of the compiled program.
10575
10576 @item @emph{Standard}:
10577 GNU extension
10578
10579 @item @emph{Class}:
10580 Function
10581
10582 @item @emph{Syntax}:
10583 @code{RESULT = TIME8()}
10584
10585 @item @emph{Return value}:
10586 The return value is a scalar of type @code{INTEGER(8)}.
10587
10588 @item @emph{See also}:
10589 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10590
10591 @end table
10592
10593
10594
10595 @node TINY
10596 @section @code{TINY} --- Smallest positive number of a real kind
10597 @fnindex TINY
10598 @cindex limits, smallest number
10599 @cindex model representation, smallest number
10600
10601 @table @asis
10602 @item @emph{Description}:
10603 @code{TINY(X)} returns the smallest positive (non zero) number
10604 in the model of the type of @code{X}.
10605
10606 @item @emph{Standard}:
10607 Fortran 95 and later
10608
10609 @item @emph{Class}:
10610 Inquiry function
10611
10612 @item @emph{Syntax}:
10613 @code{RESULT = TINY(X)}
10614
10615 @item @emph{Arguments}:
10616 @multitable @columnfractions .15 .70
10617 @item @var{X} @tab Shall be of type @code{REAL}.
10618 @end multitable
10619
10620 @item @emph{Return value}:
10621 The return value is of the same type and kind as @var{X}
10622
10623 @item @emph{Example}:
10624 See @code{HUGE} for an example.
10625 @end table
10626
10627
10628
10629 @node TRANSFER
10630 @section @code{TRANSFER} --- Transfer bit patterns
10631 @fnindex TRANSFER
10632 @cindex bits, move
10633 @cindex type cast
10634
10635 @table @asis
10636 @item @emph{Description}:
10637 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10638 is the representation of a variable or array of the same type and type
10639 parameters as @var{MOLD}.
10640
10641 This is approximately equivalent to the C concept of @emph{casting} one
10642 type to another.
10643
10644 @item @emph{Standard}:
10645 Fortran 95 and later
10646
10647 @item @emph{Class}:
10648 Transformational function
10649
10650 @item @emph{Syntax}:
10651 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10652
10653 @item @emph{Arguments}:
10654 @multitable @columnfractions .15 .70
10655 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10656 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
10657 @item @var{SIZE}   @tab (Optional) shall be a scalar of type
10658 @code{INTEGER}.
10659 @end multitable
10660
10661 @item @emph{Return value}:
10662 The result has the same type as @var{MOLD}, with the bit level
10663 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
10664 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
10665 but @var{MOLD} is an array (of any size or shape), the result is a one-
10666 dimensional array of the minimum length needed to contain the entirety
10667 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
10668 and @var{MOLD} is a scalar, the result is a scalar.
10669
10670 If the bitwise representation of the result is longer than that of
10671 @var{SOURCE}, then the leading bits of the result correspond to those of
10672 @var{SOURCE} and any trailing bits are filled arbitrarily.
10673
10674 When the resulting bit representation does not correspond to a valid
10675 representation of a variable of the same type as @var{MOLD}, the results
10676 are undefined, and subsequent operations on the result cannot be
10677 guaranteed to produce sensible behavior.  For example, it is possible to
10678 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10679 @code{.NOT.@var{VAR}} both appear to be true.
10680
10681 @item @emph{Example}:
10682 @smallexample
10683 PROGRAM test_transfer
10684   integer :: x = 2143289344
10685   print *, transfer(x, 1.0)    ! prints "NaN" on i686
10686 END PROGRAM
10687 @end smallexample
10688 @end table
10689
10690
10691
10692 @node TRANSPOSE
10693 @section @code{TRANSPOSE} --- Transpose an array of rank two
10694 @fnindex TRANSPOSE
10695 @cindex array, transpose
10696 @cindex matrix, transpose
10697 @cindex transpose
10698
10699 @table @asis
10700 @item @emph{Description}:
10701 Transpose an array of rank two. Element (i, j) of the result has the value
10702 @code{MATRIX(j, i)}, for all i, j.
10703
10704 @item @emph{Standard}:
10705 Fortran 95 and later
10706
10707 @item @emph{Class}:
10708 Transformational function
10709
10710 @item @emph{Syntax}:
10711 @code{RESULT = TRANSPOSE(MATRIX)}
10712
10713 @item @emph{Arguments}:
10714 @multitable @columnfractions .15 .70
10715 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10716 @end multitable
10717
10718 @item @emph{Return value}:
10719 The result has the same type as @var{MATRIX}, and has shape
10720 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10721 @end table
10722
10723
10724
10725 @node TRIM
10726 @section @code{TRIM} --- Remove trailing blank characters of a string
10727 @fnindex TRIM
10728 @cindex string, remove trailing whitespace
10729
10730 @table @asis
10731 @item @emph{Description}:
10732 Removes trailing blank characters of a string.
10733
10734 @item @emph{Standard}:
10735 Fortran 95 and later
10736
10737 @item @emph{Class}:
10738 Transformational function
10739
10740 @item @emph{Syntax}:
10741 @code{RESULT = TRIM(STRING)}
10742
10743 @item @emph{Arguments}:
10744 @multitable @columnfractions .15 .70
10745 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
10746 @end multitable
10747
10748 @item @emph{Return value}:
10749 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
10750 less the number of trailing blanks.
10751
10752 @item @emph{Example}:
10753 @smallexample
10754 PROGRAM test_trim
10755   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
10756   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
10757 END PROGRAM
10758 @end smallexample
10759
10760 @item @emph{See also}:
10761 @ref{ADJUSTL}, @ref{ADJUSTR}
10762 @end table
10763
10764
10765
10766 @node TTYNAM
10767 @section @code{TTYNAM} --- Get the name of a terminal device.
10768 @fnindex TTYNAM
10769 @cindex system, terminal
10770
10771 @table @asis
10772 @item @emph{Description}:
10773 Get the name of a terminal device. For more information,
10774 see @code{ttyname(3)}.
10775
10776 This intrinsic is provided in both subroutine and function forms;
10777 however, only one form can be used in any given program unit.
10778
10779 @item @emph{Standard}:
10780 GNU extension
10781
10782 @item @emph{Class}:
10783 Subroutine, function
10784
10785 @item @emph{Syntax}:
10786 @multitable @columnfractions .80
10787 @item @code{CALL TTYNAM(UNIT, NAME)}
10788 @item @code{NAME = TTYNAM(UNIT)}
10789 @end multitable
10790
10791 @item @emph{Arguments}:
10792 @multitable @columnfractions .15 .70
10793 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
10794 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
10795 @end multitable
10796
10797 @item @emph{Example}:
10798 @smallexample
10799 PROGRAM test_ttynam
10800   INTEGER :: unit
10801   DO unit = 1, 10
10802     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10803   END DO
10804 END PROGRAM
10805 @end smallexample
10806
10807 @item @emph{See also}:
10808 @ref{ISATTY}
10809 @end table
10810
10811
10812
10813 @node UBOUND
10814 @section @code{UBOUND} --- Upper dimension bounds of an array
10815 @fnindex UBOUND
10816 @cindex array, upper bound
10817
10818 @table @asis
10819 @item @emph{Description}:
10820 Returns the upper bounds of an array, or a single upper bound
10821 along the @var{DIM} dimension.
10822 @item @emph{Standard}:
10823 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10824
10825 @item @emph{Class}:
10826 Inquiry function
10827
10828 @item @emph{Syntax}:
10829 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10830
10831 @item @emph{Arguments}:
10832 @multitable @columnfractions .15 .70
10833 @item @var{ARRAY} @tab Shall be an array, of any type.
10834 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
10835 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10836                      expression indicating the kind parameter of
10837                      the result.
10838 @end multitable
10839
10840 @item @emph{Return value}:
10841 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10842 @var{KIND} is absent, the return value is of default integer kind.
10843 If @var{DIM} is absent, the result is an array of the upper bounds of
10844 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
10845 corresponding to the upper bound of the array along that dimension.  If
10846 @var{ARRAY} is an expression rather than a whole array or array
10847 structure component, or if it has a zero extent along the relevant
10848 dimension, the upper bound is taken to be the number of elements along
10849 the relevant dimension.
10850
10851 @item @emph{See also}:
10852 @ref{LBOUND}
10853 @end table
10854
10855
10856
10857 @node UMASK
10858 @section @code{UMASK} --- Set the file creation mask
10859 @fnindex UMASK
10860 @cindex file system, file creation mask
10861
10862 @table @asis
10863 @item @emph{Description}:
10864 Sets the file creation mask to @var{MASK} and returns the old value in
10865 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10866
10867 @item @emph{Standard}:
10868 GNU extension
10869
10870 @item @emph{Class}:
10871 Subroutine
10872
10873 @item @emph{Syntax}:
10874 @code{CALL UMASK(MASK [, OLD])}
10875
10876 @item @emph{Arguments}:
10877 @multitable @columnfractions .15 .70
10878 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
10879 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10880                       @code{INTEGER}.
10881 @end multitable
10882
10883 @end table
10884
10885
10886
10887 @node UNLINK
10888 @section @code{UNLINK} --- Remove a file from the file system
10889 @fnindex UNLINK
10890 @cindex file system, remove file
10891
10892 @table @asis
10893 @item @emph{Description}:
10894 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10895 used to mark the end of the name in @var{PATH}; otherwise, trailing
10896 blanks in the file name are ignored.  If the @var{STATUS} argument is
10897 supplied, it contains 0 on success or a nonzero error code upon return;
10898 see @code{unlink(2)}.
10899
10900 This intrinsic is provided in both subroutine and function forms;
10901 however, only one form can be used in any given program unit.
10902
10903 @item @emph{Standard}:
10904 GNU extension
10905
10906 @item @emph{Class}:
10907 Subroutine, function
10908
10909 @item @emph{Syntax}:
10910 @multitable @columnfractions .80
10911 @item @code{CALL UNLINK(PATH [, STATUS])}
10912 @item @code{STATUS = UNLINK(PATH)}
10913 @end multitable
10914
10915 @item @emph{Arguments}:
10916 @multitable @columnfractions .15 .70
10917 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10918 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10919 @end multitable
10920
10921 @item @emph{See also}:
10922 @ref{LINK}, @ref{SYMLNK}
10923 @end table
10924
10925
10926
10927 @node UNPACK
10928 @section @code{UNPACK} --- Unpack an array of rank one into an array
10929 @fnindex UNPACK
10930 @cindex array, unpacking
10931 @cindex array, increase dimension
10932 @cindex array, scatter elements
10933
10934 @table @asis
10935 @item @emph{Description}:
10936 Store the elements of @var{VECTOR} in an array of higher rank.
10937
10938 @item @emph{Standard}:
10939 Fortran 95 and later
10940
10941 @item @emph{Class}:
10942 Transformational function
10943
10944 @item @emph{Syntax}:
10945 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10946
10947 @item @emph{Arguments}:
10948 @multitable @columnfractions .15 .70
10949 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10950 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10951 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
10952 @item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
10953 the same shape as @var{MASK}.
10954 @end multitable
10955
10956 @item @emph{Return value}:
10957 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10958 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10959
10960 @item @emph{Example}:
10961 @smallexample
10962 PROGRAM test_unpack
10963   integer :: vector(2)  = (/1,1/)
10964   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10965   integer :: field(2,2) = 0, unity(2,2)
10966
10967   ! result: unity matrix
10968   unity = unpack(vector, reshape(mask, (/2,2/)), field)
10969 END PROGRAM
10970 @end smallexample
10971
10972 @item @emph{See also}:
10973 @ref{PACK}, @ref{SPREAD}
10974 @end table
10975
10976
10977
10978 @node VERIFY
10979 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10980 @fnindex VERIFY
10981 @cindex string, find missing set
10982
10983 @table @asis
10984 @item @emph{Description}:
10985 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10986
10987 If @var{BACK} is either absent or equals @code{FALSE}, this function
10988 returns the position of the leftmost character of @var{STRING} that is
10989 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10990 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10991 result is zero.
10992
10993 @item @emph{Standard}:
10994 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10995
10996 @item @emph{Class}:
10997 Elemental function
10998
10999 @item @emph{Syntax}:
11000 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11001
11002 @item @emph{Arguments}:
11003 @multitable @columnfractions .15 .70
11004 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11005 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
11006 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
11007 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
11008                         expression indicating the kind parameter of
11009                         the result.
11010 @end multitable
11011
11012 @item @emph{Return value}:
11013 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11014 @var{KIND} is absent, the return value is of default integer kind.
11015
11016 @item @emph{Example}:
11017 @smallexample
11018 PROGRAM test_verify
11019   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
11020   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
11021   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
11022   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
11023   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
11024 END PROGRAM
11025 @end smallexample
11026
11027 @item @emph{See also}:
11028 @ref{SCAN}, @ref{INDEX intrinsic}
11029 @end table
11030
11031
11032
11033 @node XOR
11034 @section @code{XOR} --- Bitwise logical exclusive OR
11035 @fnindex XOR
11036 @cindex bitwise logical exclusive or
11037 @cindex logical exclusive or, bitwise
11038
11039 @table @asis
11040 @item @emph{Description}:
11041 Bitwise logical exclusive or.
11042
11043 This intrinsic routine is provided for backwards compatibility with
11044 GNU Fortran 77.  For integer arguments, programmers should consider
11045 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
11046
11047 @item @emph{Standard}:
11048 GNU extension
11049
11050 @item @emph{Class}:
11051 Function
11052
11053 @item @emph{Syntax}:
11054 @code{RESULT = XOR(X, Y)}
11055
11056 @item @emph{Arguments}:
11057 @multitable @columnfractions .15 .70
11058 @item @var{X} @tab The type shall be either  a scalar @code{INTEGER}
11059 type or a scalar @code{LOGICAL} type.
11060 @item @var{Y} @tab The type shall be the same as the type of @var{I}.
11061 @end multitable
11062
11063 @item @emph{Return value}:
11064 The return type is either a scalar @code{INTEGER} or a scalar
11065 @code{LOGICAL}.  If the kind type parameters differ, then the
11066 smaller kind type is implicitly converted to larger kind, and the
11067 return has the larger kind.
11068
11069 @item @emph{Example}:
11070 @smallexample
11071 PROGRAM test_xor
11072   LOGICAL :: T = .TRUE., F = .FALSE.
11073   INTEGER :: a, b
11074   DATA a / Z'F' /, b / Z'3' /
11075
11076   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11077   WRITE (*,*) XOR(a, b)
11078 END PROGRAM
11079 @end smallexample
11080
11081 @item @emph{See also}:
11082 Fortran 95 elemental function: @ref{IEOR}
11083 @end table
11084
11085
11086
11087 @node Intrinsic Modules
11088 @chapter Intrinsic Modules
11089 @cindex intrinsic Modules
11090
11091 @c @node ISO_FORTRAN_ENV
11092 @section @code{ISO_FORTRAN_ENV}
11093 @table @asis
11094 @item @emph{Standard}:
11095 Fortran 2003 and later
11096 @end table
11097
11098 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11099 named constants:
11100
11101 @table @asis
11102 @item @code{CHARACTER_STORAGE_SIZE}:
11103 Size in bits of the character storage unit.
11104
11105 @item @code{ERROR_UNIT}:
11106 Identifies the preconnected unit used for error reporting.
11107
11108 @item @code{FILE_STORAGE_SIZE}:
11109 Size in bits of the file-storage unit.
11110
11111 @item @code{INPUT_UNIT}:
11112 Identifies the preconnected unit identified by the asterisk
11113 (@code{*}) in @code{READ} statement.
11114
11115 @item @code{IOSTAT_END}:
11116 The value assigned to the variable passed to the IOSTAT= specifier of
11117 an input/output statement if an end-of-file condition occurred.
11118
11119 @item @code{IOSTAT_EOR}:
11120 The value assigned to the variable passed to the IOSTAT= specifier of
11121 an input/output statement if an end-of-record condition occurred.
11122
11123 @item @code{NUMERIC_STORAGE_SIZE}:
11124 The size in bits of the numeric storage unit.
11125
11126 @item @code{OUTPUT_UNIT}:
11127 Identifies the preconnected unit identified by the asterisk
11128 (@code{*}) in @code{WRITE} statement.
11129 @end table
11130
11131 @c @node ISO_C_BINDING
11132 @section @code{ISO_C_BINDING}
11133 @table @asis
11134 @item @emph{Standard}:
11135 Fortran 2003 and later, GNU extensions
11136 @end table
11137
11138 The following intrinsic procedures are provided by the module; their
11139 definition can be found in the section Intrinsic Procedures of this
11140 manual.
11141
11142 @table @asis
11143 @item @code{C_ASSOCIATED}
11144 @item @code{C_F_POINTER}
11145 @item @code{C_F_PROCPOINTER}
11146 @item @code{C_FUNLOC}
11147 @item @code{C_LOC}
11148 @end table
11149
11150 The @code{ISO_C_BINDING} module provides the following named constants of the
11151 type integer, which can be used as KIND type parameter. Note that GNU
11152 Fortran currently does not support the @code{C_INT_FAST...} KIND type
11153 parameters (marked by an asterisk (@code{*}) in the list below).
11154 The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
11155 and cannot be used as KIND type parameter of the @code{INTEGER} type.
11156
11157 In addition to the integer named constants required by the Fortran 2003
11158 standard, GNU Fortran provides as an extension named constants for the
11159 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11160 C_INT_LEAST128_T, C_INT_FAST128_T}.
11161
11162 @multitable @columnfractions .15 .35 .35 .35
11163 @item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
11164 @item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
11165 @item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
11166 @item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
11167 @item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
11168 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
11169 @item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
11170 @item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
11171 @item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
11172 @item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
11173 @item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
11174 @item @code{INTEGER}@tab @code{C_INT128_T}       @tab @code{int128_t}                      @tab Ext.
11175 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
11176 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11177 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11178 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11179 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T} @tab @code{int_least128_t}                @tab Ext.
11180 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}*  @tab @code{int_fast8_t}
11181 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
11182 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
11183 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
11184 @item @code{INTEGER}@tab @code{C_INT_FAST128_T}* @tab @code{int_fast128_t}                 @tab Ext.
11185 @item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
11186 @item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
11187 @item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
11188 @item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
11189 @item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
11190 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11191 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11192 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11193 @item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
11194 @item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
11195 @end multitable
11196
11197 Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
11198 defined.
11199
11200 @multitable @columnfractions .20 .45 .15
11201 @item Name                     @tab C definition    @tab Value
11202 @item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
11203 @item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
11204 @item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
11205 @item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
11206 @item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
11207 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11208 @item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
11209 @item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
11210 @end multitable
11211
11212 @c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11213 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11214 @table @asis
11215 @item @emph{Standard}:
11216 OpenMP Application Program Interface v2.5
11217 @end table
11218
11219
11220 The OpenMP Fortran runtime library routines are provided both in
11221 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11222 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11223 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11224 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11225 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11226 below.
11227
11228 For details refer to the actual
11229 @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
11230 OpenMP Application Program Interface v2.5}.
11231
11232 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11233 named constants:
11234
11235 @table @asis
11236 @item @code{omp_integer_kind}
11237 @item @code{omp_logical_kind}
11238 @item @code{omp_lock_kind}
11239 @item @code{omp_nest_lock_kind}
11240 @end table