gcc/fortran/intrinsic.texi

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