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.3 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,     Inverse hyperbolic cosine 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,     Inverse hyperbolic sine 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,     Inverse hyperbolic tangent 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{BGE}:           BGE,       Bitwise greater than or equal to
  71 * @code{BGT}:           BGT,       Bitwise greater than
  72 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  73 * @code{BLE}:           BLE,       Bitwise less than or equal to
  74 * @code{BLT}:           BLT,       Bitwise less than
  75 * @code{BTEST}:         BTEST,     Bit test function
  76 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
  77 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
  78 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
  79 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
  80 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
  81 * @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
  82 * @code{CEILING}:       CEILING,   Integer ceiling function
  83 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
  84 * @code{CHDIR}:         CHDIR,     Change working directory
  85 * @code{CHMOD}:         CHMOD,     Change access permissions of files
  86 * @code{CMPLX}:         CMPLX,     Complex conversion function
  87 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
  88 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
  89 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
  90 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
  91 * @code{CONJG}:         CONJG,     Complex conjugate function
  92 * @code{COS}:           COS,       Cosine function
  93 * @code{COSH}:          COSH,      Hyperbolic cosine function
  94 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
  95 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  96 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
  97 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
  98 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
  99 * @code{DBLE}:          DBLE,      Double precision conversion function
 100 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
 101 * @code{DIGITS}:        DIGITS,    Significant digits function
 102 * @code{DIM}:           DIM,       Positive difference
 103 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
 104 * @code{DPROD}:         DPROD,     Double product function
 105 * @code{DREAL}:         DREAL,     Double real part function
 106 * @code{DSHIFTL}:       DSHIFTL,   Combined left shift
 107 * @code{DSHIFTR}:       DSHIFTR,   Combined right shift
 108 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 109 * @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
 110 * @code{EPSILON}:       EPSILON,   Epsilon function
 111 * @code{ERF}:           ERF,       Error function
 112 * @code{ERFC}:          ERFC,      Complementary error function
 113 * @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
 114 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
 115 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
 116 * @code{EXIT}:          EXIT,      Exit the program with status.
 117 * @code{EXP}:           EXP,       Exponential function
 118 * @code{EXPONENT}:      EXPONENT,  Exponent function
 119 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF,  Query dynamic type for extension
 120 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
 121 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
 122 * @code{FGETC}:         FGETC,     Read a single character in stream mode
 123 * @code{FLOOR}:         FLOOR,     Integer floor function
 124 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
 125 * @code{FNUM}:          FNUM,      File number function
 126 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
 127 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
 128 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
 129 * @code{FREE}:          FREE,      Memory de-allocation subroutine
 130 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
 131 * @code{FSTAT}:         FSTAT,     Get file status
 132 * @code{FTELL}:         FTELL,     Current stream position
 133 * @code{GAMMA}:         GAMMA,     Gamma function
 134 * @code{GERROR}:        GERROR,    Get last system error message
 135 * @code{GETARG}:        GETARG,    Get command line arguments
 136 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
 137 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
 138 * @code{GETCWD}:        GETCWD,    Get current working directory
 139 * @code{GETENV}:        GETENV,    Get an environmental variable
 140 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
 141 * @code{GETGID}:        GETGID,    Group ID function
 142 * @code{GETLOG}:        GETLOG,    Get login name
 143 * @code{GETPID}:        GETPID,    Process ID function
 144 * @code{GETUID}:        GETUID,    User ID function
 145 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
 146 * @code{HOSTNM}:        HOSTNM,    Get system host name
 147 * @code{HUGE}:          HUGE,      Largest number of a kind
 148 * @code{HYPOT}:         HYPOT,     Euclidean distance function
 149 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
 150 * @code{IALL}:          IALL,      Bitwise AND of array elements
 151 * @code{IAND}:          IAND,      Bitwise logical and
 152 * @code{IANY}:          IANY,      Bitwise OR of array elements
 153 * @code{IARGC}:         IARGC,     Get the number of command line arguments
 154 * @code{IBCLR}:         IBCLR,     Clear bit
 155 * @code{IBITS}:         IBITS,     Bit extraction
 156 * @code{IBSET}:         IBSET,     Set bit
 157 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
 158 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
 159 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
 160 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
 161 * @code{IMAGE_INDEX}:   IMAGE_INDEX, Cosubscript to image index conversion
 162 * @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
 163 * @code{INT}:           INT,       Convert to integer type
 164 * @code{INT2}:          INT2,      Convert to 16-bit integer type
 165 * @code{INT8}:          INT8,      Convert to 64-bit integer type
 166 * @code{IOR}:           IOR,       Bitwise logical or
 167 * @code{IPARITY}:       IPARITY,   Bitwise XOR of array elements
 168 * @code{IRAND}:         IRAND,     Integer pseudo-random number
 169 * @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
 170 * @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
 171 * @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
 172 * @code{ISHFT}:         ISHFT,     Shift bits
 173 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
 174 * @code{ISNAN}:         ISNAN,     Tests for a NaN
 175 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
 176 * @code{KILL}:          KILL,      Send a signal to a process
 177 * @code{KIND}:          KIND,      Kind of an entity
 178 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
 179 * @code{LCOBOUND}:      LCOBOUND,  Lower codimension bounds of an array
 180 * @code{LEADZ}:         LEADZ,     Number of leading zero bits of an integer
 181 * @code{LEN}:           LEN,       Length of a character entity
 182 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
 183 * @code{LGE}:           LGE,       Lexical greater than or equal
 184 * @code{LGT}:           LGT,       Lexical greater than
 185 * @code{LINK}:          LINK,      Create a hard link
 186 * @code{LLE}:           LLE,       Lexical less than or equal
 187 * @code{LLT}:           LLT,       Lexical less than
 188 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
 189 * @code{LOC}:           LOC,       Returns the address of a variable
 190 * @code{LOG}:           LOG,       Logarithm function
 191 * @code{LOG10}:         LOG10,     Base 10 logarithm function
 192 * @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
 193 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
 194 * @code{LONG}:          LONG,      Convert to integer type
 195 * @code{LSHIFT}:        LSHIFT,    Left shift bits
 196 * @code{LSTAT}:         LSTAT,     Get file status
 197 * @code{LTIME}:         LTIME,     Convert time to local time info
 198 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
 199 * @code{MASKL}:         MASKL,     Left justified mask
 200 * @code{MASKR}:         MASKR,     Right justified mask
 201 * @code{MATMUL}:        MATMUL,    matrix multiplication
 202 * @code{MAX}:           MAX,       Maximum value of an argument list
 203 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
 204 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
 205 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
 206 * @code{MCLOCK}:        MCLOCK,    Time function
 207 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
 208 * @code{MERGE}:         MERGE,     Merge arrays
 209 * @code{MERGE_BITS}:    MERGE_BITS, Merge of bits under mask
 210 * @code{MIN}:           MIN,       Minimum value of an argument list
 211 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
 212 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
 213 * @code{MINVAL}:        MINVAL,    Minimum value of an array
 214 * @code{MOD}:           MOD,       Remainder function
 215 * @code{MODULO}:        MODULO,    Modulo function
 216 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
 217 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
 218 * @code{NEAREST}:       NEAREST,   Nearest representable number
 219 * @code{NEW_LINE}:      NEW_LINE,  New line character
 220 * @code{NINT}:          NINT,      Nearest whole number
 221 * @code{NORM2}:         NORM2,     Euclidean vector norm
 222 * @code{NOT}:           NOT,       Logical negation
 223 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
 224 * @code{NUM_IMAGES}:    NUM_IMAGES, Number of images
 225 * @code{OR}:            OR,        Bitwise logical OR
 226 * @code{PACK}:          PACK,      Pack an array into an array of rank one
 227 * @code{PARITY}:        PARITY,    Reduction with exclusive OR
 228 * @code{PERROR}:        PERROR,    Print system error message
 229 * @code{POPCNT}:        POPCNT,    Number of bits set
 230 * @code{POPPAR}:        POPPAR,    Parity of the number of bits set
 231 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
 232 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
 233 * @code{PRODUCT}:       PRODUCT,   Product of array elements
 234 * @code{RADIX}:         RADIX,     Base of a data model
 235 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
 236 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
 237 * @code{RAND}:          RAND,      Real pseudo-random number
 238 * @code{RANGE}:         RANGE,     Decimal exponent range
 239 * @code{RAN}:           RAN,       Real pseudo-random number
 240 * @code{REAL}:          REAL,      Convert to real type
 241 * @code{RENAME}:        RENAME,    Rename a file
 242 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
 243 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
 244 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
 245 * @code{RSHIFT}:        RSHIFT,    Right shift bits
 246 * @code{SAME_TYPE_AS}:  SAME_TYPE_AS,  Query dynamic types for equality
 247 * @code{SCALE}:         SCALE,     Scale a real value
 248 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
 249 * @code{SECNDS}:        SECNDS,    Time function
 250 * @code{SECOND}:        SECOND,    CPU time function
 251 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
 252 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
 253 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
 254 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
 255 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
 256 * @code{SHIFTA}:        SHIFTA,    Right shift with fill
 257 * @code{SHIFTL}:        SHIFTL,    Left shift
 258 * @code{SHIFTR}:        SHIFTR,    Right shift
 259 * @code{SIGN}:          SIGN,      Sign copying function
 260 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
 261 * @code{SIN}:           SIN,       Sine function
 262 * @code{SINH}:          SINH,      Hyperbolic sine function
 263 * @code{SIZE}:          SIZE,      Function to determine the size of an array
 264 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
 265 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
 266 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
 267 * @code{SPREAD}:        SPREAD,    Add a dimension to an array
 268 * @code{SQRT}:          SQRT,      Square-root function
 269 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
 270 * @code{STAT}:          STAT,      Get file status
 271 * @code{STORAGE_SIZE}:  STORAGE_SIZE, Storage size in bits
 272 * @code{SUM}:           SUM,       Sum of array elements
 273 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
 274 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
 275 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
 276 * @code{TAN}:           TAN,       Tangent function
 277 * @code{TANH}:          TANH,      Hyperbolic tangent function
 278 * @code{THIS_IMAGE}:    THIS_IMAGE, Cosubscript index of this image
 279 * @code{TIME}:          TIME,      Time function
 280 * @code{TIME8}:         TIME8,     Time function (64-bit)
 281 * @code{TINY}:          TINY,      Smallest positive number of a real kind
 282 * @code{TRAILZ}:        TRAILZ,    Number of trailing zero bits of an integer
 283 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
 284 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
 285 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
 286 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
 287 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
 288 * @code{UCOBOUND}:      UCOBOUND,  Upper codimension bounds of an array
 289 * @code{UMASK}:         UMASK,     Set the file creation mask
 290 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
 291 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
 292 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
 293 * @code{XOR}:           XOR,       Bitwise logical exclusive or
 294 @end menu
 295
 296 @node Introduction to Intrinsics
 297 @section Introduction to intrinsic procedures
 298
 299 The intrinsic procedures provided by GNU Fortran include all of the
 300 intrinsic procedures required by the Fortran 95 standard, a set of
 301 intrinsic procedures for backwards compatibility with G77, and a
 302 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
 303 standards.  Any conflict between a description here and a description in
 304 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
 305 2008 standard is unintentional, and the standard(s) should be considered
 306 authoritative.
 307
 308 The enumeration of the @code{KIND} type parameter is processor defined in
 309 the Fortran 95 standard.  GNU Fortran defines the default integer type and
 310 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 311 respectively.  The standard mandates that both data types shall have
 312 another kind, which have more precision.  On typical target architectures
 313 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 314 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 315 In the description of generic intrinsic procedures, the kind type parameter
 316 will be specified by @code{KIND=*}, and in the description of specific
 317 names for an intrinsic procedure the kind type parameter will be explicitly
 318 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 319 brevity the optional @code{KIND=} syntax will be omitted.
 320
 321 Many of the intrinsic procedures take one or more optional arguments.
 322 This document follows the convention used in the Fortran 95 standard,
 323 and denotes such arguments by square brackets.
 324
 325 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
 326 which can be used to restrict the set of intrinsic procedures to a
 327 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 328 option, and so all intrinsic procedures described here are accepted.  There
 329 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 330 implemented both a function and a subroutine.  Both classes
 331 have been implemented in @command{gfortran} for backwards compatibility
 332 with @command{g77}.  It is noted here that these functions and subroutines
 333 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 334 the applicable standard for each intrinsic procedure is noted.
 335
 336
 337
 338 @node ABORT
 339 @section @code{ABORT} --- Abort the program
 340 @fnindex ABORT
 341 @cindex program termination, with core dump
 342 @cindex terminate program, with core dump
 343 @cindex core, dump
 344
 345 @table @asis
 346 @item @emph{Description}:
 347 @code{ABORT} causes immediate termination of the program.  On operating
 348 systems that support a core dump, @code{ABORT} will produce a core dump even if
 349 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
 350 purposes.
 351 @c TODO: Check if this (with -fno-dump-core) is correct.
 352
 353 @item @emph{Standard}:
 354 GNU extension
 355
 356 @item @emph{Class}:
 357 Subroutine
 358
 359 @item @emph{Syntax}:
 360 @code{CALL ABORT}
 361
 362 @item @emph{Return value}:
 363 Does not return.
 364
 365 @item @emph{Example}:
 366 @smallexample
 367 program test_abort
 368   integer :: i = 1, j = 2
 369   if (i /= j) call abort
 370 end program test_abort
 371 @end smallexample
 372
 373 @item @emph{See also}:
 374 @ref{EXIT}, @ref{KILL}
 375
 376 @end table
 377
 378
 379
 380 @node ABS
 381 @section @code{ABS} --- Absolute value
 382 @fnindex ABS
 383 @fnindex CABS
 384 @fnindex DABS
 385 @fnindex IABS
 386 @fnindex ZABS
 387 @fnindex CDABS
 388 @cindex absolute value
 389
 390 @table @asis
 391 @item @emph{Description}:
 392 @code{ABS(A)} computes the absolute value of @code{A}.
 393
 394 @item @emph{Standard}:
 395 Fortran 77 and later, has overloads that are GNU extensions
 396
 397 @item @emph{Class}:
 398 Elemental function
 399
 400 @item @emph{Syntax}:
 401 @code{RESULT = ABS(A)}
 402
 403 @item @emph{Arguments}:
 404 @multitable @columnfractions .15 .70
 405 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
 406 @code{REAL}, or @code{COMPLEX}.
 407 @end multitable
 408
 409 @item @emph{Return value}:
 410 The return value is of the same type and
 411 kind as the argument except the return value is @code{REAL} for a
 412 @code{COMPLEX} argument.
 413
 414 @item @emph{Example}:
 415 @smallexample
 416 program test_abs
 417   integer :: i = -1
 418   real :: x = -1.e0
 419   complex :: z = (-1.e0,0.e0)
 420   i = abs(i)
 421   x = abs(x)
 422   x = abs(z)
 423 end program test_abs
 424 @end smallexample
 425
 426 @item @emph{Specific names}:
 427 @multitable @columnfractions .20 .20 .20 .25
 428 @item Name            @tab Argument            @tab Return type       @tab Standard
 429 @item @code{ABS(A)}   @tab @code{REAL(4) A}    @tab @code{REAL(4)}    @tab Fortran 77 and later
 430 @item @code{CABS(A)}  @tab @code{COMPLEX(4) A} @tab @code{REAL(4)}    @tab Fortran 77 and later
 431 @item @code{DABS(A)}  @tab @code{REAL(8) A}    @tab @code{REAL(8)}    @tab Fortran 77 and later
 432 @item @code{IABS(A)}  @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
 433 @item @code{ZABS(A)}  @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
 434 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
 435 @end multitable
 436 @end table
 437
 438
 439
 440 @node ACCESS
 441 @section @code{ACCESS} --- Checks file access modes
 442 @fnindex ACCESS
 443 @cindex file system, access mode
 444
 445 @table @asis
 446 @item @emph{Description}:
 447 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
 448 exists, is readable, writable or executable. Except for the
 449 executable check, @code{ACCESS} can be replaced by
 450 Fortran 95's @code{INQUIRE}.
 451
 452 @item @emph{Standard}:
 453 GNU extension
 454
 455 @item @emph{Class}:
 456 Inquiry function
 457
 458 @item @emph{Syntax}:
 459 @code{RESULT = ACCESS(NAME, MODE)}
 460
 461 @item @emph{Arguments}:
 462 @multitable @columnfractions .15 .70
 463 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
 464 file name. Tailing blank are ignored unless the character @code{achar(0)}
 465 is present, then all characters up to and excluding @code{achar(0)} are
 466 used as file name.
 467 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
 468 file access mode, may be any concatenation of @code{"r"} (readable),
 469 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
 470 for existence.
 471 @end multitable
 472
 473 @item @emph{Return value}:
 474 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
 475 accessible in the given mode; otherwise or if an invalid argument
 476 has been given for @code{MODE} the value @code{1} is returned.
 477
 478 @item @emph{Example}:
 479 @smallexample
 480 program access_test
 481   implicit none
 482   character(len=*), parameter :: file  = 'test.dat'
 483   character(len=*), parameter :: file2 = 'test.dat  '//achar(0)
 484   if(access(file,' ') == 0) print *, trim(file),' is exists'
 485   if(access(file,'r') == 0) print *, trim(file),' is readable'
 486   if(access(file,'w') == 0) print *, trim(file),' is writable'
 487   if(access(file,'x') == 0) print *, trim(file),' is executable'
 488   if(access(file2,'rwx') == 0) &
 489     print *, trim(file2),' is readable, writable and executable'
 490 end program access_test
 491 @end smallexample
 492 @item @emph{Specific names}:
 493 @item @emph{See also}:
 494
 495 @end table
 496
 497
 498
 499 @node ACHAR
 500 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
 501 @fnindex ACHAR
 502 @cindex @acronym{ASCII} collating sequence
 503 @cindex collating sequence, @acronym{ASCII}
 504
 505 @table @asis
 506 @item @emph{Description}:
 507 @code{ACHAR(I)} returns the character located at position @code{I}
 508 in the @acronym{ASCII} collating sequence.
 509
 510 @item @emph{Standard}:
 511 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
 512
 513 @item @emph{Class}:
 514 Elemental function
 515
 516 @item @emph{Syntax}:
 517 @code{RESULT = ACHAR(I [, KIND])}
 518
 519 @item @emph{Arguments}:
 520 @multitable @columnfractions .15 .70
 521 @item @var{I}    @tab The type shall be @code{INTEGER}.
 522 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 523 expression indicating the kind parameter of the result.
 524 @end multitable
 525
 526 @item @emph{Return value}:
 527 The return value is of type @code{CHARACTER} with a length of one.
 528 If the @var{KIND} argument is present, the return value is of the
 529 specified kind and of the default kind otherwise.
 530
 531 @item @emph{Example}:
 532 @smallexample
 533 program test_achar
 534   character c
 535   c = achar(32)
 536 end program test_achar
 537 @end smallexample
 538
 539 @item @emph{Note}:
 540 See @ref{ICHAR} for a discussion of converting between numerical values
 541 and formatted string representations.
 542
 543 @item @emph{See also}:
 544 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
 545
 546 @end table
 547
 548
 549
 550 @node ACOS
 551 @section @code{ACOS} --- Arccosine function
 552 @fnindex ACOS
 553 @fnindex DACOS
 554 @cindex trigonometric function, cosine, inverse
 555 @cindex cosine, inverse
 556
 557 @table @asis
 558 @item @emph{Description}:
 559 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
 560
 561 @item @emph{Standard}:
 562 Fortran 77 and later, for a complex argument Fortran 2008 or later
 563
 564 @item @emph{Class}:
 565 Elemental function
 566
 567 @item @emph{Syntax}:
 568 @code{RESULT = ACOS(X)}
 569
 570 @item @emph{Arguments}:
 571 @multitable @columnfractions .15 .70
 572 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
 573 less than or equal to one - or the type shall be @code{COMPLEX}.
 574 @end multitable
 575
 576 @item @emph{Return value}:
 577 The return value is of the same type and kind as @var{X}.
 578 The real part of the result is in radians and lies in the range
 579 @math{0 \leq \Re \acos(x) \leq \pi}.
 580
 581 @item @emph{Example}:
 582 @smallexample
 583 program test_acos
 584   real(8) :: x = 0.866_8
 585   x = acos(x)
 586 end program test_acos
 587 @end smallexample
 588
 589 @item @emph{Specific names}:
 590 @multitable @columnfractions .20 .20 .20 .25
 591 @item Name            @tab Argument         @tab Return type     @tab Standard
 592 @item @code{ACOS(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}  @tab Fortran 77 and later
 593 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}  @tab Fortran 77 and later
 594 @end multitable
 595
 596 @item @emph{See also}:
 597 Inverse function: @ref{COS}
 598
 599 @end table
 600
 601
 602
 603 @node ACOSH
 604 @section @code{ACOSH} --- Inverse hyperbolic cosine function
 605 @fnindex ACOSH
 606 @fnindex DACOSH
 607 @cindex area hyperbolic cosine
 608 @cindex inverse hyperbolic cosine
 609 @cindex hyperbolic function, cosine, inverse
 610 @cindex cosine, hyperbolic, inverse
 611
 612 @table @asis
 613 @item @emph{Description}:
 614 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
 615
 616 @item @emph{Standard}:
 617 Fortran 2008 and later
 618
 619 @item @emph{Class}:
 620 Elemental function
 621
 622 @item @emph{Syntax}:
 623 @code{RESULT = ACOSH(X)}
 624
 625 @item @emph{Arguments}:
 626 @multitable @columnfractions .15 .70
 627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
 628 @end multitable
 629
 630 @item @emph{Return value}:
 631 The return value has the same type and kind as @var{X}. If @var{X} is
 632 complex, the imaginary part of the result is in radians and lies between
 633 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
 634
 635 @item @emph{Example}:
 636 @smallexample
 637 PROGRAM test_acosh
 638   REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
 639   WRITE (*,*) ACOSH(x)
 640 END PROGRAM
 641 @end smallexample
 642
 643 @item @emph{Specific names}:
 644 @multitable @columnfractions .20 .20 .20 .25
 645 @item Name             @tab Argument          @tab Return type       @tab Standard
 646 @item @code{DACOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
 647 @end multitable
 648
 649 @item @emph{See also}:
 650 Inverse function: @ref{COSH}
 651 @end table
 652
 653
 654
 655 @node ADJUSTL
 656 @section @code{ADJUSTL} --- Left adjust a string
 657 @fnindex ADJUSTL
 658 @cindex string, adjust left
 659 @cindex adjust string
 660
 661 @table @asis
 662 @item @emph{Description}:
 663 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
 664 Spaces are inserted at the end of the string as needed.
 665
 666 @item @emph{Standard}:
 667 Fortran 90 and later
 668
 669 @item @emph{Class}:
 670 Elemental function
 671
 672 @item @emph{Syntax}:
 673 @code{RESULT = ADJUSTL(STRING)}
 674
 675 @item @emph{Arguments}:
 676 @multitable @columnfractions .15 .70
 677 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
 678 @end multitable
 679
 680 @item @emph{Return value}:
 681 The return value is of type @code{CHARACTER} and of the same kind as
 682 @var{STRING} where leading spaces are removed and the same number of
 683 spaces are inserted on the end of @var{STRING}.
 684
 685 @item @emph{Example}:
 686 @smallexample
 687 program test_adjustl
 688   character(len=20) :: str = '   gfortran'
 689   str = adjustl(str)
 690   print *, str
 691 end program test_adjustl
 692 @end smallexample
 693
 694 @item @emph{See also}:
 695 @ref{ADJUSTR}, @ref{TRIM}
 696 @end table
 697
 698
 699
 700 @node ADJUSTR
 701 @section @code{ADJUSTR} --- Right adjust a string
 702 @fnindex ADJUSTR
 703 @cindex string, adjust right
 704 @cindex adjust string
 705
 706 @table @asis
 707 @item @emph{Description}:
 708 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
 709 Spaces are inserted at the start of the string as needed.
 710
 711 @item @emph{Standard}:
 712 Fortran 95 and later
 713
 714 @item @emph{Class}:
 715 Elemental function
 716
 717 @item @emph{Syntax}:
 718 @code{RESULT = ADJUSTR(STRING)}
 719
 720 @item @emph{Arguments}:
 721 @multitable @columnfractions .15 .70
 722 @item @var{STR} @tab The type shall be @code{CHARACTER}.
 723 @end multitable
 724
 725 @item @emph{Return value}:
 726 The return value is of type @code{CHARACTER} and of the same kind as
 727 @var{STRING} where trailing spaces are removed and the same number of
 728 spaces are inserted at the start of @var{STRING}.
 729
 730 @item @emph{Example}:
 731 @smallexample
 732 program test_adjustr
 733   character(len=20) :: str = 'gfortran'
 734   str = adjustr(str)
 735   print *, str
 736 end program test_adjustr
 737 @end smallexample
 738
 739 @item @emph{See also}:
 740 @ref{ADJUSTL}, @ref{TRIM}
 741 @end table
 742
 743
 744
 745 @node AIMAG
 746 @section @code{AIMAG} --- Imaginary part of complex number
 747 @fnindex AIMAG
 748 @fnindex DIMAG
 749 @fnindex IMAG
 750 @fnindex IMAGPART
 751 @cindex complex numbers, imaginary part
 752
 753 @table @asis
 754 @item @emph{Description}:
 755 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
 756 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
 757 for compatibility with @command{g77}, and their use in new code is
 758 strongly discouraged.
 759
 760 @item @emph{Standard}:
 761 Fortran 77 and later, has overloads that are GNU extensions
 762
 763 @item @emph{Class}:
 764 Elemental function
 765
 766 @item @emph{Syntax}:
 767 @code{RESULT = AIMAG(Z)}
 768
 769 @item @emph{Arguments}:
 770 @multitable @columnfractions .15 .70
 771 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
 772 @end multitable
 773
 774 @item @emph{Return value}:
 775 The return value is of type @code{REAL} with the
 776 kind type parameter of the argument.
 777
 778 @item @emph{Example}:
 779 @smallexample
 780 program test_aimag
 781   complex(4) z4
 782   complex(8) z8
 783   z4 = cmplx(1.e0_4, 0.e0_4)
 784   z8 = cmplx(0.e0_8, 1.e0_8)
 785   print *, aimag(z4), dimag(z8)
 786 end program test_aimag
 787 @end smallexample
 788
 789 @item @emph{Specific names}:
 790 @multitable @columnfractions .20 .20 .20 .25
 791 @item Name               @tab Argument            @tab Return type     @tab Standard
 792 @item @code{AIMAG(Z)}    @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 793 @item @code{DIMAG(Z)}    @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)}  @tab GNU extension
 794 @item @code{IMAG(Z)}     @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 795 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z}    @tab @code{REAL}     @tab GNU extension
 796 @end multitable
 797 @end table
 798
 799
 800
 801 @node AINT
 802 @section @code{AINT} --- Truncate to a whole number
 803 @fnindex AINT
 804 @fnindex DINT
 805 @cindex floor
 806 @cindex rounding, floor
 807
 808 @table @asis
 809 @item @emph{Description}:
 810 @code{AINT(A [, KIND])} truncates its argument to a whole number.
 811
 812 @item @emph{Standard}:
 813 Fortran 77 and later
 814
 815 @item @emph{Class}:
 816 Elemental function
 817
 818 @item @emph{Syntax}:
 819 @code{RESULT = AINT(A [, KIND])}
 820
 821 @item @emph{Arguments}:
 822 @multitable @columnfractions .15 .70
 823 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
 824 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
 825 expression indicating the kind parameter of the result.
 826 @end multitable
 827
 828 @item @emph{Return value}:
 829 The return value is of type @code{REAL} with the kind type parameter of the
 830 argument if the optional @var{KIND} is absent; otherwise, the kind
 831 type parameter will be given by @var{KIND}.  If the magnitude of
 832 @var{X} is less than one, @code{AINT(X)} returns zero.  If the
 833 magnitude is equal to or greater than one then it returns the largest
 834 whole number that does not exceed its magnitude.  The sign is the same
 835 as the sign of @var{X}.
 836
 837 @item @emph{Example}:
 838 @smallexample
 839 program test_aint
 840   real(4) x4
 841   real(8) x8
 842   x4 = 1.234E0_4
 843   x8 = 4.321_8
 844   print *, aint(x4), dint(x8)
 845   x8 = aint(x4,8)
 846 end program test_aint
 847 @end smallexample
 848
 849 @item @emph{Specific names}:
 850 @multitable @columnfractions .20 .20 .20 .25
 851 @item Name           @tab Argument         @tab Return type      @tab Standard
 852 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
 853 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
 854 @end multitable
 855 @end table
 856
 857
 858
 859 @node ALARM
 860 @section @code{ALARM} --- Execute a routine after a given delay
 861 @fnindex ALARM
 862 @cindex delayed execution
 863
 864 @table @asis
 865 @item @emph{Description}:
 866 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
 867 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
 868 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
 869 supplied, it will be returned with the number of seconds remaining until
 870 any previously scheduled alarm was due to be delivered, or zero if there
 871 was no previously scheduled alarm.
 872
 873 @item @emph{Standard}:
 874 GNU extension
 875
 876 @item @emph{Class}:
 877 Subroutine
 878
 879 @item @emph{Syntax}:
 880 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
 881
 882 @item @emph{Arguments}:
 883 @multitable @columnfractions .15 .70
 884 @item @var{SECONDS} @tab The type of the argument shall be a scalar
 885 @code{INTEGER}. It is @code{INTENT(IN)}.
 886 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
 887 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
 888 values may be either @code{SIG_IGN=1} to ignore the alarm generated
 889 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
 890 @item @var{STATUS}  @tab (Optional) @var{STATUS} shall be a scalar
 891 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
 892 @end multitable
 893
 894 @item @emph{Example}:
 895 @smallexample
 896 program test_alarm
 897   external handler_print
 898   integer i
 899   call alarm (3, handler_print, i)
 900   print *, i
 901   call sleep(10)
 902 end program test_alarm
 903 @end smallexample
 904 This will cause the external routine @var{handler_print} to be called
 905 after 3 seconds.
 906 @end table
 907
 908
 909
 910 @node ALL
 911 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
 912 @fnindex ALL
 913 @cindex array, apply condition
 914 @cindex array, condition testing
 915
 916 @table @asis
 917 @item @emph{Description}:
 918 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
 919 in the array along dimension @var{DIM}.
 920
 921 @item @emph{Standard}:
 922 Fortran 95 and later
 923
 924 @item @emph{Class}:
 925 Transformational function
 926
 927 @item @emph{Syntax}:
 928 @code{RESULT = ALL(MASK [, DIM])}
 929
 930 @item @emph{Arguments}:
 931 @multitable @columnfractions .15 .70
 932 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
 933 it shall not be scalar.
 934 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
 935 with a value that lies between one and the rank of @var{MASK}.
 936 @end multitable
 937
 938 @item @emph{Return value}:
 939 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
 940 the kind type parameter is the same as the kind type parameter of
 941 @var{MASK}.  If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
 942 an array with the rank of @var{MASK} minus 1.  The shape is determined from
 943 the shape of @var{MASK} where the @var{DIM} dimension is elided.
 944
 945 @table @asis
 946 @item (A)
 947 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
 948 It also is true if @var{MASK} has zero size; otherwise, it is false.
 949 @item (B)
 950 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
 951 to @code{ALL(MASK)}.  If the rank is greater than one, then @code{ALL(MASK,DIM)}
 952 is determined by applying @code{ALL} to the array sections.
 953 @end table
 954
 955 @item @emph{Example}:
 956 @smallexample
 957 program test_all
 958   logical l
 959   l = all((/.true., .true., .true./))
 960   print *, l
 961   call section
 962   contains
 963     subroutine section
 964       integer a(2,3), b(2,3)
 965       a = 1
 966       b = 1
 967       b(2,2) = 2
 968       print *, all(a .eq. b, 1)
 969       print *, all(a .eq. b, 2)
 970     end subroutine section
 971 end program test_all
 972 @end smallexample
 973 @end table
 974
 975
 976
 977 @node ALLOCATED
 978 @section @code{ALLOCATED} --- Status of an allocatable entity
 979 @fnindex ALLOCATED
 980 @cindex allocation, status
 981
 982 @table @asis
 983 @item @emph{Description}:
 984 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
 985 status of @var{ARRAY} and @var{SCALAR}, respectively.
 986
 987 @item @emph{Standard}:
 988 Fortran 95 and later.  Note, the @code{SCALAR=} keyword and allocatable
 989 scalar entities are available in Fortran 2003 and later.
 990
 991 @item @emph{Class}:
 992 Inquiry function
 993
 994 @item @emph{Syntax}:
 995 @multitable @columnfractions .80
 996 @item @code{RESULT = ALLOCATED(ARRAY)}
 997 @item @code{RESULT = ALLOCATED(SCALAR)}
 998 @end multitable
 999
1000 @item @emph{Arguments}:
1001 @multitable @columnfractions .15 .70
1002 @item @var{ARRAY}    @tab The argument shall be an @code{ALLOCATABLE} array.
1003 @item @var{SCALAR}   @tab The argument shall be an @code{ALLOCATABLE} scalar.
1004 @end multitable
1005
1006 @item @emph{Return value}:
1007 The return value is a scalar @code{LOGICAL} with the default logical
1008 kind type parameter.  If the argument is allocated, then the result is
1009 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1010
1011 @item @emph{Example}:
1012 @smallexample
1013 program test_allocated
1014   integer :: i = 4
1015   real(4), allocatable :: x(:)
1016   if (.not. allocated(x)) allocate(x(i))
1017 end program test_allocated
1018 @end smallexample
1019 @end table
1020
1021
1022
1023 @node AND
1024 @section @code{AND} --- Bitwise logical AND
1025 @fnindex AND
1026 @cindex bitwise logical and
1027 @cindex logical and, bitwise
1028
1029 @table @asis
1030 @item @emph{Description}:
1031 Bitwise logical @code{AND}.
1032
1033 This intrinsic routine is provided for backwards compatibility with
1034 GNU Fortran 77.  For integer arguments, programmers should consider
1035 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1036
1037 @item @emph{Standard}:
1038 GNU extension
1039
1040 @item @emph{Class}:
1041 Function
1042
1043 @item @emph{Syntax}:
1044 @code{RESULT = AND(I, J)}
1045
1046 @item @emph{Arguments}:
1047 @multitable @columnfractions .15 .70
1048 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1049 type or a scalar @code{LOGICAL} type.
1050 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1051 @end multitable
1052
1053 @item @emph{Return value}:
1054 The return type is either a scalar @code{INTEGER} or a scalar
1055 @code{LOGICAL}.  If the kind type parameters differ, then the
1056 smaller kind type is implicitly converted to larger kind, and the
1057 return has the larger kind.
1058
1059 @item @emph{Example}:
1060 @smallexample
1061 PROGRAM test_and
1062   LOGICAL :: T = .TRUE., F = .FALSE.
1063   INTEGER :: a, b
1064   DATA a / Z'F' /, b / Z'3' /
1065
1066   WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1067   WRITE (*,*) AND(a, b)
1068 END PROGRAM
1069 @end smallexample
1070
1071 @item @emph{See also}:
1072 Fortran 95 elemental function: @ref{IAND}
1073 @end table
1074
1075
1076
1077 @node ANINT
1078 @section @code{ANINT} --- Nearest whole number
1079 @fnindex ANINT
1080 @fnindex DNINT
1081 @cindex ceiling
1082 @cindex rounding, ceiling
1083
1084 @table @asis
1085 @item @emph{Description}:
1086 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1087
1088 @item @emph{Standard}:
1089 Fortran 77 and later
1090
1091 @item @emph{Class}:
1092 Elemental function
1093
1094 @item @emph{Syntax}:
1095 @code{RESULT = ANINT(A [, KIND])}
1096
1097 @item @emph{Arguments}:
1098 @multitable @columnfractions .15 .70
1099 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
1100 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1101 expression indicating the kind parameter of the result.
1102 @end multitable
1103
1104 @item @emph{Return value}:
1105 The return value is of type real with the kind type parameter of the
1106 argument if the optional @var{KIND} is absent; otherwise, the kind
1107 type parameter will be given by @var{KIND}.  If @var{A} is greater than
1108 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}.  If @var{A} is
1109 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1110
1111 @item @emph{Example}:
1112 @smallexample
1113 program test_anint
1114   real(4) x4
1115   real(8) x8
1116   x4 = 1.234E0_4
1117   x8 = 4.321_8
1118   print *, anint(x4), dnint(x8)
1119   x8 = anint(x4,8)
1120 end program test_anint
1121 @end smallexample
1122
1123 @item @emph{Specific names}:
1124 @multitable @columnfractions .20 .20 .20 .25
1125 @item Name            @tab Argument         @tab Return type      @tab Standard
1126 @item @code{AINT(A)}  @tab @code{REAL(4) A} @tab @code{REAL(4)}   @tab Fortran 77 and later
1127 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)}   @tab Fortran 77 and later
1128 @end multitable
1129 @end table
1130
1131
1132
1133 @node ANY
1134 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1135 @fnindex ANY
1136 @cindex array, apply condition
1137 @cindex array, condition testing
1138
1139 @table @asis
1140 @item @emph{Description}:
1141 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1142 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1143
1144 @item @emph{Standard}:
1145 Fortran 95 and later
1146
1147 @item @emph{Class}:
1148 Transformational function
1149
1150 @item @emph{Syntax}:
1151 @code{RESULT = ANY(MASK [, DIM])}
1152
1153 @item @emph{Arguments}:
1154 @multitable @columnfractions .15 .70
1155 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1156 it shall not be scalar.
1157 @item @var{DIM}  @tab (Optional) @var{DIM} shall be a scalar integer
1158 with a value that lies between one and the rank of @var{MASK}.
1159 @end multitable
1160
1161 @item @emph{Return value}:
1162 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1163 the kind type parameter is the same as the kind type parameter of
1164 @var{MASK}.  If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1165 an array with the rank of @var{MASK} minus 1.  The shape is determined from
1166 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1167
1168 @table @asis
1169 @item (A)
1170 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1171 otherwise, it is false.  It also is false if @var{MASK} has zero size.
1172 @item (B)
1173 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1174 to @code{ANY(MASK)}.  If the rank is greater than one, then @code{ANY(MASK,DIM)}
1175 is determined by applying @code{ANY} to the array sections.
1176 @end table
1177
1178 @item @emph{Example}:
1179 @smallexample
1180 program test_any
1181   logical l
1182   l = any((/.true., .true., .true./))
1183   print *, l
1184   call section
1185   contains
1186     subroutine section
1187       integer a(2,3), b(2,3)
1188       a = 1
1189       b = 1
1190       b(2,2) = 2
1191       print *, any(a .eq. b, 1)
1192       print *, any(a .eq. b, 2)
1193     end subroutine section
1194 end program test_any
1195 @end smallexample
1196 @end table
1197
1198
1199
1200 @node ASIN
1201 @section @code{ASIN} --- Arcsine function
1202 @fnindex ASIN
1203 @fnindex DASIN
1204 @cindex trigonometric function, sine, inverse
1205 @cindex sine, inverse
1206
1207 @table @asis
1208 @item @emph{Description}:
1209 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1210
1211 @item @emph{Standard}:
1212 Fortran 77 and later, for a complex argument Fortran 2008 or later
1213
1214 @item @emph{Class}:
1215 Elemental function
1216
1217 @item @emph{Syntax}:
1218 @code{RESULT = ASIN(X)}
1219
1220 @item @emph{Arguments}:
1221 @multitable @columnfractions .15 .70
1222 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1223 less than or equal to one - or be @code{COMPLEX}.
1224 @end multitable
1225
1226 @item @emph{Return value}:
1227 The return value is of the same type and kind as @var{X}.
1228 The real part of the result is in radians and lies in the range
1229 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1230
1231 @item @emph{Example}:
1232 @smallexample
1233 program test_asin
1234   real(8) :: x = 0.866_8
1235   x = asin(x)
1236 end program test_asin
1237 @end smallexample
1238
1239 @item @emph{Specific names}:
1240 @multitable @columnfractions .20 .20 .20 .25
1241 @item Name            @tab Argument          @tab Return type       @tab Standard
1242 @item @code{ASIN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1243 @item @code{DASIN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1244 @end multitable
1245
1246 @item @emph{See also}:
1247 Inverse function: @ref{SIN}
1248
1249 @end table
1250
1251
1252
1253 @node ASINH
1254 @section @code{ASINH} --- Inverse hyperbolic sine function
1255 @fnindex ASINH
1256 @fnindex DASINH
1257 @cindex area hyperbolic sine
1258 @cindex inverse hyperbolic sine
1259 @cindex hyperbolic function, sine, inverse
1260 @cindex sine, hyperbolic, inverse
1261
1262 @table @asis
1263 @item @emph{Description}:
1264 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1265
1266 @item @emph{Standard}:
1267 Fortran 2008 and later
1268
1269 @item @emph{Class}:
1270 Elemental function
1271
1272 @item @emph{Syntax}:
1273 @code{RESULT = ASINH(X)}
1274
1275 @item @emph{Arguments}:
1276 @multitable @columnfractions .15 .70
1277 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1278 @end multitable
1279
1280 @item @emph{Return value}:
1281 The return value is of the same type and kind as  @var{X}. If @var{X} is
1282 complex, the imaginary part of the result is in radians and lies between
1283 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1284
1285 @item @emph{Example}:
1286 @smallexample
1287 PROGRAM test_asinh
1288   REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1289   WRITE (*,*) ASINH(x)
1290 END PROGRAM
1291 @end smallexample
1292
1293 @item @emph{Specific names}:
1294 @multitable @columnfractions .20 .20 .20 .25
1295 @item Name             @tab Argument          @tab Return type       @tab Standard
1296 @item @code{DASINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension.
1297 @end multitable
1298
1299 @item @emph{See also}:
1300 Inverse function: @ref{SINH}
1301 @end table
1302
1303
1304
1305 @node ASSOCIATED
1306 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1307 @fnindex ASSOCIATED
1308 @cindex pointer, status
1309 @cindex association status
1310
1311 @table @asis
1312 @item @emph{Description}:
1313 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1314 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1315
1316 @item @emph{Standard}:
1317 Fortran 95 and later
1318
1319 @item @emph{Class}:
1320 Inquiry function
1321
1322 @item @emph{Syntax}:
1323 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1324
1325 @item @emph{Arguments}:
1326 @multitable @columnfractions .15 .70
1327 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1328 and it can be of any type.
1329 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1330 a target.  It must have the same type, kind type parameter, and
1331 array rank as @var{POINTER}.
1332 @end multitable
1333 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1334 undefined.
1335
1336 @item @emph{Return value}:
1337 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1338 There are several cases:
1339 @table @asis
1340 @item (A) When the optional @var{TARGET} is not present then
1341 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1342 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1343 @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
1344 disassociated, the result is false.
1345 @item (C) If @var{TARGET} is present and an array target, the result is true if
1346 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1347 are arrays whose elements are not zero-sized storage sequences, and
1348 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1349 order.
1350 As in case(B), the result is false, if @var{POINTER} is disassociated.
1351 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1352 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1353 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1354 units.
1355 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1356 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1357 target associated with @var{POINTER} and the target associated with @var{TARGET}
1358 have the same shape, are not zero-sized arrays, are arrays whose elements are
1359 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1360 the same storage units in array element order.
1361 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1362 @end table
1363
1364 @item @emph{Example}:
1365 @smallexample
1366 program test_associated
1367    implicit none
1368    real, target  :: tgt(2) = (/1., 2./)
1369    real, pointer :: ptr(:)
1370    ptr => tgt
1371    if (associated(ptr)     .eqv. .false.) call abort
1372    if (associated(ptr,tgt) .eqv. .false.) call abort
1373 end program test_associated
1374 @end smallexample
1375
1376 @item @emph{See also}:
1377 @ref{NULL}
1378 @end table
1379
1380
1381
1382 @node ATAN
1383 @section @code{ATAN} --- Arctangent function
1384 @fnindex ATAN
1385 @fnindex DATAN
1386 @cindex trigonometric function, tangent, inverse
1387 @cindex tangent, inverse
1388
1389 @table @asis
1390 @item @emph{Description}:
1391 @code{ATAN(X)} computes the arctangent of @var{X}.
1392
1393 @item @emph{Standard}:
1394 Fortran 77 and later, for a complex argument and for two arguments
1395 Fortran 2008 or later
1396
1397 @item @emph{Class}:
1398 Elemental function
1399
1400 @item @emph{Syntax}:
1401 @multitable @columnfractions .80
1402 @item @code{RESULT = ATAN(X)}
1403 @item @code{RESULT = ATAN(Y, X)}
1404 @end multitable
1405
1406 @item @emph{Arguments}:
1407 @multitable @columnfractions .15 .70
1408 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1409 if @var{Y} is present, @var{X} shall be REAL.
1410 @item @var{Y} shall be of the same type and kind as @var{X}.
1411 @end multitable
1412
1413 @item @emph{Return value}:
1414 The return value is of the same type and kind as @var{X}.
1415 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1416 Otherwise, it the arcus tangent of @var{X}, where the real part of
1417 the result is in radians and lies in the range
1418 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1419
1420 @item @emph{Example}:
1421 @smallexample
1422 program test_atan
1423   real(8) :: x = 2.866_8
1424   x = atan(x)
1425 end program test_atan
1426 @end smallexample
1427
1428 @item @emph{Specific names}:
1429 @multitable @columnfractions .20 .20 .20 .25
1430 @item Name            @tab Argument          @tab Return type       @tab Standard
1431 @item @code{ATAN(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
1432 @item @code{DATAN(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
1433 @end multitable
1434
1435 @item @emph{See also}:
1436 Inverse function: @ref{TAN}
1437
1438 @end table
1439
1440
1441
1442 @node ATAN2
1443 @section @code{ATAN2} --- Arctangent function
1444 @fnindex ATAN2
1445 @fnindex DATAN2
1446 @cindex trigonometric function, tangent, inverse
1447 @cindex tangent, inverse
1448
1449 @table @asis
1450 @item @emph{Description}:
1451 @code{ATAN2(Y, X)} computes the principal value of the argument
1452 function of the complex number @math{X + i Y}. This function can
1453 be used to transform from Cartesian into polar coordinates and
1454 allows to determine the angle in the correct quadrant.
1455
1456 @item @emph{Standard}:
1457 Fortran 77 and later
1458
1459 @item @emph{Class}:
1460 Elemental function
1461
1462 @item @emph{Syntax}:
1463 @code{RESULT = ATAN2(Y, X)}
1464
1465 @item @emph{Arguments}:
1466 @multitable @columnfractions .15 .70
1467 @item @var{Y} @tab The type shall be @code{REAL}.
1468 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1469 If @var{Y} is zero, then @var{X} must be nonzero.
1470 @end multitable
1471
1472 @item @emph{Return value}:
1473 The return value has the same type and kind type parameter as @var{Y}.
1474 It is the principal value of the complex number @math{X + i Y}.  If
1475 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1476 The sign is positive if @var{Y} is positive.  If @var{Y} is zero, then
1477 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1478 is negative.  Finally, if @var{X} is zero, then the magnitude of the result
1479 is @math{\pi/2}.
1480
1481 @item @emph{Example}:
1482 @smallexample
1483 program test_atan2
1484   real(4) :: x = 1.e0_4, y = 0.5e0_4
1485   x = atan2(y,x)
1486 end program test_atan2
1487 @end smallexample
1488
1489 @item @emph{Specific names}:
1490 @multitable @columnfractions .20 .20 .20 .25
1491 @item Name                @tab Argument            @tab Return type    @tab Standard
1492 @item @code{ATAN2(X, Y)}  @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1493 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1494 @end multitable
1495 @end table
1496
1497
1498
1499 @node ATANH
1500 @section @code{ATANH} --- Inverse hyperbolic tangent function
1501 @fnindex ATANH
1502 @fnindex DATANH
1503 @cindex area hyperbolic tangent
1504 @cindex inverse hyperbolic tangent
1505 @cindex hyperbolic function, tangent, inverse
1506 @cindex tangent, hyperbolic, inverse
1507
1508 @table @asis
1509 @item @emph{Description}:
1510 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1511
1512 @item @emph{Standard}:
1513 Fortran 2008 and later
1514
1515 @item @emph{Class}:
1516 Elemental function
1517
1518 @item @emph{Syntax}:
1519 @code{RESULT = ATANH(X)}
1520
1521 @item @emph{Arguments}:
1522 @multitable @columnfractions .15 .70
1523 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1524 @end multitable
1525
1526 @item @emph{Return value}:
1527 The return value has same type and kind as @var{X}. If @var{X} is
1528 complex, the imaginary part of the result is in radians and lies between
1529 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1530
1531 @item @emph{Example}:
1532 @smallexample
1533 PROGRAM test_atanh
1534   REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1535   WRITE (*,*) ATANH(x)
1536 END PROGRAM
1537 @end smallexample
1538
1539 @item @emph{Specific names}:
1540 @multitable @columnfractions .20 .20 .20 .25
1541 @item Name             @tab Argument          @tab Return type       @tab Standard
1542 @item @code{DATANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1543 @end multitable
1544
1545 @item @emph{See also}:
1546 Inverse function: @ref{TANH}
1547 @end table
1548
1549
1550
1551 @node BESSEL_J0
1552 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1553 @fnindex BESSEL_J0
1554 @fnindex BESJ0
1555 @fnindex DBESJ0
1556 @cindex Bessel function, first kind
1557
1558 @table @asis
1559 @item @emph{Description}:
1560 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1561 order 0 of @var{X}. This function is available under the name
1562 @code{BESJ0} as a GNU extension.
1563
1564 @item @emph{Standard}:
1565 Fortran 2008 and later
1566
1567 @item @emph{Class}:
1568 Elemental function
1569
1570 @item @emph{Syntax}:
1571 @code{RESULT = BESSEL_J0(X)}
1572
1573 @item @emph{Arguments}:
1574 @multitable @columnfractions .15 .70
1575 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1576 @end multitable
1577
1578 @item @emph{Return value}:
1579 The return value is of type @code{REAL} and lies in the
1580 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1581 kind as @var{X}.
1582
1583 @item @emph{Example}:
1584 @smallexample
1585 program test_besj0
1586   real(8) :: x = 0.0_8
1587   x = bessel_j0(x)
1588 end program test_besj0
1589 @end smallexample
1590
1591 @item @emph{Specific names}:
1592 @multitable @columnfractions .20 .20 .20 .25
1593 @item Name            @tab Argument          @tab Return type       @tab Standard
1594 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1595 @end multitable
1596 @end table
1597
1598
1599
1600 @node BESSEL_J1
1601 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1602 @fnindex BESSEL_J1
1603 @fnindex BESJ1
1604 @fnindex DBESJ1
1605 @cindex Bessel function, first kind
1606
1607 @table @asis
1608 @item @emph{Description}:
1609 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1610 order 1 of @var{X}. This function is available under the name
1611 @code{BESJ1} as a GNU extension.
1612
1613 @item @emph{Standard}:
1614 Fortran 2008
1615
1616 @item @emph{Class}:
1617 Elemental function
1618
1619 @item @emph{Syntax}:
1620 @code{RESULT = BESSEL_J1(X)}
1621
1622 @item @emph{Arguments}:
1623 @multitable @columnfractions .15 .70
1624 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1625 @end multitable
1626
1627 @item @emph{Return value}:
1628 The return value is of type @code{REAL} and it lies in the
1629 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1630 kind as @var{X}.
1631
1632 @item @emph{Example}:
1633 @smallexample
1634 program test_besj1
1635   real(8) :: x = 1.0_8
1636   x = bessel_j1(x)
1637 end program test_besj1
1638 @end smallexample
1639
1640 @item @emph{Specific names}:
1641 @multitable @columnfractions .20 .20 .20 .25
1642 @item Name             @tab Argument          @tab Return type       @tab Standard
1643 @item @code{DBESJ1(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1644 @end multitable
1645 @end table
1646
1647
1648
1649 @node BESSEL_JN
1650 @section @code{BESSEL_JN} --- Bessel function of the first kind
1651 @fnindex BESSEL_JN
1652 @fnindex BESJN
1653 @fnindex DBESJN
1654 @cindex Bessel function, first kind
1655
1656 @table @asis
1657 @item @emph{Description}:
1658 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1659 order @var{N} of @var{X}. This function is available under the name
1660 @code{BESJN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1661 their ranks and shapes shall conform.
1662
1663 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1664 of the first kind of the orders @var{N1} to @var{N2}.
1665
1666 @item @emph{Standard}:
1667 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1668
1669 @item @emph{Class}:
1670 Elemental function, except for the transformational function
1671 @code{BESSEL_JN(N1, N2, X)}
1672
1673 @item @emph{Syntax}:
1674 @multitable @columnfractions .80
1675 @item @code{RESULT = BESSEL_JN(N, X)}
1676 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1677 @end multitable
1678
1679 @item @emph{Arguments}:
1680 @multitable @columnfractions .15 .70
1681 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1682 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1683 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1684 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1685 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1686 @end multitable
1687
1688 @item @emph{Return value}:
1689 The return value is a scalar of type @code{REAL}. It has the same
1690 kind as @var{X}.
1691
1692 @item @emph{Note}:
1693 The transformational function uses a recurrence algorithm which might,
1694 for some values of @var{X}, lead to different results than calls to
1695 the elemental function.
1696
1697 @item @emph{Example}:
1698 @smallexample
1699 program test_besjn
1700   real(8) :: x = 1.0_8
1701   x = bessel_jn(5,x)
1702 end program test_besjn
1703 @end smallexample
1704
1705 @item @emph{Specific names}:
1706 @multitable @columnfractions .20 .20 .20 .25
1707 @item Name                @tab Argument            @tab Return type       @tab Standard
1708 @item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
1709 @item                     @tab @code{REAL(8) X}    @tab                   @tab
1710 @end multitable
1711 @end table
1712
1713
1714
1715 @node BESSEL_Y0
1716 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1717 @fnindex BESSEL_Y0
1718 @fnindex BESY0
1719 @fnindex DBESY0
1720 @cindex Bessel function, second kind
1721
1722 @table @asis
1723 @item @emph{Description}:
1724 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1725 order 0 of @var{X}. This function is available under the name
1726 @code{BESY0} as a GNU extension.
1727
1728 @item @emph{Standard}:
1729 Fortran 2008 and later
1730
1731 @item @emph{Class}:
1732 Elemental function
1733
1734 @item @emph{Syntax}:
1735 @code{RESULT = BESSEL_Y0(X)}
1736
1737 @item @emph{Arguments}:
1738 @multitable @columnfractions .15 .70
1739 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1740 @end multitable
1741
1742 @item @emph{Return value}:
1743 The return value is a scalar of type @code{REAL}. It has the same
1744 kind as @var{X}.
1745
1746 @item @emph{Example}:
1747 @smallexample
1748 program test_besy0
1749   real(8) :: x = 0.0_8
1750   x = bessel_y0(x)
1751 end program test_besy0
1752 @end smallexample
1753
1754 @item @emph{Specific names}:
1755 @multitable @columnfractions .20 .20 .20 .25
1756 @item Name            @tab Argument          @tab Return type       @tab Standard
1757 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1758 @end multitable
1759 @end table
1760
1761
1762
1763 @node BESSEL_Y1
1764 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1765 @fnindex BESSEL_Y1
1766 @fnindex BESY1
1767 @fnindex DBESY1
1768 @cindex Bessel function, second kind
1769
1770 @table @asis
1771 @item @emph{Description}:
1772 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1773 order 1 of @var{X}. This function is available under the name
1774 @code{BESY1} as a GNU extension.
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_Y1(X)}
1784
1785 @item @emph{Arguments}:
1786 @multitable @columnfractions .15 .70
1787 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1788 @end multitable
1789
1790 @item @emph{Return value}:
1791 The return value is a scalar of type @code{REAL}. It has the same
1792 kind as @var{X}.
1793
1794 @item @emph{Example}:
1795 @smallexample
1796 program test_besy1
1797   real(8) :: x = 1.0_8
1798   x = bessel_y1(x)
1799 end program test_besy1
1800 @end smallexample
1801
1802 @item @emph{Specific names}:
1803 @multitable @columnfractions .20 .20 .20 .25
1804 @item Name            @tab Argument          @tab Return type       @tab Standard
1805 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1806 @end multitable
1807 @end table
1808
1809
1810
1811 @node BESSEL_YN
1812 @section @code{BESSEL_YN} --- Bessel function of the second kind
1813 @fnindex BESSEL_YN
1814 @fnindex BESYN
1815 @fnindex DBESYN
1816 @cindex Bessel function, second kind
1817
1818 @table @asis
1819 @item @emph{Description}:
1820 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1821 order @var{N} of @var{X}. This function is available under the name
1822 @code{BESYN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1823 their ranks and shapes shall conform.
1824
1825 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1826 of the first kind of the orders @var{N1} to @var{N2}.
1827
1828 @item @emph{Standard}:
1829 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1830
1831 @item @emph{Class}:
1832 Elemental function, except for the transformational function
1833 @code{BESSEL_YN(N1, N2, X)}
1834
1835 @item @emph{Syntax}:
1836 @multitable @columnfractions .80
1837 @item @code{RESULT = BESSEL_YN(N, X)}
1838 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1839 @end multitable
1840
1841 @item @emph{Arguments}:
1842 @multitable @columnfractions .15 .70
1843 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER} .
1844 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1845 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1846 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1847 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1848 @end multitable
1849
1850 @item @emph{Return value}:
1851 The return value is a scalar of type @code{REAL}. It has the same
1852 kind as @var{X}.
1853
1854 @item @emph{Note}:
1855 The transformational function uses a recurrence algorithm which might,
1856 for some values of @var{X}, lead to different results than calls to
1857 the elemental function.
1858
1859 @item @emph{Example}:
1860 @smallexample
1861 program test_besyn
1862   real(8) :: x = 1.0_8
1863   x = bessel_yn(5,x)
1864 end program test_besyn
1865 @end smallexample
1866
1867 @item @emph{Specific names}:
1868 @multitable @columnfractions .20 .20 .20 .25
1869 @item Name               @tab Argument            @tab Return type     @tab Standard
1870 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1871 @item                    @tab @code{REAL(8) X} @tab                 @tab
1872 @end multitable
1873 @end table
1874
1875
1876
1877 @node BGE
1878 @section @code{BGE} --- Bitwise greater than or equal to
1879 @fnindex BGE
1880 @cindex bitwise comparison
1881
1882 @table @asis
1883 @item @emph{Description}:
1884 Determines whether an integral is a bitwise greater than or equal to
1885 another.
1886
1887 @item @emph{Standard}:
1888 Fortran 2008 and later
1889
1890 @item @emph{Class}:
1891 Elemental function
1892
1893 @item @emph{Syntax}:
1894 @code{RESULT = BGE(I, J)}
1895
1896 @item @emph{Arguments}:
1897 @multitable @columnfractions .15 .70
1898 @item @var{I} @tab Shall be of @code{INTEGER} type.
1899 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1900 as @var{I}.
1901 @end multitable
1902
1903 @item @emph{Return value}:
1904 The return value is of type @code{LOGICAL} and of the default kind.
1905
1906 @item @emph{See also}:
1907 @ref{BGT}, @ref{BLE}, @ref{BLT}
1908 @end table
1909
1910
1911
1912 @node BGT
1913 @section @code{BGT} --- Bitwise greater than
1914 @fnindex BGT
1915 @cindex bitwise comparison
1916
1917 @table @asis
1918 @item @emph{Description}:
1919 Determines whether an integral is a bitwise greater than another.
1920
1921 @item @emph{Standard}:
1922 Fortran 2008 and later
1923
1924 @item @emph{Class}:
1925 Elemental function
1926
1927 @item @emph{Syntax}:
1928 @code{RESULT = BGT(I, J)}
1929
1930 @item @emph{Arguments}:
1931 @multitable @columnfractions .15 .70
1932 @item @var{I} @tab Shall be of @code{INTEGER} type.
1933 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1934 as @var{I}.
1935 @end multitable
1936
1937 @item @emph{Return value}:
1938 The return value is of type @code{LOGICAL} and of the default kind.
1939
1940 @item @emph{See also}:
1941 @ref{BGE}, @ref{BLE}, @ref{BLT}
1942 @end table
1943
1944
1945
1946 @node BIT_SIZE
1947 @section @code{BIT_SIZE} --- Bit size inquiry function
1948 @fnindex BIT_SIZE
1949 @cindex bits, number of
1950 @cindex size of a variable, in bits
1951
1952 @table @asis
1953 @item @emph{Description}:
1954 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1955 represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
1956 independent of the actual value of @var{I}.
1957
1958 @item @emph{Standard}:
1959 Fortran 95 and later
1960
1961 @item @emph{Class}:
1962 Inquiry function
1963
1964 @item @emph{Syntax}:
1965 @code{RESULT = BIT_SIZE(I)}
1966
1967 @item @emph{Arguments}:
1968 @multitable @columnfractions .15 .70
1969 @item @var{I} @tab The type shall be @code{INTEGER}.
1970 @end multitable
1971
1972 @item @emph{Return value}:
1973 The return value is of type @code{INTEGER}
1974
1975 @item @emph{Example}:
1976 @smallexample
1977 program test_bit_size
1978     integer :: i = 123
1979     integer :: size
1980     size = bit_size(i)
1981     print *, size
1982 end program test_bit_size
1983 @end smallexample
1984 @end table
1985
1986
1987
1988 @node BLE
1989 @section @code{BLE} --- Bitwise less than or equal to
1990 @fnindex BLE
1991 @cindex bitwise comparison
1992
1993 @table @asis
1994 @item @emph{Description}:
1995 Determines whether an integral is a bitwise less than or equal to
1996 another.
1997
1998 @item @emph{Standard}:
1999 Fortran 2008 and later
2000
2001 @item @emph{Class}:
2002 Elemental function
2003
2004 @item @emph{Syntax}:
2005 @code{RESULT = BLE(I, J)}
2006
2007 @item @emph{Arguments}:
2008 @multitable @columnfractions .15 .70
2009 @item @var{I} @tab Shall be of @code{INTEGER} type.
2010 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2011 as @var{I}.
2012 @end multitable
2013
2014 @item @emph{Return value}:
2015 The return value is of type @code{LOGICAL} and of the default kind.
2016
2017 @item @emph{See also}:
2018 @ref{BGT}, @ref{BGE}, @ref{BLT}
2019 @end table
2020
2021
2022
2023 @node BLT
2024 @section @code{BLT} --- Bitwise less than
2025 @fnindex BLT
2026 @cindex bitwise comparison
2027
2028 @table @asis
2029 @item @emph{Description}:
2030 Determines whether an integral is a bitwise less than another.
2031
2032 @item @emph{Standard}:
2033 Fortran 2008 and later
2034
2035 @item @emph{Class}:
2036 Elemental function
2037
2038 @item @emph{Syntax}:
2039 @code{RESULT = BLT(I, J)}
2040
2041 @item @emph{Arguments}:
2042 @multitable @columnfractions .15 .70
2043 @item @var{I} @tab Shall be of @code{INTEGER} type.
2044 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2045 as @var{I}.
2046 @end multitable
2047
2048 @item @emph{Return value}:
2049 The return value is of type @code{LOGICAL} and of the default kind.
2050
2051 @item @emph{See also}:
2052 @ref{BGE}, @ref{BGT}, @ref{BLE}
2053 @end table
2054
2055
2056
2057 @node BTEST
2058 @section @code{BTEST} --- Bit test function
2059 @fnindex BTEST
2060 @cindex bits, testing
2061
2062 @table @asis
2063 @item @emph{Description}:
2064 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2065 in @var{I} is set.  The counting of the bits starts at 0.
2066
2067 @item @emph{Standard}:
2068 Fortran 95 and later
2069
2070 @item @emph{Class}:
2071 Elemental function
2072
2073 @item @emph{Syntax}:
2074 @code{RESULT = BTEST(I, POS)}
2075
2076 @item @emph{Arguments}:
2077 @multitable @columnfractions .15 .70
2078 @item @var{I} @tab The type shall be @code{INTEGER}.
2079 @item @var{POS} @tab The type shall be @code{INTEGER}.
2080 @end multitable
2081
2082 @item @emph{Return value}:
2083 The return value is of type @code{LOGICAL}
2084
2085 @item @emph{Example}:
2086 @smallexample
2087 program test_btest
2088     integer :: i = 32768 + 1024 + 64
2089     integer :: pos
2090     logical :: bool
2091     do pos=0,16
2092         bool = btest(i, pos)
2093         print *, pos, bool
2094     end do
2095 end program test_btest
2096 @end smallexample
2097 @end table
2098
2099
2100 @node C_ASSOCIATED
2101 @section @code{C_ASSOCIATED} --- Status of a C pointer
2102 @fnindex C_ASSOCIATED
2103 @cindex association status, C pointer
2104 @cindex pointer, C association status
2105
2106 @table @asis
2107 @item @emph{Description}:
2108 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2109 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2110
2111 @item @emph{Standard}:
2112 Fortran 2003 and later
2113
2114 @item @emph{Class}:
2115 Inquiry function
2116
2117 @item @emph{Syntax}:
2118 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2119
2120 @item @emph{Arguments}:
2121 @multitable @columnfractions .15 .70
2122 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2123 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2124 @end multitable
2125
2126 @item @emph{Return value}:
2127 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2128 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2129 point to different addresses.
2130
2131 @item @emph{Example}:
2132 @smallexample
2133 subroutine association_test(a,b)
2134   use iso_c_binding, only: c_associated, c_loc, c_ptr
2135   implicit none
2136   real, pointer :: a
2137   type(c_ptr) :: b
2138   if(c_associated(b, c_loc(a))) &
2139      stop 'b and a do not point to same target'
2140 end subroutine association_test
2141 @end smallexample
2142
2143 @item @emph{See also}:
2144 @ref{C_LOC}, @ref{C_FUNLOC}
2145 @end table
2146
2147
2148 @node C_FUNLOC
2149 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2150 @fnindex C_FUNLOC
2151 @cindex pointer, C address of procedures
2152
2153 @table @asis
2154 @item @emph{Description}:
2155 @code{C_FUNLOC(x)} determines the C address of the argument.
2156
2157 @item @emph{Standard}:
2158 Fortran 2003 and later
2159
2160 @item @emph{Class}:
2161 Inquiry function
2162
2163 @item @emph{Syntax}:
2164 @code{RESULT = C_FUNLOC(x)}
2165
2166 @item @emph{Arguments}:
2167 @multitable @columnfractions .15 .70
2168 @item @var{x} @tab Interoperable function or pointer to such function.
2169 @end multitable
2170
2171 @item @emph{Return value}:
2172 The return value is of type @code{C_FUNPTR} and contains the C address
2173 of the argument.
2174
2175 @item @emph{Example}:
2176 @smallexample
2177 module x
2178   use iso_c_binding
2179   implicit none
2180 contains
2181   subroutine sub(a) bind(c)
2182     real(c_float) :: a
2183     a = sqrt(a)+5.0
2184   end subroutine sub
2185 end module x
2186 program main
2187   use iso_c_binding
2188   use x
2189   implicit none
2190   interface
2191     subroutine my_routine(p) bind(c,name='myC_func')
2192       import :: c_funptr
2193       type(c_funptr), intent(in) :: p
2194     end subroutine
2195   end interface
2196   call my_routine(c_funloc(sub))
2197 end program main
2198 @end smallexample
2199
2200 @item @emph{See also}:
2201 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2202 @end table
2203
2204
2205 @node C_F_PROCPOINTER
2206 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2207 @fnindex C_F_PROCPOINTER
2208 @cindex pointer, C address of pointers
2209
2210 @table @asis
2211 @item @emph{Description}:
2212 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2213 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2214
2215 @item @emph{Standard}:
2216 Fortran 2003 and later
2217
2218 @item @emph{Class}:
2219 Subroutine
2220
2221 @item @emph{Syntax}:
2222 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2223
2224 @item @emph{Arguments}:
2225 @multitable @columnfractions .15 .70
2226 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2227 @code{INTENT(IN)}.
2228 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2229 @code{INTENT(OUT)}.
2230 @end multitable
2231
2232 @item @emph{Example}:
2233 @smallexample
2234 program main
2235   use iso_c_binding
2236   implicit none
2237   abstract interface
2238     function func(a)
2239       import :: c_float
2240       real(c_float), intent(in) :: a
2241       real(c_float) :: func
2242     end function
2243   end interface
2244   interface
2245      function getIterFunc() bind(c,name="getIterFunc")
2246        import :: c_funptr
2247        type(c_funptr) :: getIterFunc
2248      end function
2249   end interface
2250   type(c_funptr) :: cfunptr
2251   procedure(func), pointer :: myFunc
2252   cfunptr = getIterFunc()
2253   call c_f_procpointer(cfunptr, myFunc)
2254 end program main
2255 @end smallexample
2256
2257 @item @emph{See also}:
2258 @ref{C_LOC}, @ref{C_F_POINTER}
2259 @end table
2260
2261
2262 @node C_F_POINTER
2263 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2264 @fnindex C_F_POINTER
2265 @cindex pointer, convert C to Fortran
2266
2267 @table @asis
2268 @item @emph{Description}:
2269 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2270 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2271 shape.
2272
2273 @item @emph{Standard}:
2274 Fortran 2003 and later
2275
2276 @item @emph{Class}:
2277 Subroutine
2278
2279 @item @emph{Syntax}:
2280 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2281
2282 @item @emph{Arguments}:
2283 @multitable @columnfractions .15 .70
2284 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2285 @code{INTENT(IN)}.
2286 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2287 @code{INTENT(OUT)}.
2288 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2289 with @code{INTENT(IN)}. It shall be present
2290 if and only if @var{fptr} is an array. The size
2291 must be equal to the rank of @var{fptr}.
2292 @end multitable
2293
2294 @item @emph{Example}:
2295 @smallexample
2296 program main
2297   use iso_c_binding
2298   implicit none
2299   interface
2300     subroutine my_routine(p) bind(c,name='myC_func')
2301       import :: c_ptr
2302       type(c_ptr), intent(out) :: p
2303     end subroutine
2304   end interface
2305   type(c_ptr) :: cptr
2306   real,pointer :: a(:)
2307   call my_routine(cptr)
2308   call c_f_pointer(cptr, a, [12])
2309 end program main
2310 @end smallexample
2311
2312 @item @emph{See also}:
2313 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2314 @end table
2315
2316
2317 @node C_LOC
2318 @section @code{C_LOC} --- Obtain the C address of an object
2319 @fnindex C_LOC
2320 @cindex procedure pointer, convert C to Fortran
2321
2322 @table @asis
2323 @item @emph{Description}:
2324 @code{C_LOC(X)} determines the C address of the argument.
2325
2326 @item @emph{Standard}:
2327 Fortran 2003 and later
2328
2329 @item @emph{Class}:
2330 Inquiry function
2331
2332 @item @emph{Syntax}:
2333 @code{RESULT = C_LOC(X)}
2334
2335 @item @emph{Arguments}:
2336 @multitable @columnfractions .10 .75
2337 @item @var{X} @tab  Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
2338
2339 @end multitable
2340
2341 @item @emph{Return value}:
2342 The return value is of type @code{C_PTR} and contains the C address
2343 of the argument.
2344
2345 @item @emph{Example}:
2346 @smallexample
2347 subroutine association_test(a,b)
2348   use iso_c_binding, only: c_associated, c_loc, c_ptr
2349   implicit none
2350   real, pointer :: a
2351   type(c_ptr) :: b
2352   if(c_associated(b, c_loc(a))) &
2353      stop 'b and a do not point to same target'
2354 end subroutine association_test
2355 @end smallexample
2356
2357 @item @emph{See also}:
2358 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2359 @end table
2360
2361
2362 @node C_SIZEOF
2363 @section @code{C_SIZEOF} --- Size in bytes of an expression
2364 @fnindex C_SIZEOF
2365 @cindex expression size
2366 @cindex size of an expression
2367
2368 @table @asis
2369 @item @emph{Description}:
2370 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2371 expression @code{X} occupies.
2372
2373 @item @emph{Standard}:
2374 Fortran 2008
2375
2376 @item @emph{Class}:
2377 Inquiry function of the module @code{ISO_C_BINDING}
2378
2379 @item @emph{Syntax}:
2380 @code{N = C_SIZEOF(X)}
2381
2382 @item @emph{Arguments}:
2383 @multitable @columnfractions .15 .70
2384 @item @var{X} @tab The argument shall be an interoperable data entity.
2385 @end multitable
2386
2387 @item @emph{Return value}:
2388 The return value is of type integer and of the system-dependent kind
2389 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2390 number of bytes occupied by the argument.  If the argument has the
2391 @code{POINTER} attribute, the number of bytes of the storage area pointed
2392 to is returned.  If the argument is of a derived type with @code{POINTER}
2393 or @code{ALLOCATABLE} components, the return value doesn't account for
2394 the sizes of the data pointed to by these components.
2395
2396 @item @emph{Example}:
2397 @smallexample
2398    use iso_c_binding
2399    integer(c_int) :: i
2400    real(c_float) :: r, s(5)
2401    print *, (c_sizeof(s)/c_sizeof(r) == 5)
2402    end
2403 @end smallexample
2404 The example will print @code{.TRUE.} unless you are using a platform
2405 where default @code{REAL} variables are unusually padded.
2406
2407 @item @emph{See also}:
2408 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2409 @end table
2410
2411
2412 @node CEILING
2413 @section @code{CEILING} --- Integer ceiling function
2414 @fnindex CEILING
2415 @cindex ceiling
2416 @cindex rounding, ceiling
2417
2418 @table @asis
2419 @item @emph{Description}:
2420 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2421
2422 @item @emph{Standard}:
2423 Fortran 95 and later
2424
2425 @item @emph{Class}:
2426 Elemental function
2427
2428 @item @emph{Syntax}:
2429 @code{RESULT = CEILING(A [, KIND])}
2430
2431 @item @emph{Arguments}:
2432 @multitable @columnfractions .15 .70
2433 @item @var{A} @tab The type shall be @code{REAL}.
2434 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2435 expression indicating the kind parameter of the result.
2436 @end multitable
2437
2438 @item @emph{Return value}:
2439 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2440 and a default-kind @code{INTEGER} otherwise.
2441
2442 @item @emph{Example}:
2443 @smallexample
2444 program test_ceiling
2445     real :: x = 63.29
2446     real :: y = -63.59
2447     print *, ceiling(x) ! returns 64
2448     print *, ceiling(y) ! returns -63
2449 end program test_ceiling
2450 @end smallexample
2451
2452 @item @emph{See also}:
2453 @ref{FLOOR}, @ref{NINT}
2454
2455 @end table
2456
2457
2458
2459 @node CHAR
2460 @section @code{CHAR} --- Character conversion function
2461 @fnindex CHAR
2462 @cindex conversion, to character
2463
2464 @table @asis
2465 @item @emph{Description}:
2466 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2467
2468 @item @emph{Standard}:
2469 Fortran 77 and later
2470
2471 @item @emph{Class}:
2472 Elemental function
2473
2474 @item @emph{Syntax}:
2475 @code{RESULT = CHAR(I [, KIND])}
2476
2477 @item @emph{Arguments}:
2478 @multitable @columnfractions .15 .70
2479 @item @var{I} @tab The type shall be @code{INTEGER}.
2480 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2481 expression indicating the kind parameter of the result.
2482 @end multitable
2483
2484 @item @emph{Return value}:
2485 The return value is of type @code{CHARACTER(1)}
2486
2487 @item @emph{Example}:
2488 @smallexample
2489 program test_char
2490     integer :: i = 74
2491     character(1) :: c
2492     c = char(i)
2493     print *, i, c ! returns 'J'
2494 end program test_char
2495 @end smallexample
2496
2497 @item @emph{Specific names}:
2498 @multitable @columnfractions .20 .20 .20 .25
2499 @item Name           @tab Argument         @tab Return type             @tab Standard
2500 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2501 @end multitable
2502
2503 @item @emph{Note}:
2504 See @ref{ICHAR} for a discussion of converting between numerical values
2505 and formatted string representations.
2506
2507 @item @emph{See also}:
2508 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2509
2510 @end table
2511
2512
2513
2514 @node CHDIR
2515 @section @code{CHDIR} --- Change working directory
2516 @fnindex CHDIR
2517 @cindex system, working directory
2518
2519 @table @asis
2520 @item @emph{Description}:
2521 Change current working directory to a specified path.
2522
2523 This intrinsic is provided in both subroutine and function forms; however,
2524 only one form can be used in any given program unit.
2525
2526 @item @emph{Standard}:
2527 GNU extension
2528
2529 @item @emph{Class}:
2530 Subroutine, function
2531
2532 @item @emph{Syntax}:
2533 @multitable @columnfractions .80
2534 @item @code{CALL CHDIR(NAME [, STATUS])}
2535 @item @code{STATUS = CHDIR(NAME)}
2536 @end multitable
2537
2538 @item @emph{Arguments}:
2539 @multitable @columnfractions .15 .70
2540 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2541 kind and shall specify a valid path within the file system.
2542 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2543 kind.  Returns 0 on success, and a system specific and nonzero error code
2544 otherwise.
2545 @end multitable
2546
2547 @item @emph{Example}:
2548 @smallexample
2549 PROGRAM test_chdir
2550   CHARACTER(len=255) :: path
2551   CALL getcwd(path)
2552   WRITE(*,*) TRIM(path)
2553   CALL chdir("/tmp")
2554   CALL getcwd(path)
2555   WRITE(*,*) TRIM(path)
2556 END PROGRAM
2557 @end smallexample
2558
2559 @item @emph{See also}:
2560 @ref{GETCWD}
2561 @end table
2562
2563
2564
2565 @node CHMOD
2566 @section @code{CHMOD} --- Change access permissions of files
2567 @fnindex CHMOD
2568 @cindex file system, change access mode
2569
2570 @table @asis
2571 @item @emph{Description}:
2572 @code{CHMOD} changes the permissions of a file. This function invokes
2573 @code{/bin/chmod} and might therefore not work on all platforms.
2574
2575 This intrinsic is provided in both subroutine and function forms; however,
2576 only one form can be used in any given program unit.
2577
2578 @item @emph{Standard}:
2579 GNU extension
2580
2581 @item @emph{Class}:
2582 Subroutine, function
2583
2584 @item @emph{Syntax}:
2585 @multitable @columnfractions .80
2586 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2587 @item @code{STATUS = CHMOD(NAME, MODE)}
2588 @end multitable
2589
2590 @item @emph{Arguments}:
2591 @multitable @columnfractions .15 .70
2592
2593 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2594 file name. Trailing blanks are ignored unless the character
2595 @code{achar(0)} is present, then all characters up to and excluding
2596 @code{achar(0)} are used as the file name.
2597
2598 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2599 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2600 argument of @code{/bin/chmod}.
2601
2602 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2603 @code{0} on success and nonzero otherwise.
2604 @end multitable
2605
2606 @item @emph{Return value}:
2607 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2608 otherwise.
2609
2610 @item @emph{Example}:
2611 @code{CHMOD} as subroutine
2612 @smallexample
2613 program chmod_test
2614   implicit none
2615   integer :: status
2616   call chmod('test.dat','u+x',status)
2617   print *, 'Status: ', status
2618 end program chmod_test
2619 @end smallexample
2620 @code{CHMOD} as function:
2621 @smallexample
2622 program chmod_test
2623   implicit none
2624   integer :: status
2625   status = chmod('test.dat','u+x')
2626   print *, 'Status: ', status
2627 end program chmod_test
2628 @end smallexample
2629
2630 @end table
2631
2632
2633
2634 @node CMPLX
2635 @section @code{CMPLX} --- Complex conversion function
2636 @fnindex CMPLX
2637 @cindex complex numbers, conversion to
2638 @cindex conversion, to complex
2639
2640 @table @asis
2641 @item @emph{Description}:
2642 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2643 the real component.  If @var{Y} is present it is converted to the imaginary
2644 component.  If @var{Y} is not present then the imaginary component is set to
2645 0.0.  If @var{X} is complex then @var{Y} must not be present.
2646
2647 @item @emph{Standard}:
2648 Fortran 77 and later
2649
2650 @item @emph{Class}:
2651 Elemental function
2652
2653 @item @emph{Syntax}:
2654 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2655
2656 @item @emph{Arguments}:
2657 @multitable @columnfractions .15 .70
2658 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2659 or @code{COMPLEX}.
2660 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2661 @code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2662 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2663 expression indicating the kind parameter of the result.
2664 @end multitable
2665
2666 @item @emph{Return value}:
2667 The return value is of @code{COMPLEX} type, with a kind equal to
2668 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2669 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2670 @var{X} and @var{Y}.
2671
2672 @item @emph{Example}:
2673 @smallexample
2674 program test_cmplx
2675     integer :: i = 42
2676     real :: x = 3.14
2677     complex :: z
2678     z = cmplx(i, x)
2679     print *, z, cmplx(x)
2680 end program test_cmplx
2681 @end smallexample
2682
2683 @item @emph{See also}:
2684 @ref{COMPLEX}
2685 @end table
2686
2687
2688
2689 @node COMMAND_ARGUMENT_COUNT
2690 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2691 @fnindex COMMAND_ARGUMENT_COUNT
2692 @cindex command-line arguments
2693 @cindex command-line arguments, number of
2694 @cindex arguments, to program
2695
2696 @table @asis
2697 @item @emph{Description}:
2698 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2699 command line when the containing program was invoked.
2700
2701 @item @emph{Standard}:
2702 Fortran 2003 and later
2703
2704 @item @emph{Class}:
2705 Inquiry function
2706
2707 @item @emph{Syntax}:
2708 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2709
2710 @item @emph{Arguments}:
2711 @multitable @columnfractions .15 .70
2712 @item None
2713 @end multitable
2714
2715 @item @emph{Return value}:
2716 The return value is an @code{INTEGER} of default kind.
2717
2718 @item @emph{Example}:
2719 @smallexample
2720 program test_command_argument_count
2721     integer :: count
2722     count = command_argument_count()
2723     print *, count
2724 end program test_command_argument_count
2725 @end smallexample
2726
2727 @item @emph{See also}:
2728 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2729 @end table
2730
2731
2732
2733 @node COMPILER_OPTIONS
2734 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2735 @fnindex COMPILER_OPTIONS
2736 @cindex flags inquiry function
2737 @cindex options inquiry function
2738 @cindex compiler flags inquiry function
2739
2740 @table @asis
2741 @item @emph{Description}:
2742 @code{COMPILER_OPTIONS} returns a string with the options used for
2743 compiling.
2744
2745 @item @emph{Standard}:
2746 Fortran 2008
2747
2748 @item @emph{Class}:
2749 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2750
2751 @item @emph{Syntax}:
2752 @code{STR = COMPILER_OPTIONS()}
2753
2754 @item @emph{Arguments}:
2755 None.
2756
2757 @item @emph{Return value}:
2758 The return value is a default-kind string with system-dependent length.
2759 It contains the compiler flags used to compile the file, which called
2760 the @code{COMPILER_OPTIONS} intrinsic.
2761
2762 @item @emph{Example}:
2763 @smallexample
2764    use iso_fortran_env
2765    print '(4a)', 'This file was compiled by ', &
2766                  compiler_version(), ' using the the options ', &
2767                  compiler_options()
2768    end
2769 @end smallexample
2770
2771 @item @emph{See also}:
2772 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2773 @end table
2774
2775
2776
2777 @node COMPILER_VERSION
2778 @section @code{COMPILER_VERSION} --- Compiler version string
2779 @fnindex COMPILER_VERSION
2780 @cindex compiler, name and version
2781 @cindex version of the compiler
2782
2783 @table @asis
2784 @item @emph{Description}:
2785 @code{COMPILER_VERSION} returns a string with the name and the
2786 version of the compiler.
2787
2788 @item @emph{Standard}:
2789 Fortran 2008
2790
2791 @item @emph{Class}:
2792 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2793
2794 @item @emph{Syntax}:
2795 @code{STR = COMPILER_VERSION()}
2796
2797 @item @emph{Arguments}:
2798 None.
2799
2800 @item @emph{Return value}:
2801 The return value is a default-kind string with system-dependent length.
2802 It contains the name of the compiler and its version number.
2803
2804 @item @emph{Example}:
2805 @smallexample
2806    use iso_fortran_env
2807    print '(4a)', 'This file was compiled by ', &
2808                  compiler_version(), ' using the the options ', &
2809                  compiler_options()
2810    end
2811 @end smallexample
2812
2813 @item @emph{See also}:
2814 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2815 @end table
2816
2817
2818
2819 @node COMPLEX
2820 @section @code{COMPLEX} --- Complex conversion function
2821 @fnindex COMPLEX
2822 @cindex complex numbers, conversion to
2823 @cindex conversion, to complex
2824
2825 @table @asis
2826 @item @emph{Description}:
2827 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2828 to the real component and @var{Y} is converted to the imaginary
2829 component.
2830
2831 @item @emph{Standard}:
2832 GNU extension
2833
2834 @item @emph{Class}:
2835 Elemental function
2836
2837 @item @emph{Syntax}:
2838 @code{RESULT = COMPLEX(X, Y)}
2839
2840 @item @emph{Arguments}:
2841 @multitable @columnfractions .15 .70
2842 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2843 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2844 @end multitable
2845
2846 @item @emph{Return value}:
2847 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2848 value is of default @code{COMPLEX} type.
2849
2850 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2851 type and one is of @code{INTEGER} type, then the return value is of
2852 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2853 argument with the highest precision.
2854
2855 @item @emph{Example}:
2856 @smallexample
2857 program test_complex
2858     integer :: i = 42
2859     real :: x = 3.14
2860     print *, complex(i, x)
2861 end program test_complex
2862 @end smallexample
2863
2864 @item @emph{See also}:
2865 @ref{CMPLX}
2866 @end table
2867
2868
2869
2870 @node CONJG
2871 @section @code{CONJG} --- Complex conjugate function
2872 @fnindex CONJG
2873 @fnindex DCONJG
2874 @cindex complex conjugate
2875
2876 @table @asis
2877 @item @emph{Description}:
2878 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2879 then the result is @code{(x, -y)}
2880
2881 @item @emph{Standard}:
2882 Fortran 77 and later, has overloads that are GNU extensions
2883
2884 @item @emph{Class}:
2885 Elemental function
2886
2887 @item @emph{Syntax}:
2888 @code{Z = CONJG(Z)}
2889
2890 @item @emph{Arguments}:
2891 @multitable @columnfractions .15 .70
2892 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2893 @end multitable
2894
2895 @item @emph{Return value}:
2896 The return value is of type @code{COMPLEX}.
2897
2898 @item @emph{Example}:
2899 @smallexample
2900 program test_conjg
2901     complex :: z = (2.0, 3.0)
2902     complex(8) :: dz = (2.71_8, -3.14_8)
2903     z= conjg(z)
2904     print *, z
2905     dz = dconjg(dz)
2906     print *, dz
2907 end program test_conjg
2908 @end smallexample
2909
2910 @item @emph{Specific names}:
2911 @multitable @columnfractions .20 .20 .20 .25
2912 @item Name             @tab Argument             @tab Return type       @tab Standard
2913 @item @code{CONJG(Z)}  @tab @code{COMPLEX Z}     @tab @code{COMPLEX}    @tab GNU extension
2914 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)} @tab GNU extension
2915 @end multitable
2916 @end table
2917
2918
2919
2920 @node COS
2921 @section @code{COS} --- Cosine function
2922 @fnindex COS
2923 @fnindex DCOS
2924 @fnindex CCOS
2925 @fnindex ZCOS
2926 @fnindex CDCOS
2927 @cindex trigonometric function, cosine
2928 @cindex cosine
2929
2930 @table @asis
2931 @item @emph{Description}:
2932 @code{COS(X)} computes the cosine of @var{X}.
2933
2934 @item @emph{Standard}:
2935 Fortran 77 and later, has overloads that are GNU extensions
2936
2937 @item @emph{Class}:
2938 Elemental function
2939
2940 @item @emph{Syntax}:
2941 @code{RESULT = COS(X)}
2942
2943 @item @emph{Arguments}:
2944 @multitable @columnfractions .15 .70
2945 @item @var{X} @tab The type shall be @code{REAL} or
2946 @code{COMPLEX}.
2947 @end multitable
2948
2949 @item @emph{Return value}:
2950 The return value is of the same type and kind as @var{X}. The real part
2951 of the result is in radians. If @var{X} is of the type @code{REAL},
2952 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2953
2954 @item @emph{Example}:
2955 @smallexample
2956 program test_cos
2957   real :: x = 0.0
2958   x = cos(x)
2959 end program test_cos
2960 @end smallexample
2961
2962 @item @emph{Specific names}:
2963 @multitable @columnfractions .20 .20 .20 .25
2964 @item Name            @tab Argument            @tab Return type       @tab Standard
2965 @item @code{COS(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab Fortran 77 and later
2966 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
2967 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2968 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2969 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2970 @end multitable
2971
2972 @item @emph{See also}:
2973 Inverse function: @ref{ACOS}
2974
2975 @end table
2976
2977
2978
2979 @node COSH
2980 @section @code{COSH} --- Hyperbolic cosine function
2981 @fnindex COSH
2982 @fnindex DCOSH
2983 @cindex hyperbolic cosine
2984 @cindex hyperbolic function, cosine
2985 @cindex cosine, hyperbolic
2986
2987 @table @asis
2988 @item @emph{Description}:
2989 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2990
2991 @item @emph{Standard}:
2992 Fortran 77 and later, for a complex argument Fortran 2008 or later
2993
2994 @item @emph{Class}:
2995 Elemental function
2996
2997 @item @emph{Syntax}:
2998 @code{X = COSH(X)}
2999
3000 @item @emph{Arguments}:
3001 @multitable @columnfractions .15 .70
3002 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3003 @end multitable
3004
3005 @item @emph{Return value}:
3006 The return value has same type and kind as @var{X}. If @var{X} is
3007 complex, the imaginary part of the result is in radians. If @var{X}
3008 is @code{REAL}, the return value has a lower bound of one,
3009 @math{\cosh (x) \geq 1}.
3010
3011 @item @emph{Example}:
3012 @smallexample
3013 program test_cosh
3014   real(8) :: x = 1.0_8
3015   x = cosh(x)
3016 end program test_cosh
3017 @end smallexample
3018
3019 @item @emph{Specific names}:
3020 @multitable @columnfractions .20 .20 .20 .25
3021 @item Name            @tab Argument          @tab Return type       @tab Standard
3022 @item @code{COSH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
3023 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
3024 @end multitable
3025
3026 @item @emph{See also}:
3027 Inverse function: @ref{ACOSH}
3028
3029 @end table
3030
3031
3032
3033 @node COUNT
3034 @section @code{COUNT} --- Count function
3035 @fnindex COUNT
3036 @cindex array, conditionally count elements
3037 @cindex array, element counting
3038 @cindex array, number of elements
3039
3040 @table @asis
3041 @item @emph{Description}:
3042
3043 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3044 or, if the @var{DIM} argument is supplied, counts the number of
3045 elements along each row of the array in the @var{DIM} direction.
3046 If the array has zero size, or all of the elements of @var{MASK} are
3047 @code{.FALSE.}, then the result is @code{0}.
3048
3049 @item @emph{Standard}:
3050 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3051
3052 @item @emph{Class}:
3053 Transformational function
3054
3055 @item @emph{Syntax}:
3056 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3057
3058 @item @emph{Arguments}:
3059 @multitable @columnfractions .15 .70
3060 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3061 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
3062 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3063 expression indicating the kind parameter of the result.
3064 @end multitable
3065
3066 @item @emph{Return value}:
3067 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3068 @var{KIND} is absent, the return value is of default integer kind.
3069 If @var{DIM} is present, the result is an array with a rank one less
3070 than the rank of @var{ARRAY}, and a size corresponding to the shape
3071 of @var{ARRAY} with the @var{DIM} dimension removed.
3072
3073 @item @emph{Example}:
3074 @smallexample
3075 program test_count
3076     integer, dimension(2,3) :: a, b
3077     logical, dimension(2,3) :: mask
3078     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3079     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3080     print '(3i3)', a(1,:)
3081     print '(3i3)', a(2,:)
3082     print *
3083     print '(3i3)', b(1,:)
3084     print '(3i3)', b(2,:)
3085     print *
3086     mask = a.ne.b
3087     print '(3l3)', mask(1,:)
3088     print '(3l3)', mask(2,:)
3089     print *
3090     print '(3i3)', count(mask)
3091     print *
3092     print '(3i3)', count(mask, 1)
3093     print *
3094     print '(3i3)', count(mask, 2)
3095 end program test_count
3096 @end smallexample
3097 @end table
3098
3099
3100
3101 @node CPU_TIME
3102 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3103 @fnindex CPU_TIME
3104 @cindex time, elapsed
3105
3106 @table @asis
3107 @item @emph{Description}:
3108 Returns a @code{REAL} value representing the elapsed CPU time in
3109 seconds.  This is useful for testing segments of code to determine
3110 execution time.
3111
3112 If a time source is available, time will be reported with microsecond
3113 resolution. If no time source is available, @var{TIME} is set to
3114 @code{-1.0}.
3115
3116 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3117 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3118 value is meaningless, only differences between subsequent calls to
3119 this subroutine, as shown in the example below, should be used.
3120
3121
3122 @item @emph{Standard}:
3123 Fortran 95 and later
3124
3125 @item @emph{Class}:
3126 Subroutine
3127
3128 @item @emph{Syntax}:
3129 @code{CALL CPU_TIME(TIME)}
3130
3131 @item @emph{Arguments}:
3132 @multitable @columnfractions .15 .70
3133 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3134 @end multitable
3135
3136 @item @emph{Return value}:
3137 None
3138
3139 @item @emph{Example}:
3140 @smallexample
3141 program test_cpu_time
3142     real :: start, finish
3143     call cpu_time(start)
3144         ! put code to test here
3145     call cpu_time(finish)
3146     print '("Time = ",f6.3," seconds.")',finish-start
3147 end program test_cpu_time
3148 @end smallexample
3149
3150 @item @emph{See also}:
3151 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3152 @end table
3153
3154
3155
3156 @node CSHIFT
3157 @section @code{CSHIFT} --- Circular shift elements of an array
3158 @fnindex CSHIFT
3159 @cindex array, shift circularly
3160 @cindex array, permutation
3161 @cindex array, rotate
3162
3163 @table @asis
3164 @item @emph{Description}:
3165 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3166 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
3167 taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
3168 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3169 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3170 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
3171 sections of @var{ARRAY} along the given dimension are shifted.  Elements
3172 shifted out one end of each rank one section are shifted back in the other end.
3173
3174 @item @emph{Standard}:
3175 Fortran 95 and later
3176
3177 @item @emph{Class}:
3178 Transformational function
3179
3180 @item @emph{Syntax}:
3181 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3182
3183 @item @emph{Arguments}:
3184 @multitable @columnfractions .15 .70
3185 @item @var{ARRAY}  @tab Shall be an array of any type.
3186 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3187 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3188 @end multitable
3189
3190 @item @emph{Return value}:
3191 Returns an array of same type and rank as the @var{ARRAY} argument.
3192
3193 @item @emph{Example}:
3194 @smallexample
3195 program test_cshift
3196     integer, dimension(3,3) :: a
3197     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3198     print '(3i3)', a(1,:)
3199     print '(3i3)', a(2,:)
3200     print '(3i3)', a(3,:)
3201     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3202     print *
3203     print '(3i3)', a(1,:)
3204     print '(3i3)', a(2,:)
3205     print '(3i3)', a(3,:)
3206 end program test_cshift
3207 @end smallexample
3208 @end table
3209
3210
3211
3212 @node CTIME
3213 @section @code{CTIME} --- Convert a time into a string
3214 @fnindex CTIME
3215 @cindex time, conversion to string
3216 @cindex conversion, to string
3217
3218 @table @asis
3219 @item @emph{Description}:
3220 @code{CTIME} converts a system time value, such as returned by
3221 @code{TIME8}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
3222
3223 This intrinsic is provided in both subroutine and function forms; however,
3224 only one form can be used in any given program unit.
3225
3226 @item @emph{Standard}:
3227 GNU extension
3228
3229 @item @emph{Class}:
3230 Subroutine, function
3231
3232 @item @emph{Syntax}:
3233 @multitable @columnfractions .80
3234 @item @code{CALL CTIME(TIME, RESULT)}.
3235 @item @code{RESULT = CTIME(TIME)}, (not recommended).
3236 @end multitable
3237
3238 @item @emph{Arguments}:
3239 @multitable @columnfractions .15 .70
3240 @item @var{TIME}    @tab The type shall be of type @code{INTEGER(KIND=8)}.
3241 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
3242 of default kind.
3243 @end multitable
3244
3245 @item @emph{Return value}:
3246 The converted date and time as a string.
3247
3248 @item @emph{Example}:
3249 @smallexample
3250 program test_ctime
3251     integer(8) :: i
3252     character(len=30) :: date
3253     i = time8()
3254
3255     ! Do something, main part of the program
3256
3257     call ctime(i,date)
3258     print *, 'Program was started on ', date
3259 end program test_ctime
3260 @end smallexample
3261
3262 @item @emph{See Also}:
3263 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3264 @end table
3265
3266
3267
3268 @node DATE_AND_TIME
3269 @section @code{DATE_AND_TIME} --- Date and time subroutine
3270 @fnindex DATE_AND_TIME
3271 @cindex date, current
3272 @cindex current date
3273 @cindex time, current
3274 @cindex current time
3275
3276 @table @asis
3277 @item @emph{Description}:
3278 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3279 time information from the real-time system clock.  @var{DATE} is
3280 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
3281 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3282 representing the difference with respect to Coordinated Universal Time (UTC).
3283 Unavailable time and date parameters return blanks.
3284
3285 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3286
3287 @multitable @columnfractions .15 .30 .40
3288 @item @tab @code{VALUE(1)}: @tab The year
3289 @item @tab @code{VALUE(2)}: @tab The month
3290 @item @tab @code{VALUE(3)}: @tab The day of the month
3291 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3292 @item @tab @code{VALUE(5)}: @tab The hour of the day
3293 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3294 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3295 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3296 @end multitable
3297
3298 @item @emph{Standard}:
3299 Fortran 95 and later
3300
3301 @item @emph{Class}:
3302 Subroutine
3303
3304 @item @emph{Syntax}:
3305 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3306
3307 @item @emph{Arguments}:
3308 @multitable @columnfractions .15 .70
3309 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3310 or larger, and of default kind.
3311 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3312 or larger, and of default kind.
3313 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3314 or larger, and of default kind.
3315 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3316 @end multitable
3317
3318 @item @emph{Return value}:
3319 None
3320
3321 @item @emph{Example}:
3322 @smallexample
3323 program test_time_and_date
3324     character(8)  :: date
3325     character(10) :: time
3326     character(5)  :: zone
3327     integer,dimension(8) :: values
3328     ! using keyword arguments
3329     call date_and_time(date,time,zone,values)
3330     call date_and_time(DATE=date,ZONE=zone)
3331     call date_and_time(TIME=time)
3332     call date_and_time(VALUES=values)
3333     print '(a,2x,a,2x,a)', date, time, zone
3334     print '(8i5))', values
3335 end program test_time_and_date
3336 @end smallexample
3337
3338 @item @emph{See also}:
3339 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3340 @end table
3341
3342
3343
3344 @node DBLE
3345 @section @code{DBLE} --- Double conversion function
3346 @fnindex DBLE
3347 @cindex conversion, to real
3348
3349 @table @asis
3350 @item @emph{Description}:
3351 @code{DBLE(A)} Converts @var{A} to double precision real type.
3352
3353 @item @emph{Standard}:
3354 Fortran 77 and later
3355
3356 @item @emph{Class}:
3357 Elemental function
3358
3359 @item @emph{Syntax}:
3360 @code{RESULT = DBLE(A)}
3361
3362 @item @emph{Arguments}:
3363 @multitable @columnfractions .15 .70
3364 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3365 or @code{COMPLEX}.
3366 @end multitable
3367
3368 @item @emph{Return value}:
3369 The return value is of type double precision real.
3370
3371 @item @emph{Example}:
3372 @smallexample
3373 program test_dble
3374     real    :: x = 2.18
3375     integer :: i = 5
3376     complex :: z = (2.3,1.14)
3377     print *, dble(x), dble(i), dble(z)
3378 end program test_dble
3379 @end smallexample
3380
3381 @item @emph{See also}:
3382 @ref{REAL}
3383 @end table
3384
3385
3386
3387 @node DCMPLX
3388 @section @code{DCMPLX} --- Double complex conversion function
3389 @fnindex DCMPLX
3390 @cindex complex numbers, conversion to
3391 @cindex conversion, to complex
3392
3393 @table @asis
3394 @item @emph{Description}:
3395 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3396 converted to the real component.  If @var{Y} is present it is converted to the
3397 imaginary component.  If @var{Y} is not present then the imaginary component is
3398 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3399
3400 @item @emph{Standard}:
3401 GNU extension
3402
3403 @item @emph{Class}:
3404 Elemental function
3405
3406 @item @emph{Syntax}:
3407 @code{RESULT = DCMPLX(X [, Y])}
3408
3409 @item @emph{Arguments}:
3410 @multitable @columnfractions .15 .70
3411 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3412 or @code{COMPLEX}.
3413 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3414 @code{INTEGER} or @code{REAL}.
3415 @end multitable
3416
3417 @item @emph{Return value}:
3418 The return value is of type @code{COMPLEX(8)}
3419
3420 @item @emph{Example}:
3421 @smallexample
3422 program test_dcmplx
3423     integer :: i = 42
3424     real :: x = 3.14
3425     complex :: z
3426     z = cmplx(i, x)
3427     print *, dcmplx(i)
3428     print *, dcmplx(x)
3429     print *, dcmplx(z)
3430     print *, dcmplx(x,i)
3431 end program test_dcmplx
3432 @end smallexample
3433 @end table
3434
3435
3436 @node DIGITS
3437 @section @code{DIGITS} --- Significant binary digits function
3438 @fnindex DIGITS
3439 @cindex model representation, significant digits
3440
3441 @table @asis
3442 @item @emph{Description}:
3443 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3444 model representation of @var{X}.  For example, on a system using a 32-bit
3445 floating point representation, a default real number would likely return 24.
3446
3447 @item @emph{Standard}:
3448 Fortran 95 and later
3449
3450 @item @emph{Class}:
3451 Inquiry function
3452
3453 @item @emph{Syntax}:
3454 @code{RESULT = DIGITS(X)}
3455
3456 @item @emph{Arguments}:
3457 @multitable @columnfractions .15 .70
3458 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3459 @end multitable
3460
3461 @item @emph{Return value}:
3462 The return value is of type @code{INTEGER}.
3463
3464 @item @emph{Example}:
3465 @smallexample
3466 program test_digits
3467     integer :: i = 12345
3468     real :: x = 3.143
3469     real(8) :: y = 2.33
3470     print *, digits(i)
3471     print *, digits(x)
3472     print *, digits(y)
3473 end program test_digits
3474 @end smallexample
3475 @end table
3476
3477
3478
3479 @node DIM
3480 @section @code{DIM} --- Positive difference
3481 @fnindex DIM
3482 @fnindex IDIM
3483 @fnindex DDIM
3484 @cindex positive difference
3485
3486 @table @asis
3487 @item @emph{Description}:
3488 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3489 otherwise returns zero.
3490
3491 @item @emph{Standard}:
3492 Fortran 77 and later
3493
3494 @item @emph{Class}:
3495 Elemental function
3496
3497 @item @emph{Syntax}:
3498 @code{RESULT = DIM(X, Y)}
3499
3500 @item @emph{Arguments}:
3501 @multitable @columnfractions .15 .70
3502 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3503 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3504 @end multitable
3505
3506 @item @emph{Return value}:
3507 The return value is of type @code{INTEGER} or @code{REAL}.
3508
3509 @item @emph{Example}:
3510 @smallexample
3511 program test_dim
3512     integer :: i
3513     real(8) :: x
3514     i = dim(4, 15)
3515     x = dim(4.345_8, 2.111_8)
3516     print *, i
3517     print *, x
3518 end program test_dim
3519 @end smallexample
3520
3521 @item @emph{Specific names}:
3522 @multitable @columnfractions .20 .20 .20 .25
3523 @item Name             @tab Argument               @tab Return type       @tab Standard
3524 @item @code{DIM(X,Y)}  @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3525 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3526 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3527 @end multitable
3528 @end table
3529
3530
3531
3532 @node DOT_PRODUCT
3533 @section @code{DOT_PRODUCT} --- Dot product function
3534 @fnindex DOT_PRODUCT
3535 @cindex dot product
3536 @cindex vector product
3537 @cindex product, vector
3538
3539 @table @asis
3540 @item @emph{Description}:
3541 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3542 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3543 either numeric or logical and must be arrays of rank one and of equal size. If
3544 the vectors are @code{INTEGER} or @code{REAL}, the result is
3545 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3546 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3547 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3548
3549 @item @emph{Standard}:
3550 Fortran 95 and later
3551
3552 @item @emph{Class}:
3553 Transformational function
3554
3555 @item @emph{Syntax}:
3556 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3557
3558 @item @emph{Arguments}:
3559 @multitable @columnfractions .15 .70
3560 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3561 @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.
3562 @end multitable
3563
3564 @item @emph{Return value}:
3565 If the arguments are numeric, the return value is a scalar of numeric type,
3566 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3567 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3568
3569 @item @emph{Example}:
3570 @smallexample
3571 program test_dot_prod
3572     integer, dimension(3) :: a, b
3573     a = (/ 1, 2, 3 /)
3574     b = (/ 4, 5, 6 /)
3575     print '(3i3)', a
3576     print *
3577     print '(3i3)', b
3578     print *
3579     print *, dot_product(a,b)
3580 end program test_dot_prod
3581 @end smallexample
3582 @end table
3583
3584
3585
3586 @node DPROD
3587 @section @code{DPROD} --- Double product function
3588 @fnindex DPROD
3589 @cindex product, double-precision
3590
3591 @table @asis
3592 @item @emph{Description}:
3593 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3594
3595 @item @emph{Standard}:
3596 Fortran 77 and later
3597
3598 @item @emph{Class}:
3599 Elemental function
3600
3601 @item @emph{Syntax}:
3602 @code{RESULT = DPROD(X, Y)}
3603
3604 @item @emph{Arguments}:
3605 @multitable @columnfractions .15 .70
3606 @item @var{X} @tab The type shall be @code{REAL}.
3607 @item @var{Y} @tab The type shall be @code{REAL}.
3608 @end multitable
3609
3610 @item @emph{Return value}:
3611 The return value is of type @code{REAL(8)}.
3612
3613 @item @emph{Example}:
3614 @smallexample
3615 program test_dprod
3616     real :: x = 5.2
3617     real :: y = 2.3
3618     real(8) :: d
3619     d = dprod(x,y)
3620     print *, d
3621 end program test_dprod
3622 @end smallexample
3623
3624 @item @emph{Specific names}:
3625 @multitable @columnfractions .20 .20 .20 .25
3626 @item Name              @tab Argument               @tab Return type       @tab Standard
3627 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3628 @end multitable
3629
3630 @end table
3631
3632
3633 @node DREAL
3634 @section @code{DREAL} --- Double real part function
3635 @fnindex DREAL
3636 @cindex complex numbers, real part
3637
3638 @table @asis
3639 @item @emph{Description}:
3640 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3641
3642 @item @emph{Standard}:
3643 GNU extension
3644
3645 @item @emph{Class}:
3646 Elemental function
3647
3648 @item @emph{Syntax}:
3649 @code{RESULT = DREAL(A)}
3650
3651 @item @emph{Arguments}:
3652 @multitable @columnfractions .15 .70
3653 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3654 @end multitable
3655
3656 @item @emph{Return value}:
3657 The return value is of type @code{REAL(8)}.
3658
3659 @item @emph{Example}:
3660 @smallexample
3661 program test_dreal
3662     complex(8) :: z = (1.3_8,7.2_8)
3663     print *, dreal(z)
3664 end program test_dreal
3665 @end smallexample
3666
3667 @item @emph{See also}:
3668 @ref{AIMAG}
3669
3670 @end table
3671
3672
3673
3674 @node DSHIFTL
3675 @section @code{DSHIFTL} --- Combined left shift
3676 @fnindex DSHIFTL
3677 @cindex left shift, combined
3678 @cindex shift, left
3679
3680 @table @asis
3681 @item @emph{Description}:
3682 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3683 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3684 bits of @var{J}, and the remaining bits are the rightmost bits of
3685 @var{I}.
3686
3687 @item @emph{Standard}:
3688 Fortran 2008 and later
3689
3690 @item @emph{Class}:
3691 Elemental function
3692
3693 @item @emph{Syntax}:
3694 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3695
3696 @item @emph{Arguments}:
3697 @multitable @columnfractions .15 .70
3698 @item @var{I} @tab Shall be of type @code{INTEGER}.
3699 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3700 as @var{I}.
3701 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3702 @end multitable
3703
3704 @item @emph{Return value}:
3705 The return value has same type and kind as @var{I}.
3706
3707 @item @emph{See also}:
3708 @ref{DSHIFTR}
3709
3710 @end table
3711
3712
3713
3714 @node DSHIFTR
3715 @section @code{DSHIFTR} --- Combined right shift
3716 @fnindex DSHIFTR
3717 @cindex right shift, combined
3718 @cindex shift, right
3719
3720 @table @asis
3721 @item @emph{Description}:
3722 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3723 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3724 bits of @var{I}, and the remaining bits are the leftmost bits of
3725 @var{J}.
3726
3727 @item @emph{Standard}:
3728 Fortran 2008 and later
3729
3730 @item @emph{Class}:
3731 Elemental function
3732
3733 @item @emph{Syntax}:
3734 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3735
3736 @item @emph{Arguments}:
3737 @multitable @columnfractions .15 .70
3738 @item @var{I} @tab Shall be of type @code{INTEGER}.
3739 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3740 as @var{I}.
3741 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3742 @end multitable
3743
3744 @item @emph{Return value}:
3745 The return value has same type and kind as @var{I}.
3746
3747 @item @emph{See also}:
3748 @ref{DSHIFTL}
3749
3750 @end table
3751
3752
3753
3754 @node DTIME
3755 @section @code{DTIME} --- Execution time subroutine (or function)
3756 @fnindex DTIME
3757 @cindex time, elapsed
3758 @cindex elapsed time
3759
3760 @table @asis
3761 @item @emph{Description}:
3762 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3763 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3764 returns the user and system components of this time in @code{VALUES(1)} and
3765 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3766 VALUES(2)}.
3767
3768 Subsequent invocations of @code{DTIME} return values accumulated since the
3769 previous invocation.
3770
3771 On some systems, the underlying timings are represented using types with
3772 sufficiently small limits that overflows (wrap around) are possible, such as
3773 32-bit types. Therefore, the values returned by this intrinsic might be, or
3774 become, negative, or numerically less than previous values, during a single
3775 run of the compiled program.
3776
3777 Please note, that this implementation is thread safe if used within OpenMP
3778 directives, i.e., its state will be consistent while called from multiple
3779 threads. However, if @code{DTIME} is called from multiple threads, the result
3780 is still the time since the last invocation. This may not give the intended
3781 results. If possible, use @code{CPU_TIME} instead.
3782
3783 This intrinsic is provided in both subroutine and function forms; however,
3784 only one form can be used in any given program unit.
3785
3786 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3787
3788 @multitable @columnfractions .15 .30 .40
3789 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3790 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3791 @item @tab @code{TIME}: @tab Run time since start in seconds.
3792 @end multitable
3793
3794 @item @emph{Standard}:
3795 GNU extension
3796
3797 @item @emph{Class}:
3798 Subroutine, function
3799
3800 @item @emph{Syntax}:
3801 @multitable @columnfractions .80
3802 @item @code{CALL DTIME(VALUES, TIME)}.
3803 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3804 @end multitable
3805
3806 @item @emph{Arguments}:
3807 @multitable @columnfractions .15 .70
3808 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3809 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3810 @end multitable
3811
3812 @item @emph{Return value}:
3813 Elapsed time in seconds since the last invocation or since the start of program
3814 execution if not called before.
3815
3816 @item @emph{Example}:
3817 @smallexample
3818 program test_dtime
3819     integer(8) :: i, j
3820     real, dimension(2) :: tarray
3821     real :: result
3822     call dtime(tarray, result)
3823     print *, result
3824     print *, tarray(1)
3825     print *, tarray(2)
3826     do i=1,100000000    ! Just a delay
3827         j = i * i - i
3828     end do
3829     call dtime(tarray, result)
3830     print *, result
3831     print *, tarray(1)
3832     print *, tarray(2)
3833 end program test_dtime
3834 @end smallexample
3835
3836 @item @emph{See also}:
3837 @ref{CPU_TIME}
3838
3839 @end table
3840
3841
3842
3843 @node EOSHIFT
3844 @section @code{EOSHIFT} --- End-off shift elements of an array
3845 @fnindex EOSHIFT
3846 @cindex array, shift
3847
3848 @table @asis
3849 @item @emph{Description}:
3850 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3851 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3852 omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
3853 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3854 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3855 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3856 then all complete rank one sections of @var{ARRAY} along the given dimension are
3857 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3858 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3859 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3860 following are copied in depending on the type of @var{ARRAY}.
3861
3862 @multitable @columnfractions .15 .80
3863 @item @emph{Array Type} @tab @emph{Boundary Value}
3864 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3865 @item Logical  @tab @code{.FALSE.}.
3866 @item Character(@var{len}) @tab @var{len} blanks.
3867 @end multitable
3868
3869 @item @emph{Standard}:
3870 Fortran 95 and later
3871
3872 @item @emph{Class}:
3873 Transformational function
3874
3875 @item @emph{Syntax}:
3876 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3877
3878 @item @emph{Arguments}:
3879 @multitable @columnfractions .15 .70
3880 @item @var{ARRAY}  @tab May be any type, not scalar.
3881 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3882 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3883 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3884 @end multitable
3885
3886 @item @emph{Return value}:
3887 Returns an array of same type and rank as the @var{ARRAY} argument.
3888
3889 @item @emph{Example}:
3890 @smallexample
3891 program test_eoshift
3892     integer, dimension(3,3) :: a
3893     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3894     print '(3i3)', a(1,:)
3895     print '(3i3)', a(2,:)
3896     print '(3i3)', a(3,:)
3897     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3898     print *
3899     print '(3i3)', a(1,:)
3900     print '(3i3)', a(2,:)
3901     print '(3i3)', a(3,:)
3902 end program test_eoshift
3903 @end smallexample
3904 @end table
3905
3906
3907
3908 @node EPSILON
3909 @section @code{EPSILON} --- Epsilon function
3910 @fnindex EPSILON
3911 @cindex model representation, epsilon
3912
3913 @table @asis
3914 @item @emph{Description}:
3915 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3916 as @var{X} such that @math{1 + E > 1}.
3917
3918 @item @emph{Standard}:
3919 Fortran 95 and later
3920
3921 @item @emph{Class}:
3922 Inquiry function
3923
3924 @item @emph{Syntax}:
3925 @code{RESULT = EPSILON(X)}
3926
3927 @item @emph{Arguments}:
3928 @multitable @columnfractions .15 .70
3929 @item @var{X} @tab The type shall be @code{REAL}.
3930 @end multitable
3931
3932 @item @emph{Return value}:
3933 The return value is of same type as the argument.
3934
3935 @item @emph{Example}:
3936 @smallexample
3937 program test_epsilon
3938     real :: x = 3.143
3939     real(8) :: y = 2.33
3940     print *, EPSILON(x)
3941     print *, EPSILON(y)
3942 end program test_epsilon
3943 @end smallexample
3944 @end table
3945
3946
3947
3948 @node ERF
3949 @section @code{ERF} --- Error function
3950 @fnindex ERF
3951 @cindex error function
3952
3953 @table @asis
3954 @item @emph{Description}:
3955 @code{ERF(X)} computes the error function of @var{X}.
3956
3957 @item @emph{Standard}:
3958 Fortran 2008 and later
3959
3960 @item @emph{Class}:
3961 Elemental function
3962
3963 @item @emph{Syntax}:
3964 @code{RESULT = ERF(X)}
3965
3966 @item @emph{Arguments}:
3967 @multitable @columnfractions .15 .70
3968 @item @var{X} @tab The type shall be @code{REAL}.
3969 @end multitable
3970
3971 @item @emph{Return value}:
3972 The return value is of type @code{REAL}, of the same kind as
3973 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3974
3975 @item @emph{Example}:
3976 @smallexample
3977 program test_erf
3978   real(8) :: x = 0.17_8
3979   x = erf(x)
3980 end program test_erf
3981 @end smallexample
3982
3983 @item @emph{Specific names}:
3984 @multitable @columnfractions .20 .20 .20 .25
3985 @item Name            @tab Argument          @tab Return type       @tab Standard
3986 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
3987 @end multitable
3988 @end table
3989
3990
3991
3992 @node ERFC
3993 @section @code{ERFC} --- Error function
3994 @fnindex ERFC
3995 @cindex error function, complementary
3996
3997 @table @asis
3998 @item @emph{Description}:
3999 @code{ERFC(X)} computes the complementary error function of @var{X}.
4000
4001 @item @emph{Standard}:
4002 Fortran 2008 and later
4003
4004 @item @emph{Class}:
4005 Elemental function
4006
4007 @item @emph{Syntax}:
4008 @code{RESULT = ERFC(X)}
4009
4010 @item @emph{Arguments}:
4011 @multitable @columnfractions .15 .70
4012 @item @var{X} @tab The type shall be @code{REAL}.
4013 @end multitable
4014
4015 @item @emph{Return value}:
4016 The return value is of type @code{REAL} and of the same kind as @var{X}.
4017 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4018
4019 @item @emph{Example}:
4020 @smallexample
4021 program test_erfc
4022   real(8) :: x = 0.17_8
4023   x = erfc(x)
4024 end program test_erfc
4025 @end smallexample
4026
4027 @item @emph{Specific names}:
4028 @multitable @columnfractions .20 .20 .20 .25
4029 @item Name            @tab Argument          @tab Return type       @tab Standard
4030 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
4031 @end multitable
4032 @end table
4033
4034
4035
4036 @node ERFC_SCALED
4037 @section @code{ERFC_SCALED} --- Error function
4038 @fnindex ERFC_SCALED
4039 @cindex error function, complementary, exponentially-scaled
4040
4041 @table @asis
4042 @item @emph{Description}:
4043 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4044 error function of @var{X}.
4045
4046 @item @emph{Standard}:
4047 Fortran 2008 and later
4048
4049 @item @emph{Class}:
4050 Elemental function
4051
4052 @item @emph{Syntax}:
4053 @code{RESULT = ERFC_SCALED(X)}
4054
4055 @item @emph{Arguments}:
4056 @multitable @columnfractions .15 .70
4057 @item @var{X} @tab The type shall be @code{REAL}.
4058 @end multitable
4059
4060 @item @emph{Return value}:
4061 The return value is of type @code{REAL} and of the same kind as @var{X}.
4062
4063 @item @emph{Example}:
4064 @smallexample
4065 program test_erfc_scaled
4066   real(8) :: x = 0.17_8
4067   x = erfc_scaled(x)
4068 end program test_erfc_scaled
4069 @end smallexample
4070 @end table
4071
4072
4073
4074 @node ETIME
4075 @section @code{ETIME} --- Execution time subroutine (or function)
4076 @fnindex ETIME
4077 @cindex time, elapsed
4078
4079 @table @asis
4080 @item @emph{Description}:
4081 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4082 since the start of the process's execution in @var{TIME}.  @var{VALUES}
4083 returns the user and system components of this time in @code{VALUES(1)} and
4084 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4085
4086 On some systems, the underlying timings are represented using types with
4087 sufficiently small limits that overflows (wrap around) are possible, such as
4088 32-bit types. Therefore, the values returned by this intrinsic might be, or
4089 become, negative, or numerically less than previous values, during a single
4090 run of the compiled program.
4091
4092 This intrinsic is provided in both subroutine and function forms; however,
4093 only one form can be used in any given program unit.
4094
4095 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4096
4097 @multitable @columnfractions .15 .30 .60
4098 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4099 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4100 @item @tab @code{TIME}: @tab Run time since start in seconds.
4101 @end multitable
4102
4103 @item @emph{Standard}:
4104 GNU extension
4105
4106 @item @emph{Class}:
4107 Subroutine, function
4108
4109 @item @emph{Syntax}:
4110 @multitable @columnfractions .80
4111 @item @code{CALL ETIME(VALUES, TIME)}.
4112 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4113 @end multitable
4114
4115 @item @emph{Arguments}:
4116 @multitable @columnfractions .15 .70
4117 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4118 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4119 @end multitable
4120
4121 @item @emph{Return value}:
4122 Elapsed time in seconds since the start of program execution.
4123
4124 @item @emph{Example}:
4125 @smallexample
4126 program test_etime
4127     integer(8) :: i, j
4128     real, dimension(2) :: tarray
4129     real :: result
4130     call ETIME(tarray, result)
4131     print *, result
4132     print *, tarray(1)
4133     print *, tarray(2)
4134     do i=1,100000000    ! Just a delay
4135         j = i * i - i
4136     end do
4137     call ETIME(tarray, result)
4138     print *, result
4139     print *, tarray(1)
4140     print *, tarray(2)
4141 end program test_etime
4142 @end smallexample
4143
4144 @item @emph{See also}:
4145 @ref{CPU_TIME}
4146
4147 @end table
4148
4149
4150
4151 @node EXECUTE_COMMAND_LINE
4152 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4153 @fnindex EXECUTE_COMMAND_LINE
4154 @cindex system, system call
4155 @cindex command line
4156
4157 @table @asis
4158 @item @emph{Description}:
4159 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4160 asynchronously.
4161
4162 The @code{COMMAND} argument is passed to the shell and executed, using
4163 the C library's @code{system} call.  (The shell is @code{sh} on Unix
4164 systems, and @code{cmd.exe} on Windows.)  If @code{WAIT} is present
4165 and has the value false, the execution of the command is asynchronous
4166 if the system supports it; otherwise, the command is executed
4167 synchronously.
4168
4169 The three last arguments allow the user to get status information.  After
4170 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4171 the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
4172 if the command line was executed (whatever its exit status was).
4173 @code{CMDMSG} is assigned an error message if an error has occurred.
4174
4175 Note that the @code{system} function need not be thread-safe. It is
4176 the responsibility of the user to ensure that @code{system} is not
4177 called concurrently.
4178
4179 @item @emph{Standard}:
4180 Fortran 2008 and later
4181
4182 @item @emph{Class}:
4183 Subroutine
4184
4185 @item @emph{Syntax}:
4186 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4187
4188 @item @emph{Arguments}:
4189 @multitable @columnfractions .15 .70
4190 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4191 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4192 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4193 default kind.
4194 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4195 default kind.
4196 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4197 default kind.
4198 @end multitable
4199
4200 @item @emph{Example}:
4201 @smallexample
4202 program test_exec
4203   integer :: i
4204
4205   call execute_command_line ("external_prog.exe", exitstat=i)
4206   print *, "Exit status of external_prog.exe was ", i
4207
4208   call execute_command_line ("reindex_files.exe", wait=.false.)
4209   print *, "Now reindexing files in the background"
4210
4211 end program test_exec
4212 @end smallexample
4213
4214
4215 @item @emph{Note}:
4216
4217 Because this intrinsic is implemented in terms of the @code{system}
4218 function call, its behavior with respect to signaling is processor
4219 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4220 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4221 such, if the parent process is terminated, the child process might not be
4222 terminated alongside.
4223
4224
4225 @item @emph{See also}:
4226 @ref{SYSTEM}
4227 @end table
4228
4229
4230
4231 @node EXIT
4232 @section @code{EXIT} --- Exit the program with status.
4233 @fnindex EXIT
4234 @cindex program termination
4235 @cindex terminate program
4236
4237 @table @asis
4238 @item @emph{Description}:
4239 @code{EXIT} causes immediate termination of the program with status.  If status
4240 is omitted it returns the canonical @emph{success} for the system.  All Fortran
4241 I/O units are closed.
4242
4243 @item @emph{Standard}:
4244 GNU extension
4245
4246 @item @emph{Class}:
4247 Subroutine
4248
4249 @item @emph{Syntax}:
4250 @code{CALL EXIT([STATUS])}
4251
4252 @item @emph{Arguments}:
4253 @multitable @columnfractions .15 .70
4254 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4255 @end multitable
4256
4257 @item @emph{Return value}:
4258 @code{STATUS} is passed to the parent process on exit.
4259
4260 @item @emph{Example}:
4261 @smallexample
4262 program test_exit
4263   integer :: STATUS = 0
4264   print *, 'This program is going to exit.'
4265   call EXIT(STATUS)
4266 end program test_exit
4267 @end smallexample
4268
4269 @item @emph{See also}:
4270 @ref{ABORT}, @ref{KILL}
4271 @end table
4272
4273
4274
4275 @node EXP
4276 @section @code{EXP} --- Exponential function
4277 @fnindex EXP
4278 @fnindex DEXP
4279 @fnindex CEXP
4280 @fnindex ZEXP
4281 @fnindex CDEXP
4282 @cindex exponential function
4283 @cindex logarithmic function, inverse
4284
4285 @table @asis
4286 @item @emph{Description}:
4287 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4288
4289 @item @emph{Standard}:
4290 Fortran 77 and later, has overloads that are GNU extensions
4291
4292 @item @emph{Class}:
4293 Elemental function
4294
4295 @item @emph{Syntax}:
4296 @code{RESULT = EXP(X)}
4297
4298 @item @emph{Arguments}:
4299 @multitable @columnfractions .15 .70
4300 @item @var{X} @tab The type shall be @code{REAL} or
4301 @code{COMPLEX}.
4302 @end multitable
4303
4304 @item @emph{Return value}:
4305 The return value has same type and kind as @var{X}.
4306
4307 @item @emph{Example}:
4308 @smallexample
4309 program test_exp
4310   real :: x = 1.0
4311   x = exp(x)
4312 end program test_exp
4313 @end smallexample
4314
4315 @item @emph{Specific names}:
4316 @multitable @columnfractions .20 .20 .20 .25
4317 @item Name            @tab Argument             @tab Return type         @tab Standard
4318 @item @code{EXP(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}      @tab Fortran 77 and later
4319 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
4320 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
4321 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4322 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4323 @end multitable
4324 @end table
4325
4326
4327
4328 @node EXPONENT
4329 @section @code{EXPONENT} --- Exponent function
4330 @fnindex EXPONENT
4331 @cindex real number, exponent
4332 @cindex floating point, exponent
4333
4334 @table @asis
4335 @item @emph{Description}:
4336 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4337 is zero the value returned is zero.
4338
4339 @item @emph{Standard}:
4340 Fortran 95 and later
4341
4342 @item @emph{Class}:
4343 Elemental function
4344
4345 @item @emph{Syntax}:
4346 @code{RESULT = EXPONENT(X)}
4347
4348 @item @emph{Arguments}:
4349 @multitable @columnfractions .15 .70
4350 @item @var{X} @tab The type shall be @code{REAL}.
4351 @end multitable
4352
4353 @item @emph{Return value}:
4354 The return value is of type default @code{INTEGER}.
4355
4356 @item @emph{Example}:
4357 @smallexample
4358 program test_exponent
4359   real :: x = 1.0
4360   integer :: i
4361   i = exponent(x)
4362   print *, i
4363   print *, exponent(0.0)
4364 end program test_exponent
4365 @end smallexample
4366 @end table
4367
4368
4369
4370 @node EXTENDS_TYPE_OF
4371 @section @code{EXTENDS_TYPE_OF} ---  Query dynamic type for extension
4372 @fnindex EXTENDS_TYPE_OF
4373
4374 @table @asis
4375 @item @emph{Description}:
4376 Query dynamic type for extension.
4377
4378 @item @emph{Standard}:
4379 Fortran 2003 and later
4380
4381 @item @emph{Class}:
4382 Inquiry function
4383
4384 @item @emph{Syntax}:
4385 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4386
4387 @item @emph{Arguments}:
4388 @multitable @columnfractions .15 .70
4389 @item @var{A} @tab Shall be an object of extensible declared type or
4390 unlimited polymorphic.
4391 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4392 unlimited polymorphic.
4393 @end multitable
4394
4395 @item @emph{Return value}:
4396 The return value is a scalar of type default logical. It is true if and only if
4397 the dynamic type of A is an extension type of the dynamic type of MOLD.
4398
4399
4400 @item @emph{See also}:
4401 @ref{SAME_TYPE_AS}
4402 @end table
4403
4404
4405
4406 @node FDATE
4407 @section @code{FDATE} --- Get the current time as a string
4408 @fnindex FDATE
4409 @cindex time, current
4410 @cindex current time
4411 @cindex date, current
4412 @cindex current date
4413
4414 @table @asis
4415 @item @emph{Description}:
4416 @code{FDATE(DATE)} returns the current date (using the same format as
4417 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4418 TIME())}.
4419
4420 This intrinsic is provided in both subroutine and function forms; however,
4421 only one form can be used in any given program unit.
4422
4423 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
4424 default kind.
4425
4426 @item @emph{Standard}:
4427 GNU extension
4428
4429 @item @emph{Class}:
4430 Subroutine, function
4431
4432 @item @emph{Syntax}:
4433 @multitable @columnfractions .80
4434 @item @code{CALL FDATE(DATE)}.
4435 @item @code{DATE = FDATE()}, (not recommended).
4436 @end multitable
4437
4438 @item @emph{Arguments}:
4439 @multitable @columnfractions .15 .70
4440 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4441 default kind
4442 @end multitable
4443
4444 @item @emph{Return value}:
4445 The current date as a string.
4446
4447 @item @emph{Example}:
4448 @smallexample
4449 program test_fdate
4450     integer(8) :: i, j
4451     character(len=30) :: date
4452     call fdate(date)
4453     print *, 'Program started on ', date
4454     do i = 1, 100000000 ! Just a delay
4455         j = i * i - i
4456     end do
4457     call fdate(date)
4458     print *, 'Program ended on ', date
4459 end program test_fdate
4460 @end smallexample
4461 @end table
4462
4463
4464
4465 @node FGET
4466 @section @code{FGET} --- Read a single character in stream mode from stdin
4467 @fnindex FGET
4468 @cindex read character, stream mode
4469 @cindex stream mode, read character
4470 @cindex file operation, read character
4471
4472 @table @asis
4473 @item @emph{Description}:
4474 Read a single character in stream mode from stdin by bypassing normal
4475 formatted output. Stream I/O should not be mixed with normal record-oriented
4476 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4477
4478 This intrinsic is provided in both subroutine and function forms; however,
4479 only one form can be used in any given program unit.
4480
4481 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4482 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4483 Programmers should consider the use of new stream IO feature in new code
4484 for future portability. See also @ref{Fortran 2003 status}.
4485
4486 @item @emph{Standard}:
4487 GNU extension
4488
4489 @item @emph{Class}:
4490 Subroutine, function
4491
4492 @item @emph{Syntax}:
4493 @multitable @columnfractions .80
4494 @item @code{CALL FGET(C [, STATUS])}
4495 @item @code{STATUS = FGET(C)}
4496 @end multitable
4497
4498 @item @emph{Arguments}:
4499 @multitable @columnfractions .15 .70
4500 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4501 kind.
4502 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4503 Returns 0 on success, -1 on end-of-file, and a system specific positive
4504 error code otherwise.
4505 @end multitable
4506
4507 @item @emph{Example}:
4508 @smallexample
4509 PROGRAM test_fget
4510   INTEGER, PARAMETER :: strlen = 100
4511   INTEGER :: status, i = 1
4512   CHARACTER(len=strlen) :: str = ""
4513
4514   WRITE (*,*) 'Enter text:'
4515   DO
4516     CALL fget(str(i:i), status)
4517     if (status /= 0 .OR. i > strlen) exit
4518     i = i + 1
4519   END DO
4520   WRITE (*,*) TRIM(str)
4521 END PROGRAM
4522 @end smallexample
4523
4524 @item @emph{See also}:
4525 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4526 @end table
4527
4528
4529
4530 @node FGETC
4531 @section @code{FGETC} --- Read a single character in stream mode
4532 @fnindex FGETC
4533 @cindex read character, stream mode
4534 @cindex stream mode, read character
4535 @cindex file operation, read character
4536
4537 @table @asis
4538 @item @emph{Description}:
4539 Read a single character in stream mode by bypassing normal formatted output.
4540 Stream I/O should not be mixed with normal record-oriented (formatted or
4541 unformatted) I/O on the same unit; the results are unpredictable.
4542
4543 This intrinsic is provided in both subroutine and function forms; however,
4544 only one form can be used in any given program unit.
4545
4546 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4547 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4548 Programmers should consider the use of new stream IO feature in new code
4549 for future portability. See also @ref{Fortran 2003 status}.
4550
4551 @item @emph{Standard}:
4552 GNU extension
4553
4554 @item @emph{Class}:
4555 Subroutine, function
4556
4557 @item @emph{Syntax}:
4558 @multitable @columnfractions .80
4559 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4560 @item @code{STATUS = FGETC(UNIT, C)}
4561 @end multitable
4562
4563 @item @emph{Arguments}:
4564 @multitable @columnfractions .15 .70
4565 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4566 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4567 kind.
4568 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4569 Returns 0 on success, -1 on end-of-file and a system specific positive
4570 error code otherwise.
4571 @end multitable
4572
4573 @item @emph{Example}:
4574 @smallexample
4575 PROGRAM test_fgetc
4576   INTEGER :: fd = 42, status
4577   CHARACTER :: c
4578
4579   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4580   DO
4581     CALL fgetc(fd, c, status)
4582     IF (status /= 0) EXIT
4583     call fput(c)
4584   END DO
4585   CLOSE(UNIT=fd)
4586 END PROGRAM
4587 @end smallexample
4588
4589 @item @emph{See also}:
4590 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4591 @end table
4592
4593
4594
4595 @node FLOOR
4596 @section @code{FLOOR} --- Integer floor function
4597 @fnindex FLOOR
4598 @cindex floor
4599 @cindex rounding, floor
4600
4601 @table @asis
4602 @item @emph{Description}:
4603 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4604
4605 @item @emph{Standard}:
4606 Fortran 95 and later
4607
4608 @item @emph{Class}:
4609 Elemental function
4610
4611 @item @emph{Syntax}:
4612 @code{RESULT = FLOOR(A [, KIND])}
4613
4614 @item @emph{Arguments}:
4615 @multitable @columnfractions .15 .70
4616 @item @var{A} @tab The type shall be @code{REAL}.
4617 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4618 expression indicating the kind parameter of the result.
4619 @end multitable
4620
4621 @item @emph{Return value}:
4622 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4623 and of default-kind @code{INTEGER} otherwise.
4624
4625 @item @emph{Example}:
4626 @smallexample
4627 program test_floor
4628     real :: x = 63.29
4629     real :: y = -63.59
4630     print *, floor(x) ! returns 63
4631     print *, floor(y) ! returns -64
4632 end program test_floor
4633 @end smallexample
4634
4635 @item @emph{See also}:
4636 @ref{CEILING}, @ref{NINT}
4637
4638 @end table
4639
4640
4641
4642 @node FLUSH
4643 @section @code{FLUSH} --- Flush I/O unit(s)
4644 @fnindex FLUSH
4645 @cindex file operation, flush
4646
4647 @table @asis
4648 @item @emph{Description}:
4649 Flushes Fortran unit(s) currently open for output. Without the optional
4650 argument, all units are flushed, otherwise just the unit specified.
4651
4652 @item @emph{Standard}:
4653 GNU extension
4654
4655 @item @emph{Class}:
4656 Subroutine
4657
4658 @item @emph{Syntax}:
4659 @code{CALL FLUSH(UNIT)}
4660
4661 @item @emph{Arguments}:
4662 @multitable @columnfractions .15 .70
4663 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4664 @end multitable
4665
4666 @item @emph{Note}:
4667 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4668 statement that should be preferred over the @code{FLUSH} intrinsic.
4669
4670 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4671 have identical effect: they flush the runtime library's I/O buffer so
4672 that the data becomes visible to other processes. This does not guarantee
4673 that the data is committed to disk.
4674
4675 On POSIX systems, you can request that all data is transferred  to  the
4676 storage device by calling the @code{fsync} function, with the POSIX file
4677 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4678 @code{FNUM}). The following example shows how:
4679
4680 @smallexample
4681   ! Declare the interface for POSIX fsync function
4682   interface
4683     function fsync (fd) bind(c,name="fsync")
4684     use iso_c_binding, only: c_int
4685       integer(c_int), value :: fd
4686       integer(c_int) :: fsync
4687     end function fsync
4688   end interface
4689
4690   ! Variable declaration
4691   integer :: ret
4692
4693   ! Opening unit 10
4694   open (10,file="foo")
4695
4696   ! ...
4697   ! Perform I/O on unit 10
4698   ! ...
4699
4700   ! Flush and sync
4701   flush(10)
4702   ret = fsync(fnum(10))
4703
4704   ! Handle possible error
4705   if (ret /= 0) stop "Error calling FSYNC"
4706 @end smallexample
4707
4708 @end table
4709
4710
4711
4712 @node FNUM
4713 @section @code{FNUM} --- File number function
4714 @fnindex FNUM
4715 @cindex file operation, file number
4716
4717 @table @asis
4718 @item @emph{Description}:
4719 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4720 open Fortran I/O unit @code{UNIT}.
4721
4722 @item @emph{Standard}:
4723 GNU extension
4724
4725 @item @emph{Class}:
4726 Function
4727
4728 @item @emph{Syntax}:
4729 @code{RESULT = FNUM(UNIT)}
4730
4731 @item @emph{Arguments}:
4732 @multitable @columnfractions .15 .70
4733 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4734 @end multitable
4735
4736 @item @emph{Return value}:
4737 The return value is of type @code{INTEGER}
4738
4739 @item @emph{Example}:
4740 @smallexample
4741 program test_fnum
4742   integer :: i
4743   open (unit=10, status = "scratch")
4744   i = fnum(10)
4745   print *, i
4746   close (10)
4747 end program test_fnum
4748 @end smallexample
4749 @end table
4750
4751
4752
4753 @node FPUT
4754 @section @code{FPUT} --- Write a single character in stream mode to stdout
4755 @fnindex FPUT
4756 @cindex write character, stream mode
4757 @cindex stream mode, write character
4758 @cindex file operation, write character
4759
4760 @table @asis
4761 @item @emph{Description}:
4762 Write a single character in stream mode to stdout by bypassing normal
4763 formatted output. Stream I/O should not be mixed with normal record-oriented
4764 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4765
4766 This intrinsic is provided in both subroutine and function forms; however,
4767 only one form can be used in any given program unit.
4768
4769 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4770 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4771 Programmers should consider the use of new stream IO feature in new code
4772 for future portability. See also @ref{Fortran 2003 status}.
4773
4774 @item @emph{Standard}:
4775 GNU extension
4776
4777 @item @emph{Class}:
4778 Subroutine, function
4779
4780 @item @emph{Syntax}:
4781 @multitable @columnfractions .80
4782 @item @code{CALL FPUT(C [, STATUS])}
4783 @item @code{STATUS = FPUT(C)}
4784 @end multitable
4785
4786 @item @emph{Arguments}:
4787 @multitable @columnfractions .15 .70
4788 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4789 kind.
4790 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4791 Returns 0 on success, -1 on end-of-file and a system specific positive
4792 error code otherwise.
4793 @end multitable
4794
4795 @item @emph{Example}:
4796 @smallexample
4797 PROGRAM test_fput
4798   CHARACTER(len=10) :: str = "gfortran"
4799   INTEGER :: i
4800   DO i = 1, len_trim(str)
4801     CALL fput(str(i:i))
4802   END DO
4803 END PROGRAM
4804 @end smallexample
4805
4806 @item @emph{See also}:
4807 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4808 @end table
4809
4810
4811
4812 @node FPUTC
4813 @section @code{FPUTC} --- Write a single character in stream mode
4814 @fnindex FPUTC
4815 @cindex write character, stream mode
4816 @cindex stream mode, write character
4817 @cindex file operation, write character
4818
4819 @table @asis
4820 @item @emph{Description}:
4821 Write a single character in stream mode by bypassing normal formatted
4822 output. Stream I/O should not be mixed with normal record-oriented
4823 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4824
4825 This intrinsic is provided in both subroutine and function forms; however,
4826 only one form can be used in any given program unit.
4827
4828 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4829 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4830 Programmers should consider the use of new stream IO feature in new code
4831 for future portability. See also @ref{Fortran 2003 status}.
4832
4833 @item @emph{Standard}:
4834 GNU extension
4835
4836 @item @emph{Class}:
4837 Subroutine, function
4838
4839 @item @emph{Syntax}:
4840 @multitable @columnfractions .80
4841 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4842 @item @code{STATUS = FPUTC(UNIT, C)}
4843 @end multitable
4844
4845 @item @emph{Arguments}:
4846 @multitable @columnfractions .15 .70
4847 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4848 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4849 kind.
4850 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4851 Returns 0 on success, -1 on end-of-file and a system specific positive
4852 error code otherwise.
4853 @end multitable
4854
4855 @item @emph{Example}:
4856 @smallexample
4857 PROGRAM test_fputc
4858   CHARACTER(len=10) :: str = "gfortran"
4859   INTEGER :: fd = 42, i
4860
4861   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4862   DO i = 1, len_trim(str)
4863     CALL fputc(fd, str(i:i))
4864   END DO
4865   CLOSE(fd)
4866 END PROGRAM
4867 @end smallexample
4868
4869 @item @emph{See also}:
4870 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4871 @end table
4872
4873
4874
4875 @node FRACTION
4876 @section @code{FRACTION} --- Fractional part of the model representation
4877 @fnindex FRACTION
4878 @cindex real number, fraction
4879 @cindex floating point, fraction
4880
4881 @table @asis
4882 @item @emph{Description}:
4883 @code{FRACTION(X)} returns the fractional part of the model
4884 representation of @code{X}.
4885
4886 @item @emph{Standard}:
4887 Fortran 95 and later
4888
4889 @item @emph{Class}:
4890 Elemental function
4891
4892 @item @emph{Syntax}:
4893 @code{Y = FRACTION(X)}
4894
4895 @item @emph{Arguments}:
4896 @multitable @columnfractions .15 .70
4897 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4898 @end multitable
4899
4900 @item @emph{Return value}:
4901 The return value is of the same type and kind as the argument.
4902 The fractional part of the model representation of @code{X} is returned;
4903 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4904
4905 @item @emph{Example}:
4906 @smallexample
4907 program test_fraction
4908   real :: x
4909   x = 178.1387e-4
4910   print *, fraction(x), x * radix(x)**(-exponent(x))
4911 end program test_fraction
4912 @end smallexample
4913
4914 @end table
4915
4916
4917
4918 @node FREE
4919 @section @code{FREE} --- Frees memory
4920 @fnindex FREE
4921 @cindex pointer, cray
4922
4923 @table @asis
4924 @item @emph{Description}:
4925 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
4926 intrinsic is an extension intended to be used with Cray pointers, and is
4927 provided in GNU Fortran to allow user to compile legacy code. For
4928 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4929 @code{DEALLOCATE}.
4930
4931 @item @emph{Standard}:
4932 GNU extension
4933
4934 @item @emph{Class}:
4935 Subroutine
4936
4937 @item @emph{Syntax}:
4938 @code{CALL FREE(PTR)}
4939
4940 @item @emph{Arguments}:
4941 @multitable @columnfractions .15 .70
4942 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4943 location of the memory that should be de-allocated.
4944 @end multitable
4945
4946 @item @emph{Return value}:
4947 None
4948
4949 @item @emph{Example}:
4950 See @code{MALLOC} for an example.
4951
4952 @item @emph{See also}:
4953 @ref{MALLOC}
4954 @end table
4955
4956
4957
4958 @node FSEEK
4959 @section @code{FSEEK} --- Low level file positioning subroutine
4960 @fnindex FSEEK
4961 @cindex file operation, seek
4962 @cindex file operation, position
4963
4964 @table @asis
4965 @item @emph{Description}:
4966 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4967 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4968 if set to 1, @var{OFFSET} is taken to be relative to the current position
4969 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4970 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4971 fails silently.
4972
4973 This intrinsic routine is not fully backwards compatible with @command{g77}.
4974 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4975 @var{STATUS} variable. If FSEEK is used in old code, change
4976 @smallexample
4977   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4978 @end smallexample
4979 to
4980 @smallexample
4981   INTEGER :: status
4982   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4983   IF (status /= 0) GOTO label
4984 @end smallexample
4985
4986 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4987 Programmers should consider the use of new stream IO feature in new code
4988 for future portability. See also @ref{Fortran 2003 status}.
4989
4990 @item @emph{Standard}:
4991 GNU extension
4992
4993 @item @emph{Class}:
4994 Subroutine
4995
4996 @item @emph{Syntax}:
4997 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4998
4999 @item @emph{Arguments}:
5000 @multitable @columnfractions .15 .70
5001 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
5002 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5003 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5004 Its value shall be either 0, 1 or 2.
5005 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5006 @code{INTEGER(4)}.
5007 @end multitable
5008
5009 @item @emph{Example}:
5010 @smallexample
5011 PROGRAM test_fseek
5012   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5013   INTEGER :: fd, offset, ierr
5014
5015   ierr   = 0
5016   offset = 5
5017   fd     = 10
5018
5019   OPEN(UNIT=fd, FILE="fseek.test")
5020   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
5021   print *, FTELL(fd), ierr
5022
5023   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
5024   print *, FTELL(fd), ierr
5025
5026   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
5027   print *, FTELL(fd), ierr
5028
5029   CLOSE(UNIT=fd)
5030 END PROGRAM
5031 @end smallexample
5032
5033 @item @emph{See also}:
5034 @ref{FTELL}
5035 @end table
5036
5037
5038
5039 @node FSTAT
5040 @section @code{FSTAT} --- Get file status
5041 @fnindex FSTAT
5042 @cindex file system, file status
5043
5044 @table @asis
5045 @item @emph{Description}:
5046 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5047 already opened file is obtained.
5048
5049 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5050
5051 This intrinsic is provided in both subroutine and function forms; however,
5052 only one form can be used in any given program unit.
5053
5054 @item @emph{Standard}:
5055 GNU extension
5056
5057 @item @emph{Class}:
5058 Subroutine, function
5059
5060 @item @emph{Syntax}:
5061 @multitable @columnfractions .80
5062 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5063 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5064 @end multitable
5065
5066 @item @emph{Arguments}:
5067 @multitable @columnfractions .15 .70
5068 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
5069 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5070 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5071 on success and a system specific error code otherwise.
5072 @end multitable
5073
5074 @item @emph{Example}:
5075 See @ref{STAT} for an example.
5076
5077 @item @emph{See also}:
5078 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5079 @end table
5080
5081
5082
5083 @node FTELL
5084 @section @code{FTELL} --- Current stream position
5085 @fnindex FTELL
5086 @cindex file operation, position
5087
5088 @table @asis
5089 @item @emph{Description}:
5090 Retrieves the current position within an open file.
5091
5092 This intrinsic is provided in both subroutine and function forms; however,
5093 only one form can be used in any given program unit.
5094
5095 @item @emph{Standard}:
5096 GNU extension
5097
5098 @item @emph{Class}:
5099 Subroutine, function
5100
5101 @item @emph{Syntax}:
5102 @multitable @columnfractions .80
5103 @item @code{CALL FTELL(UNIT, OFFSET)}
5104 @item @code{OFFSET = FTELL(UNIT)}
5105 @end multitable
5106
5107 @item @emph{Arguments}:
5108 @multitable @columnfractions .15 .70
5109 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
5110 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
5111 @end multitable
5112
5113 @item @emph{Return value}:
5114 In either syntax, @var{OFFSET} is set to the current offset of unit
5115 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5116
5117 @item @emph{Example}:
5118 @smallexample
5119 PROGRAM test_ftell
5120   INTEGER :: i
5121   OPEN(10, FILE="temp.dat")
5122   CALL ftell(10,i)
5123   WRITE(*,*) i
5124 END PROGRAM
5125 @end smallexample
5126
5127 @item @emph{See also}:
5128 @ref{FSEEK}
5129 @end table
5130
5131
5132
5133 @node GAMMA
5134 @section @code{GAMMA} --- Gamma function
5135 @fnindex GAMMA
5136 @fnindex DGAMMA
5137 @cindex Gamma function
5138 @cindex Factorial function
5139
5140 @table @asis
5141 @item @emph{Description}:
5142 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5143 integer values of @var{X} the Gamma function simplifies to the factorial
5144 function @math{\Gamma(x)=(x-1)!}.
5145
5146 @tex
5147 $$
5148 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5149 $$
5150 @end tex
5151
5152 @item @emph{Standard}:
5153 Fortran 2008 and later
5154
5155 @item @emph{Class}:
5156 Elemental function
5157
5158 @item @emph{Syntax}:
5159 @code{X = GAMMA(X)}
5160
5161 @item @emph{Arguments}:
5162 @multitable @columnfractions .15 .70
5163 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5164 nor a negative integer.
5165 @end multitable
5166
5167 @item @emph{Return value}:
5168 The return value is of type @code{REAL} of the same kind as @var{X}.
5169
5170 @item @emph{Example}:
5171 @smallexample
5172 program test_gamma
5173   real :: x = 1.0
5174   x = gamma(x) ! returns 1.0
5175 end program test_gamma
5176 @end smallexample
5177
5178 @item @emph{Specific names}:
5179 @multitable @columnfractions .20 .20 .20 .25
5180 @item Name             @tab Argument         @tab Return type       @tab Standard
5181 @item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
5182 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
5183 @end multitable
5184
5185 @item @emph{See also}:
5186 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5187
5188 @end table
5189
5190
5191
5192 @node GERROR
5193 @section @code{GERROR} --- Get last system error message
5194 @fnindex GERROR
5195 @cindex system, error handling
5196
5197 @table @asis
5198 @item @emph{Description}:
5199 Returns the system error message corresponding to the last system error.
5200 This resembles the functionality of @code{strerror(3)} in C.
5201
5202 @item @emph{Standard}:
5203 GNU extension
5204
5205 @item @emph{Class}:
5206 Subroutine
5207
5208 @item @emph{Syntax}:
5209 @code{CALL GERROR(RESULT)}
5210
5211 @item @emph{Arguments}:
5212 @multitable @columnfractions .15 .70
5213 @item @var{RESULT}  @tab Shall of type @code{CHARACTER} and of default
5214 @end multitable
5215
5216 @item @emph{Example}:
5217 @smallexample
5218 PROGRAM test_gerror
5219   CHARACTER(len=100) :: msg
5220   CALL gerror(msg)
5221   WRITE(*,*) msg
5222 END PROGRAM
5223 @end smallexample
5224
5225 @item @emph{See also}:
5226 @ref{IERRNO}, @ref{PERROR}
5227 @end table
5228
5229
5230
5231 @node GETARG
5232 @section @code{GETARG} --- Get command line arguments
5233 @fnindex GETARG
5234 @cindex command-line arguments
5235 @cindex arguments, to program
5236
5237 @table @asis
5238 @item @emph{Description}:
5239 Retrieve the @var{POS}-th argument that was passed on the
5240 command line when the containing program was invoked.
5241
5242 This intrinsic routine is provided for backwards compatibility with
5243 GNU Fortran 77.  In new code, programmers should consider the use of
5244 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5245 standard.
5246
5247 @item @emph{Standard}:
5248 GNU extension
5249
5250 @item @emph{Class}:
5251 Subroutine
5252
5253 @item @emph{Syntax}:
5254 @code{CALL GETARG(POS, VALUE)}
5255
5256 @item @emph{Arguments}:
5257 @multitable @columnfractions .15 .70
5258 @item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
5259 the default integer kind; @math{@var{POS} \geq 0}
5260 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5261 kind.
5262 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5263 @end multitable
5264
5265 @item @emph{Return value}:
5266 After @code{GETARG} returns, the @var{VALUE} argument holds the
5267 @var{POS}th command line argument. If @var{VALUE} can not hold the
5268 argument, it is truncated to fit the length of @var{VALUE}. If there are
5269 less than @var{POS} arguments specified at the command line, @var{VALUE}
5270 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5271 to the name of the program (on systems that support this feature).
5272
5273 @item @emph{Example}:
5274 @smallexample
5275 PROGRAM test_getarg
5276   INTEGER :: i
5277   CHARACTER(len=32) :: arg
5278
5279   DO i = 1, iargc()
5280     CALL getarg(i, arg)
5281     WRITE (*,*) arg
5282   END DO
5283 END PROGRAM
5284 @end smallexample
5285
5286 @item @emph{See also}:
5287 GNU Fortran 77 compatibility function: @ref{IARGC}
5288
5289 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5290 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5291 @end table
5292
5293
5294
5295 @node GET_COMMAND
5296 @section @code{GET_COMMAND} --- Get the entire command line
5297 @fnindex GET_COMMAND
5298 @cindex command-line arguments
5299 @cindex arguments, to program
5300
5301 @table @asis
5302 @item @emph{Description}:
5303 Retrieve the entire command line that was used to invoke the program.
5304
5305 @item @emph{Standard}:
5306 Fortran 2003 and later
5307
5308 @item @emph{Class}:
5309 Subroutine
5310
5311 @item @emph{Syntax}:
5312 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5313
5314 @item @emph{Arguments}:
5315 @multitable @columnfractions .15 .70
5316 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5317 of default kind.
5318 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5319 default kind.
5320 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5321 default kind.
5322 @end multitable
5323
5324 @item @emph{Return value}:
5325 If @var{COMMAND} is present, stores the entire command line that was used
5326 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5327 assigned the length of the command line. If @var{STATUS} is present, it
5328 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5329 short to store the command line, or a positive value in case of an error.
5330
5331 @item @emph{Example}:
5332 @smallexample
5333 PROGRAM test_get_command
5334   CHARACTER(len=255) :: cmd
5335   CALL get_command(cmd)
5336   WRITE (*,*) TRIM(cmd)
5337 END PROGRAM
5338 @end smallexample
5339
5340 @item @emph{See also}:
5341 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5342 @end table
5343
5344
5345
5346 @node GET_COMMAND_ARGUMENT
5347 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5348 @fnindex GET_COMMAND_ARGUMENT
5349 @cindex command-line arguments
5350 @cindex arguments, to program
5351
5352 @table @asis
5353 @item @emph{Description}:
5354 Retrieve the @var{NUMBER}-th argument that was passed on the
5355 command line when the containing program was invoked.
5356
5357 @item @emph{Standard}:
5358 Fortran 2003 and later
5359
5360 @item @emph{Class}:
5361 Subroutine
5362
5363 @item @emph{Syntax}:
5364 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5365
5366 @item @emph{Arguments}:
5367 @multitable @columnfractions .15 .70
5368 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5369 default kind, @math{@var{NUMBER} \geq 0}
5370 @item @var{VALUE}  @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5371 and of default kind.
5372 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5373 and of default kind.
5374 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5375 and of default kind.
5376 @end multitable
5377
5378 @item @emph{Return value}:
5379 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5380 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5381 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5382 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5383 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5384 systems that support this feature). The @var{LENGTH} argument contains the
5385 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5386 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5387 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5388 zero.
5389
5390 @item @emph{Example}:
5391 @smallexample
5392 PROGRAM test_get_command_argument
5393   INTEGER :: i
5394   CHARACTER(len=32) :: arg
5395
5396   i = 0
5397   DO
5398     CALL get_command_argument(i, arg)
5399     IF (LEN_TRIM(arg) == 0) EXIT
5400
5401     WRITE (*,*) TRIM(arg)
5402     i = i+1
5403   END DO
5404 END PROGRAM
5405 @end smallexample
5406
5407 @item @emph{See also}:
5408 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5409 @end table
5410
5411
5412
5413 @node GETCWD
5414 @section @code{GETCWD} --- Get current working directory
5415 @fnindex GETCWD
5416 @cindex system, working directory
5417
5418 @table @asis
5419 @item @emph{Description}:
5420 Get current working directory.
5421
5422 This intrinsic is provided in both subroutine and function forms; however,
5423 only one form can be used in any given program unit.
5424
5425 @item @emph{Standard}:
5426 GNU extension
5427
5428 @item @emph{Class}:
5429 Subroutine, function
5430
5431 @item @emph{Syntax}:
5432 @multitable @columnfractions .80
5433 @item @code{CALL GETCWD(C [, STATUS])}
5434 @item @code{STATUS = GETCWD(C)}
5435 @end multitable
5436
5437 @item @emph{Arguments}:
5438 @multitable @columnfractions .15 .70
5439 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5440 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5441 a system specific and nonzero error code otherwise.
5442 @end multitable
5443
5444 @item @emph{Example}:
5445 @smallexample
5446 PROGRAM test_getcwd
5447   CHARACTER(len=255) :: cwd
5448   CALL getcwd(cwd)
5449   WRITE(*,*) TRIM(cwd)
5450 END PROGRAM
5451 @end smallexample
5452
5453 @item @emph{See also}:
5454 @ref{CHDIR}
5455 @end table
5456
5457
5458
5459 @node GETENV
5460 @section @code{GETENV} --- Get an environmental variable
5461 @fnindex GETENV
5462 @cindex environment variable
5463
5464 @table @asis
5465 @item @emph{Description}:
5466 Get the @var{VALUE} of the environmental variable @var{NAME}.
5467
5468 This intrinsic routine is provided for backwards compatibility with
5469 GNU Fortran 77.  In new code, programmers should consider the use of
5470 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5471 2003 standard.
5472
5473 Note that @code{GETENV} need not be thread-safe. It is the
5474 responsibility of the user to ensure that the environment is not being
5475 updated concurrently with a call to the @code{GETENV} intrinsic.
5476
5477 @item @emph{Standard}:
5478 GNU extension
5479
5480 @item @emph{Class}:
5481 Subroutine
5482
5483 @item @emph{Syntax}:
5484 @code{CALL GETENV(NAME, VALUE)}
5485
5486 @item @emph{Arguments}:
5487 @multitable @columnfractions .15 .70
5488 @item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
5489 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5490 @end multitable
5491
5492 @item @emph{Return value}:
5493 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5494 not large enough to hold the data, it is truncated. If @var{NAME}
5495 is not set, @var{VALUE} will be filled with blanks.
5496
5497 @item @emph{Example}:
5498 @smallexample
5499 PROGRAM test_getenv
5500   CHARACTER(len=255) :: homedir
5501   CALL getenv("HOME", homedir)
5502   WRITE (*,*) TRIM(homedir)
5503 END PROGRAM
5504 @end smallexample
5505
5506 @item @emph{See also}:
5507 @ref{GET_ENVIRONMENT_VARIABLE}
5508 @end table
5509
5510
5511
5512 @node GET_ENVIRONMENT_VARIABLE
5513 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5514 @fnindex GET_ENVIRONMENT_VARIABLE
5515 @cindex environment variable
5516
5517 @table @asis
5518 @item @emph{Description}:
5519 Get the @var{VALUE} of the environmental variable @var{NAME}.
5520
5521 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5522 is the responsibility of the user to ensure that the environment is
5523 not being updated concurrently with a call to the
5524 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5525
5526 @item @emph{Standard}:
5527 Fortran 2003 and later
5528
5529 @item @emph{Class}:
5530 Subroutine
5531
5532 @item @emph{Syntax}:
5533 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5534
5535 @item @emph{Arguments}:
5536 @multitable @columnfractions .15 .70
5537 @item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER}
5538 and of default kind.
5539 @item @var{VALUE}     @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5540 and of default kind.
5541 @item @var{LENGTH}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5542 and of default kind.
5543 @item @var{STATUS}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5544 and of default kind.
5545 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5546 and of default kind.
5547 @end multitable
5548
5549 @item @emph{Return value}:
5550 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5551 not large enough to hold the data, it is truncated. If @var{NAME}
5552 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5553 contains the length needed for storing the environment variable @var{NAME}
5554 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5555 but too short for the environment variable; it is 1 if the environment
5556 variable does not exist and 2 if the processor does not support environment
5557 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5558 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5559 are significant; otherwise they are not part of the environment variable
5560 name.
5561
5562 @item @emph{Example}:
5563 @smallexample
5564 PROGRAM test_getenv
5565   CHARACTER(len=255) :: homedir
5566   CALL get_environment_variable("HOME", homedir)
5567   WRITE (*,*) TRIM(homedir)
5568 END PROGRAM
5569 @end smallexample
5570 @end table
5571
5572
5573
5574 @node GETGID
5575 @section @code{GETGID} --- Group ID function
5576 @fnindex GETGID
5577 @cindex system, group ID
5578
5579 @table @asis
5580 @item @emph{Description}:
5581 Returns the numerical group ID of the current process.
5582
5583 @item @emph{Standard}:
5584 GNU extension
5585
5586 @item @emph{Class}:
5587 Function
5588
5589 @item @emph{Syntax}:
5590 @code{RESULT = GETGID()}
5591
5592 @item @emph{Return value}:
5593 The return value of @code{GETGID} is an @code{INTEGER} of the default
5594 kind.
5595
5596
5597 @item @emph{Example}:
5598 See @code{GETPID} for an example.
5599
5600 @item @emph{See also}:
5601 @ref{GETPID}, @ref{GETUID}
5602 @end table
5603
5604
5605
5606 @node GETLOG
5607 @section @code{GETLOG} --- Get login name
5608 @fnindex GETLOG
5609 @cindex system, login name
5610 @cindex login name
5611
5612 @table @asis
5613 @item @emph{Description}:
5614 Gets the username under which the program is running.
5615
5616 @item @emph{Standard}:
5617 GNU extension
5618
5619 @item @emph{Class}:
5620 Subroutine
5621
5622 @item @emph{Syntax}:
5623 @code{CALL GETLOG(C)}
5624
5625 @item @emph{Arguments}:
5626 @multitable @columnfractions .15 .70
5627 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5628 @end multitable
5629
5630 @item @emph{Return value}:
5631 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5632 functions @code{geteuid} and @code{getpwuid} are not available, and
5633 the @code{getlogin} function is not implemented either, this will
5634 return a blank string.)
5635
5636 @item @emph{Example}:
5637 @smallexample
5638 PROGRAM TEST_GETLOG
5639   CHARACTER(32) :: login
5640   CALL GETLOG(login)
5641   WRITE(*,*) login
5642 END PROGRAM
5643 @end smallexample
5644
5645 @item @emph{See also}:
5646 @ref{GETUID}
5647 @end table
5648
5649
5650
5651 @node GETPID
5652 @section @code{GETPID} --- Process ID function
5653 @fnindex GETPID
5654 @cindex system, process ID
5655 @cindex process ID
5656
5657 @table @asis
5658 @item @emph{Description}:
5659 Returns the numerical process identifier of the current process.
5660
5661 @item @emph{Standard}:
5662 GNU extension
5663
5664 @item @emph{Class}:
5665 Function
5666
5667 @item @emph{Syntax}:
5668 @code{RESULT = GETPID()}
5669
5670 @item @emph{Return value}:
5671 The return value of @code{GETPID} is an @code{INTEGER} of the default
5672 kind.
5673
5674
5675 @item @emph{Example}:
5676 @smallexample
5677 program info
5678   print *, "The current process ID is ", getpid()
5679   print *, "Your numerical user ID is ", getuid()
5680   print *, "Your numerical group ID is ", getgid()
5681 end program info
5682 @end smallexample
5683
5684 @item @emph{See also}:
5685 @ref{GETGID}, @ref{GETUID}
5686 @end table
5687
5688
5689
5690 @node GETUID
5691 @section @code{GETUID} --- User ID function
5692 @fnindex GETUID
5693 @cindex system, user ID
5694 @cindex user id
5695
5696 @table @asis
5697 @item @emph{Description}:
5698 Returns the numerical user ID of the current process.
5699
5700 @item @emph{Standard}:
5701 GNU extension
5702
5703 @item @emph{Class}:
5704 Function
5705
5706 @item @emph{Syntax}:
5707 @code{RESULT = GETUID()}
5708
5709 @item @emph{Return value}:
5710 The return value of @code{GETUID} is an @code{INTEGER} of the default
5711 kind.
5712
5713
5714 @item @emph{Example}:
5715 See @code{GETPID} for an example.
5716
5717 @item @emph{See also}:
5718 @ref{GETPID}, @ref{GETLOG}
5719 @end table
5720
5721
5722
5723 @node GMTIME
5724 @section @code{GMTIME} --- Convert time to GMT info
5725 @fnindex GMTIME
5726 @cindex time, conversion to GMT info
5727
5728 @table @asis
5729 @item @emph{Description}:
5730 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5731 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5732 to the UTC time zone (Universal Coordinated Time, also known in some
5733 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5734
5735 @item @emph{Standard}:
5736 GNU extension
5737
5738 @item @emph{Class}:
5739 Subroutine
5740
5741 @item @emph{Syntax}:
5742 @code{CALL GMTIME(TIME, VALUES)}
5743
5744 @item @emph{Arguments}:
5745 @multitable @columnfractions .15 .70
5746 @item @var{TIME}   @tab An @code{INTEGER} scalar expression
5747 corresponding to a system time, with @code{INTENT(IN)}.
5748 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5749 with @code{INTENT(OUT)}.
5750 @end multitable
5751
5752 @item @emph{Return value}:
5753 The elements of @var{VALUES} are assigned as follows:
5754 @enumerate
5755 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5756 seconds
5757 @item Minutes after the hour, range 0--59
5758 @item Hours past midnight, range 0--23
5759 @item Day of month, range 0--31
5760 @item Number of months since January, range 0--12
5761 @item Years since 1900
5762 @item Number of days since Sunday, range 0--6
5763 @item Days since January 1
5764 @item Daylight savings indicator: positive if daylight savings is in
5765 effect, zero if not, and negative if the information is not available.
5766 @end enumerate
5767
5768 @item @emph{See also}:
5769 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5770
5771 @end table
5772
5773
5774
5775 @node HOSTNM
5776 @section @code{HOSTNM} --- Get system host name
5777 @fnindex HOSTNM
5778 @cindex system, host name
5779
5780 @table @asis
5781 @item @emph{Description}:
5782 Retrieves the host name of the system on which the program is running.
5783
5784 This intrinsic is provided in both subroutine and function forms; however,
5785 only one form can be used in any given program unit.
5786
5787 @item @emph{Standard}:
5788 GNU extension
5789
5790 @item @emph{Class}:
5791 Subroutine, function
5792
5793 @item @emph{Syntax}:
5794 @multitable @columnfractions .80
5795 @item @code{CALL HOSTNM(C [, STATUS])}
5796 @item @code{STATUS = HOSTNM(NAME)}
5797 @end multitable
5798
5799 @item @emph{Arguments}:
5800 @multitable @columnfractions .15 .70
5801 @item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
5802 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5803 Returns 0 on success, or a system specific error code otherwise.
5804 @end multitable
5805
5806 @item @emph{Return value}:
5807 In either syntax, @var{NAME} is set to the current hostname if it can
5808 be obtained, or to a blank string otherwise.
5809
5810 @end table
5811
5812
5813
5814 @node HUGE
5815 @section @code{HUGE} --- Largest number of a kind
5816 @fnindex HUGE
5817 @cindex limits, largest number
5818 @cindex model representation, largest number
5819
5820 @table @asis
5821 @item @emph{Description}:
5822 @code{HUGE(X)} returns the largest number that is not an infinity in
5823 the model of the type of @code{X}.
5824
5825 @item @emph{Standard}:
5826 Fortran 95 and later
5827
5828 @item @emph{Class}:
5829 Inquiry function
5830
5831 @item @emph{Syntax}:
5832 @code{RESULT = HUGE(X)}
5833
5834 @item @emph{Arguments}:
5835 @multitable @columnfractions .15 .70
5836 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5837 @end multitable
5838
5839 @item @emph{Return value}:
5840 The return value is of the same type and kind as @var{X}
5841
5842 @item @emph{Example}:
5843 @smallexample
5844 program test_huge_tiny
5845   print *, huge(0), huge(0.0), huge(0.0d0)
5846   print *, tiny(0.0), tiny(0.0d0)
5847 end program test_huge_tiny
5848 @end smallexample
5849 @end table
5850
5851
5852
5853 @node HYPOT
5854 @section @code{HYPOT} --- Euclidean distance function
5855 @fnindex HYPOT
5856 @cindex Euclidean distance
5857
5858 @table @asis
5859 @item @emph{Description}:
5860 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5861 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5862
5863 @item @emph{Standard}:
5864 Fortran 2008 and later
5865
5866 @item @emph{Class}:
5867 Elemental function
5868
5869 @item @emph{Syntax}:
5870 @code{RESULT = HYPOT(X, Y)}
5871
5872 @item @emph{Arguments}:
5873 @multitable @columnfractions .15 .70
5874 @item @var{X} @tab The type shall be @code{REAL}.
5875 @item @var{Y} @tab The type and kind type parameter shall be the same as
5876 @var{X}.
5877 @end multitable
5878
5879 @item @emph{Return value}:
5880 The return value has the same type and kind type parameter as @var{X}.
5881
5882 @item @emph{Example}:
5883 @smallexample
5884 program test_hypot
5885   real(4) :: x = 1.e0_4, y = 0.5e0_4
5886   x = hypot(x,y)
5887 end program test_hypot
5888 @end smallexample
5889 @end table
5890
5891
5892
5893 @node IACHAR
5894 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5895 @fnindex IACHAR
5896 @cindex @acronym{ASCII} collating sequence
5897 @cindex collating sequence, @acronym{ASCII}
5898 @cindex conversion, to integer
5899
5900 @table @asis
5901 @item @emph{Description}:
5902 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5903 in the first character position of @code{C}.
5904
5905 @item @emph{Standard}:
5906 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5907
5908 @item @emph{Class}:
5909 Elemental function
5910
5911 @item @emph{Syntax}:
5912 @code{RESULT = IACHAR(C [, KIND])}
5913
5914 @item @emph{Arguments}:
5915 @multitable @columnfractions .15 .70
5916 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5917 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5918 expression indicating the kind parameter of the result.
5919 @end multitable
5920
5921 @item @emph{Return value}:
5922 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5923 @var{KIND} is absent, the return value is of default integer kind.
5924
5925 @item @emph{Example}:
5926 @smallexample
5927 program test_iachar
5928   integer i
5929   i = iachar(' ')
5930 end program test_iachar
5931 @end smallexample
5932
5933 @item @emph{Note}:
5934 See @ref{ICHAR} for a discussion of converting between numerical values
5935 and formatted string representations.
5936
5937 @item @emph{See also}:
5938 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5939
5940 @end table
5941
5942
5943
5944 @node IALL
5945 @section @code{IALL} --- Bitwise AND of array elements
5946 @fnindex IALL
5947 @cindex array, AND
5948 @cindex bits, AND of array elements
5949
5950 @table @asis
5951 @item @emph{Description}:
5952 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
5953 if the corresponding element in @var{MASK} is @code{TRUE}.
5954
5955 @item @emph{Standard}:
5956 Fortran 2008 and later
5957
5958 @item @emph{Class}:
5959 Transformational function
5960
5961 @item @emph{Syntax}:
5962 @multitable @columnfractions .80
5963 @item @code{RESULT = IALL(ARRAY[, MASK])}
5964 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
5965 @end multitable
5966
5967 @item @emph{Arguments}:
5968 @multitable @columnfractions .15 .70
5969 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
5970 @item @var{DIM}   @tab (Optional) shall be a scalar of type
5971 @code{INTEGER} with a value in the range from 1 to n, where n
5972 equals the rank of @var{ARRAY}.
5973 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
5974 and either be a scalar or an array of the same shape as @var{ARRAY}.
5975 @end multitable
5976
5977 @item @emph{Return value}:
5978 The result is of the same type as @var{ARRAY}.
5979
5980 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
5981 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
5982 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
5983 dimension @var{DIM} dropped is returned.
5984
5985 @item @emph{Example}:
5986 @smallexample
5987 PROGRAM test_iall
5988   INTEGER(1) :: a(2)
5989
5990   a(1) = b'00100100'
5991   a(2) = b'01101010'
5992
5993   ! prints 00100000
5994   PRINT '(b8.8)', IALL(a)
5995 END PROGRAM
5996 @end smallexample
5997
5998 @item @emph{See also}:
5999 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6000 @end table
6001
6002
6003
6004 @node IAND
6005 @section @code{IAND} --- Bitwise logical and
6006 @fnindex IAND
6007 @cindex bitwise logical and
6008 @cindex logical and, bitwise
6009
6010 @table @asis
6011 @item @emph{Description}:
6012 Bitwise logical @code{AND}.
6013
6014 @item @emph{Standard}:
6015 Fortran 95 and later
6016
6017 @item @emph{Class}:
6018 Elemental function
6019
6020 @item @emph{Syntax}:
6021 @code{RESULT = IAND(I, J)}
6022
6023 @item @emph{Arguments}:
6024 @multitable @columnfractions .15 .70
6025 @item @var{I} @tab The type shall be @code{INTEGER}.
6026 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6027 kind as @var{I}.  (As a GNU extension, different kinds are also
6028 permitted.)
6029 @end multitable
6030
6031 @item @emph{Return value}:
6032 The return type is @code{INTEGER}, of the same kind as the
6033 arguments.  (If the argument kinds differ, it is of the same kind as
6034 the larger argument.)
6035
6036 @item @emph{Example}:
6037 @smallexample
6038 PROGRAM test_iand
6039   INTEGER :: a, b
6040   DATA a / Z'F' /, b / Z'3' /
6041   WRITE (*,*) IAND(a, b)
6042 END PROGRAM
6043 @end smallexample
6044
6045 @item @emph{See also}:
6046 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6047
6048 @end table
6049
6050
6051
6052 @node IANY
6053 @section @code{IANY} --- Bitwise OR of array elements
6054 @fnindex IANY
6055 @cindex array, OR
6056 @cindex bits, OR of array elements
6057
6058 @table @asis
6059 @item @emph{Description}:
6060 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6061 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6062
6063 @item @emph{Standard}:
6064 Fortran 2008 and later
6065
6066 @item @emph{Class}:
6067 Transformational function
6068
6069 @item @emph{Syntax}:
6070 @multitable @columnfractions .80
6071 @item @code{RESULT = IANY(ARRAY[, MASK])}
6072 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6073 @end multitable
6074
6075 @item @emph{Arguments}:
6076 @multitable @columnfractions .15 .70
6077 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6078 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6079 @code{INTEGER} with a value in the range from 1 to n, where n
6080 equals the rank of @var{ARRAY}.
6081 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6082 and either be a scalar or an array of the same shape as @var{ARRAY}.
6083 @end multitable
6084
6085 @item @emph{Return value}:
6086 The result is of the same type as @var{ARRAY}.
6087
6088 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6089 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6090 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6091 dimension @var{DIM} dropped is returned.
6092
6093 @item @emph{Example}:
6094 @smallexample
6095 PROGRAM test_iany
6096   INTEGER(1) :: a(2)
6097
6098   a(1) = b'00100100'
6099   a(2) = b'01101010'
6100
6101   ! prints 01101110
6102   PRINT '(b8.8)', IANY(a)
6103 END PROGRAM
6104 @end smallexample
6105
6106 @item @emph{See also}:
6107 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6108 @end table
6109
6110
6111
6112 @node IARGC
6113 @section @code{IARGC} --- Get the number of command line arguments
6114 @fnindex IARGC
6115 @cindex command-line arguments
6116 @cindex command-line arguments, number of
6117 @cindex arguments, to program
6118
6119 @table @asis
6120 @item @emph{Description}:
6121 @code{IARGC} returns the number of arguments passed on the
6122 command line when the containing program was invoked.
6123
6124 This intrinsic routine is provided for backwards compatibility with
6125 GNU Fortran 77.  In new code, programmers should consider the use of
6126 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6127 standard.
6128
6129 @item @emph{Standard}:
6130 GNU extension
6131
6132 @item @emph{Class}:
6133 Function
6134
6135 @item @emph{Syntax}:
6136 @code{RESULT = IARGC()}
6137
6138 @item @emph{Arguments}:
6139 None.
6140
6141 @item @emph{Return value}:
6142 The number of command line arguments, type @code{INTEGER(4)}.
6143
6144 @item @emph{Example}:
6145 See @ref{GETARG}
6146
6147 @item @emph{See also}:
6148 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6149
6150 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6151 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6152 @end table
6153
6154
6155
6156 @node IBCLR
6157 @section @code{IBCLR} --- Clear bit
6158 @fnindex IBCLR
6159 @cindex bits, unset
6160 @cindex bits, clear
6161
6162 @table @asis
6163 @item @emph{Description}:
6164 @code{IBCLR} returns the value of @var{I} with the bit at position
6165 @var{POS} set to zero.
6166
6167 @item @emph{Standard}:
6168 Fortran 95 and later
6169
6170 @item @emph{Class}:
6171 Elemental function
6172
6173 @item @emph{Syntax}:
6174 @code{RESULT = IBCLR(I, POS)}
6175
6176 @item @emph{Arguments}:
6177 @multitable @columnfractions .15 .70
6178 @item @var{I} @tab The type shall be @code{INTEGER}.
6179 @item @var{POS} @tab The type shall be @code{INTEGER}.
6180 @end multitable
6181
6182 @item @emph{Return value}:
6183 The return value is of type @code{INTEGER} and of the same kind as
6184 @var{I}.
6185
6186 @item @emph{See also}:
6187 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6188
6189 @end table
6190
6191
6192
6193 @node IBITS
6194 @section @code{IBITS} --- Bit extraction
6195 @fnindex IBITS
6196 @cindex bits, get
6197 @cindex bits, extract
6198
6199 @table @asis
6200 @item @emph{Description}:
6201 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6202 starting from bit position @var{POS} and extending left for @var{LEN}
6203 bits.  The result is right-justified and the remaining bits are
6204 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
6205 value @code{BIT_SIZE(I)}.
6206
6207 @item @emph{Standard}:
6208 Fortran 95 and later
6209
6210 @item @emph{Class}:
6211 Elemental function
6212
6213 @item @emph{Syntax}:
6214 @code{RESULT = IBITS(I, POS, LEN)}
6215
6216 @item @emph{Arguments}:
6217 @multitable @columnfractions .15 .70
6218 @item @var{I}   @tab The type shall be @code{INTEGER}.
6219 @item @var{POS} @tab The type shall be @code{INTEGER}.
6220 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6221 @end multitable
6222
6223 @item @emph{Return value}:
6224 The return value is of type @code{INTEGER} and of the same kind as
6225 @var{I}.
6226
6227 @item @emph{See also}:
6228 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6229 @end table
6230
6231
6232
6233 @node IBSET
6234 @section @code{IBSET} --- Set bit
6235 @fnindex IBSET
6236 @cindex bits, set
6237
6238 @table @asis
6239 @item @emph{Description}:
6240 @code{IBSET} returns the value of @var{I} with the bit at position
6241 @var{POS} set to one.
6242
6243 @item @emph{Standard}:
6244 Fortran 95 and later
6245
6246 @item @emph{Class}:
6247 Elemental function
6248
6249 @item @emph{Syntax}:
6250 @code{RESULT = IBSET(I, POS)}
6251
6252 @item @emph{Arguments}:
6253 @multitable @columnfractions .15 .70
6254 @item @var{I} @tab The type shall be @code{INTEGER}.
6255 @item @var{POS} @tab The type shall be @code{INTEGER}.
6256 @end multitable
6257
6258 @item @emph{Return value}:
6259 The return value is of type @code{INTEGER} and of the same kind as
6260 @var{I}.
6261
6262 @item @emph{See also}:
6263 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6264
6265 @end table
6266
6267
6268
6269 @node ICHAR
6270 @section @code{ICHAR} --- Character-to-integer conversion function
6271 @fnindex ICHAR
6272 @cindex conversion, to integer
6273
6274 @table @asis
6275 @item @emph{Description}:
6276 @code{ICHAR(C)} returns the code for the character in the first character
6277 position of @code{C} in the system's native character set.
6278 The correspondence between characters and their codes is not necessarily
6279 the same across different GNU Fortran implementations.
6280
6281 @item @emph{Standard}:
6282 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6283
6284 @item @emph{Class}:
6285 Elemental function
6286
6287 @item @emph{Syntax}:
6288 @code{RESULT = ICHAR(C [, KIND])}
6289
6290 @item @emph{Arguments}:
6291 @multitable @columnfractions .15 .70
6292 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6293 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6294 expression indicating the kind parameter of the result.
6295 @end multitable
6296
6297 @item @emph{Return value}:
6298 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6299 @var{KIND} is absent, the return value is of default integer kind.
6300
6301 @item @emph{Example}:
6302 @smallexample
6303 program test_ichar
6304   integer i
6305   i = ichar(' ')
6306 end program test_ichar
6307 @end smallexample
6308
6309 @item @emph{Specific names}:
6310 @multitable @columnfractions .20 .20 .20 .25
6311 @item Name             @tab Argument             @tab Return type       @tab Standard
6312 @item @code{ICHAR(C)}  @tab @code{CHARACTER C}   @tab @code{INTEGER(4)}    @tab Fortran 77 and later
6313 @end multitable
6314
6315 @item @emph{Note}:
6316 No intrinsic exists to convert between a numeric value and a formatted
6317 character string representation -- for instance, given the
6318 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6319 @code{REAL} value with the value 154, or vice versa. Instead, this
6320 functionality is provided by internal-file I/O, as in the following
6321 example:
6322 @smallexample
6323 program read_val
6324   integer value
6325   character(len=10) string, string2
6326   string = '154'
6327
6328   ! Convert a string to a numeric value
6329   read (string,'(I10)') value
6330   print *, value
6331
6332   ! Convert a value to a formatted string
6333   write (string2,'(I10)') value
6334   print *, string2
6335 end program read_val
6336 @end smallexample
6337
6338 @item @emph{See also}:
6339 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6340
6341 @end table
6342
6343
6344
6345 @node IDATE
6346 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6347 @fnindex IDATE
6348 @cindex date, current
6349 @cindex current date
6350
6351 @table @asis
6352 @item @emph{Description}:
6353 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6354 current local time. The day (in the range 1-31), month (in the range 1-12),
6355 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6356 The year has four significant digits.
6357
6358 @item @emph{Standard}:
6359 GNU extension
6360
6361 @item @emph{Class}:
6362 Subroutine
6363
6364 @item @emph{Syntax}:
6365 @code{CALL IDATE(VALUES)}
6366
6367 @item @emph{Arguments}:
6368 @multitable @columnfractions .15 .70
6369 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6370 the kind shall be the default integer kind.
6371 @end multitable
6372
6373 @item @emph{Return value}:
6374 Does not return anything.
6375
6376 @item @emph{Example}:
6377 @smallexample
6378 program test_idate
6379   integer, dimension(3) :: tarray
6380   call idate(tarray)
6381   print *, tarray(1)
6382   print *, tarray(2)
6383   print *, tarray(3)
6384 end program test_idate
6385 @end smallexample
6386 @end table
6387
6388
6389
6390 @node IEOR
6391 @section @code{IEOR} --- Bitwise logical exclusive or
6392 @fnindex IEOR
6393 @cindex bitwise logical exclusive or
6394 @cindex logical exclusive or, bitwise
6395
6396 @table @asis
6397 @item @emph{Description}:
6398 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6399 @var{J}.
6400
6401 @item @emph{Standard}:
6402 Fortran 95 and later
6403
6404 @item @emph{Class}:
6405 Elemental function
6406
6407 @item @emph{Syntax}:
6408 @code{RESULT = IEOR(I, J)}
6409
6410 @item @emph{Arguments}:
6411 @multitable @columnfractions .15 .70
6412 @item @var{I} @tab The type shall be @code{INTEGER}.
6413 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6414 kind as @var{I}.  (As a GNU extension, different kinds are also
6415 permitted.)
6416 @end multitable
6417
6418 @item @emph{Return value}:
6419 The return type is @code{INTEGER}, of the same kind as the
6420 arguments.  (If the argument kinds differ, it is of the same kind as
6421 the larger argument.)
6422
6423 @item @emph{See also}:
6424 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6425 @end table
6426
6427
6428
6429 @node IERRNO
6430 @section @code{IERRNO} --- Get the last system error number
6431 @fnindex IERRNO
6432 @cindex system, error handling
6433
6434 @table @asis
6435 @item @emph{Description}:
6436 Returns the last system error number, as given by the C @code{errno}
6437 variable.
6438
6439 @item @emph{Standard}:
6440 GNU extension
6441
6442 @item @emph{Class}:
6443 Function
6444
6445 @item @emph{Syntax}:
6446 @code{RESULT = IERRNO()}
6447
6448 @item @emph{Arguments}:
6449 None.
6450
6451 @item @emph{Return value}:
6452 The return value is of type @code{INTEGER} and of the default integer
6453 kind.
6454
6455 @item @emph{See also}:
6456 @ref{PERROR}
6457 @end table
6458
6459
6460
6461 @node IMAGE_INDEX
6462 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6463 @fnindex IMAGE_INDEX
6464 @cindex coarray, @code{IMAGE_INDEX}
6465 @cindex images, cosubscript to image index conversion
6466
6467 @table @asis
6468 @item @emph{Description}:
6469 Returns the image index belonging to a cosubscript.
6470
6471 @item @emph{Standard}:
6472 Fortran 2008 and later
6473
6474 @item @emph{Class}:
6475 Inquiry function.
6476
6477 @item @emph{Syntax}:
6478 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6479
6480 @item @emph{Arguments}: None.
6481 @multitable @columnfractions .15 .70
6482 @item @var{COARRAY} @tab Coarray of any type.
6483 @item @var{SUB}     @tab default integer rank-1 array of a size equal to
6484 the corank of @var{COARRAY}.
6485 @end multitable
6486
6487
6488 @item @emph{Return value}:
6489 Scalar default integer with the value of the image index which corresponds
6490 to the cosubscripts. For invalid cosubscripts the result is zero.
6491
6492 @item @emph{Example}:
6493 @smallexample
6494 INTEGER :: array[2,-1:4,8,*]
6495 ! Writes  28 (or 0 if there are fewer than 28 images)
6496 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6497 @end smallexample
6498
6499 @item @emph{See also}:
6500 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6501 @end table
6502
6503
6504
6505 @node INDEX intrinsic
6506 @section @code{INDEX} --- Position of a substring within a string
6507 @fnindex INDEX
6508 @cindex substring position
6509 @cindex string, find substring
6510
6511 @table @asis
6512 @item @emph{Description}:
6513 Returns the position of the start of the first occurrence of string
6514 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
6515 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
6516 the @var{BACK} argument is present and true, the return value is the
6517 start of the last occurrence rather than the first.
6518
6519 @item @emph{Standard}:
6520 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6521
6522 @item @emph{Class}:
6523 Elemental function
6524
6525 @item @emph{Syntax}:
6526 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6527
6528 @item @emph{Arguments}:
6529 @multitable @columnfractions .15 .70
6530 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6531 @code{INTENT(IN)}
6532 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6533 @code{INTENT(IN)}
6534 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6535 @code{INTENT(IN)}
6536 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6537 expression indicating the kind parameter of the result.
6538 @end multitable
6539
6540 @item @emph{Return value}:
6541 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6542 @var{KIND} is absent, the return value is of default integer kind.
6543
6544 @item @emph{Specific names}:
6545 @multitable @columnfractions .20 .20 .20 .25
6546 @item Name                            @tab Argument           @tab Return type       @tab Standard
6547 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER}   @tab @code{INTEGER(4)} @tab Fortran 77 and later
6548 @end multitable
6549
6550 @item @emph{See also}:
6551 @ref{SCAN}, @ref{VERIFY}
6552 @end table
6553
6554
6555
6556 @node INT
6557 @section @code{INT} --- Convert to integer type
6558 @fnindex INT
6559 @fnindex IFIX
6560 @fnindex IDINT
6561 @cindex conversion, to integer
6562
6563 @table @asis
6564 @item @emph{Description}:
6565 Convert to integer type
6566
6567 @item @emph{Standard}:
6568 Fortran 77 and later
6569
6570 @item @emph{Class}:
6571 Elemental function
6572
6573 @item @emph{Syntax}:
6574 @code{RESULT = INT(A [, KIND))}
6575
6576 @item @emph{Arguments}:
6577 @multitable @columnfractions .15 .70
6578 @item @var{A}    @tab Shall be of type @code{INTEGER},
6579 @code{REAL}, or @code{COMPLEX}.
6580 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6581 expression indicating the kind parameter of the result.
6582 @end multitable
6583
6584 @item @emph{Return value}:
6585 These functions return a @code{INTEGER} variable or array under
6586 the following rules:
6587
6588 @table @asis
6589 @item (A)
6590 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6591 @item (B)
6592 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6593 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6594 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6595 @item (C)
6596 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6597 @end table
6598
6599 @item @emph{Example}:
6600 @smallexample
6601 program test_int
6602   integer :: i = 42
6603   complex :: z = (-3.7, 1.0)
6604   print *, int(i)
6605   print *, int(z), int(z,8)
6606 end program
6607 @end smallexample
6608
6609 @item @emph{Specific names}:
6610 @multitable @columnfractions .20 .20 .20 .25
6611 @item Name            @tab Argument          @tab Return type       @tab Standard
6612 @item @code{INT(A)}   @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6613 @item @code{IFIX(A)}  @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6614 @item @code{IDINT(A)} @tab @code{REAL(8) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6615 @end multitable
6616
6617 @end table
6618
6619
6620 @node INT2
6621 @section @code{INT2} --- Convert to 16-bit integer type
6622 @fnindex INT2
6623 @fnindex SHORT
6624 @cindex conversion, to integer
6625
6626 @table @asis
6627 @item @emph{Description}:
6628 Convert to a @code{KIND=2} integer type. This is equivalent to the
6629 standard @code{INT} intrinsic with an optional argument of
6630 @code{KIND=2}, and is only included for backwards compatibility.
6631
6632 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6633
6634 @item @emph{Standard}:
6635 GNU extension
6636
6637 @item @emph{Class}:
6638 Elemental function
6639
6640 @item @emph{Syntax}:
6641 @code{RESULT = INT2(A)}
6642
6643 @item @emph{Arguments}:
6644 @multitable @columnfractions .15 .70
6645 @item @var{A}    @tab Shall be of type @code{INTEGER},
6646 @code{REAL}, or @code{COMPLEX}.
6647 @end multitable
6648
6649 @item @emph{Return value}:
6650 The return value is a @code{INTEGER(2)} variable.
6651
6652 @item @emph{See also}:
6653 @ref{INT}, @ref{INT8}, @ref{LONG}
6654 @end table
6655
6656
6657
6658 @node INT8
6659 @section @code{INT8} --- Convert to 64-bit integer type
6660 @fnindex INT8
6661 @cindex conversion, to integer
6662
6663 @table @asis
6664 @item @emph{Description}:
6665 Convert to a @code{KIND=8} integer type. This is equivalent to the
6666 standard @code{INT} intrinsic with an optional argument of
6667 @code{KIND=8}, and is only included for backwards compatibility.
6668
6669 @item @emph{Standard}:
6670 GNU extension
6671
6672 @item @emph{Class}:
6673 Elemental function
6674
6675 @item @emph{Syntax}:
6676 @code{RESULT = INT8(A)}
6677
6678 @item @emph{Arguments}:
6679 @multitable @columnfractions .15 .70
6680 @item @var{A}    @tab Shall be of type @code{INTEGER},
6681 @code{REAL}, or @code{COMPLEX}.
6682 @end multitable
6683
6684 @item @emph{Return value}:
6685 The return value is a @code{INTEGER(8)} variable.
6686
6687 @item @emph{See also}:
6688 @ref{INT}, @ref{INT2}, @ref{LONG}
6689 @end table
6690
6691
6692
6693 @node IOR
6694 @section @code{IOR} --- Bitwise logical or
6695 @fnindex IOR
6696 @cindex bitwise logical or
6697 @cindex logical or, bitwise
6698
6699 @table @asis
6700 @item @emph{Description}:
6701 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6702 @var{J}.
6703
6704 @item @emph{Standard}:
6705 Fortran 95 and later
6706
6707 @item @emph{Class}:
6708 Elemental function
6709
6710 @item @emph{Syntax}:
6711 @code{RESULT = IOR(I, J)}
6712
6713 @item @emph{Arguments}:
6714 @multitable @columnfractions .15 .70
6715 @item @var{I} @tab The type shall be @code{INTEGER}.
6716 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6717 kind as @var{I}.  (As a GNU extension, different kinds are also
6718 permitted.)
6719 @end multitable
6720
6721 @item @emph{Return value}:
6722 The return type is @code{INTEGER}, of the same kind as the
6723 arguments.  (If the argument kinds differ, it is of the same kind as
6724 the larger argument.)
6725
6726 @item @emph{See also}:
6727 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6728 @end table
6729
6730
6731
6732 @node IPARITY
6733 @section @code{IPARITY} --- Bitwise XOR of array elements
6734 @fnindex IPARITY
6735 @cindex array, parity
6736 @cindex array, XOR
6737 @cindex bits, XOR of array elements
6738
6739 @table @asis
6740 @item @emph{Description}:
6741 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6742 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6743
6744 @item @emph{Standard}:
6745 Fortran 2008 and later
6746
6747 @item @emph{Class}:
6748 Transformational function
6749
6750 @item @emph{Syntax}:
6751 @multitable @columnfractions .80
6752 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6753 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6754 @end multitable
6755
6756 @item @emph{Arguments}:
6757 @multitable @columnfractions .15 .70
6758 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6759 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6760 @code{INTEGER} with a value in the range from 1 to n, where n
6761 equals the rank of @var{ARRAY}.
6762 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6763 and either be a scalar or an array of the same shape as @var{ARRAY}.
6764 @end multitable
6765
6766 @item @emph{Return value}:
6767 The result is of the same type as @var{ARRAY}.
6768
6769 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6770 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6771 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6772 dimension @var{DIM} dropped is returned.
6773
6774 @item @emph{Example}:
6775 @smallexample
6776 PROGRAM test_iparity
6777   INTEGER(1) :: a(2)
6778
6779   a(1) = b'00100100'
6780   a(2) = b'01101010'
6781
6782   ! prints 01001110
6783   PRINT '(b8.8)', IPARITY(a)
6784 END PROGRAM
6785 @end smallexample
6786
6787 @item @emph{See also}:
6788 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6789 @end table
6790
6791
6792
6793 @node IRAND
6794 @section @code{IRAND} --- Integer pseudo-random number
6795 @fnindex IRAND
6796 @cindex random number generation
6797
6798 @table @asis
6799 @item @emph{Description}:
6800 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6801 distribution between 0 and a system-dependent limit (which is in most
6802 cases 2147483647). If @var{FLAG} is 0, the next number
6803 in the current sequence is returned; if @var{FLAG} is 1, the generator
6804 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6805 it is used as a new seed with @code{SRAND}.
6806
6807 This intrinsic routine is provided for backwards compatibility with
6808 GNU Fortran 77. It implements a simple modulo generator as provided
6809 by @command{g77}. For new code, one should consider the use of
6810 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6811
6812 @item @emph{Standard}:
6813 GNU extension
6814
6815 @item @emph{Class}:
6816 Function
6817
6818 @item @emph{Syntax}:
6819 @code{RESULT = IRAND(I)}
6820
6821 @item @emph{Arguments}:
6822 @multitable @columnfractions .15 .70
6823 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6824 @end multitable
6825
6826 @item @emph{Return value}:
6827 The return value is of @code{INTEGER(kind=4)} type.
6828
6829 @item @emph{Example}:
6830 @smallexample
6831 program test_irand
6832   integer,parameter :: seed = 86456
6833
6834   call srand(seed)
6835   print *, irand(), irand(), irand(), irand()
6836   print *, irand(seed), irand(), irand(), irand()
6837 end program test_irand
6838 @end smallexample
6839
6840 @end table
6841
6842
6843
6844 @node IS_IOSTAT_END
6845 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6846 @fnindex IS_IOSTAT_END
6847 @cindex @code{IOSTAT}, end of file
6848
6849 @table @asis
6850 @item @emph{Description}:
6851 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6852 status ``end of file''. The function is equivalent to comparing the variable
6853 with the @code{IOSTAT_END} parameter of the intrinsic module
6854 @code{ISO_FORTRAN_ENV}.
6855
6856 @item @emph{Standard}:
6857 Fortran 2003 and later
6858
6859 @item @emph{Class}:
6860 Elemental function
6861
6862 @item @emph{Syntax}:
6863 @code{RESULT = IS_IOSTAT_END(I)}
6864
6865 @item @emph{Arguments}:
6866 @multitable @columnfractions .15 .70
6867 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6868 @end multitable
6869
6870 @item @emph{Return value}:
6871 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6872 @var{I} has the value which indicates an end of file condition for
6873 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6874
6875 @item @emph{Example}:
6876 @smallexample
6877 PROGRAM iostat
6878   IMPLICIT NONE
6879   INTEGER :: stat, i
6880   OPEN(88, FILE='test.dat')
6881   READ(88, *, IOSTAT=stat) i
6882   IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6883 END PROGRAM
6884 @end smallexample
6885 @end table
6886
6887
6888
6889 @node IS_IOSTAT_EOR
6890 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6891 @fnindex IS_IOSTAT_EOR
6892 @cindex @code{IOSTAT}, end of record
6893
6894 @table @asis
6895 @item @emph{Description}:
6896 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6897 status ``end of record''. The function is equivalent to comparing the
6898 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6899 @code{ISO_FORTRAN_ENV}.
6900
6901 @item @emph{Standard}:
6902 Fortran 2003 and later
6903
6904 @item @emph{Class}:
6905 Elemental function
6906
6907 @item @emph{Syntax}:
6908 @code{RESULT = IS_IOSTAT_EOR(I)}
6909
6910 @item @emph{Arguments}:
6911 @multitable @columnfractions .15 .70
6912 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6913 @end multitable
6914
6915 @item @emph{Return value}:
6916 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6917 @var{I} has the value which indicates an end of file condition for
6918 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6919
6920 @item @emph{Example}:
6921 @smallexample
6922 PROGRAM iostat
6923   IMPLICIT NONE
6924   INTEGER :: stat, i(50)
6925   OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6926   READ(88, IOSTAT=stat) i
6927   IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6928 END PROGRAM
6929 @end smallexample
6930 @end table
6931
6932
6933
6934 @node ISATTY
6935 @section @code{ISATTY} --- Whether a unit is a terminal device.
6936 @fnindex ISATTY
6937 @cindex system, terminal
6938
6939 @table @asis
6940 @item @emph{Description}:
6941 Determine whether a unit is connected to a terminal device.
6942
6943 @item @emph{Standard}:
6944 GNU extension
6945
6946 @item @emph{Class}:
6947 Function
6948
6949 @item @emph{Syntax}:
6950 @code{RESULT = ISATTY(UNIT)}
6951
6952 @item @emph{Arguments}:
6953 @multitable @columnfractions .15 .70
6954 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6955 @end multitable
6956
6957 @item @emph{Return value}:
6958 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6959 device, @code{.FALSE.} otherwise.
6960
6961 @item @emph{Example}:
6962 @smallexample
6963 PROGRAM test_isatty
6964   INTEGER(kind=1) :: unit
6965   DO unit = 1, 10
6966     write(*,*) isatty(unit=unit)
6967   END DO
6968 END PROGRAM
6969 @end smallexample
6970 @item @emph{See also}:
6971 @ref{TTYNAM}
6972 @end table
6973
6974
6975
6976 @node ISHFT
6977 @section @code{ISHFT} --- Shift bits
6978 @fnindex ISHFT
6979 @cindex bits, shift
6980
6981 @table @asis
6982 @item @emph{Description}:
6983 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6984 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
6985 zero corresponds to a left shift, a value of zero corresponds to no
6986 shift, and a value less than zero corresponds to a right shift.  If the
6987 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6988 value is undefined.  Bits shifted out from the left end or right end are
6989 lost; zeros are shifted in from the opposite end.
6990
6991 @item @emph{Standard}:
6992 Fortran 95 and later
6993
6994 @item @emph{Class}:
6995 Elemental function
6996
6997 @item @emph{Syntax}:
6998 @code{RESULT = ISHFT(I, SHIFT)}
6999
7000 @item @emph{Arguments}:
7001 @multitable @columnfractions .15 .70
7002 @item @var{I} @tab The type shall be @code{INTEGER}.
7003 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7004 @end multitable
7005
7006 @item @emph{Return value}:
7007 The return value is of type @code{INTEGER} and of the same kind as
7008 @var{I}.
7009
7010 @item @emph{See also}:
7011 @ref{ISHFTC}
7012 @end table
7013
7014
7015
7016 @node ISHFTC
7017 @section @code{ISHFTC} --- Shift bits circularly
7018 @fnindex ISHFTC
7019 @cindex bits, shift circular
7020
7021 @table @asis
7022 @item @emph{Description}:
7023 @code{ISHFTC} returns a value corresponding to @var{I} with the
7024 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7025 is, bits shifted out one end are shifted into the opposite end.  A value
7026 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7027 zero corresponds to no shift, and a value less than zero corresponds to
7028 a right shift.  The absolute value of @var{SHIFT} must be less than
7029 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
7030 equivalent to @code{BIT_SIZE(I)}.
7031
7032 @item @emph{Standard}:
7033 Fortran 95 and later
7034
7035 @item @emph{Class}:
7036 Elemental function
7037
7038 @item @emph{Syntax}:
7039 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7040
7041 @item @emph{Arguments}:
7042 @multitable @columnfractions .15 .70
7043 @item @var{I} @tab The type shall be @code{INTEGER}.
7044 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7045 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7046 the value must be greater than zero and less than or equal to
7047 @code{BIT_SIZE(I)}.
7048 @end multitable
7049
7050 @item @emph{Return value}:
7051 The return value is of type @code{INTEGER} and of the same kind as
7052 @var{I}.
7053
7054 @item @emph{See also}:
7055 @ref{ISHFT}
7056 @end table
7057
7058
7059
7060 @node ISNAN
7061 @section @code{ISNAN} --- Test for a NaN
7062 @fnindex ISNAN
7063 @cindex IEEE, ISNAN
7064
7065 @table @asis
7066 @item @emph{Description}:
7067 @code{ISNAN} tests whether a floating-point value is an IEEE
7068 Not-a-Number (NaN).
7069 @item @emph{Standard}:
7070 GNU extension
7071
7072 @item @emph{Class}:
7073 Elemental function
7074
7075 @item @emph{Syntax}:
7076 @code{ISNAN(X)}
7077
7078 @item @emph{Arguments}:
7079 @multitable @columnfractions .15 .70
7080 @item @var{X} @tab Variable of the type @code{REAL}.
7081
7082 @end multitable
7083
7084 @item @emph{Return value}:
7085 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7086 if @var{X} is a NaN and @code{FALSE} otherwise.
7087
7088 @item @emph{Example}:
7089 @smallexample
7090 program test_nan
7091   implicit none
7092   real :: x
7093   x = -1.0
7094   x = sqrt(x)
7095   if (isnan(x)) stop '"x" is a NaN'
7096 end program test_nan
7097 @end smallexample
7098 @end table
7099
7100
7101
7102 @node ITIME
7103 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7104 @fnindex ITIME
7105 @cindex time, current
7106 @cindex current time
7107
7108 @table @asis
7109 @item @emph{Description}:
7110 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7111 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7112 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7113 respectively.
7114
7115 @item @emph{Standard}:
7116 GNU extension
7117
7118 @item @emph{Class}:
7119 Subroutine
7120
7121 @item @emph{Syntax}:
7122 @code{CALL ITIME(VALUES)}
7123
7124 @item @emph{Arguments}:
7125 @multitable @columnfractions .15 .70
7126 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7127 and the kind shall be the default integer kind.
7128 @end multitable
7129
7130 @item @emph{Return value}:
7131 Does not return anything.
7132
7133
7134 @item @emph{Example}:
7135 @smallexample
7136 program test_itime
7137   integer, dimension(3) :: tarray
7138   call itime(tarray)
7139   print *, tarray(1)
7140   print *, tarray(2)
7141   print *, tarray(3)
7142 end program test_itime
7143 @end smallexample
7144 @end table
7145
7146
7147
7148 @node KILL
7149 @section @code{KILL} --- Send a signal to a process
7150 @fnindex KILL
7151
7152 @table @asis
7153 @item @emph{Description}:
7154 @item @emph{Standard}:
7155 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7156 See @code{kill(2)}.
7157
7158 This intrinsic is provided in both subroutine and function forms; however,
7159 only one form can be used in any given program unit.
7160
7161 @item @emph{Class}:
7162 Subroutine, function
7163
7164 @item @emph{Syntax}:
7165 @multitable @columnfractions .80
7166 @item @code{CALL KILL(C, VALUE [, STATUS])}
7167 @item @code{STATUS = KILL(C, VALUE)}
7168 @end multitable
7169
7170 @item @emph{Arguments}:
7171 @multitable @columnfractions .15 .70
7172 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7173 @code{INTENT(IN)}
7174 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7175 @code{INTENT(IN)}
7176 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7177 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7178 otherwise.
7179 @end multitable
7180
7181 @item @emph{See also}:
7182 @ref{ABORT}, @ref{EXIT}
7183 @end table
7184
7185
7186
7187 @node KIND
7188 @section @code{KIND} --- Kind of an entity
7189 @fnindex KIND
7190 @cindex kind
7191
7192 @table @asis
7193 @item @emph{Description}:
7194 @code{KIND(X)} returns the kind value of the entity @var{X}.
7195
7196 @item @emph{Standard}:
7197 Fortran 95 and later
7198
7199 @item @emph{Class}:
7200 Inquiry function
7201
7202 @item @emph{Syntax}:
7203 @code{K = KIND(X)}
7204
7205 @item @emph{Arguments}:
7206 @multitable @columnfractions .15 .70
7207 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7208 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7209 @end multitable
7210
7211 @item @emph{Return value}:
7212 The return value is a scalar of type @code{INTEGER} and of the default
7213 integer kind.
7214
7215 @item @emph{Example}:
7216 @smallexample
7217 program test_kind
7218   integer,parameter :: kc = kind(' ')
7219   integer,parameter :: kl = kind(.true.)
7220
7221   print *, "The default character kind is ", kc
7222   print *, "The default logical kind is ", kl
7223 end program test_kind
7224 @end smallexample
7225
7226 @end table
7227
7228
7229
7230 @node LBOUND
7231 @section @code{LBOUND} --- Lower dimension bounds of an array
7232 @fnindex LBOUND
7233 @cindex array, lower bound
7234
7235 @table @asis
7236 @item @emph{Description}:
7237 Returns the lower bounds of an array, or a single lower bound
7238 along the @var{DIM} dimension.
7239 @item @emph{Standard}:
7240 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7241
7242 @item @emph{Class}:
7243 Inquiry function
7244
7245 @item @emph{Syntax}:
7246 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7247
7248 @item @emph{Arguments}:
7249 @multitable @columnfractions .15 .70
7250 @item @var{ARRAY} @tab Shall be an array, of any type.
7251 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7252 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7253 expression indicating the kind parameter of the result.
7254 @end multitable
7255
7256 @item @emph{Return value}:
7257 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7258 @var{KIND} is absent, the return value is of default integer kind.
7259 If @var{DIM} is absent, the result is an array of the lower bounds of
7260 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
7261 corresponding to the lower bound of the array along that dimension.  If
7262 @var{ARRAY} is an expression rather than a whole array or array
7263 structure component, or if it has a zero extent along the relevant
7264 dimension, the lower bound is taken to be 1.
7265
7266 @item @emph{See also}:
7267 @ref{UBOUND}, @ref{LCOBOUND}
7268 @end table
7269
7270
7271
7272 @node LCOBOUND
7273 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7274 @fnindex LCOBOUND
7275 @cindex coarray, lower bound
7276
7277 @table @asis
7278 @item @emph{Description}:
7279 Returns the lower bounds of a coarray, or a single lower cobound
7280 along the @var{DIM} codimension.
7281 @item @emph{Standard}:
7282 Fortran 2008 and later
7283
7284 @item @emph{Class}:
7285 Inquiry function
7286
7287 @item @emph{Syntax}:
7288 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7289
7290 @item @emph{Arguments}:
7291 @multitable @columnfractions .15 .70
7292 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7293 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7294 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7295 expression indicating the kind parameter of the result.
7296 @end multitable
7297
7298 @item @emph{Return value}:
7299 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7300 @var{KIND} is absent, the return value is of default integer kind.
7301 If @var{DIM} is absent, the result is an array of the lower cobounds of
7302 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
7303 corresponding to the lower cobound of the array along that codimension.
7304
7305 @item @emph{See also}:
7306 @ref{UCOBOUND}, @ref{LBOUND}
7307 @end table
7308
7309
7310
7311 @node LEADZ
7312 @section @code{LEADZ} --- Number of leading zero bits of an integer
7313 @fnindex LEADZ
7314 @cindex zero bits
7315
7316 @table @asis
7317 @item @emph{Description}:
7318 @code{LEADZ} returns the number of leading zero bits of an integer.
7319
7320 @item @emph{Standard}:
7321 Fortran 2008 and later
7322
7323 @item @emph{Class}:
7324 Elemental function
7325
7326 @item @emph{Syntax}:
7327 @code{RESULT = LEADZ(I)}
7328
7329 @item @emph{Arguments}:
7330 @multitable @columnfractions .15 .70
7331 @item @var{I} @tab Shall be of type @code{INTEGER}.
7332 @end multitable
7333
7334 @item @emph{Return value}:
7335 The type of the return value is the default @code{INTEGER}.
7336 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7337
7338 @item @emph{Example}:
7339 @smallexample
7340 PROGRAM test_leadz
7341   WRITE (*,*) BIT_SIZE(1)  ! prints 32
7342   WRITE (*,*) LEADZ(1)     ! prints 31
7343 END PROGRAM
7344 @end smallexample
7345
7346 @item @emph{See also}:
7347 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7348 @end table
7349
7350
7351
7352 @node LEN
7353 @section @code{LEN} --- Length of a character entity
7354 @fnindex LEN
7355 @cindex string, length
7356
7357 @table @asis
7358 @item @emph{Description}:
7359 Returns the length of a character string.  If @var{STRING} is an array,
7360 the length of an element of @var{STRING} is returned.  Note that
7361 @var{STRING} need not be defined when this intrinsic is invoked, since
7362 only the length, not the content, of @var{STRING} is needed.
7363
7364 @item @emph{Standard}:
7365 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7366
7367 @item @emph{Class}:
7368 Inquiry function
7369
7370 @item @emph{Syntax}:
7371 @code{L = LEN(STRING [, KIND])}
7372
7373 @item @emph{Arguments}:
7374 @multitable @columnfractions .15 .70
7375 @item @var{STRING} @tab Shall be a scalar or array of type
7376 @code{CHARACTER}, with @code{INTENT(IN)}
7377 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7378 expression indicating the kind parameter of the result.
7379 @end multitable
7380
7381 @item @emph{Return value}:
7382 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7383 @var{KIND} is absent, the return value is of default integer kind.
7384
7385
7386 @item @emph{Specific names}:
7387 @multitable @columnfractions .20 .20 .20 .25
7388 @item Name               @tab Argument          @tab Return type       @tab Standard
7389 @item @code{LEN(STRING)} @tab @code{CHARACTER}  @tab @code{INTEGER}    @tab Fortran 77 and later
7390 @end multitable
7391
7392
7393 @item @emph{See also}:
7394 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7395 @end table
7396
7397
7398
7399 @node LEN_TRIM
7400 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7401 @fnindex LEN_TRIM
7402 @cindex string, length, without trailing whitespace
7403
7404 @table @asis
7405 @item @emph{Description}:
7406 Returns the length of a character string, ignoring any trailing blanks.
7407
7408 @item @emph{Standard}:
7409 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7410
7411 @item @emph{Class}:
7412 Elemental function
7413
7414 @item @emph{Syntax}:
7415 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7416
7417 @item @emph{Arguments}:
7418 @multitable @columnfractions .15 .70
7419 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7420 with @code{INTENT(IN)}
7421 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7422 expression indicating the kind parameter of the result.
7423 @end multitable
7424
7425 @item @emph{Return value}:
7426 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7427 @var{KIND} is absent, the return value is of default integer kind.
7428
7429 @item @emph{See also}:
7430 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7431 @end table
7432
7433
7434
7435 @node LGE
7436 @section @code{LGE} --- Lexical greater than or equal
7437 @fnindex LGE
7438 @cindex lexical comparison of strings
7439 @cindex string, comparison
7440
7441 @table @asis
7442 @item @emph{Description}:
7443 Determines whether one string is lexically greater than or equal to
7444 another string, where the two strings are interpreted as containing
7445 ASCII character codes.  If the String A and String B are not the same
7446 length, the shorter is compared as if spaces were appended to it to form
7447 a value that has the same length as the longer.
7448
7449 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7450 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7451 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7452 that the latter use the processor's character ordering (which is not
7453 ASCII on some targets), whereas the former always use the ASCII
7454 ordering.
7455
7456 @item @emph{Standard}:
7457 Fortran 77 and later
7458
7459 @item @emph{Class}:
7460 Elemental function
7461
7462 @item @emph{Syntax}:
7463 @code{RESULT = LGE(STRING_A, STRING_B)}
7464
7465 @item @emph{Arguments}:
7466 @multitable @columnfractions .15 .70
7467 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7468 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7469 @end multitable
7470
7471 @item @emph{Return value}:
7472 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7473 otherwise, based on the ASCII ordering.
7474
7475 @item @emph{Specific names}:
7476 @multitable @columnfractions .20 .20 .20 .25
7477 @item Name                           @tab Argument          @tab Return type       @tab Standard
7478 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7479 @end multitable
7480
7481 @item @emph{See also}:
7482 @ref{LGT}, @ref{LLE}, @ref{LLT}
7483 @end table
7484
7485
7486
7487 @node LGT
7488 @section @code{LGT} --- Lexical greater than
7489 @fnindex LGT
7490 @cindex lexical comparison of strings
7491 @cindex string, comparison
7492
7493 @table @asis
7494 @item @emph{Description}:
7495 Determines whether one string is lexically greater than another string,
7496 where the two strings are interpreted as containing ASCII character
7497 codes.  If the String A and String B are not the same length, the
7498 shorter is compared as if spaces were appended to it to form a value
7499 that has the same length as the longer.
7500
7501 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7502 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7503 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7504 that the latter use the processor's character ordering (which is not
7505 ASCII on some targets), whereas the former always use the ASCII
7506 ordering.
7507
7508 @item @emph{Standard}:
7509 Fortran 77 and later
7510
7511 @item @emph{Class}:
7512 Elemental function
7513
7514 @item @emph{Syntax}:
7515 @code{RESULT = LGT(STRING_A, STRING_B)}
7516
7517 @item @emph{Arguments}:
7518 @multitable @columnfractions .15 .70
7519 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7520 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7521 @end multitable
7522
7523 @item @emph{Return value}:
7524 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7525 otherwise, based on the ASCII ordering.
7526
7527 @item @emph{Specific names}:
7528 @multitable @columnfractions .20 .20 .20 .25
7529 @item Name                           @tab Argument          @tab Return type       @tab Standard
7530 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7531 @end multitable
7532
7533 @item @emph{See also}:
7534 @ref{LGE}, @ref{LLE}, @ref{LLT}
7535 @end table
7536
7537
7538
7539 @node LINK
7540 @section @code{LINK} --- Create a hard link
7541 @fnindex LINK
7542 @cindex file system, create link
7543 @cindex file system, hard link
7544
7545 @table @asis
7546 @item @emph{Description}:
7547 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7548 character (@code{CHAR(0)}) can be used to mark the end of the names in
7549 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7550 names are ignored.  If the @var{STATUS} argument is supplied, it
7551 contains 0 on success or a nonzero error code upon return; see
7552 @code{link(2)}.
7553
7554 This intrinsic is provided in both subroutine and function forms;
7555 however, only one form can be used in any given program unit.
7556
7557 @item @emph{Standard}:
7558 GNU extension
7559
7560 @item @emph{Class}:
7561 Subroutine, function
7562
7563 @item @emph{Syntax}:
7564 @multitable @columnfractions .80
7565 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7566 @item @code{STATUS = LINK(PATH1, PATH2)}
7567 @end multitable
7568
7569 @item @emph{Arguments}:
7570 @multitable @columnfractions .15 .70
7571 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7572 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7573 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7574 @end multitable
7575
7576 @item @emph{See also}:
7577 @ref{SYMLNK}, @ref{UNLINK}
7578 @end table
7579
7580
7581
7582 @node LLE
7583 @section @code{LLE} --- Lexical less than or equal
7584 @fnindex LLE
7585 @cindex lexical comparison of strings
7586 @cindex string, comparison
7587
7588 @table @asis
7589 @item @emph{Description}:
7590 Determines whether one string is lexically less than or equal to another
7591 string, where the two strings are interpreted as containing ASCII
7592 character codes.  If the String A and String B are not the same length,
7593 the shorter is compared as if spaces were appended to it to form a value
7594 that has the same length as the longer.
7595
7596 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7597 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7598 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7599 that the latter use the processor's character ordering (which is not
7600 ASCII on some targets), whereas the former always use the ASCII
7601 ordering.
7602
7603 @item @emph{Standard}:
7604 Fortran 77 and later
7605
7606 @item @emph{Class}:
7607 Elemental function
7608
7609 @item @emph{Syntax}:
7610 @code{RESULT = LLE(STRING_A, STRING_B)}
7611
7612 @item @emph{Arguments}:
7613 @multitable @columnfractions .15 .70
7614 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7615 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7616 @end multitable
7617
7618 @item @emph{Return value}:
7619 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7620 otherwise, based on the ASCII ordering.
7621
7622 @item @emph{Specific names}:
7623 @multitable @columnfractions .20 .20 .20 .25
7624 @item Name                           @tab Argument          @tab Return type       @tab Standard
7625 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7626 @end multitable
7627
7628 @item @emph{See also}:
7629 @ref{LGE}, @ref{LGT}, @ref{LLT}
7630 @end table
7631
7632
7633
7634 @node LLT
7635 @section @code{LLT} --- Lexical less than
7636 @fnindex LLT
7637 @cindex lexical comparison of strings
7638 @cindex string, comparison
7639
7640 @table @asis
7641 @item @emph{Description}:
7642 Determines whether one string is lexically less than another string,
7643 where the two strings are interpreted as containing ASCII character
7644 codes.  If the String A and String B are not the same length, the
7645 shorter is compared as if spaces were appended to it to form a value
7646 that has the same length as the longer.
7647
7648 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7649 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7650 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7651 that the latter use the processor's character ordering (which is not
7652 ASCII on some targets), whereas the former always use the ASCII
7653 ordering.
7654
7655 @item @emph{Standard}:
7656 Fortran 77 and later
7657
7658 @item @emph{Class}:
7659 Elemental function
7660
7661 @item @emph{Syntax}:
7662 @code{RESULT = LLT(STRING_A, STRING_B)}
7663
7664 @item @emph{Arguments}:
7665 @multitable @columnfractions .15 .70
7666 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7667 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7668 @end multitable
7669
7670 @item @emph{Return value}:
7671 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7672 otherwise, based on the ASCII ordering.
7673
7674 @item @emph{Specific names}:
7675 @multitable @columnfractions .20 .20 .20 .25
7676 @item Name                           @tab Argument          @tab Return type       @tab Standard
7677 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7678 @end multitable
7679
7680 @item @emph{See also}:
7681 @ref{LGE}, @ref{LGT}, @ref{LLE}
7682 @end table
7683
7684
7685
7686 @node LNBLNK
7687 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7688 @fnindex LNBLNK
7689 @cindex string, find non-blank character
7690
7691 @table @asis
7692 @item @emph{Description}:
7693 Returns the length of a character string, ignoring any trailing blanks.
7694 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7695 included for backwards compatibility.
7696
7697 @item @emph{Standard}:
7698 GNU extension
7699
7700 @item @emph{Class}:
7701 Elemental function
7702
7703 @item @emph{Syntax}:
7704 @code{RESULT = LNBLNK(STRING)}
7705
7706 @item @emph{Arguments}:
7707 @multitable @columnfractions .15 .70
7708 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7709 with @code{INTENT(IN)}
7710 @end multitable
7711
7712 @item @emph{Return value}:
7713 The return value is of @code{INTEGER(kind=4)} type.
7714
7715 @item @emph{See also}:
7716 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7717 @end table
7718
7719
7720
7721 @node LOC
7722 @section @code{LOC} --- Returns the address of a variable
7723 @fnindex LOC
7724 @cindex location of a variable in memory
7725
7726 @table @asis
7727 @item @emph{Description}:
7728 @code{LOC(X)} returns the address of @var{X} as an integer.
7729
7730 @item @emph{Standard}:
7731 GNU extension
7732
7733 @item @emph{Class}:
7734 Inquiry function
7735
7736 @item @emph{Syntax}:
7737 @code{RESULT = LOC(X)}
7738
7739 @item @emph{Arguments}:
7740 @multitable @columnfractions .15 .70
7741 @item @var{X} @tab Variable of any type.
7742 @end multitable
7743
7744 @item @emph{Return value}:
7745 The return value is of type @code{INTEGER}, with a @code{KIND}
7746 corresponding to the size (in bytes) of a memory address on the target
7747 machine.
7748
7749 @item @emph{Example}:
7750 @smallexample
7751 program test_loc
7752   integer :: i
7753   real :: r
7754   i = loc(r)
7755   print *, i
7756 end program test_loc
7757 @end smallexample
7758 @end table
7759
7760
7761
7762 @node LOG
7763 @section @code{LOG} --- Logarithm function
7764 @fnindex LOG
7765 @fnindex ALOG
7766 @fnindex DLOG
7767 @fnindex CLOG
7768 @fnindex ZLOG
7769 @fnindex CDLOG
7770 @cindex exponential function, inverse
7771 @cindex logarithmic function
7772
7773 @table @asis
7774 @item @emph{Description}:
7775 @code{LOG(X)} computes the logarithm of @var{X}.
7776
7777 @item @emph{Standard}:
7778 Fortran 77 and later
7779
7780 @item @emph{Class}:
7781 Elemental function
7782
7783 @item @emph{Syntax}:
7784 @code{RESULT = LOG(X)}
7785
7786 @item @emph{Arguments}:
7787 @multitable @columnfractions .15 .70
7788 @item @var{X} @tab The type shall be @code{REAL} or
7789 @code{COMPLEX}.
7790 @end multitable
7791
7792 @item @emph{Return value}:
7793 The return value is of type @code{REAL} or @code{COMPLEX}.
7794 The kind type parameter is the same as @var{X}.
7795 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7796 @math{-\pi \leq \omega \leq \pi}.
7797
7798 @item @emph{Example}:
7799 @smallexample
7800 program test_log
7801   real(8) :: x = 1.0_8
7802   complex :: z = (1.0, 2.0)
7803   x = log(x)
7804   z = log(z)
7805 end program test_log
7806 @end smallexample
7807
7808 @item @emph{Specific names}:
7809 @multitable @columnfractions .20 .20 .20 .25
7810 @item Name            @tab Argument          @tab Return type       @tab Standard
7811 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
7812 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
7813 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
7814 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7815 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7816 @end multitable
7817 @end table
7818
7819
7820
7821 @node LOG10
7822 @section @code{LOG10} --- Base 10 logarithm function
7823 @fnindex LOG10
7824 @fnindex ALOG10
7825 @fnindex DLOG10
7826 @cindex exponential function, inverse
7827 @cindex logarithmic function
7828
7829 @table @asis
7830 @item @emph{Description}:
7831 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7832
7833 @item @emph{Standard}:
7834 Fortran 77 and later
7835
7836 @item @emph{Class}:
7837 Elemental function
7838
7839 @item @emph{Syntax}:
7840 @code{RESULT = LOG10(X)}
7841
7842 @item @emph{Arguments}:
7843 @multitable @columnfractions .15 .70
7844 @item @var{X} @tab The type shall be @code{REAL}.
7845 @end multitable
7846
7847 @item @emph{Return value}:
7848 The return value is of type @code{REAL} or @code{COMPLEX}.
7849 The kind type parameter is the same as @var{X}.
7850
7851 @item @emph{Example}:
7852 @smallexample
7853 program test_log10
7854   real(8) :: x = 10.0_8
7855   x = log10(x)
7856 end program test_log10
7857 @end smallexample
7858
7859 @item @emph{Specific names}:
7860 @multitable @columnfractions .20 .20 .20 .25
7861 @item Name            @tab Argument          @tab Return type       @tab Standard
7862 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
7863 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
7864 @end multitable
7865 @end table
7866
7867
7868
7869 @node LOG_GAMMA
7870 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7871 @fnindex LOG_GAMMA
7872 @fnindex LGAMMA
7873 @fnindex ALGAMA
7874 @fnindex DLGAMA
7875 @cindex Gamma function, logarithm of
7876
7877 @table @asis
7878 @item @emph{Description}:
7879 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7880 of the Gamma (@math{\Gamma}) function.
7881
7882 @item @emph{Standard}:
7883 Fortran 2008 and later
7884
7885 @item @emph{Class}:
7886 Elemental function
7887
7888 @item @emph{Syntax}:
7889 @code{X = LOG_GAMMA(X)}
7890
7891 @item @emph{Arguments}:
7892 @multitable @columnfractions .15 .70
7893 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7894 nor a negative integer.
7895 @end multitable
7896
7897 @item @emph{Return value}:
7898 The return value is of type @code{REAL} of the same kind as @var{X}.
7899
7900 @item @emph{Example}:
7901 @smallexample
7902 program test_log_gamma
7903   real :: x = 1.0
7904   x = lgamma(x) ! returns 0.0
7905 end program test_log_gamma
7906 @end smallexample
7907
7908 @item @emph{Specific names}:
7909 @multitable @columnfractions .20 .20 .20 .25
7910 @item Name             @tab Argument         @tab Return type       @tab Standard
7911 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7912 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
7913 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
7914 @end multitable
7915
7916 @item @emph{See also}:
7917 Gamma function: @ref{GAMMA}
7918
7919 @end table
7920
7921
7922
7923 @node LOGICAL
7924 @section @code{LOGICAL} --- Convert to logical type
7925 @fnindex LOGICAL
7926 @cindex conversion, to logical
7927
7928 @table @asis
7929 @item @emph{Description}:
7930 Converts one kind of @code{LOGICAL} variable to another.
7931
7932 @item @emph{Standard}:
7933 Fortran 95 and later
7934
7935 @item @emph{Class}:
7936 Elemental function
7937
7938 @item @emph{Syntax}:
7939 @code{RESULT = LOGICAL(L [, KIND])}
7940
7941 @item @emph{Arguments}:
7942 @multitable @columnfractions .15 .70
7943 @item @var{L}    @tab The type shall be @code{LOGICAL}.
7944 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7945 expression indicating the kind parameter of the result.
7946 @end multitable
7947
7948 @item @emph{Return value}:
7949 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7950 kind corresponding to @var{KIND}, or of the default logical kind if
7951 @var{KIND} is not given.
7952
7953 @item @emph{See also}:
7954 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7955 @end table
7956
7957
7958
7959 @node LONG
7960 @section @code{LONG} --- Convert to integer type
7961 @fnindex LONG
7962 @cindex conversion, to integer
7963
7964 @table @asis
7965 @item @emph{Description}:
7966 Convert to a @code{KIND=4} integer type, which is the same size as a C
7967 @code{long} integer.  This is equivalent to the standard @code{INT}
7968 intrinsic with an optional argument of @code{KIND=4}, and is only
7969 included for backwards compatibility.
7970
7971 @item @emph{Standard}:
7972 GNU extension
7973
7974 @item @emph{Class}:
7975 Elemental function
7976
7977 @item @emph{Syntax}:
7978 @code{RESULT = LONG(A)}
7979
7980 @item @emph{Arguments}:
7981 @multitable @columnfractions .15 .70
7982 @item @var{A}    @tab Shall be of type @code{INTEGER},
7983 @code{REAL}, or @code{COMPLEX}.
7984 @end multitable
7985
7986 @item @emph{Return value}:
7987 The return value is a @code{INTEGER(4)} variable.
7988
7989 @item @emph{See also}:
7990 @ref{INT}, @ref{INT2}, @ref{INT8}
7991 @end table
7992
7993
7994
7995 @node LSHIFT
7996 @section @code{LSHIFT} --- Left shift bits
7997 @fnindex LSHIFT
7998 @cindex bits, shift left
7999
8000 @table @asis
8001 @item @emph{Description}:
8002 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8003 bits shifted left by @var{SHIFT} places.  If the absolute value of
8004 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8005 Bits shifted out from the left end are lost; zeros are shifted in from
8006 the opposite end.
8007
8008 This function has been superseded by the @code{ISHFT} intrinsic, which
8009 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8010 which is standard in Fortran 2008 and later.
8011
8012 @item @emph{Standard}:
8013 GNU extension
8014
8015 @item @emph{Class}:
8016 Elemental function
8017
8018 @item @emph{Syntax}:
8019 @code{RESULT = LSHIFT(I, SHIFT)}
8020
8021 @item @emph{Arguments}:
8022 @multitable @columnfractions .15 .70
8023 @item @var{I} @tab The type shall be @code{INTEGER}.
8024 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8025 @end multitable
8026
8027 @item @emph{Return value}:
8028 The return value is of type @code{INTEGER} and of the same kind as
8029 @var{I}.
8030
8031 @item @emph{See also}:
8032 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8033 @ref{SHIFTR}
8034
8035 @end table
8036
8037
8038
8039 @node LSTAT
8040 @section @code{LSTAT} --- Get file status
8041 @fnindex LSTAT
8042 @cindex file system, file status
8043
8044 @table @asis
8045 @item @emph{Description}:
8046 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8047 symbolic link, then the link itself is statted, not the file that it
8048 refers to.
8049
8050 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8051
8052 This intrinsic is provided in both subroutine and function forms;
8053 however, only one form can be used in any given program unit.
8054
8055 @item @emph{Standard}:
8056 GNU extension
8057
8058 @item @emph{Class}:
8059 Subroutine, function
8060
8061 @item @emph{Syntax}:
8062 @multitable @columnfractions .80
8063 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8064 @item @code{STATUS = LSTAT(NAME, VALUES)}
8065 @end multitable
8066
8067 @item @emph{Arguments}:
8068 @multitable @columnfractions .15 .70
8069 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of the default
8070 kind, a valid path within the file system.
8071 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8072 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8073 Returns 0 on success and a system specific error code otherwise.
8074 @end multitable
8075
8076 @item @emph{Example}:
8077 See @ref{STAT} for an example.
8078
8079 @item @emph{See also}:
8080 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8081 @end table
8082
8083
8084
8085 @node LTIME
8086 @section @code{LTIME} --- Convert time to local time info
8087 @fnindex LTIME
8088 @cindex time, conversion to local time info
8089
8090 @table @asis
8091 @item @emph{Description}:
8092 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8093 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8094 to the local time zone using @code{localtime(3)}.
8095
8096 @item @emph{Standard}:
8097 GNU extension
8098
8099 @item @emph{Class}:
8100 Subroutine
8101
8102 @item @emph{Syntax}:
8103 @code{CALL LTIME(TIME, VALUES)}
8104
8105 @item @emph{Arguments}:
8106 @multitable @columnfractions .15 .70
8107 @item @var{TIME}  @tab An @code{INTEGER} scalar expression
8108 corresponding to a system time, with @code{INTENT(IN)}.
8109 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8110 with @code{INTENT(OUT)}.
8111 @end multitable
8112
8113 @item @emph{Return value}:
8114 The elements of @var{VALUES} are assigned as follows:
8115 @enumerate
8116 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8117 seconds
8118 @item Minutes after the hour, range 0--59
8119 @item Hours past midnight, range 0--23
8120 @item Day of month, range 0--31
8121 @item Number of months since January, range 0--12
8122 @item Years since 1900
8123 @item Number of days since Sunday, range 0--6
8124 @item Days since January 1
8125 @item Daylight savings indicator: positive if daylight savings is in
8126 effect, zero if not, and negative if the information is not available.
8127 @end enumerate
8128
8129 @item @emph{See also}:
8130 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8131
8132 @end table
8133
8134
8135
8136 @node MALLOC
8137 @section @code{MALLOC} --- Allocate dynamic memory
8138 @fnindex MALLOC
8139 @cindex pointer, cray
8140
8141 @table @asis
8142 @item @emph{Description}:
8143 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8144 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8145 is an extension intended to be used with Cray pointers, and is provided
8146 in GNU Fortran to allow the user to compile legacy code. For new code
8147 using Fortran 95 pointers, the memory allocation intrinsic is
8148 @code{ALLOCATE}.
8149
8150 @item @emph{Standard}:
8151 GNU extension
8152
8153 @item @emph{Class}:
8154 Function
8155
8156 @item @emph{Syntax}:
8157 @code{PTR = MALLOC(SIZE)}
8158
8159 @item @emph{Arguments}:
8160 @multitable @columnfractions .15 .70
8161 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8162 @end multitable
8163
8164 @item @emph{Return value}:
8165 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8166 variables of type @code{INTEGER(K)} have the same size as
8167 C pointers (@code{sizeof(void *)}).
8168
8169 @item @emph{Example}:
8170 The following example demonstrates the use of @code{MALLOC} and
8171 @code{FREE} with Cray pointers.
8172
8173 @smallexample
8174 program test_malloc
8175   implicit none
8176   integer i
8177   real*8 x(*), z
8178   pointer(ptr_x,x)
8179
8180   ptr_x = malloc(20*8)
8181   do i = 1, 20
8182     x(i) = sqrt(1.0d0 / i)
8183   end do
8184   z = 0
8185   do i = 1, 20
8186     z = z + x(i)
8187     print *, z
8188   end do
8189   call free(ptr_x)
8190 end program test_malloc
8191 @end smallexample
8192
8193 @item @emph{See also}:
8194 @ref{FREE}
8195 @end table
8196
8197
8198
8199 @node MASKL
8200 @section @code{MASKL} --- Left justified mask
8201 @fnindex MASKL
8202 @cindex mask, left justified
8203
8204 @table @asis
8205 @item @emph{Description}:
8206 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8207 remaining bits set to 0.
8208
8209 @item @emph{Standard}:
8210 Fortran 2008 and later
8211
8212 @item @emph{Class}:
8213 Elemental function
8214
8215 @item @emph{Syntax}:
8216 @code{RESULT = MASKL(I[, KIND])}
8217
8218 @item @emph{Arguments}:
8219 @multitable @columnfractions .15 .70
8220 @item @var{I} @tab Shall be of type @code{INTEGER}.
8221 @item @var{KIND} @tab Shall be a scalar constant expression of type
8222 @code{INTEGER}.
8223 @end multitable
8224
8225 @item @emph{Return value}:
8226 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8227 specifies the kind value of the return type; otherwise, it is of the
8228 default integer kind.
8229
8230 @item @emph{See also}:
8231 @ref{MASKR}
8232 @end table
8233
8234
8235
8236 @node MASKR
8237 @section @code{MASKR} --- Right justified mask
8238 @fnindex MASKR
8239 @cindex mask, right justified
8240
8241 @table @asis
8242 @item @emph{Description}:
8243 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8244 remaining bits set to 0.
8245
8246 @item @emph{Standard}:
8247 Fortran 2008 and later
8248
8249 @item @emph{Class}:
8250 Elemental function
8251
8252 @item @emph{Syntax}:
8253 @code{RESULT = MASKR(I[, KIND])}
8254
8255 @item @emph{Arguments}:
8256 @multitable @columnfractions .15 .70
8257 @item @var{I} @tab Shall be of type @code{INTEGER}.
8258 @item @var{KIND} @tab Shall be a scalar constant expression of type
8259 @code{INTEGER}.
8260 @end multitable
8261
8262 @item @emph{Return value}:
8263 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8264 specifies the kind value of the return type; otherwise, it is of the
8265 default integer kind.
8266
8267 @item @emph{See also}:
8268 @ref{MASKL}
8269 @end table
8270
8271
8272
8273 @node MATMUL
8274 @section @code{MATMUL} --- matrix multiplication
8275 @fnindex MATMUL
8276 @cindex matrix multiplication
8277 @cindex product, matrix
8278
8279 @table @asis
8280 @item @emph{Description}:
8281 Performs a matrix multiplication on numeric or logical arguments.
8282
8283 @item @emph{Standard}:
8284 Fortran 95 and later
8285
8286 @item @emph{Class}:
8287 Transformational function
8288
8289 @item @emph{Syntax}:
8290 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8291
8292 @item @emph{Arguments}:
8293 @multitable @columnfractions .15 .70
8294 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8295 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8296 one or two.
8297 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8298 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8299 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8300 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8301 equal to the last (or only) dimension of @var{MATRIX_A}.
8302 @end multitable
8303
8304 @item @emph{Return value}:
8305 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
8306 kind of the result follow the usual type and kind promotion rules, as
8307 for the @code{*} or @code{.AND.} operators.
8308
8309 @item @emph{See also}:
8310 @end table
8311
8312
8313
8314 @node MAX
8315 @section @code{MAX} --- Maximum value of an argument list
8316 @fnindex MAX
8317 @fnindex MAX0
8318 @fnindex AMAX0
8319 @fnindex MAX1
8320 @fnindex AMAX1
8321 @fnindex DMAX1
8322 @cindex maximum value
8323
8324 @table @asis
8325 @item @emph{Description}:
8326 Returns the argument with the largest (most positive) value.
8327
8328 @item @emph{Standard}:
8329 Fortran 77 and later
8330
8331 @item @emph{Class}:
8332 Elemental function
8333
8334 @item @emph{Syntax}:
8335 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8336
8337 @item @emph{Arguments}:
8338 @multitable @columnfractions .15 .70
8339 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8340 @code{REAL}.
8341 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8342 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8343 permitted.)
8344 @end multitable
8345
8346 @item @emph{Return value}:
8347 The return value corresponds to the maximum value among the arguments,
8348 and has the same type and kind as the first argument.
8349
8350 @item @emph{Specific names}:
8351 @multitable @columnfractions .20 .20 .20 .25
8352 @item Name             @tab Argument             @tab Return type         @tab Standard
8353 @item @code{MAX0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
8354 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8355 @item @code{MAX1(A1)}  @tab @code{REAL A1}       @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
8356 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1}    @tab @code{REAL(4)}      @tab Fortran 77 and later
8357 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1}    @tab @code{REAL(8)}      @tab Fortran 77 and later
8358 @end multitable
8359
8360 @item @emph{See also}:
8361 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8362
8363 @end table
8364
8365
8366
8367 @node MAXEXPONENT
8368 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8369 @fnindex MAXEXPONENT
8370 @cindex model representation, maximum exponent
8371
8372 @table @asis
8373 @item @emph{Description}:
8374 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8375 type of @code{X}.
8376
8377 @item @emph{Standard}:
8378 Fortran 95 and later
8379
8380 @item @emph{Class}:
8381 Inquiry function
8382
8383 @item @emph{Syntax}:
8384 @code{RESULT = MAXEXPONENT(X)}
8385
8386 @item @emph{Arguments}:
8387 @multitable @columnfractions .15 .70
8388 @item @var{X} @tab Shall be of type @code{REAL}.
8389 @end multitable
8390
8391 @item @emph{Return value}:
8392 The return value is of type @code{INTEGER} and of the default integer
8393 kind.
8394
8395 @item @emph{Example}:
8396 @smallexample
8397 program exponents
8398   real(kind=4) :: x
8399   real(kind=8) :: y
8400
8401   print *, minexponent(x), maxexponent(x)
8402   print *, minexponent(y), maxexponent(y)
8403 end program exponents
8404 @end smallexample
8405 @end table
8406
8407
8408
8409 @node MAXLOC
8410 @section @code{MAXLOC} --- Location of the maximum value within an array
8411 @fnindex MAXLOC
8412 @cindex array, location of maximum element
8413
8414 @table @asis
8415 @item @emph{Description}:
8416 Determines the location of the element in the array with the maximum
8417 value, or, if the @var{DIM} argument is supplied, determines the
8418 locations of the maximum element along each row of the array in the
8419 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8420 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8421 element in the array has the maximum value, the location returned is
8422 that of the first such element in array element order.  If the array has
8423 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8424 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8425 and all of the elements of @var{MASK} along a given row are zero, the
8426 result value for that row is zero.
8427
8428 @item @emph{Standard}:
8429 Fortran 95 and later
8430
8431 @item @emph{Class}:
8432 Transformational function
8433
8434 @item @emph{Syntax}:
8435 @multitable @columnfractions .80
8436 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8437 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8438 @end multitable
8439
8440 @item @emph{Arguments}:
8441 @multitable @columnfractions .15 .70
8442 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8443 @code{REAL}.
8444 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8445 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8446 inclusive.  It may not be an optional dummy argument.
8447 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8448 and conformable with @var{ARRAY}.
8449 @end multitable
8450
8451 @item @emph{Return value}:
8452 If @var{DIM} is absent, the result is a rank-one array with a length
8453 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8454 is an array with a rank one less than the rank of @var{ARRAY}, and a
8455 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8456 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8457 of one, the result is a scalar.  In all cases, the result is of default
8458 @code{INTEGER} type.
8459
8460 @item @emph{See also}:
8461 @ref{MAX}, @ref{MAXVAL}
8462
8463 @end table
8464
8465
8466
8467 @node MAXVAL
8468 @section @code{MAXVAL} --- Maximum value of an array
8469 @fnindex MAXVAL
8470 @cindex array, maximum value
8471 @cindex maximum value
8472
8473 @table @asis
8474 @item @emph{Description}:
8475 Determines the maximum value of the elements in an array value, or, if
8476 the @var{DIM} argument is supplied, determines the maximum value along
8477 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8478 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8479 considered.  If the array has zero size, or all of the elements of
8480 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8481 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8482 type.
8483
8484 @item @emph{Standard}:
8485 Fortran 95 and later
8486
8487 @item @emph{Class}:
8488 Transformational function
8489
8490 @item @emph{Syntax}:
8491 @multitable @columnfractions .80
8492 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8493 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8494 @end multitable
8495
8496 @item @emph{Arguments}:
8497 @multitable @columnfractions .15 .70
8498 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8499 @code{REAL}.
8500 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8501 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8502 inclusive.  It may not be an optional dummy argument.
8503 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8504 and conformable with @var{ARRAY}.
8505 @end multitable
8506
8507 @item @emph{Return value}:
8508 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8509 is a scalar.  If @var{DIM} is present, the result is an array with a
8510 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8511 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8512 cases, the result is of the same type and kind as @var{ARRAY}.
8513
8514 @item @emph{See also}:
8515 @ref{MAX}, @ref{MAXLOC}
8516 @end table
8517
8518
8519
8520 @node MCLOCK
8521 @section @code{MCLOCK} --- Time function
8522 @fnindex MCLOCK
8523 @cindex time, clock ticks
8524 @cindex clock ticks
8525
8526 @table @asis
8527 @item @emph{Description}:
8528 Returns the number of clock ticks since the start of the process, based
8529 on the UNIX function @code{clock(3)}.
8530
8531 This intrinsic is not fully portable, such as to systems with 32-bit
8532 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8533 the values returned by this intrinsic might be, or become, negative, or
8534 numerically less than previous values, during a single run of the
8535 compiled program.
8536
8537 @item @emph{Standard}:
8538 GNU extension
8539
8540 @item @emph{Class}:
8541 Function
8542
8543 @item @emph{Syntax}:
8544 @code{RESULT = MCLOCK()}
8545
8546 @item @emph{Return value}:
8547 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8548 number of clock ticks since the start of the process, or @code{-1} if
8549 the system does not support @code{clock(3)}.
8550
8551 @item @emph{See also}:
8552 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8553
8554 @end table
8555
8556
8557
8558 @node MCLOCK8
8559 @section @code{MCLOCK8} --- Time function (64-bit)
8560 @fnindex MCLOCK8
8561 @cindex time, clock ticks
8562 @cindex clock ticks
8563
8564 @table @asis
8565 @item @emph{Description}:
8566 Returns the number of clock ticks since the start of the process, based
8567 on the UNIX function @code{clock(3)}.
8568
8569 @emph{Warning:} this intrinsic does not increase the range of the timing
8570 values over that returned by @code{clock(3)}. On a system with a 32-bit
8571 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8572 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8573 overflows of the 32-bit value can still occur. Therefore, the values
8574 returned by this intrinsic might be or become negative or numerically
8575 less than previous values during a single run of the compiled program.
8576
8577 @item @emph{Standard}:
8578 GNU extension
8579
8580 @item @emph{Class}:
8581 Function
8582
8583 @item @emph{Syntax}:
8584 @code{RESULT = MCLOCK8()}
8585
8586 @item @emph{Return value}:
8587 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8588 number of clock ticks since the start of the process, or @code{-1} if
8589 the system does not support @code{clock(3)}.
8590
8591 @item @emph{See also}:
8592 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8593
8594 @end table
8595
8596
8597
8598 @node MERGE
8599 @section @code{MERGE} --- Merge variables
8600 @fnindex MERGE
8601 @cindex array, merge arrays
8602 @cindex array, combine arrays
8603
8604 @table @asis
8605 @item @emph{Description}:
8606 Select values from two arrays according to a logical mask.  The result
8607 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8608 @var{FSOURCE} if it is @code{.FALSE.}.
8609
8610 @item @emph{Standard}:
8611 Fortran 95 and later
8612
8613 @item @emph{Class}:
8614 Elemental function
8615
8616 @item @emph{Syntax}:
8617 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8618
8619 @item @emph{Arguments}:
8620 @multitable @columnfractions .15 .70
8621 @item @var{TSOURCE} @tab May be of any type.
8622 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8623 as @var{TSOURCE}.
8624 @item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
8625 @end multitable
8626
8627 @item @emph{Return value}:
8628 The result is of the same type and type parameters as @var{TSOURCE}.
8629
8630 @end table
8631
8632
8633
8634 @node MERGE_BITS
8635 @section @code{MERGE_BITS} --- Merge of bits under mask
8636 @fnindex MERGE_BITS
8637 @cindex bits, merge
8638
8639 @table @asis
8640 @item @emph{Description}:
8641 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8642 as determined by the mask.  The i-th bit of the result is equal to the
8643 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8644 the i-th bit of @var{J} otherwise.
8645
8646 @item @emph{Standard}:
8647 Fortran 2008 and later
8648
8649 @item @emph{Class}:
8650 Elemental function
8651
8652 @item @emph{Syntax}:
8653 @code{RESULT = MERGE_BITS(I, J, MASK)}
8654
8655 @item @emph{Arguments}:
8656 @multitable @columnfractions .15 .70
8657 @item @var{I}    @tab Shall be of type @code{INTEGER}.
8658 @item @var{J}    @tab Shall be of type @code{INTEGER} and of the same
8659 kind as @var{I}.
8660 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8661 kind as @var{I}.
8662 @end multitable
8663
8664 @item @emph{Return value}:
8665 The result is of the same type and kind as @var{I}.
8666
8667 @end table
8668
8669
8670
8671 @node MIN
8672 @section @code{MIN} --- Minimum value of an argument list
8673 @fnindex MIN
8674 @fnindex MIN0
8675 @fnindex AMIN0
8676 @fnindex MIN1
8677 @fnindex AMIN1
8678 @fnindex DMIN1
8679 @cindex minimum value
8680
8681 @table @asis
8682 @item @emph{Description}:
8683 Returns the argument with the smallest (most negative) value.
8684
8685 @item @emph{Standard}:
8686 Fortran 77 and later
8687
8688 @item @emph{Class}:
8689 Elemental function
8690
8691 @item @emph{Syntax}:
8692 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8693
8694 @item @emph{Arguments}:
8695 @multitable @columnfractions .15 .70
8696 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8697 @code{REAL}.
8698 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8699 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8700 permitted.)
8701 @end multitable
8702
8703 @item @emph{Return value}:
8704 The return value corresponds to the maximum value among the arguments,
8705 and has the same type and kind as the first argument.
8706
8707 @item @emph{Specific names}:
8708 @multitable @columnfractions .20 .20 .20 .25
8709 @item Name              @tab Argument             @tab Return type        @tab Standard
8710 @item @code{MIN0(A1)}   @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8711 @item @code{AMIN0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{REAL(4)}     @tab Fortran 77 and later
8712 @item @code{MIN1(A1)}   @tab @code{REAL A1}       @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8713 @item @code{AMIN1(A1)}  @tab @code{REAL(4) A1}    @tab @code{REAL(4)}     @tab Fortran 77 and later
8714 @item @code{DMIN1(A1)}  @tab @code{REAL(8) A1}    @tab @code{REAL(8)}     @tab Fortran 77 and later
8715 @end multitable
8716
8717 @item @emph{See also}:
8718 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8719 @end table
8720
8721
8722
8723 @node MINEXPONENT
8724 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8725 @fnindex MINEXPONENT
8726 @cindex model representation, minimum exponent
8727
8728 @table @asis
8729 @item @emph{Description}:
8730 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8731 type of @code{X}.
8732
8733 @item @emph{Standard}:
8734 Fortran 95 and later
8735
8736 @item @emph{Class}:
8737 Inquiry function
8738
8739 @item @emph{Syntax}:
8740 @code{RESULT = MINEXPONENT(X)}
8741
8742 @item @emph{Arguments}:
8743 @multitable @columnfractions .15 .70
8744 @item @var{X} @tab Shall be of type @code{REAL}.
8745 @end multitable
8746
8747 @item @emph{Return value}:
8748 The return value is of type @code{INTEGER} and of the default integer
8749 kind.
8750
8751 @item @emph{Example}:
8752 See @code{MAXEXPONENT} for an example.
8753 @end table
8754
8755
8756
8757 @node MINLOC
8758 @section @code{MINLOC} --- Location of the minimum value within an array
8759 @fnindex MINLOC
8760 @cindex array, location of minimum element
8761
8762 @table @asis
8763 @item @emph{Description}:
8764 Determines the location of the element in the array with the minimum
8765 value, or, if the @var{DIM} argument is supplied, determines the
8766 locations of the minimum element along each row of the array in the
8767 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8768 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8769 element in the array has the minimum value, the location returned is
8770 that of the first such element in array element order.  If the array has
8771 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8772 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8773 and all of the elements of @var{MASK} along a given row are zero, the
8774 result value for that row is zero.
8775
8776 @item @emph{Standard}:
8777 Fortran 95 and later
8778
8779 @item @emph{Class}:
8780 Transformational function
8781
8782 @item @emph{Syntax}:
8783 @multitable @columnfractions .80
8784 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8785 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8786 @end multitable
8787
8788 @item @emph{Arguments}:
8789 @multitable @columnfractions .15 .70
8790 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8791 @code{REAL}.
8792 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8793 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8794 inclusive.  It may not be an optional dummy argument.
8795 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8796 and conformable with @var{ARRAY}.
8797 @end multitable
8798
8799 @item @emph{Return value}:
8800 If @var{DIM} is absent, the result is a rank-one array with a length
8801 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8802 is an array with a rank one less than the rank of @var{ARRAY}, and a
8803 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8804 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8805 of one, the result is a scalar.  In all cases, the result is of default
8806 @code{INTEGER} type.
8807
8808 @item @emph{See also}:
8809 @ref{MIN}, @ref{MINVAL}
8810
8811 @end table
8812
8813
8814
8815 @node MINVAL
8816 @section @code{MINVAL} --- Minimum value of an array
8817 @fnindex MINVAL
8818 @cindex array, minimum value
8819 @cindex minimum value
8820
8821 @table @asis
8822 @item @emph{Description}:
8823 Determines the minimum value of the elements in an array value, or, if
8824 the @var{DIM} argument is supplied, determines the minimum value along
8825 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8826 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8827 considered.  If the array has zero size, or all of the elements of
8828 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8829 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8830 @var{ARRAY} is of character type.
8831
8832 @item @emph{Standard}:
8833 Fortran 95 and later
8834
8835 @item @emph{Class}:
8836 Transformational function
8837
8838 @item @emph{Syntax}:
8839 @multitable @columnfractions .80
8840 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8841 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8842 @end multitable
8843
8844 @item @emph{Arguments}:
8845 @multitable @columnfractions .15 .70
8846 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8847 @code{REAL}.
8848 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8849 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8850 inclusive.  It may not be an optional dummy argument.
8851 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8852 and conformable with @var{ARRAY}.
8853 @end multitable
8854
8855 @item @emph{Return value}:
8856 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8857 is a scalar.  If @var{DIM} is present, the result is an array with a
8858 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8859 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8860 cases, the result is of the same type and kind as @var{ARRAY}.
8861
8862 @item @emph{See also}:
8863 @ref{MIN}, @ref{MINLOC}
8864
8865 @end table
8866
8867
8868
8869 @node MOD
8870 @section @code{MOD} --- Remainder function
8871 @fnindex MOD
8872 @fnindex AMOD
8873 @fnindex DMOD
8874 @cindex remainder
8875 @cindex division, remainder
8876
8877 @table @asis
8878 @item @emph{Description}:
8879 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8880 calculated as @code{A - (INT(A/P) * P)}.
8881
8882 @item @emph{Standard}:
8883 Fortran 77 and later
8884
8885 @item @emph{Class}:
8886 Elemental function
8887
8888 @item @emph{Syntax}:
8889 @code{RESULT = MOD(A, P)}
8890
8891 @item @emph{Arguments}:
8892 @multitable @columnfractions .15 .70
8893 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8894 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8895 equal to zero
8896 @end multitable
8897
8898 @item @emph{Return value}:
8899 The kind of the return value is the result of cross-promoting
8900 the kinds of the arguments.
8901
8902 @item @emph{Example}:
8903 @smallexample
8904 program test_mod
8905   print *, mod(17,3)
8906   print *, mod(17.5,5.5)
8907   print *, mod(17.5d0,5.5)
8908   print *, mod(17.5,5.5d0)
8909
8910   print *, mod(-17,3)
8911   print *, mod(-17.5,5.5)
8912   print *, mod(-17.5d0,5.5)
8913   print *, mod(-17.5,5.5d0)
8914
8915   print *, mod(17,-3)
8916   print *, mod(17.5,-5.5)
8917   print *, mod(17.5d0,-5.5)
8918   print *, mod(17.5,-5.5d0)
8919 end program test_mod
8920 @end smallexample
8921
8922 @item @emph{Specific names}:
8923 @multitable @columnfractions .20 .20 .20 .25
8924 @item Name             @tab Arguments          @tab Return type    @tab Standard
8925 @item @code{MOD(A,P)}  @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8926 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8927 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8928 @end multitable
8929 @end table
8930
8931
8932
8933 @node MODULO
8934 @section @code{MODULO} --- Modulo function
8935 @fnindex MODULO
8936 @cindex modulo
8937 @cindex division, modulo
8938
8939 @table @asis
8940 @item @emph{Description}:
8941 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8942
8943 @item @emph{Standard}:
8944 Fortran 95 and later
8945
8946 @item @emph{Class}:
8947 Elemental function
8948
8949 @item @emph{Syntax}:
8950 @code{RESULT = MODULO(A, P)}
8951
8952 @item @emph{Arguments}:
8953 @multitable @columnfractions .15 .70
8954 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8955 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8956 @end multitable
8957
8958 @item @emph{Return value}:
8959 The type and kind of the result are those of the arguments.
8960 @table @asis
8961 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8962 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8963 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8964 (exclusive).
8965 @item If @var{A} and @var{P} are of type @code{REAL}:
8966 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8967 @end table
8968 In all cases, if @var{P} is zero the result is processor-dependent.
8969
8970 @item @emph{Example}:
8971 @smallexample
8972 program test_modulo
8973   print *, modulo(17,3)
8974   print *, modulo(17.5,5.5)
8975
8976   print *, modulo(-17,3)
8977   print *, modulo(-17.5,5.5)
8978
8979   print *, modulo(17,-3)
8980   print *, modulo(17.5,-5.5)
8981 end program
8982 @end smallexample
8983
8984 @end table
8985
8986
8987
8988 @node MOVE_ALLOC
8989 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8990 @fnindex MOVE_ALLOC
8991 @cindex moving allocation
8992 @cindex allocation, moving
8993
8994 @table @asis
8995 @item @emph{Description}:
8996 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8997 @var{TO}.  @var{FROM} will become deallocated in the process.
8998
8999 @item @emph{Standard}:
9000 Fortran 2003 and later
9001
9002 @item @emph{Class}:
9003 Pure subroutine
9004
9005 @item @emph{Syntax}:
9006 @code{CALL MOVE_ALLOC(FROM, TO)}
9007
9008 @item @emph{Arguments}:
9009 @multitable @columnfractions .15 .70
9010 @item @var{FROM}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9011 of any type and kind.
9012 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9013 of the same type, kind and rank as @var{FROM}.
9014 @end multitable
9015
9016 @item @emph{Return value}:
9017 None
9018
9019 @item @emph{Example}:
9020 @smallexample
9021 program test_move_alloc
9022     integer, allocatable :: a(:), b(:)
9023
9024     allocate(a(3))
9025     a = [ 1, 2, 3 ]
9026     call move_alloc(a, b)
9027     print *, allocated(a), allocated(b)
9028     print *, b
9029 end program test_move_alloc
9030 @end smallexample
9031 @end table
9032
9033
9034
9035 @node MVBITS
9036 @section @code{MVBITS} --- Move bits from one integer to another
9037 @fnindex MVBITS
9038 @cindex bits, move
9039
9040 @table @asis
9041 @item @emph{Description}:
9042 Moves @var{LEN} bits from positions @var{FROMPOS} through
9043 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9044 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9045 affected by the movement of bits is unchanged. The values of
9046 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9047 @code{BIT_SIZE(FROM)}.
9048
9049 @item @emph{Standard}:
9050 Fortran 95 and later
9051
9052 @item @emph{Class}:
9053 Elemental subroutine
9054
9055 @item @emph{Syntax}:
9056 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9057
9058 @item @emph{Arguments}:
9059 @multitable @columnfractions .15 .70
9060 @item @var{FROM}    @tab The type shall be @code{INTEGER}.
9061 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9062 @item @var{LEN}     @tab The type shall be @code{INTEGER}.
9063 @item @var{TO}      @tab The type shall be @code{INTEGER}, of the
9064 same kind as @var{FROM}.
9065 @item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
9066 @end multitable
9067
9068 @item @emph{See also}:
9069 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9070 @end table
9071
9072
9073
9074 @node NEAREST
9075 @section @code{NEAREST} --- Nearest representable number
9076 @fnindex NEAREST
9077 @cindex real number, nearest different
9078 @cindex floating point, nearest different
9079
9080 @table @asis
9081 @item @emph{Description}:
9082 @code{NEAREST(X, S)} returns the processor-representable number nearest
9083 to @code{X} in the direction indicated by the sign of @code{S}.
9084
9085 @item @emph{Standard}:
9086 Fortran 95 and later
9087
9088 @item @emph{Class}:
9089 Elemental function
9090
9091 @item @emph{Syntax}:
9092 @code{RESULT = NEAREST(X, S)}
9093
9094 @item @emph{Arguments}:
9095 @multitable @columnfractions .15 .70
9096 @item @var{X} @tab Shall be of type @code{REAL}.
9097 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9098 not equal to zero.
9099 @end multitable
9100
9101 @item @emph{Return value}:
9102 The return value is of the same type as @code{X}. If @code{S} is
9103 positive, @code{NEAREST} returns the processor-representable number
9104 greater than @code{X} and nearest to it. If @code{S} is negative,
9105 @code{NEAREST} returns the processor-representable number smaller than
9106 @code{X} and nearest to it.
9107
9108 @item @emph{Example}:
9109 @smallexample
9110 program test_nearest
9111   real :: x, y
9112   x = nearest(42.0, 1.0)
9113   y = nearest(42.0, -1.0)
9114   write (*,"(3(G20.15))") x, y, x - y
9115 end program test_nearest
9116 @end smallexample
9117 @end table
9118
9119
9120
9121 @node NEW_LINE
9122 @section @code{NEW_LINE} --- New line character
9123 @fnindex NEW_LINE
9124 @cindex newline
9125 @cindex output, newline
9126
9127 @table @asis
9128 @item @emph{Description}:
9129 @code{NEW_LINE(C)} returns the new-line character.
9130
9131 @item @emph{Standard}:
9132 Fortran 2003 and later
9133
9134 @item @emph{Class}:
9135 Inquiry function
9136
9137 @item @emph{Syntax}:
9138 @code{RESULT = NEW_LINE(C)}
9139
9140 @item @emph{Arguments}:
9141 @multitable @columnfractions .15 .70
9142 @item @var{C}    @tab The argument shall be a scalar or array of the
9143 type @code{CHARACTER}.
9144 @end multitable
9145
9146 @item @emph{Return value}:
9147 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9148 the same kind as parameter @var{C}.
9149
9150 @item @emph{Example}:
9151 @smallexample
9152 program newline
9153   implicit none
9154   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9155 end program newline
9156 @end smallexample
9157 @end table
9158
9159
9160
9161 @node NINT
9162 @section @code{NINT} --- Nearest whole number
9163 @fnindex NINT
9164 @fnindex IDNINT
9165 @cindex rounding, nearest whole number
9166
9167 @table @asis
9168 @item @emph{Description}:
9169 @code{NINT(A)} rounds its argument to the nearest whole number.
9170
9171 @item @emph{Standard}:
9172 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9173
9174 @item @emph{Class}:
9175 Elemental function
9176
9177 @item @emph{Syntax}:
9178 @code{RESULT = NINT(A [, KIND])}
9179
9180 @item @emph{Arguments}:
9181 @multitable @columnfractions .15 .70
9182 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
9183 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9184 expression indicating the kind parameter of the result.
9185 @end multitable
9186
9187 @item @emph{Return value}:
9188 Returns @var{A} with the fractional portion of its magnitude eliminated by
9189 rounding to the nearest whole number and with its sign preserved,
9190 converted to an @code{INTEGER} of the default kind.
9191
9192 @item @emph{Example}:
9193 @smallexample
9194 program test_nint
9195   real(4) x4
9196   real(8) x8
9197   x4 = 1.234E0_4
9198   x8 = 4.321_8
9199   print *, nint(x4), idnint(x8)
9200 end program test_nint
9201 @end smallexample
9202
9203 @item @emph{Specific names}:
9204 @multitable @columnfractions .20 .20 .20 .25
9205 @item Name             @tab Argument           @tab Return Type     @tab Standard
9206 @item @code{NINT(A)}   @tab @code{REAL(4) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9207 @item @code{IDNINT(A)} @tab @code{REAL(8) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9208 @end multitable
9209
9210 @item @emph{See also}:
9211 @ref{CEILING}, @ref{FLOOR}
9212
9213 @end table
9214
9215
9216
9217 @node NORM2
9218 @section @code{NORM2} --- Euclidean vector norms
9219 @fnindex NORM2
9220 @cindex Euclidean vector norm
9221 @cindex L2 vector norm
9222 @cindex norm, Euclidean
9223
9224 @table @asis
9225 @item @emph{Description}:
9226 Calculates the Euclidean vector norm (@math{L_2} norm) of
9227 of @var{ARRAY} along dimension @var{DIM}.
9228
9229 @item @emph{Standard}:
9230 Fortran 2008 and later
9231
9232 @item @emph{Class}:
9233 Transformational function
9234
9235 @item @emph{Syntax}:
9236 @multitable @columnfractions .80
9237 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9238 @end multitable
9239
9240 @item @emph{Arguments}:
9241 @multitable @columnfractions .15 .70
9242 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9243 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9244 @code{INTEGER} with a value in the range from 1 to n, where n
9245 equals the rank of @var{ARRAY}.
9246 @end multitable
9247
9248 @item @emph{Return value}:
9249 The result is of the same type as @var{ARRAY}.
9250
9251 If @var{DIM} is absent, a scalar with the square root of the sum of all
9252 elements in @var{ARRAY} squared  is returned. Otherwise, an array of
9253 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9254 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9255 is returned.
9256
9257 @item @emph{Example}:
9258 @smallexample
9259 PROGRAM test_sum
9260   REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9261   print *, NORM2(x)  ! = sqrt(55.) ~ 7.416
9262 END PROGRAM
9263 @end smallexample
9264 @end table
9265
9266
9267
9268 @node NOT
9269 @section @code{NOT} --- Logical negation
9270 @fnindex NOT
9271 @cindex bits, negate
9272 @cindex bitwise logical not
9273 @cindex logical not, bitwise
9274
9275 @table @asis
9276 @item @emph{Description}:
9277 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9278
9279 @item @emph{Standard}:
9280 Fortran 95 and later
9281
9282 @item @emph{Class}:
9283 Elemental function
9284
9285 @item @emph{Syntax}:
9286 @code{RESULT = NOT(I)}
9287
9288 @item @emph{Arguments}:
9289 @multitable @columnfractions .15 .70
9290 @item @var{I} @tab The type shall be @code{INTEGER}.
9291 @end multitable
9292
9293 @item @emph{Return value}:
9294 The return type is @code{INTEGER}, of the same kind as the
9295 argument.
9296
9297 @item @emph{See also}:
9298 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9299
9300 @end table
9301
9302
9303
9304 @node NULL
9305 @section @code{NULL} --- Function that returns an disassociated pointer
9306 @fnindex NULL
9307 @cindex pointer, status
9308 @cindex pointer, disassociated
9309
9310 @table @asis
9311 @item @emph{Description}:
9312 Returns a disassociated pointer.
9313
9314 If @var{MOLD} is present, a disassociated pointer of the same type is
9315 returned, otherwise the type is determined by context.
9316
9317 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9318 includes cases where it is required.
9319
9320 @item @emph{Standard}:
9321 Fortran 95 and later
9322
9323 @item @emph{Class}:
9324 Transformational function
9325
9326 @item @emph{Syntax}:
9327 @code{PTR => NULL([MOLD])}
9328
9329 @item @emph{Arguments}:
9330 @multitable @columnfractions .15 .70
9331 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9332 status and of any type.
9333 @end multitable
9334
9335 @item @emph{Return value}:
9336 A disassociated pointer.
9337
9338 @item @emph{Example}:
9339 @smallexample
9340 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9341 @end smallexample
9342
9343 @item @emph{See also}:
9344 @ref{ASSOCIATED}
9345 @end table
9346
9347
9348
9349 @node NUM_IMAGES
9350 @section @code{NUM_IMAGES} --- Function that returns the number of images
9351 @fnindex NUM_IMAGES
9352 @cindex coarray, @code{NUM_IMAGES}
9353 @cindex images, number of
9354
9355 @table @asis
9356 @item @emph{Description}:
9357 Returns the number of images.
9358
9359 @item @emph{Standard}:
9360 Fortran 2008 and later
9361
9362 @item @emph{Class}:
9363 Transformational function
9364
9365 @item @emph{Syntax}:
9366 @code{RESULT = NUM_IMAGES()}
9367
9368 @item @emph{Arguments}: None.
9369
9370 @item @emph{Return value}:
9371 Scalar default-kind integer.
9372
9373 @item @emph{Example}:
9374 @smallexample
9375 INTEGER :: value[*]
9376 INTEGER :: i
9377 value = THIS_IMAGE()
9378 SYNC ALL
9379 IF (THIS_IMAGE() == 1) THEN
9380   DO i = 1, NUM_IMAGES()
9381     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9382   END DO
9383 END IF
9384 @end smallexample
9385
9386 @item @emph{See also}:
9387 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9388 @end table
9389
9390
9391
9392 @node OR
9393 @section @code{OR} --- Bitwise logical OR
9394 @fnindex OR
9395 @cindex bitwise logical or
9396 @cindex logical or, bitwise
9397
9398 @table @asis
9399 @item @emph{Description}:
9400 Bitwise logical @code{OR}.
9401
9402 This intrinsic routine is provided for backwards compatibility with
9403 GNU Fortran 77.  For integer arguments, programmers should consider
9404 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9405
9406 @item @emph{Standard}:
9407 GNU extension
9408
9409 @item @emph{Class}:
9410 Function
9411
9412 @item @emph{Syntax}:
9413 @code{RESULT = OR(I, J)}
9414
9415 @item @emph{Arguments}:
9416 @multitable @columnfractions .15 .70
9417 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9418 type or a scalar @code{LOGICAL} type.
9419 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9420 @end multitable
9421
9422 @item @emph{Return value}:
9423 The return type is either a scalar @code{INTEGER} or a scalar
9424 @code{LOGICAL}.  If the kind type parameters differ, then the
9425 smaller kind type is implicitly converted to larger kind, and the
9426 return has the larger kind.
9427
9428 @item @emph{Example}:
9429 @smallexample
9430 PROGRAM test_or
9431   LOGICAL :: T = .TRUE., F = .FALSE.
9432   INTEGER :: a, b
9433   DATA a / Z'F' /, b / Z'3' /
9434
9435   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9436   WRITE (*,*) OR(a, b)
9437 END PROGRAM
9438 @end smallexample
9439
9440 @item @emph{See also}:
9441 Fortran 95 elemental function: @ref{IOR}
9442 @end table
9443
9444
9445
9446 @node PACK
9447 @section @code{PACK} --- Pack an array into an array of rank one
9448 @fnindex PACK
9449 @cindex array, packing
9450 @cindex array, reduce dimension
9451 @cindex array, gather elements
9452
9453 @table @asis
9454 @item @emph{Description}:
9455 Stores the elements of @var{ARRAY} in an array of rank one.
9456
9457 The beginning of the resulting array is made up of elements whose @var{MASK}
9458 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9459 @var{VECTOR}.
9460
9461 @item @emph{Standard}:
9462 Fortran 95 and later
9463
9464 @item @emph{Class}:
9465 Transformational function
9466
9467 @item @emph{Syntax}:
9468 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9469
9470 @item @emph{Arguments}:
9471 @multitable @columnfractions .15 .70
9472 @item @var{ARRAY}  @tab Shall be an array of any type.
9473 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
9474 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9475 scalar.
9476 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9477 as @var{ARRAY} and of rank one. If present, the number of elements in
9478 @var{VECTOR} shall be equal to or greater than the number of true elements
9479 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9480 @var{VECTOR} shall be equal to or greater than the number of elements in
9481 @var{ARRAY}.
9482 @end multitable
9483
9484 @item @emph{Return value}:
9485 The result is an array of rank one and the same type as that of @var{ARRAY}.
9486 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9487 number of @code{TRUE} values in @var{MASK} otherwise.
9488
9489 @item @emph{Example}:
9490 Gathering nonzero elements from an array:
9491 @smallexample
9492 PROGRAM test_pack_1
9493   INTEGER :: m(6)
9494   m = (/ 1, 0, 0, 0, 5, 0 /)
9495   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
9496 END PROGRAM
9497 @end smallexample
9498
9499 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9500 @smallexample
9501 PROGRAM test_pack_2
9502   INTEGER :: m(4)
9503   m = (/ 1, 0, 0, 2 /)
9504   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
9505 END PROGRAM
9506 @end smallexample
9507
9508 @item @emph{See also}:
9509 @ref{UNPACK}
9510 @end table
9511
9512
9513
9514 @node PARITY
9515 @section @code{PARITY} --- Reduction with exclusive OR
9516 @fnindex PARITY
9517 @cindex Parity
9518 @cindex Reduction, XOR
9519 @cindex XOR reduction
9520
9521 @table @asis
9522 @item @emph{Description}:
9523 Calculates the parity, i.e. the reduction using @code{.XOR.},
9524 of @var{MASK} along dimension @var{DIM}.
9525
9526 @item @emph{Standard}:
9527 Fortran 2008 and later
9528
9529 @item @emph{Class}:
9530 Transformational function
9531
9532 @item @emph{Syntax}:
9533 @multitable @columnfractions .80
9534 @item @code{RESULT = PARITY(MASK[, DIM])}
9535 @end multitable
9536
9537 @item @emph{Arguments}:
9538 @multitable @columnfractions .15 .70
9539 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9540 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9541 @code{INTEGER} with a value in the range from 1 to n, where n
9542 equals the rank of @var{MASK}.
9543 @end multitable
9544
9545 @item @emph{Return value}:
9546 The result is of the same type as @var{MASK}.
9547
9548 If @var{DIM} is absent, a scalar with the parity of all elements in
9549 @var{MASK} is returned, i.e. true if an odd number of elements is
9550 @code{.true.} and false otherwise.  If @var{DIM} is present, an array
9551 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9552 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9553 dropped is returned.
9554
9555 @item @emph{Example}:
9556 @smallexample
9557 PROGRAM test_sum
9558   LOGICAL :: x(2) = [ .true., .false. ]
9559   print *, PARITY(x) ! prints "T" (true).
9560 END PROGRAM
9561 @end smallexample
9562 @end table
9563
9564
9565
9566 @node PERROR
9567 @section @code{PERROR} --- Print system error message
9568 @fnindex PERROR
9569 @cindex system, error handling
9570
9571 @table @asis
9572 @item @emph{Description}:
9573 Prints (on the C @code{stderr} stream) a newline-terminated error
9574 message corresponding to the last system error. This is prefixed by
9575 @var{STRING}, a colon and a space. See @code{perror(3)}.
9576
9577 @item @emph{Standard}:
9578 GNU extension
9579
9580 @item @emph{Class}:
9581 Subroutine
9582
9583 @item @emph{Syntax}:
9584 @code{CALL PERROR(STRING)}
9585
9586 @item @emph{Arguments}:
9587 @multitable @columnfractions .15 .70
9588 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9589 default kind.
9590 @end multitable
9591
9592 @item @emph{See also}:
9593 @ref{IERRNO}
9594 @end table
9595
9596
9597
9598 @node PRECISION
9599 @section @code{PRECISION} --- Decimal precision of a real kind
9600 @fnindex PRECISION
9601 @cindex model representation, precision
9602
9603 @table @asis
9604 @item @emph{Description}:
9605 @code{PRECISION(X)} returns the decimal precision in the model of the
9606 type of @code{X}.
9607
9608 @item @emph{Standard}:
9609 Fortran 95 and later
9610
9611 @item @emph{Class}:
9612 Inquiry function
9613
9614 @item @emph{Syntax}:
9615 @code{RESULT = PRECISION(X)}
9616
9617 @item @emph{Arguments}:
9618 @multitable @columnfractions .15 .70
9619 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9620 @end multitable
9621
9622 @item @emph{Return value}:
9623 The return value is of type @code{INTEGER} and of the default integer
9624 kind.
9625
9626 @item @emph{See also}:
9627 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9628
9629 @item @emph{Example}:
9630 @smallexample
9631 program prec_and_range
9632   real(kind=4) :: x(2)
9633   complex(kind=8) :: y
9634
9635   print *, precision(x), range(x)
9636   print *, precision(y), range(y)
9637 end program prec_and_range
9638 @end smallexample
9639 @end table
9640
9641
9642
9643 @node POPCNT
9644 @section @code{POPCNT} --- Number of bits set
9645 @fnindex POPCNT
9646 @cindex binary representation
9647 @cindex bits set
9648
9649 @table @asis
9650 @item @emph{Description}:
9651 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9652 representation of @code{I}.
9653
9654 @item @emph{Standard}:
9655 Fortran 2008 and later
9656
9657 @item @emph{Class}:
9658 Elemental function
9659
9660 @item @emph{Syntax}:
9661 @code{RESULT = POPCNT(I)}
9662
9663 @item @emph{Arguments}:
9664 @multitable @columnfractions .15 .70
9665 @item @var{I} @tab Shall be of type @code{INTEGER}.
9666 @end multitable
9667
9668 @item @emph{Return value}:
9669 The return value is of type @code{INTEGER} and of the default integer
9670 kind.
9671
9672 @item @emph{See also}:
9673 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9674
9675 @item @emph{Example}:
9676 @smallexample
9677 program test_population
9678   print *, popcnt(127),       poppar(127)
9679   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9680   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9681 end program test_population
9682 @end smallexample
9683 @end table
9684
9685
9686 @node POPPAR
9687 @section @code{POPPAR} --- Parity of the number of bits set
9688 @fnindex POPPAR
9689 @cindex binary representation
9690 @cindex parity
9691
9692 @table @asis
9693 @item @emph{Description}:
9694 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9695 of the number of bits set ('1' bits) in the binary representation of
9696 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9697 and 1 for an odd number of '1' bits.
9698
9699 @item @emph{Standard}:
9700 Fortran 2008 and later
9701
9702 @item @emph{Class}:
9703 Elemental function
9704
9705 @item @emph{Syntax}:
9706 @code{RESULT = POPPAR(I)}
9707
9708 @item @emph{Arguments}:
9709 @multitable @columnfractions .15 .70
9710 @item @var{I} @tab Shall be of type @code{INTEGER}.
9711 @end multitable
9712
9713 @item @emph{Return value}:
9714 The return value is of type @code{INTEGER} and of the default integer
9715 kind.
9716
9717 @item @emph{See also}:
9718 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9719
9720 @item @emph{Example}:
9721 @smallexample
9722 program test_population
9723   print *, popcnt(127),       poppar(127)
9724   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9725   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9726 end program test_population
9727 @end smallexample
9728 @end table
9729
9730
9731
9732 @node PRESENT
9733 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9734 @fnindex PRESENT
9735
9736 @table @asis
9737 @item @emph{Description}:
9738 Determines whether an optional dummy argument is present.
9739
9740 @item @emph{Standard}:
9741 Fortran 95 and later
9742
9743 @item @emph{Class}:
9744 Inquiry function
9745
9746 @item @emph{Syntax}:
9747 @code{RESULT = PRESENT(A)}
9748
9749 @item @emph{Arguments}:
9750 @multitable @columnfractions .15 .70
9751 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9752 value, or a dummy procedure. It shall be the name of an optional dummy argument
9753 accessible within the current subroutine or function.
9754 @end multitable
9755
9756 @item @emph{Return value}:
9757 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9758 @code{FALSE} otherwise.
9759
9760 @item @emph{Example}:
9761 @smallexample
9762 PROGRAM test_present
9763   WRITE(*,*) f(), f(42)      ! "F T"
9764 CONTAINS
9765   LOGICAL FUNCTION f(x)
9766     INTEGER, INTENT(IN), OPTIONAL :: x
9767     f = PRESENT(x)
9768   END FUNCTION
9769 END PROGRAM
9770 @end smallexample
9771 @end table
9772
9773
9774
9775 @node PRODUCT
9776 @section @code{PRODUCT} --- Product of array elements
9777 @fnindex PRODUCT
9778 @cindex array, product
9779 @cindex array, multiply elements
9780 @cindex array, conditionally multiply elements
9781 @cindex multiply array elements
9782
9783 @table @asis
9784 @item @emph{Description}:
9785 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9786 the corresponding element in @var{MASK} is @code{TRUE}.
9787
9788 @item @emph{Standard}:
9789 Fortran 95 and later
9790
9791 @item @emph{Class}:
9792 Transformational function
9793
9794 @item @emph{Syntax}:
9795 @multitable @columnfractions .80
9796 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9797 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9798 @end multitable
9799
9800 @item @emph{Arguments}:
9801 @multitable @columnfractions .15 .70
9802 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9803 @code{REAL} or @code{COMPLEX}.
9804 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9805 @code{INTEGER} with a value in the range from 1 to n, where n
9806 equals the rank of @var{ARRAY}.
9807 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
9808 and either be a scalar or an array of the same shape as @var{ARRAY}.
9809 @end multitable
9810
9811 @item @emph{Return value}:
9812 The result is of the same type as @var{ARRAY}.
9813
9814 If @var{DIM} is absent, a scalar with the product of all elements in
9815 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9816 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9817 dimension @var{DIM} dropped is returned.
9818
9819
9820 @item @emph{Example}:
9821 @smallexample
9822 PROGRAM test_product
9823   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9824   print *, PRODUCT(x)                    ! all elements, product = 120
9825   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9826 END PROGRAM
9827 @end smallexample
9828
9829 @item @emph{See also}:
9830 @ref{SUM}
9831 @end table
9832
9833
9834
9835 @node RADIX
9836 @section @code{RADIX} --- Base of a model number
9837 @fnindex RADIX
9838 @cindex model representation, base
9839 @cindex model representation, radix
9840
9841 @table @asis
9842 @item @emph{Description}:
9843 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9844
9845 @item @emph{Standard}:
9846 Fortran 95 and later
9847
9848 @item @emph{Class}:
9849 Inquiry function
9850
9851 @item @emph{Syntax}:
9852 @code{RESULT = RADIX(X)}
9853
9854 @item @emph{Arguments}:
9855 @multitable @columnfractions .15 .70
9856 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9857 @end multitable
9858
9859 @item @emph{Return value}:
9860 The return value is a scalar of type @code{INTEGER} and of the default
9861 integer kind.
9862
9863 @item @emph{See also}:
9864 @ref{SELECTED_REAL_KIND}
9865
9866 @item @emph{Example}:
9867 @smallexample
9868 program test_radix
9869   print *, "The radix for the default integer kind is", radix(0)
9870   print *, "The radix for the default real kind is", radix(0.0)
9871 end program test_radix
9872 @end smallexample
9873
9874 @end table
9875
9876
9877
9878 @node RAN
9879 @section @code{RAN} --- Real pseudo-random number
9880 @fnindex RAN
9881 @cindex random number generation
9882
9883 @table @asis
9884 @item @emph{Description}:
9885 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9886 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
9887 documentation.
9888
9889 @item @emph{Standard}:
9890 GNU extension
9891
9892 @item @emph{Class}:
9893 Function
9894
9895 @item @emph{See also}:
9896 @ref{RAND}, @ref{RANDOM_NUMBER}
9897 @end table
9898
9899
9900
9901 @node RAND
9902 @section @code{RAND} --- Real pseudo-random number
9903 @fnindex RAND
9904 @cindex random number generation
9905
9906 @table @asis
9907 @item @emph{Description}:
9908 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
9909 distribution between 0 and 1. If @var{FLAG} is 0, the next number
9910 in the current sequence is returned; if @var{FLAG} is 1, the generator
9911 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
9912 it is used as a new seed with @code{SRAND}.
9913
9914 This intrinsic routine is provided for backwards compatibility with
9915 GNU Fortran 77. It implements a simple modulo generator as provided
9916 by @command{g77}. For new code, one should consider the use of
9917 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
9918
9919 @item @emph{Standard}:
9920 GNU extension
9921
9922 @item @emph{Class}:
9923 Function
9924
9925 @item @emph{Syntax}:
9926 @code{RESULT = RAND(I)}
9927
9928 @item @emph{Arguments}:
9929 @multitable @columnfractions .15 .70
9930 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
9931 @end multitable
9932
9933 @item @emph{Return value}:
9934 The return value is of @code{REAL} type and the default kind.
9935
9936 @item @emph{Example}:
9937 @smallexample
9938 program test_rand
9939   integer,parameter :: seed = 86456
9940
9941   call srand(seed)
9942   print *, rand(), rand(), rand(), rand()
9943   print *, rand(seed), rand(), rand(), rand()
9944 end program test_rand
9945 @end smallexample
9946
9947 @item @emph{See also}:
9948 @ref{SRAND}, @ref{RANDOM_NUMBER}
9949
9950 @end table
9951
9952
9953
9954 @node RANDOM_NUMBER
9955 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9956 @fnindex RANDOM_NUMBER
9957 @cindex random number generation
9958
9959 @table @asis
9960 @item @emph{Description}:
9961 Returns a single pseudorandom number or an array of pseudorandom numbers
9962 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9963
9964 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9965 Stupid) random number generator (RNG). This RNG combines:
9966 @enumerate
9967 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9968 with a period of @math{2^{32}},
9969 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9970 @item  Two 16-bit multiply-with-carry generators with a period of
9971 @math{597273182964842497 > 2^{59}}.
9972 @end enumerate
9973 The overall period exceeds @math{2^{123}}.
9974
9975 Please note, this RNG is thread safe if used within OpenMP directives,
9976 i.e., its state will be consistent while called from multiple threads.
9977 However, the KISS generator does not create random numbers in parallel
9978 from multiple sources, but in sequence from a single source. If an
9979 OpenMP-enabled application heavily relies on random numbers, one should
9980 consider employing a dedicated parallel random number generator instead.
9981
9982 @item @emph{Standard}:
9983 Fortran 95 and later
9984
9985 @item @emph{Class}:
9986 Subroutine
9987
9988 @item @emph{Syntax}:
9989 @code{RANDOM_NUMBER(HARVEST)}
9990
9991 @item @emph{Arguments}:
9992 @multitable @columnfractions .15 .70
9993 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9994 @end multitable
9995
9996 @item @emph{Example}:
9997 @smallexample
9998 program test_random_number
9999   REAL :: r(5,5)
10000   CALL init_random_seed()         ! see example of RANDOM_SEED
10001   CALL RANDOM_NUMBER(r)
10002 end program
10003 @end smallexample
10004
10005 @item @emph{See also}:
10006 @ref{RANDOM_SEED}
10007 @end table
10008
10009
10010
10011 @node RANDOM_SEED
10012 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10013 @fnindex RANDOM_SEED
10014 @cindex random number generation, seeding
10015 @cindex seeding a random number generator
10016
10017 @table @asis
10018 @item @emph{Description}:
10019 Restarts or queries the state of the pseudorandom number generator used by
10020 @code{RANDOM_NUMBER}.
10021
10022 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10023 a default state. The example below shows how to initialize the random
10024 seed based on the system's time.
10025
10026 @item @emph{Standard}:
10027 Fortran 95 and later
10028
10029 @item @emph{Class}:
10030 Subroutine
10031
10032 @item @emph{Syntax}:
10033 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10034
10035 @item @emph{Arguments}:
10036 @multitable @columnfractions .15 .70
10037 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10038 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10039 of the arrays used with the @var{PUT} and @var{GET} arguments.
10040 @item @var{PUT}  @tab (Optional) Shall be an array of type default
10041 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10042 the array must be larger than or equal to the number returned by the
10043 @var{SIZE} argument.
10044 @item @var{GET}  @tab (Optional) Shall be an array of type default
10045 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10046 of the array must be larger than or equal to the number returned by
10047 the @var{SIZE} argument.
10048 @end multitable
10049
10050 @item @emph{Example}:
10051 @smallexample
10052 SUBROUTINE init_random_seed()
10053   INTEGER :: i, n, clock
10054   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10055
10056   CALL RANDOM_SEED(size = n)
10057   ALLOCATE(seed(n))
10058
10059   CALL SYSTEM_CLOCK(COUNT=clock)
10060
10061   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10062   CALL RANDOM_SEED(PUT = seed)
10063
10064   DEALLOCATE(seed)
10065 END SUBROUTINE
10066 @end smallexample
10067
10068 @item @emph{See also}:
10069 @ref{RANDOM_NUMBER}
10070 @end table
10071
10072
10073
10074 @node RANGE
10075 @section @code{RANGE} --- Decimal exponent range
10076 @fnindex RANGE
10077 @cindex model representation, range
10078
10079 @table @asis
10080 @item @emph{Description}:
10081 @code{RANGE(X)} returns the decimal exponent range in the model of the
10082 type of @code{X}.
10083
10084 @item @emph{Standard}:
10085 Fortran 95 and later
10086
10087 @item @emph{Class}:
10088 Inquiry function
10089
10090 @item @emph{Syntax}:
10091 @code{RESULT = RANGE(X)}
10092
10093 @item @emph{Arguments}:
10094 @multitable @columnfractions .15 .70
10095 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10096 or @code{COMPLEX}.
10097 @end multitable
10098
10099 @item @emph{Return value}:
10100 The return value is of type @code{INTEGER} and of the default integer
10101 kind.
10102
10103 @item @emph{See also}:
10104 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10105
10106 @item @emph{Example}:
10107 See @code{PRECISION} for an example.
10108 @end table
10109
10110
10111
10112 @node REAL
10113 @section @code{REAL} --- Convert to real type
10114 @fnindex REAL
10115 @fnindex REALPART
10116 @fnindex FLOAT
10117 @fnindex DFLOAT
10118 @fnindex SNGL
10119 @cindex conversion, to real
10120 @cindex complex numbers, real part
10121
10122 @table @asis
10123 @item @emph{Description}:
10124 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type.  The
10125 @code{REALPART} function is provided for compatibility with @command{g77},
10126 and its use is strongly discouraged.
10127
10128 @item @emph{Standard}:
10129 Fortran 77 and later
10130
10131 @item @emph{Class}:
10132 Elemental function
10133
10134 @item @emph{Syntax}:
10135 @multitable @columnfractions .80
10136 @item @code{RESULT = REAL(A [, KIND])}
10137 @item @code{RESULT = REALPART(Z)}
10138 @end multitable
10139
10140 @item @emph{Arguments}:
10141 @multitable @columnfractions .15 .70
10142 @item @var{A}    @tab Shall be @code{INTEGER}, @code{REAL}, or
10143 @code{COMPLEX}.
10144 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10145 expression indicating the kind parameter of the result.
10146 @end multitable
10147
10148 @item @emph{Return value}:
10149 These functions return a @code{REAL} variable or array under
10150 the following rules:
10151
10152 @table @asis
10153 @item (A)
10154 @code{REAL(A)} is converted to a default real type if @var{A} is an
10155 integer or real variable.
10156 @item (B)
10157 @code{REAL(A)} is converted to a real type with the kind type parameter
10158 of @var{A} if @var{A} is a complex variable.
10159 @item (C)
10160 @code{REAL(A, KIND)} is converted to a real type with kind type
10161 parameter @var{KIND} if @var{A} is a complex, integer, or real
10162 variable.
10163 @end table
10164
10165 @item @emph{Example}:
10166 @smallexample
10167 program test_real
10168   complex :: x = (1.0, 2.0)
10169   print *, real(x), real(x,8), realpart(x)
10170 end program test_real
10171 @end smallexample
10172
10173 @item @emph{Specific names}:
10174 @multitable @columnfractions .20 .20 .20 .25
10175 @item Name             @tab Argument           @tab Return type     @tab Standard
10176 @item @code{FLOAT(A)}  @tab @code{INTEGER(4)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10177 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)}  @tab @code{REAL(8)}  @tab GNU extension
10178 @item @code{SNGL(A)}   @tab @code{INTEGER(8)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10179 @end multitable
10180
10181
10182 @item @emph{See also}:
10183 @ref{DBLE}
10184
10185 @end table
10186
10187
10188
10189 @node RENAME
10190 @section @code{RENAME} --- Rename a file
10191 @fnindex RENAME
10192 @cindex file system, rename file
10193
10194 @table @asis
10195 @item @emph{Description}:
10196 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10197 character (@code{CHAR(0)}) can be used to mark the end of the names in
10198 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10199 names are ignored.  If the @var{STATUS} argument is supplied, it
10200 contains 0 on success or a nonzero error code upon return; see
10201 @code{rename(2)}.
10202
10203 This intrinsic is provided in both subroutine and function forms;
10204 however, only one form can be used in any given program unit.
10205
10206 @item @emph{Standard}:
10207 GNU extension
10208
10209 @item @emph{Class}:
10210 Subroutine, function
10211
10212 @item @emph{Syntax}:
10213 @multitable @columnfractions .80
10214 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10215 @item @code{STATUS = RENAME(PATH1, PATH2)}
10216 @end multitable
10217
10218 @item @emph{Arguments}:
10219 @multitable @columnfractions .15 .70
10220 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10221 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10222 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10223 @end multitable
10224
10225 @item @emph{See also}:
10226 @ref{LINK}
10227
10228 @end table
10229
10230
10231
10232 @node REPEAT
10233 @section @code{REPEAT} --- Repeated string concatenation
10234 @fnindex REPEAT
10235 @cindex string, repeat
10236 @cindex string, concatenate
10237
10238 @table @asis
10239 @item @emph{Description}:
10240 Concatenates @var{NCOPIES} copies of a string.
10241
10242 @item @emph{Standard}:
10243 Fortran 95 and later
10244
10245 @item @emph{Class}:
10246 Transformational function
10247
10248 @item @emph{Syntax}:
10249 @code{RESULT = REPEAT(STRING, NCOPIES)}
10250
10251 @item @emph{Arguments}:
10252 @multitable @columnfractions .15 .70
10253 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
10254 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10255 @end multitable
10256
10257 @item @emph{Return value}:
10258 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10259 of @var{STRING}.
10260
10261 @item @emph{Example}:
10262 @smallexample
10263 program test_repeat
10264   write(*,*) repeat("x", 5)   ! "xxxxx"
10265 end program
10266 @end smallexample
10267 @end table
10268
10269
10270
10271 @node RESHAPE
10272 @section @code{RESHAPE} --- Function to reshape an array
10273 @fnindex RESHAPE
10274 @cindex array, change dimensions
10275 @cindex array, transmogrify
10276
10277 @table @asis
10278 @item @emph{Description}:
10279 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10280 the new array may be padded with elements from @var{PAD} or permuted
10281 as defined by @var{ORDER}.
10282
10283 @item @emph{Standard}:
10284 Fortran 95 and later
10285
10286 @item @emph{Class}:
10287 Transformational function
10288
10289 @item @emph{Syntax}:
10290 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10291
10292 @item @emph{Arguments}:
10293 @multitable @columnfractions .15 .70
10294 @item @var{SOURCE} @tab Shall be an array of any type.
10295 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
10296 array of rank one. Its values must be positive or zero.
10297 @item @var{PAD}    @tab (Optional) shall be an array of the same
10298 type as @var{SOURCE}.
10299 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
10300 and an array of the same shape as @var{SHAPE}. Its values shall
10301 be a permutation of the numbers from 1 to n, where n is the size of
10302 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10303 be assumed.
10304 @end multitable
10305
10306 @item @emph{Return value}:
10307 The result is an array of shape @var{SHAPE} with the same type as
10308 @var{SOURCE}.
10309
10310 @item @emph{Example}:
10311 @smallexample
10312 PROGRAM test_reshape
10313   INTEGER, DIMENSION(4) :: x
10314   WRITE(*,*) SHAPE(x)                       ! prints "4"
10315   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
10316 END PROGRAM
10317 @end smallexample
10318
10319 @item @emph{See also}:
10320 @ref{SHAPE}
10321 @end table
10322
10323
10324
10325 @node RRSPACING
10326 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10327 @fnindex RRSPACING
10328 @cindex real number, relative spacing
10329 @cindex floating point, relative spacing
10330
10331
10332 @table @asis
10333 @item @emph{Description}:
10334 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
10335 model numbers near @var{X}.
10336
10337 @item @emph{Standard}:
10338 Fortran 95 and later
10339
10340 @item @emph{Class}:
10341 Elemental function
10342
10343 @item @emph{Syntax}:
10344 @code{RESULT = RRSPACING(X)}
10345
10346 @item @emph{Arguments}:
10347 @multitable @columnfractions .15 .70
10348 @item @var{X} @tab Shall be of type @code{REAL}.
10349 @end multitable
10350
10351 @item @emph{Return value}:
10352 The return value is of the same type and kind as @var{X}.
10353 The value returned is equal to
10354 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10355
10356 @item @emph{See also}:
10357 @ref{SPACING}
10358 @end table
10359
10360
10361
10362 @node RSHIFT
10363 @section @code{RSHIFT} --- Right shift bits
10364 @fnindex RSHIFT
10365 @cindex bits, shift right
10366
10367 @table @asis
10368 @item @emph{Description}:
10369 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10370 bits shifted right by @var{SHIFT} places.  If the absolute value of
10371 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10372 Bits shifted out from the right end are lost. The fill is arithmetic: the
10373 bits shifted in from the left end are equal to the leftmost bit, which in
10374 two's complement representation is the sign bit.
10375
10376 This function has been superseded by the @code{SHIFTA} intrinsic, which
10377 is standard in Fortran 2008 and later.
10378
10379 @item @emph{Standard}:
10380 GNU extension
10381
10382 @item @emph{Class}:
10383 Elemental function
10384
10385 @item @emph{Syntax}:
10386 @code{RESULT = RSHIFT(I, SHIFT)}
10387
10388 @item @emph{Arguments}:
10389 @multitable @columnfractions .15 .70
10390 @item @var{I} @tab The type shall be @code{INTEGER}.
10391 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10392 @end multitable
10393
10394 @item @emph{Return value}:
10395 The return value is of type @code{INTEGER} and of the same kind as
10396 @var{I}.
10397
10398 @item @emph{See also}:
10399 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10400 @ref{SHIFTL}
10401
10402 @end table
10403
10404
10405
10406 @node SAME_TYPE_AS
10407 @section @code{SAME_TYPE_AS} ---  Query dynamic types for equality
10408 @fnindex SAME_TYPE_AS
10409
10410 @table @asis
10411 @item @emph{Description}:
10412 Query dynamic types for equality.
10413
10414 @item @emph{Standard}:
10415 Fortran 2003 and later
10416
10417 @item @emph{Class}:
10418 Inquiry function
10419
10420 @item @emph{Syntax}:
10421 @code{RESULT = SAME_TYPE_AS(A, B)}
10422
10423 @item @emph{Arguments}:
10424 @multitable @columnfractions .15 .70
10425 @item @var{A} @tab Shall be an object of extensible declared type or
10426 unlimited polymorphic.
10427 @item @var{B} @tab Shall be an object of extensible declared type or
10428 unlimited polymorphic.
10429 @end multitable
10430
10431 @item @emph{Return value}:
10432 The return value is a scalar of type default logical. It is true if and
10433 only if the dynamic type of A is the same as the dynamic type of B.
10434
10435 @item @emph{See also}:
10436 @ref{EXTENDS_TYPE_OF}
10437
10438 @end table
10439
10440
10441
10442 @node SCALE
10443 @section @code{SCALE} --- Scale a real value
10444 @fnindex SCALE
10445 @cindex real number, scale
10446 @cindex floating point, scale
10447
10448 @table @asis
10449 @item @emph{Description}:
10450 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10451
10452 @item @emph{Standard}:
10453 Fortran 95 and later
10454
10455 @item @emph{Class}:
10456 Elemental function
10457
10458 @item @emph{Syntax}:
10459 @code{RESULT = SCALE(X, I)}
10460
10461 @item @emph{Arguments}:
10462 @multitable @columnfractions .15 .70
10463 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10464 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10465 @end multitable
10466
10467 @item @emph{Return value}:
10468 The return value is of the same type and kind as @var{X}.
10469 Its value is @code{X * RADIX(X)**I}.
10470
10471 @item @emph{Example}:
10472 @smallexample
10473 program test_scale
10474   real :: x = 178.1387e-4
10475   integer :: i = 5
10476   print *, scale(x,i), x*radix(x)**i
10477 end program test_scale
10478 @end smallexample
10479
10480 @end table
10481
10482
10483
10484 @node SCAN
10485 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10486 @fnindex SCAN
10487 @cindex string, find subset
10488
10489 @table @asis
10490 @item @emph{Description}:
10491 Scans a @var{STRING} for any of the characters in a @var{SET}
10492 of characters.
10493
10494 If @var{BACK} is either absent or equals @code{FALSE}, this function
10495 returns the position of the leftmost character of @var{STRING} that is
10496 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10497 is returned. If no character of @var{SET} is found in @var{STRING}, the
10498 result is zero.
10499
10500 @item @emph{Standard}:
10501 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10502
10503 @item @emph{Class}:
10504 Elemental function
10505
10506 @item @emph{Syntax}:
10507 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10508
10509 @item @emph{Arguments}:
10510 @multitable @columnfractions .15 .70
10511 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10512 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
10513 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
10514 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
10515 expression indicating the kind parameter of the result.
10516 @end multitable
10517
10518 @item @emph{Return value}:
10519 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10520 @var{KIND} is absent, the return value is of default integer kind.
10521
10522 @item @emph{Example}:
10523 @smallexample
10524 PROGRAM test_scan
10525   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
10526   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
10527   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
10528 END PROGRAM
10529 @end smallexample
10530
10531 @item @emph{See also}:
10532 @ref{INDEX intrinsic}, @ref{VERIFY}
10533 @end table
10534
10535
10536
10537 @node SECNDS
10538 @section @code{SECNDS} --- Time function
10539 @fnindex SECNDS
10540 @cindex time, elapsed
10541 @cindex elapsed time
10542
10543 @table @asis
10544 @item @emph{Description}:
10545 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10546 @var{X} is a reference time, also in seconds. If this is zero, the time in
10547 seconds from midnight is returned. This function is non-standard and its
10548 use is discouraged.
10549
10550 @item @emph{Standard}:
10551 GNU extension
10552
10553 @item @emph{Class}:
10554 Function
10555
10556 @item @emph{Syntax}:
10557 @code{RESULT = SECNDS (X)}
10558
10559 @item @emph{Arguments}:
10560 @multitable @columnfractions .15 .70
10561 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
10562 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
10563 @end multitable
10564
10565 @item @emph{Return value}:
10566 None
10567
10568 @item @emph{Example}:
10569 @smallexample
10570 program test_secnds
10571     integer :: i
10572     real(4) :: t1, t2
10573     print *, secnds (0.0)   ! seconds since midnight
10574     t1 = secnds (0.0)       ! reference time
10575     do i = 1, 10000000      ! do something
10576     end do
10577     t2 = secnds (t1)        ! elapsed time
10578     print *, "Something took ", t2, " seconds."
10579 end program test_secnds
10580 @end smallexample
10581 @end table
10582
10583
10584
10585 @node SECOND
10586 @section @code{SECOND} --- CPU time function
10587 @fnindex SECOND
10588 @cindex time, elapsed
10589 @cindex elapsed time
10590
10591 @table @asis
10592 @item @emph{Description}:
10593 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10594 seconds.  This provides the same functionality as the standard
10595 @code{CPU_TIME} intrinsic, and is only included for backwards
10596 compatibility.
10597
10598 This intrinsic is provided in both subroutine and function forms;
10599 however, only one form can be used in any given program unit.
10600
10601 @item @emph{Standard}:
10602 GNU extension
10603
10604 @item @emph{Class}:
10605 Subroutine, function
10606
10607 @item @emph{Syntax}:
10608 @multitable @columnfractions .80
10609 @item @code{CALL SECOND(TIME)}
10610 @item @code{TIME = SECOND()}
10611 @end multitable
10612
10613 @item @emph{Arguments}:
10614 @multitable @columnfractions .15 .70
10615 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
10616 @end multitable
10617
10618 @item @emph{Return value}:
10619 In either syntax, @var{TIME} is set to the process's current runtime in
10620 seconds.
10621
10622 @item @emph{See also}:
10623 @ref{CPU_TIME}
10624
10625 @end table
10626
10627
10628
10629 @node SELECTED_CHAR_KIND
10630 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10631 @fnindex SELECTED_CHAR_KIND
10632 @cindex character kind
10633 @cindex kind, character
10634
10635 @table @asis
10636 @item @emph{Description}:
10637
10638 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10639 set named @var{NAME}, if a character set with such a name is supported,
10640 or @math{-1} otherwise. Currently, supported character sets include
10641 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10642 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10643
10644 @item @emph{Standard}:
10645 Fortran 2003 and later
10646
10647 @item @emph{Class}:
10648 Transformational function
10649
10650 @item @emph{Syntax}:
10651 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10652
10653 @item @emph{Arguments}:
10654 @multitable @columnfractions .15 .70
10655 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10656 @end multitable
10657
10658 @item @emph{Example}:
10659 @smallexample
10660 program character_kind
10661   use iso_fortran_env
10662   implicit none
10663   integer, parameter :: ascii = selected_char_kind ("ascii")
10664   integer, parameter :: ucs4  = selected_char_kind ('ISO_10646')
10665
10666   character(kind=ascii, len=26) :: alphabet
10667   character(kind=ucs4,  len=30) :: hello_world
10668
10669   alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10670   hello_world = ucs4_'Hello World and Ni Hao -- ' &
10671                 // char (int (z'4F60'), ucs4)     &
10672                 // char (int (z'597D'), ucs4)
10673
10674   write (*,*) alphabet
10675
10676   open (output_unit, encoding='UTF-8')
10677   write (*,*) trim (hello_world)
10678 end program character_kind
10679 @end smallexample
10680 @end table
10681
10682
10683
10684 @node SELECTED_INT_KIND
10685 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10686 @fnindex SELECTED_INT_KIND
10687 @cindex integer kind
10688 @cindex kind, integer
10689
10690 @table @asis
10691 @item @emph{Description}:
10692 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10693 type that can represent all values ranging from @math{-10^R} (exclusive)
10694 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10695 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10696
10697 @item @emph{Standard}:
10698 Fortran 95 and later
10699
10700 @item @emph{Class}:
10701 Transformational function
10702
10703 @item @emph{Syntax}:
10704 @code{RESULT = SELECTED_INT_KIND(R)}
10705
10706 @item @emph{Arguments}:
10707 @multitable @columnfractions .15 .70
10708 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10709 @end multitable
10710
10711 @item @emph{Example}:
10712 @smallexample
10713 program large_integers
10714   integer,parameter :: k5 = selected_int_kind(5)
10715   integer,parameter :: k15 = selected_int_kind(15)
10716   integer(kind=k5) :: i5
10717   integer(kind=k15) :: i15
10718
10719   print *, huge(i5), huge(i15)
10720
10721   ! The following inequalities are always true
10722   print *, huge(i5) >= 10_k5**5-1
10723   print *, huge(i15) >= 10_k15**15-1
10724 end program large_integers
10725 @end smallexample
10726 @end table
10727
10728
10729
10730 @node SELECTED_REAL_KIND
10731 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10732 @fnindex SELECTED_REAL_KIND
10733 @cindex real kind
10734 @cindex kind, real
10735 @cindex radix, real
10736
10737 @table @asis
10738 @item @emph{Description}:
10739 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10740 with decimal precision of at least @code{P} digits, exponent range of
10741 at least @code{R}, and with a radix of @code{RADIX}.
10742
10743 @item @emph{Standard}:
10744 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10745
10746 @item @emph{Class}:
10747 Transformational function
10748
10749 @item @emph{Syntax}:
10750 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10751
10752 @item @emph{Arguments}:
10753 @multitable @columnfractions .15 .70
10754 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10755 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10756 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10757 @end multitable
10758 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10759 be present; since Fortran 2008, they are assumed to be zero if absent.
10760
10761 @item @emph{Return value}:
10762
10763 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10764 a real data type with decimal precision of at least @code{P} digits, a
10765 decimal exponent range of at least @code{R}, and with the requested
10766 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10767 any radix can be returned. If more than one real data type meet the
10768 criteria, the kind of the data type with the smallest decimal precision
10769 is returned. If no real data type matches the criteria, the result is
10770 @table @asis
10771 @item -1 if the processor does not support a real data type with a
10772 precision greater than or equal to @code{P}, but the @code{R} and
10773 @code{RADIX} requirements can be fulfilled
10774 @item -2 if the processor does not support a real type with an exponent
10775 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10776 are fulfillable
10777 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10778 are fulfillable
10779 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10780 are fulfillable
10781 @item -5 if there is no real type with the given @code{RADIX}
10782 @end table
10783
10784 @item @emph{See also}:
10785 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10786
10787 @item @emph{Example}:
10788 @smallexample
10789 program real_kinds
10790   integer,parameter :: p6 = selected_real_kind(6)
10791   integer,parameter :: p10r100 = selected_real_kind(10,100)
10792   integer,parameter :: r400 = selected_real_kind(r=400)
10793   real(kind=p6) :: x
10794   real(kind=p10r100) :: y
10795   real(kind=r400) :: z
10796
10797   print *, precision(x), range(x)
10798   print *, precision(y), range(y)
10799   print *, precision(z), range(z)
10800 end program real_kinds
10801 @end smallexample
10802 @end table
10803
10804
10805
10806 @node SET_EXPONENT
10807 @section @code{SET_EXPONENT} --- Set the exponent of the model
10808 @fnindex SET_EXPONENT
10809 @cindex real number, set exponent
10810 @cindex floating point, set exponent
10811
10812 @table @asis
10813 @item @emph{Description}:
10814 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10815 is that that of @var{X} and whose exponent part is @var{I}.
10816
10817 @item @emph{Standard}:
10818 Fortran 95 and later
10819
10820 @item @emph{Class}:
10821 Elemental function
10822
10823 @item @emph{Syntax}:
10824 @code{RESULT = SET_EXPONENT(X, I)}
10825
10826 @item @emph{Arguments}:
10827 @multitable @columnfractions .15 .70
10828 @item @var{X} @tab Shall be of type @code{REAL}.
10829 @item @var{I} @tab Shall be of type @code{INTEGER}.
10830 @end multitable
10831
10832 @item @emph{Return value}:
10833 The return value is of the same type and kind as @var{X}.
10834 The real number whose fractional part
10835 is that that of @var{X} and whose exponent part if @var{I} is returned;
10836 it is @code{FRACTION(X) * RADIX(X)**I}.
10837
10838 @item @emph{Example}:
10839 @smallexample
10840 PROGRAM test_setexp
10841   REAL :: x = 178.1387e-4
10842   INTEGER :: i = 17
10843   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10844 END PROGRAM
10845 @end smallexample
10846
10847 @end table
10848
10849
10850
10851 @node SHAPE
10852 @section @code{SHAPE} --- Determine the shape of an array
10853 @fnindex SHAPE
10854 @cindex array, shape
10855
10856 @table @asis
10857 @item @emph{Description}:
10858 Determines the shape of an array.
10859
10860 @item @emph{Standard}:
10861 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10862
10863 @item @emph{Class}:
10864 Inquiry function
10865
10866 @item @emph{Syntax}:
10867 @code{RESULT = SHAPE(SOURCE [, KIND])}
10868
10869 @item @emph{Arguments}:
10870 @multitable @columnfractions .15 .70
10871 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
10872 If @var{SOURCE} is a pointer it must be associated and allocatable
10873 arrays must be allocated.
10874 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
10875 expression indicating the kind parameter of the result.
10876 @end multitable
10877
10878 @item @emph{Return value}:
10879 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
10880 has dimensions. The elements of the resulting array correspond to the extend
10881 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
10882 the result is the rank one array of size zero. If @var{KIND} is absent, the
10883 return value has the default integer kind otherwise the specified kind.
10884
10885 @item @emph{Example}:
10886 @smallexample
10887 PROGRAM test_shape
10888   INTEGER, DIMENSION(-1:1, -1:2) :: A
10889   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
10890   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
10891 END PROGRAM
10892 @end smallexample
10893
10894 @item @emph{See also}:
10895 @ref{RESHAPE}, @ref{SIZE}
10896 @end table
10897
10898
10899
10900 @node SHIFTA
10901 @section @code{SHIFTA} --- Right shift with fill
10902 @fnindex SHIFTA
10903 @cindex bits, shift right
10904 @cindex shift, right with fill
10905
10906 @table @asis
10907 @item @emph{Description}:
10908 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
10909 bits shifted right by @var{SHIFT} places.  If the absolute value of
10910 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10911 Bits shifted out from the right end are lost. The fill is arithmetic: the
10912 bits shifted in from the left end are equal to the leftmost bit, which in
10913 two's complement representation is the sign bit.
10914
10915 @item @emph{Standard}:
10916 Fortran 2008 and later
10917
10918 @item @emph{Class}:
10919 Elemental function
10920
10921 @item @emph{Syntax}:
10922 @code{RESULT = SHIFTA(I, SHIFT)}
10923
10924 @item @emph{Arguments}:
10925 @multitable @columnfractions .15 .70
10926 @item @var{I} @tab The type shall be @code{INTEGER}.
10927 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10928 @end multitable
10929
10930 @item @emph{Return value}:
10931 The return value is of type @code{INTEGER} and of the same kind as
10932 @var{I}.
10933
10934 @item @emph{See also}:
10935 @ref{SHIFTL}, @ref{SHIFTR}
10936 @end table
10937
10938
10939
10940 @node SHIFTL
10941 @section @code{SHIFTL} --- Left shift
10942 @fnindex SHIFTL
10943 @cindex bits, shift left
10944 @cindex shift, left
10945
10946 @table @asis
10947 @item @emph{Description}:
10948 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
10949 bits shifted left by @var{SHIFT} places.  If the absolute value of
10950 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10951 Bits shifted out from the left end are lost, and bits shifted in from
10952 the right end are set to 0.
10953
10954 @item @emph{Standard}:
10955 Fortran 2008 and later
10956
10957 @item @emph{Class}:
10958 Elemental function
10959
10960 @item @emph{Syntax}:
10961 @code{RESULT = SHIFTL(I, SHIFT)}
10962
10963 @item @emph{Arguments}:
10964 @multitable @columnfractions .15 .70
10965 @item @var{I} @tab The type shall be @code{INTEGER}.
10966 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10967 @end multitable
10968
10969 @item @emph{Return value}:
10970 The return value is of type @code{INTEGER} and of the same kind as
10971 @var{I}.
10972
10973 @item @emph{See also}:
10974 @ref{SHIFTA}, @ref{SHIFTR}
10975 @end table
10976
10977
10978
10979 @node SHIFTR
10980 @section @code{SHIFTR} --- Right shift
10981 @fnindex SHIFTR
10982 @cindex bits, shift right
10983 @cindex shift, right
10984
10985 @table @asis
10986 @item @emph{Description}:
10987 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
10988 bits shifted right by @var{SHIFT} places.  If the absolute value of
10989 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10990 Bits shifted out from the right end are lost, and bits shifted in from
10991 the left end are set to 0.
10992
10993 @item @emph{Standard}:
10994 Fortran 2008 and later
10995
10996 @item @emph{Class}:
10997 Elemental function
10998
10999 @item @emph{Syntax}:
11000 @code{RESULT = SHIFTR(I, SHIFT)}
11001
11002 @item @emph{Arguments}:
11003 @multitable @columnfractions .15 .70
11004 @item @var{I} @tab The type shall be @code{INTEGER}.
11005 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11006 @end multitable
11007
11008 @item @emph{Return value}:
11009 The return value is of type @code{INTEGER} and of the same kind as
11010 @var{I}.
11011
11012 @item @emph{See also}:
11013 @ref{SHIFTA}, @ref{SHIFTL}
11014 @end table
11015
11016
11017
11018 @node SIGN
11019 @section @code{SIGN} --- Sign copying function
11020 @fnindex SIGN
11021 @fnindex ISIGN
11022 @fnindex DSIGN
11023 @cindex sign copying
11024
11025 @table @asis
11026 @item @emph{Description}:
11027 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11028
11029 @item @emph{Standard}:
11030 Fortran 77 and later
11031
11032 @item @emph{Class}:
11033 Elemental function
11034
11035 @item @emph{Syntax}:
11036 @code{RESULT = SIGN(A, B)}
11037
11038 @item @emph{Arguments}:
11039 @multitable @columnfractions .15 .70
11040 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11041 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11042 @end multitable
11043
11044 @item @emph{Return value}:
11045 The kind of the return value is that of @var{A} and @var{B}.
11046 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11047 it is @code{-ABS(A)}.
11048
11049 @item @emph{Example}:
11050 @smallexample
11051 program test_sign
11052   print *, sign(-12,1)
11053   print *, sign(-12,0)
11054   print *, sign(-12,-1)
11055
11056   print *, sign(-12.,1.)
11057   print *, sign(-12.,0.)
11058   print *, sign(-12.,-1.)
11059 end program test_sign
11060 @end smallexample
11061
11062 @item @emph{Specific names}:
11063 @multitable @columnfractions .20 .20 .20 .25
11064 @item Name              @tab Arguments              @tab Return type       @tab Standard
11065 @item @code{SIGN(A,B)}  @tab @code{REAL(4) A, B}    @tab @code{REAL(4)}    @tab f77, gnu
11066 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11067 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B}    @tab @code{REAL(8)}    @tab f77, gnu
11068 @end multitable
11069 @end table
11070
11071
11072
11073 @node SIGNAL
11074 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11075 @fnindex SIGNAL
11076 @cindex system, signal handling
11077
11078 @table @asis
11079 @item @emph{Description}:
11080 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11081 @var{HANDLER} to be executed with a single integer argument when signal
11082 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
11083 turn off handling of signal @var{NUMBER} or revert to its default
11084 action.  See @code{signal(2)}.
11085
11086 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11087 is supplied, it is set to the value returned by @code{signal(2)}.
11088
11089 @item @emph{Standard}:
11090 GNU extension
11091
11092 @item @emph{Class}:
11093 Subroutine, function
11094
11095 @item @emph{Syntax}:
11096 @multitable @columnfractions .80
11097 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11098 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11099 @end multitable
11100
11101 @item @emph{Arguments}:
11102 @multitable @columnfractions .15 .70
11103 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11104 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11105 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11106 @code{INTEGER}. It is @code{INTENT(IN)}.
11107 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11108 integer. It has @code{INTENT(OUT)}.
11109 @end multitable
11110 @c TODO: What should the interface of the handler be?  Does it take arguments?
11111
11112 @item @emph{Return value}:
11113 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11114
11115 @item @emph{Example}:
11116 @smallexample
11117 program test_signal
11118   intrinsic signal
11119   external handler_print
11120
11121   call signal (12, handler_print)
11122   call signal (10, 1)
11123
11124   call sleep (30)
11125 end program test_signal
11126 @end smallexample
11127 @end table
11128
11129
11130
11131 @node SIN
11132 @section @code{SIN} --- Sine function
11133 @fnindex SIN
11134 @fnindex DSIN
11135 @fnindex CSIN
11136 @fnindex ZSIN
11137 @fnindex CDSIN
11138 @cindex trigonometric function, sine
11139 @cindex sine
11140
11141 @table @asis
11142 @item @emph{Description}:
11143 @code{SIN(X)} computes the sine of @var{X}.
11144
11145 @item @emph{Standard}:
11146 Fortran 77 and later
11147
11148 @item @emph{Class}:
11149 Elemental function
11150
11151 @item @emph{Syntax}:
11152 @code{RESULT = SIN(X)}
11153
11154 @item @emph{Arguments}:
11155 @multitable @columnfractions .15 .70
11156 @item @var{X} @tab The type shall be @code{REAL} or
11157 @code{COMPLEX}.
11158 @end multitable
11159
11160 @item @emph{Return value}:
11161 The return value has same type and kind as @var{X}.
11162
11163 @item @emph{Example}:
11164 @smallexample
11165 program test_sin
11166   real :: x = 0.0
11167   x = sin(x)
11168 end program test_sin
11169 @end smallexample
11170
11171 @item @emph{Specific names}:
11172 @multitable @columnfractions .20 .20 .20 .25
11173 @item Name            @tab Argument             @tab Return type       @tab Standard
11174 @item @code{SIN(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}    @tab f77, gnu
11175 @item @code{DSIN(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}    @tab f95, gnu
11176 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)} @tab f95, gnu
11177 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11178 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11179 @end multitable
11180
11181 @item @emph{See also}:
11182 @ref{ASIN}
11183 @end table
11184
11185
11186
11187 @node SINH
11188 @section @code{SINH} --- Hyperbolic sine function
11189 @fnindex SINH
11190 @fnindex DSINH
11191 @cindex hyperbolic sine
11192 @cindex hyperbolic function, sine
11193 @cindex sine, hyperbolic
11194
11195 @table @asis
11196 @item @emph{Description}:
11197 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11198
11199 @item @emph{Standard}:
11200 Fortran 95 and later, for a complex argument Fortran 2008 or later
11201
11202 @item @emph{Class}:
11203 Elemental function
11204
11205 @item @emph{Syntax}:
11206 @code{RESULT = SINH(X)}
11207
11208 @item @emph{Arguments}:
11209 @multitable @columnfractions .15 .70
11210 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11211 @end multitable
11212
11213 @item @emph{Return value}:
11214 The return value has same type and kind as @var{X}.
11215
11216 @item @emph{Example}:
11217 @smallexample
11218 program test_sinh
11219   real(8) :: x = - 1.0_8
11220   x = sinh(x)
11221 end program test_sinh
11222 @end smallexample
11223
11224 @item @emph{Specific names}:
11225 @multitable @columnfractions .20 .20 .20 .25
11226 @item Name            @tab Argument          @tab Return type       @tab Standard
11227 @item @code{SINH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
11228 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
11229 @end multitable
11230
11231 @item @emph{See also}:
11232 @ref{ASINH}
11233 @end table
11234
11235
11236
11237 @node SIZE
11238 @section @code{SIZE} --- Determine the size of an array
11239 @fnindex SIZE
11240 @cindex array, size
11241 @cindex array, number of elements
11242 @cindex array, count elements
11243
11244 @table @asis
11245 @item @emph{Description}:
11246 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11247 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11248
11249 @item @emph{Standard}:
11250 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11251
11252 @item @emph{Class}:
11253 Inquiry function
11254
11255 @item @emph{Syntax}:
11256 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11257
11258 @item @emph{Arguments}:
11259 @multitable @columnfractions .15 .70
11260 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11261 a pointer it must be associated and allocatable arrays must be allocated.
11262 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
11263 and its value shall be in the range from 1 to n, where n equals the rank
11264 of @var{ARRAY}.
11265 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11266 expression indicating the kind parameter of the result.
11267 @end multitable
11268
11269 @item @emph{Return value}:
11270 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11271 @var{KIND} is absent, the return value is of default integer kind.
11272
11273 @item @emph{Example}:
11274 @smallexample
11275 PROGRAM test_size
11276   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
11277 END PROGRAM
11278 @end smallexample
11279
11280 @item @emph{See also}:
11281 @ref{SHAPE}, @ref{RESHAPE}
11282 @end table
11283
11284
11285 @node SIZEOF
11286 @section @code{SIZEOF} --- Size in bytes of an expression
11287 @fnindex SIZEOF
11288 @cindex expression size
11289 @cindex size of an expression
11290
11291 @table @asis
11292 @item @emph{Description}:
11293 @code{SIZEOF(X)} calculates the number of bytes of storage the
11294 expression @code{X} occupies.
11295
11296 @item @emph{Standard}:
11297 GNU extension
11298
11299 @item @emph{Class}:
11300 Intrinsic function
11301
11302 @item @emph{Syntax}:
11303 @code{N = SIZEOF(X)}
11304
11305 @item @emph{Arguments}:
11306 @multitable @columnfractions .15 .70
11307 @item @var{X} @tab The argument shall be of any type, rank or shape.
11308 @end multitable
11309
11310 @item @emph{Return value}:
11311 The return value is of type integer and of the system-dependent kind
11312 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11313 number of bytes occupied by the argument.  If the argument has the
11314 @code{POINTER} attribute, the number of bytes of the storage area pointed
11315 to is returned.  If the argument is of a derived type with @code{POINTER}
11316 or @code{ALLOCATABLE} components, the return value doesn't account for
11317 the sizes of the data pointed to by these components. If the argument is
11318 polymorphic, the size according to the declared type is returned.
11319
11320 @item @emph{Example}:
11321 @smallexample
11322    integer :: i
11323    real :: r, s(5)
11324    print *, (sizeof(s)/sizeof(r) == 5)
11325    end
11326 @end smallexample
11327 The example will print @code{.TRUE.} unless you are using a platform
11328 where default @code{REAL} variables are unusually padded.
11329
11330 @item @emph{See also}:
11331 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11332 @end table
11333
11334
11335 @node SLEEP
11336 @section @code{SLEEP} --- Sleep for the specified number of seconds
11337 @fnindex SLEEP
11338 @cindex delayed execution
11339
11340 @table @asis
11341 @item @emph{Description}:
11342 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11343
11344 @item @emph{Standard}:
11345 GNU extension
11346
11347 @item @emph{Class}:
11348 Subroutine
11349
11350 @item @emph{Syntax}:
11351 @code{CALL SLEEP(SECONDS)}
11352
11353 @item @emph{Arguments}:
11354 @multitable @columnfractions .15 .70
11355 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11356 @end multitable
11357
11358 @item @emph{Example}:
11359 @smallexample
11360 program test_sleep
11361   call sleep(5)
11362 end
11363 @end smallexample
11364 @end table
11365
11366
11367
11368 @node SPACING
11369 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11370 @fnindex SPACING
11371 @cindex real number, relative spacing
11372 @cindex floating point, relative spacing
11373
11374 @table @asis
11375 @item @emph{Description}:
11376 Determines the distance between the argument @var{X} and the nearest
11377 adjacent number of the same type.
11378
11379 @item @emph{Standard}:
11380 Fortran 95 and later
11381
11382 @item @emph{Class}:
11383 Elemental function
11384
11385 @item @emph{Syntax}:
11386 @code{RESULT = SPACING(X)}
11387
11388 @item @emph{Arguments}:
11389 @multitable @columnfractions .15 .70
11390 @item @var{X} @tab Shall be of type @code{REAL}.
11391 @end multitable
11392
11393 @item @emph{Return value}:
11394 The result is of the same type as the input argument @var{X}.
11395
11396 @item @emph{Example}:
11397 @smallexample
11398 PROGRAM test_spacing
11399   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11400   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11401
11402   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
11403   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
11404 END PROGRAM
11405 @end smallexample
11406
11407 @item @emph{See also}:
11408 @ref{RRSPACING}
11409 @end table
11410
11411
11412
11413 @node SPREAD
11414 @section @code{SPREAD} --- Add a dimension to an array
11415 @fnindex SPREAD
11416 @cindex array, increase dimension
11417 @cindex array, duplicate elements
11418 @cindex array, duplicate dimensions
11419
11420 @table @asis
11421 @item @emph{Description}:
11422 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11423 dimension @var{DIM}.
11424
11425 @item @emph{Standard}:
11426 Fortran 95 and later
11427
11428 @item @emph{Class}:
11429 Transformational function
11430
11431 @item @emph{Syntax}:
11432 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11433
11434 @item @emph{Arguments}:
11435 @multitable @columnfractions .15 .70
11436 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
11437 a rank less than seven.
11438 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
11439 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11440 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11441 @end multitable
11442
11443 @item @emph{Return value}:
11444 The result is an array of the same type as @var{SOURCE} and has rank n+1
11445 where n equals the rank of @var{SOURCE}.
11446
11447 @item @emph{Example}:
11448 @smallexample
11449 PROGRAM test_spread
11450   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11451   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
11452   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
11453 END PROGRAM
11454 @end smallexample
11455
11456 @item @emph{See also}:
11457 @ref{UNPACK}
11458 @end table
11459
11460
11461
11462 @node SQRT
11463 @section @code{SQRT} --- Square-root function
11464 @fnindex SQRT
11465 @fnindex DSQRT
11466 @fnindex CSQRT
11467 @fnindex ZSQRT
11468 @fnindex CDSQRT
11469 @cindex root
11470 @cindex square-root
11471
11472 @table @asis
11473 @item @emph{Description}:
11474 @code{SQRT(X)} computes the square root of @var{X}.
11475
11476 @item @emph{Standard}:
11477 Fortran 77 and later
11478
11479 @item @emph{Class}:
11480 Elemental function
11481
11482 @item @emph{Syntax}:
11483 @code{RESULT = SQRT(X)}
11484
11485 @item @emph{Arguments}:
11486 @multitable @columnfractions .15 .70
11487 @item @var{X} @tab The type shall be @code{REAL} or
11488 @code{COMPLEX}.
11489 @end multitable
11490
11491 @item @emph{Return value}:
11492 The return value is of type @code{REAL} or @code{COMPLEX}.
11493 The kind type parameter is the same as @var{X}.
11494
11495 @item @emph{Example}:
11496 @smallexample
11497 program test_sqrt
11498   real(8) :: x = 2.0_8
11499   complex :: z = (1.0, 2.0)
11500   x = sqrt(x)
11501   z = sqrt(z)
11502 end program test_sqrt
11503 @end smallexample
11504
11505 @item @emph{Specific names}:
11506 @multitable @columnfractions .20 .20 .20 .25
11507 @item Name             @tab Argument             @tab Return type          @tab Standard
11508 @item @code{SQRT(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}       @tab Fortran 95 and later
11509 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
11510 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
11511 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11512 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11513 @end multitable
11514 @end table
11515
11516
11517
11518 @node SRAND
11519 @section @code{SRAND} --- Reinitialize the random number generator
11520 @fnindex SRAND
11521 @cindex random number generation, seeding
11522 @cindex seeding a random number generator
11523
11524 @table @asis
11525 @item @emph{Description}:
11526 @code{SRAND} reinitializes the pseudo-random number generator
11527 called by @code{RAND} and @code{IRAND}. The new seed used by the
11528 generator is specified by the required argument @var{SEED}.
11529
11530 @item @emph{Standard}:
11531 GNU extension
11532
11533 @item @emph{Class}:
11534 Subroutine
11535
11536 @item @emph{Syntax}:
11537 @code{CALL SRAND(SEED)}
11538
11539 @item @emph{Arguments}:
11540 @multitable @columnfractions .15 .70
11541 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11542 @end multitable
11543
11544 @item @emph{Return value}:
11545 Does not return anything.
11546
11547 @item @emph{Example}:
11548 See @code{RAND} and @code{IRAND} for examples.
11549
11550 @item @emph{Notes}:
11551 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11552 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11553 to generate pseudo-random numbers. Please note that in
11554 GNU Fortran, these two sets of intrinsics (@code{RAND},
11555 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11556 @code{RANDOM_SEED} on the other hand) access two independent
11557 pseudo-random number generators.
11558
11559 @item @emph{See also}:
11560 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11561
11562 @end table
11563
11564
11565
11566 @node STAT
11567 @section @code{STAT} --- Get file status
11568 @fnindex STAT
11569 @cindex file system, file status
11570
11571 @table @asis
11572 @item @emph{Description}:
11573 This function returns information about a file. No permissions are required on
11574 the file itself, but execute (search) permission is required on all of the
11575 directories in path that lead to the file.
11576
11577 The elements that are obtained and stored in the array @code{VALUES}:
11578 @multitable @columnfractions .15 .70
11579 @item @code{VALUES(1)}   @tab  Device ID
11580 @item @code{VALUES(2)}   @tab  Inode number
11581 @item @code{VALUES(3)}   @tab  File mode
11582 @item @code{VALUES(4)}   @tab  Number of links
11583 @item @code{VALUES(5)}   @tab  Owner's uid
11584 @item @code{VALUES(6)}   @tab  Owner's gid
11585 @item @code{VALUES(7)}   @tab  ID of device containing directory entry for file (0 if not available)
11586 @item @code{VALUES(8)}   @tab  File size (bytes)
11587 @item @code{VALUES(9)}   @tab  Last access time
11588 @item @code{VALUES(10)}  @tab  Last modification time
11589 @item @code{VALUES(11)}  @tab  Last file status change time
11590 @item @code{VALUES(12)}  @tab  Preferred I/O block size (-1 if not available)
11591 @item @code{VALUES(13)}  @tab  Number of blocks allocated (-1 if not available)
11592 @end multitable
11593
11594 Not all these elements are relevant on all systems.
11595 If an element is not relevant, it is returned as 0.
11596
11597 This intrinsic is provided in both subroutine and function forms; however,
11598 only one form can be used in any given program unit.
11599
11600 @item @emph{Standard}:
11601 GNU extension
11602
11603 @item @emph{Class}:
11604 Subroutine, function
11605
11606 @item @emph{Syntax}:
11607 @multitable @columnfractions .80
11608 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11609 @item @code{STATUS = STAT(NAME, VALUES)}
11610 @end multitable
11611
11612 @item @emph{Arguments}:
11613 @multitable @columnfractions .15 .70
11614 @item @var{NAME}   @tab The type shall be @code{CHARACTER}, of the
11615 default kind and a valid path within the file system.
11616 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11617 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11618 on success and a system specific error code otherwise.
11619 @end multitable
11620
11621 @item @emph{Example}:
11622 @smallexample
11623 PROGRAM test_stat
11624   INTEGER, DIMENSION(13) :: buff
11625   INTEGER :: status
11626
11627   CALL STAT("/etc/passwd", buff, status)
11628
11629   IF (status == 0) THEN
11630     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
11631     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
11632     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
11633     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
11634     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
11635     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
11636     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
11637     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
11638     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
11639     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
11640     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11641     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
11642     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11643   END IF
11644 END PROGRAM
11645 @end smallexample
11646
11647 @item @emph{See also}:
11648 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11649 @end table
11650
11651
11652
11653 @node STORAGE_SIZE
11654 @section @code{STORAGE_SIZE} --- Storage size in bits
11655 @fnindex STORAGE_SIZE
11656 @cindex storage size
11657
11658 @table @asis
11659 @item @emph{Description}:
11660 Returns the storage size of argument @var{A} in bits.
11661 @item @emph{Standard}:
11662 Fortran 2008 and later
11663 @item @emph{Class}:
11664 Inquiry function
11665 @item @emph{Syntax}:
11666 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11667
11668 @item @emph{Arguments}:
11669 @multitable @columnfractions .15 .70
11670 @item @var{A} @tab Shall be a scalar or array of any type.
11671 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11672 @end multitable
11673
11674 @item @emph{Return Value}:
11675 The result is a scalar integer with the kind type parameter speciﬁed by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that
11676 has the dynamic type and type parameters of A.
11677
11678 @item @emph{See also}:
11679 @ref{C_SIZEOF}, @ref{SIZEOF}
11680 @end table
11681
11682
11683
11684 @node SUM
11685 @section @code{SUM} --- Sum of array elements
11686 @fnindex SUM
11687 @cindex array, sum
11688 @cindex array, add elements
11689 @cindex array, conditionally add elements
11690 @cindex sum array elements
11691
11692 @table @asis
11693 @item @emph{Description}:
11694 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11695 the corresponding element in @var{MASK} is @code{TRUE}.
11696
11697 @item @emph{Standard}:
11698 Fortran 95 and later
11699
11700 @item @emph{Class}:
11701 Transformational function
11702
11703 @item @emph{Syntax}:
11704 @multitable @columnfractions .80
11705 @item @code{RESULT = SUM(ARRAY[, MASK])}
11706 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11707 @end multitable
11708
11709 @item @emph{Arguments}:
11710 @multitable @columnfractions .15 .70
11711 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11712 @code{REAL} or @code{COMPLEX}.
11713 @item @var{DIM}   @tab (Optional) shall be a scalar of type
11714 @code{INTEGER} with a value in the range from 1 to n, where n
11715 equals the rank of @var{ARRAY}.
11716 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
11717 and either be a scalar or an array of the same shape as @var{ARRAY}.
11718 @end multitable
11719
11720 @item @emph{Return value}:
11721 The result is of the same type as @var{ARRAY}.
11722
11723 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11724 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11725 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11726 dropped is returned.
11727
11728 @item @emph{Example}:
11729 @smallexample
11730 PROGRAM test_sum
11731   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11732   print *, SUM(x)                        ! all elements, sum = 15
11733   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
11734 END PROGRAM
11735 @end smallexample
11736
11737 @item @emph{See also}:
11738 @ref{PRODUCT}
11739 @end table
11740
11741
11742
11743 @node SYMLNK
11744 @section @code{SYMLNK} --- Create a symbolic link
11745 @fnindex SYMLNK
11746 @cindex file system, create link
11747 @cindex file system, soft link
11748
11749 @table @asis
11750 @item @emph{Description}:
11751 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11752 character (@code{CHAR(0)}) can be used to mark the end of the names in
11753 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11754 names are ignored.  If the @var{STATUS} argument is supplied, it
11755 contains 0 on success or a nonzero error code upon return; see
11756 @code{symlink(2)}.  If the system does not supply @code{symlink(2)},
11757 @code{ENOSYS} is returned.
11758
11759 This intrinsic is provided in both subroutine and function forms;
11760 however, only one form can be used in any given program unit.
11761
11762 @item @emph{Standard}:
11763 GNU extension
11764
11765 @item @emph{Class}:
11766 Subroutine, function
11767
11768 @item @emph{Syntax}:
11769 @multitable @columnfractions .80
11770 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11771 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11772 @end multitable
11773
11774 @item @emph{Arguments}:
11775 @multitable @columnfractions .15 .70
11776 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11777 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11778 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11779 @end multitable
11780
11781 @item @emph{See also}:
11782 @ref{LINK}, @ref{UNLINK}
11783
11784 @end table
11785
11786
11787
11788 @node SYSTEM
11789 @section @code{SYSTEM} --- Execute a shell command
11790 @fnindex SYSTEM
11791 @cindex system, system call
11792
11793 @table @asis
11794 @item @emph{Description}:
11795 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11796 argument @var{STATUS} is present, it contains the value returned by
11797 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11798 Note that which shell is used to invoke the command is system-dependent
11799 and environment-dependent.
11800
11801 This intrinsic is provided in both subroutine and function forms;
11802 however, only one form can be used in any given program unit.
11803
11804 Note that the @code{system} function need not be thread-safe. It is
11805 the responsibility of the user to ensure that @code{system} is not
11806 called concurrently.
11807
11808 @item @emph{Standard}:
11809 GNU extension
11810
11811 @item @emph{Class}:
11812 Subroutine, function
11813
11814 @item @emph{Syntax}:
11815 @multitable @columnfractions .80
11816 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11817 @item @code{STATUS = SYSTEM(COMMAND)}
11818 @end multitable
11819
11820 @item @emph{Arguments}:
11821 @multitable @columnfractions .15 .70
11822 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11823 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
11824 @end multitable
11825
11826 @item @emph{See also}:
11827 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11828 and should considered in new code for future portability.
11829 @end table
11830
11831
11832
11833 @node SYSTEM_CLOCK
11834 @section @code{SYSTEM_CLOCK} --- Time function
11835 @fnindex SYSTEM_CLOCK
11836 @cindex time, clock ticks
11837 @cindex clock ticks
11838
11839 @table @asis
11840 @item @emph{Description}:
11841 Determines the @var{COUNT} of a processor clock since an unspecified
11842 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
11843 the number of clock ticks per second.  If the platform supports a high
11844 resolution monotonic clock, that clock is used and can provide up to
11845 nanosecond resolution.  If a high resolution monotonic clock is not
11846 available, the implementation falls back to a potentially lower
11847 resolution realtime clock.
11848
11849 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
11850 arguments.  For @var{kind=8} arguments, @var{COUNT} represents
11851 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
11852 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
11853 @var{COUNT_MAX} are constant, however the particular values are
11854 specific to @command{gfortran}.
11855
11856 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
11857 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
11858
11859 When running on a platform using the GNU C library (glibc), or a
11860 derivative thereof, the high resolution monotonic clock is available
11861 only when linking with the @var{rt} library.  This can be done
11862 explicitly by adding the @code{-lrt} flag when linking the
11863 application, but is also done implicitly when using OpenMP.
11864
11865 @item @emph{Standard}:
11866 Fortran 95 and later
11867
11868 @item @emph{Class}:
11869 Subroutine
11870
11871 @item @emph{Syntax}:
11872 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
11873
11874 @item @emph{Arguments}:
11875 @multitable @columnfractions .15 .70
11876 @item @var{COUNT}      @tab (Optional) shall be a scalar of type
11877 @code{INTEGER} with @code{INTENT(OUT)}.
11878 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
11879 @code{INTEGER} with @code{INTENT(OUT)}.
11880 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type
11881 @code{INTEGER} with @code{INTENT(OUT)}.
11882 @end multitable
11883
11884 @item @emph{Example}:
11885 @smallexample
11886 PROGRAM test_system_clock
11887   INTEGER :: count, count_rate, count_max
11888   CALL SYSTEM_CLOCK(count, count_rate, count_max)
11889   WRITE(*,*) count, count_rate, count_max
11890 END PROGRAM
11891 @end smallexample
11892
11893 @item @emph{See also}:
11894 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
11895 @end table
11896
11897
11898
11899 @node TAN
11900 @section @code{TAN} --- Tangent function
11901 @fnindex TAN
11902 @fnindex DTAN
11903 @cindex trigonometric function, tangent
11904 @cindex tangent
11905
11906 @table @asis
11907 @item @emph{Description}:
11908 @code{TAN(X)} computes the tangent of @var{X}.
11909
11910 @item @emph{Standard}:
11911 Fortran 77 and later, for a complex argument Fortran 2008 or later
11912
11913 @item @emph{Class}:
11914 Elemental function
11915
11916 @item @emph{Syntax}:
11917 @code{RESULT = TAN(X)}
11918
11919 @item @emph{Arguments}:
11920 @multitable @columnfractions .15 .70
11921 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11922 @end multitable
11923
11924 @item @emph{Return value}:
11925 The return value has same type and kind as @var{X}.
11926
11927 @item @emph{Example}:
11928 @smallexample
11929 program test_tan
11930   real(8) :: x = 0.165_8
11931   x = tan(x)
11932 end program test_tan
11933 @end smallexample
11934
11935 @item @emph{Specific names}:
11936 @multitable @columnfractions .20 .20 .20 .25
11937 @item Name            @tab Argument          @tab Return type     @tab Standard
11938 @item @code{TAN(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab Fortran 95 and later
11939 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab Fortran 95 and later
11940 @end multitable
11941
11942 @item @emph{See also}:
11943 @ref{ATAN}
11944 @end table
11945
11946
11947
11948 @node TANH
11949 @section @code{TANH} --- Hyperbolic tangent function
11950 @fnindex TANH
11951 @fnindex DTANH
11952 @cindex hyperbolic tangent
11953 @cindex hyperbolic function, tangent
11954 @cindex tangent, hyperbolic
11955
11956 @table @asis
11957 @item @emph{Description}:
11958 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
11959
11960 @item @emph{Standard}:
11961 Fortran 77 and later, for a complex argument Fortran 2008 or later
11962
11963 @item @emph{Class}:
11964 Elemental function
11965
11966 @item @emph{Syntax}:
11967 @code{X = TANH(X)}
11968
11969 @item @emph{Arguments}:
11970 @multitable @columnfractions .15 .70
11971 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11972 @end multitable
11973
11974 @item @emph{Return value}:
11975 The return value has same type and kind as @var{X}. If @var{X} is
11976 complex, the imaginary part of the result is in radians. If @var{X}
11977 is @code{REAL}, the return value lies in the range
11978 @math{ - 1 \leq tanh(x) \leq 1 }.
11979
11980 @item @emph{Example}:
11981 @smallexample
11982 program test_tanh
11983   real(8) :: x = 2.1_8
11984   x = tanh(x)
11985 end program test_tanh
11986 @end smallexample
11987
11988 @item @emph{Specific names}:
11989 @multitable @columnfractions .20 .20 .20 .25
11990 @item Name            @tab Argument          @tab Return type       @tab Standard
11991 @item @code{TANH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
11992 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
11993 @end multitable
11994
11995 @item @emph{See also}:
11996 @ref{ATANH}
11997 @end table
11998
11999
12000
12001 @node THIS_IMAGE
12002 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12003 @fnindex THIS_IMAGE
12004 @cindex coarray, @code{THIS_IMAGE}
12005 @cindex images, index of this image
12006
12007 @table @asis
12008 @item @emph{Description}:
12009 Returns the cosubscript for this image.
12010
12011 @item @emph{Standard}:
12012 Fortran 2008 and later
12013
12014 @item @emph{Class}:
12015 Transformational function
12016
12017 @item @emph{Syntax}:
12018 @multitable @columnfractions .80
12019 @item @code{RESULT = THIS_IMAGE()}
12020 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12021 @end multitable
12022
12023 @item @emph{Arguments}:
12024 @multitable @columnfractions .15 .70
12025 @item @var{COARRAY} @tab Coarray of any type  (optional; if @var{DIM}
12026 present, required).
12027 @item @var{DIM}     @tab default integer scalar (optional). If present,
12028 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12029 @end multitable
12030
12031
12032 @item @emph{Return value}:
12033 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12034 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12035 a rank-1 array with corank elements is returned, containing the cosubscripts
12036 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12037 a scalar is returned, with the value of the @var{DIM} element of
12038 @code{THIS_IMAGE(COARRAY)}.
12039
12040 @item @emph{Example}:
12041 @smallexample
12042 INTEGER :: value[*]
12043 INTEGER :: i
12044 value = THIS_IMAGE()
12045 SYNC ALL
12046 IF (THIS_IMAGE() == 1) THEN
12047   DO i = 1, NUM_IMAGES()
12048     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12049   END DO
12050 END IF
12051 @end smallexample
12052
12053 @item @emph{See also}:
12054 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12055 @end table
12056
12057
12058
12059 @node TIME
12060 @section @code{TIME} --- Time function
12061 @fnindex TIME
12062 @cindex time, current
12063 @cindex current time
12064
12065 @table @asis
12066 @item @emph{Description}:
12067 Returns the current time encoded as an integer (in the manner of the
12068 UNIX function @code{time(3)}). This value is suitable for passing to
12069 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12070
12071 This intrinsic is not fully portable, such as to systems with 32-bit
12072 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12073 the values returned by this intrinsic might be, or become, negative, or
12074 numerically less than previous values, during a single run of the
12075 compiled program.
12076
12077 See @ref{TIME8}, for information on a similar intrinsic that might be
12078 portable to more GNU Fortran implementations, though to fewer Fortran
12079 compilers.
12080
12081 @item @emph{Standard}:
12082 GNU extension
12083
12084 @item @emph{Class}:
12085 Function
12086
12087 @item @emph{Syntax}:
12088 @code{RESULT = TIME()}
12089
12090 @item @emph{Return value}:
12091 The return value is a scalar of type @code{INTEGER(4)}.
12092
12093 @item @emph{See also}:
12094 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12095
12096 @end table
12097
12098
12099
12100 @node TIME8
12101 @section @code{TIME8} --- Time function (64-bit)
12102 @fnindex TIME8
12103 @cindex time, current
12104 @cindex current time
12105
12106 @table @asis
12107 @item @emph{Description}:
12108 Returns the current time encoded as an integer (in the manner of the
12109 UNIX function @code{time(3)}). This value is suitable for passing to
12110 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12111
12112 @emph{Warning:} this intrinsic does not increase the range of the timing
12113 values over that returned by @code{time(3)}. On a system with a 32-bit
12114 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12115 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12116 overflows of the 32-bit value can still occur. Therefore, the values
12117 returned by this intrinsic might be or become negative or numerically
12118 less than previous values during a single run of the compiled program.
12119
12120 @item @emph{Standard}:
12121 GNU extension
12122
12123 @item @emph{Class}:
12124 Function
12125
12126 @item @emph{Syntax}:
12127 @code{RESULT = TIME8()}
12128
12129 @item @emph{Return value}:
12130 The return value is a scalar of type @code{INTEGER(8)}.
12131
12132 @item @emph{See also}:
12133 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12134
12135 @end table
12136
12137
12138
12139 @node TINY
12140 @section @code{TINY} --- Smallest positive number of a real kind
12141 @fnindex TINY
12142 @cindex limits, smallest number
12143 @cindex model representation, smallest number
12144
12145 @table @asis
12146 @item @emph{Description}:
12147 @code{TINY(X)} returns the smallest positive (non zero) number
12148 in the model of the type of @code{X}.
12149
12150 @item @emph{Standard}:
12151 Fortran 95 and later
12152
12153 @item @emph{Class}:
12154 Inquiry function
12155
12156 @item @emph{Syntax}:
12157 @code{RESULT = TINY(X)}
12158
12159 @item @emph{Arguments}:
12160 @multitable @columnfractions .15 .70
12161 @item @var{X} @tab Shall be of type @code{REAL}.
12162 @end multitable
12163
12164 @item @emph{Return value}:
12165 The return value is of the same type and kind as @var{X}
12166
12167 @item @emph{Example}:
12168 See @code{HUGE} for an example.
12169 @end table
12170
12171
12172
12173 @node TRAILZ
12174 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12175 @fnindex TRAILZ
12176 @cindex zero bits
12177
12178 @table @asis
12179 @item @emph{Description}:
12180 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12181
12182 @item @emph{Standard}:
12183 Fortran 2008 and later
12184
12185 @item @emph{Class}:
12186 Elemental function
12187
12188 @item @emph{Syntax}:
12189 @code{RESULT = TRAILZ(I)}
12190
12191 @item @emph{Arguments}:
12192 @multitable @columnfractions .15 .70
12193 @item @var{I} @tab Shall be of type @code{INTEGER}.
12194 @end multitable
12195
12196 @item @emph{Return value}:
12197 The type of the return value is the default @code{INTEGER}.
12198 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12199
12200 @item @emph{Example}:
12201 @smallexample
12202 PROGRAM test_trailz
12203   WRITE (*,*) TRAILZ(8)  ! prints 3
12204 END PROGRAM
12205 @end smallexample
12206
12207 @item @emph{See also}:
12208 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12209 @end table
12210
12211
12212
12213 @node TRANSFER
12214 @section @code{TRANSFER} --- Transfer bit patterns
12215 @fnindex TRANSFER
12216 @cindex bits, move
12217 @cindex type cast
12218
12219 @table @asis
12220 @item @emph{Description}:
12221 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12222 is the representation of a variable or array of the same type and type
12223 parameters as @var{MOLD}.
12224
12225 This is approximately equivalent to the C concept of @emph{casting} one
12226 type to another.
12227
12228 @item @emph{Standard}:
12229 Fortran 95 and later
12230
12231 @item @emph{Class}:
12232 Transformational function
12233
12234 @item @emph{Syntax}:
12235 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12236
12237 @item @emph{Arguments}:
12238 @multitable @columnfractions .15 .70
12239 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12240 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
12241 @item @var{SIZE}   @tab (Optional) shall be a scalar of type
12242 @code{INTEGER}.
12243 @end multitable
12244
12245 @item @emph{Return value}:
12246 The result has the same type as @var{MOLD}, with the bit level
12247 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
12248 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
12249 but @var{MOLD} is an array (of any size or shape), the result is a one-
12250 dimensional array of the minimum length needed to contain the entirety
12251 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
12252 and @var{MOLD} is a scalar, the result is a scalar.
12253
12254 If the bitwise representation of the result is longer than that of
12255 @var{SOURCE}, then the leading bits of the result correspond to those of
12256 @var{SOURCE} and any trailing bits are filled arbitrarily.
12257
12258 When the resulting bit representation does not correspond to a valid
12259 representation of a variable of the same type as @var{MOLD}, the results
12260 are undefined, and subsequent operations on the result cannot be
12261 guaranteed to produce sensible behavior.  For example, it is possible to
12262 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12263 @code{.NOT.@var{VAR}} both appear to be true.
12264
12265 @item @emph{Example}:
12266 @smallexample
12267 PROGRAM test_transfer
12268   integer :: x = 2143289344
12269   print *, transfer(x, 1.0)    ! prints "NaN" on i686
12270 END PROGRAM
12271 @end smallexample
12272 @end table
12273
12274
12275
12276 @node TRANSPOSE
12277 @section @code{TRANSPOSE} --- Transpose an array of rank two
12278 @fnindex TRANSPOSE
12279 @cindex array, transpose
12280 @cindex matrix, transpose
12281 @cindex transpose
12282
12283 @table @asis
12284 @item @emph{Description}:
12285 Transpose an array of rank two. Element (i, j) of the result has the value
12286 @code{MATRIX(j, i)}, for all i, j.
12287
12288 @item @emph{Standard}:
12289 Fortran 95 and later
12290
12291 @item @emph{Class}:
12292 Transformational function
12293
12294 @item @emph{Syntax}:
12295 @code{RESULT = TRANSPOSE(MATRIX)}
12296
12297 @item @emph{Arguments}:
12298 @multitable @columnfractions .15 .70
12299 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12300 @end multitable
12301
12302 @item @emph{Return value}:
12303 The result has the same type as @var{MATRIX}, and has shape
12304 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12305 @end table
12306
12307
12308
12309 @node TRIM
12310 @section @code{TRIM} --- Remove trailing blank characters of a string
12311 @fnindex TRIM
12312 @cindex string, remove trailing whitespace
12313
12314 @table @asis
12315 @item @emph{Description}:
12316 Removes trailing blank characters of a string.
12317
12318 @item @emph{Standard}:
12319 Fortran 95 and later
12320
12321 @item @emph{Class}:
12322 Transformational function
12323
12324 @item @emph{Syntax}:
12325 @code{RESULT = TRIM(STRING)}
12326
12327 @item @emph{Arguments}:
12328 @multitable @columnfractions .15 .70
12329 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12330 @end multitable
12331
12332 @item @emph{Return value}:
12333 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12334 less the number of trailing blanks.
12335
12336 @item @emph{Example}:
12337 @smallexample
12338 PROGRAM test_trim
12339   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
12340   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
12341 END PROGRAM
12342 @end smallexample
12343
12344 @item @emph{See also}:
12345 @ref{ADJUSTL}, @ref{ADJUSTR}
12346 @end table
12347
12348
12349
12350 @node TTYNAM
12351 @section @code{TTYNAM} --- Get the name of a terminal device.
12352 @fnindex TTYNAM
12353 @cindex system, terminal
12354
12355 @table @asis
12356 @item @emph{Description}:
12357 Get the name of a terminal device. For more information,
12358 see @code{ttyname(3)}.
12359
12360 This intrinsic is provided in both subroutine and function forms;
12361 however, only one form can be used in any given program unit.
12362
12363 @item @emph{Standard}:
12364 GNU extension
12365
12366 @item @emph{Class}:
12367 Subroutine, function
12368
12369 @item @emph{Syntax}:
12370 @multitable @columnfractions .80
12371 @item @code{CALL TTYNAM(UNIT, NAME)}
12372 @item @code{NAME = TTYNAM(UNIT)}
12373 @end multitable
12374
12375 @item @emph{Arguments}:
12376 @multitable @columnfractions .15 .70
12377 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12378 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12379 @end multitable
12380
12381 @item @emph{Example}:
12382 @smallexample
12383 PROGRAM test_ttynam
12384   INTEGER :: unit
12385   DO unit = 1, 10
12386     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12387   END DO
12388 END PROGRAM
12389 @end smallexample
12390
12391 @item @emph{See also}:
12392 @ref{ISATTY}
12393 @end table
12394
12395
12396
12397 @node UBOUND
12398 @section @code{UBOUND} --- Upper dimension bounds of an array
12399 @fnindex UBOUND
12400 @cindex array, upper bound
12401
12402 @table @asis
12403 @item @emph{Description}:
12404 Returns the upper bounds of an array, or a single upper bound
12405 along the @var{DIM} dimension.
12406 @item @emph{Standard}:
12407 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12408
12409 @item @emph{Class}:
12410 Inquiry function
12411
12412 @item @emph{Syntax}:
12413 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12414
12415 @item @emph{Arguments}:
12416 @multitable @columnfractions .15 .70
12417 @item @var{ARRAY} @tab Shall be an array, of any type.
12418 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12419 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12420 expression indicating the kind parameter of the result.
12421 @end multitable
12422
12423 @item @emph{Return value}:
12424 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12425 @var{KIND} is absent, the return value is of default integer kind.
12426 If @var{DIM} is absent, the result is an array of the upper bounds of
12427 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
12428 corresponding to the upper bound of the array along that dimension.  If
12429 @var{ARRAY} is an expression rather than a whole array or array
12430 structure component, or if it has a zero extent along the relevant
12431 dimension, the upper bound is taken to be the number of elements along
12432 the relevant dimension.
12433
12434 @item @emph{See also}:
12435 @ref{LBOUND}, @ref{LCOBOUND}
12436 @end table
12437
12438
12439
12440 @node UCOBOUND
12441 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12442 @fnindex UCOBOUND
12443 @cindex coarray, upper bound
12444
12445 @table @asis
12446 @item @emph{Description}:
12447 Returns the upper cobounds of a coarray, or a single upper cobound
12448 along the @var{DIM} codimension.
12449 @item @emph{Standard}:
12450 Fortran 2008 and later
12451
12452 @item @emph{Class}:
12453 Inquiry function
12454
12455 @item @emph{Syntax}:
12456 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12457
12458 @item @emph{Arguments}:
12459 @multitable @columnfractions .15 .70
12460 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12461 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12462 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12463 expression indicating the kind parameter of the result.
12464 @end multitable
12465
12466 @item @emph{Return value}:
12467 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12468 @var{KIND} is absent, the return value is of default integer kind.
12469 If @var{DIM} is absent, the result is an array of the lower cobounds of
12470 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
12471 corresponding to the lower cobound of the array along that codimension.
12472
12473 @item @emph{See also}:
12474 @ref{LCOBOUND}, @ref{LBOUND}
12475 @end table
12476
12477
12478
12479 @node UMASK
12480 @section @code{UMASK} --- Set the file creation mask
12481 @fnindex UMASK
12482 @cindex file system, file creation mask
12483
12484 @table @asis
12485 @item @emph{Description}:
12486 Sets the file creation mask to @var{MASK}. If called as a function, it
12487 returns the old value. If called as a subroutine and argument @var{OLD}
12488 if it is supplied, it is set to the old value. See @code{umask(2)}.
12489
12490 @item @emph{Standard}:
12491 GNU extension
12492
12493 @item @emph{Class}:
12494 Subroutine, function
12495
12496 @item @emph{Syntax}:
12497 @multitable @columnfractions .80
12498 @item @code{CALL UMASK(MASK [, OLD])}
12499 @item @code{OLD = UMASK(MASK)}
12500 @end multitable
12501
12502 @item @emph{Arguments}:
12503 @multitable @columnfractions .15 .70
12504 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12505 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12506 @code{INTEGER}.
12507 @end multitable
12508
12509 @end table
12510
12511
12512
12513 @node UNLINK
12514 @section @code{UNLINK} --- Remove a file from the file system
12515 @fnindex UNLINK
12516 @cindex file system, remove file
12517
12518 @table @asis
12519 @item @emph{Description}:
12520 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12521 used to mark the end of the name in @var{PATH}; otherwise, trailing
12522 blanks in the file name are ignored.  If the @var{STATUS} argument is
12523 supplied, it contains 0 on success or a nonzero error code upon return;
12524 see @code{unlink(2)}.
12525
12526 This intrinsic is provided in both subroutine and function forms;
12527 however, only one form can be used in any given program unit.
12528
12529 @item @emph{Standard}:
12530 GNU extension
12531
12532 @item @emph{Class}:
12533 Subroutine, function
12534
12535 @item @emph{Syntax}:
12536 @multitable @columnfractions .80
12537 @item @code{CALL UNLINK(PATH [, STATUS])}
12538 @item @code{STATUS = UNLINK(PATH)}
12539 @end multitable
12540
12541 @item @emph{Arguments}:
12542 @multitable @columnfractions .15 .70
12543 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12544 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12545 @end multitable
12546
12547 @item @emph{See also}:
12548 @ref{LINK}, @ref{SYMLNK}
12549 @end table
12550
12551
12552
12553 @node UNPACK
12554 @section @code{UNPACK} --- Unpack an array of rank one into an array
12555 @fnindex UNPACK
12556 @cindex array, unpacking
12557 @cindex array, increase dimension
12558 @cindex array, scatter elements
12559
12560 @table @asis
12561 @item @emph{Description}:
12562 Store the elements of @var{VECTOR} in an array of higher rank.
12563
12564 @item @emph{Standard}:
12565 Fortran 95 and later
12566
12567 @item @emph{Class}:
12568 Transformational function
12569
12570 @item @emph{Syntax}:
12571 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12572
12573 @item @emph{Arguments}:
12574 @multitable @columnfractions .15 .70
12575 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12576 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12577 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
12578 @item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
12579 the same shape as @var{MASK}.
12580 @end multitable
12581
12582 @item @emph{Return value}:
12583 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12584 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12585
12586 @item @emph{Example}:
12587 @smallexample
12588 PROGRAM test_unpack
12589   integer :: vector(2)  = (/1,1/)
12590   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12591   integer :: field(2,2) = 0, unity(2,2)
12592
12593   ! result: unity matrix
12594   unity = unpack(vector, reshape(mask, (/2,2/)), field)
12595 END PROGRAM
12596 @end smallexample
12597
12598 @item @emph{See also}:
12599 @ref{PACK}, @ref{SPREAD}
12600 @end table
12601
12602
12603
12604 @node VERIFY
12605 @section @code{VERIFY} --- Scan a string for characters not a given set
12606 @fnindex VERIFY
12607 @cindex string, find missing set
12608
12609 @table @asis
12610 @item @emph{Description}:
12611 Verifies that all the characters in @var{STRING} belong the set of
12612 characters in @var{SET}.
12613
12614 If @var{BACK} is either absent or equals @code{FALSE}, this function
12615 returns the position of the leftmost character of @var{STRING} that is
12616 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12617 position is returned. If all characters of @var{STRING} are found in
12618 @var{SET}, the result is zero.
12619
12620 @item @emph{Standard}:
12621 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12622
12623 @item @emph{Class}:
12624 Elemental function
12625
12626 @item @emph{Syntax}:
12627 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12628
12629 @item @emph{Arguments}:
12630 @multitable @columnfractions .15 .70
12631 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12632 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
12633 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
12634 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
12635 expression indicating the kind parameter of the result.
12636 @end multitable
12637
12638 @item @emph{Return value}:
12639 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12640 @var{KIND} is absent, the return value is of default integer kind.
12641
12642 @item @emph{Example}:
12643 @smallexample
12644 PROGRAM test_verify
12645   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
12646   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
12647   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
12648   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
12649   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
12650 END PROGRAM
12651 @end smallexample
12652
12653 @item @emph{See also}:
12654 @ref{SCAN}, @ref{INDEX intrinsic}
12655 @end table
12656
12657
12658
12659 @node XOR
12660 @section @code{XOR} --- Bitwise logical exclusive OR
12661 @fnindex XOR
12662 @cindex bitwise logical exclusive or
12663 @cindex logical exclusive or, bitwise
12664
12665 @table @asis
12666 @item @emph{Description}:
12667 Bitwise logical exclusive or.
12668
12669 This intrinsic routine is provided for backwards compatibility with
12670 GNU Fortran 77.  For integer arguments, programmers should consider
12671 the use of the @ref{IEOR} intrinsic and for logical arguments the
12672 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12673
12674 @item @emph{Standard}:
12675 GNU extension
12676
12677 @item @emph{Class}:
12678 Function
12679
12680 @item @emph{Syntax}:
12681 @code{RESULT = XOR(I, J)}
12682
12683 @item @emph{Arguments}:
12684 @multitable @columnfractions .15 .70
12685 @item @var{I} @tab The type shall be either  a scalar @code{INTEGER}
12686 type or a scalar @code{LOGICAL} type.
12687 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12688 @end multitable
12689
12690 @item @emph{Return value}:
12691 The return type is either a scalar @code{INTEGER} or a scalar
12692 @code{LOGICAL}.  If the kind type parameters differ, then the
12693 smaller kind type is implicitly converted to larger kind, and the
12694 return has the larger kind.
12695
12696 @item @emph{Example}:
12697 @smallexample
12698 PROGRAM test_xor
12699   LOGICAL :: T = .TRUE., F = .FALSE.
12700   INTEGER :: a, b
12701   DATA a / Z'F' /, b / Z'3' /
12702
12703   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12704   WRITE (*,*) XOR(a, b)
12705 END PROGRAM
12706 @end smallexample
12707
12708 @item @emph{See also}:
12709 Fortran 95 elemental function: @ref{IEOR}
12710 @end table
12711
12712
12713
12714 @node Intrinsic Modules
12715 @chapter Intrinsic Modules
12716 @cindex intrinsic Modules
12717
12718 @menu
12719 * ISO_FORTRAN_ENV::
12720 * ISO_C_BINDING::
12721 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12722 @end menu
12723
12724 @node ISO_FORTRAN_ENV
12725 @section @code{ISO_FORTRAN_ENV}
12726 @table @asis
12727 @item @emph{Standard}:
12728 Fortran 2003 and later, except when otherwise noted
12729 @end table
12730
12731 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12732 named constants:
12733
12734 @table @asis
12735 @item @code{ATOMIC_INT_KIND}:
12736 Default-kind integer constant to be used as kind parameter when defining
12737 integer variables used in atomic operations. (Fortran 2008 or later.)
12738
12739 @item @code{ATOMIC_LOGICAL_KIND}:
12740 Default-kind integer constant to be used as kind parameter when defining
12741 logical variables used in atomic operations. (Fortran 2008 or later.)
12742
12743 @item @code{CHARACTER_KINDS}:
12744 Default-kind integer constant array of rank one containing the supported kind
12745 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12746
12747 @item @code{CHARACTER_STORAGE_SIZE}:
12748 Size in bits of the character storage unit.
12749
12750 @item @code{ERROR_UNIT}:
12751 Identifies the preconnected unit used for error reporting.
12752
12753 @item @code{FILE_STORAGE_SIZE}:
12754 Size in bits of the file-storage unit.
12755
12756 @item @code{INPUT_UNIT}:
12757 Identifies the preconnected unit identified by the asterisk
12758 (@code{*}) in @code{READ} statement.
12759
12760 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12761 Kind type parameters to specify an INTEGER type with a storage
12762 size of 16, 32, and 64 bits. It is negative if a target platform
12763 does not support the particular kind. (Fortran 2008 or later.)
12764
12765 @item @code{INTEGER_KINDS}:
12766 Default-kind integer constant array of rank one containing the supported kind
12767 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12768
12769 @item @code{IOSTAT_END}:
12770 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12771 an input/output statement if an end-of-file condition occurred.
12772
12773 @item @code{IOSTAT_EOR}:
12774 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12775 an input/output statement if an end-of-record condition occurred.
12776
12777 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12778 Scalar default-integer constant, used by @code{INQUIRE} for the
12779 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12780 internal unit. (Fortran 2008 or later.)
12781
12782 @item @code{NUMERIC_STORAGE_SIZE}:
12783 The size in bits of the numeric storage unit.
12784
12785 @item @code{LOGICAL_KINDS}:
12786 Default-kind integer constant array of rank one containing the supported kind
12787 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12788
12789 @item @code{OUTPUT_UNIT}:
12790 Identifies the preconnected unit identified by the asterisk
12791 (@code{*}) in @code{WRITE} statement.
12792
12793 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12794 Kind type parameters to specify a REAL type with a storage
12795 size of 32, 64, and 128 bits. It is negative if a target platform
12796 does not support the particular kind. (Fortran 2008 or later.)
12797
12798 @item @code{REAL_KINDS}:
12799 Default-kind integer constant array of rank one containing the supported kind
12800 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12801
12802 @item @code{STAT_LOCKED}:
12803 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12804 denote that the lock variable is locked by the executing image. (Fortran 2008
12805 or later.)
12806
12807 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12808 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12809 denote that the lock variable is locked by another image. (Fortran 2008 or
12810 later.)
12811
12812 @item @code{STAT_STOPPED_IMAGE}:
12813 Positive, scalar default-integer constant used as STAT= return value if the
12814 argument in the statement requires synchronisation with an image, which has
12815 initiated the termination of the execution. (Fortran 2008 or later.)
12816
12817 @item @code{STAT_UNLOCKED}:
12818 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12819 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12820 @end table
12821
12822 The module also provides the following intrinsic procedures:
12823 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12824
12825
12826
12827 @node ISO_C_BINDING
12828 @section @code{ISO_C_BINDING}
12829 @table @asis
12830 @item @emph{Standard}:
12831 Fortran 2003 and later, GNU extensions
12832 @end table
12833
12834 The following intrinsic procedures are provided by the module; their
12835 definition can be found in the section Intrinsic Procedures of this
12836 manual.
12837
12838 @table @asis
12839 @item @code{C_ASSOCIATED}
12840 @item @code{C_F_POINTER}
12841 @item @code{C_F_PROCPOINTER}
12842 @item @code{C_FUNLOC}
12843 @item @code{C_LOC}
12844 @item @code{C_SIZEOF}
12845 @end table
12846 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
12847 @c don't really know why.
12848
12849 The @code{ISO_C_BINDING} module provides the following named constants of
12850 type default integer, which can be used as KIND type parameters.
12851
12852 In addition to the integer named constants required by the Fortran 2003
12853 standard, GNU Fortran provides as an extension named constants for the
12854 128-bit integer types supported by the C compiler: @code{C_INT128_T,
12855 C_INT_LEAST128_T, C_INT_FAST128_T}.
12856
12857 @multitable @columnfractions .15 .35 .35 .35
12858 @item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
12859 @item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
12860 @item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
12861 @item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
12862 @item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
12863 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
12864 @item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
12865 @item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
12866 @item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
12867 @item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
12868 @item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
12869 @item @code{INTEGER}@tab @code{C_INT128_T}      @tab @code{int128_t}                      @tab Ext.
12870 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
12871 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
12872 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
12873 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
12874 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t}                @tab Ext.
12875 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}   @tab @code{int_fast8_t}
12876 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}  @tab @code{int_fast16_t}
12877 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}  @tab @code{int_fast32_t}
12878 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}  @tab @code{int_fast64_t}
12879 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t}                 @tab Ext.
12880 @item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
12881 @item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
12882 @item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
12883 @item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
12884 @item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
12885 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
12886 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
12887 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
12888 @item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
12889 @item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
12890 @end multitable
12891
12892 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
12893 are defined.
12894
12895 @multitable @columnfractions .20 .45 .15
12896 @item Name                     @tab C definition    @tab Value
12897 @item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
12898 @item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
12899 @item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
12900 @item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
12901 @item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
12902 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
12903 @item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
12904 @item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
12905 @end multitable
12906
12907 Moreover, the following two named constants are defined:
12908
12909 @multitable @columnfractions .20 .80
12910 @item Name                 @tab Type
12911 @item @code{C_NULL_PTR}    @tab @code{C_PTR}
12912 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
12913 @end multitable
12914
12915 Both are equivalent to the value @code{NULL} in C.
12916
12917 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
12918 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
12919 @table @asis
12920 @item @emph{Standard}:
12921 OpenMP Application Program Interface v3.0
12922 @end table
12923
12924
12925 The OpenMP Fortran runtime library routines are provided both in
12926 a form of two Fortran 90 modules, named @code{OMP_LIB} and
12927 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
12928 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
12929 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
12930 the named constants defined in the modules are listed
12931 below.
12932
12933 For details refer to the actual
12934 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
12935 OpenMP Application Program Interface v3.0}.
12936
12937 @code{OMP_LIB_KINDS} provides the following scalar default-integer
12938 named constants:
12939
12940 @table @asis
12941 @item @code{omp_integer_kind}
12942 @item @code{omp_logical_kind}
12943 @item @code{omp_lock_kind}
12944 @item @code{omp_nest_lock_kind}
12945 @item @code{omp_sched_kind}
12946 @end table
12947
12948 @code{OMP_LIB} provides the scalar default-integer
12949 named constant @code{openmp_version} with a value of the form
12950 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
12951 of the OpenMP version; for OpenMP v3.0 the value is @code{200805}.
12952
12953 And the following scalar integer named constants of the
12954 kind @code{omp_sched_kind}:
12955
12956 @table @asis
12957 @item @code{omp_sched_static}
12958 @item @code{omp_sched_dynamic}
12959 @item @code{omp_sched_guided}
12960 @item @code{omp_sched_auto}
12961 @end table