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