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{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
  65 * @code{ATOMIC_REF}:    ATOMIC_REF, Obtaining the value of a variable atomically
  66 * @code{BESSEL_J0}:     BESSEL_J0, Bessel function of the first kind of order 0
  67 * @code{BESSEL_J1}:     BESSEL_J1, Bessel function of the first kind of order 1
  68 * @code{BESSEL_JN}:     BESSEL_JN, Bessel function of the first kind
  69 * @code{BESSEL_Y0}:     BESSEL_Y0, Bessel function of the second kind of order 0
  70 * @code{BESSEL_Y1}:     BESSEL_Y1, Bessel function of the second kind of order 1
  71 * @code{BESSEL_YN}:     BESSEL_YN, Bessel function of the second kind
  72 * @code{BGE}:           BGE,       Bitwise greater than or equal to
  73 * @code{BGT}:           BGT,       Bitwise greater than
  74 * @code{BIT_SIZE}:      BIT_SIZE,  Bit size inquiry function
  75 * @code{BLE}:           BLE,       Bitwise less than or equal to
  76 * @code{BLT}:           BLT,       Bitwise less than
  77 * @code{BTEST}:         BTEST,     Bit test function
  78 * @code{C_ASSOCIATED}:  C_ASSOCIATED, Status of a C pointer
  79 * @code{C_F_POINTER}:   C_F_POINTER, Convert C into Fortran pointer
  80 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
  81 * @code{C_FUNLOC}:      C_FUNLOC,  Obtain the C address of a procedure
  82 * @code{C_LOC}:         C_LOC,     Obtain the C address of an object
  83 * @code{C_SIZEOF}:      C_SIZEOF,  Size in bytes of an expression
  84 * @code{CEILING}:       CEILING,   Integer ceiling function
  85 * @code{CHAR}:          CHAR,      Integer-to-character conversion function
  86 * @code{CHDIR}:         CHDIR,     Change working directory
  87 * @code{CHMOD}:         CHMOD,     Change access permissions of files
  88 * @code{CMPLX}:         CMPLX,     Complex conversion function
  89 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
  90 * @code{COMPLEX}:       COMPLEX,   Complex conversion function
  91 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
  92 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
  93 * @code{CONJG}:         CONJG,     Complex conjugate function
  94 * @code{COS}:           COS,       Cosine function
  95 * @code{COSH}:          COSH,      Hyperbolic cosine function
  96 * @code{COUNT}:         COUNT,     Count occurrences of TRUE in an array
  97 * @code{CPU_TIME}:      CPU_TIME,  CPU time subroutine
  98 * @code{CSHIFT}:        CSHIFT,    Circular shift elements of an array
  99 * @code{CTIME}:         CTIME,     Subroutine (or function) to convert a time into a string
 100 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
 101 * @code{DBLE}:          DBLE,      Double precision conversion function
 102 * @code{DCMPLX}:        DCMPLX,    Double complex conversion function
 103 * @code{DIGITS}:        DIGITS,    Significant digits function
 104 * @code{DIM}:           DIM,       Positive difference
 105 * @code{DOT_PRODUCT}:   DOT_PRODUCT, Dot product function
 106 * @code{DPROD}:         DPROD,     Double product function
 107 * @code{DREAL}:         DREAL,     Double real part function
 108 * @code{DSHIFTL}:       DSHIFTL,   Combined left shift
 109 * @code{DSHIFTR}:       DSHIFTR,   Combined right shift
 110 * @code{DTIME}:         DTIME,     Execution time subroutine (or function)
 111 * @code{EOSHIFT}:       EOSHIFT,   End-off shift elements of an array
 112 * @code{EPSILON}:       EPSILON,   Epsilon function
 113 * @code{ERF}:           ERF,       Error function
 114 * @code{ERFC}:          ERFC,      Complementary error function
 115 * @code{ERFC_SCALED}:   ERFC_SCALED, Exponentially-scaled complementary error function
 116 * @code{ETIME}:         ETIME,     Execution time subroutine (or function)
 117 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
 118 * @code{EXIT}:          EXIT,      Exit the program with status.
 119 * @code{EXP}:           EXP,       Exponential function
 120 * @code{EXPONENT}:      EXPONENT,  Exponent function
 121 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF,  Query dynamic type for extension
 122 * @code{FDATE}:         FDATE,     Subroutine (or function) to get the current time as a string
 123 * @code{FGET}:          FGET,      Read a single character in stream mode from stdin
 124 * @code{FGETC}:         FGETC,     Read a single character in stream mode
 125 * @code{FLOOR}:         FLOOR,     Integer floor function
 126 * @code{FLUSH}:         FLUSH,     Flush I/O unit(s)
 127 * @code{FNUM}:          FNUM,      File number function
 128 * @code{FPUT}:          FPUT,      Write a single character in stream mode to stdout
 129 * @code{FPUTC}:         FPUTC,     Write a single character in stream mode
 130 * @code{FRACTION}:      FRACTION,  Fractional part of the model representation
 131 * @code{FREE}:          FREE,      Memory de-allocation subroutine
 132 * @code{FSEEK}:         FSEEK,     Low level file positioning subroutine
 133 * @code{FSTAT}:         FSTAT,     Get file status
 134 * @code{FTELL}:         FTELL,     Current stream position
 135 * @code{GAMMA}:         GAMMA,     Gamma function
 136 * @code{GERROR}:        GERROR,    Get last system error message
 137 * @code{GETARG}:        GETARG,    Get command line arguments
 138 * @code{GET_COMMAND}:   GET_COMMAND, Get the entire command line
 139 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
 140 * @code{GETCWD}:        GETCWD,    Get current working directory
 141 * @code{GETENV}:        GETENV,    Get an environmental variable
 142 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
 143 * @code{GETGID}:        GETGID,    Group ID function
 144 * @code{GETLOG}:        GETLOG,    Get login name
 145 * @code{GETPID}:        GETPID,    Process ID function
 146 * @code{GETUID}:        GETUID,    User ID function
 147 * @code{GMTIME}:        GMTIME,    Convert time to GMT info
 148 * @code{HOSTNM}:        HOSTNM,    Get system host name
 149 * @code{HUGE}:          HUGE,      Largest number of a kind
 150 * @code{HYPOT}:         HYPOT,     Euclidean distance function
 151 * @code{IACHAR}:        IACHAR,    Code in @acronym{ASCII} collating sequence
 152 * @code{IALL}:          IALL,      Bitwise AND of array elements
 153 * @code{IAND}:          IAND,      Bitwise logical and
 154 * @code{IANY}:          IANY,      Bitwise OR of array elements
 155 * @code{IARGC}:         IARGC,     Get the number of command line arguments
 156 * @code{IBCLR}:         IBCLR,     Clear bit
 157 * @code{IBITS}:         IBITS,     Bit extraction
 158 * @code{IBSET}:         IBSET,     Set bit
 159 * @code{ICHAR}:         ICHAR,     Character-to-integer conversion function
 160 * @code{IDATE}:         IDATE,     Current local time (day/month/year)
 161 * @code{IEOR}:          IEOR,      Bitwise logical exclusive or
 162 * @code{IERRNO}:        IERRNO,    Function to get the last system error number
 163 * @code{IMAGE_INDEX}:   IMAGE_INDEX, Cosubscript to image index conversion
 164 * @code{INDEX}:         INDEX intrinsic, Position of a substring within a string
 165 * @code{INT}:           INT,       Convert to integer type
 166 * @code{INT2}:          INT2,      Convert to 16-bit integer type
 167 * @code{INT8}:          INT8,      Convert to 64-bit integer type
 168 * @code{IOR}:           IOR,       Bitwise logical or
 169 * @code{IPARITY}:       IPARITY,   Bitwise XOR of array elements
 170 * @code{IRAND}:         IRAND,     Integer pseudo-random number
 171 * @code{IS_IOSTAT_END}:  IS_IOSTAT_END, Test for end-of-file value
 172 * @code{IS_IOSTAT_EOR}:  IS_IOSTAT_EOR, Test for end-of-record value
 173 * @code{ISATTY}:        ISATTY,    Whether a unit is a terminal device
 174 * @code{ISHFT}:         ISHFT,     Shift bits
 175 * @code{ISHFTC}:        ISHFTC,    Shift bits circularly
 176 * @code{ISNAN}:         ISNAN,     Tests for a NaN
 177 * @code{ITIME}:         ITIME,     Current local time (hour/minutes/seconds)
 178 * @code{KILL}:          KILL,      Send a signal to a process
 179 * @code{KIND}:          KIND,      Kind of an entity
 180 * @code{LBOUND}:        LBOUND,    Lower dimension bounds of an array
 181 * @code{LCOBOUND}:      LCOBOUND,  Lower codimension bounds of an array
 182 * @code{LEADZ}:         LEADZ,     Number of leading zero bits of an integer
 183 * @code{LEN}:           LEN,       Length of a character entity
 184 * @code{LEN_TRIM}:      LEN_TRIM,  Length of a character entity without trailing blank characters
 185 * @code{LGE}:           LGE,       Lexical greater than or equal
 186 * @code{LGT}:           LGT,       Lexical greater than
 187 * @code{LINK}:          LINK,      Create a hard link
 188 * @code{LLE}:           LLE,       Lexical less than or equal
 189 * @code{LLT}:           LLT,       Lexical less than
 190 * @code{LNBLNK}:        LNBLNK,    Index of the last non-blank character in a string
 191 * @code{LOC}:           LOC,       Returns the address of a variable
 192 * @code{LOG}:           LOG,       Logarithm function
 193 * @code{LOG10}:         LOG10,     Base 10 logarithm function
 194 * @code{LOG_GAMMA}:     LOG_GAMMA, Logarithm of the Gamma function
 195 * @code{LOGICAL}:       LOGICAL,   Convert to logical type
 196 * @code{LONG}:          LONG,      Convert to integer type
 197 * @code{LSHIFT}:        LSHIFT,    Left shift bits
 198 * @code{LSTAT}:         LSTAT,     Get file status
 199 * @code{LTIME}:         LTIME,     Convert time to local time info
 200 * @code{MALLOC}:        MALLOC,    Dynamic memory allocation function
 201 * @code{MASKL}:         MASKL,     Left justified mask
 202 * @code{MASKR}:         MASKR,     Right justified mask
 203 * @code{MATMUL}:        MATMUL,    matrix multiplication
 204 * @code{MAX}:           MAX,       Maximum value of an argument list
 205 * @code{MAXEXPONENT}:   MAXEXPONENT, Maximum exponent of a real kind
 206 * @code{MAXLOC}:        MAXLOC,    Location of the maximum value within an array
 207 * @code{MAXVAL}:        MAXVAL,    Maximum value of an array
 208 * @code{MCLOCK}:        MCLOCK,    Time function
 209 * @code{MCLOCK8}:       MCLOCK8,   Time function (64-bit)
 210 * @code{MERGE}:         MERGE,     Merge arrays
 211 * @code{MERGE_BITS}:    MERGE_BITS, Merge of bits under mask
 212 * @code{MIN}:           MIN,       Minimum value of an argument list
 213 * @code{MINEXPONENT}:   MINEXPONENT, Minimum exponent of a real kind
 214 * @code{MINLOC}:        MINLOC,    Location of the minimum value within an array
 215 * @code{MINVAL}:        MINVAL,    Minimum value of an array
 216 * @code{MOD}:           MOD,       Remainder function
 217 * @code{MODULO}:        MODULO,    Modulo function
 218 * @code{MOVE_ALLOC}:    MOVE_ALLOC, Move allocation from one object to another
 219 * @code{MVBITS}:        MVBITS,    Move bits from one integer to another
 220 * @code{NEAREST}:       NEAREST,   Nearest representable number
 221 * @code{NEW_LINE}:      NEW_LINE,  New line character
 222 * @code{NINT}:          NINT,      Nearest whole number
 223 * @code{NORM2}:         NORM2,     Euclidean vector norm
 224 * @code{NOT}:           NOT,       Logical negation
 225 * @code{NULL}:          NULL,      Function that returns an disassociated pointer
 226 * @code{NUM_IMAGES}:    NUM_IMAGES, Number of images
 227 * @code{OR}:            OR,        Bitwise logical OR
 228 * @code{PACK}:          PACK,      Pack an array into an array of rank one
 229 * @code{PARITY}:        PARITY,    Reduction with exclusive OR
 230 * @code{PERROR}:        PERROR,    Print system error message
 231 * @code{POPCNT}:        POPCNT,    Number of bits set
 232 * @code{POPPAR}:        POPPAR,    Parity of the number of bits set
 233 * @code{PRECISION}:     PRECISION, Decimal precision of a real kind
 234 * @code{PRESENT}:       PRESENT,   Determine whether an optional dummy argument is specified
 235 * @code{PRODUCT}:       PRODUCT,   Product of array elements
 236 * @code{RADIX}:         RADIX,     Base of a data model
 237 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
 238 * @code{RANDOM_SEED}:   RANDOM_SEED, Initialize a pseudo-random number sequence
 239 * @code{RAND}:          RAND,      Real pseudo-random number
 240 * @code{RANGE}:         RANGE,     Decimal exponent range
 241 * @code{RANK} :         RANK,      Rank of a data object
 242 * @code{RAN}:           RAN,       Real pseudo-random number
 243 * @code{REAL}:          REAL,      Convert to real type
 244 * @code{RENAME}:        RENAME,    Rename a file
 245 * @code{REPEAT}:        REPEAT,    Repeated string concatenation
 246 * @code{RESHAPE}:       RESHAPE,   Function to reshape an array
 247 * @code{RRSPACING}:     RRSPACING, Reciprocal of the relative spacing
 248 * @code{RSHIFT}:        RSHIFT,    Right shift bits
 249 * @code{SAME_TYPE_AS}:  SAME_TYPE_AS,  Query dynamic types for equality
 250 * @code{SCALE}:         SCALE,     Scale a real value
 251 * @code{SCAN}:          SCAN,      Scan a string for the presence of a set of characters
 252 * @code{SECNDS}:        SECNDS,    Time function
 253 * @code{SECOND}:        SECOND,    CPU time function
 254 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND,  Choose character kind
 255 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND,  Choose integer kind
 256 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND,  Choose real kind
 257 * @code{SET_EXPONENT}:  SET_EXPONENT, Set the exponent of the model
 258 * @code{SHAPE}:         SHAPE,     Determine the shape of an array
 259 * @code{SHIFTA}:        SHIFTA,    Right shift with fill
 260 * @code{SHIFTL}:        SHIFTL,    Left shift
 261 * @code{SHIFTR}:        SHIFTR,    Right shift
 262 * @code{SIGN}:          SIGN,      Sign copying function
 263 * @code{SIGNAL}:        SIGNAL,    Signal handling subroutine (or function)
 264 * @code{SIN}:           SIN,       Sine function
 265 * @code{SINH}:          SINH,      Hyperbolic sine function
 266 * @code{SIZE}:          SIZE,      Function to determine the size of an array
 267 * @code{SIZEOF}:        SIZEOF,    Determine the size in bytes of an expression
 268 * @code{SLEEP}:         SLEEP,     Sleep for the specified number of seconds
 269 * @code{SPACING}:       SPACING,   Smallest distance between two numbers of a given type
 270 * @code{SPREAD}:        SPREAD,    Add a dimension to an array
 271 * @code{SQRT}:          SQRT,      Square-root function
 272 * @code{SRAND}:         SRAND,     Reinitialize the random number generator
 273 * @code{STAT}:          STAT,      Get file status
 274 * @code{STORAGE_SIZE}:  STORAGE_SIZE, Storage size in bits
 275 * @code{SUM}:           SUM,       Sum of array elements
 276 * @code{SYMLNK}:        SYMLNK,    Create a symbolic link
 277 * @code{SYSTEM}:        SYSTEM,    Execute a shell command
 278 * @code{SYSTEM_CLOCK}:  SYSTEM_CLOCK, Time function
 279 * @code{TAN}:           TAN,       Tangent function
 280 * @code{TANH}:          TANH,      Hyperbolic tangent function
 281 * @code{THIS_IMAGE}:    THIS_IMAGE, Cosubscript index of this image
 282 * @code{TIME}:          TIME,      Time function
 283 * @code{TIME8}:         TIME8,     Time function (64-bit)
 284 * @code{TINY}:          TINY,      Smallest positive number of a real kind
 285 * @code{TRAILZ}:        TRAILZ,    Number of trailing zero bits of an integer
 286 * @code{TRANSFER}:      TRANSFER,  Transfer bit patterns
 287 * @code{TRANSPOSE}:     TRANSPOSE, Transpose an array of rank two
 288 * @code{TRIM}:          TRIM,      Remove trailing blank characters of a string
 289 * @code{TTYNAM}:        TTYNAM,    Get the name of a terminal device.
 290 * @code{UBOUND}:        UBOUND,    Upper dimension bounds of an array
 291 * @code{UCOBOUND}:      UCOBOUND,  Upper codimension bounds of an array
 292 * @code{UMASK}:         UMASK,     Set the file creation mask
 293 * @code{UNLINK}:        UNLINK,    Remove a file from the file system
 294 * @code{UNPACK}:        UNPACK,    Unpack an array of rank one into an array
 295 * @code{VERIFY}:        VERIFY,    Scan a string for the absence of a set of characters
 296 * @code{XOR}:           XOR,       Bitwise logical exclusive or
 297 @end menu
 298
 299 @node Introduction to Intrinsics
 300 @section Introduction to intrinsic procedures
 301
 302 The intrinsic procedures provided by GNU Fortran include all of the
 303 intrinsic procedures required by the Fortran 95 standard, a set of
 304 intrinsic procedures for backwards compatibility with G77, and a
 305 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
 306 standards.  Any conflict between a description here and a description in
 307 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
 308 2008 standard is unintentional, and the standard(s) should be considered
 309 authoritative.
 310
 311 The enumeration of the @code{KIND} type parameter is processor defined in
 312 the Fortran 95 standard.  GNU Fortran defines the default integer type and
 313 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
 314 respectively.  The standard mandates that both data types shall have
 315 another kind, which have more precision.  On typical target architectures
 316 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
 317 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
 318 In the description of generic intrinsic procedures, the kind type parameter
 319 will be specified by @code{KIND=*}, and in the description of specific
 320 names for an intrinsic procedure the kind type parameter will be explicitly
 321 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}).  Finally, for
 322 brevity the optional @code{KIND=} syntax will be omitted.
 323
 324 Many of the intrinsic procedures take one or more optional arguments.
 325 This document follows the convention used in the Fortran 95 standard,
 326 and denotes such arguments by square brackets.
 327
 328 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
 329 which can be used to restrict the set of intrinsic procedures to a
 330 given standard.  By default, @command{gfortran} sets the @option{-std=gnu}
 331 option, and so all intrinsic procedures described here are accepted.  There
 332 is one caveat.  For a select group of intrinsic procedures, @command{g77}
 333 implemented both a function and a subroutine.  Both classes
 334 have been implemented in @command{gfortran} for backwards compatibility
 335 with @command{g77}.  It is noted here that these functions and subroutines
 336 cannot be intermixed in a given subprogram.  In the descriptions that follow,
 337 the applicable standard for each intrinsic procedure is noted.
 338
 339
 340
 341 @node ABORT
 342 @section @code{ABORT} --- Abort the program
 343 @fnindex ABORT
 344 @cindex program termination, with core dump
 345 @cindex terminate program, with core dump
 346 @cindex core, dump
 347
 348 @table @asis
 349 @item @emph{Description}:
 350 @code{ABORT} causes immediate termination of the program.  On operating
 351 systems that support a core dump, @code{ABORT} will produce a core dump.
 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 ATOMIC_DEFINE
1552 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1553 @fnindex ATOMIC_DEFINE
1554 @cindex Atomic subroutine, define
1555
1556 @table @asis
1557 @item @emph{Description}:
1558 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1559 @var{VALUE} atomically.
1560
1561 @item @emph{Standard}:
1562 Fortran 2008 and later
1563
1564 @item @emph{Class}:
1565 Atomic subroutine
1566
1567 @item @emph{Syntax}:
1568 @code{CALL ATOMIC_DEFINE(ATOM, VALUE)}
1569
1570 @item @emph{Arguments}:
1571 @multitable @columnfractions .15 .70
1572 @item @var{ATOM}   @tab Scalar coarray or coindexed variable of either integer
1573                         type with @code{ATOMIC_INT_KIND} kind or logical type
1574                         with @code{ATOMIC_LOGICAL_KIND} kind.
1575 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1576                         is different, the value is converted to the kind of
1577                         @var{ATOM}.
1578 @end multitable
1579
1580 @item @emph{Example}:
1581 @smallexample
1582 program atomic
1583   use iso_fortran_env
1584   integer(atomic_int_kind) :: atom[*]
1585   call atomic_define (atom[1], this_image())
1586 end program atomic
1587 @end smallexample
1588
1589 @item @emph{See also}:
1590 @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1591 @end table
1592
1593
1594
1595 @node ATOMIC_REF
1596 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
1597 @fnindex ATOMIC_REF
1598 @cindex Atomic subroutine, reference
1599
1600 @table @asis
1601 @item @emph{Description}:
1602 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
1603 variable @var{ATOM} to @var{VALUE}.
1604
1605 @item @emph{Standard}:
1606 Fortran 2008 and later
1607
1608 @item @emph{Class}:
1609 Atomic subroutine
1610
1611 @item @emph{Syntax}:
1612 @code{CALL ATOMIC_REF(VALUE, ATOM)}
1613
1614 @item @emph{Arguments}:
1615 @multitable @columnfractions .15 .70
1616 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1617                         is different, the value is converted to the kind of
1618                         @var{ATOM}.
1619 @item @var{ATOM}   @tab Scalar coarray or coindexed variable of either integer
1620                         type with @code{ATOMIC_INT_KIND} kind or logical type
1621                         with @code{ATOMIC_LOGICAL_KIND} kind.
1622 @end multitable
1623
1624 @item @emph{Example}:
1625 @smallexample
1626 program atomic
1627   use iso_fortran_env
1628   logical(atomic_logical_kind) :: atom[*]
1629   logical :: val
1630   call atomic_ref (atom, .false.)
1631   ! ...
1632   call atomic_ref (atom, val)
1633   if (val) then
1634     print *, "Obtained"
1635   end if
1636 end program atomic
1637 @end smallexample
1638
1639 @item @emph{See also}:
1640 @ref{ATOMIC_DEFINE}, @ref{ISO_FORTRAN_ENV}
1641 @end table
1642
1643
1644
1645 @node BESSEL_J0
1646 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1647 @fnindex BESSEL_J0
1648 @fnindex BESJ0
1649 @fnindex DBESJ0
1650 @cindex Bessel function, first kind
1651
1652 @table @asis
1653 @item @emph{Description}:
1654 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1655 order 0 of @var{X}. This function is available under the name
1656 @code{BESJ0} as a GNU extension.
1657
1658 @item @emph{Standard}:
1659 Fortran 2008 and later
1660
1661 @item @emph{Class}:
1662 Elemental function
1663
1664 @item @emph{Syntax}:
1665 @code{RESULT = BESSEL_J0(X)}
1666
1667 @item @emph{Arguments}:
1668 @multitable @columnfractions .15 .70
1669 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1670 @end multitable
1671
1672 @item @emph{Return value}:
1673 The return value is of type @code{REAL} and lies in the
1674 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1675 kind as @var{X}.
1676
1677 @item @emph{Example}:
1678 @smallexample
1679 program test_besj0
1680   real(8) :: x = 0.0_8
1681   x = bessel_j0(x)
1682 end program test_besj0
1683 @end smallexample
1684
1685 @item @emph{Specific names}:
1686 @multitable @columnfractions .20 .20 .20 .25
1687 @item Name            @tab Argument          @tab Return type       @tab Standard
1688 @item @code{DBESJ0(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}   @tab GNU extension
1689 @end multitable
1690 @end table
1691
1692
1693
1694 @node BESSEL_J1
1695 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1696 @fnindex BESSEL_J1
1697 @fnindex BESJ1
1698 @fnindex DBESJ1
1699 @cindex Bessel function, first kind
1700
1701 @table @asis
1702 @item @emph{Description}:
1703 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1704 order 1 of @var{X}. This function is available under the name
1705 @code{BESJ1} as a GNU extension.
1706
1707 @item @emph{Standard}:
1708 Fortran 2008
1709
1710 @item @emph{Class}:
1711 Elemental function
1712
1713 @item @emph{Syntax}:
1714 @code{RESULT = BESSEL_J1(X)}
1715
1716 @item @emph{Arguments}:
1717 @multitable @columnfractions .15 .70
1718 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1719 @end multitable
1720
1721 @item @emph{Return value}:
1722 The return value is of type @code{REAL} and it lies in the
1723 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1724 kind as @var{X}.
1725
1726 @item @emph{Example}:
1727 @smallexample
1728 program test_besj1
1729   real(8) :: x = 1.0_8
1730   x = bessel_j1(x)
1731 end program test_besj1
1732 @end smallexample
1733
1734 @item @emph{Specific names}:
1735 @multitable @columnfractions .20 .20 .20 .25
1736 @item Name             @tab Argument          @tab Return type       @tab Standard
1737 @item @code{DBESJ1(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1738 @end multitable
1739 @end table
1740
1741
1742
1743 @node BESSEL_JN
1744 @section @code{BESSEL_JN} --- Bessel function of the first kind
1745 @fnindex BESSEL_JN
1746 @fnindex BESJN
1747 @fnindex DBESJN
1748 @cindex Bessel function, first kind
1749
1750 @table @asis
1751 @item @emph{Description}:
1752 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1753 order @var{N} of @var{X}. This function is available under the name
1754 @code{BESJN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1755 their ranks and shapes shall conform.
1756
1757 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1758 of the first kind of the orders @var{N1} to @var{N2}.
1759
1760 @item @emph{Standard}:
1761 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1762
1763 @item @emph{Class}:
1764 Elemental function, except for the transformational function
1765 @code{BESSEL_JN(N1, N2, X)}
1766
1767 @item @emph{Syntax}:
1768 @multitable @columnfractions .80
1769 @item @code{RESULT = BESSEL_JN(N, X)}
1770 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1771 @end multitable
1772
1773 @item @emph{Arguments}:
1774 @multitable @columnfractions .15 .70
1775 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER}.
1776 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1777 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1778 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1779 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1780 @end multitable
1781
1782 @item @emph{Return value}:
1783 The return value is a scalar of type @code{REAL}. It has the same
1784 kind as @var{X}.
1785
1786 @item @emph{Note}:
1787 The transformational function uses a recurrence algorithm which might,
1788 for some values of @var{X}, lead to different results than calls to
1789 the elemental function.
1790
1791 @item @emph{Example}:
1792 @smallexample
1793 program test_besjn
1794   real(8) :: x = 1.0_8
1795   x = bessel_jn(5,x)
1796 end program test_besjn
1797 @end smallexample
1798
1799 @item @emph{Specific names}:
1800 @multitable @columnfractions .20 .20 .20 .25
1801 @item Name                @tab Argument            @tab Return type       @tab Standard
1802 @item @code{DBESJN(N, X)} @tab @code{INTEGER N}    @tab @code{REAL(8)}    @tab GNU extension
1803 @item                     @tab @code{REAL(8) X}    @tab                   @tab
1804 @end multitable
1805 @end table
1806
1807
1808
1809 @node BESSEL_Y0
1810 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1811 @fnindex BESSEL_Y0
1812 @fnindex BESY0
1813 @fnindex DBESY0
1814 @cindex Bessel function, second kind
1815
1816 @table @asis
1817 @item @emph{Description}:
1818 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1819 order 0 of @var{X}. This function is available under the name
1820 @code{BESY0} as a GNU extension.
1821
1822 @item @emph{Standard}:
1823 Fortran 2008 and later
1824
1825 @item @emph{Class}:
1826 Elemental function
1827
1828 @item @emph{Syntax}:
1829 @code{RESULT = BESSEL_Y0(X)}
1830
1831 @item @emph{Arguments}:
1832 @multitable @columnfractions .15 .70
1833 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1834 @end multitable
1835
1836 @item @emph{Return value}:
1837 The return value is a scalar of type @code{REAL}. It has the same
1838 kind as @var{X}.
1839
1840 @item @emph{Example}:
1841 @smallexample
1842 program test_besy0
1843   real(8) :: x = 0.0_8
1844   x = bessel_y0(x)
1845 end program test_besy0
1846 @end smallexample
1847
1848 @item @emph{Specific names}:
1849 @multitable @columnfractions .20 .20 .20 .25
1850 @item Name            @tab Argument          @tab Return type       @tab Standard
1851 @item @code{DBESY0(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1852 @end multitable
1853 @end table
1854
1855
1856
1857 @node BESSEL_Y1
1858 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1859 @fnindex BESSEL_Y1
1860 @fnindex BESY1
1861 @fnindex DBESY1
1862 @cindex Bessel function, second kind
1863
1864 @table @asis
1865 @item @emph{Description}:
1866 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1867 order 1 of @var{X}. This function is available under the name
1868 @code{BESY1} as a GNU extension.
1869
1870 @item @emph{Standard}:
1871 Fortran 2008 and later
1872
1873 @item @emph{Class}:
1874 Elemental function
1875
1876 @item @emph{Syntax}:
1877 @code{RESULT = BESSEL_Y1(X)}
1878
1879 @item @emph{Arguments}:
1880 @multitable @columnfractions .15 .70
1881 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1882 @end multitable
1883
1884 @item @emph{Return value}:
1885 The return value is a scalar of type @code{REAL}. It has the same
1886 kind as @var{X}.
1887
1888 @item @emph{Example}:
1889 @smallexample
1890 program test_besy1
1891   real(8) :: x = 1.0_8
1892   x = bessel_y1(x)
1893 end program test_besy1
1894 @end smallexample
1895
1896 @item @emph{Specific names}:
1897 @multitable @columnfractions .20 .20 .20 .25
1898 @item Name            @tab Argument          @tab Return type       @tab Standard
1899 @item @code{DBESY1(X)}@tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
1900 @end multitable
1901 @end table
1902
1903
1904
1905 @node BESSEL_YN
1906 @section @code{BESSEL_YN} --- Bessel function of the second kind
1907 @fnindex BESSEL_YN
1908 @fnindex BESYN
1909 @fnindex DBESYN
1910 @cindex Bessel function, second kind
1911
1912 @table @asis
1913 @item @emph{Description}:
1914 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1915 order @var{N} of @var{X}. This function is available under the name
1916 @code{BESYN} as a GNU extension.  If @var{N} and @var{X} are arrays,
1917 their ranks and shapes shall conform.
1918
1919 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1920 of the first kind of the orders @var{N1} to @var{N2}.
1921
1922 @item @emph{Standard}:
1923 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1924
1925 @item @emph{Class}:
1926 Elemental function, except for the transformational function
1927 @code{BESSEL_YN(N1, N2, X)}
1928
1929 @item @emph{Syntax}:
1930 @multitable @columnfractions .80
1931 @item @code{RESULT = BESSEL_YN(N, X)}
1932 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1933 @end multitable
1934
1935 @item @emph{Arguments}:
1936 @multitable @columnfractions .15 .70
1937 @item @var{N} @tab Shall be a scalar or an array of type  @code{INTEGER} .
1938 @item @var{N1} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1939 @item @var{N2} @tab Shall be a non-negative scalar of type  @code{INTEGER}.
1940 @item @var{X} @tab Shall be a scalar or an array of type  @code{REAL};
1941 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1942 @end multitable
1943
1944 @item @emph{Return value}:
1945 The return value is a scalar of type @code{REAL}. It has the same
1946 kind as @var{X}.
1947
1948 @item @emph{Note}:
1949 The transformational function uses a recurrence algorithm which might,
1950 for some values of @var{X}, lead to different results than calls to
1951 the elemental function.
1952
1953 @item @emph{Example}:
1954 @smallexample
1955 program test_besyn
1956   real(8) :: x = 1.0_8
1957   x = bessel_yn(5,x)
1958 end program test_besyn
1959 @end smallexample
1960
1961 @item @emph{Specific names}:
1962 @multitable @columnfractions .20 .20 .20 .25
1963 @item Name               @tab Argument            @tab Return type     @tab Standard
1964 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)}  @tab GNU extension
1965 @item                    @tab @code{REAL(8) X} @tab                 @tab
1966 @end multitable
1967 @end table
1968
1969
1970
1971 @node BGE
1972 @section @code{BGE} --- Bitwise greater than or equal to
1973 @fnindex BGE
1974 @cindex bitwise comparison
1975
1976 @table @asis
1977 @item @emph{Description}:
1978 Determines whether an integral is a bitwise greater than or equal to
1979 another.
1980
1981 @item @emph{Standard}:
1982 Fortran 2008 and later
1983
1984 @item @emph{Class}:
1985 Elemental function
1986
1987 @item @emph{Syntax}:
1988 @code{RESULT = BGE(I, J)}
1989
1990 @item @emph{Arguments}:
1991 @multitable @columnfractions .15 .70
1992 @item @var{I} @tab Shall be of @code{INTEGER} type.
1993 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1994 as @var{I}.
1995 @end multitable
1996
1997 @item @emph{Return value}:
1998 The return value is of type @code{LOGICAL} and of the default kind.
1999
2000 @item @emph{See also}:
2001 @ref{BGT}, @ref{BLE}, @ref{BLT}
2002 @end table
2003
2004
2005
2006 @node BGT
2007 @section @code{BGT} --- Bitwise greater than
2008 @fnindex BGT
2009 @cindex bitwise comparison
2010
2011 @table @asis
2012 @item @emph{Description}:
2013 Determines whether an integral is a bitwise greater than another.
2014
2015 @item @emph{Standard}:
2016 Fortran 2008 and later
2017
2018 @item @emph{Class}:
2019 Elemental function
2020
2021 @item @emph{Syntax}:
2022 @code{RESULT = BGT(I, J)}
2023
2024 @item @emph{Arguments}:
2025 @multitable @columnfractions .15 .70
2026 @item @var{I} @tab Shall be of @code{INTEGER} type.
2027 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2028 as @var{I}.
2029 @end multitable
2030
2031 @item @emph{Return value}:
2032 The return value is of type @code{LOGICAL} and of the default kind.
2033
2034 @item @emph{See also}:
2035 @ref{BGE}, @ref{BLE}, @ref{BLT}
2036 @end table
2037
2038
2039
2040 @node BIT_SIZE
2041 @section @code{BIT_SIZE} --- Bit size inquiry function
2042 @fnindex BIT_SIZE
2043 @cindex bits, number of
2044 @cindex size of a variable, in bits
2045
2046 @table @asis
2047 @item @emph{Description}:
2048 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2049 represented by the type of @var{I}.  The result of @code{BIT_SIZE(I)} is
2050 independent of the actual value of @var{I}.
2051
2052 @item @emph{Standard}:
2053 Fortran 95 and later
2054
2055 @item @emph{Class}:
2056 Inquiry function
2057
2058 @item @emph{Syntax}:
2059 @code{RESULT = BIT_SIZE(I)}
2060
2061 @item @emph{Arguments}:
2062 @multitable @columnfractions .15 .70
2063 @item @var{I} @tab The type shall be @code{INTEGER}.
2064 @end multitable
2065
2066 @item @emph{Return value}:
2067 The return value is of type @code{INTEGER}
2068
2069 @item @emph{Example}:
2070 @smallexample
2071 program test_bit_size
2072     integer :: i = 123
2073     integer :: size
2074     size = bit_size(i)
2075     print *, size
2076 end program test_bit_size
2077 @end smallexample
2078 @end table
2079
2080
2081
2082 @node BLE
2083 @section @code{BLE} --- Bitwise less than or equal to
2084 @fnindex BLE
2085 @cindex bitwise comparison
2086
2087 @table @asis
2088 @item @emph{Description}:
2089 Determines whether an integral is a bitwise less than or equal to
2090 another.
2091
2092 @item @emph{Standard}:
2093 Fortran 2008 and later
2094
2095 @item @emph{Class}:
2096 Elemental function
2097
2098 @item @emph{Syntax}:
2099 @code{RESULT = BLE(I, J)}
2100
2101 @item @emph{Arguments}:
2102 @multitable @columnfractions .15 .70
2103 @item @var{I} @tab Shall be of @code{INTEGER} type.
2104 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2105 as @var{I}.
2106 @end multitable
2107
2108 @item @emph{Return value}:
2109 The return value is of type @code{LOGICAL} and of the default kind.
2110
2111 @item @emph{See also}:
2112 @ref{BGT}, @ref{BGE}, @ref{BLT}
2113 @end table
2114
2115
2116
2117 @node BLT
2118 @section @code{BLT} --- Bitwise less than
2119 @fnindex BLT
2120 @cindex bitwise comparison
2121
2122 @table @asis
2123 @item @emph{Description}:
2124 Determines whether an integral is a bitwise less than another.
2125
2126 @item @emph{Standard}:
2127 Fortran 2008 and later
2128
2129 @item @emph{Class}:
2130 Elemental function
2131
2132 @item @emph{Syntax}:
2133 @code{RESULT = BLT(I, J)}
2134
2135 @item @emph{Arguments}:
2136 @multitable @columnfractions .15 .70
2137 @item @var{I} @tab Shall be of @code{INTEGER} type.
2138 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2139 as @var{I}.
2140 @end multitable
2141
2142 @item @emph{Return value}:
2143 The return value is of type @code{LOGICAL} and of the default kind.
2144
2145 @item @emph{See also}:
2146 @ref{BGE}, @ref{BGT}, @ref{BLE}
2147 @end table
2148
2149
2150
2151 @node BTEST
2152 @section @code{BTEST} --- Bit test function
2153 @fnindex BTEST
2154 @cindex bits, testing
2155
2156 @table @asis
2157 @item @emph{Description}:
2158 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2159 in @var{I} is set.  The counting of the bits starts at 0.
2160
2161 @item @emph{Standard}:
2162 Fortran 95 and later
2163
2164 @item @emph{Class}:
2165 Elemental function
2166
2167 @item @emph{Syntax}:
2168 @code{RESULT = BTEST(I, POS)}
2169
2170 @item @emph{Arguments}:
2171 @multitable @columnfractions .15 .70
2172 @item @var{I} @tab The type shall be @code{INTEGER}.
2173 @item @var{POS} @tab The type shall be @code{INTEGER}.
2174 @end multitable
2175
2176 @item @emph{Return value}:
2177 The return value is of type @code{LOGICAL}
2178
2179 @item @emph{Example}:
2180 @smallexample
2181 program test_btest
2182     integer :: i = 32768 + 1024 + 64
2183     integer :: pos
2184     logical :: bool
2185     do pos=0,16
2186         bool = btest(i, pos)
2187         print *, pos, bool
2188     end do
2189 end program test_btest
2190 @end smallexample
2191 @end table
2192
2193
2194 @node C_ASSOCIATED
2195 @section @code{C_ASSOCIATED} --- Status of a C pointer
2196 @fnindex C_ASSOCIATED
2197 @cindex association status, C pointer
2198 @cindex pointer, C association status
2199
2200 @table @asis
2201 @item @emph{Description}:
2202 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2203 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2204
2205 @item @emph{Standard}:
2206 Fortran 2003 and later
2207
2208 @item @emph{Class}:
2209 Inquiry function
2210
2211 @item @emph{Syntax}:
2212 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2213
2214 @item @emph{Arguments}:
2215 @multitable @columnfractions .15 .70
2216 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2217 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2218 @end multitable
2219
2220 @item @emph{Return value}:
2221 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2222 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2223 point to different addresses.
2224
2225 @item @emph{Example}:
2226 @smallexample
2227 subroutine association_test(a,b)
2228   use iso_c_binding, only: c_associated, c_loc, c_ptr
2229   implicit none
2230   real, pointer :: a
2231   type(c_ptr) :: b
2232   if(c_associated(b, c_loc(a))) &
2233      stop 'b and a do not point to same target'
2234 end subroutine association_test
2235 @end smallexample
2236
2237 @item @emph{See also}:
2238 @ref{C_LOC}, @ref{C_FUNLOC}
2239 @end table
2240
2241
2242 @node C_FUNLOC
2243 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2244 @fnindex C_FUNLOC
2245 @cindex pointer, C address of procedures
2246
2247 @table @asis
2248 @item @emph{Description}:
2249 @code{C_FUNLOC(x)} determines the C address of the argument.
2250
2251 @item @emph{Standard}:
2252 Fortran 2003 and later
2253
2254 @item @emph{Class}:
2255 Inquiry function
2256
2257 @item @emph{Syntax}:
2258 @code{RESULT = C_FUNLOC(x)}
2259
2260 @item @emph{Arguments}:
2261 @multitable @columnfractions .15 .70
2262 @item @var{x} @tab Interoperable function or pointer to such function.
2263 @end multitable
2264
2265 @item @emph{Return value}:
2266 The return value is of type @code{C_FUNPTR} and contains the C address
2267 of the argument.
2268
2269 @item @emph{Example}:
2270 @smallexample
2271 module x
2272   use iso_c_binding
2273   implicit none
2274 contains
2275   subroutine sub(a) bind(c)
2276     real(c_float) :: a
2277     a = sqrt(a)+5.0
2278   end subroutine sub
2279 end module x
2280 program main
2281   use iso_c_binding
2282   use x
2283   implicit none
2284   interface
2285     subroutine my_routine(p) bind(c,name='myC_func')
2286       import :: c_funptr
2287       type(c_funptr), intent(in) :: p
2288     end subroutine
2289   end interface
2290   call my_routine(c_funloc(sub))
2291 end program main
2292 @end smallexample
2293
2294 @item @emph{See also}:
2295 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2296 @end table
2297
2298
2299 @node C_F_PROCPOINTER
2300 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2301 @fnindex C_F_PROCPOINTER
2302 @cindex pointer, C address of pointers
2303
2304 @table @asis
2305 @item @emph{Description}:
2306 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2307 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2308
2309 @item @emph{Standard}:
2310 Fortran 2003 and later
2311
2312 @item @emph{Class}:
2313 Subroutine
2314
2315 @item @emph{Syntax}:
2316 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2317
2318 @item @emph{Arguments}:
2319 @multitable @columnfractions .15 .70
2320 @item @var{CPTR}  @tab scalar of the type @code{C_FUNPTR}. It is
2321 @code{INTENT(IN)}.
2322 @item @var{FPTR}  @tab procedure pointer interoperable with @var{cptr}. It is
2323 @code{INTENT(OUT)}.
2324 @end multitable
2325
2326 @item @emph{Example}:
2327 @smallexample
2328 program main
2329   use iso_c_binding
2330   implicit none
2331   abstract interface
2332     function func(a)
2333       import :: c_float
2334       real(c_float), intent(in) :: a
2335       real(c_float) :: func
2336     end function
2337   end interface
2338   interface
2339      function getIterFunc() bind(c,name="getIterFunc")
2340        import :: c_funptr
2341        type(c_funptr) :: getIterFunc
2342      end function
2343   end interface
2344   type(c_funptr) :: cfunptr
2345   procedure(func), pointer :: myFunc
2346   cfunptr = getIterFunc()
2347   call c_f_procpointer(cfunptr, myFunc)
2348 end program main
2349 @end smallexample
2350
2351 @item @emph{See also}:
2352 @ref{C_LOC}, @ref{C_F_POINTER}
2353 @end table
2354
2355
2356 @node C_F_POINTER
2357 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2358 @fnindex C_F_POINTER
2359 @cindex pointer, convert C to Fortran
2360
2361 @table @asis
2362 @item @emph{Description}:
2363 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2364 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2365 shape.
2366
2367 @item @emph{Standard}:
2368 Fortran 2003 and later
2369
2370 @item @emph{Class}:
2371 Subroutine
2372
2373 @item @emph{Syntax}:
2374 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2375
2376 @item @emph{Arguments}:
2377 @multitable @columnfractions .15 .70
2378 @item @var{CPTR}  @tab scalar of the type @code{C_PTR}. It is
2379 @code{INTENT(IN)}.
2380 @item @var{FPTR}  @tab pointer interoperable with @var{cptr}. It is
2381 @code{INTENT(OUT)}.
2382 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2383 with @code{INTENT(IN)}. It shall be present
2384 if and only if @var{fptr} is an array. The size
2385 must be equal to the rank of @var{fptr}.
2386 @end multitable
2387
2388 @item @emph{Example}:
2389 @smallexample
2390 program main
2391   use iso_c_binding
2392   implicit none
2393   interface
2394     subroutine my_routine(p) bind(c,name='myC_func')
2395       import :: c_ptr
2396       type(c_ptr), intent(out) :: p
2397     end subroutine
2398   end interface
2399   type(c_ptr) :: cptr
2400   real,pointer :: a(:)
2401   call my_routine(cptr)
2402   call c_f_pointer(cptr, a, [12])
2403 end program main
2404 @end smallexample
2405
2406 @item @emph{See also}:
2407 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2408 @end table
2409
2410
2411 @node C_LOC
2412 @section @code{C_LOC} --- Obtain the C address of an object
2413 @fnindex C_LOC
2414 @cindex procedure pointer, convert C to Fortran
2415
2416 @table @asis
2417 @item @emph{Description}:
2418 @code{C_LOC(X)} determines the C address of the argument.
2419
2420 @item @emph{Standard}:
2421 Fortran 2003 and later
2422
2423 @item @emph{Class}:
2424 Inquiry function
2425
2426 @item @emph{Syntax}:
2427 @code{RESULT = C_LOC(X)}
2428
2429 @item @emph{Arguments}:
2430 @multitable @columnfractions .10 .75
2431 @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.
2432
2433 @end multitable
2434
2435 @item @emph{Return value}:
2436 The return value is of type @code{C_PTR} and contains the C address
2437 of the argument.
2438
2439 @item @emph{Example}:
2440 @smallexample
2441 subroutine association_test(a,b)
2442   use iso_c_binding, only: c_associated, c_loc, c_ptr
2443   implicit none
2444   real, pointer :: a
2445   type(c_ptr) :: b
2446   if(c_associated(b, c_loc(a))) &
2447      stop 'b and a do not point to same target'
2448 end subroutine association_test
2449 @end smallexample
2450
2451 @item @emph{See also}:
2452 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2453 @end table
2454
2455
2456 @node C_SIZEOF
2457 @section @code{C_SIZEOF} --- Size in bytes of an expression
2458 @fnindex C_SIZEOF
2459 @cindex expression size
2460 @cindex size of an expression
2461
2462 @table @asis
2463 @item @emph{Description}:
2464 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2465 expression @code{X} occupies.
2466
2467 @item @emph{Standard}:
2468 Fortran 2008
2469
2470 @item @emph{Class}:
2471 Inquiry function of the module @code{ISO_C_BINDING}
2472
2473 @item @emph{Syntax}:
2474 @code{N = C_SIZEOF(X)}
2475
2476 @item @emph{Arguments}:
2477 @multitable @columnfractions .15 .70
2478 @item @var{X} @tab The argument shall be an interoperable data entity.
2479 @end multitable
2480
2481 @item @emph{Return value}:
2482 The return value is of type integer and of the system-dependent kind
2483 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2484 number of bytes occupied by the argument.  If the argument has the
2485 @code{POINTER} attribute, the number of bytes of the storage area pointed
2486 to is returned.  If the argument is of a derived type with @code{POINTER}
2487 or @code{ALLOCATABLE} components, the return value doesn't account for
2488 the sizes of the data pointed to by these components.
2489
2490 @item @emph{Example}:
2491 @smallexample
2492    use iso_c_binding
2493    integer(c_int) :: i
2494    real(c_float) :: r, s(5)
2495    print *, (c_sizeof(s)/c_sizeof(r) == 5)
2496    end
2497 @end smallexample
2498 The example will print @code{.TRUE.} unless you are using a platform
2499 where default @code{REAL} variables are unusually padded.
2500
2501 @item @emph{See also}:
2502 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2503 @end table
2504
2505
2506 @node CEILING
2507 @section @code{CEILING} --- Integer ceiling function
2508 @fnindex CEILING
2509 @cindex ceiling
2510 @cindex rounding, ceiling
2511
2512 @table @asis
2513 @item @emph{Description}:
2514 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2515
2516 @item @emph{Standard}:
2517 Fortran 95 and later
2518
2519 @item @emph{Class}:
2520 Elemental function
2521
2522 @item @emph{Syntax}:
2523 @code{RESULT = CEILING(A [, KIND])}
2524
2525 @item @emph{Arguments}:
2526 @multitable @columnfractions .15 .70
2527 @item @var{A} @tab The type shall be @code{REAL}.
2528 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2529 expression indicating the kind parameter of the result.
2530 @end multitable
2531
2532 @item @emph{Return value}:
2533 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2534 and a default-kind @code{INTEGER} otherwise.
2535
2536 @item @emph{Example}:
2537 @smallexample
2538 program test_ceiling
2539     real :: x = 63.29
2540     real :: y = -63.59
2541     print *, ceiling(x) ! returns 64
2542     print *, ceiling(y) ! returns -63
2543 end program test_ceiling
2544 @end smallexample
2545
2546 @item @emph{See also}:
2547 @ref{FLOOR}, @ref{NINT}
2548
2549 @end table
2550
2551
2552
2553 @node CHAR
2554 @section @code{CHAR} --- Character conversion function
2555 @fnindex CHAR
2556 @cindex conversion, to character
2557
2558 @table @asis
2559 @item @emph{Description}:
2560 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2561
2562 @item @emph{Standard}:
2563 Fortran 77 and later
2564
2565 @item @emph{Class}:
2566 Elemental function
2567
2568 @item @emph{Syntax}:
2569 @code{RESULT = CHAR(I [, KIND])}
2570
2571 @item @emph{Arguments}:
2572 @multitable @columnfractions .15 .70
2573 @item @var{I} @tab The type shall be @code{INTEGER}.
2574 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2575 expression indicating the kind parameter of the result.
2576 @end multitable
2577
2578 @item @emph{Return value}:
2579 The return value is of type @code{CHARACTER(1)}
2580
2581 @item @emph{Example}:
2582 @smallexample
2583 program test_char
2584     integer :: i = 74
2585     character(1) :: c
2586     c = char(i)
2587     print *, i, c ! returns 'J'
2588 end program test_char
2589 @end smallexample
2590
2591 @item @emph{Specific names}:
2592 @multitable @columnfractions .20 .20 .20 .25
2593 @item Name           @tab Argument         @tab Return type             @tab Standard
2594 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2595 @end multitable
2596
2597 @item @emph{Note}:
2598 See @ref{ICHAR} for a discussion of converting between numerical values
2599 and formatted string representations.
2600
2601 @item @emph{See also}:
2602 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2603
2604 @end table
2605
2606
2607
2608 @node CHDIR
2609 @section @code{CHDIR} --- Change working directory
2610 @fnindex CHDIR
2611 @cindex system, working directory
2612
2613 @table @asis
2614 @item @emph{Description}:
2615 Change current working directory to a specified path.
2616
2617 This intrinsic is provided in both subroutine and function forms; however,
2618 only one form can be used in any given program unit.
2619
2620 @item @emph{Standard}:
2621 GNU extension
2622
2623 @item @emph{Class}:
2624 Subroutine, function
2625
2626 @item @emph{Syntax}:
2627 @multitable @columnfractions .80
2628 @item @code{CALL CHDIR(NAME [, STATUS])}
2629 @item @code{STATUS = CHDIR(NAME)}
2630 @end multitable
2631
2632 @item @emph{Arguments}:
2633 @multitable @columnfractions .15 .70
2634 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of default
2635 kind and shall specify a valid path within the file system.
2636 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2637 kind.  Returns 0 on success, and a system specific and nonzero error code
2638 otherwise.
2639 @end multitable
2640
2641 @item @emph{Example}:
2642 @smallexample
2643 PROGRAM test_chdir
2644   CHARACTER(len=255) :: path
2645   CALL getcwd(path)
2646   WRITE(*,*) TRIM(path)
2647   CALL chdir("/tmp")
2648   CALL getcwd(path)
2649   WRITE(*,*) TRIM(path)
2650 END PROGRAM
2651 @end smallexample
2652
2653 @item @emph{See also}:
2654 @ref{GETCWD}
2655 @end table
2656
2657
2658
2659 @node CHMOD
2660 @section @code{CHMOD} --- Change access permissions of files
2661 @fnindex CHMOD
2662 @cindex file system, change access mode
2663
2664 @table @asis
2665 @item @emph{Description}:
2666 @code{CHMOD} changes the permissions of a file. This function invokes
2667 @code{/bin/chmod} and might therefore not work on all platforms.
2668
2669 This intrinsic is provided in both subroutine and function forms; however,
2670 only one form can be used in any given program unit.
2671
2672 @item @emph{Standard}:
2673 GNU extension
2674
2675 @item @emph{Class}:
2676 Subroutine, function
2677
2678 @item @emph{Syntax}:
2679 @multitable @columnfractions .80
2680 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2681 @item @code{STATUS = CHMOD(NAME, MODE)}
2682 @end multitable
2683
2684 @item @emph{Arguments}:
2685 @multitable @columnfractions .15 .70
2686
2687 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2688 file name. Trailing blanks are ignored unless the character
2689 @code{achar(0)} is present, then all characters up to and excluding
2690 @code{achar(0)} are used as the file name.
2691
2692 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2693 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2694 argument of @code{/bin/chmod}.
2695
2696 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2697 @code{0} on success and nonzero otherwise.
2698 @end multitable
2699
2700 @item @emph{Return value}:
2701 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2702 otherwise.
2703
2704 @item @emph{Example}:
2705 @code{CHMOD} as subroutine
2706 @smallexample
2707 program chmod_test
2708   implicit none
2709   integer :: status
2710   call chmod('test.dat','u+x',status)
2711   print *, 'Status: ', status
2712 end program chmod_test
2713 @end smallexample
2714 @code{CHMOD} as function:
2715 @smallexample
2716 program chmod_test
2717   implicit none
2718   integer :: status
2719   status = chmod('test.dat','u+x')
2720   print *, 'Status: ', status
2721 end program chmod_test
2722 @end smallexample
2723
2724 @end table
2725
2726
2727
2728 @node CMPLX
2729 @section @code{CMPLX} --- Complex conversion function
2730 @fnindex CMPLX
2731 @cindex complex numbers, conversion to
2732 @cindex conversion, to complex
2733
2734 @table @asis
2735 @item @emph{Description}:
2736 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2737 the real component.  If @var{Y} is present it is converted to the imaginary
2738 component.  If @var{Y} is not present then the imaginary component is set to
2739 0.0.  If @var{X} is complex then @var{Y} must not be present.
2740
2741 @item @emph{Standard}:
2742 Fortran 77 and later
2743
2744 @item @emph{Class}:
2745 Elemental function
2746
2747 @item @emph{Syntax}:
2748 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2749
2750 @item @emph{Arguments}:
2751 @multitable @columnfractions .15 .70
2752 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2753 or @code{COMPLEX}.
2754 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2755 @code{COMPLEX}.)  May be @code{INTEGER} or @code{REAL}.
2756 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2757 expression indicating the kind parameter of the result.
2758 @end multitable
2759
2760 @item @emph{Return value}:
2761 The return value is of @code{COMPLEX} type, with a kind equal to
2762 @var{KIND} if it is specified.  If @var{KIND} is not specified, the
2763 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2764 @var{X} and @var{Y}.
2765
2766 @item @emph{Example}:
2767 @smallexample
2768 program test_cmplx
2769     integer :: i = 42
2770     real :: x = 3.14
2771     complex :: z
2772     z = cmplx(i, x)
2773     print *, z, cmplx(x)
2774 end program test_cmplx
2775 @end smallexample
2776
2777 @item @emph{See also}:
2778 @ref{COMPLEX}
2779 @end table
2780
2781
2782
2783 @node COMMAND_ARGUMENT_COUNT
2784 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2785 @fnindex COMMAND_ARGUMENT_COUNT
2786 @cindex command-line arguments
2787 @cindex command-line arguments, number of
2788 @cindex arguments, to program
2789
2790 @table @asis
2791 @item @emph{Description}:
2792 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2793 command line when the containing program was invoked.
2794
2795 @item @emph{Standard}:
2796 Fortran 2003 and later
2797
2798 @item @emph{Class}:
2799 Inquiry function
2800
2801 @item @emph{Syntax}:
2802 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2803
2804 @item @emph{Arguments}:
2805 @multitable @columnfractions .15 .70
2806 @item None
2807 @end multitable
2808
2809 @item @emph{Return value}:
2810 The return value is an @code{INTEGER} of default kind.
2811
2812 @item @emph{Example}:
2813 @smallexample
2814 program test_command_argument_count
2815     integer :: count
2816     count = command_argument_count()
2817     print *, count
2818 end program test_command_argument_count
2819 @end smallexample
2820
2821 @item @emph{See also}:
2822 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2823 @end table
2824
2825
2826
2827 @node COMPILER_OPTIONS
2828 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2829 @fnindex COMPILER_OPTIONS
2830 @cindex flags inquiry function
2831 @cindex options inquiry function
2832 @cindex compiler flags inquiry function
2833
2834 @table @asis
2835 @item @emph{Description}:
2836 @code{COMPILER_OPTIONS} returns a string with the options used for
2837 compiling.
2838
2839 @item @emph{Standard}:
2840 Fortran 2008
2841
2842 @item @emph{Class}:
2843 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2844
2845 @item @emph{Syntax}:
2846 @code{STR = COMPILER_OPTIONS()}
2847
2848 @item @emph{Arguments}:
2849 None.
2850
2851 @item @emph{Return value}:
2852 The return value is a default-kind string with system-dependent length.
2853 It contains the compiler flags used to compile the file, which called
2854 the @code{COMPILER_OPTIONS} intrinsic.
2855
2856 @item @emph{Example}:
2857 @smallexample
2858    use iso_fortran_env
2859    print '(4a)', 'This file was compiled by ', &
2860                  compiler_version(), ' using the options ', &
2861                  compiler_options()
2862    end
2863 @end smallexample
2864
2865 @item @emph{See also}:
2866 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2867 @end table
2868
2869
2870
2871 @node COMPILER_VERSION
2872 @section @code{COMPILER_VERSION} --- Compiler version string
2873 @fnindex COMPILER_VERSION
2874 @cindex compiler, name and version
2875 @cindex version of the compiler
2876
2877 @table @asis
2878 @item @emph{Description}:
2879 @code{COMPILER_VERSION} returns a string with the name and the
2880 version of the compiler.
2881
2882 @item @emph{Standard}:
2883 Fortran 2008
2884
2885 @item @emph{Class}:
2886 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2887
2888 @item @emph{Syntax}:
2889 @code{STR = COMPILER_VERSION()}
2890
2891 @item @emph{Arguments}:
2892 None.
2893
2894 @item @emph{Return value}:
2895 The return value is a default-kind string with system-dependent length.
2896 It contains the name of the compiler and its version number.
2897
2898 @item @emph{Example}:
2899 @smallexample
2900    use iso_fortran_env
2901    print '(4a)', 'This file was compiled by ', &
2902                  compiler_version(), ' using the options ', &
2903                  compiler_options()
2904    end
2905 @end smallexample
2906
2907 @item @emph{See also}:
2908 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2909 @end table
2910
2911
2912
2913 @node COMPLEX
2914 @section @code{COMPLEX} --- Complex conversion function
2915 @fnindex COMPLEX
2916 @cindex complex numbers, conversion to
2917 @cindex conversion, to complex
2918
2919 @table @asis
2920 @item @emph{Description}:
2921 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2922 to the real component and @var{Y} is converted to the imaginary
2923 component.
2924
2925 @item @emph{Standard}:
2926 GNU extension
2927
2928 @item @emph{Class}:
2929 Elemental function
2930
2931 @item @emph{Syntax}:
2932 @code{RESULT = COMPLEX(X, Y)}
2933
2934 @item @emph{Arguments}:
2935 @multitable @columnfractions .15 .70
2936 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2937 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2938 @end multitable
2939
2940 @item @emph{Return value}:
2941 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2942 value is of default @code{COMPLEX} type.
2943
2944 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2945 type and one is of @code{INTEGER} type, then the return value is of
2946 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2947 argument with the highest precision.
2948
2949 @item @emph{Example}:
2950 @smallexample
2951 program test_complex
2952     integer :: i = 42
2953     real :: x = 3.14
2954     print *, complex(i, x)
2955 end program test_complex
2956 @end smallexample
2957
2958 @item @emph{See also}:
2959 @ref{CMPLX}
2960 @end table
2961
2962
2963
2964 @node CONJG
2965 @section @code{CONJG} --- Complex conjugate function
2966 @fnindex CONJG
2967 @fnindex DCONJG
2968 @cindex complex conjugate
2969
2970 @table @asis
2971 @item @emph{Description}:
2972 @code{CONJG(Z)} returns the conjugate of @var{Z}.  If @var{Z} is @code{(x, y)}
2973 then the result is @code{(x, -y)}
2974
2975 @item @emph{Standard}:
2976 Fortran 77 and later, has overloads that are GNU extensions
2977
2978 @item @emph{Class}:
2979 Elemental function
2980
2981 @item @emph{Syntax}:
2982 @code{Z = CONJG(Z)}
2983
2984 @item @emph{Arguments}:
2985 @multitable @columnfractions .15 .70
2986 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2987 @end multitable
2988
2989 @item @emph{Return value}:
2990 The return value is of type @code{COMPLEX}.
2991
2992 @item @emph{Example}:
2993 @smallexample
2994 program test_conjg
2995     complex :: z = (2.0, 3.0)
2996     complex(8) :: dz = (2.71_8, -3.14_8)
2997     z= conjg(z)
2998     print *, z
2999     dz = dconjg(dz)
3000     print *, dz
3001 end program test_conjg
3002 @end smallexample
3003
3004 @item @emph{Specific names}:
3005 @multitable @columnfractions .20 .20 .20 .25
3006 @item Name             @tab Argument             @tab Return type       @tab Standard
3007 @item @code{CONJG(Z)}  @tab @code{COMPLEX Z}     @tab @code{COMPLEX}    @tab GNU extension
3008 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z}  @tab @code{COMPLEX(8)} @tab GNU extension
3009 @end multitable
3010 @end table
3011
3012
3013
3014 @node COS
3015 @section @code{COS} --- Cosine function
3016 @fnindex COS
3017 @fnindex DCOS
3018 @fnindex CCOS
3019 @fnindex ZCOS
3020 @fnindex CDCOS
3021 @cindex trigonometric function, cosine
3022 @cindex cosine
3023
3024 @table @asis
3025 @item @emph{Description}:
3026 @code{COS(X)} computes the cosine of @var{X}.
3027
3028 @item @emph{Standard}:
3029 Fortran 77 and later, has overloads that are GNU extensions
3030
3031 @item @emph{Class}:
3032 Elemental function
3033
3034 @item @emph{Syntax}:
3035 @code{RESULT = COS(X)}
3036
3037 @item @emph{Arguments}:
3038 @multitable @columnfractions .15 .70
3039 @item @var{X} @tab The type shall be @code{REAL} or
3040 @code{COMPLEX}.
3041 @end multitable
3042
3043 @item @emph{Return value}:
3044 The return value is of the same type and kind as @var{X}. The real part
3045 of the result is in radians. If @var{X} is of the type @code{REAL},
3046 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3047
3048 @item @emph{Example}:
3049 @smallexample
3050 program test_cos
3051   real :: x = 0.0
3052   x = cos(x)
3053 end program test_cos
3054 @end smallexample
3055
3056 @item @emph{Specific names}:
3057 @multitable @columnfractions .20 .20 .20 .25
3058 @item Name            @tab Argument            @tab Return type       @tab Standard
3059 @item @code{COS(X)}   @tab @code{REAL(4) X}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3060 @item @code{DCOS(X)}  @tab @code{REAL(8) X}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3061 @item @code{CCOS(X)}  @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3062 @item @code{ZCOS(X)}  @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3063 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3064 @end multitable
3065
3066 @item @emph{See also}:
3067 Inverse function: @ref{ACOS}
3068
3069 @end table
3070
3071
3072
3073 @node COSH
3074 @section @code{COSH} --- Hyperbolic cosine function
3075 @fnindex COSH
3076 @fnindex DCOSH
3077 @cindex hyperbolic cosine
3078 @cindex hyperbolic function, cosine
3079 @cindex cosine, hyperbolic
3080
3081 @table @asis
3082 @item @emph{Description}:
3083 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3084
3085 @item @emph{Standard}:
3086 Fortran 77 and later, for a complex argument Fortran 2008 or later
3087
3088 @item @emph{Class}:
3089 Elemental function
3090
3091 @item @emph{Syntax}:
3092 @code{X = COSH(X)}
3093
3094 @item @emph{Arguments}:
3095 @multitable @columnfractions .15 .70
3096 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3097 @end multitable
3098
3099 @item @emph{Return value}:
3100 The return value has same type and kind as @var{X}. If @var{X} is
3101 complex, the imaginary part of the result is in radians. If @var{X}
3102 is @code{REAL}, the return value has a lower bound of one,
3103 @math{\cosh (x) \geq 1}.
3104
3105 @item @emph{Example}:
3106 @smallexample
3107 program test_cosh
3108   real(8) :: x = 1.0_8
3109   x = cosh(x)
3110 end program test_cosh
3111 @end smallexample
3112
3113 @item @emph{Specific names}:
3114 @multitable @columnfractions .20 .20 .20 .25
3115 @item Name            @tab Argument          @tab Return type       @tab Standard
3116 @item @code{COSH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 77 and later
3117 @item @code{DCOSH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 77 and later
3118 @end multitable
3119
3120 @item @emph{See also}:
3121 Inverse function: @ref{ACOSH}
3122
3123 @end table
3124
3125
3126
3127 @node COUNT
3128 @section @code{COUNT} --- Count function
3129 @fnindex COUNT
3130 @cindex array, conditionally count elements
3131 @cindex array, element counting
3132 @cindex array, number of elements
3133
3134 @table @asis
3135 @item @emph{Description}:
3136
3137 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3138 or, if the @var{DIM} argument is supplied, counts the number of
3139 elements along each row of the array in the @var{DIM} direction.
3140 If the array has zero size, or all of the elements of @var{MASK} are
3141 @code{.FALSE.}, then the result is @code{0}.
3142
3143 @item @emph{Standard}:
3144 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3145
3146 @item @emph{Class}:
3147 Transformational function
3148
3149 @item @emph{Syntax}:
3150 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3151
3152 @item @emph{Arguments}:
3153 @multitable @columnfractions .15 .70
3154 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3155 @item @var{DIM}  @tab (Optional) The type shall be @code{INTEGER}.
3156 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3157 expression indicating the kind parameter of the result.
3158 @end multitable
3159
3160 @item @emph{Return value}:
3161 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3162 @var{KIND} is absent, the return value is of default integer kind.
3163 If @var{DIM} is present, the result is an array with a rank one less
3164 than the rank of @var{ARRAY}, and a size corresponding to the shape
3165 of @var{ARRAY} with the @var{DIM} dimension removed.
3166
3167 @item @emph{Example}:
3168 @smallexample
3169 program test_count
3170     integer, dimension(2,3) :: a, b
3171     logical, dimension(2,3) :: mask
3172     a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3173     b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3174     print '(3i3)', a(1,:)
3175     print '(3i3)', a(2,:)
3176     print *
3177     print '(3i3)', b(1,:)
3178     print '(3i3)', b(2,:)
3179     print *
3180     mask = a.ne.b
3181     print '(3l3)', mask(1,:)
3182     print '(3l3)', mask(2,:)
3183     print *
3184     print '(3i3)', count(mask)
3185     print *
3186     print '(3i3)', count(mask, 1)
3187     print *
3188     print '(3i3)', count(mask, 2)
3189 end program test_count
3190 @end smallexample
3191 @end table
3192
3193
3194
3195 @node CPU_TIME
3196 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3197 @fnindex CPU_TIME
3198 @cindex time, elapsed
3199
3200 @table @asis
3201 @item @emph{Description}:
3202 Returns a @code{REAL} value representing the elapsed CPU time in
3203 seconds.  This is useful for testing segments of code to determine
3204 execution time.
3205
3206 If a time source is available, time will be reported with microsecond
3207 resolution. If no time source is available, @var{TIME} is set to
3208 @code{-1.0}.
3209
3210 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3211 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3212 value is meaningless, only differences between subsequent calls to
3213 this subroutine, as shown in the example below, should be used.
3214
3215
3216 @item @emph{Standard}:
3217 Fortran 95 and later
3218
3219 @item @emph{Class}:
3220 Subroutine
3221
3222 @item @emph{Syntax}:
3223 @code{CALL CPU_TIME(TIME)}
3224
3225 @item @emph{Arguments}:
3226 @multitable @columnfractions .15 .70
3227 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3228 @end multitable
3229
3230 @item @emph{Return value}:
3231 None
3232
3233 @item @emph{Example}:
3234 @smallexample
3235 program test_cpu_time
3236     real :: start, finish
3237     call cpu_time(start)
3238         ! put code to test here
3239     call cpu_time(finish)
3240     print '("Time = ",f6.3," seconds.")',finish-start
3241 end program test_cpu_time
3242 @end smallexample
3243
3244 @item @emph{See also}:
3245 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3246 @end table
3247
3248
3249
3250 @node CSHIFT
3251 @section @code{CSHIFT} --- Circular shift elements of an array
3252 @fnindex CSHIFT
3253 @cindex array, shift circularly
3254 @cindex array, permutation
3255 @cindex array, rotate
3256
3257 @table @asis
3258 @item @emph{Description}:
3259 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3260 @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is omitted it is
3261 taken to be @code{1}.  @var{DIM} is a scalar of type @code{INTEGER} in the
3262 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3263 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3264 by @var{SHIFT} places.  If rank is greater than one, then all complete rank one
3265 sections of @var{ARRAY} along the given dimension are shifted.  Elements
3266 shifted out one end of each rank one section are shifted back in the other end.
3267
3268 @item @emph{Standard}:
3269 Fortran 95 and later
3270
3271 @item @emph{Class}:
3272 Transformational function
3273
3274 @item @emph{Syntax}:
3275 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3276
3277 @item @emph{Arguments}:
3278 @multitable @columnfractions .15 .70
3279 @item @var{ARRAY}  @tab Shall be an array of any type.
3280 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3281 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3282 @end multitable
3283
3284 @item @emph{Return value}:
3285 Returns an array of same type and rank as the @var{ARRAY} argument.
3286
3287 @item @emph{Example}:
3288 @smallexample
3289 program test_cshift
3290     integer, dimension(3,3) :: a
3291     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3292     print '(3i3)', a(1,:)
3293     print '(3i3)', a(2,:)
3294     print '(3i3)', a(3,:)
3295     a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3296     print *
3297     print '(3i3)', a(1,:)
3298     print '(3i3)', a(2,:)
3299     print '(3i3)', a(3,:)
3300 end program test_cshift
3301 @end smallexample
3302 @end table
3303
3304
3305
3306 @node CTIME
3307 @section @code{CTIME} --- Convert a time into a string
3308 @fnindex CTIME
3309 @cindex time, conversion to string
3310 @cindex conversion, to string
3311
3312 @table @asis
3313 @item @emph{Description}:
3314 @code{CTIME} converts a system time value, such as returned by
3315 @code{TIME8}, to a string. Unless the application has called
3316 @code{setlocale}, the output will be in the default locale, of length
3317 24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3318 a longer string may result.
3319
3320 This intrinsic is provided in both subroutine and function forms; however,
3321 only one form can be used in any given program unit.
3322
3323 @item @emph{Standard}:
3324 GNU extension
3325
3326 @item @emph{Class}:
3327 Subroutine, function
3328
3329 @item @emph{Syntax}:
3330 @multitable @columnfractions .80
3331 @item @code{CALL CTIME(TIME, RESULT)}.
3332 @item @code{RESULT = CTIME(TIME)}.
3333 @end multitable
3334
3335 @item @emph{Arguments}:
3336 @multitable @columnfractions .15 .70
3337 @item @var{TIME}    @tab The type shall be of type @code{INTEGER}.
3338 @item @var{RESULT}  @tab The type shall be of type @code{CHARACTER} and
3339 of default kind. It is an @code{INTENT(OUT)} argument. If the length
3340 of this variable is too short for the time and date string to fit
3341 completely, it will be blank on procedure return.
3342 @end multitable
3343
3344 @item @emph{Return value}:
3345 The converted date and time as a string.
3346
3347 @item @emph{Example}:
3348 @smallexample
3349 program test_ctime
3350     integer(8) :: i
3351     character(len=30) :: date
3352     i = time8()
3353
3354     ! Do something, main part of the program
3355
3356     call ctime(i,date)
3357     print *, 'Program was started on ', date
3358 end program test_ctime
3359 @end smallexample
3360
3361 @item @emph{See Also}:
3362 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3363 @end table
3364
3365
3366
3367 @node DATE_AND_TIME
3368 @section @code{DATE_AND_TIME} --- Date and time subroutine
3369 @fnindex DATE_AND_TIME
3370 @cindex date, current
3371 @cindex current date
3372 @cindex time, current
3373 @cindex current time
3374
3375 @table @asis
3376 @item @emph{Description}:
3377 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3378 time information from the real-time system clock.  @var{DATE} is
3379 @code{INTENT(OUT)} and has form ccyymmdd.  @var{TIME} is @code{INTENT(OUT)} and
3380 has form hhmmss.sss.  @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3381 representing the difference with respect to Coordinated Universal Time (UTC).
3382 Unavailable time and date parameters return blanks.
3383
3384 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3385
3386 @multitable @columnfractions .15 .30 .40
3387 @item @tab @code{VALUE(1)}: @tab The year
3388 @item @tab @code{VALUE(2)}: @tab The month
3389 @item @tab @code{VALUE(3)}: @tab The day of the month
3390 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3391 @item @tab @code{VALUE(5)}: @tab The hour of the day
3392 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3393 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3394 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3395 @end multitable
3396
3397 @item @emph{Standard}:
3398 Fortran 95 and later
3399
3400 @item @emph{Class}:
3401 Subroutine
3402
3403 @item @emph{Syntax}:
3404 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3405
3406 @item @emph{Arguments}:
3407 @multitable @columnfractions .15 .70
3408 @item @var{DATE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3409 or larger, and of default kind.
3410 @item @var{TIME}  @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3411 or larger, and of default kind.
3412 @item @var{ZONE}  @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3413 or larger, and of default kind.
3414 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3415 @end multitable
3416
3417 @item @emph{Return value}:
3418 None
3419
3420 @item @emph{Example}:
3421 @smallexample
3422 program test_time_and_date
3423     character(8)  :: date
3424     character(10) :: time
3425     character(5)  :: zone
3426     integer,dimension(8) :: values
3427     ! using keyword arguments
3428     call date_and_time(date,time,zone,values)
3429     call date_and_time(DATE=date,ZONE=zone)
3430     call date_and_time(TIME=time)
3431     call date_and_time(VALUES=values)
3432     print '(a,2x,a,2x,a)', date, time, zone
3433     print '(8i5))', values
3434 end program test_time_and_date
3435 @end smallexample
3436
3437 @item @emph{See also}:
3438 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3439 @end table
3440
3441
3442
3443 @node DBLE
3444 @section @code{DBLE} --- Double conversion function
3445 @fnindex DBLE
3446 @cindex conversion, to real
3447
3448 @table @asis
3449 @item @emph{Description}:
3450 @code{DBLE(A)} Converts @var{A} to double precision real type.
3451
3452 @item @emph{Standard}:
3453 Fortran 77 and later
3454
3455 @item @emph{Class}:
3456 Elemental function
3457
3458 @item @emph{Syntax}:
3459 @code{RESULT = DBLE(A)}
3460
3461 @item @emph{Arguments}:
3462 @multitable @columnfractions .15 .70
3463 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3464 or @code{COMPLEX}.
3465 @end multitable
3466
3467 @item @emph{Return value}:
3468 The return value is of type double precision real.
3469
3470 @item @emph{Example}:
3471 @smallexample
3472 program test_dble
3473     real    :: x = 2.18
3474     integer :: i = 5
3475     complex :: z = (2.3,1.14)
3476     print *, dble(x), dble(i), dble(z)
3477 end program test_dble
3478 @end smallexample
3479
3480 @item @emph{See also}:
3481 @ref{REAL}
3482 @end table
3483
3484
3485
3486 @node DCMPLX
3487 @section @code{DCMPLX} --- Double complex conversion function
3488 @fnindex DCMPLX
3489 @cindex complex numbers, conversion to
3490 @cindex conversion, to complex
3491
3492 @table @asis
3493 @item @emph{Description}:
3494 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3495 converted to the real component.  If @var{Y} is present it is converted to the
3496 imaginary component.  If @var{Y} is not present then the imaginary component is
3497 set to 0.0.  If @var{X} is complex then @var{Y} must not be present.
3498
3499 @item @emph{Standard}:
3500 GNU extension
3501
3502 @item @emph{Class}:
3503 Elemental function
3504
3505 @item @emph{Syntax}:
3506 @code{RESULT = DCMPLX(X [, Y])}
3507
3508 @item @emph{Arguments}:
3509 @multitable @columnfractions .15 .70
3510 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3511 or @code{COMPLEX}.
3512 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3513 @code{INTEGER} or @code{REAL}.
3514 @end multitable
3515
3516 @item @emph{Return value}:
3517 The return value is of type @code{COMPLEX(8)}
3518
3519 @item @emph{Example}:
3520 @smallexample
3521 program test_dcmplx
3522     integer :: i = 42
3523     real :: x = 3.14
3524     complex :: z
3525     z = cmplx(i, x)
3526     print *, dcmplx(i)
3527     print *, dcmplx(x)
3528     print *, dcmplx(z)
3529     print *, dcmplx(x,i)
3530 end program test_dcmplx
3531 @end smallexample
3532 @end table
3533
3534
3535 @node DIGITS
3536 @section @code{DIGITS} --- Significant binary digits function
3537 @fnindex DIGITS
3538 @cindex model representation, significant digits
3539
3540 @table @asis
3541 @item @emph{Description}:
3542 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3543 model representation of @var{X}.  For example, on a system using a 32-bit
3544 floating point representation, a default real number would likely return 24.
3545
3546 @item @emph{Standard}:
3547 Fortran 95 and later
3548
3549 @item @emph{Class}:
3550 Inquiry function
3551
3552 @item @emph{Syntax}:
3553 @code{RESULT = DIGITS(X)}
3554
3555 @item @emph{Arguments}:
3556 @multitable @columnfractions .15 .70
3557 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3558 @end multitable
3559
3560 @item @emph{Return value}:
3561 The return value is of type @code{INTEGER}.
3562
3563 @item @emph{Example}:
3564 @smallexample
3565 program test_digits
3566     integer :: i = 12345
3567     real :: x = 3.143
3568     real(8) :: y = 2.33
3569     print *, digits(i)
3570     print *, digits(x)
3571     print *, digits(y)
3572 end program test_digits
3573 @end smallexample
3574 @end table
3575
3576
3577
3578 @node DIM
3579 @section @code{DIM} --- Positive difference
3580 @fnindex DIM
3581 @fnindex IDIM
3582 @fnindex DDIM
3583 @cindex positive difference
3584
3585 @table @asis
3586 @item @emph{Description}:
3587 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3588 otherwise returns zero.
3589
3590 @item @emph{Standard}:
3591 Fortran 77 and later
3592
3593 @item @emph{Class}:
3594 Elemental function
3595
3596 @item @emph{Syntax}:
3597 @code{RESULT = DIM(X, Y)}
3598
3599 @item @emph{Arguments}:
3600 @multitable @columnfractions .15 .70
3601 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3602 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3603 @end multitable
3604
3605 @item @emph{Return value}:
3606 The return value is of type @code{INTEGER} or @code{REAL}.
3607
3608 @item @emph{Example}:
3609 @smallexample
3610 program test_dim
3611     integer :: i
3612     real(8) :: x
3613     i = dim(4, 15)
3614     x = dim(4.345_8, 2.111_8)
3615     print *, i
3616     print *, x
3617 end program test_dim
3618 @end smallexample
3619
3620 @item @emph{Specific names}:
3621 @multitable @columnfractions .20 .20 .20 .25
3622 @item Name             @tab Argument               @tab Return type       @tab Standard
3623 @item @code{DIM(X,Y)}  @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3624 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3625 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y}    @tab @code{REAL(8)}    @tab Fortran 77 and later
3626 @end multitable
3627 @end table
3628
3629
3630
3631 @node DOT_PRODUCT
3632 @section @code{DOT_PRODUCT} --- Dot product function
3633 @fnindex DOT_PRODUCT
3634 @cindex dot product
3635 @cindex vector product
3636 @cindex product, vector
3637
3638 @table @asis
3639 @item @emph{Description}:
3640 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3641 of two vectors @var{VECTOR_A} and @var{VECTOR_B}.  The two vectors may be
3642 either numeric or logical and must be arrays of rank one and of equal size. If
3643 the vectors are @code{INTEGER} or @code{REAL}, the result is
3644 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3645 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3646 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3647
3648 @item @emph{Standard}:
3649 Fortran 95 and later
3650
3651 @item @emph{Class}:
3652 Transformational function
3653
3654 @item @emph{Syntax}:
3655 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3656
3657 @item @emph{Arguments}:
3658 @multitable @columnfractions .15 .70
3659 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3660 @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.
3661 @end multitable
3662
3663 @item @emph{Return value}:
3664 If the arguments are numeric, the return value is a scalar of numeric type,
3665 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}.  If the arguments are
3666 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3667
3668 @item @emph{Example}:
3669 @smallexample
3670 program test_dot_prod
3671     integer, dimension(3) :: a, b
3672     a = (/ 1, 2, 3 /)
3673     b = (/ 4, 5, 6 /)
3674     print '(3i3)', a
3675     print *
3676     print '(3i3)', b
3677     print *
3678     print *, dot_product(a,b)
3679 end program test_dot_prod
3680 @end smallexample
3681 @end table
3682
3683
3684
3685 @node DPROD
3686 @section @code{DPROD} --- Double product function
3687 @fnindex DPROD
3688 @cindex product, double-precision
3689
3690 @table @asis
3691 @item @emph{Description}:
3692 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3693
3694 @item @emph{Standard}:
3695 Fortran 77 and later
3696
3697 @item @emph{Class}:
3698 Elemental function
3699
3700 @item @emph{Syntax}:
3701 @code{RESULT = DPROD(X, Y)}
3702
3703 @item @emph{Arguments}:
3704 @multitable @columnfractions .15 .70
3705 @item @var{X} @tab The type shall be @code{REAL}.
3706 @item @var{Y} @tab The type shall be @code{REAL}.
3707 @end multitable
3708
3709 @item @emph{Return value}:
3710 The return value is of type @code{REAL(8)}.
3711
3712 @item @emph{Example}:
3713 @smallexample
3714 program test_dprod
3715     real :: x = 5.2
3716     real :: y = 2.3
3717     real(8) :: d
3718     d = dprod(x,y)
3719     print *, d
3720 end program test_dprod
3721 @end smallexample
3722
3723 @item @emph{Specific names}:
3724 @multitable @columnfractions .20 .20 .20 .25
3725 @item Name              @tab Argument               @tab Return type       @tab Standard
3726 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y}    @tab @code{REAL(4)}    @tab Fortran 77 and later
3727 @end multitable
3728
3729 @end table
3730
3731
3732 @node DREAL
3733 @section @code{DREAL} --- Double real part function
3734 @fnindex DREAL
3735 @cindex complex numbers, real part
3736
3737 @table @asis
3738 @item @emph{Description}:
3739 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3740
3741 @item @emph{Standard}:
3742 GNU extension
3743
3744 @item @emph{Class}:
3745 Elemental function
3746
3747 @item @emph{Syntax}:
3748 @code{RESULT = DREAL(A)}
3749
3750 @item @emph{Arguments}:
3751 @multitable @columnfractions .15 .70
3752 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3753 @end multitable
3754
3755 @item @emph{Return value}:
3756 The return value is of type @code{REAL(8)}.
3757
3758 @item @emph{Example}:
3759 @smallexample
3760 program test_dreal
3761     complex(8) :: z = (1.3_8,7.2_8)
3762     print *, dreal(z)
3763 end program test_dreal
3764 @end smallexample
3765
3766 @item @emph{See also}:
3767 @ref{AIMAG}
3768
3769 @end table
3770
3771
3772
3773 @node DSHIFTL
3774 @section @code{DSHIFTL} --- Combined left shift
3775 @fnindex DSHIFTL
3776 @cindex left shift, combined
3777 @cindex shift, left
3778
3779 @table @asis
3780 @item @emph{Description}:
3781 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3782 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3783 bits of @var{J}, and the remaining bits are the rightmost bits of
3784 @var{I}.
3785
3786 @item @emph{Standard}:
3787 Fortran 2008 and later
3788
3789 @item @emph{Class}:
3790 Elemental function
3791
3792 @item @emph{Syntax}:
3793 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3794
3795 @item @emph{Arguments}:
3796 @multitable @columnfractions .15 .70
3797 @item @var{I} @tab Shall be of type @code{INTEGER}.
3798 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3799 as @var{I}.
3800 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3801 @end multitable
3802
3803 @item @emph{Return value}:
3804 The return value has same type and kind as @var{I}.
3805
3806 @item @emph{See also}:
3807 @ref{DSHIFTR}
3808
3809 @end table
3810
3811
3812
3813 @node DSHIFTR
3814 @section @code{DSHIFTR} --- Combined right shift
3815 @fnindex DSHIFTR
3816 @cindex right shift, combined
3817 @cindex shift, right
3818
3819 @table @asis
3820 @item @emph{Description}:
3821 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3822 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3823 bits of @var{I}, and the remaining bits are the leftmost bits of
3824 @var{J}.
3825
3826 @item @emph{Standard}:
3827 Fortran 2008 and later
3828
3829 @item @emph{Class}:
3830 Elemental function
3831
3832 @item @emph{Syntax}:
3833 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3834
3835 @item @emph{Arguments}:
3836 @multitable @columnfractions .15 .70
3837 @item @var{I} @tab Shall be of type @code{INTEGER}.
3838 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3839 as @var{I}.
3840 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3841 @end multitable
3842
3843 @item @emph{Return value}:
3844 The return value has same type and kind as @var{I}.
3845
3846 @item @emph{See also}:
3847 @ref{DSHIFTL}
3848
3849 @end table
3850
3851
3852
3853 @node DTIME
3854 @section @code{DTIME} --- Execution time subroutine (or function)
3855 @fnindex DTIME
3856 @cindex time, elapsed
3857 @cindex elapsed time
3858
3859 @table @asis
3860 @item @emph{Description}:
3861 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3862 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3863 returns the user and system components of this time in @code{VALUES(1)} and
3864 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3865 VALUES(2)}.
3866
3867 Subsequent invocations of @code{DTIME} return values accumulated since the
3868 previous invocation.
3869
3870 On some systems, the underlying timings are represented using types with
3871 sufficiently small limits that overflows (wrap around) are possible, such as
3872 32-bit types. Therefore, the values returned by this intrinsic might be, or
3873 become, negative, or numerically less than previous values, during a single
3874 run of the compiled program.
3875
3876 Please note, that this implementation is thread safe if used within OpenMP
3877 directives, i.e., its state will be consistent while called from multiple
3878 threads. However, if @code{DTIME} is called from multiple threads, the result
3879 is still the time since the last invocation. This may not give the intended
3880 results. If possible, use @code{CPU_TIME} instead.
3881
3882 This intrinsic is provided in both subroutine and function forms; however,
3883 only one form can be used in any given program unit.
3884
3885 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3886
3887 @multitable @columnfractions .15 .30 .40
3888 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3889 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3890 @item @tab @code{TIME}: @tab Run time since start in seconds.
3891 @end multitable
3892
3893 @item @emph{Standard}:
3894 GNU extension
3895
3896 @item @emph{Class}:
3897 Subroutine, function
3898
3899 @item @emph{Syntax}:
3900 @multitable @columnfractions .80
3901 @item @code{CALL DTIME(VALUES, TIME)}.
3902 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3903 @end multitable
3904
3905 @item @emph{Arguments}:
3906 @multitable @columnfractions .15 .70
3907 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3908 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3909 @end multitable
3910
3911 @item @emph{Return value}:
3912 Elapsed time in seconds since the last invocation or since the start of program
3913 execution if not called before.
3914
3915 @item @emph{Example}:
3916 @smallexample
3917 program test_dtime
3918     integer(8) :: i, j
3919     real, dimension(2) :: tarray
3920     real :: result
3921     call dtime(tarray, result)
3922     print *, result
3923     print *, tarray(1)
3924     print *, tarray(2)
3925     do i=1,100000000    ! Just a delay
3926         j = i * i - i
3927     end do
3928     call dtime(tarray, result)
3929     print *, result
3930     print *, tarray(1)
3931     print *, tarray(2)
3932 end program test_dtime
3933 @end smallexample
3934
3935 @item @emph{See also}:
3936 @ref{CPU_TIME}
3937
3938 @end table
3939
3940
3941
3942 @node EOSHIFT
3943 @section @code{EOSHIFT} --- End-off shift elements of an array
3944 @fnindex EOSHIFT
3945 @cindex array, shift
3946
3947 @table @asis
3948 @item @emph{Description}:
3949 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3950 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3951 omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
3952 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3953 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3954 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3955 then all complete rank one sections of @var{ARRAY} along the given dimension are
3956 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3957 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3958 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3959 following are copied in depending on the type of @var{ARRAY}.
3960
3961 @multitable @columnfractions .15 .80
3962 @item @emph{Array Type} @tab @emph{Boundary Value}
3963 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3964 @item Logical  @tab @code{.FALSE.}.
3965 @item Character(@var{len}) @tab @var{len} blanks.
3966 @end multitable
3967
3968 @item @emph{Standard}:
3969 Fortran 95 and later
3970
3971 @item @emph{Class}:
3972 Transformational function
3973
3974 @item @emph{Syntax}:
3975 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3976
3977 @item @emph{Arguments}:
3978 @multitable @columnfractions .15 .70
3979 @item @var{ARRAY}  @tab May be any type, not scalar.
3980 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3981 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3982 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3983 @end multitable
3984
3985 @item @emph{Return value}:
3986 Returns an array of same type and rank as the @var{ARRAY} argument.
3987
3988 @item @emph{Example}:
3989 @smallexample
3990 program test_eoshift
3991     integer, dimension(3,3) :: a
3992     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3993     print '(3i3)', a(1,:)
3994     print '(3i3)', a(2,:)
3995     print '(3i3)', a(3,:)
3996     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3997     print *
3998     print '(3i3)', a(1,:)
3999     print '(3i3)', a(2,:)
4000     print '(3i3)', a(3,:)
4001 end program test_eoshift
4002 @end smallexample
4003 @end table
4004
4005
4006
4007 @node EPSILON
4008 @section @code{EPSILON} --- Epsilon function
4009 @fnindex EPSILON
4010 @cindex model representation, epsilon
4011
4012 @table @asis
4013 @item @emph{Description}:
4014 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4015 as @var{X} such that @math{1 + E > 1}.
4016
4017 @item @emph{Standard}:
4018 Fortran 95 and later
4019
4020 @item @emph{Class}:
4021 Inquiry function
4022
4023 @item @emph{Syntax}:
4024 @code{RESULT = EPSILON(X)}
4025
4026 @item @emph{Arguments}:
4027 @multitable @columnfractions .15 .70
4028 @item @var{X} @tab The type shall be @code{REAL}.
4029 @end multitable
4030
4031 @item @emph{Return value}:
4032 The return value is of same type as the argument.
4033
4034 @item @emph{Example}:
4035 @smallexample
4036 program test_epsilon
4037     real :: x = 3.143
4038     real(8) :: y = 2.33
4039     print *, EPSILON(x)
4040     print *, EPSILON(y)
4041 end program test_epsilon
4042 @end smallexample
4043 @end table
4044
4045
4046
4047 @node ERF
4048 @section @code{ERF} --- Error function
4049 @fnindex ERF
4050 @cindex error function
4051
4052 @table @asis
4053 @item @emph{Description}:
4054 @code{ERF(X)} computes the error function of @var{X}.
4055
4056 @item @emph{Standard}:
4057 Fortran 2008 and later
4058
4059 @item @emph{Class}:
4060 Elemental function
4061
4062 @item @emph{Syntax}:
4063 @code{RESULT = ERF(X)}
4064
4065 @item @emph{Arguments}:
4066 @multitable @columnfractions .15 .70
4067 @item @var{X} @tab The type shall be @code{REAL}.
4068 @end multitable
4069
4070 @item @emph{Return value}:
4071 The return value is of type @code{REAL}, of the same kind as
4072 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4073
4074 @item @emph{Example}:
4075 @smallexample
4076 program test_erf
4077   real(8) :: x = 0.17_8
4078   x = erf(x)
4079 end program test_erf
4080 @end smallexample
4081
4082 @item @emph{Specific names}:
4083 @multitable @columnfractions .20 .20 .20 .25
4084 @item Name            @tab Argument          @tab Return type       @tab Standard
4085 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
4086 @end multitable
4087 @end table
4088
4089
4090
4091 @node ERFC
4092 @section @code{ERFC} --- Error function
4093 @fnindex ERFC
4094 @cindex error function, complementary
4095
4096 @table @asis
4097 @item @emph{Description}:
4098 @code{ERFC(X)} computes the complementary error function of @var{X}.
4099
4100 @item @emph{Standard}:
4101 Fortran 2008 and later
4102
4103 @item @emph{Class}:
4104 Elemental function
4105
4106 @item @emph{Syntax}:
4107 @code{RESULT = ERFC(X)}
4108
4109 @item @emph{Arguments}:
4110 @multitable @columnfractions .15 .70
4111 @item @var{X} @tab The type shall be @code{REAL}.
4112 @end multitable
4113
4114 @item @emph{Return value}:
4115 The return value is of type @code{REAL} and of the same kind as @var{X}.
4116 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4117
4118 @item @emph{Example}:
4119 @smallexample
4120 program test_erfc
4121   real(8) :: x = 0.17_8
4122   x = erfc(x)
4123 end program test_erfc
4124 @end smallexample
4125
4126 @item @emph{Specific names}:
4127 @multitable @columnfractions .20 .20 .20 .25
4128 @item Name            @tab Argument          @tab Return type       @tab Standard
4129 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
4130 @end multitable
4131 @end table
4132
4133
4134
4135 @node ERFC_SCALED
4136 @section @code{ERFC_SCALED} --- Error function
4137 @fnindex ERFC_SCALED
4138 @cindex error function, complementary, exponentially-scaled
4139
4140 @table @asis
4141 @item @emph{Description}:
4142 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4143 error function of @var{X}.
4144
4145 @item @emph{Standard}:
4146 Fortran 2008 and later
4147
4148 @item @emph{Class}:
4149 Elemental function
4150
4151 @item @emph{Syntax}:
4152 @code{RESULT = ERFC_SCALED(X)}
4153
4154 @item @emph{Arguments}:
4155 @multitable @columnfractions .15 .70
4156 @item @var{X} @tab The type shall be @code{REAL}.
4157 @end multitable
4158
4159 @item @emph{Return value}:
4160 The return value is of type @code{REAL} and of the same kind as @var{X}.
4161
4162 @item @emph{Example}:
4163 @smallexample
4164 program test_erfc_scaled
4165   real(8) :: x = 0.17_8
4166   x = erfc_scaled(x)
4167 end program test_erfc_scaled
4168 @end smallexample
4169 @end table
4170
4171
4172
4173 @node ETIME
4174 @section @code{ETIME} --- Execution time subroutine (or function)
4175 @fnindex ETIME
4176 @cindex time, elapsed
4177
4178 @table @asis
4179 @item @emph{Description}:
4180 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4181 since the start of the process's execution in @var{TIME}.  @var{VALUES}
4182 returns the user and system components of this time in @code{VALUES(1)} and
4183 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4184
4185 On some systems, the underlying timings are represented using types with
4186 sufficiently small limits that overflows (wrap around) are possible, such as
4187 32-bit types. Therefore, the values returned by this intrinsic might be, or
4188 become, negative, or numerically less than previous values, during a single
4189 run of the compiled program.
4190
4191 This intrinsic is provided in both subroutine and function forms; however,
4192 only one form can be used in any given program unit.
4193
4194 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4195
4196 @multitable @columnfractions .15 .30 .60
4197 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4198 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4199 @item @tab @code{TIME}: @tab Run time since start in seconds.
4200 @end multitable
4201
4202 @item @emph{Standard}:
4203 GNU extension
4204
4205 @item @emph{Class}:
4206 Subroutine, function
4207
4208 @item @emph{Syntax}:
4209 @multitable @columnfractions .80
4210 @item @code{CALL ETIME(VALUES, TIME)}.
4211 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4212 @end multitable
4213
4214 @item @emph{Arguments}:
4215 @multitable @columnfractions .15 .70
4216 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4217 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4218 @end multitable
4219
4220 @item @emph{Return value}:
4221 Elapsed time in seconds since the start of program execution.
4222
4223 @item @emph{Example}:
4224 @smallexample
4225 program test_etime
4226     integer(8) :: i, j
4227     real, dimension(2) :: tarray
4228     real :: result
4229     call ETIME(tarray, result)
4230     print *, result
4231     print *, tarray(1)
4232     print *, tarray(2)
4233     do i=1,100000000    ! Just a delay
4234         j = i * i - i
4235     end do
4236     call ETIME(tarray, result)
4237     print *, result
4238     print *, tarray(1)
4239     print *, tarray(2)
4240 end program test_etime
4241 @end smallexample
4242
4243 @item @emph{See also}:
4244 @ref{CPU_TIME}
4245
4246 @end table
4247
4248
4249
4250 @node EXECUTE_COMMAND_LINE
4251 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4252 @fnindex EXECUTE_COMMAND_LINE
4253 @cindex system, system call
4254 @cindex command line
4255
4256 @table @asis
4257 @item @emph{Description}:
4258 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4259 asynchronously.
4260
4261 The @code{COMMAND} argument is passed to the shell and executed, using
4262 the C library's @code{system} call.  (The shell is @code{sh} on Unix
4263 systems, and @code{cmd.exe} on Windows.)  If @code{WAIT} is present
4264 and has the value false, the execution of the command is asynchronous
4265 if the system supports it; otherwise, the command is executed
4266 synchronously.
4267
4268 The three last arguments allow the user to get status information.  After
4269 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4270 the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
4271 if the command line was executed (whatever its exit status was).
4272 @code{CMDMSG} is assigned an error message if an error has occurred.
4273
4274 Note that the @code{system} function need not be thread-safe. It is
4275 the responsibility of the user to ensure that @code{system} is not
4276 called concurrently.
4277
4278 @item @emph{Standard}:
4279 Fortran 2008 and later
4280
4281 @item @emph{Class}:
4282 Subroutine
4283
4284 @item @emph{Syntax}:
4285 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4286
4287 @item @emph{Arguments}:
4288 @multitable @columnfractions .15 .70
4289 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4290 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4291 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4292 default kind.
4293 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4294 default kind.
4295 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4296 default kind.
4297 @end multitable
4298
4299 @item @emph{Example}:
4300 @smallexample
4301 program test_exec
4302   integer :: i
4303
4304   call execute_command_line ("external_prog.exe", exitstat=i)
4305   print *, "Exit status of external_prog.exe was ", i
4306
4307   call execute_command_line ("reindex_files.exe", wait=.false.)
4308   print *, "Now reindexing files in the background"
4309
4310 end program test_exec
4311 @end smallexample
4312
4313
4314 @item @emph{Note}:
4315
4316 Because this intrinsic is implemented in terms of the @code{system}
4317 function call, its behavior with respect to signaling is processor
4318 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4319 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4320 such, if the parent process is terminated, the child process might not be
4321 terminated alongside.
4322
4323
4324 @item @emph{See also}:
4325 @ref{SYSTEM}
4326 @end table
4327
4328
4329
4330 @node EXIT
4331 @section @code{EXIT} --- Exit the program with status.
4332 @fnindex EXIT
4333 @cindex program termination
4334 @cindex terminate program
4335
4336 @table @asis
4337 @item @emph{Description}:
4338 @code{EXIT} causes immediate termination of the program with status.  If status
4339 is omitted it returns the canonical @emph{success} for the system.  All Fortran
4340 I/O units are closed.
4341
4342 @item @emph{Standard}:
4343 GNU extension
4344
4345 @item @emph{Class}:
4346 Subroutine
4347
4348 @item @emph{Syntax}:
4349 @code{CALL EXIT([STATUS])}
4350
4351 @item @emph{Arguments}:
4352 @multitable @columnfractions .15 .70
4353 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4354 @end multitable
4355
4356 @item @emph{Return value}:
4357 @code{STATUS} is passed to the parent process on exit.
4358
4359 @item @emph{Example}:
4360 @smallexample
4361 program test_exit
4362   integer :: STATUS = 0
4363   print *, 'This program is going to exit.'
4364   call EXIT(STATUS)
4365 end program test_exit
4366 @end smallexample
4367
4368 @item @emph{See also}:
4369 @ref{ABORT}, @ref{KILL}
4370 @end table
4371
4372
4373
4374 @node EXP
4375 @section @code{EXP} --- Exponential function
4376 @fnindex EXP
4377 @fnindex DEXP
4378 @fnindex CEXP
4379 @fnindex ZEXP
4380 @fnindex CDEXP
4381 @cindex exponential function
4382 @cindex logarithm function, inverse
4383
4384 @table @asis
4385 @item @emph{Description}:
4386 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4387
4388 @item @emph{Standard}:
4389 Fortran 77 and later, has overloads that are GNU extensions
4390
4391 @item @emph{Class}:
4392 Elemental function
4393
4394 @item @emph{Syntax}:
4395 @code{RESULT = EXP(X)}
4396
4397 @item @emph{Arguments}:
4398 @multitable @columnfractions .15 .70
4399 @item @var{X} @tab The type shall be @code{REAL} or
4400 @code{COMPLEX}.
4401 @end multitable
4402
4403 @item @emph{Return value}:
4404 The return value has same type and kind as @var{X}.
4405
4406 @item @emph{Example}:
4407 @smallexample
4408 program test_exp
4409   real :: x = 1.0
4410   x = exp(x)
4411 end program test_exp
4412 @end smallexample
4413
4414 @item @emph{Specific names}:
4415 @multitable @columnfractions .20 .20 .20 .25
4416 @item Name            @tab Argument             @tab Return type         @tab Standard
4417 @item @code{EXP(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}      @tab Fortran 77 and later
4418 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
4419 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
4420 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4421 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4422 @end multitable
4423 @end table
4424
4425
4426
4427 @node EXPONENT
4428 @section @code{EXPONENT} --- Exponent function
4429 @fnindex EXPONENT
4430 @cindex real number, exponent
4431 @cindex floating point, exponent
4432
4433 @table @asis
4434 @item @emph{Description}:
4435 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4436 is zero the value returned is zero.
4437
4438 @item @emph{Standard}:
4439 Fortran 95 and later
4440
4441 @item @emph{Class}:
4442 Elemental function
4443
4444 @item @emph{Syntax}:
4445 @code{RESULT = EXPONENT(X)}
4446
4447 @item @emph{Arguments}:
4448 @multitable @columnfractions .15 .70
4449 @item @var{X} @tab The type shall be @code{REAL}.
4450 @end multitable
4451
4452 @item @emph{Return value}:
4453 The return value is of type default @code{INTEGER}.
4454
4455 @item @emph{Example}:
4456 @smallexample
4457 program test_exponent
4458   real :: x = 1.0
4459   integer :: i
4460   i = exponent(x)
4461   print *, i
4462   print *, exponent(0.0)
4463 end program test_exponent
4464 @end smallexample
4465 @end table
4466
4467
4468
4469 @node EXTENDS_TYPE_OF
4470 @section @code{EXTENDS_TYPE_OF} ---  Query dynamic type for extension
4471 @fnindex EXTENDS_TYPE_OF
4472
4473 @table @asis
4474 @item @emph{Description}:
4475 Query dynamic type for extension.
4476
4477 @item @emph{Standard}:
4478 Fortran 2003 and later
4479
4480 @item @emph{Class}:
4481 Inquiry function
4482
4483 @item @emph{Syntax}:
4484 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4485
4486 @item @emph{Arguments}:
4487 @multitable @columnfractions .15 .70
4488 @item @var{A} @tab Shall be an object of extensible declared type or
4489 unlimited polymorphic.
4490 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4491 unlimited polymorphic.
4492 @end multitable
4493
4494 @item @emph{Return value}:
4495 The return value is a scalar of type default logical. It is true if and only if
4496 the dynamic type of A is an extension type of the dynamic type of MOLD.
4497
4498
4499 @item @emph{See also}:
4500 @ref{SAME_TYPE_AS}
4501 @end table
4502
4503
4504
4505 @node FDATE
4506 @section @code{FDATE} --- Get the current time as a string
4507 @fnindex FDATE
4508 @cindex time, current
4509 @cindex current time
4510 @cindex date, current
4511 @cindex current date
4512
4513 @table @asis
4514 @item @emph{Description}:
4515 @code{FDATE(DATE)} returns the current date (using the same format as
4516 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4517 TIME())}.
4518
4519 This intrinsic is provided in both subroutine and function forms; however,
4520 only one form can be used in any given program unit.
4521
4522 @item @emph{Standard}:
4523 GNU extension
4524
4525 @item @emph{Class}:
4526 Subroutine, function
4527
4528 @item @emph{Syntax}:
4529 @multitable @columnfractions .80
4530 @item @code{CALL FDATE(DATE)}.
4531 @item @code{DATE = FDATE()}.
4532 @end multitable
4533
4534 @item @emph{Arguments}:
4535 @multitable @columnfractions .15 .70
4536 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4537 default kind. It is an @code{INTENT(OUT)} argument.  If the length of
4538 this variable is too short for the date and time string to fit
4539 completely, it will be blank on procedure return.
4540 @end multitable
4541
4542 @item @emph{Return value}:
4543 The current date and time as a string.
4544
4545 @item @emph{Example}:
4546 @smallexample
4547 program test_fdate
4548     integer(8) :: i, j
4549     character(len=30) :: date
4550     call fdate(date)
4551     print *, 'Program started on ', date
4552     do i = 1, 100000000 ! Just a delay
4553         j = i * i - i
4554     end do
4555     call fdate(date)
4556     print *, 'Program ended on ', date
4557 end program test_fdate
4558 @end smallexample
4559
4560 @item @emph{See also}:
4561 @ref{DATE_AND_TIME}, @ref{CTIME}
4562 @end table
4563
4564
4565 @node FGET
4566 @section @code{FGET} --- Read a single character in stream mode from stdin
4567 @fnindex FGET
4568 @cindex read character, stream mode
4569 @cindex stream mode, read character
4570 @cindex file operation, read character
4571
4572 @table @asis
4573 @item @emph{Description}:
4574 Read a single character in stream mode from stdin by bypassing normal
4575 formatted output. Stream I/O should not be mixed with normal record-oriented
4576 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4577
4578 This intrinsic is provided in both subroutine and function forms; however,
4579 only one form can be used in any given program unit.
4580
4581 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4582 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4583 Programmers should consider the use of new stream IO feature in new code
4584 for future portability. See also @ref{Fortran 2003 status}.
4585
4586 @item @emph{Standard}:
4587 GNU extension
4588
4589 @item @emph{Class}:
4590 Subroutine, function
4591
4592 @item @emph{Syntax}:
4593 @multitable @columnfractions .80
4594 @item @code{CALL FGET(C [, STATUS])}
4595 @item @code{STATUS = FGET(C)}
4596 @end multitable
4597
4598 @item @emph{Arguments}:
4599 @multitable @columnfractions .15 .70
4600 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4601 kind.
4602 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4603 Returns 0 on success, -1 on end-of-file, and a system specific positive
4604 error code otherwise.
4605 @end multitable
4606
4607 @item @emph{Example}:
4608 @smallexample
4609 PROGRAM test_fget
4610   INTEGER, PARAMETER :: strlen = 100
4611   INTEGER :: status, i = 1
4612   CHARACTER(len=strlen) :: str = ""
4613
4614   WRITE (*,*) 'Enter text:'
4615   DO
4616     CALL fget(str(i:i), status)
4617     if (status /= 0 .OR. i > strlen) exit
4618     i = i + 1
4619   END DO
4620   WRITE (*,*) TRIM(str)
4621 END PROGRAM
4622 @end smallexample
4623
4624 @item @emph{See also}:
4625 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4626 @end table
4627
4628
4629
4630 @node FGETC
4631 @section @code{FGETC} --- Read a single character in stream mode
4632 @fnindex FGETC
4633 @cindex read character, stream mode
4634 @cindex stream mode, read character
4635 @cindex file operation, read character
4636
4637 @table @asis
4638 @item @emph{Description}:
4639 Read a single character in stream mode by bypassing normal formatted output.
4640 Stream I/O should not be mixed with normal record-oriented (formatted or
4641 unformatted) I/O on the same unit; the results are unpredictable.
4642
4643 This intrinsic is provided in both subroutine and function forms; however,
4644 only one form can be used in any given program unit.
4645
4646 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4647 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4648 Programmers should consider the use of new stream IO feature in new code
4649 for future portability. See also @ref{Fortran 2003 status}.
4650
4651 @item @emph{Standard}:
4652 GNU extension
4653
4654 @item @emph{Class}:
4655 Subroutine, function
4656
4657 @item @emph{Syntax}:
4658 @multitable @columnfractions .80
4659 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4660 @item @code{STATUS = FGETC(UNIT, C)}
4661 @end multitable
4662
4663 @item @emph{Arguments}:
4664 @multitable @columnfractions .15 .70
4665 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4666 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4667 kind.
4668 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4669 Returns 0 on success, -1 on end-of-file and a system specific positive
4670 error code otherwise.
4671 @end multitable
4672
4673 @item @emph{Example}:
4674 @smallexample
4675 PROGRAM test_fgetc
4676   INTEGER :: fd = 42, status
4677   CHARACTER :: c
4678
4679   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4680   DO
4681     CALL fgetc(fd, c, status)
4682     IF (status /= 0) EXIT
4683     call fput(c)
4684   END DO
4685   CLOSE(UNIT=fd)
4686 END PROGRAM
4687 @end smallexample
4688
4689 @item @emph{See also}:
4690 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4691 @end table
4692
4693
4694
4695 @node FLOOR
4696 @section @code{FLOOR} --- Integer floor function
4697 @fnindex FLOOR
4698 @cindex floor
4699 @cindex rounding, floor
4700
4701 @table @asis
4702 @item @emph{Description}:
4703 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4704
4705 @item @emph{Standard}:
4706 Fortran 95 and later
4707
4708 @item @emph{Class}:
4709 Elemental function
4710
4711 @item @emph{Syntax}:
4712 @code{RESULT = FLOOR(A [, KIND])}
4713
4714 @item @emph{Arguments}:
4715 @multitable @columnfractions .15 .70
4716 @item @var{A} @tab The type shall be @code{REAL}.
4717 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4718 expression indicating the kind parameter of the result.
4719 @end multitable
4720
4721 @item @emph{Return value}:
4722 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4723 and of default-kind @code{INTEGER} otherwise.
4724
4725 @item @emph{Example}:
4726 @smallexample
4727 program test_floor
4728     real :: x = 63.29
4729     real :: y = -63.59
4730     print *, floor(x) ! returns 63
4731     print *, floor(y) ! returns -64
4732 end program test_floor
4733 @end smallexample
4734
4735 @item @emph{See also}:
4736 @ref{CEILING}, @ref{NINT}
4737
4738 @end table
4739
4740
4741
4742 @node FLUSH
4743 @section @code{FLUSH} --- Flush I/O unit(s)
4744 @fnindex FLUSH
4745 @cindex file operation, flush
4746
4747 @table @asis
4748 @item @emph{Description}:
4749 Flushes Fortran unit(s) currently open for output. Without the optional
4750 argument, all units are flushed, otherwise just the unit specified.
4751
4752 @item @emph{Standard}:
4753 GNU extension
4754
4755 @item @emph{Class}:
4756 Subroutine
4757
4758 @item @emph{Syntax}:
4759 @code{CALL FLUSH(UNIT)}
4760
4761 @item @emph{Arguments}:
4762 @multitable @columnfractions .15 .70
4763 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4764 @end multitable
4765
4766 @item @emph{Note}:
4767 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4768 statement that should be preferred over the @code{FLUSH} intrinsic.
4769
4770 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4771 have identical effect: they flush the runtime library's I/O buffer so
4772 that the data becomes visible to other processes. This does not guarantee
4773 that the data is committed to disk.
4774
4775 On POSIX systems, you can request that all data is transferred  to  the
4776 storage device by calling the @code{fsync} function, with the POSIX file
4777 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4778 @code{FNUM}). The following example shows how:
4779
4780 @smallexample
4781   ! Declare the interface for POSIX fsync function
4782   interface
4783     function fsync (fd) bind(c,name="fsync")
4784     use iso_c_binding, only: c_int
4785       integer(c_int), value :: fd
4786       integer(c_int) :: fsync
4787     end function fsync
4788   end interface
4789
4790   ! Variable declaration
4791   integer :: ret
4792
4793   ! Opening unit 10
4794   open (10,file="foo")
4795
4796   ! ...
4797   ! Perform I/O on unit 10
4798   ! ...
4799
4800   ! Flush and sync
4801   flush(10)
4802   ret = fsync(fnum(10))
4803
4804   ! Handle possible error
4805   if (ret /= 0) stop "Error calling FSYNC"
4806 @end smallexample
4807
4808 @end table
4809
4810
4811
4812 @node FNUM
4813 @section @code{FNUM} --- File number function
4814 @fnindex FNUM
4815 @cindex file operation, file number
4816
4817 @table @asis
4818 @item @emph{Description}:
4819 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4820 open Fortran I/O unit @code{UNIT}.
4821
4822 @item @emph{Standard}:
4823 GNU extension
4824
4825 @item @emph{Class}:
4826 Function
4827
4828 @item @emph{Syntax}:
4829 @code{RESULT = FNUM(UNIT)}
4830
4831 @item @emph{Arguments}:
4832 @multitable @columnfractions .15 .70
4833 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4834 @end multitable
4835
4836 @item @emph{Return value}:
4837 The return value is of type @code{INTEGER}
4838
4839 @item @emph{Example}:
4840 @smallexample
4841 program test_fnum
4842   integer :: i
4843   open (unit=10, status = "scratch")
4844   i = fnum(10)
4845   print *, i
4846   close (10)
4847 end program test_fnum
4848 @end smallexample
4849 @end table
4850
4851
4852
4853 @node FPUT
4854 @section @code{FPUT} --- Write a single character in stream mode to stdout
4855 @fnindex FPUT
4856 @cindex write character, stream mode
4857 @cindex stream mode, write character
4858 @cindex file operation, write character
4859
4860 @table @asis
4861 @item @emph{Description}:
4862 Write a single character in stream mode to stdout by bypassing normal
4863 formatted output. Stream I/O should not be mixed with normal record-oriented
4864 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4865
4866 This intrinsic is provided in both subroutine and function forms; however,
4867 only one form can be used in any given program unit.
4868
4869 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4870 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4871 Programmers should consider the use of new stream IO feature in new code
4872 for future portability. See also @ref{Fortran 2003 status}.
4873
4874 @item @emph{Standard}:
4875 GNU extension
4876
4877 @item @emph{Class}:
4878 Subroutine, function
4879
4880 @item @emph{Syntax}:
4881 @multitable @columnfractions .80
4882 @item @code{CALL FPUT(C [, STATUS])}
4883 @item @code{STATUS = FPUT(C)}
4884 @end multitable
4885
4886 @item @emph{Arguments}:
4887 @multitable @columnfractions .15 .70
4888 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4889 kind.
4890 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4891 Returns 0 on success, -1 on end-of-file and a system specific positive
4892 error code otherwise.
4893 @end multitable
4894
4895 @item @emph{Example}:
4896 @smallexample
4897 PROGRAM test_fput
4898   CHARACTER(len=10) :: str = "gfortran"
4899   INTEGER :: i
4900   DO i = 1, len_trim(str)
4901     CALL fput(str(i:i))
4902   END DO
4903 END PROGRAM
4904 @end smallexample
4905
4906 @item @emph{See also}:
4907 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4908 @end table
4909
4910
4911
4912 @node FPUTC
4913 @section @code{FPUTC} --- Write a single character in stream mode
4914 @fnindex FPUTC
4915 @cindex write character, stream mode
4916 @cindex stream mode, write character
4917 @cindex file operation, write character
4918
4919 @table @asis
4920 @item @emph{Description}:
4921 Write a single character in stream mode by bypassing normal formatted
4922 output. Stream I/O should not be mixed with normal record-oriented
4923 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4924
4925 This intrinsic is provided in both subroutine and function forms; however,
4926 only one form can be used in any given program unit.
4927
4928 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4929 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4930 Programmers should consider the use of new stream IO feature in new code
4931 for future portability. See also @ref{Fortran 2003 status}.
4932
4933 @item @emph{Standard}:
4934 GNU extension
4935
4936 @item @emph{Class}:
4937 Subroutine, function
4938
4939 @item @emph{Syntax}:
4940 @multitable @columnfractions .80
4941 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4942 @item @code{STATUS = FPUTC(UNIT, C)}
4943 @end multitable
4944
4945 @item @emph{Arguments}:
4946 @multitable @columnfractions .15 .70
4947 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4948 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4949 kind.
4950 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4951 Returns 0 on success, -1 on end-of-file and a system specific positive
4952 error code otherwise.
4953 @end multitable
4954
4955 @item @emph{Example}:
4956 @smallexample
4957 PROGRAM test_fputc
4958   CHARACTER(len=10) :: str = "gfortran"
4959   INTEGER :: fd = 42, i
4960
4961   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4962   DO i = 1, len_trim(str)
4963     CALL fputc(fd, str(i:i))
4964   END DO
4965   CLOSE(fd)
4966 END PROGRAM
4967 @end smallexample
4968
4969 @item @emph{See also}:
4970 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4971 @end table
4972
4973
4974
4975 @node FRACTION
4976 @section @code{FRACTION} --- Fractional part of the model representation
4977 @fnindex FRACTION
4978 @cindex real number, fraction
4979 @cindex floating point, fraction
4980
4981 @table @asis
4982 @item @emph{Description}:
4983 @code{FRACTION(X)} returns the fractional part of the model
4984 representation of @code{X}.
4985
4986 @item @emph{Standard}:
4987 Fortran 95 and later
4988
4989 @item @emph{Class}:
4990 Elemental function
4991
4992 @item @emph{Syntax}:
4993 @code{Y = FRACTION(X)}
4994
4995 @item @emph{Arguments}:
4996 @multitable @columnfractions .15 .70
4997 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4998 @end multitable
4999
5000 @item @emph{Return value}:
5001 The return value is of the same type and kind as the argument.
5002 The fractional part of the model representation of @code{X} is returned;
5003 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5004
5005 @item @emph{Example}:
5006 @smallexample
5007 program test_fraction
5008   real :: x
5009   x = 178.1387e-4
5010   print *, fraction(x), x * radix(x)**(-exponent(x))
5011 end program test_fraction
5012 @end smallexample
5013
5014 @end table
5015
5016
5017
5018 @node FREE
5019 @section @code{FREE} --- Frees memory
5020 @fnindex FREE
5021 @cindex pointer, cray
5022
5023 @table @asis
5024 @item @emph{Description}:
5025 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5026 intrinsic is an extension intended to be used with Cray pointers, and is
5027 provided in GNU Fortran to allow user to compile legacy code. For
5028 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5029 @code{DEALLOCATE}.
5030
5031 @item @emph{Standard}:
5032 GNU extension
5033
5034 @item @emph{Class}:
5035 Subroutine
5036
5037 @item @emph{Syntax}:
5038 @code{CALL FREE(PTR)}
5039
5040 @item @emph{Arguments}:
5041 @multitable @columnfractions .15 .70
5042 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5043 location of the memory that should be de-allocated.
5044 @end multitable
5045
5046 @item @emph{Return value}:
5047 None
5048
5049 @item @emph{Example}:
5050 See @code{MALLOC} for an example.
5051
5052 @item @emph{See also}:
5053 @ref{MALLOC}
5054 @end table
5055
5056
5057
5058 @node FSEEK
5059 @section @code{FSEEK} --- Low level file positioning subroutine
5060 @fnindex FSEEK
5061 @cindex file operation, seek
5062 @cindex file operation, position
5063
5064 @table @asis
5065 @item @emph{Description}:
5066 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5067 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5068 if set to 1, @var{OFFSET} is taken to be relative to the current position
5069 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5070 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5071 fails silently.
5072
5073 This intrinsic routine is not fully backwards compatible with @command{g77}.
5074 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5075 @var{STATUS} variable. If FSEEK is used in old code, change
5076 @smallexample
5077   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5078 @end smallexample
5079 to
5080 @smallexample
5081   INTEGER :: status
5082   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5083   IF (status /= 0) GOTO label
5084 @end smallexample
5085
5086 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5087 Programmers should consider the use of new stream IO feature in new code
5088 for future portability. See also @ref{Fortran 2003 status}.
5089
5090 @item @emph{Standard}:
5091 GNU extension
5092
5093 @item @emph{Class}:
5094 Subroutine
5095
5096 @item @emph{Syntax}:
5097 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5098
5099 @item @emph{Arguments}:
5100 @multitable @columnfractions .15 .70
5101 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
5102 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5103 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5104 Its value shall be either 0, 1 or 2.
5105 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5106 @code{INTEGER(4)}.
5107 @end multitable
5108
5109 @item @emph{Example}:
5110 @smallexample
5111 PROGRAM test_fseek
5112   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5113   INTEGER :: fd, offset, ierr
5114
5115   ierr   = 0
5116   offset = 5
5117   fd     = 10
5118
5119   OPEN(UNIT=fd, FILE="fseek.test")
5120   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
5121   print *, FTELL(fd), ierr
5122
5123   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
5124   print *, FTELL(fd), ierr
5125
5126   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
5127   print *, FTELL(fd), ierr
5128
5129   CLOSE(UNIT=fd)
5130 END PROGRAM
5131 @end smallexample
5132
5133 @item @emph{See also}:
5134 @ref{FTELL}
5135 @end table
5136
5137
5138
5139 @node FSTAT
5140 @section @code{FSTAT} --- Get file status
5141 @fnindex FSTAT
5142 @cindex file system, file status
5143
5144 @table @asis
5145 @item @emph{Description}:
5146 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5147 already opened file is obtained.
5148
5149 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5150
5151 This intrinsic is provided in both subroutine and function forms; however,
5152 only one form can be used in any given program unit.
5153
5154 @item @emph{Standard}:
5155 GNU extension
5156
5157 @item @emph{Class}:
5158 Subroutine, function
5159
5160 @item @emph{Syntax}:
5161 @multitable @columnfractions .80
5162 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5163 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5164 @end multitable
5165
5166 @item @emph{Arguments}:
5167 @multitable @columnfractions .15 .70
5168 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
5169 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5170 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5171 on success and a system specific error code otherwise.
5172 @end multitable
5173
5174 @item @emph{Example}:
5175 See @ref{STAT} for an example.
5176
5177 @item @emph{See also}:
5178 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5179 @end table
5180
5181
5182
5183 @node FTELL
5184 @section @code{FTELL} --- Current stream position
5185 @fnindex FTELL
5186 @cindex file operation, position
5187
5188 @table @asis
5189 @item @emph{Description}:
5190 Retrieves the current position within an open file.
5191
5192 This intrinsic is provided in both subroutine and function forms; however,
5193 only one form can be used in any given program unit.
5194
5195 @item @emph{Standard}:
5196 GNU extension
5197
5198 @item @emph{Class}:
5199 Subroutine, function
5200
5201 @item @emph{Syntax}:
5202 @multitable @columnfractions .80
5203 @item @code{CALL FTELL(UNIT, OFFSET)}
5204 @item @code{OFFSET = FTELL(UNIT)}
5205 @end multitable
5206
5207 @item @emph{Arguments}:
5208 @multitable @columnfractions .15 .70
5209 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
5210 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
5211 @end multitable
5212
5213 @item @emph{Return value}:
5214 In either syntax, @var{OFFSET} is set to the current offset of unit
5215 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5216
5217 @item @emph{Example}:
5218 @smallexample
5219 PROGRAM test_ftell
5220   INTEGER :: i
5221   OPEN(10, FILE="temp.dat")
5222   CALL ftell(10,i)
5223   WRITE(*,*) i
5224 END PROGRAM
5225 @end smallexample
5226
5227 @item @emph{See also}:
5228 @ref{FSEEK}
5229 @end table
5230
5231
5232
5233 @node GAMMA
5234 @section @code{GAMMA} --- Gamma function
5235 @fnindex GAMMA
5236 @fnindex DGAMMA
5237 @cindex Gamma function
5238 @cindex Factorial function
5239
5240 @table @asis
5241 @item @emph{Description}:
5242 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5243 integer values of @var{X} the Gamma function simplifies to the factorial
5244 function @math{\Gamma(x)=(x-1)!}.
5245
5246 @tex
5247 $$
5248 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5249 $$
5250 @end tex
5251
5252 @item @emph{Standard}:
5253 Fortran 2008 and later
5254
5255 @item @emph{Class}:
5256 Elemental function
5257
5258 @item @emph{Syntax}:
5259 @code{X = GAMMA(X)}
5260
5261 @item @emph{Arguments}:
5262 @multitable @columnfractions .15 .70
5263 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5264 nor a negative integer.
5265 @end multitable
5266
5267 @item @emph{Return value}:
5268 The return value is of type @code{REAL} of the same kind as @var{X}.
5269
5270 @item @emph{Example}:
5271 @smallexample
5272 program test_gamma
5273   real :: x = 1.0
5274   x = gamma(x) ! returns 1.0
5275 end program test_gamma
5276 @end smallexample
5277
5278 @item @emph{Specific names}:
5279 @multitable @columnfractions .20 .20 .20 .25
5280 @item Name             @tab Argument         @tab Return type       @tab Standard
5281 @item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
5282 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
5283 @end multitable
5284
5285 @item @emph{See also}:
5286 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5287
5288 @end table
5289
5290
5291
5292 @node GERROR
5293 @section @code{GERROR} --- Get last system error message
5294 @fnindex GERROR
5295 @cindex system, error handling
5296
5297 @table @asis
5298 @item @emph{Description}:
5299 Returns the system error message corresponding to the last system error.
5300 This resembles the functionality of @code{strerror(3)} in C.
5301
5302 @item @emph{Standard}:
5303 GNU extension
5304
5305 @item @emph{Class}:
5306 Subroutine
5307
5308 @item @emph{Syntax}:
5309 @code{CALL GERROR(RESULT)}
5310
5311 @item @emph{Arguments}:
5312 @multitable @columnfractions .15 .70
5313 @item @var{RESULT}  @tab Shall of type @code{CHARACTER} and of default
5314 @end multitable
5315
5316 @item @emph{Example}:
5317 @smallexample
5318 PROGRAM test_gerror
5319   CHARACTER(len=100) :: msg
5320   CALL gerror(msg)
5321   WRITE(*,*) msg
5322 END PROGRAM
5323 @end smallexample
5324
5325 @item @emph{See also}:
5326 @ref{IERRNO}, @ref{PERROR}
5327 @end table
5328
5329
5330
5331 @node GETARG
5332 @section @code{GETARG} --- Get command line arguments
5333 @fnindex GETARG
5334 @cindex command-line arguments
5335 @cindex arguments, to program
5336
5337 @table @asis
5338 @item @emph{Description}:
5339 Retrieve the @var{POS}-th argument that was passed on the
5340 command line when the containing program was invoked.
5341
5342 This intrinsic routine is provided for backwards compatibility with
5343 GNU Fortran 77.  In new code, programmers should consider the use of
5344 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5345 standard.
5346
5347 @item @emph{Standard}:
5348 GNU extension
5349
5350 @item @emph{Class}:
5351 Subroutine
5352
5353 @item @emph{Syntax}:
5354 @code{CALL GETARG(POS, VALUE)}
5355
5356 @item @emph{Arguments}:
5357 @multitable @columnfractions .15 .70
5358 @item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
5359 the default integer kind; @math{@var{POS} \geq 0}
5360 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5361 kind.
5362 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5363 @end multitable
5364
5365 @item @emph{Return value}:
5366 After @code{GETARG} returns, the @var{VALUE} argument holds the
5367 @var{POS}th command line argument. If @var{VALUE} can not hold the
5368 argument, it is truncated to fit the length of @var{VALUE}. If there are
5369 less than @var{POS} arguments specified at the command line, @var{VALUE}
5370 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5371 to the name of the program (on systems that support this feature).
5372
5373 @item @emph{Example}:
5374 @smallexample
5375 PROGRAM test_getarg
5376   INTEGER :: i
5377   CHARACTER(len=32) :: arg
5378
5379   DO i = 1, iargc()
5380     CALL getarg(i, arg)
5381     WRITE (*,*) arg
5382   END DO
5383 END PROGRAM
5384 @end smallexample
5385
5386 @item @emph{See also}:
5387 GNU Fortran 77 compatibility function: @ref{IARGC}
5388
5389 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5390 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5391 @end table
5392
5393
5394
5395 @node GET_COMMAND
5396 @section @code{GET_COMMAND} --- Get the entire command line
5397 @fnindex GET_COMMAND
5398 @cindex command-line arguments
5399 @cindex arguments, to program
5400
5401 @table @asis
5402 @item @emph{Description}:
5403 Retrieve the entire command line that was used to invoke the program.
5404
5405 @item @emph{Standard}:
5406 Fortran 2003 and later
5407
5408 @item @emph{Class}:
5409 Subroutine
5410
5411 @item @emph{Syntax}:
5412 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5413
5414 @item @emph{Arguments}:
5415 @multitable @columnfractions .15 .70
5416 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5417 of default kind.
5418 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5419 default kind.
5420 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5421 default kind.
5422 @end multitable
5423
5424 @item @emph{Return value}:
5425 If @var{COMMAND} is present, stores the entire command line that was used
5426 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5427 assigned the length of the command line. If @var{STATUS} is present, it
5428 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5429 short to store the command line, or a positive value in case of an error.
5430
5431 @item @emph{Example}:
5432 @smallexample
5433 PROGRAM test_get_command
5434   CHARACTER(len=255) :: cmd
5435   CALL get_command(cmd)
5436   WRITE (*,*) TRIM(cmd)
5437 END PROGRAM
5438 @end smallexample
5439
5440 @item @emph{See also}:
5441 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5442 @end table
5443
5444
5445
5446 @node GET_COMMAND_ARGUMENT
5447 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5448 @fnindex GET_COMMAND_ARGUMENT
5449 @cindex command-line arguments
5450 @cindex arguments, to program
5451
5452 @table @asis
5453 @item @emph{Description}:
5454 Retrieve the @var{NUMBER}-th argument that was passed on the
5455 command line when the containing program was invoked.
5456
5457 @item @emph{Standard}:
5458 Fortran 2003 and later
5459
5460 @item @emph{Class}:
5461 Subroutine
5462
5463 @item @emph{Syntax}:
5464 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5465
5466 @item @emph{Arguments}:
5467 @multitable @columnfractions .15 .70
5468 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5469 default kind, @math{@var{NUMBER} \geq 0}
5470 @item @var{VALUE}  @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5471 and of default kind.
5472 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5473 and of default kind.
5474 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5475 and of default kind.
5476 @end multitable
5477
5478 @item @emph{Return value}:
5479 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5480 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5481 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5482 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5483 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5484 systems that support this feature). The @var{LENGTH} argument contains the
5485 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5486 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5487 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5488 zero.
5489
5490 @item @emph{Example}:
5491 @smallexample
5492 PROGRAM test_get_command_argument
5493   INTEGER :: i
5494   CHARACTER(len=32) :: arg
5495
5496   i = 0
5497   DO
5498     CALL get_command_argument(i, arg)
5499     IF (LEN_TRIM(arg) == 0) EXIT
5500
5501     WRITE (*,*) TRIM(arg)
5502     i = i+1
5503   END DO
5504 END PROGRAM
5505 @end smallexample
5506
5507 @item @emph{See also}:
5508 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5509 @end table
5510
5511
5512
5513 @node GETCWD
5514 @section @code{GETCWD} --- Get current working directory
5515 @fnindex GETCWD
5516 @cindex system, working directory
5517
5518 @table @asis
5519 @item @emph{Description}:
5520 Get current working directory.
5521
5522 This intrinsic is provided in both subroutine and function forms; however,
5523 only one form can be used in any given program unit.
5524
5525 @item @emph{Standard}:
5526 GNU extension
5527
5528 @item @emph{Class}:
5529 Subroutine, function
5530
5531 @item @emph{Syntax}:
5532 @multitable @columnfractions .80
5533 @item @code{CALL GETCWD(C [, STATUS])}
5534 @item @code{STATUS = GETCWD(C)}
5535 @end multitable
5536
5537 @item @emph{Arguments}:
5538 @multitable @columnfractions .15 .70
5539 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5540 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5541 a system specific and nonzero error code otherwise.
5542 @end multitable
5543
5544 @item @emph{Example}:
5545 @smallexample
5546 PROGRAM test_getcwd
5547   CHARACTER(len=255) :: cwd
5548   CALL getcwd(cwd)
5549   WRITE(*,*) TRIM(cwd)
5550 END PROGRAM
5551 @end smallexample
5552
5553 @item @emph{See also}:
5554 @ref{CHDIR}
5555 @end table
5556
5557
5558
5559 @node GETENV
5560 @section @code{GETENV} --- Get an environmental variable
5561 @fnindex GETENV
5562 @cindex environment variable
5563
5564 @table @asis
5565 @item @emph{Description}:
5566 Get the @var{VALUE} of the environmental variable @var{NAME}.
5567
5568 This intrinsic routine is provided for backwards compatibility with
5569 GNU Fortran 77.  In new code, programmers should consider the use of
5570 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5571 2003 standard.
5572
5573 Note that @code{GETENV} need not be thread-safe. It is the
5574 responsibility of the user to ensure that the environment is not being
5575 updated concurrently with a call to the @code{GETENV} intrinsic.
5576
5577 @item @emph{Standard}:
5578 GNU extension
5579
5580 @item @emph{Class}:
5581 Subroutine
5582
5583 @item @emph{Syntax}:
5584 @code{CALL GETENV(NAME, VALUE)}
5585
5586 @item @emph{Arguments}:
5587 @multitable @columnfractions .15 .70
5588 @item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
5589 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5590 @end multitable
5591
5592 @item @emph{Return value}:
5593 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5594 not large enough to hold the data, it is truncated. If @var{NAME}
5595 is not set, @var{VALUE} will be filled with blanks.
5596
5597 @item @emph{Example}:
5598 @smallexample
5599 PROGRAM test_getenv
5600   CHARACTER(len=255) :: homedir
5601   CALL getenv("HOME", homedir)
5602   WRITE (*,*) TRIM(homedir)
5603 END PROGRAM
5604 @end smallexample
5605
5606 @item @emph{See also}:
5607 @ref{GET_ENVIRONMENT_VARIABLE}
5608 @end table
5609
5610
5611
5612 @node GET_ENVIRONMENT_VARIABLE
5613 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5614 @fnindex GET_ENVIRONMENT_VARIABLE
5615 @cindex environment variable
5616
5617 @table @asis
5618 @item @emph{Description}:
5619 Get the @var{VALUE} of the environmental variable @var{NAME}.
5620
5621 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5622 is the responsibility of the user to ensure that the environment is
5623 not being updated concurrently with a call to the
5624 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5625
5626 @item @emph{Standard}:
5627 Fortran 2003 and later
5628
5629 @item @emph{Class}:
5630 Subroutine
5631
5632 @item @emph{Syntax}:
5633 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5634
5635 @item @emph{Arguments}:
5636 @multitable @columnfractions .15 .70
5637 @item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER}
5638 and of default kind.
5639 @item @var{VALUE}     @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5640 and of default kind.
5641 @item @var{LENGTH}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5642 and of default kind.
5643 @item @var{STATUS}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5644 and of default kind.
5645 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5646 and of default kind.
5647 @end multitable
5648
5649 @item @emph{Return value}:
5650 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5651 not large enough to hold the data, it is truncated. If @var{NAME}
5652 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5653 contains the length needed for storing the environment variable @var{NAME}
5654 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5655 but too short for the environment variable; it is 1 if the environment
5656 variable does not exist and 2 if the processor does not support environment
5657 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5658 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5659 are significant; otherwise they are not part of the environment variable
5660 name.
5661
5662 @item @emph{Example}:
5663 @smallexample
5664 PROGRAM test_getenv
5665   CHARACTER(len=255) :: homedir
5666   CALL get_environment_variable("HOME", homedir)
5667   WRITE (*,*) TRIM(homedir)
5668 END PROGRAM
5669 @end smallexample
5670 @end table
5671
5672
5673
5674 @node GETGID
5675 @section @code{GETGID} --- Group ID function
5676 @fnindex GETGID
5677 @cindex system, group ID
5678
5679 @table @asis
5680 @item @emph{Description}:
5681 Returns the numerical group ID of the current process.
5682
5683 @item @emph{Standard}:
5684 GNU extension
5685
5686 @item @emph{Class}:
5687 Function
5688
5689 @item @emph{Syntax}:
5690 @code{RESULT = GETGID()}
5691
5692 @item @emph{Return value}:
5693 The return value of @code{GETGID} is an @code{INTEGER} of the default
5694 kind.
5695
5696
5697 @item @emph{Example}:
5698 See @code{GETPID} for an example.
5699
5700 @item @emph{See also}:
5701 @ref{GETPID}, @ref{GETUID}
5702 @end table
5703
5704
5705
5706 @node GETLOG
5707 @section @code{GETLOG} --- Get login name
5708 @fnindex GETLOG
5709 @cindex system, login name
5710 @cindex login name
5711
5712 @table @asis
5713 @item @emph{Description}:
5714 Gets the username under which the program is running.
5715
5716 @item @emph{Standard}:
5717 GNU extension
5718
5719 @item @emph{Class}:
5720 Subroutine
5721
5722 @item @emph{Syntax}:
5723 @code{CALL GETLOG(C)}
5724
5725 @item @emph{Arguments}:
5726 @multitable @columnfractions .15 .70
5727 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5728 @end multitable
5729
5730 @item @emph{Return value}:
5731 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5732 functions @code{geteuid} and @code{getpwuid} are not available, and
5733 the @code{getlogin} function is not implemented either, this will
5734 return a blank string.)
5735
5736 @item @emph{Example}:
5737 @smallexample
5738 PROGRAM TEST_GETLOG
5739   CHARACTER(32) :: login
5740   CALL GETLOG(login)
5741   WRITE(*,*) login
5742 END PROGRAM
5743 @end smallexample
5744
5745 @item @emph{See also}:
5746 @ref{GETUID}
5747 @end table
5748
5749
5750
5751 @node GETPID
5752 @section @code{GETPID} --- Process ID function
5753 @fnindex GETPID
5754 @cindex system, process ID
5755 @cindex process ID
5756
5757 @table @asis
5758 @item @emph{Description}:
5759 Returns the numerical process identifier of the current process.
5760
5761 @item @emph{Standard}:
5762 GNU extension
5763
5764 @item @emph{Class}:
5765 Function
5766
5767 @item @emph{Syntax}:
5768 @code{RESULT = GETPID()}
5769
5770 @item @emph{Return value}:
5771 The return value of @code{GETPID} is an @code{INTEGER} of the default
5772 kind.
5773
5774
5775 @item @emph{Example}:
5776 @smallexample
5777 program info
5778   print *, "The current process ID is ", getpid()
5779   print *, "Your numerical user ID is ", getuid()
5780   print *, "Your numerical group ID is ", getgid()
5781 end program info
5782 @end smallexample
5783
5784 @item @emph{See also}:
5785 @ref{GETGID}, @ref{GETUID}
5786 @end table
5787
5788
5789
5790 @node GETUID
5791 @section @code{GETUID} --- User ID function
5792 @fnindex GETUID
5793 @cindex system, user ID
5794 @cindex user id
5795
5796 @table @asis
5797 @item @emph{Description}:
5798 Returns the numerical user ID of the current process.
5799
5800 @item @emph{Standard}:
5801 GNU extension
5802
5803 @item @emph{Class}:
5804 Function
5805
5806 @item @emph{Syntax}:
5807 @code{RESULT = GETUID()}
5808
5809 @item @emph{Return value}:
5810 The return value of @code{GETUID} is an @code{INTEGER} of the default
5811 kind.
5812
5813
5814 @item @emph{Example}:
5815 See @code{GETPID} for an example.
5816
5817 @item @emph{See also}:
5818 @ref{GETPID}, @ref{GETLOG}
5819 @end table
5820
5821
5822
5823 @node GMTIME
5824 @section @code{GMTIME} --- Convert time to GMT info
5825 @fnindex GMTIME
5826 @cindex time, conversion to GMT info
5827
5828 @table @asis
5829 @item @emph{Description}:
5830 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5831 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5832 to the UTC time zone (Universal Coordinated Time, also known in some
5833 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5834
5835 @item @emph{Standard}:
5836 GNU extension
5837
5838 @item @emph{Class}:
5839 Subroutine
5840
5841 @item @emph{Syntax}:
5842 @code{CALL GMTIME(TIME, VALUES)}
5843
5844 @item @emph{Arguments}:
5845 @multitable @columnfractions .15 .70
5846 @item @var{TIME}   @tab An @code{INTEGER} scalar expression
5847 corresponding to a system time, with @code{INTENT(IN)}.
5848 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5849 with @code{INTENT(OUT)}.
5850 @end multitable
5851
5852 @item @emph{Return value}:
5853 The elements of @var{VALUES} are assigned as follows:
5854 @enumerate
5855 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5856 seconds
5857 @item Minutes after the hour, range 0--59
5858 @item Hours past midnight, range 0--23
5859 @item Day of month, range 0--31
5860 @item Number of months since January, range 0--12
5861 @item Years since 1900
5862 @item Number of days since Sunday, range 0--6
5863 @item Days since January 1
5864 @item Daylight savings indicator: positive if daylight savings is in
5865 effect, zero if not, and negative if the information is not available.
5866 @end enumerate
5867
5868 @item @emph{See also}:
5869 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5870
5871 @end table
5872
5873
5874
5875 @node HOSTNM
5876 @section @code{HOSTNM} --- Get system host name
5877 @fnindex HOSTNM
5878 @cindex system, host name
5879
5880 @table @asis
5881 @item @emph{Description}:
5882 Retrieves the host name of the system on which the program is running.
5883
5884 This intrinsic is provided in both subroutine and function forms; however,
5885 only one form can be used in any given program unit.
5886
5887 @item @emph{Standard}:
5888 GNU extension
5889
5890 @item @emph{Class}:
5891 Subroutine, function
5892
5893 @item @emph{Syntax}:
5894 @multitable @columnfractions .80
5895 @item @code{CALL HOSTNM(C [, STATUS])}
5896 @item @code{STATUS = HOSTNM(NAME)}
5897 @end multitable
5898
5899 @item @emph{Arguments}:
5900 @multitable @columnfractions .15 .70
5901 @item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
5902 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5903 Returns 0 on success, or a system specific error code otherwise.
5904 @end multitable
5905
5906 @item @emph{Return value}:
5907 In either syntax, @var{NAME} is set to the current hostname if it can
5908 be obtained, or to a blank string otherwise.
5909
5910 @end table
5911
5912
5913
5914 @node HUGE
5915 @section @code{HUGE} --- Largest number of a kind
5916 @fnindex HUGE
5917 @cindex limits, largest number
5918 @cindex model representation, largest number
5919
5920 @table @asis
5921 @item @emph{Description}:
5922 @code{HUGE(X)} returns the largest number that is not an infinity in
5923 the model of the type of @code{X}.
5924
5925 @item @emph{Standard}:
5926 Fortran 95 and later
5927
5928 @item @emph{Class}:
5929 Inquiry function
5930
5931 @item @emph{Syntax}:
5932 @code{RESULT = HUGE(X)}
5933
5934 @item @emph{Arguments}:
5935 @multitable @columnfractions .15 .70
5936 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5937 @end multitable
5938
5939 @item @emph{Return value}:
5940 The return value is of the same type and kind as @var{X}
5941
5942 @item @emph{Example}:
5943 @smallexample
5944 program test_huge_tiny
5945   print *, huge(0), huge(0.0), huge(0.0d0)
5946   print *, tiny(0.0), tiny(0.0d0)
5947 end program test_huge_tiny
5948 @end smallexample
5949 @end table
5950
5951
5952
5953 @node HYPOT
5954 @section @code{HYPOT} --- Euclidean distance function
5955 @fnindex HYPOT
5956 @cindex Euclidean distance
5957
5958 @table @asis
5959 @item @emph{Description}:
5960 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5961 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5962
5963 @item @emph{Standard}:
5964 Fortran 2008 and later
5965
5966 @item @emph{Class}:
5967 Elemental function
5968
5969 @item @emph{Syntax}:
5970 @code{RESULT = HYPOT(X, Y)}
5971
5972 @item @emph{Arguments}:
5973 @multitable @columnfractions .15 .70
5974 @item @var{X} @tab The type shall be @code{REAL}.
5975 @item @var{Y} @tab The type and kind type parameter shall be the same as
5976 @var{X}.
5977 @end multitable
5978
5979 @item @emph{Return value}:
5980 The return value has the same type and kind type parameter as @var{X}.
5981
5982 @item @emph{Example}:
5983 @smallexample
5984 program test_hypot
5985   real(4) :: x = 1.e0_4, y = 0.5e0_4
5986   x = hypot(x,y)
5987 end program test_hypot
5988 @end smallexample
5989 @end table
5990
5991
5992
5993 @node IACHAR
5994 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5995 @fnindex IACHAR
5996 @cindex @acronym{ASCII} collating sequence
5997 @cindex collating sequence, @acronym{ASCII}
5998 @cindex conversion, to integer
5999
6000 @table @asis
6001 @item @emph{Description}:
6002 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6003 in the first character position of @code{C}.
6004
6005 @item @emph{Standard}:
6006 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6007
6008 @item @emph{Class}:
6009 Elemental function
6010
6011 @item @emph{Syntax}:
6012 @code{RESULT = IACHAR(C [, KIND])}
6013
6014 @item @emph{Arguments}:
6015 @multitable @columnfractions .15 .70
6016 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6017 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6018 expression indicating the kind parameter of the result.
6019 @end multitable
6020
6021 @item @emph{Return value}:
6022 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6023 @var{KIND} is absent, the return value is of default integer kind.
6024
6025 @item @emph{Example}:
6026 @smallexample
6027 program test_iachar
6028   integer i
6029   i = iachar(' ')
6030 end program test_iachar
6031 @end smallexample
6032
6033 @item @emph{Note}:
6034 See @ref{ICHAR} for a discussion of converting between numerical values
6035 and formatted string representations.
6036
6037 @item @emph{See also}:
6038 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6039
6040 @end table
6041
6042
6043
6044 @node IALL
6045 @section @code{IALL} --- Bitwise AND of array elements
6046 @fnindex IALL
6047 @cindex array, AND
6048 @cindex bits, AND of array elements
6049
6050 @table @asis
6051 @item @emph{Description}:
6052 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6053 if the corresponding element in @var{MASK} is @code{TRUE}.
6054
6055 @item @emph{Standard}:
6056 Fortran 2008 and later
6057
6058 @item @emph{Class}:
6059 Transformational function
6060
6061 @item @emph{Syntax}:
6062 @multitable @columnfractions .80
6063 @item @code{RESULT = IALL(ARRAY[, MASK])}
6064 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6065 @end multitable
6066
6067 @item @emph{Arguments}:
6068 @multitable @columnfractions .15 .70
6069 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6070 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6071 @code{INTEGER} with a value in the range from 1 to n, where n
6072 equals the rank of @var{ARRAY}.
6073 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6074 and either be a scalar or an array of the same shape as @var{ARRAY}.
6075 @end multitable
6076
6077 @item @emph{Return value}:
6078 The result is of the same type as @var{ARRAY}.
6079
6080 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6081 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6082 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6083 dimension @var{DIM} dropped is returned.
6084
6085 @item @emph{Example}:
6086 @smallexample
6087 PROGRAM test_iall
6088   INTEGER(1) :: a(2)
6089
6090   a(1) = b'00100100'
6091   a(2) = b'01101010'
6092
6093   ! prints 00100000
6094   PRINT '(b8.8)', IALL(a)
6095 END PROGRAM
6096 @end smallexample
6097
6098 @item @emph{See also}:
6099 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6100 @end table
6101
6102
6103
6104 @node IAND
6105 @section @code{IAND} --- Bitwise logical and
6106 @fnindex IAND
6107 @cindex bitwise logical and
6108 @cindex logical and, bitwise
6109
6110 @table @asis
6111 @item @emph{Description}:
6112 Bitwise logical @code{AND}.
6113
6114 @item @emph{Standard}:
6115 Fortran 95 and later
6116
6117 @item @emph{Class}:
6118 Elemental function
6119
6120 @item @emph{Syntax}:
6121 @code{RESULT = IAND(I, J)}
6122
6123 @item @emph{Arguments}:
6124 @multitable @columnfractions .15 .70
6125 @item @var{I} @tab The type shall be @code{INTEGER}.
6126 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6127 kind as @var{I}.  (As a GNU extension, different kinds are also
6128 permitted.)
6129 @end multitable
6130
6131 @item @emph{Return value}:
6132 The return type is @code{INTEGER}, of the same kind as the
6133 arguments.  (If the argument kinds differ, it is of the same kind as
6134 the larger argument.)
6135
6136 @item @emph{Example}:
6137 @smallexample
6138 PROGRAM test_iand
6139   INTEGER :: a, b
6140   DATA a / Z'F' /, b / Z'3' /
6141   WRITE (*,*) IAND(a, b)
6142 END PROGRAM
6143 @end smallexample
6144
6145 @item @emph{See also}:
6146 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6147
6148 @end table
6149
6150
6151
6152 @node IANY
6153 @section @code{IANY} --- Bitwise OR of array elements
6154 @fnindex IANY
6155 @cindex array, OR
6156 @cindex bits, OR of array elements
6157
6158 @table @asis
6159 @item @emph{Description}:
6160 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6161 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6162
6163 @item @emph{Standard}:
6164 Fortran 2008 and later
6165
6166 @item @emph{Class}:
6167 Transformational function
6168
6169 @item @emph{Syntax}:
6170 @multitable @columnfractions .80
6171 @item @code{RESULT = IANY(ARRAY[, MASK])}
6172 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6173 @end multitable
6174
6175 @item @emph{Arguments}:
6176 @multitable @columnfractions .15 .70
6177 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6178 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6179 @code{INTEGER} with a value in the range from 1 to n, where n
6180 equals the rank of @var{ARRAY}.
6181 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6182 and either be a scalar or an array of the same shape as @var{ARRAY}.
6183 @end multitable
6184
6185 @item @emph{Return value}:
6186 The result is of the same type as @var{ARRAY}.
6187
6188 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6189 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6190 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6191 dimension @var{DIM} dropped is returned.
6192
6193 @item @emph{Example}:
6194 @smallexample
6195 PROGRAM test_iany
6196   INTEGER(1) :: a(2)
6197
6198   a(1) = b'00100100'
6199   a(2) = b'01101010'
6200
6201   ! prints 01101110
6202   PRINT '(b8.8)', IANY(a)
6203 END PROGRAM
6204 @end smallexample
6205
6206 @item @emph{See also}:
6207 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6208 @end table
6209
6210
6211
6212 @node IARGC
6213 @section @code{IARGC} --- Get the number of command line arguments
6214 @fnindex IARGC
6215 @cindex command-line arguments
6216 @cindex command-line arguments, number of
6217 @cindex arguments, to program
6218
6219 @table @asis
6220 @item @emph{Description}:
6221 @code{IARGC} returns the number of arguments passed on the
6222 command line when the containing program was invoked.
6223
6224 This intrinsic routine is provided for backwards compatibility with
6225 GNU Fortran 77.  In new code, programmers should consider the use of
6226 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6227 standard.
6228
6229 @item @emph{Standard}:
6230 GNU extension
6231
6232 @item @emph{Class}:
6233 Function
6234
6235 @item @emph{Syntax}:
6236 @code{RESULT = IARGC()}
6237
6238 @item @emph{Arguments}:
6239 None.
6240
6241 @item @emph{Return value}:
6242 The number of command line arguments, type @code{INTEGER(4)}.
6243
6244 @item @emph{Example}:
6245 See @ref{GETARG}
6246
6247 @item @emph{See also}:
6248 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6249
6250 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6251 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6252 @end table
6253
6254
6255
6256 @node IBCLR
6257 @section @code{IBCLR} --- Clear bit
6258 @fnindex IBCLR
6259 @cindex bits, unset
6260 @cindex bits, clear
6261
6262 @table @asis
6263 @item @emph{Description}:
6264 @code{IBCLR} returns the value of @var{I} with the bit at position
6265 @var{POS} set to zero.
6266
6267 @item @emph{Standard}:
6268 Fortran 95 and later
6269
6270 @item @emph{Class}:
6271 Elemental function
6272
6273 @item @emph{Syntax}:
6274 @code{RESULT = IBCLR(I, POS)}
6275
6276 @item @emph{Arguments}:
6277 @multitable @columnfractions .15 .70
6278 @item @var{I} @tab The type shall be @code{INTEGER}.
6279 @item @var{POS} @tab The type shall be @code{INTEGER}.
6280 @end multitable
6281
6282 @item @emph{Return value}:
6283 The return value is of type @code{INTEGER} and of the same kind as
6284 @var{I}.
6285
6286 @item @emph{See also}:
6287 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6288
6289 @end table
6290
6291
6292
6293 @node IBITS
6294 @section @code{IBITS} --- Bit extraction
6295 @fnindex IBITS
6296 @cindex bits, get
6297 @cindex bits, extract
6298
6299 @table @asis
6300 @item @emph{Description}:
6301 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6302 starting from bit position @var{POS} and extending left for @var{LEN}
6303 bits.  The result is right-justified and the remaining bits are
6304 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
6305 value @code{BIT_SIZE(I)}.
6306
6307 @item @emph{Standard}:
6308 Fortran 95 and later
6309
6310 @item @emph{Class}:
6311 Elemental function
6312
6313 @item @emph{Syntax}:
6314 @code{RESULT = IBITS(I, POS, LEN)}
6315
6316 @item @emph{Arguments}:
6317 @multitable @columnfractions .15 .70
6318 @item @var{I}   @tab The type shall be @code{INTEGER}.
6319 @item @var{POS} @tab The type shall be @code{INTEGER}.
6320 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6321 @end multitable
6322
6323 @item @emph{Return value}:
6324 The return value is of type @code{INTEGER} and of the same kind as
6325 @var{I}.
6326
6327 @item @emph{See also}:
6328 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6329 @end table
6330
6331
6332
6333 @node IBSET
6334 @section @code{IBSET} --- Set bit
6335 @fnindex IBSET
6336 @cindex bits, set
6337
6338 @table @asis
6339 @item @emph{Description}:
6340 @code{IBSET} returns the value of @var{I} with the bit at position
6341 @var{POS} set to one.
6342
6343 @item @emph{Standard}:
6344 Fortran 95 and later
6345
6346 @item @emph{Class}:
6347 Elemental function
6348
6349 @item @emph{Syntax}:
6350 @code{RESULT = IBSET(I, POS)}
6351
6352 @item @emph{Arguments}:
6353 @multitable @columnfractions .15 .70
6354 @item @var{I} @tab The type shall be @code{INTEGER}.
6355 @item @var{POS} @tab The type shall be @code{INTEGER}.
6356 @end multitable
6357
6358 @item @emph{Return value}:
6359 The return value is of type @code{INTEGER} and of the same kind as
6360 @var{I}.
6361
6362 @item @emph{See also}:
6363 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6364
6365 @end table
6366
6367
6368
6369 @node ICHAR
6370 @section @code{ICHAR} --- Character-to-integer conversion function
6371 @fnindex ICHAR
6372 @cindex conversion, to integer
6373
6374 @table @asis
6375 @item @emph{Description}:
6376 @code{ICHAR(C)} returns the code for the character in the first character
6377 position of @code{C} in the system's native character set.
6378 The correspondence between characters and their codes is not necessarily
6379 the same across different GNU Fortran implementations.
6380
6381 @item @emph{Standard}:
6382 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6383
6384 @item @emph{Class}:
6385 Elemental function
6386
6387 @item @emph{Syntax}:
6388 @code{RESULT = ICHAR(C [, KIND])}
6389
6390 @item @emph{Arguments}:
6391 @multitable @columnfractions .15 .70
6392 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6393 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6394 expression indicating the kind parameter of the result.
6395 @end multitable
6396
6397 @item @emph{Return value}:
6398 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6399 @var{KIND} is absent, the return value is of default integer kind.
6400
6401 @item @emph{Example}:
6402 @smallexample
6403 program test_ichar
6404   integer i
6405   i = ichar(' ')
6406 end program test_ichar
6407 @end smallexample
6408
6409 @item @emph{Specific names}:
6410 @multitable @columnfractions .20 .20 .20 .25
6411 @item Name             @tab Argument             @tab Return type       @tab Standard
6412 @item @code{ICHAR(C)}  @tab @code{CHARACTER C}   @tab @code{INTEGER(4)}    @tab Fortran 77 and later
6413 @end multitable
6414
6415 @item @emph{Note}:
6416 No intrinsic exists to convert between a numeric value and a formatted
6417 character string representation -- for instance, given the
6418 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6419 @code{REAL} value with the value 154, or vice versa. Instead, this
6420 functionality is provided by internal-file I/O, as in the following
6421 example:
6422 @smallexample
6423 program read_val
6424   integer value
6425   character(len=10) string, string2
6426   string = '154'
6427
6428   ! Convert a string to a numeric value
6429   read (string,'(I10)') value
6430   print *, value
6431
6432   ! Convert a value to a formatted string
6433   write (string2,'(I10)') value
6434   print *, string2
6435 end program read_val
6436 @end smallexample
6437
6438 @item @emph{See also}:
6439 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6440
6441 @end table
6442
6443
6444
6445 @node IDATE
6446 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6447 @fnindex IDATE
6448 @cindex date, current
6449 @cindex current date
6450
6451 @table @asis
6452 @item @emph{Description}:
6453 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6454 current local time. The day (in the range 1-31), month (in the range 1-12),
6455 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6456 The year has four significant digits.
6457
6458 @item @emph{Standard}:
6459 GNU extension
6460
6461 @item @emph{Class}:
6462 Subroutine
6463
6464 @item @emph{Syntax}:
6465 @code{CALL IDATE(VALUES)}
6466
6467 @item @emph{Arguments}:
6468 @multitable @columnfractions .15 .70
6469 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6470 the kind shall be the default integer kind.
6471 @end multitable
6472
6473 @item @emph{Return value}:
6474 Does not return anything.
6475
6476 @item @emph{Example}:
6477 @smallexample
6478 program test_idate
6479   integer, dimension(3) :: tarray
6480   call idate(tarray)
6481   print *, tarray(1)
6482   print *, tarray(2)
6483   print *, tarray(3)
6484 end program test_idate
6485 @end smallexample
6486 @end table
6487
6488
6489
6490 @node IEOR
6491 @section @code{IEOR} --- Bitwise logical exclusive or
6492 @fnindex IEOR
6493 @cindex bitwise logical exclusive or
6494 @cindex logical exclusive or, bitwise
6495
6496 @table @asis
6497 @item @emph{Description}:
6498 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6499 @var{J}.
6500
6501 @item @emph{Standard}:
6502 Fortran 95 and later
6503
6504 @item @emph{Class}:
6505 Elemental function
6506
6507 @item @emph{Syntax}:
6508 @code{RESULT = IEOR(I, J)}
6509
6510 @item @emph{Arguments}:
6511 @multitable @columnfractions .15 .70
6512 @item @var{I} @tab The type shall be @code{INTEGER}.
6513 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6514 kind as @var{I}.  (As a GNU extension, different kinds are also
6515 permitted.)
6516 @end multitable
6517
6518 @item @emph{Return value}:
6519 The return type is @code{INTEGER}, of the same kind as the
6520 arguments.  (If the argument kinds differ, it is of the same kind as
6521 the larger argument.)
6522
6523 @item @emph{See also}:
6524 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6525 @end table
6526
6527
6528
6529 @node IERRNO
6530 @section @code{IERRNO} --- Get the last system error number
6531 @fnindex IERRNO
6532 @cindex system, error handling
6533
6534 @table @asis
6535 @item @emph{Description}:
6536 Returns the last system error number, as given by the C @code{errno}
6537 variable.
6538
6539 @item @emph{Standard}:
6540 GNU extension
6541
6542 @item @emph{Class}:
6543 Function
6544
6545 @item @emph{Syntax}:
6546 @code{RESULT = IERRNO()}
6547
6548 @item @emph{Arguments}:
6549 None.
6550
6551 @item @emph{Return value}:
6552 The return value is of type @code{INTEGER} and of the default integer
6553 kind.
6554
6555 @item @emph{See also}:
6556 @ref{PERROR}
6557 @end table
6558
6559
6560
6561 @node IMAGE_INDEX
6562 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6563 @fnindex IMAGE_INDEX
6564 @cindex coarray, @code{IMAGE_INDEX}
6565 @cindex images, cosubscript to image index conversion
6566
6567 @table @asis
6568 @item @emph{Description}:
6569 Returns the image index belonging to a cosubscript.
6570
6571 @item @emph{Standard}:
6572 Fortran 2008 and later
6573
6574 @item @emph{Class}:
6575 Inquiry function.
6576
6577 @item @emph{Syntax}:
6578 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6579
6580 @item @emph{Arguments}: None.
6581 @multitable @columnfractions .15 .70
6582 @item @var{COARRAY} @tab Coarray of any type.
6583 @item @var{SUB}     @tab default integer rank-1 array of a size equal to
6584 the corank of @var{COARRAY}.
6585 @end multitable
6586
6587
6588 @item @emph{Return value}:
6589 Scalar default integer with the value of the image index which corresponds
6590 to the cosubscripts. For invalid cosubscripts the result is zero.
6591
6592 @item @emph{Example}:
6593 @smallexample
6594 INTEGER :: array[2,-1:4,8,*]
6595 ! Writes  28 (or 0 if there are fewer than 28 images)
6596 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6597 @end smallexample
6598
6599 @item @emph{See also}:
6600 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6601 @end table
6602
6603
6604
6605 @node INDEX intrinsic
6606 @section @code{INDEX} --- Position of a substring within a string
6607 @fnindex INDEX
6608 @cindex substring position
6609 @cindex string, find substring
6610
6611 @table @asis
6612 @item @emph{Description}:
6613 Returns the position of the start of the first occurrence of string
6614 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
6615 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
6616 the @var{BACK} argument is present and true, the return value is the
6617 start of the last occurrence rather than the first.
6618
6619 @item @emph{Standard}:
6620 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6621
6622 @item @emph{Class}:
6623 Elemental function
6624
6625 @item @emph{Syntax}:
6626 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6627
6628 @item @emph{Arguments}:
6629 @multitable @columnfractions .15 .70
6630 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6631 @code{INTENT(IN)}
6632 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6633 @code{INTENT(IN)}
6634 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6635 @code{INTENT(IN)}
6636 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6637 expression indicating the kind parameter of the result.
6638 @end multitable
6639
6640 @item @emph{Return value}:
6641 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6642 @var{KIND} is absent, the return value is of default integer kind.
6643
6644 @item @emph{Specific names}:
6645 @multitable @columnfractions .20 .20 .20 .25
6646 @item Name                            @tab Argument           @tab Return type       @tab Standard
6647 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER}   @tab @code{INTEGER(4)} @tab Fortran 77 and later
6648 @end multitable
6649
6650 @item @emph{See also}:
6651 @ref{SCAN}, @ref{VERIFY}
6652 @end table
6653
6654
6655
6656 @node INT
6657 @section @code{INT} --- Convert to integer type
6658 @fnindex INT
6659 @fnindex IFIX
6660 @fnindex IDINT
6661 @cindex conversion, to integer
6662
6663 @table @asis
6664 @item @emph{Description}:
6665 Convert to integer type
6666
6667 @item @emph{Standard}:
6668 Fortran 77 and later
6669
6670 @item @emph{Class}:
6671 Elemental function
6672
6673 @item @emph{Syntax}:
6674 @code{RESULT = INT(A [, KIND))}
6675
6676 @item @emph{Arguments}:
6677 @multitable @columnfractions .15 .70
6678 @item @var{A}    @tab Shall be of type @code{INTEGER},
6679 @code{REAL}, or @code{COMPLEX}.
6680 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6681 expression indicating the kind parameter of the result.
6682 @end multitable
6683
6684 @item @emph{Return value}:
6685 These functions return a @code{INTEGER} variable or array under
6686 the following rules:
6687
6688 @table @asis
6689 @item (A)
6690 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6691 @item (B)
6692 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6693 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6694 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6695 @item (C)
6696 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6697 @end table
6698
6699 @item @emph{Example}:
6700 @smallexample
6701 program test_int
6702   integer :: i = 42
6703   complex :: z = (-3.7, 1.0)
6704   print *, int(i)
6705   print *, int(z), int(z,8)
6706 end program
6707 @end smallexample
6708
6709 @item @emph{Specific names}:
6710 @multitable @columnfractions .20 .20 .20 .25
6711 @item Name            @tab Argument          @tab Return type       @tab Standard
6712 @item @code{INT(A)}   @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6713 @item @code{IFIX(A)}  @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6714 @item @code{IDINT(A)} @tab @code{REAL(8) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6715 @end multitable
6716
6717 @end table
6718
6719
6720 @node INT2
6721 @section @code{INT2} --- Convert to 16-bit integer type
6722 @fnindex INT2
6723 @fnindex SHORT
6724 @cindex conversion, to integer
6725
6726 @table @asis
6727 @item @emph{Description}:
6728 Convert to a @code{KIND=2} integer type. This is equivalent to the
6729 standard @code{INT} intrinsic with an optional argument of
6730 @code{KIND=2}, and is only included for backwards compatibility.
6731
6732 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6733
6734 @item @emph{Standard}:
6735 GNU extension
6736
6737 @item @emph{Class}:
6738 Elemental function
6739
6740 @item @emph{Syntax}:
6741 @code{RESULT = INT2(A)}
6742
6743 @item @emph{Arguments}:
6744 @multitable @columnfractions .15 .70
6745 @item @var{A}    @tab Shall be of type @code{INTEGER},
6746 @code{REAL}, or @code{COMPLEX}.
6747 @end multitable
6748
6749 @item @emph{Return value}:
6750 The return value is a @code{INTEGER(2)} variable.
6751
6752 @item @emph{See also}:
6753 @ref{INT}, @ref{INT8}, @ref{LONG}
6754 @end table
6755
6756
6757
6758 @node INT8
6759 @section @code{INT8} --- Convert to 64-bit integer type
6760 @fnindex INT8
6761 @cindex conversion, to integer
6762
6763 @table @asis
6764 @item @emph{Description}:
6765 Convert to a @code{KIND=8} integer type. This is equivalent to the
6766 standard @code{INT} intrinsic with an optional argument of
6767 @code{KIND=8}, and is only included for backwards compatibility.
6768
6769 @item @emph{Standard}:
6770 GNU extension
6771
6772 @item @emph{Class}:
6773 Elemental function
6774
6775 @item @emph{Syntax}:
6776 @code{RESULT = INT8(A)}
6777
6778 @item @emph{Arguments}:
6779 @multitable @columnfractions .15 .70
6780 @item @var{A}    @tab Shall be of type @code{INTEGER},
6781 @code{REAL}, or @code{COMPLEX}.
6782 @end multitable
6783
6784 @item @emph{Return value}:
6785 The return value is a @code{INTEGER(8)} variable.
6786
6787 @item @emph{See also}:
6788 @ref{INT}, @ref{INT2}, @ref{LONG}
6789 @end table
6790
6791
6792
6793 @node IOR
6794 @section @code{IOR} --- Bitwise logical or
6795 @fnindex IOR
6796 @cindex bitwise logical or
6797 @cindex logical or, bitwise
6798
6799 @table @asis
6800 @item @emph{Description}:
6801 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6802 @var{J}.
6803
6804 @item @emph{Standard}:
6805 Fortran 95 and later
6806
6807 @item @emph{Class}:
6808 Elemental function
6809
6810 @item @emph{Syntax}:
6811 @code{RESULT = IOR(I, J)}
6812
6813 @item @emph{Arguments}:
6814 @multitable @columnfractions .15 .70
6815 @item @var{I} @tab The type shall be @code{INTEGER}.
6816 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6817 kind as @var{I}.  (As a GNU extension, different kinds are also
6818 permitted.)
6819 @end multitable
6820
6821 @item @emph{Return value}:
6822 The return type is @code{INTEGER}, of the same kind as the
6823 arguments.  (If the argument kinds differ, it is of the same kind as
6824 the larger argument.)
6825
6826 @item @emph{See also}:
6827 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6828 @end table
6829
6830
6831
6832 @node IPARITY
6833 @section @code{IPARITY} --- Bitwise XOR of array elements
6834 @fnindex IPARITY
6835 @cindex array, parity
6836 @cindex array, XOR
6837 @cindex bits, XOR of array elements
6838
6839 @table @asis
6840 @item @emph{Description}:
6841 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6842 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6843
6844 @item @emph{Standard}:
6845 Fortran 2008 and later
6846
6847 @item @emph{Class}:
6848 Transformational function
6849
6850 @item @emph{Syntax}:
6851 @multitable @columnfractions .80
6852 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6853 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6854 @end multitable
6855
6856 @item @emph{Arguments}:
6857 @multitable @columnfractions .15 .70
6858 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6859 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6860 @code{INTEGER} with a value in the range from 1 to n, where n
6861 equals the rank of @var{ARRAY}.
6862 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6863 and either be a scalar or an array of the same shape as @var{ARRAY}.
6864 @end multitable
6865
6866 @item @emph{Return value}:
6867 The result is of the same type as @var{ARRAY}.
6868
6869 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6870 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6871 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6872 dimension @var{DIM} dropped is returned.
6873
6874 @item @emph{Example}:
6875 @smallexample
6876 PROGRAM test_iparity
6877   INTEGER(1) :: a(2)
6878
6879   a(1) = b'00100100'
6880   a(2) = b'01101010'
6881
6882   ! prints 01001110
6883   PRINT '(b8.8)', IPARITY(a)
6884 END PROGRAM
6885 @end smallexample
6886
6887 @item @emph{See also}:
6888 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6889 @end table
6890
6891
6892
6893 @node IRAND
6894 @section @code{IRAND} --- Integer pseudo-random number
6895 @fnindex IRAND
6896 @cindex random number generation
6897
6898 @table @asis
6899 @item @emph{Description}:
6900 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6901 distribution between 0 and a system-dependent limit (which is in most
6902 cases 2147483647). If @var{FLAG} is 0, the next number
6903 in the current sequence is returned; if @var{FLAG} is 1, the generator
6904 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6905 it is used as a new seed with @code{SRAND}.
6906
6907 This intrinsic routine is provided for backwards compatibility with
6908 GNU Fortran 77. It implements a simple modulo generator as provided
6909 by @command{g77}. For new code, one should consider the use of
6910 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6911
6912 @item @emph{Standard}:
6913 GNU extension
6914
6915 @item @emph{Class}:
6916 Function
6917
6918 @item @emph{Syntax}:
6919 @code{RESULT = IRAND(I)}
6920
6921 @item @emph{Arguments}:
6922 @multitable @columnfractions .15 .70
6923 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6924 @end multitable
6925
6926 @item @emph{Return value}:
6927 The return value is of @code{INTEGER(kind=4)} type.
6928
6929 @item @emph{Example}:
6930 @smallexample
6931 program test_irand
6932   integer,parameter :: seed = 86456
6933
6934   call srand(seed)
6935   print *, irand(), irand(), irand(), irand()
6936   print *, irand(seed), irand(), irand(), irand()
6937 end program test_irand
6938 @end smallexample
6939
6940 @end table
6941
6942
6943
6944 @node IS_IOSTAT_END
6945 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6946 @fnindex IS_IOSTAT_END
6947 @cindex @code{IOSTAT}, end of file
6948
6949 @table @asis
6950 @item @emph{Description}:
6951 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6952 status ``end of file''. The function is equivalent to comparing the variable
6953 with the @code{IOSTAT_END} parameter of the intrinsic module
6954 @code{ISO_FORTRAN_ENV}.
6955
6956 @item @emph{Standard}:
6957 Fortran 2003 and later
6958
6959 @item @emph{Class}:
6960 Elemental function
6961
6962 @item @emph{Syntax}:
6963 @code{RESULT = IS_IOSTAT_END(I)}
6964
6965 @item @emph{Arguments}:
6966 @multitable @columnfractions .15 .70
6967 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6968 @end multitable
6969
6970 @item @emph{Return value}:
6971 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6972 @var{I} has the value which indicates an end of file condition for
6973 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6974
6975 @item @emph{Example}:
6976 @smallexample
6977 PROGRAM iostat
6978   IMPLICIT NONE
6979   INTEGER :: stat, i
6980   OPEN(88, FILE='test.dat')
6981   READ(88, *, IOSTAT=stat) i
6982   IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6983 END PROGRAM
6984 @end smallexample
6985 @end table
6986
6987
6988
6989 @node IS_IOSTAT_EOR
6990 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6991 @fnindex IS_IOSTAT_EOR
6992 @cindex @code{IOSTAT}, end of record
6993
6994 @table @asis
6995 @item @emph{Description}:
6996 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6997 status ``end of record''. The function is equivalent to comparing the
6998 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6999 @code{ISO_FORTRAN_ENV}.
7000
7001 @item @emph{Standard}:
7002 Fortran 2003 and later
7003
7004 @item @emph{Class}:
7005 Elemental function
7006
7007 @item @emph{Syntax}:
7008 @code{RESULT = IS_IOSTAT_EOR(I)}
7009
7010 @item @emph{Arguments}:
7011 @multitable @columnfractions .15 .70
7012 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7013 @end multitable
7014
7015 @item @emph{Return value}:
7016 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7017 @var{I} has the value which indicates an end of file condition for
7018 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7019
7020 @item @emph{Example}:
7021 @smallexample
7022 PROGRAM iostat
7023   IMPLICIT NONE
7024   INTEGER :: stat, i(50)
7025   OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7026   READ(88, IOSTAT=stat) i
7027   IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7028 END PROGRAM
7029 @end smallexample
7030 @end table
7031
7032
7033
7034 @node ISATTY
7035 @section @code{ISATTY} --- Whether a unit is a terminal device.
7036 @fnindex ISATTY
7037 @cindex system, terminal
7038
7039 @table @asis
7040 @item @emph{Description}:
7041 Determine whether a unit is connected to a terminal device.
7042
7043 @item @emph{Standard}:
7044 GNU extension
7045
7046 @item @emph{Class}:
7047 Function
7048
7049 @item @emph{Syntax}:
7050 @code{RESULT = ISATTY(UNIT)}
7051
7052 @item @emph{Arguments}:
7053 @multitable @columnfractions .15 .70
7054 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7055 @end multitable
7056
7057 @item @emph{Return value}:
7058 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7059 device, @code{.FALSE.} otherwise.
7060
7061 @item @emph{Example}:
7062 @smallexample
7063 PROGRAM test_isatty
7064   INTEGER(kind=1) :: unit
7065   DO unit = 1, 10
7066     write(*,*) isatty(unit=unit)
7067   END DO
7068 END PROGRAM
7069 @end smallexample
7070 @item @emph{See also}:
7071 @ref{TTYNAM}
7072 @end table
7073
7074
7075
7076 @node ISHFT
7077 @section @code{ISHFT} --- Shift bits
7078 @fnindex ISHFT
7079 @cindex bits, shift
7080
7081 @table @asis
7082 @item @emph{Description}:
7083 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7084 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
7085 zero corresponds to a left shift, a value of zero corresponds to no
7086 shift, and a value less than zero corresponds to a right shift.  If the
7087 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7088 value is undefined.  Bits shifted out from the left end or right end are
7089 lost; zeros are shifted in from the opposite end.
7090
7091 @item @emph{Standard}:
7092 Fortran 95 and later
7093
7094 @item @emph{Class}:
7095 Elemental function
7096
7097 @item @emph{Syntax}:
7098 @code{RESULT = ISHFT(I, SHIFT)}
7099
7100 @item @emph{Arguments}:
7101 @multitable @columnfractions .15 .70
7102 @item @var{I} @tab The type shall be @code{INTEGER}.
7103 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7104 @end multitable
7105
7106 @item @emph{Return value}:
7107 The return value is of type @code{INTEGER} and of the same kind as
7108 @var{I}.
7109
7110 @item @emph{See also}:
7111 @ref{ISHFTC}
7112 @end table
7113
7114
7115
7116 @node ISHFTC
7117 @section @code{ISHFTC} --- Shift bits circularly
7118 @fnindex ISHFTC
7119 @cindex bits, shift circular
7120
7121 @table @asis
7122 @item @emph{Description}:
7123 @code{ISHFTC} returns a value corresponding to @var{I} with the
7124 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7125 is, bits shifted out one end are shifted into the opposite end.  A value
7126 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7127 zero corresponds to no shift, and a value less than zero corresponds to
7128 a right shift.  The absolute value of @var{SHIFT} must be less than
7129 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
7130 equivalent to @code{BIT_SIZE(I)}.
7131
7132 @item @emph{Standard}:
7133 Fortran 95 and later
7134
7135 @item @emph{Class}:
7136 Elemental function
7137
7138 @item @emph{Syntax}:
7139 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7140
7141 @item @emph{Arguments}:
7142 @multitable @columnfractions .15 .70
7143 @item @var{I} @tab The type shall be @code{INTEGER}.
7144 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7145 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7146 the value must be greater than zero and less than or equal to
7147 @code{BIT_SIZE(I)}.
7148 @end multitable
7149
7150 @item @emph{Return value}:
7151 The return value is of type @code{INTEGER} and of the same kind as
7152 @var{I}.
7153
7154 @item @emph{See also}:
7155 @ref{ISHFT}
7156 @end table
7157
7158
7159
7160 @node ISNAN
7161 @section @code{ISNAN} --- Test for a NaN
7162 @fnindex ISNAN
7163 @cindex IEEE, ISNAN
7164
7165 @table @asis
7166 @item @emph{Description}:
7167 @code{ISNAN} tests whether a floating-point value is an IEEE
7168 Not-a-Number (NaN).
7169 @item @emph{Standard}:
7170 GNU extension
7171
7172 @item @emph{Class}:
7173 Elemental function
7174
7175 @item @emph{Syntax}:
7176 @code{ISNAN(X)}
7177
7178 @item @emph{Arguments}:
7179 @multitable @columnfractions .15 .70
7180 @item @var{X} @tab Variable of the type @code{REAL}.
7181
7182 @end multitable
7183
7184 @item @emph{Return value}:
7185 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7186 if @var{X} is a NaN and @code{FALSE} otherwise.
7187
7188 @item @emph{Example}:
7189 @smallexample
7190 program test_nan
7191   implicit none
7192   real :: x
7193   x = -1.0
7194   x = sqrt(x)
7195   if (isnan(x)) stop '"x" is a NaN'
7196 end program test_nan
7197 @end smallexample
7198 @end table
7199
7200
7201
7202 @node ITIME
7203 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7204 @fnindex ITIME
7205 @cindex time, current
7206 @cindex current time
7207
7208 @table @asis
7209 @item @emph{Description}:
7210 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7211 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7212 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7213 respectively.
7214
7215 @item @emph{Standard}:
7216 GNU extension
7217
7218 @item @emph{Class}:
7219 Subroutine
7220
7221 @item @emph{Syntax}:
7222 @code{CALL ITIME(VALUES)}
7223
7224 @item @emph{Arguments}:
7225 @multitable @columnfractions .15 .70
7226 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7227 and the kind shall be the default integer kind.
7228 @end multitable
7229
7230 @item @emph{Return value}:
7231 Does not return anything.
7232
7233
7234 @item @emph{Example}:
7235 @smallexample
7236 program test_itime
7237   integer, dimension(3) :: tarray
7238   call itime(tarray)
7239   print *, tarray(1)
7240   print *, tarray(2)
7241   print *, tarray(3)
7242 end program test_itime
7243 @end smallexample
7244 @end table
7245
7246
7247
7248 @node KILL
7249 @section @code{KILL} --- Send a signal to a process
7250 @fnindex KILL
7251
7252 @table @asis
7253 @item @emph{Description}:
7254 @item @emph{Standard}:
7255 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7256 See @code{kill(2)}.
7257
7258 This intrinsic is provided in both subroutine and function forms; however,
7259 only one form can be used in any given program unit.
7260
7261 @item @emph{Class}:
7262 Subroutine, function
7263
7264 @item @emph{Syntax}:
7265 @multitable @columnfractions .80
7266 @item @code{CALL KILL(C, VALUE [, STATUS])}
7267 @item @code{STATUS = KILL(C, VALUE)}
7268 @end multitable
7269
7270 @item @emph{Arguments}:
7271 @multitable @columnfractions .15 .70
7272 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7273 @code{INTENT(IN)}
7274 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7275 @code{INTENT(IN)}
7276 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7277 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7278 otherwise.
7279 @end multitable
7280
7281 @item @emph{See also}:
7282 @ref{ABORT}, @ref{EXIT}
7283 @end table
7284
7285
7286
7287 @node KIND
7288 @section @code{KIND} --- Kind of an entity
7289 @fnindex KIND
7290 @cindex kind
7291
7292 @table @asis
7293 @item @emph{Description}:
7294 @code{KIND(X)} returns the kind value of the entity @var{X}.
7295
7296 @item @emph{Standard}:
7297 Fortran 95 and later
7298
7299 @item @emph{Class}:
7300 Inquiry function
7301
7302 @item @emph{Syntax}:
7303 @code{K = KIND(X)}
7304
7305 @item @emph{Arguments}:
7306 @multitable @columnfractions .15 .70
7307 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7308 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7309 @end multitable
7310
7311 @item @emph{Return value}:
7312 The return value is a scalar of type @code{INTEGER} and of the default
7313 integer kind.
7314
7315 @item @emph{Example}:
7316 @smallexample
7317 program test_kind
7318   integer,parameter :: kc = kind(' ')
7319   integer,parameter :: kl = kind(.true.)
7320
7321   print *, "The default character kind is ", kc
7322   print *, "The default logical kind is ", kl
7323 end program test_kind
7324 @end smallexample
7325
7326 @end table
7327
7328
7329
7330 @node LBOUND
7331 @section @code{LBOUND} --- Lower dimension bounds of an array
7332 @fnindex LBOUND
7333 @cindex array, lower bound
7334
7335 @table @asis
7336 @item @emph{Description}:
7337 Returns the lower bounds of an array, or a single lower bound
7338 along the @var{DIM} dimension.
7339 @item @emph{Standard}:
7340 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7341
7342 @item @emph{Class}:
7343 Inquiry function
7344
7345 @item @emph{Syntax}:
7346 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7347
7348 @item @emph{Arguments}:
7349 @multitable @columnfractions .15 .70
7350 @item @var{ARRAY} @tab Shall be an array, of any type.
7351 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7352 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7353 expression indicating the kind parameter of the result.
7354 @end multitable
7355
7356 @item @emph{Return value}:
7357 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7358 @var{KIND} is absent, the return value is of default integer kind.
7359 If @var{DIM} is absent, the result is an array of the lower bounds of
7360 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
7361 corresponding to the lower bound of the array along that dimension.  If
7362 @var{ARRAY} is an expression rather than a whole array or array
7363 structure component, or if it has a zero extent along the relevant
7364 dimension, the lower bound is taken to be 1.
7365
7366 @item @emph{See also}:
7367 @ref{UBOUND}, @ref{LCOBOUND}
7368 @end table
7369
7370
7371
7372 @node LCOBOUND
7373 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7374 @fnindex LCOBOUND
7375 @cindex coarray, lower bound
7376
7377 @table @asis
7378 @item @emph{Description}:
7379 Returns the lower bounds of a coarray, or a single lower cobound
7380 along the @var{DIM} codimension.
7381 @item @emph{Standard}:
7382 Fortran 2008 and later
7383
7384 @item @emph{Class}:
7385 Inquiry function
7386
7387 @item @emph{Syntax}:
7388 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7389
7390 @item @emph{Arguments}:
7391 @multitable @columnfractions .15 .70
7392 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7393 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7394 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7395 expression indicating the kind parameter of the result.
7396 @end multitable
7397
7398 @item @emph{Return value}:
7399 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7400 @var{KIND} is absent, the return value is of default integer kind.
7401 If @var{DIM} is absent, the result is an array of the lower cobounds of
7402 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
7403 corresponding to the lower cobound of the array along that codimension.
7404
7405 @item @emph{See also}:
7406 @ref{UCOBOUND}, @ref{LBOUND}
7407 @end table
7408
7409
7410
7411 @node LEADZ
7412 @section @code{LEADZ} --- Number of leading zero bits of an integer
7413 @fnindex LEADZ
7414 @cindex zero bits
7415
7416 @table @asis
7417 @item @emph{Description}:
7418 @code{LEADZ} returns the number of leading zero bits of an integer.
7419
7420 @item @emph{Standard}:
7421 Fortran 2008 and later
7422
7423 @item @emph{Class}:
7424 Elemental function
7425
7426 @item @emph{Syntax}:
7427 @code{RESULT = LEADZ(I)}
7428
7429 @item @emph{Arguments}:
7430 @multitable @columnfractions .15 .70
7431 @item @var{I} @tab Shall be of type @code{INTEGER}.
7432 @end multitable
7433
7434 @item @emph{Return value}:
7435 The type of the return value is the default @code{INTEGER}.
7436 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7437
7438 @item @emph{Example}:
7439 @smallexample
7440 PROGRAM test_leadz
7441   WRITE (*,*) BIT_SIZE(1)  ! prints 32
7442   WRITE (*,*) LEADZ(1)     ! prints 31
7443 END PROGRAM
7444 @end smallexample
7445
7446 @item @emph{See also}:
7447 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7448 @end table
7449
7450
7451
7452 @node LEN
7453 @section @code{LEN} --- Length of a character entity
7454 @fnindex LEN
7455 @cindex string, length
7456
7457 @table @asis
7458 @item @emph{Description}:
7459 Returns the length of a character string.  If @var{STRING} is an array,
7460 the length of an element of @var{STRING} is returned.  Note that
7461 @var{STRING} need not be defined when this intrinsic is invoked, since
7462 only the length, not the content, of @var{STRING} is needed.
7463
7464 @item @emph{Standard}:
7465 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7466
7467 @item @emph{Class}:
7468 Inquiry function
7469
7470 @item @emph{Syntax}:
7471 @code{L = LEN(STRING [, KIND])}
7472
7473 @item @emph{Arguments}:
7474 @multitable @columnfractions .15 .70
7475 @item @var{STRING} @tab Shall be a scalar or array of type
7476 @code{CHARACTER}, with @code{INTENT(IN)}
7477 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7478 expression indicating the kind parameter of the result.
7479 @end multitable
7480
7481 @item @emph{Return value}:
7482 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7483 @var{KIND} is absent, the return value is of default integer kind.
7484
7485
7486 @item @emph{Specific names}:
7487 @multitable @columnfractions .20 .20 .20 .25
7488 @item Name               @tab Argument          @tab Return type       @tab Standard
7489 @item @code{LEN(STRING)} @tab @code{CHARACTER}  @tab @code{INTEGER}    @tab Fortran 77 and later
7490 @end multitable
7491
7492
7493 @item @emph{See also}:
7494 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7495 @end table
7496
7497
7498
7499 @node LEN_TRIM
7500 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7501 @fnindex LEN_TRIM
7502 @cindex string, length, without trailing whitespace
7503
7504 @table @asis
7505 @item @emph{Description}:
7506 Returns the length of a character string, ignoring any trailing blanks.
7507
7508 @item @emph{Standard}:
7509 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7510
7511 @item @emph{Class}:
7512 Elemental function
7513
7514 @item @emph{Syntax}:
7515 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7516
7517 @item @emph{Arguments}:
7518 @multitable @columnfractions .15 .70
7519 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7520 with @code{INTENT(IN)}
7521 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7522 expression indicating the kind parameter of the result.
7523 @end multitable
7524
7525 @item @emph{Return value}:
7526 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7527 @var{KIND} is absent, the return value is of default integer kind.
7528
7529 @item @emph{See also}:
7530 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7531 @end table
7532
7533
7534
7535 @node LGE
7536 @section @code{LGE} --- Lexical greater than or equal
7537 @fnindex LGE
7538 @cindex lexical comparison of strings
7539 @cindex string, comparison
7540
7541 @table @asis
7542 @item @emph{Description}:
7543 Determines whether one string is lexically greater than or equal to
7544 another string, where the two strings are interpreted as containing
7545 ASCII character codes.  If the String A and String B are not the same
7546 length, the shorter is compared as if spaces were appended to it to form
7547 a value that has the same length as the longer.
7548
7549 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7550 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7551 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7552 that the latter use the processor's character ordering (which is not
7553 ASCII on some targets), whereas the former always use the ASCII
7554 ordering.
7555
7556 @item @emph{Standard}:
7557 Fortran 77 and later
7558
7559 @item @emph{Class}:
7560 Elemental function
7561
7562 @item @emph{Syntax}:
7563 @code{RESULT = LGE(STRING_A, STRING_B)}
7564
7565 @item @emph{Arguments}:
7566 @multitable @columnfractions .15 .70
7567 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7568 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7569 @end multitable
7570
7571 @item @emph{Return value}:
7572 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7573 otherwise, based on the ASCII ordering.
7574
7575 @item @emph{Specific names}:
7576 @multitable @columnfractions .20 .20 .20 .25
7577 @item Name                           @tab Argument          @tab Return type       @tab Standard
7578 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7579 @end multitable
7580
7581 @item @emph{See also}:
7582 @ref{LGT}, @ref{LLE}, @ref{LLT}
7583 @end table
7584
7585
7586
7587 @node LGT
7588 @section @code{LGT} --- Lexical greater than
7589 @fnindex LGT
7590 @cindex lexical comparison of strings
7591 @cindex string, comparison
7592
7593 @table @asis
7594 @item @emph{Description}:
7595 Determines whether one string is lexically greater than another string,
7596 where the two strings are interpreted as containing ASCII character
7597 codes.  If the String A and String B are not the same length, the
7598 shorter is compared as if spaces were appended to it to form a value
7599 that has the same length as the longer.
7600
7601 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7602 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7603 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7604 that the latter use the processor's character ordering (which is not
7605 ASCII on some targets), whereas the former always use the ASCII
7606 ordering.
7607
7608 @item @emph{Standard}:
7609 Fortran 77 and later
7610
7611 @item @emph{Class}:
7612 Elemental function
7613
7614 @item @emph{Syntax}:
7615 @code{RESULT = LGT(STRING_A, STRING_B)}
7616
7617 @item @emph{Arguments}:
7618 @multitable @columnfractions .15 .70
7619 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7620 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7621 @end multitable
7622
7623 @item @emph{Return value}:
7624 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7625 otherwise, based on the ASCII ordering.
7626
7627 @item @emph{Specific names}:
7628 @multitable @columnfractions .20 .20 .20 .25
7629 @item Name                           @tab Argument          @tab Return type       @tab Standard
7630 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7631 @end multitable
7632
7633 @item @emph{See also}:
7634 @ref{LGE}, @ref{LLE}, @ref{LLT}
7635 @end table
7636
7637
7638
7639 @node LINK
7640 @section @code{LINK} --- Create a hard link
7641 @fnindex LINK
7642 @cindex file system, create link
7643 @cindex file system, hard link
7644
7645 @table @asis
7646 @item @emph{Description}:
7647 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7648 character (@code{CHAR(0)}) can be used to mark the end of the names in
7649 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7650 names are ignored.  If the @var{STATUS} argument is supplied, it
7651 contains 0 on success or a nonzero error code upon return; see
7652 @code{link(2)}.
7653
7654 This intrinsic is provided in both subroutine and function forms;
7655 however, only one form can be used in any given program unit.
7656
7657 @item @emph{Standard}:
7658 GNU extension
7659
7660 @item @emph{Class}:
7661 Subroutine, function
7662
7663 @item @emph{Syntax}:
7664 @multitable @columnfractions .80
7665 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7666 @item @code{STATUS = LINK(PATH1, PATH2)}
7667 @end multitable
7668
7669 @item @emph{Arguments}:
7670 @multitable @columnfractions .15 .70
7671 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7672 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7673 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7674 @end multitable
7675
7676 @item @emph{See also}:
7677 @ref{SYMLNK}, @ref{UNLINK}
7678 @end table
7679
7680
7681
7682 @node LLE
7683 @section @code{LLE} --- Lexical less than or equal
7684 @fnindex LLE
7685 @cindex lexical comparison of strings
7686 @cindex string, comparison
7687
7688 @table @asis
7689 @item @emph{Description}:
7690 Determines whether one string is lexically less than or equal to another
7691 string, where the two strings are interpreted as containing ASCII
7692 character codes.  If the String A and String B are not the same length,
7693 the shorter is compared as if spaces were appended to it to form a value
7694 that has the same length as the longer.
7695
7696 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7697 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7698 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7699 that the latter use the processor's character ordering (which is not
7700 ASCII on some targets), whereas the former always use the ASCII
7701 ordering.
7702
7703 @item @emph{Standard}:
7704 Fortran 77 and later
7705
7706 @item @emph{Class}:
7707 Elemental function
7708
7709 @item @emph{Syntax}:
7710 @code{RESULT = LLE(STRING_A, STRING_B)}
7711
7712 @item @emph{Arguments}:
7713 @multitable @columnfractions .15 .70
7714 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7715 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7716 @end multitable
7717
7718 @item @emph{Return value}:
7719 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7720 otherwise, based on the ASCII ordering.
7721
7722 @item @emph{Specific names}:
7723 @multitable @columnfractions .20 .20 .20 .25
7724 @item Name                           @tab Argument          @tab Return type       @tab Standard
7725 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7726 @end multitable
7727
7728 @item @emph{See also}:
7729 @ref{LGE}, @ref{LGT}, @ref{LLT}
7730 @end table
7731
7732
7733
7734 @node LLT
7735 @section @code{LLT} --- Lexical less than
7736 @fnindex LLT
7737 @cindex lexical comparison of strings
7738 @cindex string, comparison
7739
7740 @table @asis
7741 @item @emph{Description}:
7742 Determines whether one string is lexically less than another string,
7743 where the two strings are interpreted as containing ASCII character
7744 codes.  If the String A and String B are not the same length, the
7745 shorter is compared as if spaces were appended to it to form a value
7746 that has the same length as the longer.
7747
7748 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7749 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7750 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7751 that the latter use the processor's character ordering (which is not
7752 ASCII on some targets), whereas the former always use the ASCII
7753 ordering.
7754
7755 @item @emph{Standard}:
7756 Fortran 77 and later
7757
7758 @item @emph{Class}:
7759 Elemental function
7760
7761 @item @emph{Syntax}:
7762 @code{RESULT = LLT(STRING_A, STRING_B)}
7763
7764 @item @emph{Arguments}:
7765 @multitable @columnfractions .15 .70
7766 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7767 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7768 @end multitable
7769
7770 @item @emph{Return value}:
7771 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7772 otherwise, based on the ASCII ordering.
7773
7774 @item @emph{Specific names}:
7775 @multitable @columnfractions .20 .20 .20 .25
7776 @item Name                           @tab Argument          @tab Return type       @tab Standard
7777 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7778 @end multitable
7779
7780 @item @emph{See also}:
7781 @ref{LGE}, @ref{LGT}, @ref{LLE}
7782 @end table
7783
7784
7785
7786 @node LNBLNK
7787 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7788 @fnindex LNBLNK
7789 @cindex string, find non-blank character
7790
7791 @table @asis
7792 @item @emph{Description}:
7793 Returns the length of a character string, ignoring any trailing blanks.
7794 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7795 included for backwards compatibility.
7796
7797 @item @emph{Standard}:
7798 GNU extension
7799
7800 @item @emph{Class}:
7801 Elemental function
7802
7803 @item @emph{Syntax}:
7804 @code{RESULT = LNBLNK(STRING)}
7805
7806 @item @emph{Arguments}:
7807 @multitable @columnfractions .15 .70
7808 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7809 with @code{INTENT(IN)}
7810 @end multitable
7811
7812 @item @emph{Return value}:
7813 The return value is of @code{INTEGER(kind=4)} type.
7814
7815 @item @emph{See also}:
7816 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7817 @end table
7818
7819
7820
7821 @node LOC
7822 @section @code{LOC} --- Returns the address of a variable
7823 @fnindex LOC
7824 @cindex location of a variable in memory
7825
7826 @table @asis
7827 @item @emph{Description}:
7828 @code{LOC(X)} returns the address of @var{X} as an integer.
7829
7830 @item @emph{Standard}:
7831 GNU extension
7832
7833 @item @emph{Class}:
7834 Inquiry function
7835
7836 @item @emph{Syntax}:
7837 @code{RESULT = LOC(X)}
7838
7839 @item @emph{Arguments}:
7840 @multitable @columnfractions .15 .70
7841 @item @var{X} @tab Variable of any type.
7842 @end multitable
7843
7844 @item @emph{Return value}:
7845 The return value is of type @code{INTEGER}, with a @code{KIND}
7846 corresponding to the size (in bytes) of a memory address on the target
7847 machine.
7848
7849 @item @emph{Example}:
7850 @smallexample
7851 program test_loc
7852   integer :: i
7853   real :: r
7854   i = loc(r)
7855   print *, i
7856 end program test_loc
7857 @end smallexample
7858 @end table
7859
7860
7861
7862 @node LOG
7863 @section @code{LOG} --- Natural logarithm function
7864 @fnindex LOG
7865 @fnindex ALOG
7866 @fnindex DLOG
7867 @fnindex CLOG
7868 @fnindex ZLOG
7869 @fnindex CDLOG
7870 @cindex exponential function, inverse
7871 @cindex logarithm function
7872 @cindex natural logarithm function
7873
7874 @table @asis
7875 @item @emph{Description}:
7876 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7877 logarithm to the base @math{e}.
7878
7879 @item @emph{Standard}:
7880 Fortran 77 and later
7881
7882 @item @emph{Class}:
7883 Elemental function
7884
7885 @item @emph{Syntax}:
7886 @code{RESULT = LOG(X)}
7887
7888 @item @emph{Arguments}:
7889 @multitable @columnfractions .15 .70
7890 @item @var{X} @tab The type shall be @code{REAL} or
7891 @code{COMPLEX}.
7892 @end multitable
7893
7894 @item @emph{Return value}:
7895 The return value is of type @code{REAL} or @code{COMPLEX}.
7896 The kind type parameter is the same as @var{X}.
7897 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7898 @math{-\pi \leq \omega \leq \pi}.
7899
7900 @item @emph{Example}:
7901 @smallexample
7902 program test_log
7903   real(8) :: x = 2.7182818284590451_8
7904   complex :: z = (1.0, 2.0)
7905   x = log(x)    ! will yield (approximately) 1
7906   z = log(z)
7907 end program test_log
7908 @end smallexample
7909
7910 @item @emph{Specific names}:
7911 @multitable @columnfractions .20 .20 .20 .25
7912 @item Name            @tab Argument          @tab Return type       @tab Standard
7913 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
7914 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
7915 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
7916 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7917 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7918 @end multitable
7919 @end table
7920
7921
7922
7923 @node LOG10
7924 @section @code{LOG10} --- Base 10 logarithm function
7925 @fnindex LOG10
7926 @fnindex ALOG10
7927 @fnindex DLOG10
7928 @cindex exponential function, inverse
7929 @cindex logarithm function with base 10
7930 @cindex base 10 logarithm function
7931
7932 @table @asis
7933 @item @emph{Description}:
7934 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7935
7936 @item @emph{Standard}:
7937 Fortran 77 and later
7938
7939 @item @emph{Class}:
7940 Elemental function
7941
7942 @item @emph{Syntax}:
7943 @code{RESULT = LOG10(X)}
7944
7945 @item @emph{Arguments}:
7946 @multitable @columnfractions .15 .70
7947 @item @var{X} @tab The type shall be @code{REAL}.
7948 @end multitable
7949
7950 @item @emph{Return value}:
7951 The return value is of type @code{REAL} or @code{COMPLEX}.
7952 The kind type parameter is the same as @var{X}.
7953
7954 @item @emph{Example}:
7955 @smallexample
7956 program test_log10
7957   real(8) :: x = 10.0_8
7958   x = log10(x)
7959 end program test_log10
7960 @end smallexample
7961
7962 @item @emph{Specific names}:
7963 @multitable @columnfractions .20 .20 .20 .25
7964 @item Name            @tab Argument          @tab Return type       @tab Standard
7965 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
7966 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
7967 @end multitable
7968 @end table
7969
7970
7971
7972 @node LOG_GAMMA
7973 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7974 @fnindex LOG_GAMMA
7975 @fnindex LGAMMA
7976 @fnindex ALGAMA
7977 @fnindex DLGAMA
7978 @cindex Gamma function, logarithm of
7979
7980 @table @asis
7981 @item @emph{Description}:
7982 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7983 of the Gamma (@math{\Gamma}) function.
7984
7985 @item @emph{Standard}:
7986 Fortran 2008 and later
7987
7988 @item @emph{Class}:
7989 Elemental function
7990
7991 @item @emph{Syntax}:
7992 @code{X = LOG_GAMMA(X)}
7993
7994 @item @emph{Arguments}:
7995 @multitable @columnfractions .15 .70
7996 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7997 nor a negative integer.
7998 @end multitable
7999
8000 @item @emph{Return value}:
8001 The return value is of type @code{REAL} of the same kind as @var{X}.
8002
8003 @item @emph{Example}:
8004 @smallexample
8005 program test_log_gamma
8006   real :: x = 1.0
8007   x = lgamma(x) ! returns 0.0
8008 end program test_log_gamma
8009 @end smallexample
8010
8011 @item @emph{Specific names}:
8012 @multitable @columnfractions .20 .20 .20 .25
8013 @item Name             @tab Argument         @tab Return type       @tab Standard
8014 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
8015 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
8016 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
8017 @end multitable
8018
8019 @item @emph{See also}:
8020 Gamma function: @ref{GAMMA}
8021
8022 @end table
8023
8024
8025
8026 @node LOGICAL
8027 @section @code{LOGICAL} --- Convert to logical type
8028 @fnindex LOGICAL
8029 @cindex conversion, to logical
8030
8031 @table @asis
8032 @item @emph{Description}:
8033 Converts one kind of @code{LOGICAL} variable to another.
8034
8035 @item @emph{Standard}:
8036 Fortran 95 and later
8037
8038 @item @emph{Class}:
8039 Elemental function
8040
8041 @item @emph{Syntax}:
8042 @code{RESULT = LOGICAL(L [, KIND])}
8043
8044 @item @emph{Arguments}:
8045 @multitable @columnfractions .15 .70
8046 @item @var{L}    @tab The type shall be @code{LOGICAL}.
8047 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8048 expression indicating the kind parameter of the result.
8049 @end multitable
8050
8051 @item @emph{Return value}:
8052 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8053 kind corresponding to @var{KIND}, or of the default logical kind if
8054 @var{KIND} is not given.
8055
8056 @item @emph{See also}:
8057 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8058 @end table
8059
8060
8061
8062 @node LONG
8063 @section @code{LONG} --- Convert to integer type
8064 @fnindex LONG
8065 @cindex conversion, to integer
8066
8067 @table @asis
8068 @item @emph{Description}:
8069 Convert to a @code{KIND=4} integer type, which is the same size as a C
8070 @code{long} integer.  This is equivalent to the standard @code{INT}
8071 intrinsic with an optional argument of @code{KIND=4}, and is only
8072 included for backwards compatibility.
8073
8074 @item @emph{Standard}:
8075 GNU extension
8076
8077 @item @emph{Class}:
8078 Elemental function
8079
8080 @item @emph{Syntax}:
8081 @code{RESULT = LONG(A)}
8082
8083 @item @emph{Arguments}:
8084 @multitable @columnfractions .15 .70
8085 @item @var{A}    @tab Shall be of type @code{INTEGER},
8086 @code{REAL}, or @code{COMPLEX}.
8087 @end multitable
8088
8089 @item @emph{Return value}:
8090 The return value is a @code{INTEGER(4)} variable.
8091
8092 @item @emph{See also}:
8093 @ref{INT}, @ref{INT2}, @ref{INT8}
8094 @end table
8095
8096
8097
8098 @node LSHIFT
8099 @section @code{LSHIFT} --- Left shift bits
8100 @fnindex LSHIFT
8101 @cindex bits, shift left
8102
8103 @table @asis
8104 @item @emph{Description}:
8105 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8106 bits shifted left by @var{SHIFT} places.  If the absolute value of
8107 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8108 Bits shifted out from the left end are lost; zeros are shifted in from
8109 the opposite end.
8110
8111 This function has been superseded by the @code{ISHFT} intrinsic, which
8112 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8113 which is standard in Fortran 2008 and later.
8114
8115 @item @emph{Standard}:
8116 GNU extension
8117
8118 @item @emph{Class}:
8119 Elemental function
8120
8121 @item @emph{Syntax}:
8122 @code{RESULT = LSHIFT(I, SHIFT)}
8123
8124 @item @emph{Arguments}:
8125 @multitable @columnfractions .15 .70
8126 @item @var{I} @tab The type shall be @code{INTEGER}.
8127 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8128 @end multitable
8129
8130 @item @emph{Return value}:
8131 The return value is of type @code{INTEGER} and of the same kind as
8132 @var{I}.
8133
8134 @item @emph{See also}:
8135 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8136 @ref{SHIFTR}
8137
8138 @end table
8139
8140
8141
8142 @node LSTAT
8143 @section @code{LSTAT} --- Get file status
8144 @fnindex LSTAT
8145 @cindex file system, file status
8146
8147 @table @asis
8148 @item @emph{Description}:
8149 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8150 symbolic link, then the link itself is statted, not the file that it
8151 refers to.
8152
8153 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8154
8155 This intrinsic is provided in both subroutine and function forms;
8156 however, only one form can be used in any given program unit.
8157
8158 @item @emph{Standard}:
8159 GNU extension
8160
8161 @item @emph{Class}:
8162 Subroutine, function
8163
8164 @item @emph{Syntax}:
8165 @multitable @columnfractions .80
8166 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8167 @item @code{STATUS = LSTAT(NAME, VALUES)}
8168 @end multitable
8169
8170 @item @emph{Arguments}:
8171 @multitable @columnfractions .15 .70
8172 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of the default
8173 kind, a valid path within the file system.
8174 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8175 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8176 Returns 0 on success and a system specific error code otherwise.
8177 @end multitable
8178
8179 @item @emph{Example}:
8180 See @ref{STAT} for an example.
8181
8182 @item @emph{See also}:
8183 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8184 @end table
8185
8186
8187
8188 @node LTIME
8189 @section @code{LTIME} --- Convert time to local time info
8190 @fnindex LTIME
8191 @cindex time, conversion to local time info
8192
8193 @table @asis
8194 @item @emph{Description}:
8195 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8196 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8197 to the local time zone using @code{localtime(3)}.
8198
8199 @item @emph{Standard}:
8200 GNU extension
8201
8202 @item @emph{Class}:
8203 Subroutine
8204
8205 @item @emph{Syntax}:
8206 @code{CALL LTIME(TIME, VALUES)}
8207
8208 @item @emph{Arguments}:
8209 @multitable @columnfractions .15 .70
8210 @item @var{TIME}  @tab An @code{INTEGER} scalar expression
8211 corresponding to a system time, with @code{INTENT(IN)}.
8212 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8213 with @code{INTENT(OUT)}.
8214 @end multitable
8215
8216 @item @emph{Return value}:
8217 The elements of @var{VALUES} are assigned as follows:
8218 @enumerate
8219 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8220 seconds
8221 @item Minutes after the hour, range 0--59
8222 @item Hours past midnight, range 0--23
8223 @item Day of month, range 0--31
8224 @item Number of months since January, range 0--12
8225 @item Years since 1900
8226 @item Number of days since Sunday, range 0--6
8227 @item Days since January 1
8228 @item Daylight savings indicator: positive if daylight savings is in
8229 effect, zero if not, and negative if the information is not available.
8230 @end enumerate
8231
8232 @item @emph{See also}:
8233 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8234
8235 @end table
8236
8237
8238
8239 @node MALLOC
8240 @section @code{MALLOC} --- Allocate dynamic memory
8241 @fnindex MALLOC
8242 @cindex pointer, cray
8243
8244 @table @asis
8245 @item @emph{Description}:
8246 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8247 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8248 is an extension intended to be used with Cray pointers, and is provided
8249 in GNU Fortran to allow the user to compile legacy code. For new code
8250 using Fortran 95 pointers, the memory allocation intrinsic is
8251 @code{ALLOCATE}.
8252
8253 @item @emph{Standard}:
8254 GNU extension
8255
8256 @item @emph{Class}:
8257 Function
8258
8259 @item @emph{Syntax}:
8260 @code{PTR = MALLOC(SIZE)}
8261
8262 @item @emph{Arguments}:
8263 @multitable @columnfractions .15 .70
8264 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8265 @end multitable
8266
8267 @item @emph{Return value}:
8268 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8269 variables of type @code{INTEGER(K)} have the same size as
8270 C pointers (@code{sizeof(void *)}).
8271
8272 @item @emph{Example}:
8273 The following example demonstrates the use of @code{MALLOC} and
8274 @code{FREE} with Cray pointers.
8275
8276 @smallexample
8277 program test_malloc
8278   implicit none
8279   integer i
8280   real*8 x(*), z
8281   pointer(ptr_x,x)
8282
8283   ptr_x = malloc(20*8)
8284   do i = 1, 20
8285     x(i) = sqrt(1.0d0 / i)
8286   end do
8287   z = 0
8288   do i = 1, 20
8289     z = z + x(i)
8290     print *, z
8291   end do
8292   call free(ptr_x)
8293 end program test_malloc
8294 @end smallexample
8295
8296 @item @emph{See also}:
8297 @ref{FREE}
8298 @end table
8299
8300
8301
8302 @node MASKL
8303 @section @code{MASKL} --- Left justified mask
8304 @fnindex MASKL
8305 @cindex mask, left justified
8306
8307 @table @asis
8308 @item @emph{Description}:
8309 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8310 remaining bits set to 0.
8311
8312 @item @emph{Standard}:
8313 Fortran 2008 and later
8314
8315 @item @emph{Class}:
8316 Elemental function
8317
8318 @item @emph{Syntax}:
8319 @code{RESULT = MASKL(I[, KIND])}
8320
8321 @item @emph{Arguments}:
8322 @multitable @columnfractions .15 .70
8323 @item @var{I} @tab Shall be of type @code{INTEGER}.
8324 @item @var{KIND} @tab Shall be a scalar constant expression of type
8325 @code{INTEGER}.
8326 @end multitable
8327
8328 @item @emph{Return value}:
8329 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8330 specifies the kind value of the return type; otherwise, it is of the
8331 default integer kind.
8332
8333 @item @emph{See also}:
8334 @ref{MASKR}
8335 @end table
8336
8337
8338
8339 @node MASKR
8340 @section @code{MASKR} --- Right justified mask
8341 @fnindex MASKR
8342 @cindex mask, right justified
8343
8344 @table @asis
8345 @item @emph{Description}:
8346 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8347 remaining bits set to 0.
8348
8349 @item @emph{Standard}:
8350 Fortran 2008 and later
8351
8352 @item @emph{Class}:
8353 Elemental function
8354
8355 @item @emph{Syntax}:
8356 @code{RESULT = MASKR(I[, KIND])}
8357
8358 @item @emph{Arguments}:
8359 @multitable @columnfractions .15 .70
8360 @item @var{I} @tab Shall be of type @code{INTEGER}.
8361 @item @var{KIND} @tab Shall be a scalar constant expression of type
8362 @code{INTEGER}.
8363 @end multitable
8364
8365 @item @emph{Return value}:
8366 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8367 specifies the kind value of the return type; otherwise, it is of the
8368 default integer kind.
8369
8370 @item @emph{See also}:
8371 @ref{MASKL}
8372 @end table
8373
8374
8375
8376 @node MATMUL
8377 @section @code{MATMUL} --- matrix multiplication
8378 @fnindex MATMUL
8379 @cindex matrix multiplication
8380 @cindex product, matrix
8381
8382 @table @asis
8383 @item @emph{Description}:
8384 Performs a matrix multiplication on numeric or logical arguments.
8385
8386 @item @emph{Standard}:
8387 Fortran 95 and later
8388
8389 @item @emph{Class}:
8390 Transformational function
8391
8392 @item @emph{Syntax}:
8393 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8394
8395 @item @emph{Arguments}:
8396 @multitable @columnfractions .15 .70
8397 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8398 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8399 one or two.
8400 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8401 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8402 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8403 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8404 equal to the last (or only) dimension of @var{MATRIX_A}.
8405 @end multitable
8406
8407 @item @emph{Return value}:
8408 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
8409 kind of the result follow the usual type and kind promotion rules, as
8410 for the @code{*} or @code{.AND.} operators.
8411
8412 @item @emph{See also}:
8413 @end table
8414
8415
8416
8417 @node MAX
8418 @section @code{MAX} --- Maximum value of an argument list
8419 @fnindex MAX
8420 @fnindex MAX0
8421 @fnindex AMAX0
8422 @fnindex MAX1
8423 @fnindex AMAX1
8424 @fnindex DMAX1
8425 @cindex maximum value
8426
8427 @table @asis
8428 @item @emph{Description}:
8429 Returns the argument with the largest (most positive) value.
8430
8431 @item @emph{Standard}:
8432 Fortran 77 and later
8433
8434 @item @emph{Class}:
8435 Elemental function
8436
8437 @item @emph{Syntax}:
8438 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8439
8440 @item @emph{Arguments}:
8441 @multitable @columnfractions .15 .70
8442 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8443 @code{REAL}.
8444 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8445 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8446 permitted.)
8447 @end multitable
8448
8449 @item @emph{Return value}:
8450 The return value corresponds to the maximum value among the arguments,
8451 and has the same type and kind as the first argument.
8452
8453 @item @emph{Specific names}:
8454 @multitable @columnfractions .20 .20 .20 .25
8455 @item Name             @tab Argument             @tab Return type         @tab Standard
8456 @item @code{MAX0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
8457 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8458 @item @code{MAX1(A1)}  @tab @code{REAL A1}       @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
8459 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1}    @tab @code{REAL(4)}      @tab Fortran 77 and later
8460 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1}    @tab @code{REAL(8)}      @tab Fortran 77 and later
8461 @end multitable
8462
8463 @item @emph{See also}:
8464 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8465
8466 @end table
8467
8468
8469
8470 @node MAXEXPONENT
8471 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8472 @fnindex MAXEXPONENT
8473 @cindex model representation, maximum exponent
8474
8475 @table @asis
8476 @item @emph{Description}:
8477 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8478 type of @code{X}.
8479
8480 @item @emph{Standard}:
8481 Fortran 95 and later
8482
8483 @item @emph{Class}:
8484 Inquiry function
8485
8486 @item @emph{Syntax}:
8487 @code{RESULT = MAXEXPONENT(X)}
8488
8489 @item @emph{Arguments}:
8490 @multitable @columnfractions .15 .70
8491 @item @var{X} @tab Shall be of type @code{REAL}.
8492 @end multitable
8493
8494 @item @emph{Return value}:
8495 The return value is of type @code{INTEGER} and of the default integer
8496 kind.
8497
8498 @item @emph{Example}:
8499 @smallexample
8500 program exponents
8501   real(kind=4) :: x
8502   real(kind=8) :: y
8503
8504   print *, minexponent(x), maxexponent(x)
8505   print *, minexponent(y), maxexponent(y)
8506 end program exponents
8507 @end smallexample
8508 @end table
8509
8510
8511
8512 @node MAXLOC
8513 @section @code{MAXLOC} --- Location of the maximum value within an array
8514 @fnindex MAXLOC
8515 @cindex array, location of maximum element
8516
8517 @table @asis
8518 @item @emph{Description}:
8519 Determines the location of the element in the array with the maximum
8520 value, or, if the @var{DIM} argument is supplied, determines the
8521 locations of the maximum element along each row of the array in the
8522 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8523 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8524 element in the array has the maximum value, the location returned is
8525 that of the first such element in array element order.  If the array has
8526 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8527 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8528 and all of the elements of @var{MASK} along a given row are zero, the
8529 result value for that row is zero.
8530
8531 @item @emph{Standard}:
8532 Fortran 95 and later
8533
8534 @item @emph{Class}:
8535 Transformational function
8536
8537 @item @emph{Syntax}:
8538 @multitable @columnfractions .80
8539 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8540 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8541 @end multitable
8542
8543 @item @emph{Arguments}:
8544 @multitable @columnfractions .15 .70
8545 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8546 @code{REAL}.
8547 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8548 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8549 inclusive.  It may not be an optional dummy argument.
8550 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8551 and conformable with @var{ARRAY}.
8552 @end multitable
8553
8554 @item @emph{Return value}:
8555 If @var{DIM} is absent, the result is a rank-one array with a length
8556 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8557 is an array with a rank one less than the rank of @var{ARRAY}, and a
8558 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8559 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8560 of one, the result is a scalar.  In all cases, the result is of default
8561 @code{INTEGER} type.
8562
8563 @item @emph{See also}:
8564 @ref{MAX}, @ref{MAXVAL}
8565
8566 @end table
8567
8568
8569
8570 @node MAXVAL
8571 @section @code{MAXVAL} --- Maximum value of an array
8572 @fnindex MAXVAL
8573 @cindex array, maximum value
8574 @cindex maximum value
8575
8576 @table @asis
8577 @item @emph{Description}:
8578 Determines the maximum value of the elements in an array value, or, if
8579 the @var{DIM} argument is supplied, determines the maximum value along
8580 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8581 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8582 considered.  If the array has zero size, or all of the elements of
8583 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8584 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8585 type.
8586
8587 @item @emph{Standard}:
8588 Fortran 95 and later
8589
8590 @item @emph{Class}:
8591 Transformational function
8592
8593 @item @emph{Syntax}:
8594 @multitable @columnfractions .80
8595 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8596 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8597 @end multitable
8598
8599 @item @emph{Arguments}:
8600 @multitable @columnfractions .15 .70
8601 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8602 @code{REAL}.
8603 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8604 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8605 inclusive.  It may not be an optional dummy argument.
8606 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8607 and conformable with @var{ARRAY}.
8608 @end multitable
8609
8610 @item @emph{Return value}:
8611 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8612 is a scalar.  If @var{DIM} is present, the result is an array with a
8613 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8614 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8615 cases, the result is of the same type and kind as @var{ARRAY}.
8616
8617 @item @emph{See also}:
8618 @ref{MAX}, @ref{MAXLOC}
8619 @end table
8620
8621
8622
8623 @node MCLOCK
8624 @section @code{MCLOCK} --- Time function
8625 @fnindex MCLOCK
8626 @cindex time, clock ticks
8627 @cindex clock ticks
8628
8629 @table @asis
8630 @item @emph{Description}:
8631 Returns the number of clock ticks since the start of the process, based
8632 on the UNIX function @code{clock(3)}.
8633
8634 This intrinsic is not fully portable, such as to systems with 32-bit
8635 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8636 the values returned by this intrinsic might be, or become, negative, or
8637 numerically less than previous values, during a single run of the
8638 compiled program.
8639
8640 @item @emph{Standard}:
8641 GNU extension
8642
8643 @item @emph{Class}:
8644 Function
8645
8646 @item @emph{Syntax}:
8647 @code{RESULT = MCLOCK()}
8648
8649 @item @emph{Return value}:
8650 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8651 number of clock ticks since the start of the process, or @code{-1} if
8652 the system does not support @code{clock(3)}.
8653
8654 @item @emph{See also}:
8655 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8656
8657 @end table
8658
8659
8660
8661 @node MCLOCK8
8662 @section @code{MCLOCK8} --- Time function (64-bit)
8663 @fnindex MCLOCK8
8664 @cindex time, clock ticks
8665 @cindex clock ticks
8666
8667 @table @asis
8668 @item @emph{Description}:
8669 Returns the number of clock ticks since the start of the process, based
8670 on the UNIX function @code{clock(3)}.
8671
8672 @emph{Warning:} this intrinsic does not increase the range of the timing
8673 values over that returned by @code{clock(3)}. On a system with a 32-bit
8674 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8675 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8676 overflows of the 32-bit value can still occur. Therefore, the values
8677 returned by this intrinsic might be or become negative or numerically
8678 less than previous values during a single run of the compiled program.
8679
8680 @item @emph{Standard}:
8681 GNU extension
8682
8683 @item @emph{Class}:
8684 Function
8685
8686 @item @emph{Syntax}:
8687 @code{RESULT = MCLOCK8()}
8688
8689 @item @emph{Return value}:
8690 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8691 number of clock ticks since the start of the process, or @code{-1} if
8692 the system does not support @code{clock(3)}.
8693
8694 @item @emph{See also}:
8695 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8696
8697 @end table
8698
8699
8700
8701 @node MERGE
8702 @section @code{MERGE} --- Merge variables
8703 @fnindex MERGE
8704 @cindex array, merge arrays
8705 @cindex array, combine arrays
8706
8707 @table @asis
8708 @item @emph{Description}:
8709 Select values from two arrays according to a logical mask.  The result
8710 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8711 @var{FSOURCE} if it is @code{.FALSE.}.
8712
8713 @item @emph{Standard}:
8714 Fortran 95 and later
8715
8716 @item @emph{Class}:
8717 Elemental function
8718
8719 @item @emph{Syntax}:
8720 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8721
8722 @item @emph{Arguments}:
8723 @multitable @columnfractions .15 .70
8724 @item @var{TSOURCE} @tab May be of any type.
8725 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8726 as @var{TSOURCE}.
8727 @item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
8728 @end multitable
8729
8730 @item @emph{Return value}:
8731 The result is of the same type and type parameters as @var{TSOURCE}.
8732
8733 @end table
8734
8735
8736
8737 @node MERGE_BITS
8738 @section @code{MERGE_BITS} --- Merge of bits under mask
8739 @fnindex MERGE_BITS
8740 @cindex bits, merge
8741
8742 @table @asis
8743 @item @emph{Description}:
8744 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8745 as determined by the mask.  The i-th bit of the result is equal to the
8746 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8747 the i-th bit of @var{J} otherwise.
8748
8749 @item @emph{Standard}:
8750 Fortran 2008 and later
8751
8752 @item @emph{Class}:
8753 Elemental function
8754
8755 @item @emph{Syntax}:
8756 @code{RESULT = MERGE_BITS(I, J, MASK)}
8757
8758 @item @emph{Arguments}:
8759 @multitable @columnfractions .15 .70
8760 @item @var{I}    @tab Shall be of type @code{INTEGER}.
8761 @item @var{J}    @tab Shall be of type @code{INTEGER} and of the same
8762 kind as @var{I}.
8763 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8764 kind as @var{I}.
8765 @end multitable
8766
8767 @item @emph{Return value}:
8768 The result is of the same type and kind as @var{I}.
8769
8770 @end table
8771
8772
8773
8774 @node MIN
8775 @section @code{MIN} --- Minimum value of an argument list
8776 @fnindex MIN
8777 @fnindex MIN0
8778 @fnindex AMIN0
8779 @fnindex MIN1
8780 @fnindex AMIN1
8781 @fnindex DMIN1
8782 @cindex minimum value
8783
8784 @table @asis
8785 @item @emph{Description}:
8786 Returns the argument with the smallest (most negative) value.
8787
8788 @item @emph{Standard}:
8789 Fortran 77 and later
8790
8791 @item @emph{Class}:
8792 Elemental function
8793
8794 @item @emph{Syntax}:
8795 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8796
8797 @item @emph{Arguments}:
8798 @multitable @columnfractions .15 .70
8799 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8800 @code{REAL}.
8801 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8802 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8803 permitted.)
8804 @end multitable
8805
8806 @item @emph{Return value}:
8807 The return value corresponds to the maximum value among the arguments,
8808 and has the same type and kind as the first argument.
8809
8810 @item @emph{Specific names}:
8811 @multitable @columnfractions .20 .20 .20 .25
8812 @item Name              @tab Argument             @tab Return type        @tab Standard
8813 @item @code{MIN0(A1)}   @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8814 @item @code{AMIN0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{REAL(4)}     @tab Fortran 77 and later
8815 @item @code{MIN1(A1)}   @tab @code{REAL A1}       @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8816 @item @code{AMIN1(A1)}  @tab @code{REAL(4) A1}    @tab @code{REAL(4)}     @tab Fortran 77 and later
8817 @item @code{DMIN1(A1)}  @tab @code{REAL(8) A1}    @tab @code{REAL(8)}     @tab Fortran 77 and later
8818 @end multitable
8819
8820 @item @emph{See also}:
8821 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8822 @end table
8823
8824
8825
8826 @node MINEXPONENT
8827 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8828 @fnindex MINEXPONENT
8829 @cindex model representation, minimum exponent
8830
8831 @table @asis
8832 @item @emph{Description}:
8833 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8834 type of @code{X}.
8835
8836 @item @emph{Standard}:
8837 Fortran 95 and later
8838
8839 @item @emph{Class}:
8840 Inquiry function
8841
8842 @item @emph{Syntax}:
8843 @code{RESULT = MINEXPONENT(X)}
8844
8845 @item @emph{Arguments}:
8846 @multitable @columnfractions .15 .70
8847 @item @var{X} @tab Shall be of type @code{REAL}.
8848 @end multitable
8849
8850 @item @emph{Return value}:
8851 The return value is of type @code{INTEGER} and of the default integer
8852 kind.
8853
8854 @item @emph{Example}:
8855 See @code{MAXEXPONENT} for an example.
8856 @end table
8857
8858
8859
8860 @node MINLOC
8861 @section @code{MINLOC} --- Location of the minimum value within an array
8862 @fnindex MINLOC
8863 @cindex array, location of minimum element
8864
8865 @table @asis
8866 @item @emph{Description}:
8867 Determines the location of the element in the array with the minimum
8868 value, or, if the @var{DIM} argument is supplied, determines the
8869 locations of the minimum element along each row of the array in the
8870 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8871 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8872 element in the array has the minimum value, the location returned is
8873 that of the first such element in array element order.  If the array has
8874 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8875 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8876 and all of the elements of @var{MASK} along a given row are zero, the
8877 result value for that row is zero.
8878
8879 @item @emph{Standard}:
8880 Fortran 95 and later
8881
8882 @item @emph{Class}:
8883 Transformational function
8884
8885 @item @emph{Syntax}:
8886 @multitable @columnfractions .80
8887 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8888 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8889 @end multitable
8890
8891 @item @emph{Arguments}:
8892 @multitable @columnfractions .15 .70
8893 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8894 @code{REAL}.
8895 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8896 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8897 inclusive.  It may not be an optional dummy argument.
8898 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8899 and conformable with @var{ARRAY}.
8900 @end multitable
8901
8902 @item @emph{Return value}:
8903 If @var{DIM} is absent, the result is a rank-one array with a length
8904 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8905 is an array with a rank one less than the rank of @var{ARRAY}, and a
8906 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8907 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8908 of one, the result is a scalar.  In all cases, the result is of default
8909 @code{INTEGER} type.
8910
8911 @item @emph{See also}:
8912 @ref{MIN}, @ref{MINVAL}
8913
8914 @end table
8915
8916
8917
8918 @node MINVAL
8919 @section @code{MINVAL} --- Minimum value of an array
8920 @fnindex MINVAL
8921 @cindex array, minimum value
8922 @cindex minimum value
8923
8924 @table @asis
8925 @item @emph{Description}:
8926 Determines the minimum value of the elements in an array value, or, if
8927 the @var{DIM} argument is supplied, determines the minimum value along
8928 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8929 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8930 considered.  If the array has zero size, or all of the elements of
8931 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8932 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8933 @var{ARRAY} is of character type.
8934
8935 @item @emph{Standard}:
8936 Fortran 95 and later
8937
8938 @item @emph{Class}:
8939 Transformational function
8940
8941 @item @emph{Syntax}:
8942 @multitable @columnfractions .80
8943 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8944 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8945 @end multitable
8946
8947 @item @emph{Arguments}:
8948 @multitable @columnfractions .15 .70
8949 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8950 @code{REAL}.
8951 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8952 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8953 inclusive.  It may not be an optional dummy argument.
8954 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8955 and conformable with @var{ARRAY}.
8956 @end multitable
8957
8958 @item @emph{Return value}:
8959 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8960 is a scalar.  If @var{DIM} is present, the result is an array with a
8961 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8962 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8963 cases, the result is of the same type and kind as @var{ARRAY}.
8964
8965 @item @emph{See also}:
8966 @ref{MIN}, @ref{MINLOC}
8967
8968 @end table
8969
8970
8971
8972 @node MOD
8973 @section @code{MOD} --- Remainder function
8974 @fnindex MOD
8975 @fnindex AMOD
8976 @fnindex DMOD
8977 @cindex remainder
8978 @cindex division, remainder
8979
8980 @table @asis
8981 @item @emph{Description}:
8982 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8983 calculated as @code{A - (INT(A/P) * P)}.
8984
8985 @item @emph{Standard}:
8986 Fortran 77 and later
8987
8988 @item @emph{Class}:
8989 Elemental function
8990
8991 @item @emph{Syntax}:
8992 @code{RESULT = MOD(A, P)}
8993
8994 @item @emph{Arguments}:
8995 @multitable @columnfractions .15 .70
8996 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8997 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8998 equal to zero
8999 @end multitable
9000
9001 @item @emph{Return value}:
9002 The kind of the return value is the result of cross-promoting
9003 the kinds of the arguments.
9004
9005 @item @emph{Example}:
9006 @smallexample
9007 program test_mod
9008   print *, mod(17,3)
9009   print *, mod(17.5,5.5)
9010   print *, mod(17.5d0,5.5)
9011   print *, mod(17.5,5.5d0)
9012
9013   print *, mod(-17,3)
9014   print *, mod(-17.5,5.5)
9015   print *, mod(-17.5d0,5.5)
9016   print *, mod(-17.5,5.5d0)
9017
9018   print *, mod(17,-3)
9019   print *, mod(17.5,-5.5)
9020   print *, mod(17.5d0,-5.5)
9021   print *, mod(17.5,-5.5d0)
9022 end program test_mod
9023 @end smallexample
9024
9025 @item @emph{Specific names}:
9026 @multitable @columnfractions .20 .20 .20 .25
9027 @item Name             @tab Arguments          @tab Return type    @tab Standard
9028 @item @code{MOD(A,P)}  @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9029 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9030 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9031 @end multitable
9032 @end table
9033
9034
9035
9036 @node MODULO
9037 @section @code{MODULO} --- Modulo function
9038 @fnindex MODULO
9039 @cindex modulo
9040 @cindex division, modulo
9041
9042 @table @asis
9043 @item @emph{Description}:
9044 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9045
9046 @item @emph{Standard}:
9047 Fortran 95 and later
9048
9049 @item @emph{Class}:
9050 Elemental function
9051
9052 @item @emph{Syntax}:
9053 @code{RESULT = MODULO(A, P)}
9054
9055 @item @emph{Arguments}:
9056 @multitable @columnfractions .15 .70
9057 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9058 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9059 @end multitable
9060
9061 @item @emph{Return value}:
9062 The type and kind of the result are those of the arguments.
9063 @table @asis
9064 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9065 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9066 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9067 (exclusive).
9068 @item If @var{A} and @var{P} are of type @code{REAL}:
9069 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9070 @end table
9071 In all cases, if @var{P} is zero the result is processor-dependent.
9072
9073 @item @emph{Example}:
9074 @smallexample
9075 program test_modulo
9076   print *, modulo(17,3)
9077   print *, modulo(17.5,5.5)
9078
9079   print *, modulo(-17,3)
9080   print *, modulo(-17.5,5.5)
9081
9082   print *, modulo(17,-3)
9083   print *, modulo(17.5,-5.5)
9084 end program
9085 @end smallexample
9086
9087 @end table
9088
9089
9090
9091 @node MOVE_ALLOC
9092 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9093 @fnindex MOVE_ALLOC
9094 @cindex moving allocation
9095 @cindex allocation, moving
9096
9097 @table @asis
9098 @item @emph{Description}:
9099 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9100 @var{TO}.  @var{FROM} will become deallocated in the process.
9101
9102 @item @emph{Standard}:
9103 Fortran 2003 and later
9104
9105 @item @emph{Class}:
9106 Pure subroutine
9107
9108 @item @emph{Syntax}:
9109 @code{CALL MOVE_ALLOC(FROM, TO)}
9110
9111 @item @emph{Arguments}:
9112 @multitable @columnfractions .15 .70
9113 @item @var{FROM}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9114 of any type and kind.
9115 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9116 of the same type, kind and rank as @var{FROM}.
9117 @end multitable
9118
9119 @item @emph{Return value}:
9120 None
9121
9122 @item @emph{Example}:
9123 @smallexample
9124 program test_move_alloc
9125     integer, allocatable :: a(:), b(:)
9126
9127     allocate(a(3))
9128     a = [ 1, 2, 3 ]
9129     call move_alloc(a, b)
9130     print *, allocated(a), allocated(b)
9131     print *, b
9132 end program test_move_alloc
9133 @end smallexample
9134 @end table
9135
9136
9137
9138 @node MVBITS
9139 @section @code{MVBITS} --- Move bits from one integer to another
9140 @fnindex MVBITS
9141 @cindex bits, move
9142
9143 @table @asis
9144 @item @emph{Description}:
9145 Moves @var{LEN} bits from positions @var{FROMPOS} through
9146 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9147 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9148 affected by the movement of bits is unchanged. The values of
9149 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9150 @code{BIT_SIZE(FROM)}.
9151
9152 @item @emph{Standard}:
9153 Fortran 95 and later
9154
9155 @item @emph{Class}:
9156 Elemental subroutine
9157
9158 @item @emph{Syntax}:
9159 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9160
9161 @item @emph{Arguments}:
9162 @multitable @columnfractions .15 .70
9163 @item @var{FROM}    @tab The type shall be @code{INTEGER}.
9164 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9165 @item @var{LEN}     @tab The type shall be @code{INTEGER}.
9166 @item @var{TO}      @tab The type shall be @code{INTEGER}, of the
9167 same kind as @var{FROM}.
9168 @item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
9169 @end multitable
9170
9171 @item @emph{See also}:
9172 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9173 @end table
9174
9175
9176
9177 @node NEAREST
9178 @section @code{NEAREST} --- Nearest representable number
9179 @fnindex NEAREST
9180 @cindex real number, nearest different
9181 @cindex floating point, nearest different
9182
9183 @table @asis
9184 @item @emph{Description}:
9185 @code{NEAREST(X, S)} returns the processor-representable number nearest
9186 to @code{X} in the direction indicated by the sign of @code{S}.
9187
9188 @item @emph{Standard}:
9189 Fortran 95 and later
9190
9191 @item @emph{Class}:
9192 Elemental function
9193
9194 @item @emph{Syntax}:
9195 @code{RESULT = NEAREST(X, S)}
9196
9197 @item @emph{Arguments}:
9198 @multitable @columnfractions .15 .70
9199 @item @var{X} @tab Shall be of type @code{REAL}.
9200 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9201 not equal to zero.
9202 @end multitable
9203
9204 @item @emph{Return value}:
9205 The return value is of the same type as @code{X}. If @code{S} is
9206 positive, @code{NEAREST} returns the processor-representable number
9207 greater than @code{X} and nearest to it. If @code{S} is negative,
9208 @code{NEAREST} returns the processor-representable number smaller than
9209 @code{X} and nearest to it.
9210
9211 @item @emph{Example}:
9212 @smallexample
9213 program test_nearest
9214   real :: x, y
9215   x = nearest(42.0, 1.0)
9216   y = nearest(42.0, -1.0)
9217   write (*,"(3(G20.15))") x, y, x - y
9218 end program test_nearest
9219 @end smallexample
9220 @end table
9221
9222
9223
9224 @node NEW_LINE
9225 @section @code{NEW_LINE} --- New line character
9226 @fnindex NEW_LINE
9227 @cindex newline
9228 @cindex output, newline
9229
9230 @table @asis
9231 @item @emph{Description}:
9232 @code{NEW_LINE(C)} returns the new-line character.
9233
9234 @item @emph{Standard}:
9235 Fortran 2003 and later
9236
9237 @item @emph{Class}:
9238 Inquiry function
9239
9240 @item @emph{Syntax}:
9241 @code{RESULT = NEW_LINE(C)}
9242
9243 @item @emph{Arguments}:
9244 @multitable @columnfractions .15 .70
9245 @item @var{C}    @tab The argument shall be a scalar or array of the
9246 type @code{CHARACTER}.
9247 @end multitable
9248
9249 @item @emph{Return value}:
9250 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9251 the same kind as parameter @var{C}.
9252
9253 @item @emph{Example}:
9254 @smallexample
9255 program newline
9256   implicit none
9257   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9258 end program newline
9259 @end smallexample
9260 @end table
9261
9262
9263
9264 @node NINT
9265 @section @code{NINT} --- Nearest whole number
9266 @fnindex NINT
9267 @fnindex IDNINT
9268 @cindex rounding, nearest whole number
9269
9270 @table @asis
9271 @item @emph{Description}:
9272 @code{NINT(A)} rounds its argument to the nearest whole number.
9273
9274 @item @emph{Standard}:
9275 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9276
9277 @item @emph{Class}:
9278 Elemental function
9279
9280 @item @emph{Syntax}:
9281 @code{RESULT = NINT(A [, KIND])}
9282
9283 @item @emph{Arguments}:
9284 @multitable @columnfractions .15 .70
9285 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
9286 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9287 expression indicating the kind parameter of the result.
9288 @end multitable
9289
9290 @item @emph{Return value}:
9291 Returns @var{A} with the fractional portion of its magnitude eliminated by
9292 rounding to the nearest whole number and with its sign preserved,
9293 converted to an @code{INTEGER} of the default kind.
9294
9295 @item @emph{Example}:
9296 @smallexample
9297 program test_nint
9298   real(4) x4
9299   real(8) x8
9300   x4 = 1.234E0_4
9301   x8 = 4.321_8
9302   print *, nint(x4), idnint(x8)
9303 end program test_nint
9304 @end smallexample
9305
9306 @item @emph{Specific names}:
9307 @multitable @columnfractions .20 .20 .20 .25
9308 @item Name             @tab Argument           @tab Return Type     @tab Standard
9309 @item @code{NINT(A)}   @tab @code{REAL(4) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9310 @item @code{IDNINT(A)} @tab @code{REAL(8) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9311 @end multitable
9312
9313 @item @emph{See also}:
9314 @ref{CEILING}, @ref{FLOOR}
9315
9316 @end table
9317
9318
9319
9320 @node NORM2
9321 @section @code{NORM2} --- Euclidean vector norms
9322 @fnindex NORM2
9323 @cindex Euclidean vector norm
9324 @cindex L2 vector norm
9325 @cindex norm, Euclidean
9326
9327 @table @asis
9328 @item @emph{Description}:
9329 Calculates the Euclidean vector norm (@math{L_2} norm) of
9330 of @var{ARRAY} along dimension @var{DIM}.
9331
9332 @item @emph{Standard}:
9333 Fortran 2008 and later
9334
9335 @item @emph{Class}:
9336 Transformational function
9337
9338 @item @emph{Syntax}:
9339 @multitable @columnfractions .80
9340 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9341 @end multitable
9342
9343 @item @emph{Arguments}:
9344 @multitable @columnfractions .15 .70
9345 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9346 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9347 @code{INTEGER} with a value in the range from 1 to n, where n
9348 equals the rank of @var{ARRAY}.
9349 @end multitable
9350
9351 @item @emph{Return value}:
9352 The result is of the same type as @var{ARRAY}.
9353
9354 If @var{DIM} is absent, a scalar with the square root of the sum of all
9355 elements in @var{ARRAY} squared  is returned. Otherwise, an array of
9356 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9357 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9358 is returned.
9359
9360 @item @emph{Example}:
9361 @smallexample
9362 PROGRAM test_sum
9363   REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9364   print *, NORM2(x)  ! = sqrt(55.) ~ 7.416
9365 END PROGRAM
9366 @end smallexample
9367 @end table
9368
9369
9370
9371 @node NOT
9372 @section @code{NOT} --- Logical negation
9373 @fnindex NOT
9374 @cindex bits, negate
9375 @cindex bitwise logical not
9376 @cindex logical not, bitwise
9377
9378 @table @asis
9379 @item @emph{Description}:
9380 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9381
9382 @item @emph{Standard}:
9383 Fortran 95 and later
9384
9385 @item @emph{Class}:
9386 Elemental function
9387
9388 @item @emph{Syntax}:
9389 @code{RESULT = NOT(I)}
9390
9391 @item @emph{Arguments}:
9392 @multitable @columnfractions .15 .70
9393 @item @var{I} @tab The type shall be @code{INTEGER}.
9394 @end multitable
9395
9396 @item @emph{Return value}:
9397 The return type is @code{INTEGER}, of the same kind as the
9398 argument.
9399
9400 @item @emph{See also}:
9401 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9402
9403 @end table
9404
9405
9406
9407 @node NULL
9408 @section @code{NULL} --- Function that returns an disassociated pointer
9409 @fnindex NULL
9410 @cindex pointer, status
9411 @cindex pointer, disassociated
9412
9413 @table @asis
9414 @item @emph{Description}:
9415 Returns a disassociated pointer.
9416
9417 If @var{MOLD} is present, a disassociated pointer of the same type is
9418 returned, otherwise the type is determined by context.
9419
9420 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9421 includes cases where it is required.
9422
9423 @item @emph{Standard}:
9424 Fortran 95 and later
9425
9426 @item @emph{Class}:
9427 Transformational function
9428
9429 @item @emph{Syntax}:
9430 @code{PTR => NULL([MOLD])}
9431
9432 @item @emph{Arguments}:
9433 @multitable @columnfractions .15 .70
9434 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9435 status and of any type.
9436 @end multitable
9437
9438 @item @emph{Return value}:
9439 A disassociated pointer.
9440
9441 @item @emph{Example}:
9442 @smallexample
9443 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9444 @end smallexample
9445
9446 @item @emph{See also}:
9447 @ref{ASSOCIATED}
9448 @end table
9449
9450
9451
9452 @node NUM_IMAGES
9453 @section @code{NUM_IMAGES} --- Function that returns the number of images
9454 @fnindex NUM_IMAGES
9455 @cindex coarray, @code{NUM_IMAGES}
9456 @cindex images, number of
9457
9458 @table @asis
9459 @item @emph{Description}:
9460 Returns the number of images.
9461
9462 @item @emph{Standard}:
9463 Fortran 2008 and later
9464
9465 @item @emph{Class}:
9466 Transformational function
9467
9468 @item @emph{Syntax}:
9469 @code{RESULT = NUM_IMAGES()}
9470
9471 @item @emph{Arguments}: None.
9472
9473 @item @emph{Return value}:
9474 Scalar default-kind integer.
9475
9476 @item @emph{Example}:
9477 @smallexample
9478 INTEGER :: value[*]
9479 INTEGER :: i
9480 value = THIS_IMAGE()
9481 SYNC ALL
9482 IF (THIS_IMAGE() == 1) THEN
9483   DO i = 1, NUM_IMAGES()
9484     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9485   END DO
9486 END IF
9487 @end smallexample
9488
9489 @item @emph{See also}:
9490 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9491 @end table
9492
9493
9494
9495 @node OR
9496 @section @code{OR} --- Bitwise logical OR
9497 @fnindex OR
9498 @cindex bitwise logical or
9499 @cindex logical or, bitwise
9500
9501 @table @asis
9502 @item @emph{Description}:
9503 Bitwise logical @code{OR}.
9504
9505 This intrinsic routine is provided for backwards compatibility with
9506 GNU Fortran 77.  For integer arguments, programmers should consider
9507 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9508
9509 @item @emph{Standard}:
9510 GNU extension
9511
9512 @item @emph{Class}:
9513 Function
9514
9515 @item @emph{Syntax}:
9516 @code{RESULT = OR(I, J)}
9517
9518 @item @emph{Arguments}:
9519 @multitable @columnfractions .15 .70
9520 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9521 type or a scalar @code{LOGICAL} type.
9522 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9523 @end multitable
9524
9525 @item @emph{Return value}:
9526 The return type is either a scalar @code{INTEGER} or a scalar
9527 @code{LOGICAL}.  If the kind type parameters differ, then the
9528 smaller kind type is implicitly converted to larger kind, and the
9529 return has the larger kind.
9530
9531 @item @emph{Example}:
9532 @smallexample
9533 PROGRAM test_or
9534   LOGICAL :: T = .TRUE., F = .FALSE.
9535   INTEGER :: a, b
9536   DATA a / Z'F' /, b / Z'3' /
9537
9538   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9539   WRITE (*,*) OR(a, b)
9540 END PROGRAM
9541 @end smallexample
9542
9543 @item @emph{See also}:
9544 Fortran 95 elemental function: @ref{IOR}
9545 @end table
9546
9547
9548
9549 @node PACK
9550 @section @code{PACK} --- Pack an array into an array of rank one
9551 @fnindex PACK
9552 @cindex array, packing
9553 @cindex array, reduce dimension
9554 @cindex array, gather elements
9555
9556 @table @asis
9557 @item @emph{Description}:
9558 Stores the elements of @var{ARRAY} in an array of rank one.
9559
9560 The beginning of the resulting array is made up of elements whose @var{MASK}
9561 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9562 @var{VECTOR}.
9563
9564 @item @emph{Standard}:
9565 Fortran 95 and later
9566
9567 @item @emph{Class}:
9568 Transformational function
9569
9570 @item @emph{Syntax}:
9571 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9572
9573 @item @emph{Arguments}:
9574 @multitable @columnfractions .15 .70
9575 @item @var{ARRAY}  @tab Shall be an array of any type.
9576 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
9577 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9578 scalar.
9579 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9580 as @var{ARRAY} and of rank one. If present, the number of elements in
9581 @var{VECTOR} shall be equal to or greater than the number of true elements
9582 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9583 @var{VECTOR} shall be equal to or greater than the number of elements in
9584 @var{ARRAY}.
9585 @end multitable
9586
9587 @item @emph{Return value}:
9588 The result is an array of rank one and the same type as that of @var{ARRAY}.
9589 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9590 number of @code{TRUE} values in @var{MASK} otherwise.
9591
9592 @item @emph{Example}:
9593 Gathering nonzero elements from an array:
9594 @smallexample
9595 PROGRAM test_pack_1
9596   INTEGER :: m(6)
9597   m = (/ 1, 0, 0, 0, 5, 0 /)
9598   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
9599 END PROGRAM
9600 @end smallexample
9601
9602 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9603 @smallexample
9604 PROGRAM test_pack_2
9605   INTEGER :: m(4)
9606   m = (/ 1, 0, 0, 2 /)
9607   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
9608 END PROGRAM
9609 @end smallexample
9610
9611 @item @emph{See also}:
9612 @ref{UNPACK}
9613 @end table
9614
9615
9616
9617 @node PARITY
9618 @section @code{PARITY} --- Reduction with exclusive OR
9619 @fnindex PARITY
9620 @cindex Parity
9621 @cindex Reduction, XOR
9622 @cindex XOR reduction
9623
9624 @table @asis
9625 @item @emph{Description}:
9626 Calculates the parity, i.e. the reduction using @code{.XOR.},
9627 of @var{MASK} along dimension @var{DIM}.
9628
9629 @item @emph{Standard}:
9630 Fortran 2008 and later
9631
9632 @item @emph{Class}:
9633 Transformational function
9634
9635 @item @emph{Syntax}:
9636 @multitable @columnfractions .80
9637 @item @code{RESULT = PARITY(MASK[, DIM])}
9638 @end multitable
9639
9640 @item @emph{Arguments}:
9641 @multitable @columnfractions .15 .70
9642 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9643 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9644 @code{INTEGER} with a value in the range from 1 to n, where n
9645 equals the rank of @var{MASK}.
9646 @end multitable
9647
9648 @item @emph{Return value}:
9649 The result is of the same type as @var{MASK}.
9650
9651 If @var{DIM} is absent, a scalar with the parity of all elements in
9652 @var{MASK} is returned, i.e. true if an odd number of elements is
9653 @code{.true.} and false otherwise.  If @var{DIM} is present, an array
9654 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9655 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9656 dropped is returned.
9657
9658 @item @emph{Example}:
9659 @smallexample
9660 PROGRAM test_sum
9661   LOGICAL :: x(2) = [ .true., .false. ]
9662   print *, PARITY(x) ! prints "T" (true).
9663 END PROGRAM
9664 @end smallexample
9665 @end table
9666
9667
9668
9669 @node PERROR
9670 @section @code{PERROR} --- Print system error message
9671 @fnindex PERROR
9672 @cindex system, error handling
9673
9674 @table @asis
9675 @item @emph{Description}:
9676 Prints (on the C @code{stderr} stream) a newline-terminated error
9677 message corresponding to the last system error. This is prefixed by
9678 @var{STRING}, a colon and a space. See @code{perror(3)}.
9679
9680 @item @emph{Standard}:
9681 GNU extension
9682
9683 @item @emph{Class}:
9684 Subroutine
9685
9686 @item @emph{Syntax}:
9687 @code{CALL PERROR(STRING)}
9688
9689 @item @emph{Arguments}:
9690 @multitable @columnfractions .15 .70
9691 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9692 default kind.
9693 @end multitable
9694
9695 @item @emph{See also}:
9696 @ref{IERRNO}
9697 @end table
9698
9699
9700
9701 @node PRECISION
9702 @section @code{PRECISION} --- Decimal precision of a real kind
9703 @fnindex PRECISION
9704 @cindex model representation, precision
9705
9706 @table @asis
9707 @item @emph{Description}:
9708 @code{PRECISION(X)} returns the decimal precision in the model of the
9709 type of @code{X}.
9710
9711 @item @emph{Standard}:
9712 Fortran 95 and later
9713
9714 @item @emph{Class}:
9715 Inquiry function
9716
9717 @item @emph{Syntax}:
9718 @code{RESULT = PRECISION(X)}
9719
9720 @item @emph{Arguments}:
9721 @multitable @columnfractions .15 .70
9722 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9723 @end multitable
9724
9725 @item @emph{Return value}:
9726 The return value is of type @code{INTEGER} and of the default integer
9727 kind.
9728
9729 @item @emph{See also}:
9730 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9731
9732 @item @emph{Example}:
9733 @smallexample
9734 program prec_and_range
9735   real(kind=4) :: x(2)
9736   complex(kind=8) :: y
9737
9738   print *, precision(x), range(x)
9739   print *, precision(y), range(y)
9740 end program prec_and_range
9741 @end smallexample
9742 @end table
9743
9744
9745
9746 @node POPCNT
9747 @section @code{POPCNT} --- Number of bits set
9748 @fnindex POPCNT
9749 @cindex binary representation
9750 @cindex bits set
9751
9752 @table @asis
9753 @item @emph{Description}:
9754 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9755 representation of @code{I}.
9756
9757 @item @emph{Standard}:
9758 Fortran 2008 and later
9759
9760 @item @emph{Class}:
9761 Elemental function
9762
9763 @item @emph{Syntax}:
9764 @code{RESULT = POPCNT(I)}
9765
9766 @item @emph{Arguments}:
9767 @multitable @columnfractions .15 .70
9768 @item @var{I} @tab Shall be of type @code{INTEGER}.
9769 @end multitable
9770
9771 @item @emph{Return value}:
9772 The return value is of type @code{INTEGER} and of the default integer
9773 kind.
9774
9775 @item @emph{See also}:
9776 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9777
9778 @item @emph{Example}:
9779 @smallexample
9780 program test_population
9781   print *, popcnt(127),       poppar(127)
9782   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9783   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9784 end program test_population
9785 @end smallexample
9786 @end table
9787
9788
9789 @node POPPAR
9790 @section @code{POPPAR} --- Parity of the number of bits set
9791 @fnindex POPPAR
9792 @cindex binary representation
9793 @cindex parity
9794
9795 @table @asis
9796 @item @emph{Description}:
9797 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9798 of the number of bits set ('1' bits) in the binary representation of
9799 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9800 and 1 for an odd number of '1' bits.
9801
9802 @item @emph{Standard}:
9803 Fortran 2008 and later
9804
9805 @item @emph{Class}:
9806 Elemental function
9807
9808 @item @emph{Syntax}:
9809 @code{RESULT = POPPAR(I)}
9810
9811 @item @emph{Arguments}:
9812 @multitable @columnfractions .15 .70
9813 @item @var{I} @tab Shall be of type @code{INTEGER}.
9814 @end multitable
9815
9816 @item @emph{Return value}:
9817 The return value is of type @code{INTEGER} and of the default integer
9818 kind.
9819
9820 @item @emph{See also}:
9821 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9822
9823 @item @emph{Example}:
9824 @smallexample
9825 program test_population
9826   print *, popcnt(127),       poppar(127)
9827   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9828   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9829 end program test_population
9830 @end smallexample
9831 @end table
9832
9833
9834
9835 @node PRESENT
9836 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9837 @fnindex PRESENT
9838
9839 @table @asis
9840 @item @emph{Description}:
9841 Determines whether an optional dummy argument is present.
9842
9843 @item @emph{Standard}:
9844 Fortran 95 and later
9845
9846 @item @emph{Class}:
9847 Inquiry function
9848
9849 @item @emph{Syntax}:
9850 @code{RESULT = PRESENT(A)}
9851
9852 @item @emph{Arguments}:
9853 @multitable @columnfractions .15 .70
9854 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9855 value, or a dummy procedure. It shall be the name of an optional dummy argument
9856 accessible within the current subroutine or function.
9857 @end multitable
9858
9859 @item @emph{Return value}:
9860 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9861 @code{FALSE} otherwise.
9862
9863 @item @emph{Example}:
9864 @smallexample
9865 PROGRAM test_present
9866   WRITE(*,*) f(), f(42)      ! "F T"
9867 CONTAINS
9868   LOGICAL FUNCTION f(x)
9869     INTEGER, INTENT(IN), OPTIONAL :: x
9870     f = PRESENT(x)
9871   END FUNCTION
9872 END PROGRAM
9873 @end smallexample
9874 @end table
9875
9876
9877
9878 @node PRODUCT
9879 @section @code{PRODUCT} --- Product of array elements
9880 @fnindex PRODUCT
9881 @cindex array, product
9882 @cindex array, multiply elements
9883 @cindex array, conditionally multiply elements
9884 @cindex multiply array elements
9885
9886 @table @asis
9887 @item @emph{Description}:
9888 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9889 the corresponding element in @var{MASK} is @code{TRUE}.
9890
9891 @item @emph{Standard}:
9892 Fortran 95 and later
9893
9894 @item @emph{Class}:
9895 Transformational function
9896
9897 @item @emph{Syntax}:
9898 @multitable @columnfractions .80
9899 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9900 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9901 @end multitable
9902
9903 @item @emph{Arguments}:
9904 @multitable @columnfractions .15 .70
9905 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9906 @code{REAL} or @code{COMPLEX}.
9907 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9908 @code{INTEGER} with a value in the range from 1 to n, where n
9909 equals the rank of @var{ARRAY}.
9910 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
9911 and either be a scalar or an array of the same shape as @var{ARRAY}.
9912 @end multitable
9913
9914 @item @emph{Return value}:
9915 The result is of the same type as @var{ARRAY}.
9916
9917 If @var{DIM} is absent, a scalar with the product of all elements in
9918 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9919 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9920 dimension @var{DIM} dropped is returned.
9921
9922
9923 @item @emph{Example}:
9924 @smallexample
9925 PROGRAM test_product
9926   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9927   print *, PRODUCT(x)                    ! all elements, product = 120
9928   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9929 END PROGRAM
9930 @end smallexample
9931
9932 @item @emph{See also}:
9933 @ref{SUM}
9934 @end table
9935
9936
9937
9938 @node RADIX
9939 @section @code{RADIX} --- Base of a model number
9940 @fnindex RADIX
9941 @cindex model representation, base
9942 @cindex model representation, radix
9943
9944 @table @asis
9945 @item @emph{Description}:
9946 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9947
9948 @item @emph{Standard}:
9949 Fortran 95 and later
9950
9951 @item @emph{Class}:
9952 Inquiry function
9953
9954 @item @emph{Syntax}:
9955 @code{RESULT = RADIX(X)}
9956
9957 @item @emph{Arguments}:
9958 @multitable @columnfractions .15 .70
9959 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9960 @end multitable
9961
9962 @item @emph{Return value}:
9963 The return value is a scalar of type @code{INTEGER} and of the default
9964 integer kind.
9965
9966 @item @emph{See also}:
9967 @ref{SELECTED_REAL_KIND}
9968
9969 @item @emph{Example}:
9970 @smallexample
9971 program test_radix
9972   print *, "The radix for the default integer kind is", radix(0)
9973   print *, "The radix for the default real kind is", radix(0.0)
9974 end program test_radix
9975 @end smallexample
9976
9977 @end table
9978
9979
9980
9981 @node RAN
9982 @section @code{RAN} --- Real pseudo-random number
9983 @fnindex RAN
9984 @cindex random number generation
9985
9986 @table @asis
9987 @item @emph{Description}:
9988 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9989 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
9990 documentation.
9991
9992 @item @emph{Standard}:
9993 GNU extension
9994
9995 @item @emph{Class}:
9996 Function
9997
9998 @item @emph{See also}:
9999 @ref{RAND}, @ref{RANDOM_NUMBER}
10000 @end table
10001
10002
10003
10004 @node RAND
10005 @section @code{RAND} --- Real pseudo-random number
10006 @fnindex RAND
10007 @cindex random number generation
10008
10009 @table @asis
10010 @item @emph{Description}:
10011 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10012 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10013 in the current sequence is returned; if @var{FLAG} is 1, the generator
10014 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10015 it is used as a new seed with @code{SRAND}.
10016
10017 This intrinsic routine is provided for backwards compatibility with
10018 GNU Fortran 77. It implements a simple modulo generator as provided
10019 by @command{g77}. For new code, one should consider the use of
10020 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10021
10022 @item @emph{Standard}:
10023 GNU extension
10024
10025 @item @emph{Class}:
10026 Function
10027
10028 @item @emph{Syntax}:
10029 @code{RESULT = RAND(I)}
10030
10031 @item @emph{Arguments}:
10032 @multitable @columnfractions .15 .70
10033 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10034 @end multitable
10035
10036 @item @emph{Return value}:
10037 The return value is of @code{REAL} type and the default kind.
10038
10039 @item @emph{Example}:
10040 @smallexample
10041 program test_rand
10042   integer,parameter :: seed = 86456
10043
10044   call srand(seed)
10045   print *, rand(), rand(), rand(), rand()
10046   print *, rand(seed), rand(), rand(), rand()
10047 end program test_rand
10048 @end smallexample
10049
10050 @item @emph{See also}:
10051 @ref{SRAND}, @ref{RANDOM_NUMBER}
10052
10053 @end table
10054
10055
10056
10057 @node RANDOM_NUMBER
10058 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10059 @fnindex RANDOM_NUMBER
10060 @cindex random number generation
10061
10062 @table @asis
10063 @item @emph{Description}:
10064 Returns a single pseudorandom number or an array of pseudorandom numbers
10065 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10066
10067 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10068 Stupid) random number generator (RNG). This RNG combines:
10069 @enumerate
10070 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10071 with a period of @math{2^{32}},
10072 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10073 @item  Two 16-bit multiply-with-carry generators with a period of
10074 @math{597273182964842497 > 2^{59}}.
10075 @end enumerate
10076 The overall period exceeds @math{2^{123}}.
10077
10078 Please note, this RNG is thread safe if used within OpenMP directives,
10079 i.e., its state will be consistent while called from multiple threads.
10080 However, the KISS generator does not create random numbers in parallel
10081 from multiple sources, but in sequence from a single source. If an
10082 OpenMP-enabled application heavily relies on random numbers, one should
10083 consider employing a dedicated parallel random number generator instead.
10084
10085 @item @emph{Standard}:
10086 Fortran 95 and later
10087
10088 @item @emph{Class}:
10089 Subroutine
10090
10091 @item @emph{Syntax}:
10092 @code{RANDOM_NUMBER(HARVEST)}
10093
10094 @item @emph{Arguments}:
10095 @multitable @columnfractions .15 .70
10096 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10097 @end multitable
10098
10099 @item @emph{Example}:
10100 @smallexample
10101 program test_random_number
10102   REAL :: r(5,5)
10103   CALL init_random_seed()         ! see example of RANDOM_SEED
10104   CALL RANDOM_NUMBER(r)
10105 end program
10106 @end smallexample
10107
10108 @item @emph{See also}:
10109 @ref{RANDOM_SEED}
10110 @end table
10111
10112
10113
10114 @node RANDOM_SEED
10115 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10116 @fnindex RANDOM_SEED
10117 @cindex random number generation, seeding
10118 @cindex seeding a random number generator
10119
10120 @table @asis
10121 @item @emph{Description}:
10122 Restarts or queries the state of the pseudorandom number generator used by
10123 @code{RANDOM_NUMBER}.
10124
10125 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10126 a default state. The example below shows how to initialize the random
10127 seed based on the system's time.
10128
10129 @item @emph{Standard}:
10130 Fortran 95 and later
10131
10132 @item @emph{Class}:
10133 Subroutine
10134
10135 @item @emph{Syntax}:
10136 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10137
10138 @item @emph{Arguments}:
10139 @multitable @columnfractions .15 .70
10140 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10141 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10142 of the arrays used with the @var{PUT} and @var{GET} arguments.
10143 @item @var{PUT}  @tab (Optional) Shall be an array of type default
10144 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10145 the array must be larger than or equal to the number returned by the
10146 @var{SIZE} argument.
10147 @item @var{GET}  @tab (Optional) Shall be an array of type default
10148 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10149 of the array must be larger than or equal to the number returned by
10150 the @var{SIZE} argument.
10151 @end multitable
10152
10153 @item @emph{Example}:
10154 @smallexample
10155 SUBROUTINE init_random_seed()
10156   INTEGER :: i, n, clock
10157   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10158
10159   CALL RANDOM_SEED(size = n)
10160   ALLOCATE(seed(n))
10161
10162   CALL SYSTEM_CLOCK(COUNT=clock)
10163
10164   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10165   CALL RANDOM_SEED(PUT = seed)
10166
10167   DEALLOCATE(seed)
10168 END SUBROUTINE
10169 @end smallexample
10170
10171 @item @emph{See also}:
10172 @ref{RANDOM_NUMBER}
10173 @end table
10174
10175
10176
10177 @node RANGE
10178 @section @code{RANGE} --- Decimal exponent range
10179 @fnindex RANGE
10180 @cindex model representation, range
10181
10182 @table @asis
10183 @item @emph{Description}:
10184 @code{RANGE(X)} returns the decimal exponent range in the model of the
10185 type of @code{X}.
10186
10187 @item @emph{Standard}:
10188 Fortran 95 and later
10189
10190 @item @emph{Class}:
10191 Inquiry function
10192
10193 @item @emph{Syntax}:
10194 @code{RESULT = RANGE(X)}
10195
10196 @item @emph{Arguments}:
10197 @multitable @columnfractions .15 .70
10198 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10199 or @code{COMPLEX}.
10200 @end multitable
10201
10202 @item @emph{Return value}:
10203 The return value is of type @code{INTEGER} and of the default integer
10204 kind.
10205
10206 @item @emph{See also}:
10207 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10208
10209 @item @emph{Example}:
10210 See @code{PRECISION} for an example.
10211 @end table
10212
10213
10214
10215 @node RANK
10216 @section @code{RANK} --- Rank of a data object
10217 @fnindex RANK
10218 @cindex rank
10219
10220 @table @asis
10221 @item @emph{Description}:
10222 @code{RANK(A)} returns the rank of a scalar or array data object.
10223
10224 @item @emph{Standard}:
10225 Technical Report (TR) 29113
10226
10227 @item @emph{Class}:
10228 Inquiry function
10229
10230 @item @emph{Syntax}:
10231 @code{RESULT = RANGE(A)}
10232
10233 @item @emph{Arguments}:
10234 @multitable @columnfractions .15 .70
10235 @item @var{A} @tab can be of any type
10236 @end multitable
10237
10238 @item @emph{Return value}:
10239 The return value is of type @code{INTEGER} and of the default integer
10240 kind. For arrays, their rank is returned; for scalars zero is returned.
10241
10242 @item @emph{Example}:
10243 @smallexample
10244 program test_rank
10245   integer :: a
10246   real, allocatable :: b(:,:)
10247
10248   print *, rank(a), rank(b) ! Prints:  0  3
10249 end program test_rank
10250 @end smallexample
10251
10252 @end table
10253
10254
10255
10256 @node REAL
10257 @section @code{REAL} --- Convert to real type
10258 @fnindex REAL
10259 @fnindex REALPART
10260 @fnindex FLOAT
10261 @fnindex DFLOAT
10262 @fnindex SNGL
10263 @cindex conversion, to real
10264 @cindex complex numbers, real part
10265
10266 @table @asis
10267 @item @emph{Description}:
10268 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type.  The
10269 @code{REALPART} function is provided for compatibility with @command{g77},
10270 and its use is strongly discouraged.
10271
10272 @item @emph{Standard}:
10273 Fortran 77 and later
10274
10275 @item @emph{Class}:
10276 Elemental function
10277
10278 @item @emph{Syntax}:
10279 @multitable @columnfractions .80
10280 @item @code{RESULT = REAL(A [, KIND])}
10281 @item @code{RESULT = REALPART(Z)}
10282 @end multitable
10283
10284 @item @emph{Arguments}:
10285 @multitable @columnfractions .15 .70
10286 @item @var{A}    @tab Shall be @code{INTEGER}, @code{REAL}, or
10287 @code{COMPLEX}.
10288 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10289 expression indicating the kind parameter of the result.
10290 @end multitable
10291
10292 @item @emph{Return value}:
10293 These functions return a @code{REAL} variable or array under
10294 the following rules:
10295
10296 @table @asis
10297 @item (A)
10298 @code{REAL(A)} is converted to a default real type if @var{A} is an
10299 integer or real variable.
10300 @item (B)
10301 @code{REAL(A)} is converted to a real type with the kind type parameter
10302 of @var{A} if @var{A} is a complex variable.
10303 @item (C)
10304 @code{REAL(A, KIND)} is converted to a real type with kind type
10305 parameter @var{KIND} if @var{A} is a complex, integer, or real
10306 variable.
10307 @end table
10308
10309 @item @emph{Example}:
10310 @smallexample
10311 program test_real
10312   complex :: x = (1.0, 2.0)
10313   print *, real(x), real(x,8), realpart(x)
10314 end program test_real
10315 @end smallexample
10316
10317 @item @emph{Specific names}:
10318 @multitable @columnfractions .20 .20 .20 .25
10319 @item Name             @tab Argument           @tab Return type     @tab Standard
10320 @item @code{FLOAT(A)}  @tab @code{INTEGER(4)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10321 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)}  @tab @code{REAL(8)}  @tab GNU extension
10322 @item @code{SNGL(A)}   @tab @code{INTEGER(8)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10323 @end multitable
10324
10325
10326 @item @emph{See also}:
10327 @ref{DBLE}
10328
10329 @end table
10330
10331
10332
10333 @node RENAME
10334 @section @code{RENAME} --- Rename a file
10335 @fnindex RENAME
10336 @cindex file system, rename file
10337
10338 @table @asis
10339 @item @emph{Description}:
10340 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10341 character (@code{CHAR(0)}) can be used to mark the end of the names in
10342 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10343 names are ignored.  If the @var{STATUS} argument is supplied, it
10344 contains 0 on success or a nonzero error code upon return; see
10345 @code{rename(2)}.
10346
10347 This intrinsic is provided in both subroutine and function forms;
10348 however, only one form can be used in any given program unit.
10349
10350 @item @emph{Standard}:
10351 GNU extension
10352
10353 @item @emph{Class}:
10354 Subroutine, function
10355
10356 @item @emph{Syntax}:
10357 @multitable @columnfractions .80
10358 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10359 @item @code{STATUS = RENAME(PATH1, PATH2)}
10360 @end multitable
10361
10362 @item @emph{Arguments}:
10363 @multitable @columnfractions .15 .70
10364 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10365 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10366 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10367 @end multitable
10368
10369 @item @emph{See also}:
10370 @ref{LINK}
10371
10372 @end table
10373
10374
10375
10376 @node REPEAT
10377 @section @code{REPEAT} --- Repeated string concatenation
10378 @fnindex REPEAT
10379 @cindex string, repeat
10380 @cindex string, concatenate
10381
10382 @table @asis
10383 @item @emph{Description}:
10384 Concatenates @var{NCOPIES} copies of a string.
10385
10386 @item @emph{Standard}:
10387 Fortran 95 and later
10388
10389 @item @emph{Class}:
10390 Transformational function
10391
10392 @item @emph{Syntax}:
10393 @code{RESULT = REPEAT(STRING, NCOPIES)}
10394
10395 @item @emph{Arguments}:
10396 @multitable @columnfractions .15 .70
10397 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
10398 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10399 @end multitable
10400
10401 @item @emph{Return value}:
10402 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10403 of @var{STRING}.
10404
10405 @item @emph{Example}:
10406 @smallexample
10407 program test_repeat
10408   write(*,*) repeat("x", 5)   ! "xxxxx"
10409 end program
10410 @end smallexample
10411 @end table
10412
10413
10414
10415 @node RESHAPE
10416 @section @code{RESHAPE} --- Function to reshape an array
10417 @fnindex RESHAPE
10418 @cindex array, change dimensions
10419 @cindex array, transmogrify
10420
10421 @table @asis
10422 @item @emph{Description}:
10423 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10424 the new array may be padded with elements from @var{PAD} or permuted
10425 as defined by @var{ORDER}.
10426
10427 @item @emph{Standard}:
10428 Fortran 95 and later
10429
10430 @item @emph{Class}:
10431 Transformational function
10432
10433 @item @emph{Syntax}:
10434 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10435
10436 @item @emph{Arguments}:
10437 @multitable @columnfractions .15 .70
10438 @item @var{SOURCE} @tab Shall be an array of any type.
10439 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
10440 array of rank one. Its values must be positive or zero.
10441 @item @var{PAD}    @tab (Optional) shall be an array of the same
10442 type as @var{SOURCE}.
10443 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
10444 and an array of the same shape as @var{SHAPE}. Its values shall
10445 be a permutation of the numbers from 1 to n, where n is the size of
10446 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10447 be assumed.
10448 @end multitable
10449
10450 @item @emph{Return value}:
10451 The result is an array of shape @var{SHAPE} with the same type as
10452 @var{SOURCE}.
10453
10454 @item @emph{Example}:
10455 @smallexample
10456 PROGRAM test_reshape
10457   INTEGER, DIMENSION(4) :: x
10458   WRITE(*,*) SHAPE(x)                       ! prints "4"
10459   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
10460 END PROGRAM
10461 @end smallexample
10462
10463 @item @emph{See also}:
10464 @ref{SHAPE}
10465 @end table
10466
10467
10468
10469 @node RRSPACING
10470 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10471 @fnindex RRSPACING
10472 @cindex real number, relative spacing
10473 @cindex floating point, relative spacing
10474
10475
10476 @table @asis
10477 @item @emph{Description}:
10478 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
10479 model numbers near @var{X}.
10480
10481 @item @emph{Standard}:
10482 Fortran 95 and later
10483
10484 @item @emph{Class}:
10485 Elemental function
10486
10487 @item @emph{Syntax}:
10488 @code{RESULT = RRSPACING(X)}
10489
10490 @item @emph{Arguments}:
10491 @multitable @columnfractions .15 .70
10492 @item @var{X} @tab Shall be of type @code{REAL}.
10493 @end multitable
10494
10495 @item @emph{Return value}:
10496 The return value is of the same type and kind as @var{X}.
10497 The value returned is equal to
10498 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10499
10500 @item @emph{See also}:
10501 @ref{SPACING}
10502 @end table
10503
10504
10505
10506 @node RSHIFT
10507 @section @code{RSHIFT} --- Right shift bits
10508 @fnindex RSHIFT
10509 @cindex bits, shift right
10510
10511 @table @asis
10512 @item @emph{Description}:
10513 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10514 bits shifted right by @var{SHIFT} places.  If the absolute value of
10515 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10516 Bits shifted out from the right end are lost. The fill is arithmetic: the
10517 bits shifted in from the left end are equal to the leftmost bit, which in
10518 two's complement representation is the sign bit.
10519
10520 This function has been superseded by the @code{SHIFTA} intrinsic, which
10521 is standard in Fortran 2008 and later.
10522
10523 @item @emph{Standard}:
10524 GNU extension
10525
10526 @item @emph{Class}:
10527 Elemental function
10528
10529 @item @emph{Syntax}:
10530 @code{RESULT = RSHIFT(I, SHIFT)}
10531
10532 @item @emph{Arguments}:
10533 @multitable @columnfractions .15 .70
10534 @item @var{I} @tab The type shall be @code{INTEGER}.
10535 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10536 @end multitable
10537
10538 @item @emph{Return value}:
10539 The return value is of type @code{INTEGER} and of the same kind as
10540 @var{I}.
10541
10542 @item @emph{See also}:
10543 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10544 @ref{SHIFTL}
10545
10546 @end table
10547
10548
10549
10550 @node SAME_TYPE_AS
10551 @section @code{SAME_TYPE_AS} ---  Query dynamic types for equality
10552 @fnindex SAME_TYPE_AS
10553
10554 @table @asis
10555 @item @emph{Description}:
10556 Query dynamic types for equality.
10557
10558 @item @emph{Standard}:
10559 Fortran 2003 and later
10560
10561 @item @emph{Class}:
10562 Inquiry function
10563
10564 @item @emph{Syntax}:
10565 @code{RESULT = SAME_TYPE_AS(A, B)}
10566
10567 @item @emph{Arguments}:
10568 @multitable @columnfractions .15 .70
10569 @item @var{A} @tab Shall be an object of extensible declared type or
10570 unlimited polymorphic.
10571 @item @var{B} @tab Shall be an object of extensible declared type or
10572 unlimited polymorphic.
10573 @end multitable
10574
10575 @item @emph{Return value}:
10576 The return value is a scalar of type default logical. It is true if and
10577 only if the dynamic type of A is the same as the dynamic type of B.
10578
10579 @item @emph{See also}:
10580 @ref{EXTENDS_TYPE_OF}
10581
10582 @end table
10583
10584
10585
10586 @node SCALE
10587 @section @code{SCALE} --- Scale a real value
10588 @fnindex SCALE
10589 @cindex real number, scale
10590 @cindex floating point, scale
10591
10592 @table @asis
10593 @item @emph{Description}:
10594 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10595
10596 @item @emph{Standard}:
10597 Fortran 95 and later
10598
10599 @item @emph{Class}:
10600 Elemental function
10601
10602 @item @emph{Syntax}:
10603 @code{RESULT = SCALE(X, I)}
10604
10605 @item @emph{Arguments}:
10606 @multitable @columnfractions .15 .70
10607 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10608 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10609 @end multitable
10610
10611 @item @emph{Return value}:
10612 The return value is of the same type and kind as @var{X}.
10613 Its value is @code{X * RADIX(X)**I}.
10614
10615 @item @emph{Example}:
10616 @smallexample
10617 program test_scale
10618   real :: x = 178.1387e-4
10619   integer :: i = 5
10620   print *, scale(x,i), x*radix(x)**i
10621 end program test_scale
10622 @end smallexample
10623
10624 @end table
10625
10626
10627
10628 @node SCAN
10629 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10630 @fnindex SCAN
10631 @cindex string, find subset
10632
10633 @table @asis
10634 @item @emph{Description}:
10635 Scans a @var{STRING} for any of the characters in a @var{SET}
10636 of characters.
10637
10638 If @var{BACK} is either absent or equals @code{FALSE}, this function
10639 returns the position of the leftmost character of @var{STRING} that is
10640 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10641 is returned. If no character of @var{SET} is found in @var{STRING}, the
10642 result is zero.
10643
10644 @item @emph{Standard}:
10645 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10646
10647 @item @emph{Class}:
10648 Elemental function
10649
10650 @item @emph{Syntax}:
10651 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10652
10653 @item @emph{Arguments}:
10654 @multitable @columnfractions .15 .70
10655 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10656 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
10657 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
10658 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
10659 expression indicating the kind parameter of the result.
10660 @end multitable
10661
10662 @item @emph{Return value}:
10663 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10664 @var{KIND} is absent, the return value is of default integer kind.
10665
10666 @item @emph{Example}:
10667 @smallexample
10668 PROGRAM test_scan
10669   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
10670   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
10671   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
10672 END PROGRAM
10673 @end smallexample
10674
10675 @item @emph{See also}:
10676 @ref{INDEX intrinsic}, @ref{VERIFY}
10677 @end table
10678
10679
10680
10681 @node SECNDS
10682 @section @code{SECNDS} --- Time function
10683 @fnindex SECNDS
10684 @cindex time, elapsed
10685 @cindex elapsed time
10686
10687 @table @asis
10688 @item @emph{Description}:
10689 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10690 @var{X} is a reference time, also in seconds. If this is zero, the time in
10691 seconds from midnight is returned. This function is non-standard and its
10692 use is discouraged.
10693
10694 @item @emph{Standard}:
10695 GNU extension
10696
10697 @item @emph{Class}:
10698 Function
10699
10700 @item @emph{Syntax}:
10701 @code{RESULT = SECNDS (X)}
10702
10703 @item @emph{Arguments}:
10704 @multitable @columnfractions .15 .70
10705 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
10706 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
10707 @end multitable
10708
10709 @item @emph{Return value}:
10710 None
10711
10712 @item @emph{Example}:
10713 @smallexample
10714 program test_secnds
10715     integer :: i
10716     real(4) :: t1, t2
10717     print *, secnds (0.0)   ! seconds since midnight
10718     t1 = secnds (0.0)       ! reference time
10719     do i = 1, 10000000      ! do something
10720     end do
10721     t2 = secnds (t1)        ! elapsed time
10722     print *, "Something took ", t2, " seconds."
10723 end program test_secnds
10724 @end smallexample
10725 @end table
10726
10727
10728
10729 @node SECOND
10730 @section @code{SECOND} --- CPU time function
10731 @fnindex SECOND
10732 @cindex time, elapsed
10733 @cindex elapsed time
10734
10735 @table @asis
10736 @item @emph{Description}:
10737 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10738 seconds.  This provides the same functionality as the standard
10739 @code{CPU_TIME} intrinsic, and is only included for backwards
10740 compatibility.
10741
10742 This intrinsic is provided in both subroutine and function forms;
10743 however, only one form can be used in any given program unit.
10744
10745 @item @emph{Standard}:
10746 GNU extension
10747
10748 @item @emph{Class}:
10749 Subroutine, function
10750
10751 @item @emph{Syntax}:
10752 @multitable @columnfractions .80
10753 @item @code{CALL SECOND(TIME)}
10754 @item @code{TIME = SECOND()}
10755 @end multitable
10756
10757 @item @emph{Arguments}:
10758 @multitable @columnfractions .15 .70
10759 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
10760 @end multitable
10761
10762 @item @emph{Return value}:
10763 In either syntax, @var{TIME} is set to the process's current runtime in
10764 seconds.
10765
10766 @item @emph{See also}:
10767 @ref{CPU_TIME}
10768
10769 @end table
10770
10771
10772
10773 @node SELECTED_CHAR_KIND
10774 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10775 @fnindex SELECTED_CHAR_KIND
10776 @cindex character kind
10777 @cindex kind, character
10778
10779 @table @asis
10780 @item @emph{Description}:
10781
10782 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10783 set named @var{NAME}, if a character set with such a name is supported,
10784 or @math{-1} otherwise. Currently, supported character sets include
10785 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10786 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10787
10788 @item @emph{Standard}:
10789 Fortran 2003 and later
10790
10791 @item @emph{Class}:
10792 Transformational function
10793
10794 @item @emph{Syntax}:
10795 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10796
10797 @item @emph{Arguments}:
10798 @multitable @columnfractions .15 .70
10799 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10800 @end multitable
10801
10802 @item @emph{Example}:
10803 @smallexample
10804 program character_kind
10805   use iso_fortran_env
10806   implicit none
10807   integer, parameter :: ascii = selected_char_kind ("ascii")
10808   integer, parameter :: ucs4  = selected_char_kind ('ISO_10646')
10809
10810   character(kind=ascii, len=26) :: alphabet
10811   character(kind=ucs4,  len=30) :: hello_world
10812
10813   alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10814   hello_world = ucs4_'Hello World and Ni Hao -- ' &
10815                 // char (int (z'4F60'), ucs4)     &
10816                 // char (int (z'597D'), ucs4)
10817
10818   write (*,*) alphabet
10819
10820   open (output_unit, encoding='UTF-8')
10821   write (*,*) trim (hello_world)
10822 end program character_kind
10823 @end smallexample
10824 @end table
10825
10826
10827
10828 @node SELECTED_INT_KIND
10829 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10830 @fnindex SELECTED_INT_KIND
10831 @cindex integer kind
10832 @cindex kind, integer
10833
10834 @table @asis
10835 @item @emph{Description}:
10836 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10837 type that can represent all values ranging from @math{-10^R} (exclusive)
10838 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10839 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10840
10841 @item @emph{Standard}:
10842 Fortran 95 and later
10843
10844 @item @emph{Class}:
10845 Transformational function
10846
10847 @item @emph{Syntax}:
10848 @code{RESULT = SELECTED_INT_KIND(R)}
10849
10850 @item @emph{Arguments}:
10851 @multitable @columnfractions .15 .70
10852 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10853 @end multitable
10854
10855 @item @emph{Example}:
10856 @smallexample
10857 program large_integers
10858   integer,parameter :: k5 = selected_int_kind(5)
10859   integer,parameter :: k15 = selected_int_kind(15)
10860   integer(kind=k5) :: i5
10861   integer(kind=k15) :: i15
10862
10863   print *, huge(i5), huge(i15)
10864
10865   ! The following inequalities are always true
10866   print *, huge(i5) >= 10_k5**5-1
10867   print *, huge(i15) >= 10_k15**15-1
10868 end program large_integers
10869 @end smallexample
10870 @end table
10871
10872
10873
10874 @node SELECTED_REAL_KIND
10875 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10876 @fnindex SELECTED_REAL_KIND
10877 @cindex real kind
10878 @cindex kind, real
10879 @cindex radix, real
10880
10881 @table @asis
10882 @item @emph{Description}:
10883 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10884 with decimal precision of at least @code{P} digits, exponent range of
10885 at least @code{R}, and with a radix of @code{RADIX}.
10886
10887 @item @emph{Standard}:
10888 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10889
10890 @item @emph{Class}:
10891 Transformational function
10892
10893 @item @emph{Syntax}:
10894 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10895
10896 @item @emph{Arguments}:
10897 @multitable @columnfractions .15 .70
10898 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10899 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10900 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10901 @end multitable
10902 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10903 be present; since Fortran 2008, they are assumed to be zero if absent.
10904
10905 @item @emph{Return value}:
10906
10907 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10908 a real data type with decimal precision of at least @code{P} digits, a
10909 decimal exponent range of at least @code{R}, and with the requested
10910 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10911 any radix can be returned. If more than one real data type meet the
10912 criteria, the kind of the data type with the smallest decimal precision
10913 is returned. If no real data type matches the criteria, the result is
10914 @table @asis
10915 @item -1 if the processor does not support a real data type with a
10916 precision greater than or equal to @code{P}, but the @code{R} and
10917 @code{RADIX} requirements can be fulfilled
10918 @item -2 if the processor does not support a real type with an exponent
10919 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10920 are fulfillable
10921 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10922 are fulfillable
10923 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10924 are fulfillable
10925 @item -5 if there is no real type with the given @code{RADIX}
10926 @end table
10927
10928 @item @emph{See also}:
10929 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10930
10931 @item @emph{Example}:
10932 @smallexample
10933 program real_kinds
10934   integer,parameter :: p6 = selected_real_kind(6)
10935   integer,parameter :: p10r100 = selected_real_kind(10,100)
10936   integer,parameter :: r400 = selected_real_kind(r=400)
10937   real(kind=p6) :: x
10938   real(kind=p10r100) :: y
10939   real(kind=r400) :: z
10940
10941   print *, precision(x), range(x)
10942   print *, precision(y), range(y)
10943   print *, precision(z), range(z)
10944 end program real_kinds
10945 @end smallexample
10946 @end table
10947
10948
10949
10950 @node SET_EXPONENT
10951 @section @code{SET_EXPONENT} --- Set the exponent of the model
10952 @fnindex SET_EXPONENT
10953 @cindex real number, set exponent
10954 @cindex floating point, set exponent
10955
10956 @table @asis
10957 @item @emph{Description}:
10958 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10959 is that that of @var{X} and whose exponent part is @var{I}.
10960
10961 @item @emph{Standard}:
10962 Fortran 95 and later
10963
10964 @item @emph{Class}:
10965 Elemental function
10966
10967 @item @emph{Syntax}:
10968 @code{RESULT = SET_EXPONENT(X, I)}
10969
10970 @item @emph{Arguments}:
10971 @multitable @columnfractions .15 .70
10972 @item @var{X} @tab Shall be of type @code{REAL}.
10973 @item @var{I} @tab Shall be of type @code{INTEGER}.
10974 @end multitable
10975
10976 @item @emph{Return value}:
10977 The return value is of the same type and kind as @var{X}.
10978 The real number whose fractional part
10979 is that that of @var{X} and whose exponent part if @var{I} is returned;
10980 it is @code{FRACTION(X) * RADIX(X)**I}.
10981
10982 @item @emph{Example}:
10983 @smallexample
10984 PROGRAM test_setexp
10985   REAL :: x = 178.1387e-4
10986   INTEGER :: i = 17
10987   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10988 END PROGRAM
10989 @end smallexample
10990
10991 @end table
10992
10993
10994
10995 @node SHAPE
10996 @section @code{SHAPE} --- Determine the shape of an array
10997 @fnindex SHAPE
10998 @cindex array, shape
10999
11000 @table @asis
11001 @item @emph{Description}:
11002 Determines the shape of an array.
11003
11004 @item @emph{Standard}:
11005 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11006
11007 @item @emph{Class}:
11008 Inquiry function
11009
11010 @item @emph{Syntax}:
11011 @code{RESULT = SHAPE(SOURCE [, KIND])}
11012
11013 @item @emph{Arguments}:
11014 @multitable @columnfractions .15 .70
11015 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11016 If @var{SOURCE} is a pointer it must be associated and allocatable
11017 arrays must be allocated.
11018 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
11019 expression indicating the kind parameter of the result.
11020 @end multitable
11021
11022 @item @emph{Return value}:
11023 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11024 has dimensions. The elements of the resulting array correspond to the extend
11025 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11026 the result is the rank one array of size zero. If @var{KIND} is absent, the
11027 return value has the default integer kind otherwise the specified kind.
11028
11029 @item @emph{Example}:
11030 @smallexample
11031 PROGRAM test_shape
11032   INTEGER, DIMENSION(-1:1, -1:2) :: A
11033   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
11034   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
11035 END PROGRAM
11036 @end smallexample
11037
11038 @item @emph{See also}:
11039 @ref{RESHAPE}, @ref{SIZE}
11040 @end table
11041
11042
11043
11044 @node SHIFTA
11045 @section @code{SHIFTA} --- Right shift with fill
11046 @fnindex SHIFTA
11047 @cindex bits, shift right
11048 @cindex shift, right with fill
11049
11050 @table @asis
11051 @item @emph{Description}:
11052 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11053 bits shifted right by @var{SHIFT} places.  If the absolute value of
11054 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11055 Bits shifted out from the right end are lost. The fill is arithmetic: the
11056 bits shifted in from the left end are equal to the leftmost bit, which in
11057 two's complement representation is the sign bit.
11058
11059 @item @emph{Standard}:
11060 Fortran 2008 and later
11061
11062 @item @emph{Class}:
11063 Elemental function
11064
11065 @item @emph{Syntax}:
11066 @code{RESULT = SHIFTA(I, SHIFT)}
11067
11068 @item @emph{Arguments}:
11069 @multitable @columnfractions .15 .70
11070 @item @var{I} @tab The type shall be @code{INTEGER}.
11071 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11072 @end multitable
11073
11074 @item @emph{Return value}:
11075 The return value is of type @code{INTEGER} and of the same kind as
11076 @var{I}.
11077
11078 @item @emph{See also}:
11079 @ref{SHIFTL}, @ref{SHIFTR}
11080 @end table
11081
11082
11083
11084 @node SHIFTL
11085 @section @code{SHIFTL} --- Left shift
11086 @fnindex SHIFTL
11087 @cindex bits, shift left
11088 @cindex shift, left
11089
11090 @table @asis
11091 @item @emph{Description}:
11092 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11093 bits shifted left by @var{SHIFT} places.  If the absolute value of
11094 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11095 Bits shifted out from the left end are lost, and bits shifted in from
11096 the right end are set to 0.
11097
11098 @item @emph{Standard}:
11099 Fortran 2008 and later
11100
11101 @item @emph{Class}:
11102 Elemental function
11103
11104 @item @emph{Syntax}:
11105 @code{RESULT = SHIFTL(I, SHIFT)}
11106
11107 @item @emph{Arguments}:
11108 @multitable @columnfractions .15 .70
11109 @item @var{I} @tab The type shall be @code{INTEGER}.
11110 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11111 @end multitable
11112
11113 @item @emph{Return value}:
11114 The return value is of type @code{INTEGER} and of the same kind as
11115 @var{I}.
11116
11117 @item @emph{See also}:
11118 @ref{SHIFTA}, @ref{SHIFTR}
11119 @end table
11120
11121
11122
11123 @node SHIFTR
11124 @section @code{SHIFTR} --- Right shift
11125 @fnindex SHIFTR
11126 @cindex bits, shift right
11127 @cindex shift, right
11128
11129 @table @asis
11130 @item @emph{Description}:
11131 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11132 bits shifted right by @var{SHIFT} places.  If the absolute value of
11133 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11134 Bits shifted out from the right end are lost, and bits shifted in from
11135 the left end are set to 0.
11136
11137 @item @emph{Standard}:
11138 Fortran 2008 and later
11139
11140 @item @emph{Class}:
11141 Elemental function
11142
11143 @item @emph{Syntax}:
11144 @code{RESULT = SHIFTR(I, SHIFT)}
11145
11146 @item @emph{Arguments}:
11147 @multitable @columnfractions .15 .70
11148 @item @var{I} @tab The type shall be @code{INTEGER}.
11149 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11150 @end multitable
11151
11152 @item @emph{Return value}:
11153 The return value is of type @code{INTEGER} and of the same kind as
11154 @var{I}.
11155
11156 @item @emph{See also}:
11157 @ref{SHIFTA}, @ref{SHIFTL}
11158 @end table
11159
11160
11161
11162 @node SIGN
11163 @section @code{SIGN} --- Sign copying function
11164 @fnindex SIGN
11165 @fnindex ISIGN
11166 @fnindex DSIGN
11167 @cindex sign copying
11168
11169 @table @asis
11170 @item @emph{Description}:
11171 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11172
11173 @item @emph{Standard}:
11174 Fortran 77 and later
11175
11176 @item @emph{Class}:
11177 Elemental function
11178
11179 @item @emph{Syntax}:
11180 @code{RESULT = SIGN(A, B)}
11181
11182 @item @emph{Arguments}:
11183 @multitable @columnfractions .15 .70
11184 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11185 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11186 @end multitable
11187
11188 @item @emph{Return value}:
11189 The kind of the return value is that of @var{A} and @var{B}.
11190 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11191 it is @code{-ABS(A)}.
11192
11193 @item @emph{Example}:
11194 @smallexample
11195 program test_sign
11196   print *, sign(-12,1)
11197   print *, sign(-12,0)
11198   print *, sign(-12,-1)
11199
11200   print *, sign(-12.,1.)
11201   print *, sign(-12.,0.)
11202   print *, sign(-12.,-1.)
11203 end program test_sign
11204 @end smallexample
11205
11206 @item @emph{Specific names}:
11207 @multitable @columnfractions .20 .20 .20 .25
11208 @item Name              @tab Arguments              @tab Return type       @tab Standard
11209 @item @code{SIGN(A,B)}  @tab @code{REAL(4) A, B}    @tab @code{REAL(4)}    @tab f77, gnu
11210 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11211 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B}    @tab @code{REAL(8)}    @tab f77, gnu
11212 @end multitable
11213 @end table
11214
11215
11216
11217 @node SIGNAL
11218 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11219 @fnindex SIGNAL
11220 @cindex system, signal handling
11221
11222 @table @asis
11223 @item @emph{Description}:
11224 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11225 @var{HANDLER} to be executed with a single integer argument when signal
11226 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
11227 turn off handling of signal @var{NUMBER} or revert to its default
11228 action.  See @code{signal(2)}.
11229
11230 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11231 is supplied, it is set to the value returned by @code{signal(2)}.
11232
11233 @item @emph{Standard}:
11234 GNU extension
11235
11236 @item @emph{Class}:
11237 Subroutine, function
11238
11239 @item @emph{Syntax}:
11240 @multitable @columnfractions .80
11241 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11242 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11243 @end multitable
11244
11245 @item @emph{Arguments}:
11246 @multitable @columnfractions .15 .70
11247 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11248 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11249 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11250 @code{INTEGER}. It is @code{INTENT(IN)}.
11251 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11252 integer. It has @code{INTENT(OUT)}.
11253 @end multitable
11254 @c TODO: What should the interface of the handler be?  Does it take arguments?
11255
11256 @item @emph{Return value}:
11257 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11258
11259 @item @emph{Example}:
11260 @smallexample
11261 program test_signal
11262   intrinsic signal
11263   external handler_print
11264
11265   call signal (12, handler_print)
11266   call signal (10, 1)
11267
11268   call sleep (30)
11269 end program test_signal
11270 @end smallexample
11271 @end table
11272
11273
11274
11275 @node SIN
11276 @section @code{SIN} --- Sine function
11277 @fnindex SIN
11278 @fnindex DSIN
11279 @fnindex CSIN
11280 @fnindex ZSIN
11281 @fnindex CDSIN
11282 @cindex trigonometric function, sine
11283 @cindex sine
11284
11285 @table @asis
11286 @item @emph{Description}:
11287 @code{SIN(X)} computes the sine of @var{X}.
11288
11289 @item @emph{Standard}:
11290 Fortran 77 and later
11291
11292 @item @emph{Class}:
11293 Elemental function
11294
11295 @item @emph{Syntax}:
11296 @code{RESULT = SIN(X)}
11297
11298 @item @emph{Arguments}:
11299 @multitable @columnfractions .15 .70
11300 @item @var{X} @tab The type shall be @code{REAL} or
11301 @code{COMPLEX}.
11302 @end multitable
11303
11304 @item @emph{Return value}:
11305 The return value has same type and kind as @var{X}.
11306
11307 @item @emph{Example}:
11308 @smallexample
11309 program test_sin
11310   real :: x = 0.0
11311   x = sin(x)
11312 end program test_sin
11313 @end smallexample
11314
11315 @item @emph{Specific names}:
11316 @multitable @columnfractions .20 .20 .20 .25
11317 @item Name            @tab Argument             @tab Return type       @tab Standard
11318 @item @code{SIN(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}    @tab f77, gnu
11319 @item @code{DSIN(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}    @tab f95, gnu
11320 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)} @tab f95, gnu
11321 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11322 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11323 @end multitable
11324
11325 @item @emph{See also}:
11326 @ref{ASIN}
11327 @end table
11328
11329
11330
11331 @node SINH
11332 @section @code{SINH} --- Hyperbolic sine function
11333 @fnindex SINH
11334 @fnindex DSINH
11335 @cindex hyperbolic sine
11336 @cindex hyperbolic function, sine
11337 @cindex sine, hyperbolic
11338
11339 @table @asis
11340 @item @emph{Description}:
11341 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11342
11343 @item @emph{Standard}:
11344 Fortran 95 and later, for a complex argument Fortran 2008 or later
11345
11346 @item @emph{Class}:
11347 Elemental function
11348
11349 @item @emph{Syntax}:
11350 @code{RESULT = SINH(X)}
11351
11352 @item @emph{Arguments}:
11353 @multitable @columnfractions .15 .70
11354 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11355 @end multitable
11356
11357 @item @emph{Return value}:
11358 The return value has same type and kind as @var{X}.
11359
11360 @item @emph{Example}:
11361 @smallexample
11362 program test_sinh
11363   real(8) :: x = - 1.0_8
11364   x = sinh(x)
11365 end program test_sinh
11366 @end smallexample
11367
11368 @item @emph{Specific names}:
11369 @multitable @columnfractions .20 .20 .20 .25
11370 @item Name            @tab Argument          @tab Return type       @tab Standard
11371 @item @code{SINH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
11372 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
11373 @end multitable
11374
11375 @item @emph{See also}:
11376 @ref{ASINH}
11377 @end table
11378
11379
11380
11381 @node SIZE
11382 @section @code{SIZE} --- Determine the size of an array
11383 @fnindex SIZE
11384 @cindex array, size
11385 @cindex array, number of elements
11386 @cindex array, count elements
11387
11388 @table @asis
11389 @item @emph{Description}:
11390 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11391 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11392
11393 @item @emph{Standard}:
11394 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11395
11396 @item @emph{Class}:
11397 Inquiry function
11398
11399 @item @emph{Syntax}:
11400 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11401
11402 @item @emph{Arguments}:
11403 @multitable @columnfractions .15 .70
11404 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11405 a pointer it must be associated and allocatable arrays must be allocated.
11406 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
11407 and its value shall be in the range from 1 to n, where n equals the rank
11408 of @var{ARRAY}.
11409 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11410 expression indicating the kind parameter of the result.
11411 @end multitable
11412
11413 @item @emph{Return value}:
11414 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11415 @var{KIND} is absent, the return value is of default integer kind.
11416
11417 @item @emph{Example}:
11418 @smallexample
11419 PROGRAM test_size
11420   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
11421 END PROGRAM
11422 @end smallexample
11423
11424 @item @emph{See also}:
11425 @ref{SHAPE}, @ref{RESHAPE}
11426 @end table
11427
11428
11429 @node SIZEOF
11430 @section @code{SIZEOF} --- Size in bytes of an expression
11431 @fnindex SIZEOF
11432 @cindex expression size
11433 @cindex size of an expression
11434
11435 @table @asis
11436 @item @emph{Description}:
11437 @code{SIZEOF(X)} calculates the number of bytes of storage the
11438 expression @code{X} occupies.
11439
11440 @item @emph{Standard}:
11441 GNU extension
11442
11443 @item @emph{Class}:
11444 Intrinsic function
11445
11446 @item @emph{Syntax}:
11447 @code{N = SIZEOF(X)}
11448
11449 @item @emph{Arguments}:
11450 @multitable @columnfractions .15 .70
11451 @item @var{X} @tab The argument shall be of any type, rank or shape.
11452 @end multitable
11453
11454 @item @emph{Return value}:
11455 The return value is of type integer and of the system-dependent kind
11456 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11457 number of bytes occupied by the argument.  If the argument has the
11458 @code{POINTER} attribute, the number of bytes of the storage area pointed
11459 to is returned.  If the argument is of a derived type with @code{POINTER}
11460 or @code{ALLOCATABLE} components, the return value doesn't account for
11461 the sizes of the data pointed to by these components. If the argument is
11462 polymorphic, the size according to the declared type is returned.
11463
11464 @item @emph{Example}:
11465 @smallexample
11466    integer :: i
11467    real :: r, s(5)
11468    print *, (sizeof(s)/sizeof(r) == 5)
11469    end
11470 @end smallexample
11471 The example will print @code{.TRUE.} unless you are using a platform
11472 where default @code{REAL} variables are unusually padded.
11473
11474 @item @emph{See also}:
11475 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11476 @end table
11477
11478
11479 @node SLEEP
11480 @section @code{SLEEP} --- Sleep for the specified number of seconds
11481 @fnindex SLEEP
11482 @cindex delayed execution
11483
11484 @table @asis
11485 @item @emph{Description}:
11486 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11487
11488 @item @emph{Standard}:
11489 GNU extension
11490
11491 @item @emph{Class}:
11492 Subroutine
11493
11494 @item @emph{Syntax}:
11495 @code{CALL SLEEP(SECONDS)}
11496
11497 @item @emph{Arguments}:
11498 @multitable @columnfractions .15 .70
11499 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11500 @end multitable
11501
11502 @item @emph{Example}:
11503 @smallexample
11504 program test_sleep
11505   call sleep(5)
11506 end
11507 @end smallexample
11508 @end table
11509
11510
11511
11512 @node SPACING
11513 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11514 @fnindex SPACING
11515 @cindex real number, relative spacing
11516 @cindex floating point, relative spacing
11517
11518 @table @asis
11519 @item @emph{Description}:
11520 Determines the distance between the argument @var{X} and the nearest
11521 adjacent number of the same type.
11522
11523 @item @emph{Standard}:
11524 Fortran 95 and later
11525
11526 @item @emph{Class}:
11527 Elemental function
11528
11529 @item @emph{Syntax}:
11530 @code{RESULT = SPACING(X)}
11531
11532 @item @emph{Arguments}:
11533 @multitable @columnfractions .15 .70
11534 @item @var{X} @tab Shall be of type @code{REAL}.
11535 @end multitable
11536
11537 @item @emph{Return value}:
11538 The result is of the same type as the input argument @var{X}.
11539
11540 @item @emph{Example}:
11541 @smallexample
11542 PROGRAM test_spacing
11543   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11544   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11545
11546   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
11547   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
11548 END PROGRAM
11549 @end smallexample
11550
11551 @item @emph{See also}:
11552 @ref{RRSPACING}
11553 @end table
11554
11555
11556
11557 @node SPREAD
11558 @section @code{SPREAD} --- Add a dimension to an array
11559 @fnindex SPREAD
11560 @cindex array, increase dimension
11561 @cindex array, duplicate elements
11562 @cindex array, duplicate dimensions
11563
11564 @table @asis
11565 @item @emph{Description}:
11566 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11567 dimension @var{DIM}.
11568
11569 @item @emph{Standard}:
11570 Fortran 95 and later
11571
11572 @item @emph{Class}:
11573 Transformational function
11574
11575 @item @emph{Syntax}:
11576 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11577
11578 @item @emph{Arguments}:
11579 @multitable @columnfractions .15 .70
11580 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
11581 a rank less than seven.
11582 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
11583 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11584 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11585 @end multitable
11586
11587 @item @emph{Return value}:
11588 The result is an array of the same type as @var{SOURCE} and has rank n+1
11589 where n equals the rank of @var{SOURCE}.
11590
11591 @item @emph{Example}:
11592 @smallexample
11593 PROGRAM test_spread
11594   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11595   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
11596   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
11597 END PROGRAM
11598 @end smallexample
11599
11600 @item @emph{See also}:
11601 @ref{UNPACK}
11602 @end table
11603
11604
11605
11606 @node SQRT
11607 @section @code{SQRT} --- Square-root function
11608 @fnindex SQRT
11609 @fnindex DSQRT
11610 @fnindex CSQRT
11611 @fnindex ZSQRT
11612 @fnindex CDSQRT
11613 @cindex root
11614 @cindex square-root
11615
11616 @table @asis
11617 @item @emph{Description}:
11618 @code{SQRT(X)} computes the square root of @var{X}.
11619
11620 @item @emph{Standard}:
11621 Fortran 77 and later
11622
11623 @item @emph{Class}:
11624 Elemental function
11625
11626 @item @emph{Syntax}:
11627 @code{RESULT = SQRT(X)}
11628
11629 @item @emph{Arguments}:
11630 @multitable @columnfractions .15 .70
11631 @item @var{X} @tab The type shall be @code{REAL} or
11632 @code{COMPLEX}.
11633 @end multitable
11634
11635 @item @emph{Return value}:
11636 The return value is of type @code{REAL} or @code{COMPLEX}.
11637 The kind type parameter is the same as @var{X}.
11638
11639 @item @emph{Example}:
11640 @smallexample
11641 program test_sqrt
11642   real(8) :: x = 2.0_8
11643   complex :: z = (1.0, 2.0)
11644   x = sqrt(x)
11645   z = sqrt(z)
11646 end program test_sqrt
11647 @end smallexample
11648
11649 @item @emph{Specific names}:
11650 @multitable @columnfractions .20 .20 .20 .25
11651 @item Name             @tab Argument             @tab Return type          @tab Standard
11652 @item @code{SQRT(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}       @tab Fortran 95 and later
11653 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
11654 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
11655 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11656 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11657 @end multitable
11658 @end table
11659
11660
11661
11662 @node SRAND
11663 @section @code{SRAND} --- Reinitialize the random number generator
11664 @fnindex SRAND
11665 @cindex random number generation, seeding
11666 @cindex seeding a random number generator
11667
11668 @table @asis
11669 @item @emph{Description}:
11670 @code{SRAND} reinitializes the pseudo-random number generator
11671 called by @code{RAND} and @code{IRAND}. The new seed used by the
11672 generator is specified by the required argument @var{SEED}.
11673
11674 @item @emph{Standard}:
11675 GNU extension
11676
11677 @item @emph{Class}:
11678 Subroutine
11679
11680 @item @emph{Syntax}:
11681 @code{CALL SRAND(SEED)}
11682
11683 @item @emph{Arguments}:
11684 @multitable @columnfractions .15 .70
11685 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11686 @end multitable
11687
11688 @item @emph{Return value}:
11689 Does not return anything.
11690
11691 @item @emph{Example}:
11692 See @code{RAND} and @code{IRAND} for examples.
11693
11694 @item @emph{Notes}:
11695 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11696 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11697 to generate pseudo-random numbers. Please note that in
11698 GNU Fortran, these two sets of intrinsics (@code{RAND},
11699 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11700 @code{RANDOM_SEED} on the other hand) access two independent
11701 pseudo-random number generators.
11702
11703 @item @emph{See also}:
11704 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11705
11706 @end table
11707
11708
11709
11710 @node STAT
11711 @section @code{STAT} --- Get file status
11712 @fnindex STAT
11713 @cindex file system, file status
11714
11715 @table @asis
11716 @item @emph{Description}:
11717 This function returns information about a file. No permissions are required on
11718 the file itself, but execute (search) permission is required on all of the
11719 directories in path that lead to the file.
11720
11721 The elements that are obtained and stored in the array @code{VALUES}:
11722 @multitable @columnfractions .15 .70
11723 @item @code{VALUES(1)}   @tab  Device ID
11724 @item @code{VALUES(2)}   @tab  Inode number
11725 @item @code{VALUES(3)}   @tab  File mode
11726 @item @code{VALUES(4)}   @tab  Number of links
11727 @item @code{VALUES(5)}   @tab  Owner's uid
11728 @item @code{VALUES(6)}   @tab  Owner's gid
11729 @item @code{VALUES(7)}   @tab  ID of device containing directory entry for file (0 if not available)
11730 @item @code{VALUES(8)}   @tab  File size (bytes)
11731 @item @code{VALUES(9)}   @tab  Last access time
11732 @item @code{VALUES(10)}  @tab  Last modification time
11733 @item @code{VALUES(11)}  @tab  Last file status change time
11734 @item @code{VALUES(12)}  @tab  Preferred I/O block size (-1 if not available)
11735 @item @code{VALUES(13)}  @tab  Number of blocks allocated (-1 if not available)
11736 @end multitable
11737
11738 Not all these elements are relevant on all systems.
11739 If an element is not relevant, it is returned as 0.
11740
11741 This intrinsic is provided in both subroutine and function forms; however,
11742 only one form can be used in any given program unit.
11743
11744 @item @emph{Standard}:
11745 GNU extension
11746
11747 @item @emph{Class}:
11748 Subroutine, function
11749
11750 @item @emph{Syntax}:
11751 @multitable @columnfractions .80
11752 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11753 @item @code{STATUS = STAT(NAME, VALUES)}
11754 @end multitable
11755
11756 @item @emph{Arguments}:
11757 @multitable @columnfractions .15 .70
11758 @item @var{NAME}   @tab The type shall be @code{CHARACTER}, of the
11759 default kind and a valid path within the file system.
11760 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11761 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11762 on success and a system specific error code otherwise.
11763 @end multitable
11764
11765 @item @emph{Example}:
11766 @smallexample
11767 PROGRAM test_stat
11768   INTEGER, DIMENSION(13) :: buff
11769   INTEGER :: status
11770
11771   CALL STAT("/etc/passwd", buff, status)
11772
11773   IF (status == 0) THEN
11774     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
11775     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
11776     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
11777     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
11778     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
11779     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
11780     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
11781     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
11782     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
11783     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
11784     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11785     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
11786     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11787   END IF
11788 END PROGRAM
11789 @end smallexample
11790
11791 @item @emph{See also}:
11792 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11793 @end table
11794
11795
11796
11797 @node STORAGE_SIZE
11798 @section @code{STORAGE_SIZE} --- Storage size in bits
11799 @fnindex STORAGE_SIZE
11800 @cindex storage size
11801
11802 @table @asis
11803 @item @emph{Description}:
11804 Returns the storage size of argument @var{A} in bits.
11805 @item @emph{Standard}:
11806 Fortran 2008 and later
11807 @item @emph{Class}:
11808 Inquiry function
11809 @item @emph{Syntax}:
11810 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11811
11812 @item @emph{Arguments}:
11813 @multitable @columnfractions .15 .70
11814 @item @var{A} @tab Shall be a scalar or array of any type.
11815 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11816 @end multitable
11817
11818 @item @emph{Return Value}:
11819 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
11820 has the dynamic type and type parameters of A.
11821
11822 @item @emph{See also}:
11823 @ref{C_SIZEOF}, @ref{SIZEOF}
11824 @end table
11825
11826
11827
11828 @node SUM
11829 @section @code{SUM} --- Sum of array elements
11830 @fnindex SUM
11831 @cindex array, sum
11832 @cindex array, add elements
11833 @cindex array, conditionally add elements
11834 @cindex sum array elements
11835
11836 @table @asis
11837 @item @emph{Description}:
11838 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11839 the corresponding element in @var{MASK} is @code{TRUE}.
11840
11841 @item @emph{Standard}:
11842 Fortran 95 and later
11843
11844 @item @emph{Class}:
11845 Transformational function
11846
11847 @item @emph{Syntax}:
11848 @multitable @columnfractions .80
11849 @item @code{RESULT = SUM(ARRAY[, MASK])}
11850 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11851 @end multitable
11852
11853 @item @emph{Arguments}:
11854 @multitable @columnfractions .15 .70
11855 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11856 @code{REAL} or @code{COMPLEX}.
11857 @item @var{DIM}   @tab (Optional) shall be a scalar of type
11858 @code{INTEGER} with a value in the range from 1 to n, where n
11859 equals the rank of @var{ARRAY}.
11860 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
11861 and either be a scalar or an array of the same shape as @var{ARRAY}.
11862 @end multitable
11863
11864 @item @emph{Return value}:
11865 The result is of the same type as @var{ARRAY}.
11866
11867 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11868 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11869 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11870 dropped is returned.
11871
11872 @item @emph{Example}:
11873 @smallexample
11874 PROGRAM test_sum
11875   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11876   print *, SUM(x)                        ! all elements, sum = 15
11877   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
11878 END PROGRAM
11879 @end smallexample
11880
11881 @item @emph{See also}:
11882 @ref{PRODUCT}
11883 @end table
11884
11885
11886
11887 @node SYMLNK
11888 @section @code{SYMLNK} --- Create a symbolic link
11889 @fnindex SYMLNK
11890 @cindex file system, create link
11891 @cindex file system, soft link
11892
11893 @table @asis
11894 @item @emph{Description}:
11895 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11896 character (@code{CHAR(0)}) can be used to mark the end of the names in
11897 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11898 names are ignored.  If the @var{STATUS} argument is supplied, it
11899 contains 0 on success or a nonzero error code upon return; see
11900 @code{symlink(2)}.  If the system does not supply @code{symlink(2)},
11901 @code{ENOSYS} is returned.
11902
11903 This intrinsic is provided in both subroutine and function forms;
11904 however, only one form can be used in any given program unit.
11905
11906 @item @emph{Standard}:
11907 GNU extension
11908
11909 @item @emph{Class}:
11910 Subroutine, function
11911
11912 @item @emph{Syntax}:
11913 @multitable @columnfractions .80
11914 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11915 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11916 @end multitable
11917
11918 @item @emph{Arguments}:
11919 @multitable @columnfractions .15 .70
11920 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11921 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11922 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11923 @end multitable
11924
11925 @item @emph{See also}:
11926 @ref{LINK}, @ref{UNLINK}
11927
11928 @end table
11929
11930
11931
11932 @node SYSTEM
11933 @section @code{SYSTEM} --- Execute a shell command
11934 @fnindex SYSTEM
11935 @cindex system, system call
11936
11937 @table @asis
11938 @item @emph{Description}:
11939 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11940 argument @var{STATUS} is present, it contains the value returned by
11941 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11942 Note that which shell is used to invoke the command is system-dependent
11943 and environment-dependent.
11944
11945 This intrinsic is provided in both subroutine and function forms;
11946 however, only one form can be used in any given program unit.
11947
11948 Note that the @code{system} function need not be thread-safe. It is
11949 the responsibility of the user to ensure that @code{system} is not
11950 called concurrently.
11951
11952 @item @emph{Standard}:
11953 GNU extension
11954
11955 @item @emph{Class}:
11956 Subroutine, function
11957
11958 @item @emph{Syntax}:
11959 @multitable @columnfractions .80
11960 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11961 @item @code{STATUS = SYSTEM(COMMAND)}
11962 @end multitable
11963
11964 @item @emph{Arguments}:
11965 @multitable @columnfractions .15 .70
11966 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11967 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
11968 @end multitable
11969
11970 @item @emph{See also}:
11971 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11972 and should considered in new code for future portability.
11973 @end table
11974
11975
11976
11977 @node SYSTEM_CLOCK
11978 @section @code{SYSTEM_CLOCK} --- Time function
11979 @fnindex SYSTEM_CLOCK
11980 @cindex time, clock ticks
11981 @cindex clock ticks
11982
11983 @table @asis
11984 @item @emph{Description}:
11985 Determines the @var{COUNT} of a processor clock since an unspecified
11986 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
11987 the number of clock ticks per second.  If the platform supports a high
11988 resolution monotonic clock, that clock is used and can provide up to
11989 nanosecond resolution.  If a high resolution monotonic clock is not
11990 available, the implementation falls back to a potentially lower
11991 resolution realtime clock.
11992
11993 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
11994 arguments.  For @var{kind=8} arguments, @var{COUNT} represents
11995 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
11996 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
11997 @var{COUNT_MAX} are constant, however the particular values are
11998 specific to @command{gfortran}.
11999
12000 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
12001 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
12002
12003 When running on a platform using the GNU C library (glibc), or a
12004 derivative thereof, the high resolution monotonic clock is available
12005 only when linking with the @var{rt} library.  This can be done
12006 explicitly by adding the @code{-lrt} flag when linking the
12007 application, but is also done implicitly when using OpenMP.
12008
12009 @item @emph{Standard}:
12010 Fortran 95 and later
12011
12012 @item @emph{Class}:
12013 Subroutine
12014
12015 @item @emph{Syntax}:
12016 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12017
12018 @item @emph{Arguments}:
12019 @multitable @columnfractions .15 .70
12020 @item @var{COUNT}      @tab (Optional) shall be a scalar of type
12021 @code{INTEGER} with @code{INTENT(OUT)}.
12022 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12023 @code{INTEGER} with @code{INTENT(OUT)}.
12024 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type
12025 @code{INTEGER} with @code{INTENT(OUT)}.
12026 @end multitable
12027
12028 @item @emph{Example}:
12029 @smallexample
12030 PROGRAM test_system_clock
12031   INTEGER :: count, count_rate, count_max
12032   CALL SYSTEM_CLOCK(count, count_rate, count_max)
12033   WRITE(*,*) count, count_rate, count_max
12034 END PROGRAM
12035 @end smallexample
12036
12037 @item @emph{See also}:
12038 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12039 @end table
12040
12041
12042
12043 @node TAN
12044 @section @code{TAN} --- Tangent function
12045 @fnindex TAN
12046 @fnindex DTAN
12047 @cindex trigonometric function, tangent
12048 @cindex tangent
12049
12050 @table @asis
12051 @item @emph{Description}:
12052 @code{TAN(X)} computes the tangent of @var{X}.
12053
12054 @item @emph{Standard}:
12055 Fortran 77 and later, for a complex argument Fortran 2008 or later
12056
12057 @item @emph{Class}:
12058 Elemental function
12059
12060 @item @emph{Syntax}:
12061 @code{RESULT = TAN(X)}
12062
12063 @item @emph{Arguments}:
12064 @multitable @columnfractions .15 .70
12065 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12066 @end multitable
12067
12068 @item @emph{Return value}:
12069 The return value has same type and kind as @var{X}.
12070
12071 @item @emph{Example}:
12072 @smallexample
12073 program test_tan
12074   real(8) :: x = 0.165_8
12075   x = tan(x)
12076 end program test_tan
12077 @end smallexample
12078
12079 @item @emph{Specific names}:
12080 @multitable @columnfractions .20 .20 .20 .25
12081 @item Name            @tab Argument          @tab Return type     @tab Standard
12082 @item @code{TAN(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab Fortran 95 and later
12083 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab Fortran 95 and later
12084 @end multitable
12085
12086 @item @emph{See also}:
12087 @ref{ATAN}
12088 @end table
12089
12090
12091
12092 @node TANH
12093 @section @code{TANH} --- Hyperbolic tangent function
12094 @fnindex TANH
12095 @fnindex DTANH
12096 @cindex hyperbolic tangent
12097 @cindex hyperbolic function, tangent
12098 @cindex tangent, hyperbolic
12099
12100 @table @asis
12101 @item @emph{Description}:
12102 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12103
12104 @item @emph{Standard}:
12105 Fortran 77 and later, for a complex argument Fortran 2008 or later
12106
12107 @item @emph{Class}:
12108 Elemental function
12109
12110 @item @emph{Syntax}:
12111 @code{X = TANH(X)}
12112
12113 @item @emph{Arguments}:
12114 @multitable @columnfractions .15 .70
12115 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12116 @end multitable
12117
12118 @item @emph{Return value}:
12119 The return value has same type and kind as @var{X}. If @var{X} is
12120 complex, the imaginary part of the result is in radians. If @var{X}
12121 is @code{REAL}, the return value lies in the range
12122 @math{ - 1 \leq tanh(x) \leq 1 }.
12123
12124 @item @emph{Example}:
12125 @smallexample
12126 program test_tanh
12127   real(8) :: x = 2.1_8
12128   x = tanh(x)
12129 end program test_tanh
12130 @end smallexample
12131
12132 @item @emph{Specific names}:
12133 @multitable @columnfractions .20 .20 .20 .25
12134 @item Name            @tab Argument          @tab Return type       @tab Standard
12135 @item @code{TANH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
12136 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
12137 @end multitable
12138
12139 @item @emph{See also}:
12140 @ref{ATANH}
12141 @end table
12142
12143
12144
12145 @node THIS_IMAGE
12146 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12147 @fnindex THIS_IMAGE
12148 @cindex coarray, @code{THIS_IMAGE}
12149 @cindex images, index of this image
12150
12151 @table @asis
12152 @item @emph{Description}:
12153 Returns the cosubscript for this image.
12154
12155 @item @emph{Standard}:
12156 Fortran 2008 and later
12157
12158 @item @emph{Class}:
12159 Transformational function
12160
12161 @item @emph{Syntax}:
12162 @multitable @columnfractions .80
12163 @item @code{RESULT = THIS_IMAGE()}
12164 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12165 @end multitable
12166
12167 @item @emph{Arguments}:
12168 @multitable @columnfractions .15 .70
12169 @item @var{COARRAY} @tab Coarray of any type  (optional; if @var{DIM}
12170 present, required).
12171 @item @var{DIM}     @tab default integer scalar (optional). If present,
12172 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12173 @end multitable
12174
12175
12176 @item @emph{Return value}:
12177 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12178 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12179 a rank-1 array with corank elements is returned, containing the cosubscripts
12180 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12181 a scalar is returned, with the value of the @var{DIM} element of
12182 @code{THIS_IMAGE(COARRAY)}.
12183
12184 @item @emph{Example}:
12185 @smallexample
12186 INTEGER :: value[*]
12187 INTEGER :: i
12188 value = THIS_IMAGE()
12189 SYNC ALL
12190 IF (THIS_IMAGE() == 1) THEN
12191   DO i = 1, NUM_IMAGES()
12192     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12193   END DO
12194 END IF
12195 @end smallexample
12196
12197 @item @emph{See also}:
12198 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12199 @end table
12200
12201
12202
12203 @node TIME
12204 @section @code{TIME} --- Time function
12205 @fnindex TIME
12206 @cindex time, current
12207 @cindex current time
12208
12209 @table @asis
12210 @item @emph{Description}:
12211 Returns the current time encoded as an integer (in the manner of the
12212 UNIX function @code{time(3)}). This value is suitable for passing to
12213 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12214
12215 This intrinsic is not fully portable, such as to systems with 32-bit
12216 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12217 the values returned by this intrinsic might be, or become, negative, or
12218 numerically less than previous values, during a single run of the
12219 compiled program.
12220
12221 See @ref{TIME8}, for information on a similar intrinsic that might be
12222 portable to more GNU Fortran implementations, though to fewer Fortran
12223 compilers.
12224
12225 @item @emph{Standard}:
12226 GNU extension
12227
12228 @item @emph{Class}:
12229 Function
12230
12231 @item @emph{Syntax}:
12232 @code{RESULT = TIME()}
12233
12234 @item @emph{Return value}:
12235 The return value is a scalar of type @code{INTEGER(4)}.
12236
12237 @item @emph{See also}:
12238 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12239
12240 @end table
12241
12242
12243
12244 @node TIME8
12245 @section @code{TIME8} --- Time function (64-bit)
12246 @fnindex TIME8
12247 @cindex time, current
12248 @cindex current time
12249
12250 @table @asis
12251 @item @emph{Description}:
12252 Returns the current time encoded as an integer (in the manner of the
12253 UNIX function @code{time(3)}). This value is suitable for passing to
12254 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12255
12256 @emph{Warning:} this intrinsic does not increase the range of the timing
12257 values over that returned by @code{time(3)}. On a system with a 32-bit
12258 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12259 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12260 overflows of the 32-bit value can still occur. Therefore, the values
12261 returned by this intrinsic might be or become negative or numerically
12262 less than previous values during a single run of the compiled program.
12263
12264 @item @emph{Standard}:
12265 GNU extension
12266
12267 @item @emph{Class}:
12268 Function
12269
12270 @item @emph{Syntax}:
12271 @code{RESULT = TIME8()}
12272
12273 @item @emph{Return value}:
12274 The return value is a scalar of type @code{INTEGER(8)}.
12275
12276 @item @emph{See also}:
12277 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12278
12279 @end table
12280
12281
12282
12283 @node TINY
12284 @section @code{TINY} --- Smallest positive number of a real kind
12285 @fnindex TINY
12286 @cindex limits, smallest number
12287 @cindex model representation, smallest number
12288
12289 @table @asis
12290 @item @emph{Description}:
12291 @code{TINY(X)} returns the smallest positive (non zero) number
12292 in the model of the type of @code{X}.
12293
12294 @item @emph{Standard}:
12295 Fortran 95 and later
12296
12297 @item @emph{Class}:
12298 Inquiry function
12299
12300 @item @emph{Syntax}:
12301 @code{RESULT = TINY(X)}
12302
12303 @item @emph{Arguments}:
12304 @multitable @columnfractions .15 .70
12305 @item @var{X} @tab Shall be of type @code{REAL}.
12306 @end multitable
12307
12308 @item @emph{Return value}:
12309 The return value is of the same type and kind as @var{X}
12310
12311 @item @emph{Example}:
12312 See @code{HUGE} for an example.
12313 @end table
12314
12315
12316
12317 @node TRAILZ
12318 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12319 @fnindex TRAILZ
12320 @cindex zero bits
12321
12322 @table @asis
12323 @item @emph{Description}:
12324 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12325
12326 @item @emph{Standard}:
12327 Fortran 2008 and later
12328
12329 @item @emph{Class}:
12330 Elemental function
12331
12332 @item @emph{Syntax}:
12333 @code{RESULT = TRAILZ(I)}
12334
12335 @item @emph{Arguments}:
12336 @multitable @columnfractions .15 .70
12337 @item @var{I} @tab Shall be of type @code{INTEGER}.
12338 @end multitable
12339
12340 @item @emph{Return value}:
12341 The type of the return value is the default @code{INTEGER}.
12342 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12343
12344 @item @emph{Example}:
12345 @smallexample
12346 PROGRAM test_trailz
12347   WRITE (*,*) TRAILZ(8)  ! prints 3
12348 END PROGRAM
12349 @end smallexample
12350
12351 @item @emph{See also}:
12352 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12353 @end table
12354
12355
12356
12357 @node TRANSFER
12358 @section @code{TRANSFER} --- Transfer bit patterns
12359 @fnindex TRANSFER
12360 @cindex bits, move
12361 @cindex type cast
12362
12363 @table @asis
12364 @item @emph{Description}:
12365 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12366 is the representation of a variable or array of the same type and type
12367 parameters as @var{MOLD}.
12368
12369 This is approximately equivalent to the C concept of @emph{casting} one
12370 type to another.
12371
12372 @item @emph{Standard}:
12373 Fortran 95 and later
12374
12375 @item @emph{Class}:
12376 Transformational function
12377
12378 @item @emph{Syntax}:
12379 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12380
12381 @item @emph{Arguments}:
12382 @multitable @columnfractions .15 .70
12383 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12384 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
12385 @item @var{SIZE}   @tab (Optional) shall be a scalar of type
12386 @code{INTEGER}.
12387 @end multitable
12388
12389 @item @emph{Return value}:
12390 The result has the same type as @var{MOLD}, with the bit level
12391 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
12392 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
12393 but @var{MOLD} is an array (of any size or shape), the result is a one-
12394 dimensional array of the minimum length needed to contain the entirety
12395 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
12396 and @var{MOLD} is a scalar, the result is a scalar.
12397
12398 If the bitwise representation of the result is longer than that of
12399 @var{SOURCE}, then the leading bits of the result correspond to those of
12400 @var{SOURCE} and any trailing bits are filled arbitrarily.
12401
12402 When the resulting bit representation does not correspond to a valid
12403 representation of a variable of the same type as @var{MOLD}, the results
12404 are undefined, and subsequent operations on the result cannot be
12405 guaranteed to produce sensible behavior.  For example, it is possible to
12406 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12407 @code{.NOT.@var{VAR}} both appear to be true.
12408
12409 @item @emph{Example}:
12410 @smallexample
12411 PROGRAM test_transfer
12412   integer :: x = 2143289344
12413   print *, transfer(x, 1.0)    ! prints "NaN" on i686
12414 END PROGRAM
12415 @end smallexample
12416 @end table
12417
12418
12419
12420 @node TRANSPOSE
12421 @section @code{TRANSPOSE} --- Transpose an array of rank two
12422 @fnindex TRANSPOSE
12423 @cindex array, transpose
12424 @cindex matrix, transpose
12425 @cindex transpose
12426
12427 @table @asis
12428 @item @emph{Description}:
12429 Transpose an array of rank two. Element (i, j) of the result has the value
12430 @code{MATRIX(j, i)}, for all i, j.
12431
12432 @item @emph{Standard}:
12433 Fortran 95 and later
12434
12435 @item @emph{Class}:
12436 Transformational function
12437
12438 @item @emph{Syntax}:
12439 @code{RESULT = TRANSPOSE(MATRIX)}
12440
12441 @item @emph{Arguments}:
12442 @multitable @columnfractions .15 .70
12443 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12444 @end multitable
12445
12446 @item @emph{Return value}:
12447 The result has the same type as @var{MATRIX}, and has shape
12448 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12449 @end table
12450
12451
12452
12453 @node TRIM
12454 @section @code{TRIM} --- Remove trailing blank characters of a string
12455 @fnindex TRIM
12456 @cindex string, remove trailing whitespace
12457
12458 @table @asis
12459 @item @emph{Description}:
12460 Removes trailing blank characters of a string.
12461
12462 @item @emph{Standard}:
12463 Fortran 95 and later
12464
12465 @item @emph{Class}:
12466 Transformational function
12467
12468 @item @emph{Syntax}:
12469 @code{RESULT = TRIM(STRING)}
12470
12471 @item @emph{Arguments}:
12472 @multitable @columnfractions .15 .70
12473 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12474 @end multitable
12475
12476 @item @emph{Return value}:
12477 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12478 less the number of trailing blanks.
12479
12480 @item @emph{Example}:
12481 @smallexample
12482 PROGRAM test_trim
12483   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
12484   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
12485 END PROGRAM
12486 @end smallexample
12487
12488 @item @emph{See also}:
12489 @ref{ADJUSTL}, @ref{ADJUSTR}
12490 @end table
12491
12492
12493
12494 @node TTYNAM
12495 @section @code{TTYNAM} --- Get the name of a terminal device.
12496 @fnindex TTYNAM
12497 @cindex system, terminal
12498
12499 @table @asis
12500 @item @emph{Description}:
12501 Get the name of a terminal device. For more information,
12502 see @code{ttyname(3)}.
12503
12504 This intrinsic is provided in both subroutine and function forms;
12505 however, only one form can be used in any given program unit.
12506
12507 @item @emph{Standard}:
12508 GNU extension
12509
12510 @item @emph{Class}:
12511 Subroutine, function
12512
12513 @item @emph{Syntax}:
12514 @multitable @columnfractions .80
12515 @item @code{CALL TTYNAM(UNIT, NAME)}
12516 @item @code{NAME = TTYNAM(UNIT)}
12517 @end multitable
12518
12519 @item @emph{Arguments}:
12520 @multitable @columnfractions .15 .70
12521 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12522 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12523 @end multitable
12524
12525 @item @emph{Example}:
12526 @smallexample
12527 PROGRAM test_ttynam
12528   INTEGER :: unit
12529   DO unit = 1, 10
12530     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12531   END DO
12532 END PROGRAM
12533 @end smallexample
12534
12535 @item @emph{See also}:
12536 @ref{ISATTY}
12537 @end table
12538
12539
12540
12541 @node UBOUND
12542 @section @code{UBOUND} --- Upper dimension bounds of an array
12543 @fnindex UBOUND
12544 @cindex array, upper bound
12545
12546 @table @asis
12547 @item @emph{Description}:
12548 Returns the upper bounds of an array, or a single upper bound
12549 along the @var{DIM} dimension.
12550 @item @emph{Standard}:
12551 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12552
12553 @item @emph{Class}:
12554 Inquiry function
12555
12556 @item @emph{Syntax}:
12557 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12558
12559 @item @emph{Arguments}:
12560 @multitable @columnfractions .15 .70
12561 @item @var{ARRAY} @tab Shall be an array, of any type.
12562 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12563 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12564 expression indicating the kind parameter of the result.
12565 @end multitable
12566
12567 @item @emph{Return value}:
12568 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12569 @var{KIND} is absent, the return value is of default integer kind.
12570 If @var{DIM} is absent, the result is an array of the upper bounds of
12571 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
12572 corresponding to the upper bound of the array along that dimension.  If
12573 @var{ARRAY} is an expression rather than a whole array or array
12574 structure component, or if it has a zero extent along the relevant
12575 dimension, the upper bound is taken to be the number of elements along
12576 the relevant dimension.
12577
12578 @item @emph{See also}:
12579 @ref{LBOUND}, @ref{LCOBOUND}
12580 @end table
12581
12582
12583
12584 @node UCOBOUND
12585 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12586 @fnindex UCOBOUND
12587 @cindex coarray, upper bound
12588
12589 @table @asis
12590 @item @emph{Description}:
12591 Returns the upper cobounds of a coarray, or a single upper cobound
12592 along the @var{DIM} codimension.
12593 @item @emph{Standard}:
12594 Fortran 2008 and later
12595
12596 @item @emph{Class}:
12597 Inquiry function
12598
12599 @item @emph{Syntax}:
12600 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12601
12602 @item @emph{Arguments}:
12603 @multitable @columnfractions .15 .70
12604 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12605 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12606 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12607 expression indicating the kind parameter of the result.
12608 @end multitable
12609
12610 @item @emph{Return value}:
12611 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12612 @var{KIND} is absent, the return value is of default integer kind.
12613 If @var{DIM} is absent, the result is an array of the lower cobounds of
12614 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
12615 corresponding to the lower cobound of the array along that codimension.
12616
12617 @item @emph{See also}:
12618 @ref{LCOBOUND}, @ref{LBOUND}
12619 @end table
12620
12621
12622
12623 @node UMASK
12624 @section @code{UMASK} --- Set the file creation mask
12625 @fnindex UMASK
12626 @cindex file system, file creation mask
12627
12628 @table @asis
12629 @item @emph{Description}:
12630 Sets the file creation mask to @var{MASK}. If called as a function, it
12631 returns the old value. If called as a subroutine and argument @var{OLD}
12632 if it is supplied, it is set to the old value. See @code{umask(2)}.
12633
12634 @item @emph{Standard}:
12635 GNU extension
12636
12637 @item @emph{Class}:
12638 Subroutine, function
12639
12640 @item @emph{Syntax}:
12641 @multitable @columnfractions .80
12642 @item @code{CALL UMASK(MASK [, OLD])}
12643 @item @code{OLD = UMASK(MASK)}
12644 @end multitable
12645
12646 @item @emph{Arguments}:
12647 @multitable @columnfractions .15 .70
12648 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12649 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12650 @code{INTEGER}.
12651 @end multitable
12652
12653 @end table
12654
12655
12656
12657 @node UNLINK
12658 @section @code{UNLINK} --- Remove a file from the file system
12659 @fnindex UNLINK
12660 @cindex file system, remove file
12661
12662 @table @asis
12663 @item @emph{Description}:
12664 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12665 used to mark the end of the name in @var{PATH}; otherwise, trailing
12666 blanks in the file name are ignored.  If the @var{STATUS} argument is
12667 supplied, it contains 0 on success or a nonzero error code upon return;
12668 see @code{unlink(2)}.
12669
12670 This intrinsic is provided in both subroutine and function forms;
12671 however, only one form can be used in any given program unit.
12672
12673 @item @emph{Standard}:
12674 GNU extension
12675
12676 @item @emph{Class}:
12677 Subroutine, function
12678
12679 @item @emph{Syntax}:
12680 @multitable @columnfractions .80
12681 @item @code{CALL UNLINK(PATH [, STATUS])}
12682 @item @code{STATUS = UNLINK(PATH)}
12683 @end multitable
12684
12685 @item @emph{Arguments}:
12686 @multitable @columnfractions .15 .70
12687 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12688 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12689 @end multitable
12690
12691 @item @emph{See also}:
12692 @ref{LINK}, @ref{SYMLNK}
12693 @end table
12694
12695
12696
12697 @node UNPACK
12698 @section @code{UNPACK} --- Unpack an array of rank one into an array
12699 @fnindex UNPACK
12700 @cindex array, unpacking
12701 @cindex array, increase dimension
12702 @cindex array, scatter elements
12703
12704 @table @asis
12705 @item @emph{Description}:
12706 Store the elements of @var{VECTOR} in an array of higher rank.
12707
12708 @item @emph{Standard}:
12709 Fortran 95 and later
12710
12711 @item @emph{Class}:
12712 Transformational function
12713
12714 @item @emph{Syntax}:
12715 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12716
12717 @item @emph{Arguments}:
12718 @multitable @columnfractions .15 .70
12719 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12720 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12721 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
12722 @item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
12723 the same shape as @var{MASK}.
12724 @end multitable
12725
12726 @item @emph{Return value}:
12727 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12728 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12729
12730 @item @emph{Example}:
12731 @smallexample
12732 PROGRAM test_unpack
12733   integer :: vector(2)  = (/1,1/)
12734   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12735   integer :: field(2,2) = 0, unity(2,2)
12736
12737   ! result: unity matrix
12738   unity = unpack(vector, reshape(mask, (/2,2/)), field)
12739 END PROGRAM
12740 @end smallexample
12741
12742 @item @emph{See also}:
12743 @ref{PACK}, @ref{SPREAD}
12744 @end table
12745
12746
12747
12748 @node VERIFY
12749 @section @code{VERIFY} --- Scan a string for characters not a given set
12750 @fnindex VERIFY
12751 @cindex string, find missing set
12752
12753 @table @asis
12754 @item @emph{Description}:
12755 Verifies that all the characters in @var{STRING} belong to the set of
12756 characters in @var{SET}.
12757
12758 If @var{BACK} is either absent or equals @code{FALSE}, this function
12759 returns the position of the leftmost character of @var{STRING} that is
12760 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12761 position is returned. If all characters of @var{STRING} are found in
12762 @var{SET}, the result is zero.
12763
12764 @item @emph{Standard}:
12765 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12766
12767 @item @emph{Class}:
12768 Elemental function
12769
12770 @item @emph{Syntax}:
12771 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12772
12773 @item @emph{Arguments}:
12774 @multitable @columnfractions .15 .70
12775 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12776 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
12777 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
12778 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
12779 expression indicating the kind parameter of the result.
12780 @end multitable
12781
12782 @item @emph{Return value}:
12783 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12784 @var{KIND} is absent, the return value is of default integer kind.
12785
12786 @item @emph{Example}:
12787 @smallexample
12788 PROGRAM test_verify
12789   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
12790   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
12791   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
12792   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
12793   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
12794 END PROGRAM
12795 @end smallexample
12796
12797 @item @emph{See also}:
12798 @ref{SCAN}, @ref{INDEX intrinsic}
12799 @end table
12800
12801
12802
12803 @node XOR
12804 @section @code{XOR} --- Bitwise logical exclusive OR
12805 @fnindex XOR
12806 @cindex bitwise logical exclusive or
12807 @cindex logical exclusive or, bitwise
12808
12809 @table @asis
12810 @item @emph{Description}:
12811 Bitwise logical exclusive or.
12812
12813 This intrinsic routine is provided for backwards compatibility with
12814 GNU Fortran 77.  For integer arguments, programmers should consider
12815 the use of the @ref{IEOR} intrinsic and for logical arguments the
12816 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12817
12818 @item @emph{Standard}:
12819 GNU extension
12820
12821 @item @emph{Class}:
12822 Function
12823
12824 @item @emph{Syntax}:
12825 @code{RESULT = XOR(I, J)}
12826
12827 @item @emph{Arguments}:
12828 @multitable @columnfractions .15 .70
12829 @item @var{I} @tab The type shall be either  a scalar @code{INTEGER}
12830 type or a scalar @code{LOGICAL} type.
12831 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12832 @end multitable
12833
12834 @item @emph{Return value}:
12835 The return type is either a scalar @code{INTEGER} or a scalar
12836 @code{LOGICAL}.  If the kind type parameters differ, then the
12837 smaller kind type is implicitly converted to larger kind, and the
12838 return has the larger kind.
12839
12840 @item @emph{Example}:
12841 @smallexample
12842 PROGRAM test_xor
12843   LOGICAL :: T = .TRUE., F = .FALSE.
12844   INTEGER :: a, b
12845   DATA a / Z'F' /, b / Z'3' /
12846
12847   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12848   WRITE (*,*) XOR(a, b)
12849 END PROGRAM
12850 @end smallexample
12851
12852 @item @emph{See also}:
12853 Fortran 95 elemental function: @ref{IEOR}
12854 @end table
12855
12856
12857
12858 @node Intrinsic Modules
12859 @chapter Intrinsic Modules
12860 @cindex intrinsic Modules
12861
12862 @menu
12863 * ISO_FORTRAN_ENV::
12864 * ISO_C_BINDING::
12865 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12866 @end menu
12867
12868 @node ISO_FORTRAN_ENV
12869 @section @code{ISO_FORTRAN_ENV}
12870 @table @asis
12871 @item @emph{Standard}:
12872 Fortran 2003 and later, except when otherwise noted
12873 @end table
12874
12875 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12876 named constants:
12877
12878 @table @asis
12879 @item @code{ATOMIC_INT_KIND}:
12880 Default-kind integer constant to be used as kind parameter when defining
12881 integer variables used in atomic operations. (Fortran 2008 or later.)
12882
12883 @item @code{ATOMIC_LOGICAL_KIND}:
12884 Default-kind integer constant to be used as kind parameter when defining
12885 logical variables used in atomic operations. (Fortran 2008 or later.)
12886
12887 @item @code{CHARACTER_KINDS}:
12888 Default-kind integer constant array of rank one containing the supported kind
12889 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12890
12891 @item @code{CHARACTER_STORAGE_SIZE}:
12892 Size in bits of the character storage unit.
12893
12894 @item @code{ERROR_UNIT}:
12895 Identifies the preconnected unit used for error reporting.
12896
12897 @item @code{FILE_STORAGE_SIZE}:
12898 Size in bits of the file-storage unit.
12899
12900 @item @code{INPUT_UNIT}:
12901 Identifies the preconnected unit identified by the asterisk
12902 (@code{*}) in @code{READ} statement.
12903
12904 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12905 Kind type parameters to specify an INTEGER type with a storage
12906 size of 16, 32, and 64 bits. It is negative if a target platform
12907 does not support the particular kind. (Fortran 2008 or later.)
12908
12909 @item @code{INTEGER_KINDS}:
12910 Default-kind integer constant array of rank one containing the supported kind
12911 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12912
12913 @item @code{IOSTAT_END}:
12914 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12915 an input/output statement if an end-of-file condition occurred.
12916
12917 @item @code{IOSTAT_EOR}:
12918 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12919 an input/output statement if an end-of-record condition occurred.
12920
12921 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12922 Scalar default-integer constant, used by @code{INQUIRE} for the
12923 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12924 internal unit. (Fortran 2008 or later.)
12925
12926 @item @code{NUMERIC_STORAGE_SIZE}:
12927 The size in bits of the numeric storage unit.
12928
12929 @item @code{LOGICAL_KINDS}:
12930 Default-kind integer constant array of rank one containing the supported kind
12931 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12932
12933 @item @code{OUTPUT_UNIT}:
12934 Identifies the preconnected unit identified by the asterisk
12935 (@code{*}) in @code{WRITE} statement.
12936
12937 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12938 Kind type parameters to specify a REAL type with a storage
12939 size of 32, 64, and 128 bits. It is negative if a target platform
12940 does not support the particular kind. (Fortran 2008 or later.)
12941
12942 @item @code{REAL_KINDS}:
12943 Default-kind integer constant array of rank one containing the supported kind
12944 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12945
12946 @item @code{STAT_LOCKED}:
12947 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12948 denote that the lock variable is locked by the executing image. (Fortran 2008
12949 or later.)
12950
12951 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12952 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12953 denote that the lock variable is locked by another image. (Fortran 2008 or
12954 later.)
12955
12956 @item @code{STAT_STOPPED_IMAGE}:
12957 Positive, scalar default-integer constant used as STAT= return value if the
12958 argument in the statement requires synchronisation with an image, which has
12959 initiated the termination of the execution. (Fortran 2008 or later.)
12960
12961 @item @code{STAT_UNLOCKED}:
12962 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12963 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12964 @end table
12965
12966 The module provides the following derived type:
12967
12968 @table @asis
12969 @item @code{LOCK_TYPE}:
12970 Derived type with private components to be use with the @code{LOCK} and
12971 @code{UNLOCK} statement. A variable of its type has to be always declared
12972 as coarray and may not appear in a variable-definition context.
12973 (Fortran 2008 or later.)
12974 @end table
12975
12976 The module also provides the following intrinsic procedures:
12977 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12978
12979
12980
12981 @node ISO_C_BINDING
12982 @section @code{ISO_C_BINDING}
12983 @table @asis
12984 @item @emph{Standard}:
12985 Fortran 2003 and later, GNU extensions
12986 @end table
12987
12988 The following intrinsic procedures are provided by the module; their
12989 definition can be found in the section Intrinsic Procedures of this
12990 manual.
12991
12992 @table @asis
12993 @item @code{C_ASSOCIATED}
12994 @item @code{C_F_POINTER}
12995 @item @code{C_F_PROCPOINTER}
12996 @item @code{C_FUNLOC}
12997 @item @code{C_LOC}
12998 @item @code{C_SIZEOF}
12999 @end table
13000 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13001 @c don't really know why.
13002
13003 The @code{ISO_C_BINDING} module provides the following named constants of
13004 type default integer, which can be used as KIND type parameters.
13005
13006 In addition to the integer named constants required by the Fortran 2003
13007 standard, GNU Fortran provides as an extension named constants for the
13008 128-bit integer types supported by the C compiler: @code{C_INT128_T,
13009 C_INT_LEAST128_T, C_INT_FAST128_T}.
13010
13011 @multitable @columnfractions .15 .35 .35 .35
13012 @item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
13013 @item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
13014 @item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
13015 @item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
13016 @item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
13017 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
13018 @item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
13019 @item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
13020 @item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
13021 @item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
13022 @item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
13023 @item @code{INTEGER}@tab @code{C_INT128_T}      @tab @code{int128_t}                      @tab Ext.
13024 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
13025 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13026 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13027 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13028 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t}                @tab Ext.
13029 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}   @tab @code{int_fast8_t}
13030 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}  @tab @code{int_fast16_t}
13031 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}  @tab @code{int_fast32_t}
13032 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}  @tab @code{int_fast64_t}
13033 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t}                 @tab Ext.
13034 @item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
13035 @item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
13036 @item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
13037 @item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
13038 @item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
13039 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13040 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13041 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13042 @item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
13043 @item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
13044 @end multitable
13045
13046 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13047 are defined.
13048
13049 @multitable @columnfractions .20 .45 .15
13050 @item Name                     @tab C definition    @tab Value
13051 @item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
13052 @item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
13053 @item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
13054 @item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
13055 @item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
13056 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13057 @item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
13058 @item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
13059 @end multitable
13060
13061 Moreover, the following two named constants are defined:
13062
13063 @multitable @columnfractions .20 .80
13064 @item Name                 @tab Type
13065 @item @code{C_NULL_PTR}    @tab @code{C_PTR}
13066 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13067 @end multitable
13068
13069 Both are equivalent to the value @code{NULL} in C.
13070
13071 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13072 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13073 @table @asis
13074 @item @emph{Standard}:
13075 OpenMP Application Program Interface v3.1
13076 @end table
13077
13078
13079 The OpenMP Fortran runtime library routines are provided both in
13080 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13081 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13082 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13083 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13084 the named constants defined in the modules are listed
13085 below.
13086
13087 For details refer to the actual
13088 @uref{http://www.openmp.org/mp-documents/spec31.pdf,
13089 OpenMP Application Program Interface v3.1}.
13090
13091 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13092 named constants:
13093
13094 @table @asis
13095 @item @code{omp_lock_kind}
13096 @item @code{omp_nest_lock_kind}
13097 @item @code{omp_sched_kind}
13098 @end table
13099
13100 @code{OMP_LIB} provides the scalar default-integer
13101 named constant @code{openmp_version} with a value of the form
13102 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13103 of the OpenMP version; for OpenMP v3.1 the value is @code{201107}.
13104
13105 And the following scalar integer named constants of the
13106 kind @code{omp_sched_kind}:
13107
13108 @table @asis
13109 @item @code{omp_sched_static}
13110 @item @code{omp_sched_dynamic}
13111 @item @code{omp_sched_guided}
13112 @item @code{omp_sched_auto}
13113 @end table