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} or a BOZ constant.
3798 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3799 If both @var{I} and @var{J} have integer type, then they shall have
3800 the same kind type parameter. @var{I} and @var{J} shall not both be
3801 BOZ constants.
3802 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3803 be nonnegative.  If @var{I} is not a BOZ constant, then @var{SHIFT}
3804 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3805 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3806 @end multitable
3807
3808 @item @emph{Return value}:
3809 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3810 as if by the intrinsic function @code{INT} to an integer type with the
3811 kind type parameter of the other.
3812
3813 @item @emph{See also}:
3814 @ref{DSHIFTR}
3815 @end table
3816
3817
3818 @node DSHIFTR
3819 @section @code{DSHIFTR} --- Combined right shift
3820 @fnindex DSHIFTR
3821 @cindex right shift, combined
3822 @cindex shift, right
3823
3824 @table @asis
3825 @item @emph{Description}:
3826 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3827 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3828 bits of @var{I}, and the remaining bits are the leftmost bits of
3829 @var{J}.
3830
3831 @item @emph{Standard}:
3832 Fortran 2008 and later
3833
3834 @item @emph{Class}:
3835 Elemental function
3836
3837 @item @emph{Syntax}:
3838 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3839
3840 @item @emph{Arguments}:
3841 @multitable @columnfractions .15 .70
3842 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3843 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3844 If both @var{I} and @var{J} have integer type, then they shall have
3845 the same kind type parameter. @var{I} and @var{J} shall not both be
3846 BOZ constants.
3847 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3848 be nonnegative.  If @var{I} is not a BOZ constant, then @var{SHIFT}
3849 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3850 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3851 @end multitable
3852
3853 @item @emph{Return value}:
3854 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3855 as if by the intrinsic function @code{INT} to an integer type with the
3856 kind type parameter of the other.
3857
3858 @item @emph{See also}:
3859 @ref{DSHIFTL}
3860 @end table
3861
3862
3863 @node DTIME
3864 @section @code{DTIME} --- Execution time subroutine (or function)
3865 @fnindex DTIME
3866 @cindex time, elapsed
3867 @cindex elapsed time
3868
3869 @table @asis
3870 @item @emph{Description}:
3871 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3872 since the start of the process's execution in @var{TIME}.  @var{VALUES}
3873 returns the user and system components of this time in @code{VALUES(1)} and
3874 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3875 VALUES(2)}.
3876
3877 Subsequent invocations of @code{DTIME} return values accumulated since the
3878 previous invocation.
3879
3880 On some systems, the underlying timings are represented using types with
3881 sufficiently small limits that overflows (wrap around) are possible, such as
3882 32-bit types. Therefore, the values returned by this intrinsic might be, or
3883 become, negative, or numerically less than previous values, during a single
3884 run of the compiled program.
3885
3886 Please note, that this implementation is thread safe if used within OpenMP
3887 directives, i.e., its state will be consistent while called from multiple
3888 threads. However, if @code{DTIME} is called from multiple threads, the result
3889 is still the time since the last invocation. This may not give the intended
3890 results. If possible, use @code{CPU_TIME} instead.
3891
3892 This intrinsic is provided in both subroutine and function forms; however,
3893 only one form can be used in any given program unit.
3894
3895 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3896
3897 @multitable @columnfractions .15 .30 .40
3898 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3899 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3900 @item @tab @code{TIME}: @tab Run time since start in seconds.
3901 @end multitable
3902
3903 @item @emph{Standard}:
3904 GNU extension
3905
3906 @item @emph{Class}:
3907 Subroutine, function
3908
3909 @item @emph{Syntax}:
3910 @multitable @columnfractions .80
3911 @item @code{CALL DTIME(VALUES, TIME)}.
3912 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3913 @end multitable
3914
3915 @item @emph{Arguments}:
3916 @multitable @columnfractions .15 .70
3917 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3918 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3919 @end multitable
3920
3921 @item @emph{Return value}:
3922 Elapsed time in seconds since the last invocation or since the start of program
3923 execution if not called before.
3924
3925 @item @emph{Example}:
3926 @smallexample
3927 program test_dtime
3928     integer(8) :: i, j
3929     real, dimension(2) :: tarray
3930     real :: result
3931     call dtime(tarray, result)
3932     print *, result
3933     print *, tarray(1)
3934     print *, tarray(2)
3935     do i=1,100000000    ! Just a delay
3936         j = i * i - i
3937     end do
3938     call dtime(tarray, result)
3939     print *, result
3940     print *, tarray(1)
3941     print *, tarray(2)
3942 end program test_dtime
3943 @end smallexample
3944
3945 @item @emph{See also}:
3946 @ref{CPU_TIME}
3947
3948 @end table
3949
3950
3951
3952 @node EOSHIFT
3953 @section @code{EOSHIFT} --- End-off shift elements of an array
3954 @fnindex EOSHIFT
3955 @cindex array, shift
3956
3957 @table @asis
3958 @item @emph{Description}:
3959 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3960 elements of @var{ARRAY} along the dimension of @var{DIM}.  If @var{DIM} is
3961 omitted it is taken to be @code{1}.  @var{DIM} is a scalar of type
3962 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3963 rank of @var{ARRAY}.  If the rank of @var{ARRAY} is one, then all elements of
3964 @var{ARRAY} are shifted by @var{SHIFT} places.  If rank is greater than one,
3965 then all complete rank one sections of @var{ARRAY} along the given dimension are
3966 shifted.  Elements shifted out one end of each rank one section are dropped.  If
3967 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3968 is copied back in the other end.  If @var{BOUNDARY} is not present then the
3969 following are copied in depending on the type of @var{ARRAY}.
3970
3971 @multitable @columnfractions .15 .80
3972 @item @emph{Array Type} @tab @emph{Boundary Value}
3973 @item Numeric  @tab 0 of the type and kind of @var{ARRAY}.
3974 @item Logical  @tab @code{.FALSE.}.
3975 @item Character(@var{len}) @tab @var{len} blanks.
3976 @end multitable
3977
3978 @item @emph{Standard}:
3979 Fortran 95 and later
3980
3981 @item @emph{Class}:
3982 Transformational function
3983
3984 @item @emph{Syntax}:
3985 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3986
3987 @item @emph{Arguments}:
3988 @multitable @columnfractions .15 .70
3989 @item @var{ARRAY}  @tab May be any type, not scalar.
3990 @item @var{SHIFT}  @tab The type shall be @code{INTEGER}.
3991 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3992 @item @var{DIM}    @tab The type shall be @code{INTEGER}.
3993 @end multitable
3994
3995 @item @emph{Return value}:
3996 Returns an array of same type and rank as the @var{ARRAY} argument.
3997
3998 @item @emph{Example}:
3999 @smallexample
4000 program test_eoshift
4001     integer, dimension(3,3) :: a
4002     a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4003     print '(3i3)', a(1,:)
4004     print '(3i3)', a(2,:)
4005     print '(3i3)', a(3,:)
4006     a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4007     print *
4008     print '(3i3)', a(1,:)
4009     print '(3i3)', a(2,:)
4010     print '(3i3)', a(3,:)
4011 end program test_eoshift
4012 @end smallexample
4013 @end table
4014
4015
4016
4017 @node EPSILON
4018 @section @code{EPSILON} --- Epsilon function
4019 @fnindex EPSILON
4020 @cindex model representation, epsilon
4021
4022 @table @asis
4023 @item @emph{Description}:
4024 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4025 as @var{X} such that @math{1 + E > 1}.
4026
4027 @item @emph{Standard}:
4028 Fortran 95 and later
4029
4030 @item @emph{Class}:
4031 Inquiry function
4032
4033 @item @emph{Syntax}:
4034 @code{RESULT = EPSILON(X)}
4035
4036 @item @emph{Arguments}:
4037 @multitable @columnfractions .15 .70
4038 @item @var{X} @tab The type shall be @code{REAL}.
4039 @end multitable
4040
4041 @item @emph{Return value}:
4042 The return value is of same type as the argument.
4043
4044 @item @emph{Example}:
4045 @smallexample
4046 program test_epsilon
4047     real :: x = 3.143
4048     real(8) :: y = 2.33
4049     print *, EPSILON(x)
4050     print *, EPSILON(y)
4051 end program test_epsilon
4052 @end smallexample
4053 @end table
4054
4055
4056
4057 @node ERF
4058 @section @code{ERF} --- Error function
4059 @fnindex ERF
4060 @cindex error function
4061
4062 @table @asis
4063 @item @emph{Description}:
4064 @code{ERF(X)} computes the error function of @var{X}.
4065
4066 @item @emph{Standard}:
4067 Fortran 2008 and later
4068
4069 @item @emph{Class}:
4070 Elemental function
4071
4072 @item @emph{Syntax}:
4073 @code{RESULT = ERF(X)}
4074
4075 @item @emph{Arguments}:
4076 @multitable @columnfractions .15 .70
4077 @item @var{X} @tab The type shall be @code{REAL}.
4078 @end multitable
4079
4080 @item @emph{Return value}:
4081 The return value is of type @code{REAL}, of the same kind as
4082 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4083
4084 @item @emph{Example}:
4085 @smallexample
4086 program test_erf
4087   real(8) :: x = 0.17_8
4088   x = erf(x)
4089 end program test_erf
4090 @end smallexample
4091
4092 @item @emph{Specific names}:
4093 @multitable @columnfractions .20 .20 .20 .25
4094 @item Name            @tab Argument          @tab Return type       @tab Standard
4095 @item @code{DERF(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
4096 @end multitable
4097 @end table
4098
4099
4100
4101 @node ERFC
4102 @section @code{ERFC} --- Error function
4103 @fnindex ERFC
4104 @cindex error function, complementary
4105
4106 @table @asis
4107 @item @emph{Description}:
4108 @code{ERFC(X)} computes the complementary error function of @var{X}.
4109
4110 @item @emph{Standard}:
4111 Fortran 2008 and later
4112
4113 @item @emph{Class}:
4114 Elemental function
4115
4116 @item @emph{Syntax}:
4117 @code{RESULT = ERFC(X)}
4118
4119 @item @emph{Arguments}:
4120 @multitable @columnfractions .15 .70
4121 @item @var{X} @tab The type shall be @code{REAL}.
4122 @end multitable
4123
4124 @item @emph{Return value}:
4125 The return value is of type @code{REAL} and of the same kind as @var{X}.
4126 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4127
4128 @item @emph{Example}:
4129 @smallexample
4130 program test_erfc
4131   real(8) :: x = 0.17_8
4132   x = erfc(x)
4133 end program test_erfc
4134 @end smallexample
4135
4136 @item @emph{Specific names}:
4137 @multitable @columnfractions .20 .20 .20 .25
4138 @item Name            @tab Argument          @tab Return type       @tab Standard
4139 @item @code{DERFC(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab GNU extension
4140 @end multitable
4141 @end table
4142
4143
4144
4145 @node ERFC_SCALED
4146 @section @code{ERFC_SCALED} --- Error function
4147 @fnindex ERFC_SCALED
4148 @cindex error function, complementary, exponentially-scaled
4149
4150 @table @asis
4151 @item @emph{Description}:
4152 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4153 error function of @var{X}.
4154
4155 @item @emph{Standard}:
4156 Fortran 2008 and later
4157
4158 @item @emph{Class}:
4159 Elemental function
4160
4161 @item @emph{Syntax}:
4162 @code{RESULT = ERFC_SCALED(X)}
4163
4164 @item @emph{Arguments}:
4165 @multitable @columnfractions .15 .70
4166 @item @var{X} @tab The type shall be @code{REAL}.
4167 @end multitable
4168
4169 @item @emph{Return value}:
4170 The return value is of type @code{REAL} and of the same kind as @var{X}.
4171
4172 @item @emph{Example}:
4173 @smallexample
4174 program test_erfc_scaled
4175   real(8) :: x = 0.17_8
4176   x = erfc_scaled(x)
4177 end program test_erfc_scaled
4178 @end smallexample
4179 @end table
4180
4181
4182
4183 @node ETIME
4184 @section @code{ETIME} --- Execution time subroutine (or function)
4185 @fnindex ETIME
4186 @cindex time, elapsed
4187
4188 @table @asis
4189 @item @emph{Description}:
4190 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4191 since the start of the process's execution in @var{TIME}.  @var{VALUES}
4192 returns the user and system components of this time in @code{VALUES(1)} and
4193 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4194
4195 On some systems, the underlying timings are represented using types with
4196 sufficiently small limits that overflows (wrap around) are possible, such as
4197 32-bit types. Therefore, the values returned by this intrinsic might be, or
4198 become, negative, or numerically less than previous values, during a single
4199 run of the compiled program.
4200
4201 This intrinsic is provided in both subroutine and function forms; however,
4202 only one form can be used in any given program unit.
4203
4204 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4205
4206 @multitable @columnfractions .15 .30 .60
4207 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4208 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4209 @item @tab @code{TIME}: @tab Run time since start in seconds.
4210 @end multitable
4211
4212 @item @emph{Standard}:
4213 GNU extension
4214
4215 @item @emph{Class}:
4216 Subroutine, function
4217
4218 @item @emph{Syntax}:
4219 @multitable @columnfractions .80
4220 @item @code{CALL ETIME(VALUES, TIME)}.
4221 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4222 @end multitable
4223
4224 @item @emph{Arguments}:
4225 @multitable @columnfractions .15 .70
4226 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4227 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4228 @end multitable
4229
4230 @item @emph{Return value}:
4231 Elapsed time in seconds since the start of program execution.
4232
4233 @item @emph{Example}:
4234 @smallexample
4235 program test_etime
4236     integer(8) :: i, j
4237     real, dimension(2) :: tarray
4238     real :: result
4239     call ETIME(tarray, result)
4240     print *, result
4241     print *, tarray(1)
4242     print *, tarray(2)
4243     do i=1,100000000    ! Just a delay
4244         j = i * i - i
4245     end do
4246     call ETIME(tarray, result)
4247     print *, result
4248     print *, tarray(1)
4249     print *, tarray(2)
4250 end program test_etime
4251 @end smallexample
4252
4253 @item @emph{See also}:
4254 @ref{CPU_TIME}
4255
4256 @end table
4257
4258
4259
4260 @node EXECUTE_COMMAND_LINE
4261 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4262 @fnindex EXECUTE_COMMAND_LINE
4263 @cindex system, system call
4264 @cindex command line
4265
4266 @table @asis
4267 @item @emph{Description}:
4268 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4269 asynchronously.
4270
4271 The @code{COMMAND} argument is passed to the shell and executed, using
4272 the C library's @code{system} call.  (The shell is @code{sh} on Unix
4273 systems, and @code{cmd.exe} on Windows.)  If @code{WAIT} is present
4274 and has the value false, the execution of the command is asynchronous
4275 if the system supports it; otherwise, the command is executed
4276 synchronously.
4277
4278 The three last arguments allow the user to get status information.  After
4279 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4280 the command, as returned by @code{system}.  @code{CMDSTAT} is set to zero
4281 if the command line was executed (whatever its exit status was).
4282 @code{CMDMSG} is assigned an error message if an error has occurred.
4283
4284 Note that the @code{system} function need not be thread-safe. It is
4285 the responsibility of the user to ensure that @code{system} is not
4286 called concurrently.
4287
4288 @item @emph{Standard}:
4289 Fortran 2008 and later
4290
4291 @item @emph{Class}:
4292 Subroutine
4293
4294 @item @emph{Syntax}:
4295 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4296
4297 @item @emph{Arguments}:
4298 @multitable @columnfractions .15 .70
4299 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4300 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4301 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4302 default kind.
4303 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4304 default kind.
4305 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4306 default kind.
4307 @end multitable
4308
4309 @item @emph{Example}:
4310 @smallexample
4311 program test_exec
4312   integer :: i
4313
4314   call execute_command_line ("external_prog.exe", exitstat=i)
4315   print *, "Exit status of external_prog.exe was ", i
4316
4317   call execute_command_line ("reindex_files.exe", wait=.false.)
4318   print *, "Now reindexing files in the background"
4319
4320 end program test_exec
4321 @end smallexample
4322
4323
4324 @item @emph{Note}:
4325
4326 Because this intrinsic is implemented in terms of the @code{system}
4327 function call, its behavior with respect to signaling is processor
4328 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4329 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4330 such, if the parent process is terminated, the child process might not be
4331 terminated alongside.
4332
4333
4334 @item @emph{See also}:
4335 @ref{SYSTEM}
4336 @end table
4337
4338
4339
4340 @node EXIT
4341 @section @code{EXIT} --- Exit the program with status.
4342 @fnindex EXIT
4343 @cindex program termination
4344 @cindex terminate program
4345
4346 @table @asis
4347 @item @emph{Description}:
4348 @code{EXIT} causes immediate termination of the program with status.  If status
4349 is omitted it returns the canonical @emph{success} for the system.  All Fortran
4350 I/O units are closed.
4351
4352 @item @emph{Standard}:
4353 GNU extension
4354
4355 @item @emph{Class}:
4356 Subroutine
4357
4358 @item @emph{Syntax}:
4359 @code{CALL EXIT([STATUS])}
4360
4361 @item @emph{Arguments}:
4362 @multitable @columnfractions .15 .70
4363 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4364 @end multitable
4365
4366 @item @emph{Return value}:
4367 @code{STATUS} is passed to the parent process on exit.
4368
4369 @item @emph{Example}:
4370 @smallexample
4371 program test_exit
4372   integer :: STATUS = 0
4373   print *, 'This program is going to exit.'
4374   call EXIT(STATUS)
4375 end program test_exit
4376 @end smallexample
4377
4378 @item @emph{See also}:
4379 @ref{ABORT}, @ref{KILL}
4380 @end table
4381
4382
4383
4384 @node EXP
4385 @section @code{EXP} --- Exponential function
4386 @fnindex EXP
4387 @fnindex DEXP
4388 @fnindex CEXP
4389 @fnindex ZEXP
4390 @fnindex CDEXP
4391 @cindex exponential function
4392 @cindex logarithm function, inverse
4393
4394 @table @asis
4395 @item @emph{Description}:
4396 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4397
4398 @item @emph{Standard}:
4399 Fortran 77 and later, has overloads that are GNU extensions
4400
4401 @item @emph{Class}:
4402 Elemental function
4403
4404 @item @emph{Syntax}:
4405 @code{RESULT = EXP(X)}
4406
4407 @item @emph{Arguments}:
4408 @multitable @columnfractions .15 .70
4409 @item @var{X} @tab The type shall be @code{REAL} or
4410 @code{COMPLEX}.
4411 @end multitable
4412
4413 @item @emph{Return value}:
4414 The return value has same type and kind as @var{X}.
4415
4416 @item @emph{Example}:
4417 @smallexample
4418 program test_exp
4419   real :: x = 1.0
4420   x = exp(x)
4421 end program test_exp
4422 @end smallexample
4423
4424 @item @emph{Specific names}:
4425 @multitable @columnfractions .20 .20 .20 .25
4426 @item Name            @tab Argument             @tab Return type         @tab Standard
4427 @item @code{EXP(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}      @tab Fortran 77 and later
4428 @item @code{DEXP(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}      @tab Fortran 77 and later
4429 @item @code{CEXP(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}   @tab Fortran 77 and later
4430 @item @code{ZEXP(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4431 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}   @tab GNU extension
4432 @end multitable
4433 @end table
4434
4435
4436
4437 @node EXPONENT
4438 @section @code{EXPONENT} --- Exponent function
4439 @fnindex EXPONENT
4440 @cindex real number, exponent
4441 @cindex floating point, exponent
4442
4443 @table @asis
4444 @item @emph{Description}:
4445 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4446 is zero the value returned is zero.
4447
4448 @item @emph{Standard}:
4449 Fortran 95 and later
4450
4451 @item @emph{Class}:
4452 Elemental function
4453
4454 @item @emph{Syntax}:
4455 @code{RESULT = EXPONENT(X)}
4456
4457 @item @emph{Arguments}:
4458 @multitable @columnfractions .15 .70
4459 @item @var{X} @tab The type shall be @code{REAL}.
4460 @end multitable
4461
4462 @item @emph{Return value}:
4463 The return value is of type default @code{INTEGER}.
4464
4465 @item @emph{Example}:
4466 @smallexample
4467 program test_exponent
4468   real :: x = 1.0
4469   integer :: i
4470   i = exponent(x)
4471   print *, i
4472   print *, exponent(0.0)
4473 end program test_exponent
4474 @end smallexample
4475 @end table
4476
4477
4478
4479 @node EXTENDS_TYPE_OF
4480 @section @code{EXTENDS_TYPE_OF} ---  Query dynamic type for extension
4481 @fnindex EXTENDS_TYPE_OF
4482
4483 @table @asis
4484 @item @emph{Description}:
4485 Query dynamic type for extension.
4486
4487 @item @emph{Standard}:
4488 Fortran 2003 and later
4489
4490 @item @emph{Class}:
4491 Inquiry function
4492
4493 @item @emph{Syntax}:
4494 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4495
4496 @item @emph{Arguments}:
4497 @multitable @columnfractions .15 .70
4498 @item @var{A} @tab Shall be an object of extensible declared type or
4499 unlimited polymorphic.
4500 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4501 unlimited polymorphic.
4502 @end multitable
4503
4504 @item @emph{Return value}:
4505 The return value is a scalar of type default logical. It is true if and only if
4506 the dynamic type of A is an extension type of the dynamic type of MOLD.
4507
4508
4509 @item @emph{See also}:
4510 @ref{SAME_TYPE_AS}
4511 @end table
4512
4513
4514
4515 @node FDATE
4516 @section @code{FDATE} --- Get the current time as a string
4517 @fnindex FDATE
4518 @cindex time, current
4519 @cindex current time
4520 @cindex date, current
4521 @cindex current date
4522
4523 @table @asis
4524 @item @emph{Description}:
4525 @code{FDATE(DATE)} returns the current date (using the same format as
4526 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4527 TIME())}.
4528
4529 This intrinsic is provided in both subroutine and function forms; however,
4530 only one form can be used in any given program unit.
4531
4532 @item @emph{Standard}:
4533 GNU extension
4534
4535 @item @emph{Class}:
4536 Subroutine, function
4537
4538 @item @emph{Syntax}:
4539 @multitable @columnfractions .80
4540 @item @code{CALL FDATE(DATE)}.
4541 @item @code{DATE = FDATE()}.
4542 @end multitable
4543
4544 @item @emph{Arguments}:
4545 @multitable @columnfractions .15 .70
4546 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4547 default kind. It is an @code{INTENT(OUT)} argument.  If the length of
4548 this variable is too short for the date and time string to fit
4549 completely, it will be blank on procedure return.
4550 @end multitable
4551
4552 @item @emph{Return value}:
4553 The current date and time as a string.
4554
4555 @item @emph{Example}:
4556 @smallexample
4557 program test_fdate
4558     integer(8) :: i, j
4559     character(len=30) :: date
4560     call fdate(date)
4561     print *, 'Program started on ', date
4562     do i = 1, 100000000 ! Just a delay
4563         j = i * i - i
4564     end do
4565     call fdate(date)
4566     print *, 'Program ended on ', date
4567 end program test_fdate
4568 @end smallexample
4569
4570 @item @emph{See also}:
4571 @ref{DATE_AND_TIME}, @ref{CTIME}
4572 @end table
4573
4574
4575 @node FGET
4576 @section @code{FGET} --- Read a single character in stream mode from stdin
4577 @fnindex FGET
4578 @cindex read character, stream mode
4579 @cindex stream mode, read character
4580 @cindex file operation, read character
4581
4582 @table @asis
4583 @item @emph{Description}:
4584 Read a single character in stream mode from stdin by bypassing normal
4585 formatted output. Stream I/O should not be mixed with normal record-oriented
4586 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4587
4588 This intrinsic is provided in both subroutine and function forms; however,
4589 only one form can be used in any given program unit.
4590
4591 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4592 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4593 Programmers should consider the use of new stream IO feature in new code
4594 for future portability. See also @ref{Fortran 2003 status}.
4595
4596 @item @emph{Standard}:
4597 GNU extension
4598
4599 @item @emph{Class}:
4600 Subroutine, function
4601
4602 @item @emph{Syntax}:
4603 @multitable @columnfractions .80
4604 @item @code{CALL FGET(C [, STATUS])}
4605 @item @code{STATUS = FGET(C)}
4606 @end multitable
4607
4608 @item @emph{Arguments}:
4609 @multitable @columnfractions .15 .70
4610 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4611 kind.
4612 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4613 Returns 0 on success, -1 on end-of-file, and a system specific positive
4614 error code otherwise.
4615 @end multitable
4616
4617 @item @emph{Example}:
4618 @smallexample
4619 PROGRAM test_fget
4620   INTEGER, PARAMETER :: strlen = 100
4621   INTEGER :: status, i = 1
4622   CHARACTER(len=strlen) :: str = ""
4623
4624   WRITE (*,*) 'Enter text:'
4625   DO
4626     CALL fget(str(i:i), status)
4627     if (status /= 0 .OR. i > strlen) exit
4628     i = i + 1
4629   END DO
4630   WRITE (*,*) TRIM(str)
4631 END PROGRAM
4632 @end smallexample
4633
4634 @item @emph{See also}:
4635 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4636 @end table
4637
4638
4639
4640 @node FGETC
4641 @section @code{FGETC} --- Read a single character in stream mode
4642 @fnindex FGETC
4643 @cindex read character, stream mode
4644 @cindex stream mode, read character
4645 @cindex file operation, read character
4646
4647 @table @asis
4648 @item @emph{Description}:
4649 Read a single character in stream mode by bypassing normal formatted output.
4650 Stream I/O should not be mixed with normal record-oriented (formatted or
4651 unformatted) I/O on the same unit; the results are unpredictable.
4652
4653 This intrinsic is provided in both subroutine and function forms; however,
4654 only one form can be used in any given program unit.
4655
4656 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4657 with @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4658 Programmers should consider the use of new stream IO feature in new code
4659 for future portability. See also @ref{Fortran 2003 status}.
4660
4661 @item @emph{Standard}:
4662 GNU extension
4663
4664 @item @emph{Class}:
4665 Subroutine, function
4666
4667 @item @emph{Syntax}:
4668 @multitable @columnfractions .80
4669 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4670 @item @code{STATUS = FGETC(UNIT, C)}
4671 @end multitable
4672
4673 @item @emph{Arguments}:
4674 @multitable @columnfractions .15 .70
4675 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4676 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4677 kind.
4678 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4679 Returns 0 on success, -1 on end-of-file and a system specific positive
4680 error code otherwise.
4681 @end multitable
4682
4683 @item @emph{Example}:
4684 @smallexample
4685 PROGRAM test_fgetc
4686   INTEGER :: fd = 42, status
4687   CHARACTER :: c
4688
4689   OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4690   DO
4691     CALL fgetc(fd, c, status)
4692     IF (status /= 0) EXIT
4693     call fput(c)
4694   END DO
4695   CLOSE(UNIT=fd)
4696 END PROGRAM
4697 @end smallexample
4698
4699 @item @emph{See also}:
4700 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4701 @end table
4702
4703
4704
4705 @node FLOOR
4706 @section @code{FLOOR} --- Integer floor function
4707 @fnindex FLOOR
4708 @cindex floor
4709 @cindex rounding, floor
4710
4711 @table @asis
4712 @item @emph{Description}:
4713 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4714
4715 @item @emph{Standard}:
4716 Fortran 95 and later
4717
4718 @item @emph{Class}:
4719 Elemental function
4720
4721 @item @emph{Syntax}:
4722 @code{RESULT = FLOOR(A [, KIND])}
4723
4724 @item @emph{Arguments}:
4725 @multitable @columnfractions .15 .70
4726 @item @var{A} @tab The type shall be @code{REAL}.
4727 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4728 expression indicating the kind parameter of the result.
4729 @end multitable
4730
4731 @item @emph{Return value}:
4732 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4733 and of default-kind @code{INTEGER} otherwise.
4734
4735 @item @emph{Example}:
4736 @smallexample
4737 program test_floor
4738     real :: x = 63.29
4739     real :: y = -63.59
4740     print *, floor(x) ! returns 63
4741     print *, floor(y) ! returns -64
4742 end program test_floor
4743 @end smallexample
4744
4745 @item @emph{See also}:
4746 @ref{CEILING}, @ref{NINT}
4747
4748 @end table
4749
4750
4751
4752 @node FLUSH
4753 @section @code{FLUSH} --- Flush I/O unit(s)
4754 @fnindex FLUSH
4755 @cindex file operation, flush
4756
4757 @table @asis
4758 @item @emph{Description}:
4759 Flushes Fortran unit(s) currently open for output. Without the optional
4760 argument, all units are flushed, otherwise just the unit specified.
4761
4762 @item @emph{Standard}:
4763 GNU extension
4764
4765 @item @emph{Class}:
4766 Subroutine
4767
4768 @item @emph{Syntax}:
4769 @code{CALL FLUSH(UNIT)}
4770
4771 @item @emph{Arguments}:
4772 @multitable @columnfractions .15 .70
4773 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4774 @end multitable
4775
4776 @item @emph{Note}:
4777 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4778 statement that should be preferred over the @code{FLUSH} intrinsic.
4779
4780 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4781 have identical effect: they flush the runtime library's I/O buffer so
4782 that the data becomes visible to other processes. This does not guarantee
4783 that the data is committed to disk.
4784
4785 On POSIX systems, you can request that all data is transferred  to  the
4786 storage device by calling the @code{fsync} function, with the POSIX file
4787 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4788 @code{FNUM}). The following example shows how:
4789
4790 @smallexample
4791   ! Declare the interface for POSIX fsync function
4792   interface
4793     function fsync (fd) bind(c,name="fsync")
4794     use iso_c_binding, only: c_int
4795       integer(c_int), value :: fd
4796       integer(c_int) :: fsync
4797     end function fsync
4798   end interface
4799
4800   ! Variable declaration
4801   integer :: ret
4802
4803   ! Opening unit 10
4804   open (10,file="foo")
4805
4806   ! ...
4807   ! Perform I/O on unit 10
4808   ! ...
4809
4810   ! Flush and sync
4811   flush(10)
4812   ret = fsync(fnum(10))
4813
4814   ! Handle possible error
4815   if (ret /= 0) stop "Error calling FSYNC"
4816 @end smallexample
4817
4818 @end table
4819
4820
4821
4822 @node FNUM
4823 @section @code{FNUM} --- File number function
4824 @fnindex FNUM
4825 @cindex file operation, file number
4826
4827 @table @asis
4828 @item @emph{Description}:
4829 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4830 open Fortran I/O unit @code{UNIT}.
4831
4832 @item @emph{Standard}:
4833 GNU extension
4834
4835 @item @emph{Class}:
4836 Function
4837
4838 @item @emph{Syntax}:
4839 @code{RESULT = FNUM(UNIT)}
4840
4841 @item @emph{Arguments}:
4842 @multitable @columnfractions .15 .70
4843 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4844 @end multitable
4845
4846 @item @emph{Return value}:
4847 The return value is of type @code{INTEGER}
4848
4849 @item @emph{Example}:
4850 @smallexample
4851 program test_fnum
4852   integer :: i
4853   open (unit=10, status = "scratch")
4854   i = fnum(10)
4855   print *, i
4856   close (10)
4857 end program test_fnum
4858 @end smallexample
4859 @end table
4860
4861
4862
4863 @node FPUT
4864 @section @code{FPUT} --- Write a single character in stream mode to stdout
4865 @fnindex FPUT
4866 @cindex write character, stream mode
4867 @cindex stream mode, write character
4868 @cindex file operation, write character
4869
4870 @table @asis
4871 @item @emph{Description}:
4872 Write a single character in stream mode to stdout by bypassing normal
4873 formatted output. Stream I/O should not be mixed with normal record-oriented
4874 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4875
4876 This intrinsic is provided in both subroutine and function forms; however,
4877 only one form can be used in any given program unit.
4878
4879 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4880 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4881 Programmers should consider the use of new stream IO feature in new code
4882 for future portability. See also @ref{Fortran 2003 status}.
4883
4884 @item @emph{Standard}:
4885 GNU extension
4886
4887 @item @emph{Class}:
4888 Subroutine, function
4889
4890 @item @emph{Syntax}:
4891 @multitable @columnfractions .80
4892 @item @code{CALL FPUT(C [, STATUS])}
4893 @item @code{STATUS = FPUT(C)}
4894 @end multitable
4895
4896 @item @emph{Arguments}:
4897 @multitable @columnfractions .15 .70
4898 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4899 kind.
4900 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4901 Returns 0 on success, -1 on end-of-file and a system specific positive
4902 error code otherwise.
4903 @end multitable
4904
4905 @item @emph{Example}:
4906 @smallexample
4907 PROGRAM test_fput
4908   CHARACTER(len=10) :: str = "gfortran"
4909   INTEGER :: i
4910   DO i = 1, len_trim(str)
4911     CALL fput(str(i:i))
4912   END DO
4913 END PROGRAM
4914 @end smallexample
4915
4916 @item @emph{See also}:
4917 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4918 @end table
4919
4920
4921
4922 @node FPUTC
4923 @section @code{FPUTC} --- Write a single character in stream mode
4924 @fnindex FPUTC
4925 @cindex write character, stream mode
4926 @cindex stream mode, write character
4927 @cindex file operation, write character
4928
4929 @table @asis
4930 @item @emph{Description}:
4931 Write a single character in stream mode by bypassing normal formatted
4932 output. Stream I/O should not be mixed with normal record-oriented
4933 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4934
4935 This intrinsic is provided in both subroutine and function forms; however,
4936 only one form can be used in any given program unit.
4937
4938 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4939 @command{g77}.  GNU Fortran provides the Fortran 2003 Stream facility.
4940 Programmers should consider the use of new stream IO feature in new code
4941 for future portability. See also @ref{Fortran 2003 status}.
4942
4943 @item @emph{Standard}:
4944 GNU extension
4945
4946 @item @emph{Class}:
4947 Subroutine, function
4948
4949 @item @emph{Syntax}:
4950 @multitable @columnfractions .80
4951 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4952 @item @code{STATUS = FPUTC(UNIT, C)}
4953 @end multitable
4954
4955 @item @emph{Arguments}:
4956 @multitable @columnfractions .15 .70
4957 @item @var{UNIT}   @tab The type shall be @code{INTEGER}.
4958 @item @var{C}      @tab The type shall be @code{CHARACTER} and of default
4959 kind.
4960 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4961 Returns 0 on success, -1 on end-of-file and a system specific positive
4962 error code otherwise.
4963 @end multitable
4964
4965 @item @emph{Example}:
4966 @smallexample
4967 PROGRAM test_fputc
4968   CHARACTER(len=10) :: str = "gfortran"
4969   INTEGER :: fd = 42, i
4970
4971   OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4972   DO i = 1, len_trim(str)
4973     CALL fputc(fd, str(i:i))
4974   END DO
4975   CLOSE(fd)
4976 END PROGRAM
4977 @end smallexample
4978
4979 @item @emph{See also}:
4980 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4981 @end table
4982
4983
4984
4985 @node FRACTION
4986 @section @code{FRACTION} --- Fractional part of the model representation
4987 @fnindex FRACTION
4988 @cindex real number, fraction
4989 @cindex floating point, fraction
4990
4991 @table @asis
4992 @item @emph{Description}:
4993 @code{FRACTION(X)} returns the fractional part of the model
4994 representation of @code{X}.
4995
4996 @item @emph{Standard}:
4997 Fortran 95 and later
4998
4999 @item @emph{Class}:
5000 Elemental function
5001
5002 @item @emph{Syntax}:
5003 @code{Y = FRACTION(X)}
5004
5005 @item @emph{Arguments}:
5006 @multitable @columnfractions .15 .70
5007 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5008 @end multitable
5009
5010 @item @emph{Return value}:
5011 The return value is of the same type and kind as the argument.
5012 The fractional part of the model representation of @code{X} is returned;
5013 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5014
5015 @item @emph{Example}:
5016 @smallexample
5017 program test_fraction
5018   real :: x
5019   x = 178.1387e-4
5020   print *, fraction(x), x * radix(x)**(-exponent(x))
5021 end program test_fraction
5022 @end smallexample
5023
5024 @end table
5025
5026
5027
5028 @node FREE
5029 @section @code{FREE} --- Frees memory
5030 @fnindex FREE
5031 @cindex pointer, cray
5032
5033 @table @asis
5034 @item @emph{Description}:
5035 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5036 intrinsic is an extension intended to be used with Cray pointers, and is
5037 provided in GNU Fortran to allow user to compile legacy code. For
5038 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5039 @code{DEALLOCATE}.
5040
5041 @item @emph{Standard}:
5042 GNU extension
5043
5044 @item @emph{Class}:
5045 Subroutine
5046
5047 @item @emph{Syntax}:
5048 @code{CALL FREE(PTR)}
5049
5050 @item @emph{Arguments}:
5051 @multitable @columnfractions .15 .70
5052 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5053 location of the memory that should be de-allocated.
5054 @end multitable
5055
5056 @item @emph{Return value}:
5057 None
5058
5059 @item @emph{Example}:
5060 See @code{MALLOC} for an example.
5061
5062 @item @emph{See also}:
5063 @ref{MALLOC}
5064 @end table
5065
5066
5067
5068 @node FSEEK
5069 @section @code{FSEEK} --- Low level file positioning subroutine
5070 @fnindex FSEEK
5071 @cindex file operation, seek
5072 @cindex file operation, position
5073
5074 @table @asis
5075 @item @emph{Description}:
5076 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5077 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5078 if set to 1, @var{OFFSET} is taken to be relative to the current position
5079 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5080 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5081 fails silently.
5082
5083 This intrinsic routine is not fully backwards compatible with @command{g77}.
5084 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5085 @var{STATUS} variable. If FSEEK is used in old code, change
5086 @smallexample
5087   CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5088 @end smallexample
5089 to
5090 @smallexample
5091   INTEGER :: status
5092   CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5093   IF (status /= 0) GOTO label
5094 @end smallexample
5095
5096 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5097 Programmers should consider the use of new stream IO feature in new code
5098 for future portability. See also @ref{Fortran 2003 status}.
5099
5100 @item @emph{Standard}:
5101 GNU extension
5102
5103 @item @emph{Class}:
5104 Subroutine
5105
5106 @item @emph{Syntax}:
5107 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5108
5109 @item @emph{Arguments}:
5110 @multitable @columnfractions .15 .70
5111 @item @var{UNIT}   @tab Shall be a scalar of type @code{INTEGER}.
5112 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5113 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5114 Its value shall be either 0, 1 or 2.
5115 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5116 @code{INTEGER(4)}.
5117 @end multitable
5118
5119 @item @emph{Example}:
5120 @smallexample
5121 PROGRAM test_fseek
5122   INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5123   INTEGER :: fd, offset, ierr
5124
5125   ierr   = 0
5126   offset = 5
5127   fd     = 10
5128
5129   OPEN(UNIT=fd, FILE="fseek.test")
5130   CALL FSEEK(fd, offset, SEEK_SET, ierr)  ! move to OFFSET
5131   print *, FTELL(fd), ierr
5132
5133   CALL FSEEK(fd, 0, SEEK_END, ierr)       ! move to end
5134   print *, FTELL(fd), ierr
5135
5136   CALL FSEEK(fd, 0, SEEK_SET, ierr)       ! move to beginning
5137   print *, FTELL(fd), ierr
5138
5139   CLOSE(UNIT=fd)
5140 END PROGRAM
5141 @end smallexample
5142
5143 @item @emph{See also}:
5144 @ref{FTELL}
5145 @end table
5146
5147
5148
5149 @node FSTAT
5150 @section @code{FSTAT} --- Get file status
5151 @fnindex FSTAT
5152 @cindex file system, file status
5153
5154 @table @asis
5155 @item @emph{Description}:
5156 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5157 already opened file is obtained.
5158
5159 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5160
5161 This intrinsic is provided in both subroutine and function forms; however,
5162 only one form can be used in any given program unit.
5163
5164 @item @emph{Standard}:
5165 GNU extension
5166
5167 @item @emph{Class}:
5168 Subroutine, function
5169
5170 @item @emph{Syntax}:
5171 @multitable @columnfractions .80
5172 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5173 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5174 @end multitable
5175
5176 @item @emph{Arguments}:
5177 @multitable @columnfractions .15 .70
5178 @item @var{UNIT}   @tab An open I/O unit number of type @code{INTEGER}.
5179 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5180 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5181 on success and a system specific error code otherwise.
5182 @end multitable
5183
5184 @item @emph{Example}:
5185 See @ref{STAT} for an example.
5186
5187 @item @emph{See also}:
5188 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5189 @end table
5190
5191
5192
5193 @node FTELL
5194 @section @code{FTELL} --- Current stream position
5195 @fnindex FTELL
5196 @cindex file operation, position
5197
5198 @table @asis
5199 @item @emph{Description}:
5200 Retrieves the current position within an open file.
5201
5202 This intrinsic is provided in both subroutine and function forms; however,
5203 only one form can be used in any given program unit.
5204
5205 @item @emph{Standard}:
5206 GNU extension
5207
5208 @item @emph{Class}:
5209 Subroutine, function
5210
5211 @item @emph{Syntax}:
5212 @multitable @columnfractions .80
5213 @item @code{CALL FTELL(UNIT, OFFSET)}
5214 @item @code{OFFSET = FTELL(UNIT)}
5215 @end multitable
5216
5217 @item @emph{Arguments}:
5218 @multitable @columnfractions .15 .70
5219 @item @var{OFFSET}  @tab Shall of type @code{INTEGER}.
5220 @item @var{UNIT}    @tab Shall of type @code{INTEGER}.
5221 @end multitable
5222
5223 @item @emph{Return value}:
5224 In either syntax, @var{OFFSET} is set to the current offset of unit
5225 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5226
5227 @item @emph{Example}:
5228 @smallexample
5229 PROGRAM test_ftell
5230   INTEGER :: i
5231   OPEN(10, FILE="temp.dat")
5232   CALL ftell(10,i)
5233   WRITE(*,*) i
5234 END PROGRAM
5235 @end smallexample
5236
5237 @item @emph{See also}:
5238 @ref{FSEEK}
5239 @end table
5240
5241
5242
5243 @node GAMMA
5244 @section @code{GAMMA} --- Gamma function
5245 @fnindex GAMMA
5246 @fnindex DGAMMA
5247 @cindex Gamma function
5248 @cindex Factorial function
5249
5250 @table @asis
5251 @item @emph{Description}:
5252 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5253 integer values of @var{X} the Gamma function simplifies to the factorial
5254 function @math{\Gamma(x)=(x-1)!}.
5255
5256 @tex
5257 $$
5258 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5259 $$
5260 @end tex
5261
5262 @item @emph{Standard}:
5263 Fortran 2008 and later
5264
5265 @item @emph{Class}:
5266 Elemental function
5267
5268 @item @emph{Syntax}:
5269 @code{X = GAMMA(X)}
5270
5271 @item @emph{Arguments}:
5272 @multitable @columnfractions .15 .70
5273 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5274 nor a negative integer.
5275 @end multitable
5276
5277 @item @emph{Return value}:
5278 The return value is of type @code{REAL} of the same kind as @var{X}.
5279
5280 @item @emph{Example}:
5281 @smallexample
5282 program test_gamma
5283   real :: x = 1.0
5284   x = gamma(x) ! returns 1.0
5285 end program test_gamma
5286 @end smallexample
5287
5288 @item @emph{Specific names}:
5289 @multitable @columnfractions .20 .20 .20 .25
5290 @item Name             @tab Argument         @tab Return type       @tab Standard
5291 @item @code{GAMMA(X)}  @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
5292 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
5293 @end multitable
5294
5295 @item @emph{See also}:
5296 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5297
5298 @end table
5299
5300
5301
5302 @node GERROR
5303 @section @code{GERROR} --- Get last system error message
5304 @fnindex GERROR
5305 @cindex system, error handling
5306
5307 @table @asis
5308 @item @emph{Description}:
5309 Returns the system error message corresponding to the last system error.
5310 This resembles the functionality of @code{strerror(3)} in C.
5311
5312 @item @emph{Standard}:
5313 GNU extension
5314
5315 @item @emph{Class}:
5316 Subroutine
5317
5318 @item @emph{Syntax}:
5319 @code{CALL GERROR(RESULT)}
5320
5321 @item @emph{Arguments}:
5322 @multitable @columnfractions .15 .70
5323 @item @var{RESULT}  @tab Shall of type @code{CHARACTER} and of default
5324 @end multitable
5325
5326 @item @emph{Example}:
5327 @smallexample
5328 PROGRAM test_gerror
5329   CHARACTER(len=100) :: msg
5330   CALL gerror(msg)
5331   WRITE(*,*) msg
5332 END PROGRAM
5333 @end smallexample
5334
5335 @item @emph{See also}:
5336 @ref{IERRNO}, @ref{PERROR}
5337 @end table
5338
5339
5340
5341 @node GETARG
5342 @section @code{GETARG} --- Get command line arguments
5343 @fnindex GETARG
5344 @cindex command-line arguments
5345 @cindex arguments, to program
5346
5347 @table @asis
5348 @item @emph{Description}:
5349 Retrieve the @var{POS}-th argument that was passed on the
5350 command line when the containing program was invoked.
5351
5352 This intrinsic routine is provided for backwards compatibility with
5353 GNU Fortran 77.  In new code, programmers should consider the use of
5354 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5355 standard.
5356
5357 @item @emph{Standard}:
5358 GNU extension
5359
5360 @item @emph{Class}:
5361 Subroutine
5362
5363 @item @emph{Syntax}:
5364 @code{CALL GETARG(POS, VALUE)}
5365
5366 @item @emph{Arguments}:
5367 @multitable @columnfractions .15 .70
5368 @item @var{POS}   @tab Shall be of type @code{INTEGER} and not wider than
5369 the default integer kind; @math{@var{POS} \geq 0}
5370 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5371 kind.
5372 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5373 @end multitable
5374
5375 @item @emph{Return value}:
5376 After @code{GETARG} returns, the @var{VALUE} argument holds the
5377 @var{POS}th command line argument. If @var{VALUE} can not hold the
5378 argument, it is truncated to fit the length of @var{VALUE}. If there are
5379 less than @var{POS} arguments specified at the command line, @var{VALUE}
5380 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5381 to the name of the program (on systems that support this feature).
5382
5383 @item @emph{Example}:
5384 @smallexample
5385 PROGRAM test_getarg
5386   INTEGER :: i
5387   CHARACTER(len=32) :: arg
5388
5389   DO i = 1, iargc()
5390     CALL getarg(i, arg)
5391     WRITE (*,*) arg
5392   END DO
5393 END PROGRAM
5394 @end smallexample
5395
5396 @item @emph{See also}:
5397 GNU Fortran 77 compatibility function: @ref{IARGC}
5398
5399 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5400 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5401 @end table
5402
5403
5404
5405 @node GET_COMMAND
5406 @section @code{GET_COMMAND} --- Get the entire command line
5407 @fnindex GET_COMMAND
5408 @cindex command-line arguments
5409 @cindex arguments, to program
5410
5411 @table @asis
5412 @item @emph{Description}:
5413 Retrieve the entire command line that was used to invoke the program.
5414
5415 @item @emph{Standard}:
5416 Fortran 2003 and later
5417
5418 @item @emph{Class}:
5419 Subroutine
5420
5421 @item @emph{Syntax}:
5422 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5423
5424 @item @emph{Arguments}:
5425 @multitable @columnfractions .15 .70
5426 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5427 of default kind.
5428 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5429 default kind.
5430 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5431 default kind.
5432 @end multitable
5433
5434 @item @emph{Return value}:
5435 If @var{COMMAND} is present, stores the entire command line that was used
5436 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5437 assigned the length of the command line. If @var{STATUS} is present, it
5438 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5439 short to store the command line, or a positive value in case of an error.
5440
5441 @item @emph{Example}:
5442 @smallexample
5443 PROGRAM test_get_command
5444   CHARACTER(len=255) :: cmd
5445   CALL get_command(cmd)
5446   WRITE (*,*) TRIM(cmd)
5447 END PROGRAM
5448 @end smallexample
5449
5450 @item @emph{See also}:
5451 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5452 @end table
5453
5454
5455
5456 @node GET_COMMAND_ARGUMENT
5457 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5458 @fnindex GET_COMMAND_ARGUMENT
5459 @cindex command-line arguments
5460 @cindex arguments, to program
5461
5462 @table @asis
5463 @item @emph{Description}:
5464 Retrieve the @var{NUMBER}-th argument that was passed on the
5465 command line when the containing program was invoked.
5466
5467 @item @emph{Standard}:
5468 Fortran 2003 and later
5469
5470 @item @emph{Class}:
5471 Subroutine
5472
5473 @item @emph{Syntax}:
5474 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5475
5476 @item @emph{Arguments}:
5477 @multitable @columnfractions .15 .70
5478 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5479 default kind, @math{@var{NUMBER} \geq 0}
5480 @item @var{VALUE}  @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5481 and of default kind.
5482 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5483 and of default kind.
5484 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5485 and of default kind.
5486 @end multitable
5487
5488 @item @emph{Return value}:
5489 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5490 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5491 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5492 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5493 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5494 systems that support this feature). The @var{LENGTH} argument contains the
5495 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5496 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5497 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5498 zero.
5499
5500 @item @emph{Example}:
5501 @smallexample
5502 PROGRAM test_get_command_argument
5503   INTEGER :: i
5504   CHARACTER(len=32) :: arg
5505
5506   i = 0
5507   DO
5508     CALL get_command_argument(i, arg)
5509     IF (LEN_TRIM(arg) == 0) EXIT
5510
5511     WRITE (*,*) TRIM(arg)
5512     i = i+1
5513   END DO
5514 END PROGRAM
5515 @end smallexample
5516
5517 @item @emph{See also}:
5518 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5519 @end table
5520
5521
5522
5523 @node GETCWD
5524 @section @code{GETCWD} --- Get current working directory
5525 @fnindex GETCWD
5526 @cindex system, working directory
5527
5528 @table @asis
5529 @item @emph{Description}:
5530 Get current working directory.
5531
5532 This intrinsic is provided in both subroutine and function forms; however,
5533 only one form can be used in any given program unit.
5534
5535 @item @emph{Standard}:
5536 GNU extension
5537
5538 @item @emph{Class}:
5539 Subroutine, function
5540
5541 @item @emph{Syntax}:
5542 @multitable @columnfractions .80
5543 @item @code{CALL GETCWD(C [, STATUS])}
5544 @item @code{STATUS = GETCWD(C)}
5545 @end multitable
5546
5547 @item @emph{Arguments}:
5548 @multitable @columnfractions .15 .70
5549 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5550 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5551 a system specific and nonzero error code otherwise.
5552 @end multitable
5553
5554 @item @emph{Example}:
5555 @smallexample
5556 PROGRAM test_getcwd
5557   CHARACTER(len=255) :: cwd
5558   CALL getcwd(cwd)
5559   WRITE(*,*) TRIM(cwd)
5560 END PROGRAM
5561 @end smallexample
5562
5563 @item @emph{See also}:
5564 @ref{CHDIR}
5565 @end table
5566
5567
5568
5569 @node GETENV
5570 @section @code{GETENV} --- Get an environmental variable
5571 @fnindex GETENV
5572 @cindex environment variable
5573
5574 @table @asis
5575 @item @emph{Description}:
5576 Get the @var{VALUE} of the environmental variable @var{NAME}.
5577
5578 This intrinsic routine is provided for backwards compatibility with
5579 GNU Fortran 77.  In new code, programmers should consider the use of
5580 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5581 2003 standard.
5582
5583 Note that @code{GETENV} need not be thread-safe. It is the
5584 responsibility of the user to ensure that the environment is not being
5585 updated concurrently with a call to the @code{GETENV} intrinsic.
5586
5587 @item @emph{Standard}:
5588 GNU extension
5589
5590 @item @emph{Class}:
5591 Subroutine
5592
5593 @item @emph{Syntax}:
5594 @code{CALL GETENV(NAME, VALUE)}
5595
5596 @item @emph{Arguments}:
5597 @multitable @columnfractions .15 .70
5598 @item @var{NAME}  @tab Shall be of type @code{CHARACTER} and of default kind.
5599 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5600 @end multitable
5601
5602 @item @emph{Return value}:
5603 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5604 not large enough to hold the data, it is truncated. If @var{NAME}
5605 is not set, @var{VALUE} will be filled with blanks.
5606
5607 @item @emph{Example}:
5608 @smallexample
5609 PROGRAM test_getenv
5610   CHARACTER(len=255) :: homedir
5611   CALL getenv("HOME", homedir)
5612   WRITE (*,*) TRIM(homedir)
5613 END PROGRAM
5614 @end smallexample
5615
5616 @item @emph{See also}:
5617 @ref{GET_ENVIRONMENT_VARIABLE}
5618 @end table
5619
5620
5621
5622 @node GET_ENVIRONMENT_VARIABLE
5623 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5624 @fnindex GET_ENVIRONMENT_VARIABLE
5625 @cindex environment variable
5626
5627 @table @asis
5628 @item @emph{Description}:
5629 Get the @var{VALUE} of the environmental variable @var{NAME}.
5630
5631 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5632 is the responsibility of the user to ensure that the environment is
5633 not being updated concurrently with a call to the
5634 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5635
5636 @item @emph{Standard}:
5637 Fortran 2003 and later
5638
5639 @item @emph{Class}:
5640 Subroutine
5641
5642 @item @emph{Syntax}:
5643 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5644
5645 @item @emph{Arguments}:
5646 @multitable @columnfractions .15 .70
5647 @item @var{NAME}      @tab Shall be a scalar of type @code{CHARACTER}
5648 and of default kind.
5649 @item @var{VALUE}     @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5650 and of default kind.
5651 @item @var{LENGTH}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5652 and of default kind.
5653 @item @var{STATUS}    @tab (Optional) Shall be a scalar of type @code{INTEGER}
5654 and of default kind.
5655 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5656 and of default kind.
5657 @end multitable
5658
5659 @item @emph{Return value}:
5660 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5661 not large enough to hold the data, it is truncated. If @var{NAME}
5662 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5663 contains the length needed for storing the environment variable @var{NAME}
5664 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5665 but too short for the environment variable; it is 1 if the environment
5666 variable does not exist and 2 if the processor does not support environment
5667 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5668 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5669 are significant; otherwise they are not part of the environment variable
5670 name.
5671
5672 @item @emph{Example}:
5673 @smallexample
5674 PROGRAM test_getenv
5675   CHARACTER(len=255) :: homedir
5676   CALL get_environment_variable("HOME", homedir)
5677   WRITE (*,*) TRIM(homedir)
5678 END PROGRAM
5679 @end smallexample
5680 @end table
5681
5682
5683
5684 @node GETGID
5685 @section @code{GETGID} --- Group ID function
5686 @fnindex GETGID
5687 @cindex system, group ID
5688
5689 @table @asis
5690 @item @emph{Description}:
5691 Returns the numerical group ID of the current process.
5692
5693 @item @emph{Standard}:
5694 GNU extension
5695
5696 @item @emph{Class}:
5697 Function
5698
5699 @item @emph{Syntax}:
5700 @code{RESULT = GETGID()}
5701
5702 @item @emph{Return value}:
5703 The return value of @code{GETGID} is an @code{INTEGER} of the default
5704 kind.
5705
5706
5707 @item @emph{Example}:
5708 See @code{GETPID} for an example.
5709
5710 @item @emph{See also}:
5711 @ref{GETPID}, @ref{GETUID}
5712 @end table
5713
5714
5715
5716 @node GETLOG
5717 @section @code{GETLOG} --- Get login name
5718 @fnindex GETLOG
5719 @cindex system, login name
5720 @cindex login name
5721
5722 @table @asis
5723 @item @emph{Description}:
5724 Gets the username under which the program is running.
5725
5726 @item @emph{Standard}:
5727 GNU extension
5728
5729 @item @emph{Class}:
5730 Subroutine
5731
5732 @item @emph{Syntax}:
5733 @code{CALL GETLOG(C)}
5734
5735 @item @emph{Arguments}:
5736 @multitable @columnfractions .15 .70
5737 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5738 @end multitable
5739
5740 @item @emph{Return value}:
5741 Stores the current user name in @var{LOGIN}.  (On systems where POSIX
5742 functions @code{geteuid} and @code{getpwuid} are not available, and
5743 the @code{getlogin} function is not implemented either, this will
5744 return a blank string.)
5745
5746 @item @emph{Example}:
5747 @smallexample
5748 PROGRAM TEST_GETLOG
5749   CHARACTER(32) :: login
5750   CALL GETLOG(login)
5751   WRITE(*,*) login
5752 END PROGRAM
5753 @end smallexample
5754
5755 @item @emph{See also}:
5756 @ref{GETUID}
5757 @end table
5758
5759
5760
5761 @node GETPID
5762 @section @code{GETPID} --- Process ID function
5763 @fnindex GETPID
5764 @cindex system, process ID
5765 @cindex process ID
5766
5767 @table @asis
5768 @item @emph{Description}:
5769 Returns the numerical process identifier of the current process.
5770
5771 @item @emph{Standard}:
5772 GNU extension
5773
5774 @item @emph{Class}:
5775 Function
5776
5777 @item @emph{Syntax}:
5778 @code{RESULT = GETPID()}
5779
5780 @item @emph{Return value}:
5781 The return value of @code{GETPID} is an @code{INTEGER} of the default
5782 kind.
5783
5784
5785 @item @emph{Example}:
5786 @smallexample
5787 program info
5788   print *, "The current process ID is ", getpid()
5789   print *, "Your numerical user ID is ", getuid()
5790   print *, "Your numerical group ID is ", getgid()
5791 end program info
5792 @end smallexample
5793
5794 @item @emph{See also}:
5795 @ref{GETGID}, @ref{GETUID}
5796 @end table
5797
5798
5799
5800 @node GETUID
5801 @section @code{GETUID} --- User ID function
5802 @fnindex GETUID
5803 @cindex system, user ID
5804 @cindex user id
5805
5806 @table @asis
5807 @item @emph{Description}:
5808 Returns the numerical user ID of the current process.
5809
5810 @item @emph{Standard}:
5811 GNU extension
5812
5813 @item @emph{Class}:
5814 Function
5815
5816 @item @emph{Syntax}:
5817 @code{RESULT = GETUID()}
5818
5819 @item @emph{Return value}:
5820 The return value of @code{GETUID} is an @code{INTEGER} of the default
5821 kind.
5822
5823
5824 @item @emph{Example}:
5825 See @code{GETPID} for an example.
5826
5827 @item @emph{See also}:
5828 @ref{GETPID}, @ref{GETLOG}
5829 @end table
5830
5831
5832
5833 @node GMTIME
5834 @section @code{GMTIME} --- Convert time to GMT info
5835 @fnindex GMTIME
5836 @cindex time, conversion to GMT info
5837
5838 @table @asis
5839 @item @emph{Description}:
5840 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5841 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5842 to the UTC time zone (Universal Coordinated Time, also known in some
5843 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5844
5845 @item @emph{Standard}:
5846 GNU extension
5847
5848 @item @emph{Class}:
5849 Subroutine
5850
5851 @item @emph{Syntax}:
5852 @code{CALL GMTIME(TIME, VALUES)}
5853
5854 @item @emph{Arguments}:
5855 @multitable @columnfractions .15 .70
5856 @item @var{TIME}   @tab An @code{INTEGER} scalar expression
5857 corresponding to a system time, with @code{INTENT(IN)}.
5858 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5859 with @code{INTENT(OUT)}.
5860 @end multitable
5861
5862 @item @emph{Return value}:
5863 The elements of @var{VALUES} are assigned as follows:
5864 @enumerate
5865 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5866 seconds
5867 @item Minutes after the hour, range 0--59
5868 @item Hours past midnight, range 0--23
5869 @item Day of month, range 0--31
5870 @item Number of months since January, range 0--12
5871 @item Years since 1900
5872 @item Number of days since Sunday, range 0--6
5873 @item Days since January 1
5874 @item Daylight savings indicator: positive if daylight savings is in
5875 effect, zero if not, and negative if the information is not available.
5876 @end enumerate
5877
5878 @item @emph{See also}:
5879 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5880
5881 @end table
5882
5883
5884
5885 @node HOSTNM
5886 @section @code{HOSTNM} --- Get system host name
5887 @fnindex HOSTNM
5888 @cindex system, host name
5889
5890 @table @asis
5891 @item @emph{Description}:
5892 Retrieves the host name of the system on which the program is running.
5893
5894 This intrinsic is provided in both subroutine and function forms; however,
5895 only one form can be used in any given program unit.
5896
5897 @item @emph{Standard}:
5898 GNU extension
5899
5900 @item @emph{Class}:
5901 Subroutine, function
5902
5903 @item @emph{Syntax}:
5904 @multitable @columnfractions .80
5905 @item @code{CALL HOSTNM(C [, STATUS])}
5906 @item @code{STATUS = HOSTNM(NAME)}
5907 @end multitable
5908
5909 @item @emph{Arguments}:
5910 @multitable @columnfractions .15 .70
5911 @item @var{C}    @tab Shall of type @code{CHARACTER} and of default kind.
5912 @item @var{STATUS}  @tab (Optional) status flag of type @code{INTEGER}.
5913 Returns 0 on success, or a system specific error code otherwise.
5914 @end multitable
5915
5916 @item @emph{Return value}:
5917 In either syntax, @var{NAME} is set to the current hostname if it can
5918 be obtained, or to a blank string otherwise.
5919
5920 @end table
5921
5922
5923
5924 @node HUGE
5925 @section @code{HUGE} --- Largest number of a kind
5926 @fnindex HUGE
5927 @cindex limits, largest number
5928 @cindex model representation, largest number
5929
5930 @table @asis
5931 @item @emph{Description}:
5932 @code{HUGE(X)} returns the largest number that is not an infinity in
5933 the model of the type of @code{X}.
5934
5935 @item @emph{Standard}:
5936 Fortran 95 and later
5937
5938 @item @emph{Class}:
5939 Inquiry function
5940
5941 @item @emph{Syntax}:
5942 @code{RESULT = HUGE(X)}
5943
5944 @item @emph{Arguments}:
5945 @multitable @columnfractions .15 .70
5946 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5947 @end multitable
5948
5949 @item @emph{Return value}:
5950 The return value is of the same type and kind as @var{X}
5951
5952 @item @emph{Example}:
5953 @smallexample
5954 program test_huge_tiny
5955   print *, huge(0), huge(0.0), huge(0.0d0)
5956   print *, tiny(0.0), tiny(0.0d0)
5957 end program test_huge_tiny
5958 @end smallexample
5959 @end table
5960
5961
5962
5963 @node HYPOT
5964 @section @code{HYPOT} --- Euclidean distance function
5965 @fnindex HYPOT
5966 @cindex Euclidean distance
5967
5968 @table @asis
5969 @item @emph{Description}:
5970 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5971 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5972
5973 @item @emph{Standard}:
5974 Fortran 2008 and later
5975
5976 @item @emph{Class}:
5977 Elemental function
5978
5979 @item @emph{Syntax}:
5980 @code{RESULT = HYPOT(X, Y)}
5981
5982 @item @emph{Arguments}:
5983 @multitable @columnfractions .15 .70
5984 @item @var{X} @tab The type shall be @code{REAL}.
5985 @item @var{Y} @tab The type and kind type parameter shall be the same as
5986 @var{X}.
5987 @end multitable
5988
5989 @item @emph{Return value}:
5990 The return value has the same type and kind type parameter as @var{X}.
5991
5992 @item @emph{Example}:
5993 @smallexample
5994 program test_hypot
5995   real(4) :: x = 1.e0_4, y = 0.5e0_4
5996   x = hypot(x,y)
5997 end program test_hypot
5998 @end smallexample
5999 @end table
6000
6001
6002
6003 @node IACHAR
6004 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6005 @fnindex IACHAR
6006 @cindex @acronym{ASCII} collating sequence
6007 @cindex collating sequence, @acronym{ASCII}
6008 @cindex conversion, to integer
6009
6010 @table @asis
6011 @item @emph{Description}:
6012 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6013 in the first character position of @code{C}.
6014
6015 @item @emph{Standard}:
6016 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6017
6018 @item @emph{Class}:
6019 Elemental function
6020
6021 @item @emph{Syntax}:
6022 @code{RESULT = IACHAR(C [, KIND])}
6023
6024 @item @emph{Arguments}:
6025 @multitable @columnfractions .15 .70
6026 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6027 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6028 expression indicating the kind parameter of the result.
6029 @end multitable
6030
6031 @item @emph{Return value}:
6032 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6033 @var{KIND} is absent, the return value is of default integer kind.
6034
6035 @item @emph{Example}:
6036 @smallexample
6037 program test_iachar
6038   integer i
6039   i = iachar(' ')
6040 end program test_iachar
6041 @end smallexample
6042
6043 @item @emph{Note}:
6044 See @ref{ICHAR} for a discussion of converting between numerical values
6045 and formatted string representations.
6046
6047 @item @emph{See also}:
6048 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6049
6050 @end table
6051
6052
6053
6054 @node IALL
6055 @section @code{IALL} --- Bitwise AND of array elements
6056 @fnindex IALL
6057 @cindex array, AND
6058 @cindex bits, AND of array elements
6059
6060 @table @asis
6061 @item @emph{Description}:
6062 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6063 if the corresponding element in @var{MASK} is @code{TRUE}.
6064
6065 @item @emph{Standard}:
6066 Fortran 2008 and later
6067
6068 @item @emph{Class}:
6069 Transformational function
6070
6071 @item @emph{Syntax}:
6072 @multitable @columnfractions .80
6073 @item @code{RESULT = IALL(ARRAY[, MASK])}
6074 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6075 @end multitable
6076
6077 @item @emph{Arguments}:
6078 @multitable @columnfractions .15 .70
6079 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6080 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6081 @code{INTEGER} with a value in the range from 1 to n, where n
6082 equals the rank of @var{ARRAY}.
6083 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6084 and either be a scalar or an array of the same shape as @var{ARRAY}.
6085 @end multitable
6086
6087 @item @emph{Return value}:
6088 The result is of the same type as @var{ARRAY}.
6089
6090 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6091 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6092 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6093 dimension @var{DIM} dropped is returned.
6094
6095 @item @emph{Example}:
6096 @smallexample
6097 PROGRAM test_iall
6098   INTEGER(1) :: a(2)
6099
6100   a(1) = b'00100100'
6101   a(2) = b'01101010'
6102
6103   ! prints 00100000
6104   PRINT '(b8.8)', IALL(a)
6105 END PROGRAM
6106 @end smallexample
6107
6108 @item @emph{See also}:
6109 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6110 @end table
6111
6112
6113
6114 @node IAND
6115 @section @code{IAND} --- Bitwise logical and
6116 @fnindex IAND
6117 @cindex bitwise logical and
6118 @cindex logical and, bitwise
6119
6120 @table @asis
6121 @item @emph{Description}:
6122 Bitwise logical @code{AND}.
6123
6124 @item @emph{Standard}:
6125 Fortran 95 and later
6126
6127 @item @emph{Class}:
6128 Elemental function
6129
6130 @item @emph{Syntax}:
6131 @code{RESULT = IAND(I, J)}
6132
6133 @item @emph{Arguments}:
6134 @multitable @columnfractions .15 .70
6135 @item @var{I} @tab The type shall be @code{INTEGER}.
6136 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6137 kind as @var{I}.  (As a GNU extension, different kinds are also
6138 permitted.)
6139 @end multitable
6140
6141 @item @emph{Return value}:
6142 The return type is @code{INTEGER}, of the same kind as the
6143 arguments.  (If the argument kinds differ, it is of the same kind as
6144 the larger argument.)
6145
6146 @item @emph{Example}:
6147 @smallexample
6148 PROGRAM test_iand
6149   INTEGER :: a, b
6150   DATA a / Z'F' /, b / Z'3' /
6151   WRITE (*,*) IAND(a, b)
6152 END PROGRAM
6153 @end smallexample
6154
6155 @item @emph{See also}:
6156 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6157
6158 @end table
6159
6160
6161
6162 @node IANY
6163 @section @code{IANY} --- Bitwise OR of array elements
6164 @fnindex IANY
6165 @cindex array, OR
6166 @cindex bits, OR of array elements
6167
6168 @table @asis
6169 @item @emph{Description}:
6170 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6171 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6172
6173 @item @emph{Standard}:
6174 Fortran 2008 and later
6175
6176 @item @emph{Class}:
6177 Transformational function
6178
6179 @item @emph{Syntax}:
6180 @multitable @columnfractions .80
6181 @item @code{RESULT = IANY(ARRAY[, MASK])}
6182 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6183 @end multitable
6184
6185 @item @emph{Arguments}:
6186 @multitable @columnfractions .15 .70
6187 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6188 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6189 @code{INTEGER} with a value in the range from 1 to n, where n
6190 equals the rank of @var{ARRAY}.
6191 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6192 and either be a scalar or an array of the same shape as @var{ARRAY}.
6193 @end multitable
6194
6195 @item @emph{Return value}:
6196 The result is of the same type as @var{ARRAY}.
6197
6198 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6199 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6200 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6201 dimension @var{DIM} dropped is returned.
6202
6203 @item @emph{Example}:
6204 @smallexample
6205 PROGRAM test_iany
6206   INTEGER(1) :: a(2)
6207
6208   a(1) = b'00100100'
6209   a(2) = b'01101010'
6210
6211   ! prints 01101110
6212   PRINT '(b8.8)', IANY(a)
6213 END PROGRAM
6214 @end smallexample
6215
6216 @item @emph{See also}:
6217 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6218 @end table
6219
6220
6221
6222 @node IARGC
6223 @section @code{IARGC} --- Get the number of command line arguments
6224 @fnindex IARGC
6225 @cindex command-line arguments
6226 @cindex command-line arguments, number of
6227 @cindex arguments, to program
6228
6229 @table @asis
6230 @item @emph{Description}:
6231 @code{IARGC} returns the number of arguments passed on the
6232 command line when the containing program was invoked.
6233
6234 This intrinsic routine is provided for backwards compatibility with
6235 GNU Fortran 77.  In new code, programmers should consider the use of
6236 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6237 standard.
6238
6239 @item @emph{Standard}:
6240 GNU extension
6241
6242 @item @emph{Class}:
6243 Function
6244
6245 @item @emph{Syntax}:
6246 @code{RESULT = IARGC()}
6247
6248 @item @emph{Arguments}:
6249 None.
6250
6251 @item @emph{Return value}:
6252 The number of command line arguments, type @code{INTEGER(4)}.
6253
6254 @item @emph{Example}:
6255 See @ref{GETARG}
6256
6257 @item @emph{See also}:
6258 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6259
6260 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6261 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6262 @end table
6263
6264
6265
6266 @node IBCLR
6267 @section @code{IBCLR} --- Clear bit
6268 @fnindex IBCLR
6269 @cindex bits, unset
6270 @cindex bits, clear
6271
6272 @table @asis
6273 @item @emph{Description}:
6274 @code{IBCLR} returns the value of @var{I} with the bit at position
6275 @var{POS} set to zero.
6276
6277 @item @emph{Standard}:
6278 Fortran 95 and later
6279
6280 @item @emph{Class}:
6281 Elemental function
6282
6283 @item @emph{Syntax}:
6284 @code{RESULT = IBCLR(I, POS)}
6285
6286 @item @emph{Arguments}:
6287 @multitable @columnfractions .15 .70
6288 @item @var{I} @tab The type shall be @code{INTEGER}.
6289 @item @var{POS} @tab The type shall be @code{INTEGER}.
6290 @end multitable
6291
6292 @item @emph{Return value}:
6293 The return value is of type @code{INTEGER} and of the same kind as
6294 @var{I}.
6295
6296 @item @emph{See also}:
6297 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6298
6299 @end table
6300
6301
6302
6303 @node IBITS
6304 @section @code{IBITS} --- Bit extraction
6305 @fnindex IBITS
6306 @cindex bits, get
6307 @cindex bits, extract
6308
6309 @table @asis
6310 @item @emph{Description}:
6311 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6312 starting from bit position @var{POS} and extending left for @var{LEN}
6313 bits.  The result is right-justified and the remaining bits are
6314 zeroed.  The value of @code{POS+LEN} must be less than or equal to the
6315 value @code{BIT_SIZE(I)}.
6316
6317 @item @emph{Standard}:
6318 Fortran 95 and later
6319
6320 @item @emph{Class}:
6321 Elemental function
6322
6323 @item @emph{Syntax}:
6324 @code{RESULT = IBITS(I, POS, LEN)}
6325
6326 @item @emph{Arguments}:
6327 @multitable @columnfractions .15 .70
6328 @item @var{I}   @tab The type shall be @code{INTEGER}.
6329 @item @var{POS} @tab The type shall be @code{INTEGER}.
6330 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6331 @end multitable
6332
6333 @item @emph{Return value}:
6334 The return value is of type @code{INTEGER} and of the same kind as
6335 @var{I}.
6336
6337 @item @emph{See also}:
6338 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6339 @end table
6340
6341
6342
6343 @node IBSET
6344 @section @code{IBSET} --- Set bit
6345 @fnindex IBSET
6346 @cindex bits, set
6347
6348 @table @asis
6349 @item @emph{Description}:
6350 @code{IBSET} returns the value of @var{I} with the bit at position
6351 @var{POS} set to one.
6352
6353 @item @emph{Standard}:
6354 Fortran 95 and later
6355
6356 @item @emph{Class}:
6357 Elemental function
6358
6359 @item @emph{Syntax}:
6360 @code{RESULT = IBSET(I, POS)}
6361
6362 @item @emph{Arguments}:
6363 @multitable @columnfractions .15 .70
6364 @item @var{I} @tab The type shall be @code{INTEGER}.
6365 @item @var{POS} @tab The type shall be @code{INTEGER}.
6366 @end multitable
6367
6368 @item @emph{Return value}:
6369 The return value is of type @code{INTEGER} and of the same kind as
6370 @var{I}.
6371
6372 @item @emph{See also}:
6373 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6374
6375 @end table
6376
6377
6378
6379 @node ICHAR
6380 @section @code{ICHAR} --- Character-to-integer conversion function
6381 @fnindex ICHAR
6382 @cindex conversion, to integer
6383
6384 @table @asis
6385 @item @emph{Description}:
6386 @code{ICHAR(C)} returns the code for the character in the first character
6387 position of @code{C} in the system's native character set.
6388 The correspondence between characters and their codes is not necessarily
6389 the same across different GNU Fortran implementations.
6390
6391 @item @emph{Standard}:
6392 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6393
6394 @item @emph{Class}:
6395 Elemental function
6396
6397 @item @emph{Syntax}:
6398 @code{RESULT = ICHAR(C [, KIND])}
6399
6400 @item @emph{Arguments}:
6401 @multitable @columnfractions .15 .70
6402 @item @var{C}    @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6403 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6404 expression indicating the kind parameter of the result.
6405 @end multitable
6406
6407 @item @emph{Return value}:
6408 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6409 @var{KIND} is absent, the return value is of default integer kind.
6410
6411 @item @emph{Example}:
6412 @smallexample
6413 program test_ichar
6414   integer i
6415   i = ichar(' ')
6416 end program test_ichar
6417 @end smallexample
6418
6419 @item @emph{Specific names}:
6420 @multitable @columnfractions .20 .20 .20 .25
6421 @item Name             @tab Argument             @tab Return type       @tab Standard
6422 @item @code{ICHAR(C)}  @tab @code{CHARACTER C}   @tab @code{INTEGER(4)}    @tab Fortran 77 and later
6423 @end multitable
6424
6425 @item @emph{Note}:
6426 No intrinsic exists to convert between a numeric value and a formatted
6427 character string representation -- for instance, given the
6428 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6429 @code{REAL} value with the value 154, or vice versa. Instead, this
6430 functionality is provided by internal-file I/O, as in the following
6431 example:
6432 @smallexample
6433 program read_val
6434   integer value
6435   character(len=10) string, string2
6436   string = '154'
6437
6438   ! Convert a string to a numeric value
6439   read (string,'(I10)') value
6440   print *, value
6441
6442   ! Convert a value to a formatted string
6443   write (string2,'(I10)') value
6444   print *, string2
6445 end program read_val
6446 @end smallexample
6447
6448 @item @emph{See also}:
6449 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6450
6451 @end table
6452
6453
6454
6455 @node IDATE
6456 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6457 @fnindex IDATE
6458 @cindex date, current
6459 @cindex current date
6460
6461 @table @asis
6462 @item @emph{Description}:
6463 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6464 current local time. The day (in the range 1-31), month (in the range 1-12),
6465 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6466 The year has four significant digits.
6467
6468 @item @emph{Standard}:
6469 GNU extension
6470
6471 @item @emph{Class}:
6472 Subroutine
6473
6474 @item @emph{Syntax}:
6475 @code{CALL IDATE(VALUES)}
6476
6477 @item @emph{Arguments}:
6478 @multitable @columnfractions .15 .70
6479 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6480 the kind shall be the default integer kind.
6481 @end multitable
6482
6483 @item @emph{Return value}:
6484 Does not return anything.
6485
6486 @item @emph{Example}:
6487 @smallexample
6488 program test_idate
6489   integer, dimension(3) :: tarray
6490   call idate(tarray)
6491   print *, tarray(1)
6492   print *, tarray(2)
6493   print *, tarray(3)
6494 end program test_idate
6495 @end smallexample
6496 @end table
6497
6498
6499
6500 @node IEOR
6501 @section @code{IEOR} --- Bitwise logical exclusive or
6502 @fnindex IEOR
6503 @cindex bitwise logical exclusive or
6504 @cindex logical exclusive or, bitwise
6505
6506 @table @asis
6507 @item @emph{Description}:
6508 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6509 @var{J}.
6510
6511 @item @emph{Standard}:
6512 Fortran 95 and later
6513
6514 @item @emph{Class}:
6515 Elemental function
6516
6517 @item @emph{Syntax}:
6518 @code{RESULT = IEOR(I, J)}
6519
6520 @item @emph{Arguments}:
6521 @multitable @columnfractions .15 .70
6522 @item @var{I} @tab The type shall be @code{INTEGER}.
6523 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6524 kind as @var{I}.  (As a GNU extension, different kinds are also
6525 permitted.)
6526 @end multitable
6527
6528 @item @emph{Return value}:
6529 The return type is @code{INTEGER}, of the same kind as the
6530 arguments.  (If the argument kinds differ, it is of the same kind as
6531 the larger argument.)
6532
6533 @item @emph{See also}:
6534 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6535 @end table
6536
6537
6538
6539 @node IERRNO
6540 @section @code{IERRNO} --- Get the last system error number
6541 @fnindex IERRNO
6542 @cindex system, error handling
6543
6544 @table @asis
6545 @item @emph{Description}:
6546 Returns the last system error number, as given by the C @code{errno}
6547 variable.
6548
6549 @item @emph{Standard}:
6550 GNU extension
6551
6552 @item @emph{Class}:
6553 Function
6554
6555 @item @emph{Syntax}:
6556 @code{RESULT = IERRNO()}
6557
6558 @item @emph{Arguments}:
6559 None.
6560
6561 @item @emph{Return value}:
6562 The return value is of type @code{INTEGER} and of the default integer
6563 kind.
6564
6565 @item @emph{See also}:
6566 @ref{PERROR}
6567 @end table
6568
6569
6570
6571 @node IMAGE_INDEX
6572 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6573 @fnindex IMAGE_INDEX
6574 @cindex coarray, @code{IMAGE_INDEX}
6575 @cindex images, cosubscript to image index conversion
6576
6577 @table @asis
6578 @item @emph{Description}:
6579 Returns the image index belonging to a cosubscript.
6580
6581 @item @emph{Standard}:
6582 Fortran 2008 and later
6583
6584 @item @emph{Class}:
6585 Inquiry function.
6586
6587 @item @emph{Syntax}:
6588 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6589
6590 @item @emph{Arguments}: None.
6591 @multitable @columnfractions .15 .70
6592 @item @var{COARRAY} @tab Coarray of any type.
6593 @item @var{SUB}     @tab default integer rank-1 array of a size equal to
6594 the corank of @var{COARRAY}.
6595 @end multitable
6596
6597
6598 @item @emph{Return value}:
6599 Scalar default integer with the value of the image index which corresponds
6600 to the cosubscripts. For invalid cosubscripts the result is zero.
6601
6602 @item @emph{Example}:
6603 @smallexample
6604 INTEGER :: array[2,-1:4,8,*]
6605 ! Writes  28 (or 0 if there are fewer than 28 images)
6606 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6607 @end smallexample
6608
6609 @item @emph{See also}:
6610 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6611 @end table
6612
6613
6614
6615 @node INDEX intrinsic
6616 @section @code{INDEX} --- Position of a substring within a string
6617 @fnindex INDEX
6618 @cindex substring position
6619 @cindex string, find substring
6620
6621 @table @asis
6622 @item @emph{Description}:
6623 Returns the position of the start of the first occurrence of string
6624 @var{SUBSTRING} as a substring in @var{STRING}, counting from one.  If
6625 @var{SUBSTRING} is not present in @var{STRING}, zero is returned.  If
6626 the @var{BACK} argument is present and true, the return value is the
6627 start of the last occurrence rather than the first.
6628
6629 @item @emph{Standard}:
6630 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6631
6632 @item @emph{Class}:
6633 Elemental function
6634
6635 @item @emph{Syntax}:
6636 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6637
6638 @item @emph{Arguments}:
6639 @multitable @columnfractions .15 .70
6640 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6641 @code{INTENT(IN)}
6642 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6643 @code{INTENT(IN)}
6644 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6645 @code{INTENT(IN)}
6646 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6647 expression indicating the kind parameter of the result.
6648 @end multitable
6649
6650 @item @emph{Return value}:
6651 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6652 @var{KIND} is absent, the return value is of default integer kind.
6653
6654 @item @emph{Specific names}:
6655 @multitable @columnfractions .20 .20 .20 .25
6656 @item Name                            @tab Argument           @tab Return type       @tab Standard
6657 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER}   @tab @code{INTEGER(4)} @tab Fortran 77 and later
6658 @end multitable
6659
6660 @item @emph{See also}:
6661 @ref{SCAN}, @ref{VERIFY}
6662 @end table
6663
6664
6665
6666 @node INT
6667 @section @code{INT} --- Convert to integer type
6668 @fnindex INT
6669 @fnindex IFIX
6670 @fnindex IDINT
6671 @cindex conversion, to integer
6672
6673 @table @asis
6674 @item @emph{Description}:
6675 Convert to integer type
6676
6677 @item @emph{Standard}:
6678 Fortran 77 and later
6679
6680 @item @emph{Class}:
6681 Elemental function
6682
6683 @item @emph{Syntax}:
6684 @code{RESULT = INT(A [, KIND))}
6685
6686 @item @emph{Arguments}:
6687 @multitable @columnfractions .15 .70
6688 @item @var{A}    @tab Shall be of type @code{INTEGER},
6689 @code{REAL}, or @code{COMPLEX}.
6690 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6691 expression indicating the kind parameter of the result.
6692 @end multitable
6693
6694 @item @emph{Return value}:
6695 These functions return a @code{INTEGER} variable or array under
6696 the following rules:
6697
6698 @table @asis
6699 @item (A)
6700 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6701 @item (B)
6702 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6703 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6704 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6705 @item (C)
6706 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6707 @end table
6708
6709 @item @emph{Example}:
6710 @smallexample
6711 program test_int
6712   integer :: i = 42
6713   complex :: z = (-3.7, 1.0)
6714   print *, int(i)
6715   print *, int(z), int(z,8)
6716 end program
6717 @end smallexample
6718
6719 @item @emph{Specific names}:
6720 @multitable @columnfractions .20 .20 .20 .25
6721 @item Name            @tab Argument          @tab Return type       @tab Standard
6722 @item @code{INT(A)}   @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6723 @item @code{IFIX(A)}  @tab @code{REAL(4) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6724 @item @code{IDINT(A)} @tab @code{REAL(8) A}  @tab @code{INTEGER}    @tab Fortran 77 and later
6725 @end multitable
6726
6727 @end table
6728
6729
6730 @node INT2
6731 @section @code{INT2} --- Convert to 16-bit integer type
6732 @fnindex INT2
6733 @fnindex SHORT
6734 @cindex conversion, to integer
6735
6736 @table @asis
6737 @item @emph{Description}:
6738 Convert to a @code{KIND=2} integer type. This is equivalent to the
6739 standard @code{INT} intrinsic with an optional argument of
6740 @code{KIND=2}, and is only included for backwards compatibility.
6741
6742 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6743
6744 @item @emph{Standard}:
6745 GNU extension
6746
6747 @item @emph{Class}:
6748 Elemental function
6749
6750 @item @emph{Syntax}:
6751 @code{RESULT = INT2(A)}
6752
6753 @item @emph{Arguments}:
6754 @multitable @columnfractions .15 .70
6755 @item @var{A}    @tab Shall be of type @code{INTEGER},
6756 @code{REAL}, or @code{COMPLEX}.
6757 @end multitable
6758
6759 @item @emph{Return value}:
6760 The return value is a @code{INTEGER(2)} variable.
6761
6762 @item @emph{See also}:
6763 @ref{INT}, @ref{INT8}, @ref{LONG}
6764 @end table
6765
6766
6767
6768 @node INT8
6769 @section @code{INT8} --- Convert to 64-bit integer type
6770 @fnindex INT8
6771 @cindex conversion, to integer
6772
6773 @table @asis
6774 @item @emph{Description}:
6775 Convert to a @code{KIND=8} integer type. This is equivalent to the
6776 standard @code{INT} intrinsic with an optional argument of
6777 @code{KIND=8}, and is only included for backwards compatibility.
6778
6779 @item @emph{Standard}:
6780 GNU extension
6781
6782 @item @emph{Class}:
6783 Elemental function
6784
6785 @item @emph{Syntax}:
6786 @code{RESULT = INT8(A)}
6787
6788 @item @emph{Arguments}:
6789 @multitable @columnfractions .15 .70
6790 @item @var{A}    @tab Shall be of type @code{INTEGER},
6791 @code{REAL}, or @code{COMPLEX}.
6792 @end multitable
6793
6794 @item @emph{Return value}:
6795 The return value is a @code{INTEGER(8)} variable.
6796
6797 @item @emph{See also}:
6798 @ref{INT}, @ref{INT2}, @ref{LONG}
6799 @end table
6800
6801
6802
6803 @node IOR
6804 @section @code{IOR} --- Bitwise logical or
6805 @fnindex IOR
6806 @cindex bitwise logical or
6807 @cindex logical or, bitwise
6808
6809 @table @asis
6810 @item @emph{Description}:
6811 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6812 @var{J}.
6813
6814 @item @emph{Standard}:
6815 Fortran 95 and later
6816
6817 @item @emph{Class}:
6818 Elemental function
6819
6820 @item @emph{Syntax}:
6821 @code{RESULT = IOR(I, J)}
6822
6823 @item @emph{Arguments}:
6824 @multitable @columnfractions .15 .70
6825 @item @var{I} @tab The type shall be @code{INTEGER}.
6826 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6827 kind as @var{I}.  (As a GNU extension, different kinds are also
6828 permitted.)
6829 @end multitable
6830
6831 @item @emph{Return value}:
6832 The return type is @code{INTEGER}, of the same kind as the
6833 arguments.  (If the argument kinds differ, it is of the same kind as
6834 the larger argument.)
6835
6836 @item @emph{See also}:
6837 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6838 @end table
6839
6840
6841
6842 @node IPARITY
6843 @section @code{IPARITY} --- Bitwise XOR of array elements
6844 @fnindex IPARITY
6845 @cindex array, parity
6846 @cindex array, XOR
6847 @cindex bits, XOR of array elements
6848
6849 @table @asis
6850 @item @emph{Description}:
6851 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6852 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6853
6854 @item @emph{Standard}:
6855 Fortran 2008 and later
6856
6857 @item @emph{Class}:
6858 Transformational function
6859
6860 @item @emph{Syntax}:
6861 @multitable @columnfractions .80
6862 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6863 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6864 @end multitable
6865
6866 @item @emph{Arguments}:
6867 @multitable @columnfractions .15 .70
6868 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6869 @item @var{DIM}   @tab (Optional) shall be a scalar of type
6870 @code{INTEGER} with a value in the range from 1 to n, where n
6871 equals the rank of @var{ARRAY}.
6872 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
6873 and either be a scalar or an array of the same shape as @var{ARRAY}.
6874 @end multitable
6875
6876 @item @emph{Return value}:
6877 The result is of the same type as @var{ARRAY}.
6878
6879 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6880 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6881 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6882 dimension @var{DIM} dropped is returned.
6883
6884 @item @emph{Example}:
6885 @smallexample
6886 PROGRAM test_iparity
6887   INTEGER(1) :: a(2)
6888
6889   a(1) = b'00100100'
6890   a(2) = b'01101010'
6891
6892   ! prints 01001110
6893   PRINT '(b8.8)', IPARITY(a)
6894 END PROGRAM
6895 @end smallexample
6896
6897 @item @emph{See also}:
6898 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6899 @end table
6900
6901
6902
6903 @node IRAND
6904 @section @code{IRAND} --- Integer pseudo-random number
6905 @fnindex IRAND
6906 @cindex random number generation
6907
6908 @table @asis
6909 @item @emph{Description}:
6910 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6911 distribution between 0 and a system-dependent limit (which is in most
6912 cases 2147483647). If @var{FLAG} is 0, the next number
6913 in the current sequence is returned; if @var{FLAG} is 1, the generator
6914 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6915 it is used as a new seed with @code{SRAND}.
6916
6917 This intrinsic routine is provided for backwards compatibility with
6918 GNU Fortran 77. It implements a simple modulo generator as provided
6919 by @command{g77}. For new code, one should consider the use of
6920 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6921
6922 @item @emph{Standard}:
6923 GNU extension
6924
6925 @item @emph{Class}:
6926 Function
6927
6928 @item @emph{Syntax}:
6929 @code{RESULT = IRAND(I)}
6930
6931 @item @emph{Arguments}:
6932 @multitable @columnfractions .15 .70
6933 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6934 @end multitable
6935
6936 @item @emph{Return value}:
6937 The return value is of @code{INTEGER(kind=4)} type.
6938
6939 @item @emph{Example}:
6940 @smallexample
6941 program test_irand
6942   integer,parameter :: seed = 86456
6943
6944   call srand(seed)
6945   print *, irand(), irand(), irand(), irand()
6946   print *, irand(seed), irand(), irand(), irand()
6947 end program test_irand
6948 @end smallexample
6949
6950 @end table
6951
6952
6953
6954 @node IS_IOSTAT_END
6955 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6956 @fnindex IS_IOSTAT_END
6957 @cindex @code{IOSTAT}, end of file
6958
6959 @table @asis
6960 @item @emph{Description}:
6961 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6962 status ``end of file''. The function is equivalent to comparing the variable
6963 with the @code{IOSTAT_END} parameter of the intrinsic module
6964 @code{ISO_FORTRAN_ENV}.
6965
6966 @item @emph{Standard}:
6967 Fortran 2003 and later
6968
6969 @item @emph{Class}:
6970 Elemental function
6971
6972 @item @emph{Syntax}:
6973 @code{RESULT = IS_IOSTAT_END(I)}
6974
6975 @item @emph{Arguments}:
6976 @multitable @columnfractions .15 .70
6977 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6978 @end multitable
6979
6980 @item @emph{Return value}:
6981 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6982 @var{I} has the value which indicates an end of file condition for
6983 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6984
6985 @item @emph{Example}:
6986 @smallexample
6987 PROGRAM iostat
6988   IMPLICIT NONE
6989   INTEGER :: stat, i
6990   OPEN(88, FILE='test.dat')
6991   READ(88, *, IOSTAT=stat) i
6992   IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6993 END PROGRAM
6994 @end smallexample
6995 @end table
6996
6997
6998
6999 @node IS_IOSTAT_EOR
7000 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7001 @fnindex IS_IOSTAT_EOR
7002 @cindex @code{IOSTAT}, end of record
7003
7004 @table @asis
7005 @item @emph{Description}:
7006 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7007 status ``end of record''. The function is equivalent to comparing the
7008 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7009 @code{ISO_FORTRAN_ENV}.
7010
7011 @item @emph{Standard}:
7012 Fortran 2003 and later
7013
7014 @item @emph{Class}:
7015 Elemental function
7016
7017 @item @emph{Syntax}:
7018 @code{RESULT = IS_IOSTAT_EOR(I)}
7019
7020 @item @emph{Arguments}:
7021 @multitable @columnfractions .15 .70
7022 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7023 @end multitable
7024
7025 @item @emph{Return value}:
7026 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7027 @var{I} has the value which indicates an end of file condition for
7028 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7029
7030 @item @emph{Example}:
7031 @smallexample
7032 PROGRAM iostat
7033   IMPLICIT NONE
7034   INTEGER :: stat, i(50)
7035   OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7036   READ(88, IOSTAT=stat) i
7037   IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7038 END PROGRAM
7039 @end smallexample
7040 @end table
7041
7042
7043
7044 @node ISATTY
7045 @section @code{ISATTY} --- Whether a unit is a terminal device.
7046 @fnindex ISATTY
7047 @cindex system, terminal
7048
7049 @table @asis
7050 @item @emph{Description}:
7051 Determine whether a unit is connected to a terminal device.
7052
7053 @item @emph{Standard}:
7054 GNU extension
7055
7056 @item @emph{Class}:
7057 Function
7058
7059 @item @emph{Syntax}:
7060 @code{RESULT = ISATTY(UNIT)}
7061
7062 @item @emph{Arguments}:
7063 @multitable @columnfractions .15 .70
7064 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7065 @end multitable
7066
7067 @item @emph{Return value}:
7068 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7069 device, @code{.FALSE.} otherwise.
7070
7071 @item @emph{Example}:
7072 @smallexample
7073 PROGRAM test_isatty
7074   INTEGER(kind=1) :: unit
7075   DO unit = 1, 10
7076     write(*,*) isatty(unit=unit)
7077   END DO
7078 END PROGRAM
7079 @end smallexample
7080 @item @emph{See also}:
7081 @ref{TTYNAM}
7082 @end table
7083
7084
7085
7086 @node ISHFT
7087 @section @code{ISHFT} --- Shift bits
7088 @fnindex ISHFT
7089 @cindex bits, shift
7090
7091 @table @asis
7092 @item @emph{Description}:
7093 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7094 bits shifted @var{SHIFT} places.  A value of @var{SHIFT} greater than
7095 zero corresponds to a left shift, a value of zero corresponds to no
7096 shift, and a value less than zero corresponds to a right shift.  If the
7097 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7098 value is undefined.  Bits shifted out from the left end or right end are
7099 lost; zeros are shifted in from the opposite end.
7100
7101 @item @emph{Standard}:
7102 Fortran 95 and later
7103
7104 @item @emph{Class}:
7105 Elemental function
7106
7107 @item @emph{Syntax}:
7108 @code{RESULT = ISHFT(I, SHIFT)}
7109
7110 @item @emph{Arguments}:
7111 @multitable @columnfractions .15 .70
7112 @item @var{I} @tab The type shall be @code{INTEGER}.
7113 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7114 @end multitable
7115
7116 @item @emph{Return value}:
7117 The return value is of type @code{INTEGER} and of the same kind as
7118 @var{I}.
7119
7120 @item @emph{See also}:
7121 @ref{ISHFTC}
7122 @end table
7123
7124
7125
7126 @node ISHFTC
7127 @section @code{ISHFTC} --- Shift bits circularly
7128 @fnindex ISHFTC
7129 @cindex bits, shift circular
7130
7131 @table @asis
7132 @item @emph{Description}:
7133 @code{ISHFTC} returns a value corresponding to @var{I} with the
7134 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7135 is, bits shifted out one end are shifted into the opposite end.  A value
7136 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7137 zero corresponds to no shift, and a value less than zero corresponds to
7138 a right shift.  The absolute value of @var{SHIFT} must be less than
7139 @var{SIZE}.  If the @var{SIZE} argument is omitted, it is taken to be
7140 equivalent to @code{BIT_SIZE(I)}.
7141
7142 @item @emph{Standard}:
7143 Fortran 95 and later
7144
7145 @item @emph{Class}:
7146 Elemental function
7147
7148 @item @emph{Syntax}:
7149 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7150
7151 @item @emph{Arguments}:
7152 @multitable @columnfractions .15 .70
7153 @item @var{I} @tab The type shall be @code{INTEGER}.
7154 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7155 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7156 the value must be greater than zero and less than or equal to
7157 @code{BIT_SIZE(I)}.
7158 @end multitable
7159
7160 @item @emph{Return value}:
7161 The return value is of type @code{INTEGER} and of the same kind as
7162 @var{I}.
7163
7164 @item @emph{See also}:
7165 @ref{ISHFT}
7166 @end table
7167
7168
7169
7170 @node ISNAN
7171 @section @code{ISNAN} --- Test for a NaN
7172 @fnindex ISNAN
7173 @cindex IEEE, ISNAN
7174
7175 @table @asis
7176 @item @emph{Description}:
7177 @code{ISNAN} tests whether a floating-point value is an IEEE
7178 Not-a-Number (NaN).
7179 @item @emph{Standard}:
7180 GNU extension
7181
7182 @item @emph{Class}:
7183 Elemental function
7184
7185 @item @emph{Syntax}:
7186 @code{ISNAN(X)}
7187
7188 @item @emph{Arguments}:
7189 @multitable @columnfractions .15 .70
7190 @item @var{X} @tab Variable of the type @code{REAL}.
7191
7192 @end multitable
7193
7194 @item @emph{Return value}:
7195 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7196 if @var{X} is a NaN and @code{FALSE} otherwise.
7197
7198 @item @emph{Example}:
7199 @smallexample
7200 program test_nan
7201   implicit none
7202   real :: x
7203   x = -1.0
7204   x = sqrt(x)
7205   if (isnan(x)) stop '"x" is a NaN'
7206 end program test_nan
7207 @end smallexample
7208 @end table
7209
7210
7211
7212 @node ITIME
7213 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7214 @fnindex ITIME
7215 @cindex time, current
7216 @cindex current time
7217
7218 @table @asis
7219 @item @emph{Description}:
7220 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7221 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7222 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7223 respectively.
7224
7225 @item @emph{Standard}:
7226 GNU extension
7227
7228 @item @emph{Class}:
7229 Subroutine
7230
7231 @item @emph{Syntax}:
7232 @code{CALL ITIME(VALUES)}
7233
7234 @item @emph{Arguments}:
7235 @multitable @columnfractions .15 .70
7236 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7237 and the kind shall be the default integer kind.
7238 @end multitable
7239
7240 @item @emph{Return value}:
7241 Does not return anything.
7242
7243
7244 @item @emph{Example}:
7245 @smallexample
7246 program test_itime
7247   integer, dimension(3) :: tarray
7248   call itime(tarray)
7249   print *, tarray(1)
7250   print *, tarray(2)
7251   print *, tarray(3)
7252 end program test_itime
7253 @end smallexample
7254 @end table
7255
7256
7257
7258 @node KILL
7259 @section @code{KILL} --- Send a signal to a process
7260 @fnindex KILL
7261
7262 @table @asis
7263 @item @emph{Description}:
7264 @item @emph{Standard}:
7265 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7266 See @code{kill(2)}.
7267
7268 This intrinsic is provided in both subroutine and function forms; however,
7269 only one form can be used in any given program unit.
7270
7271 @item @emph{Class}:
7272 Subroutine, function
7273
7274 @item @emph{Syntax}:
7275 @multitable @columnfractions .80
7276 @item @code{CALL KILL(C, VALUE [, STATUS])}
7277 @item @code{STATUS = KILL(C, VALUE)}
7278 @end multitable
7279
7280 @item @emph{Arguments}:
7281 @multitable @columnfractions .15 .70
7282 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7283 @code{INTENT(IN)}
7284 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7285 @code{INTENT(IN)}
7286 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7287 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7288 otherwise.
7289 @end multitable
7290
7291 @item @emph{See also}:
7292 @ref{ABORT}, @ref{EXIT}
7293 @end table
7294
7295
7296
7297 @node KIND
7298 @section @code{KIND} --- Kind of an entity
7299 @fnindex KIND
7300 @cindex kind
7301
7302 @table @asis
7303 @item @emph{Description}:
7304 @code{KIND(X)} returns the kind value of the entity @var{X}.
7305
7306 @item @emph{Standard}:
7307 Fortran 95 and later
7308
7309 @item @emph{Class}:
7310 Inquiry function
7311
7312 @item @emph{Syntax}:
7313 @code{K = KIND(X)}
7314
7315 @item @emph{Arguments}:
7316 @multitable @columnfractions .15 .70
7317 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7318 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7319 @end multitable
7320
7321 @item @emph{Return value}:
7322 The return value is a scalar of type @code{INTEGER} and of the default
7323 integer kind.
7324
7325 @item @emph{Example}:
7326 @smallexample
7327 program test_kind
7328   integer,parameter :: kc = kind(' ')
7329   integer,parameter :: kl = kind(.true.)
7330
7331   print *, "The default character kind is ", kc
7332   print *, "The default logical kind is ", kl
7333 end program test_kind
7334 @end smallexample
7335
7336 @end table
7337
7338
7339
7340 @node LBOUND
7341 @section @code{LBOUND} --- Lower dimension bounds of an array
7342 @fnindex LBOUND
7343 @cindex array, lower bound
7344
7345 @table @asis
7346 @item @emph{Description}:
7347 Returns the lower bounds of an array, or a single lower bound
7348 along the @var{DIM} dimension.
7349 @item @emph{Standard}:
7350 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7351
7352 @item @emph{Class}:
7353 Inquiry function
7354
7355 @item @emph{Syntax}:
7356 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7357
7358 @item @emph{Arguments}:
7359 @multitable @columnfractions .15 .70
7360 @item @var{ARRAY} @tab Shall be an array, of any type.
7361 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7362 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7363 expression indicating the kind parameter of the result.
7364 @end multitable
7365
7366 @item @emph{Return value}:
7367 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7368 @var{KIND} is absent, the return value is of default integer kind.
7369 If @var{DIM} is absent, the result is an array of the lower bounds of
7370 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
7371 corresponding to the lower bound of the array along that dimension.  If
7372 @var{ARRAY} is an expression rather than a whole array or array
7373 structure component, or if it has a zero extent along the relevant
7374 dimension, the lower bound is taken to be 1.
7375
7376 @item @emph{See also}:
7377 @ref{UBOUND}, @ref{LCOBOUND}
7378 @end table
7379
7380
7381
7382 @node LCOBOUND
7383 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7384 @fnindex LCOBOUND
7385 @cindex coarray, lower bound
7386
7387 @table @asis
7388 @item @emph{Description}:
7389 Returns the lower bounds of a coarray, or a single lower cobound
7390 along the @var{DIM} codimension.
7391 @item @emph{Standard}:
7392 Fortran 2008 and later
7393
7394 @item @emph{Class}:
7395 Inquiry function
7396
7397 @item @emph{Syntax}:
7398 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7399
7400 @item @emph{Arguments}:
7401 @multitable @columnfractions .15 .70
7402 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7403 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7404 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7405 expression indicating the kind parameter of the result.
7406 @end multitable
7407
7408 @item @emph{Return value}:
7409 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7410 @var{KIND} is absent, the return value is of default integer kind.
7411 If @var{DIM} is absent, the result is an array of the lower cobounds of
7412 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
7413 corresponding to the lower cobound of the array along that codimension.
7414
7415 @item @emph{See also}:
7416 @ref{UCOBOUND}, @ref{LBOUND}
7417 @end table
7418
7419
7420
7421 @node LEADZ
7422 @section @code{LEADZ} --- Number of leading zero bits of an integer
7423 @fnindex LEADZ
7424 @cindex zero bits
7425
7426 @table @asis
7427 @item @emph{Description}:
7428 @code{LEADZ} returns the number of leading zero bits of an integer.
7429
7430 @item @emph{Standard}:
7431 Fortran 2008 and later
7432
7433 @item @emph{Class}:
7434 Elemental function
7435
7436 @item @emph{Syntax}:
7437 @code{RESULT = LEADZ(I)}
7438
7439 @item @emph{Arguments}:
7440 @multitable @columnfractions .15 .70
7441 @item @var{I} @tab Shall be of type @code{INTEGER}.
7442 @end multitable
7443
7444 @item @emph{Return value}:
7445 The type of the return value is the default @code{INTEGER}.
7446 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7447
7448 @item @emph{Example}:
7449 @smallexample
7450 PROGRAM test_leadz
7451   WRITE (*,*) BIT_SIZE(1)  ! prints 32
7452   WRITE (*,*) LEADZ(1)     ! prints 31
7453 END PROGRAM
7454 @end smallexample
7455
7456 @item @emph{See also}:
7457 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7458 @end table
7459
7460
7461
7462 @node LEN
7463 @section @code{LEN} --- Length of a character entity
7464 @fnindex LEN
7465 @cindex string, length
7466
7467 @table @asis
7468 @item @emph{Description}:
7469 Returns the length of a character string.  If @var{STRING} is an array,
7470 the length of an element of @var{STRING} is returned.  Note that
7471 @var{STRING} need not be defined when this intrinsic is invoked, since
7472 only the length, not the content, of @var{STRING} is needed.
7473
7474 @item @emph{Standard}:
7475 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7476
7477 @item @emph{Class}:
7478 Inquiry function
7479
7480 @item @emph{Syntax}:
7481 @code{L = LEN(STRING [, KIND])}
7482
7483 @item @emph{Arguments}:
7484 @multitable @columnfractions .15 .70
7485 @item @var{STRING} @tab Shall be a scalar or array of type
7486 @code{CHARACTER}, with @code{INTENT(IN)}
7487 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7488 expression indicating the kind parameter of the result.
7489 @end multitable
7490
7491 @item @emph{Return value}:
7492 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7493 @var{KIND} is absent, the return value is of default integer kind.
7494
7495
7496 @item @emph{Specific names}:
7497 @multitable @columnfractions .20 .20 .20 .25
7498 @item Name               @tab Argument          @tab Return type       @tab Standard
7499 @item @code{LEN(STRING)} @tab @code{CHARACTER}  @tab @code{INTEGER}    @tab Fortran 77 and later
7500 @end multitable
7501
7502
7503 @item @emph{See also}:
7504 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7505 @end table
7506
7507
7508
7509 @node LEN_TRIM
7510 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7511 @fnindex LEN_TRIM
7512 @cindex string, length, without trailing whitespace
7513
7514 @table @asis
7515 @item @emph{Description}:
7516 Returns the length of a character string, ignoring any trailing blanks.
7517
7518 @item @emph{Standard}:
7519 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7520
7521 @item @emph{Class}:
7522 Elemental function
7523
7524 @item @emph{Syntax}:
7525 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7526
7527 @item @emph{Arguments}:
7528 @multitable @columnfractions .15 .70
7529 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7530 with @code{INTENT(IN)}
7531 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7532 expression indicating the kind parameter of the result.
7533 @end multitable
7534
7535 @item @emph{Return value}:
7536 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7537 @var{KIND} is absent, the return value is of default integer kind.
7538
7539 @item @emph{See also}:
7540 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7541 @end table
7542
7543
7544
7545 @node LGE
7546 @section @code{LGE} --- Lexical greater than or equal
7547 @fnindex LGE
7548 @cindex lexical comparison of strings
7549 @cindex string, comparison
7550
7551 @table @asis
7552 @item @emph{Description}:
7553 Determines whether one string is lexically greater than or equal to
7554 another string, where the two strings are interpreted as containing
7555 ASCII character codes.  If the String A and String B are not the same
7556 length, the shorter is compared as if spaces were appended to it to form
7557 a value that has the same length as the longer.
7558
7559 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7560 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7561 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7562 that the latter use the processor's character ordering (which is not
7563 ASCII on some targets), whereas the former always use the ASCII
7564 ordering.
7565
7566 @item @emph{Standard}:
7567 Fortran 77 and later
7568
7569 @item @emph{Class}:
7570 Elemental function
7571
7572 @item @emph{Syntax}:
7573 @code{RESULT = LGE(STRING_A, STRING_B)}
7574
7575 @item @emph{Arguments}:
7576 @multitable @columnfractions .15 .70
7577 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7578 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7579 @end multitable
7580
7581 @item @emph{Return value}:
7582 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7583 otherwise, based on the ASCII ordering.
7584
7585 @item @emph{Specific names}:
7586 @multitable @columnfractions .20 .20 .20 .25
7587 @item Name                           @tab Argument          @tab Return type       @tab Standard
7588 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7589 @end multitable
7590
7591 @item @emph{See also}:
7592 @ref{LGT}, @ref{LLE}, @ref{LLT}
7593 @end table
7594
7595
7596
7597 @node LGT
7598 @section @code{LGT} --- Lexical greater than
7599 @fnindex LGT
7600 @cindex lexical comparison of strings
7601 @cindex string, comparison
7602
7603 @table @asis
7604 @item @emph{Description}:
7605 Determines whether one string is lexically greater than another string,
7606 where the two strings are interpreted as containing ASCII character
7607 codes.  If the String A and String B are not the same length, the
7608 shorter is compared as if spaces were appended to it to form a value
7609 that has the same length as the longer.
7610
7611 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7612 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7613 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7614 that the latter use the processor's character ordering (which is not
7615 ASCII on some targets), whereas the former always use the ASCII
7616 ordering.
7617
7618 @item @emph{Standard}:
7619 Fortran 77 and later
7620
7621 @item @emph{Class}:
7622 Elemental function
7623
7624 @item @emph{Syntax}:
7625 @code{RESULT = LGT(STRING_A, STRING_B)}
7626
7627 @item @emph{Arguments}:
7628 @multitable @columnfractions .15 .70
7629 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7630 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7631 @end multitable
7632
7633 @item @emph{Return value}:
7634 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7635 otherwise, based on the ASCII ordering.
7636
7637 @item @emph{Specific names}:
7638 @multitable @columnfractions .20 .20 .20 .25
7639 @item Name                           @tab Argument          @tab Return type       @tab Standard
7640 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7641 @end multitable
7642
7643 @item @emph{See also}:
7644 @ref{LGE}, @ref{LLE}, @ref{LLT}
7645 @end table
7646
7647
7648
7649 @node LINK
7650 @section @code{LINK} --- Create a hard link
7651 @fnindex LINK
7652 @cindex file system, create link
7653 @cindex file system, hard link
7654
7655 @table @asis
7656 @item @emph{Description}:
7657 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7658 character (@code{CHAR(0)}) can be used to mark the end of the names in
7659 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7660 names are ignored.  If the @var{STATUS} argument is supplied, it
7661 contains 0 on success or a nonzero error code upon return; see
7662 @code{link(2)}.
7663
7664 This intrinsic is provided in both subroutine and function forms;
7665 however, only one form can be used in any given program unit.
7666
7667 @item @emph{Standard}:
7668 GNU extension
7669
7670 @item @emph{Class}:
7671 Subroutine, function
7672
7673 @item @emph{Syntax}:
7674 @multitable @columnfractions .80
7675 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7676 @item @code{STATUS = LINK(PATH1, PATH2)}
7677 @end multitable
7678
7679 @item @emph{Arguments}:
7680 @multitable @columnfractions .15 .70
7681 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7682 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7683 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7684 @end multitable
7685
7686 @item @emph{See also}:
7687 @ref{SYMLNK}, @ref{UNLINK}
7688 @end table
7689
7690
7691
7692 @node LLE
7693 @section @code{LLE} --- Lexical less than or equal
7694 @fnindex LLE
7695 @cindex lexical comparison of strings
7696 @cindex string, comparison
7697
7698 @table @asis
7699 @item @emph{Description}:
7700 Determines whether one string is lexically less than or equal to another
7701 string, where the two strings are interpreted as containing ASCII
7702 character codes.  If the String A and String B are not the same length,
7703 the shorter is compared as if spaces were appended to it to form a value
7704 that has the same length as the longer.
7705
7706 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7707 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7708 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7709 that the latter use the processor's character ordering (which is not
7710 ASCII on some targets), whereas the former always use the ASCII
7711 ordering.
7712
7713 @item @emph{Standard}:
7714 Fortran 77 and later
7715
7716 @item @emph{Class}:
7717 Elemental function
7718
7719 @item @emph{Syntax}:
7720 @code{RESULT = LLE(STRING_A, STRING_B)}
7721
7722 @item @emph{Arguments}:
7723 @multitable @columnfractions .15 .70
7724 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7725 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7726 @end multitable
7727
7728 @item @emph{Return value}:
7729 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7730 otherwise, based on the ASCII ordering.
7731
7732 @item @emph{Specific names}:
7733 @multitable @columnfractions .20 .20 .20 .25
7734 @item Name                           @tab Argument          @tab Return type       @tab Standard
7735 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7736 @end multitable
7737
7738 @item @emph{See also}:
7739 @ref{LGE}, @ref{LGT}, @ref{LLT}
7740 @end table
7741
7742
7743
7744 @node LLT
7745 @section @code{LLT} --- Lexical less than
7746 @fnindex LLT
7747 @cindex lexical comparison of strings
7748 @cindex string, comparison
7749
7750 @table @asis
7751 @item @emph{Description}:
7752 Determines whether one string is lexically less than another string,
7753 where the two strings are interpreted as containing ASCII character
7754 codes.  If the String A and String B are not the same length, the
7755 shorter is compared as if spaces were appended to it to form a value
7756 that has the same length as the longer.
7757
7758 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7759 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7760 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7761 that the latter use the processor's character ordering (which is not
7762 ASCII on some targets), whereas the former always use the ASCII
7763 ordering.
7764
7765 @item @emph{Standard}:
7766 Fortran 77 and later
7767
7768 @item @emph{Class}:
7769 Elemental function
7770
7771 @item @emph{Syntax}:
7772 @code{RESULT = LLT(STRING_A, STRING_B)}
7773
7774 @item @emph{Arguments}:
7775 @multitable @columnfractions .15 .70
7776 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7777 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7778 @end multitable
7779
7780 @item @emph{Return value}:
7781 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7782 otherwise, based on the ASCII ordering.
7783
7784 @item @emph{Specific names}:
7785 @multitable @columnfractions .20 .20 .20 .25
7786 @item Name                           @tab Argument          @tab Return type       @tab Standard
7787 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER}  @tab @code{LOGICAL}    @tab Fortran 77 and later
7788 @end multitable
7789
7790 @item @emph{See also}:
7791 @ref{LGE}, @ref{LGT}, @ref{LLE}
7792 @end table
7793
7794
7795
7796 @node LNBLNK
7797 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7798 @fnindex LNBLNK
7799 @cindex string, find non-blank character
7800
7801 @table @asis
7802 @item @emph{Description}:
7803 Returns the length of a character string, ignoring any trailing blanks.
7804 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7805 included for backwards compatibility.
7806
7807 @item @emph{Standard}:
7808 GNU extension
7809
7810 @item @emph{Class}:
7811 Elemental function
7812
7813 @item @emph{Syntax}:
7814 @code{RESULT = LNBLNK(STRING)}
7815
7816 @item @emph{Arguments}:
7817 @multitable @columnfractions .15 .70
7818 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7819 with @code{INTENT(IN)}
7820 @end multitable
7821
7822 @item @emph{Return value}:
7823 The return value is of @code{INTEGER(kind=4)} type.
7824
7825 @item @emph{See also}:
7826 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7827 @end table
7828
7829
7830
7831 @node LOC
7832 @section @code{LOC} --- Returns the address of a variable
7833 @fnindex LOC
7834 @cindex location of a variable in memory
7835
7836 @table @asis
7837 @item @emph{Description}:
7838 @code{LOC(X)} returns the address of @var{X} as an integer.
7839
7840 @item @emph{Standard}:
7841 GNU extension
7842
7843 @item @emph{Class}:
7844 Inquiry function
7845
7846 @item @emph{Syntax}:
7847 @code{RESULT = LOC(X)}
7848
7849 @item @emph{Arguments}:
7850 @multitable @columnfractions .15 .70
7851 @item @var{X} @tab Variable of any type.
7852 @end multitable
7853
7854 @item @emph{Return value}:
7855 The return value is of type @code{INTEGER}, with a @code{KIND}
7856 corresponding to the size (in bytes) of a memory address on the target
7857 machine.
7858
7859 @item @emph{Example}:
7860 @smallexample
7861 program test_loc
7862   integer :: i
7863   real :: r
7864   i = loc(r)
7865   print *, i
7866 end program test_loc
7867 @end smallexample
7868 @end table
7869
7870
7871
7872 @node LOG
7873 @section @code{LOG} --- Natural logarithm function
7874 @fnindex LOG
7875 @fnindex ALOG
7876 @fnindex DLOG
7877 @fnindex CLOG
7878 @fnindex ZLOG
7879 @fnindex CDLOG
7880 @cindex exponential function, inverse
7881 @cindex logarithm function
7882 @cindex natural logarithm function
7883
7884 @table @asis
7885 @item @emph{Description}:
7886 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7887 logarithm to the base @math{e}.
7888
7889 @item @emph{Standard}:
7890 Fortran 77 and later
7891
7892 @item @emph{Class}:
7893 Elemental function
7894
7895 @item @emph{Syntax}:
7896 @code{RESULT = LOG(X)}
7897
7898 @item @emph{Arguments}:
7899 @multitable @columnfractions .15 .70
7900 @item @var{X} @tab The type shall be @code{REAL} or
7901 @code{COMPLEX}.
7902 @end multitable
7903
7904 @item @emph{Return value}:
7905 The return value is of type @code{REAL} or @code{COMPLEX}.
7906 The kind type parameter is the same as @var{X}.
7907 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7908 @math{-\pi \leq \omega \leq \pi}.
7909
7910 @item @emph{Example}:
7911 @smallexample
7912 program test_log
7913   real(8) :: x = 2.7182818284590451_8
7914   complex :: z = (1.0, 2.0)
7915   x = log(x)    ! will yield (approximately) 1
7916   z = log(z)
7917 end program test_log
7918 @end smallexample
7919
7920 @item @emph{Specific names}:
7921 @multitable @columnfractions .20 .20 .20 .25
7922 @item Name            @tab Argument          @tab Return type       @tab Standard
7923 @item @code{ALOG(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab f95, gnu
7924 @item @code{DLOG(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab f95, gnu
7925 @item @code{CLOG(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab f95, gnu
7926 @item @code{ZLOG(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7927 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab f95, gnu
7928 @end multitable
7929 @end table
7930
7931
7932
7933 @node LOG10
7934 @section @code{LOG10} --- Base 10 logarithm function
7935 @fnindex LOG10
7936 @fnindex ALOG10
7937 @fnindex DLOG10
7938 @cindex exponential function, inverse
7939 @cindex logarithm function with base 10
7940 @cindex base 10 logarithm function
7941
7942 @table @asis
7943 @item @emph{Description}:
7944 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7945
7946 @item @emph{Standard}:
7947 Fortran 77 and later
7948
7949 @item @emph{Class}:
7950 Elemental function
7951
7952 @item @emph{Syntax}:
7953 @code{RESULT = LOG10(X)}
7954
7955 @item @emph{Arguments}:
7956 @multitable @columnfractions .15 .70
7957 @item @var{X} @tab The type shall be @code{REAL}.
7958 @end multitable
7959
7960 @item @emph{Return value}:
7961 The return value is of type @code{REAL} or @code{COMPLEX}.
7962 The kind type parameter is the same as @var{X}.
7963
7964 @item @emph{Example}:
7965 @smallexample
7966 program test_log10
7967   real(8) :: x = 10.0_8
7968   x = log10(x)
7969 end program test_log10
7970 @end smallexample
7971
7972 @item @emph{Specific names}:
7973 @multitable @columnfractions .20 .20 .20 .25
7974 @item Name            @tab Argument          @tab Return type       @tab Standard
7975 @item @code{ALOG10(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
7976 @item @code{DLOG10(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
7977 @end multitable
7978 @end table
7979
7980
7981
7982 @node LOG_GAMMA
7983 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7984 @fnindex LOG_GAMMA
7985 @fnindex LGAMMA
7986 @fnindex ALGAMA
7987 @fnindex DLGAMA
7988 @cindex Gamma function, logarithm of
7989
7990 @table @asis
7991 @item @emph{Description}:
7992 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7993 of the Gamma (@math{\Gamma}) function.
7994
7995 @item @emph{Standard}:
7996 Fortran 2008 and later
7997
7998 @item @emph{Class}:
7999 Elemental function
8000
8001 @item @emph{Syntax}:
8002 @code{X = LOG_GAMMA(X)}
8003
8004 @item @emph{Arguments}:
8005 @multitable @columnfractions .15 .70
8006 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8007 nor a negative integer.
8008 @end multitable
8009
8010 @item @emph{Return value}:
8011 The return value is of type @code{REAL} of the same kind as @var{X}.
8012
8013 @item @emph{Example}:
8014 @smallexample
8015 program test_log_gamma
8016   real :: x = 1.0
8017   x = lgamma(x) ! returns 0.0
8018 end program test_log_gamma
8019 @end smallexample
8020
8021 @item @emph{Specific names}:
8022 @multitable @columnfractions .20 .20 .20 .25
8023 @item Name             @tab Argument         @tab Return type       @tab Standard
8024 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
8025 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)}    @tab GNU Extension
8026 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)}    @tab GNU Extension
8027 @end multitable
8028
8029 @item @emph{See also}:
8030 Gamma function: @ref{GAMMA}
8031
8032 @end table
8033
8034
8035
8036 @node LOGICAL
8037 @section @code{LOGICAL} --- Convert to logical type
8038 @fnindex LOGICAL
8039 @cindex conversion, to logical
8040
8041 @table @asis
8042 @item @emph{Description}:
8043 Converts one kind of @code{LOGICAL} variable to another.
8044
8045 @item @emph{Standard}:
8046 Fortran 95 and later
8047
8048 @item @emph{Class}:
8049 Elemental function
8050
8051 @item @emph{Syntax}:
8052 @code{RESULT = LOGICAL(L [, KIND])}
8053
8054 @item @emph{Arguments}:
8055 @multitable @columnfractions .15 .70
8056 @item @var{L}    @tab The type shall be @code{LOGICAL}.
8057 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8058 expression indicating the kind parameter of the result.
8059 @end multitable
8060
8061 @item @emph{Return value}:
8062 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8063 kind corresponding to @var{KIND}, or of the default logical kind if
8064 @var{KIND} is not given.
8065
8066 @item @emph{See also}:
8067 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8068 @end table
8069
8070
8071
8072 @node LONG
8073 @section @code{LONG} --- Convert to integer type
8074 @fnindex LONG
8075 @cindex conversion, to integer
8076
8077 @table @asis
8078 @item @emph{Description}:
8079 Convert to a @code{KIND=4} integer type, which is the same size as a C
8080 @code{long} integer.  This is equivalent to the standard @code{INT}
8081 intrinsic with an optional argument of @code{KIND=4}, and is only
8082 included for backwards compatibility.
8083
8084 @item @emph{Standard}:
8085 GNU extension
8086
8087 @item @emph{Class}:
8088 Elemental function
8089
8090 @item @emph{Syntax}:
8091 @code{RESULT = LONG(A)}
8092
8093 @item @emph{Arguments}:
8094 @multitable @columnfractions .15 .70
8095 @item @var{A}    @tab Shall be of type @code{INTEGER},
8096 @code{REAL}, or @code{COMPLEX}.
8097 @end multitable
8098
8099 @item @emph{Return value}:
8100 The return value is a @code{INTEGER(4)} variable.
8101
8102 @item @emph{See also}:
8103 @ref{INT}, @ref{INT2}, @ref{INT8}
8104 @end table
8105
8106
8107
8108 @node LSHIFT
8109 @section @code{LSHIFT} --- Left shift bits
8110 @fnindex LSHIFT
8111 @cindex bits, shift left
8112
8113 @table @asis
8114 @item @emph{Description}:
8115 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8116 bits shifted left by @var{SHIFT} places.  If the absolute value of
8117 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8118 Bits shifted out from the left end are lost; zeros are shifted in from
8119 the opposite end.
8120
8121 This function has been superseded by the @code{ISHFT} intrinsic, which
8122 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8123 which is standard in Fortran 2008 and later.
8124
8125 @item @emph{Standard}:
8126 GNU extension
8127
8128 @item @emph{Class}:
8129 Elemental function
8130
8131 @item @emph{Syntax}:
8132 @code{RESULT = LSHIFT(I, SHIFT)}
8133
8134 @item @emph{Arguments}:
8135 @multitable @columnfractions .15 .70
8136 @item @var{I} @tab The type shall be @code{INTEGER}.
8137 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8138 @end multitable
8139
8140 @item @emph{Return value}:
8141 The return value is of type @code{INTEGER} and of the same kind as
8142 @var{I}.
8143
8144 @item @emph{See also}:
8145 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8146 @ref{SHIFTR}
8147
8148 @end table
8149
8150
8151
8152 @node LSTAT
8153 @section @code{LSTAT} --- Get file status
8154 @fnindex LSTAT
8155 @cindex file system, file status
8156
8157 @table @asis
8158 @item @emph{Description}:
8159 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8160 symbolic link, then the link itself is statted, not the file that it
8161 refers to.
8162
8163 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8164
8165 This intrinsic is provided in both subroutine and function forms;
8166 however, only one form can be used in any given program unit.
8167
8168 @item @emph{Standard}:
8169 GNU extension
8170
8171 @item @emph{Class}:
8172 Subroutine, function
8173
8174 @item @emph{Syntax}:
8175 @multitable @columnfractions .80
8176 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8177 @item @code{STATUS = LSTAT(NAME, VALUES)}
8178 @end multitable
8179
8180 @item @emph{Arguments}:
8181 @multitable @columnfractions .15 .70
8182 @item @var{NAME}   @tab The type shall be @code{CHARACTER} of the default
8183 kind, a valid path within the file system.
8184 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8185 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8186 Returns 0 on success and a system specific error code otherwise.
8187 @end multitable
8188
8189 @item @emph{Example}:
8190 See @ref{STAT} for an example.
8191
8192 @item @emph{See also}:
8193 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8194 @end table
8195
8196
8197
8198 @node LTIME
8199 @section @code{LTIME} --- Convert time to local time info
8200 @fnindex LTIME
8201 @cindex time, conversion to local time info
8202
8203 @table @asis
8204 @item @emph{Description}:
8205 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8206 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8207 to the local time zone using @code{localtime(3)}.
8208
8209 @item @emph{Standard}:
8210 GNU extension
8211
8212 @item @emph{Class}:
8213 Subroutine
8214
8215 @item @emph{Syntax}:
8216 @code{CALL LTIME(TIME, VALUES)}
8217
8218 @item @emph{Arguments}:
8219 @multitable @columnfractions .15 .70
8220 @item @var{TIME}  @tab An @code{INTEGER} scalar expression
8221 corresponding to a system time, with @code{INTENT(IN)}.
8222 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8223 with @code{INTENT(OUT)}.
8224 @end multitable
8225
8226 @item @emph{Return value}:
8227 The elements of @var{VALUES} are assigned as follows:
8228 @enumerate
8229 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8230 seconds
8231 @item Minutes after the hour, range 0--59
8232 @item Hours past midnight, range 0--23
8233 @item Day of month, range 0--31
8234 @item Number of months since January, range 0--12
8235 @item Years since 1900
8236 @item Number of days since Sunday, range 0--6
8237 @item Days since January 1
8238 @item Daylight savings indicator: positive if daylight savings is in
8239 effect, zero if not, and negative if the information is not available.
8240 @end enumerate
8241
8242 @item @emph{See also}:
8243 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8244
8245 @end table
8246
8247
8248
8249 @node MALLOC
8250 @section @code{MALLOC} --- Allocate dynamic memory
8251 @fnindex MALLOC
8252 @cindex pointer, cray
8253
8254 @table @asis
8255 @item @emph{Description}:
8256 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8257 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8258 is an extension intended to be used with Cray pointers, and is provided
8259 in GNU Fortran to allow the user to compile legacy code. For new code
8260 using Fortran 95 pointers, the memory allocation intrinsic is
8261 @code{ALLOCATE}.
8262
8263 @item @emph{Standard}:
8264 GNU extension
8265
8266 @item @emph{Class}:
8267 Function
8268
8269 @item @emph{Syntax}:
8270 @code{PTR = MALLOC(SIZE)}
8271
8272 @item @emph{Arguments}:
8273 @multitable @columnfractions .15 .70
8274 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8275 @end multitable
8276
8277 @item @emph{Return value}:
8278 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8279 variables of type @code{INTEGER(K)} have the same size as
8280 C pointers (@code{sizeof(void *)}).
8281
8282 @item @emph{Example}:
8283 The following example demonstrates the use of @code{MALLOC} and
8284 @code{FREE} with Cray pointers.
8285
8286 @smallexample
8287 program test_malloc
8288   implicit none
8289   integer i
8290   real*8 x(*), z
8291   pointer(ptr_x,x)
8292
8293   ptr_x = malloc(20*8)
8294   do i = 1, 20
8295     x(i) = sqrt(1.0d0 / i)
8296   end do
8297   z = 0
8298   do i = 1, 20
8299     z = z + x(i)
8300     print *, z
8301   end do
8302   call free(ptr_x)
8303 end program test_malloc
8304 @end smallexample
8305
8306 @item @emph{See also}:
8307 @ref{FREE}
8308 @end table
8309
8310
8311
8312 @node MASKL
8313 @section @code{MASKL} --- Left justified mask
8314 @fnindex MASKL
8315 @cindex mask, left justified
8316
8317 @table @asis
8318 @item @emph{Description}:
8319 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8320 remaining bits set to 0.
8321
8322 @item @emph{Standard}:
8323 Fortran 2008 and later
8324
8325 @item @emph{Class}:
8326 Elemental function
8327
8328 @item @emph{Syntax}:
8329 @code{RESULT = MASKL(I[, KIND])}
8330
8331 @item @emph{Arguments}:
8332 @multitable @columnfractions .15 .70
8333 @item @var{I} @tab Shall be of type @code{INTEGER}.
8334 @item @var{KIND} @tab Shall be a scalar constant expression of type
8335 @code{INTEGER}.
8336 @end multitable
8337
8338 @item @emph{Return value}:
8339 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8340 specifies the kind value of the return type; otherwise, it is of the
8341 default integer kind.
8342
8343 @item @emph{See also}:
8344 @ref{MASKR}
8345 @end table
8346
8347
8348
8349 @node MASKR
8350 @section @code{MASKR} --- Right justified mask
8351 @fnindex MASKR
8352 @cindex mask, right justified
8353
8354 @table @asis
8355 @item @emph{Description}:
8356 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8357 remaining bits set to 0.
8358
8359 @item @emph{Standard}:
8360 Fortran 2008 and later
8361
8362 @item @emph{Class}:
8363 Elemental function
8364
8365 @item @emph{Syntax}:
8366 @code{RESULT = MASKR(I[, KIND])}
8367
8368 @item @emph{Arguments}:
8369 @multitable @columnfractions .15 .70
8370 @item @var{I} @tab Shall be of type @code{INTEGER}.
8371 @item @var{KIND} @tab Shall be a scalar constant expression of type
8372 @code{INTEGER}.
8373 @end multitable
8374
8375 @item @emph{Return value}:
8376 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8377 specifies the kind value of the return type; otherwise, it is of the
8378 default integer kind.
8379
8380 @item @emph{See also}:
8381 @ref{MASKL}
8382 @end table
8383
8384
8385
8386 @node MATMUL
8387 @section @code{MATMUL} --- matrix multiplication
8388 @fnindex MATMUL
8389 @cindex matrix multiplication
8390 @cindex product, matrix
8391
8392 @table @asis
8393 @item @emph{Description}:
8394 Performs a matrix multiplication on numeric or logical arguments.
8395
8396 @item @emph{Standard}:
8397 Fortran 95 and later
8398
8399 @item @emph{Class}:
8400 Transformational function
8401
8402 @item @emph{Syntax}:
8403 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8404
8405 @item @emph{Arguments}:
8406 @multitable @columnfractions .15 .70
8407 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8408 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8409 one or two.
8410 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8411 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8412 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8413 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8414 equal to the last (or only) dimension of @var{MATRIX_A}.
8415 @end multitable
8416
8417 @item @emph{Return value}:
8418 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}.  The type and
8419 kind of the result follow the usual type and kind promotion rules, as
8420 for the @code{*} or @code{.AND.} operators.
8421
8422 @item @emph{See also}:
8423 @end table
8424
8425
8426
8427 @node MAX
8428 @section @code{MAX} --- Maximum value of an argument list
8429 @fnindex MAX
8430 @fnindex MAX0
8431 @fnindex AMAX0
8432 @fnindex MAX1
8433 @fnindex AMAX1
8434 @fnindex DMAX1
8435 @cindex maximum value
8436
8437 @table @asis
8438 @item @emph{Description}:
8439 Returns the argument with the largest (most positive) value.
8440
8441 @item @emph{Standard}:
8442 Fortran 77 and later
8443
8444 @item @emph{Class}:
8445 Elemental function
8446
8447 @item @emph{Syntax}:
8448 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8449
8450 @item @emph{Arguments}:
8451 @multitable @columnfractions .15 .70
8452 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8453 @code{REAL}.
8454 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8455 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8456 permitted.)
8457 @end multitable
8458
8459 @item @emph{Return value}:
8460 The return value corresponds to the maximum value among the arguments,
8461 and has the same type and kind as the first argument.
8462
8463 @item @emph{Specific names}:
8464 @multitable @columnfractions .20 .20 .20 .25
8465 @item Name             @tab Argument             @tab Return type         @tab Standard
8466 @item @code{MAX0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}   @tab Fortran 77 and later
8467 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8468 @item @code{MAX1(A1)}  @tab @code{REAL A1}       @tab @code{INT(MAX(X))}  @tab Fortran 77 and later
8469 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1}    @tab @code{REAL(4)}      @tab Fortran 77 and later
8470 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1}    @tab @code{REAL(8)}      @tab Fortran 77 and later
8471 @end multitable
8472
8473 @item @emph{See also}:
8474 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8475
8476 @end table
8477
8478
8479
8480 @node MAXEXPONENT
8481 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8482 @fnindex MAXEXPONENT
8483 @cindex model representation, maximum exponent
8484
8485 @table @asis
8486 @item @emph{Description}:
8487 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8488 type of @code{X}.
8489
8490 @item @emph{Standard}:
8491 Fortran 95 and later
8492
8493 @item @emph{Class}:
8494 Inquiry function
8495
8496 @item @emph{Syntax}:
8497 @code{RESULT = MAXEXPONENT(X)}
8498
8499 @item @emph{Arguments}:
8500 @multitable @columnfractions .15 .70
8501 @item @var{X} @tab Shall be of type @code{REAL}.
8502 @end multitable
8503
8504 @item @emph{Return value}:
8505 The return value is of type @code{INTEGER} and of the default integer
8506 kind.
8507
8508 @item @emph{Example}:
8509 @smallexample
8510 program exponents
8511   real(kind=4) :: x
8512   real(kind=8) :: y
8513
8514   print *, minexponent(x), maxexponent(x)
8515   print *, minexponent(y), maxexponent(y)
8516 end program exponents
8517 @end smallexample
8518 @end table
8519
8520
8521
8522 @node MAXLOC
8523 @section @code{MAXLOC} --- Location of the maximum value within an array
8524 @fnindex MAXLOC
8525 @cindex array, location of maximum element
8526
8527 @table @asis
8528 @item @emph{Description}:
8529 Determines the location of the element in the array with the maximum
8530 value, or, if the @var{DIM} argument is supplied, determines the
8531 locations of the maximum element along each row of the array in the
8532 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8533 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8534 element in the array has the maximum value, the location returned is
8535 that of the first such element in array element order.  If the array has
8536 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8537 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8538 and all of the elements of @var{MASK} along a given row are zero, the
8539 result value for that row is zero.
8540
8541 @item @emph{Standard}:
8542 Fortran 95 and later
8543
8544 @item @emph{Class}:
8545 Transformational function
8546
8547 @item @emph{Syntax}:
8548 @multitable @columnfractions .80
8549 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8550 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8551 @end multitable
8552
8553 @item @emph{Arguments}:
8554 @multitable @columnfractions .15 .70
8555 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8556 @code{REAL}.
8557 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8558 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8559 inclusive.  It may not be an optional dummy argument.
8560 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8561 and conformable with @var{ARRAY}.
8562 @end multitable
8563
8564 @item @emph{Return value}:
8565 If @var{DIM} is absent, the result is a rank-one array with a length
8566 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8567 is an array with a rank one less than the rank of @var{ARRAY}, and a
8568 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8569 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8570 of one, the result is a scalar.  In all cases, the result is of default
8571 @code{INTEGER} type.
8572
8573 @item @emph{See also}:
8574 @ref{MAX}, @ref{MAXVAL}
8575
8576 @end table
8577
8578
8579
8580 @node MAXVAL
8581 @section @code{MAXVAL} --- Maximum value of an array
8582 @fnindex MAXVAL
8583 @cindex array, maximum value
8584 @cindex maximum value
8585
8586 @table @asis
8587 @item @emph{Description}:
8588 Determines the maximum value of the elements in an array value, or, if
8589 the @var{DIM} argument is supplied, determines the maximum value along
8590 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8591 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8592 considered.  If the array has zero size, or all of the elements of
8593 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8594 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8595 type.
8596
8597 @item @emph{Standard}:
8598 Fortran 95 and later
8599
8600 @item @emph{Class}:
8601 Transformational function
8602
8603 @item @emph{Syntax}:
8604 @multitable @columnfractions .80
8605 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8606 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8607 @end multitable
8608
8609 @item @emph{Arguments}:
8610 @multitable @columnfractions .15 .70
8611 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8612 @code{REAL}.
8613 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8614 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8615 inclusive.  It may not be an optional dummy argument.
8616 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8617 and conformable with @var{ARRAY}.
8618 @end multitable
8619
8620 @item @emph{Return value}:
8621 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8622 is a scalar.  If @var{DIM} is present, the result is an array with a
8623 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8624 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8625 cases, the result is of the same type and kind as @var{ARRAY}.
8626
8627 @item @emph{See also}:
8628 @ref{MAX}, @ref{MAXLOC}
8629 @end table
8630
8631
8632
8633 @node MCLOCK
8634 @section @code{MCLOCK} --- Time function
8635 @fnindex MCLOCK
8636 @cindex time, clock ticks
8637 @cindex clock ticks
8638
8639 @table @asis
8640 @item @emph{Description}:
8641 Returns the number of clock ticks since the start of the process, based
8642 on the UNIX function @code{clock(3)}.
8643
8644 This intrinsic is not fully portable, such as to systems with 32-bit
8645 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8646 the values returned by this intrinsic might be, or become, negative, or
8647 numerically less than previous values, during a single run of the
8648 compiled program.
8649
8650 @item @emph{Standard}:
8651 GNU extension
8652
8653 @item @emph{Class}:
8654 Function
8655
8656 @item @emph{Syntax}:
8657 @code{RESULT = MCLOCK()}
8658
8659 @item @emph{Return value}:
8660 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8661 number of clock ticks since the start of the process, or @code{-1} if
8662 the system does not support @code{clock(3)}.
8663
8664 @item @emph{See also}:
8665 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8666
8667 @end table
8668
8669
8670
8671 @node MCLOCK8
8672 @section @code{MCLOCK8} --- Time function (64-bit)
8673 @fnindex MCLOCK8
8674 @cindex time, clock ticks
8675 @cindex clock ticks
8676
8677 @table @asis
8678 @item @emph{Description}:
8679 Returns the number of clock ticks since the start of the process, based
8680 on the UNIX function @code{clock(3)}.
8681
8682 @emph{Warning:} this intrinsic does not increase the range of the timing
8683 values over that returned by @code{clock(3)}. On a system with a 32-bit
8684 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8685 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8686 overflows of the 32-bit value can still occur. Therefore, the values
8687 returned by this intrinsic might be or become negative or numerically
8688 less than previous values during a single run of the compiled program.
8689
8690 @item @emph{Standard}:
8691 GNU extension
8692
8693 @item @emph{Class}:
8694 Function
8695
8696 @item @emph{Syntax}:
8697 @code{RESULT = MCLOCK8()}
8698
8699 @item @emph{Return value}:
8700 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8701 number of clock ticks since the start of the process, or @code{-1} if
8702 the system does not support @code{clock(3)}.
8703
8704 @item @emph{See also}:
8705 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8706
8707 @end table
8708
8709
8710
8711 @node MERGE
8712 @section @code{MERGE} --- Merge variables
8713 @fnindex MERGE
8714 @cindex array, merge arrays
8715 @cindex array, combine arrays
8716
8717 @table @asis
8718 @item @emph{Description}:
8719 Select values from two arrays according to a logical mask.  The result
8720 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8721 @var{FSOURCE} if it is @code{.FALSE.}.
8722
8723 @item @emph{Standard}:
8724 Fortran 95 and later
8725
8726 @item @emph{Class}:
8727 Elemental function
8728
8729 @item @emph{Syntax}:
8730 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8731
8732 @item @emph{Arguments}:
8733 @multitable @columnfractions .15 .70
8734 @item @var{TSOURCE} @tab May be of any type.
8735 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8736 as @var{TSOURCE}.
8737 @item @var{MASK}    @tab Shall be of type @code{LOGICAL}.
8738 @end multitable
8739
8740 @item @emph{Return value}:
8741 The result is of the same type and type parameters as @var{TSOURCE}.
8742
8743 @end table
8744
8745
8746
8747 @node MERGE_BITS
8748 @section @code{MERGE_BITS} --- Merge of bits under mask
8749 @fnindex MERGE_BITS
8750 @cindex bits, merge
8751
8752 @table @asis
8753 @item @emph{Description}:
8754 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8755 as determined by the mask.  The i-th bit of the result is equal to the
8756 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8757 the i-th bit of @var{J} otherwise.
8758
8759 @item @emph{Standard}:
8760 Fortran 2008 and later
8761
8762 @item @emph{Class}:
8763 Elemental function
8764
8765 @item @emph{Syntax}:
8766 @code{RESULT = MERGE_BITS(I, J, MASK)}
8767
8768 @item @emph{Arguments}:
8769 @multitable @columnfractions .15 .70
8770 @item @var{I}    @tab Shall be of type @code{INTEGER}.
8771 @item @var{J}    @tab Shall be of type @code{INTEGER} and of the same
8772 kind as @var{I}.
8773 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8774 kind as @var{I}.
8775 @end multitable
8776
8777 @item @emph{Return value}:
8778 The result is of the same type and kind as @var{I}.
8779
8780 @end table
8781
8782
8783
8784 @node MIN
8785 @section @code{MIN} --- Minimum value of an argument list
8786 @fnindex MIN
8787 @fnindex MIN0
8788 @fnindex AMIN0
8789 @fnindex MIN1
8790 @fnindex AMIN1
8791 @fnindex DMIN1
8792 @cindex minimum value
8793
8794 @table @asis
8795 @item @emph{Description}:
8796 Returns the argument with the smallest (most negative) value.
8797
8798 @item @emph{Standard}:
8799 Fortran 77 and later
8800
8801 @item @emph{Class}:
8802 Elemental function
8803
8804 @item @emph{Syntax}:
8805 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8806
8807 @item @emph{Arguments}:
8808 @multitable @columnfractions .15 .70
8809 @item @var{A1}          @tab The type shall be @code{INTEGER} or
8810 @code{REAL}.
8811 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8812 as @var{A1}.  (As a GNU extension, arguments of different kinds are
8813 permitted.)
8814 @end multitable
8815
8816 @item @emph{Return value}:
8817 The return value corresponds to the maximum value among the arguments,
8818 and has the same type and kind as the first argument.
8819
8820 @item @emph{Specific names}:
8821 @multitable @columnfractions .20 .20 .20 .25
8822 @item Name              @tab Argument             @tab Return type        @tab Standard
8823 @item @code{MIN0(A1)}   @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8824 @item @code{AMIN0(A1)}  @tab @code{INTEGER(4) A1} @tab @code{REAL(4)}     @tab Fortran 77 and later
8825 @item @code{MIN1(A1)}   @tab @code{REAL A1}       @tab @code{INTEGER(4)}  @tab Fortran 77 and later
8826 @item @code{AMIN1(A1)}  @tab @code{REAL(4) A1}    @tab @code{REAL(4)}     @tab Fortran 77 and later
8827 @item @code{DMIN1(A1)}  @tab @code{REAL(8) A1}    @tab @code{REAL(8)}     @tab Fortran 77 and later
8828 @end multitable
8829
8830 @item @emph{See also}:
8831 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8832 @end table
8833
8834
8835
8836 @node MINEXPONENT
8837 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8838 @fnindex MINEXPONENT
8839 @cindex model representation, minimum exponent
8840
8841 @table @asis
8842 @item @emph{Description}:
8843 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8844 type of @code{X}.
8845
8846 @item @emph{Standard}:
8847 Fortran 95 and later
8848
8849 @item @emph{Class}:
8850 Inquiry function
8851
8852 @item @emph{Syntax}:
8853 @code{RESULT = MINEXPONENT(X)}
8854
8855 @item @emph{Arguments}:
8856 @multitable @columnfractions .15 .70
8857 @item @var{X} @tab Shall be of type @code{REAL}.
8858 @end multitable
8859
8860 @item @emph{Return value}:
8861 The return value is of type @code{INTEGER} and of the default integer
8862 kind.
8863
8864 @item @emph{Example}:
8865 See @code{MAXEXPONENT} for an example.
8866 @end table
8867
8868
8869
8870 @node MINLOC
8871 @section @code{MINLOC} --- Location of the minimum value within an array
8872 @fnindex MINLOC
8873 @cindex array, location of minimum element
8874
8875 @table @asis
8876 @item @emph{Description}:
8877 Determines the location of the element in the array with the minimum
8878 value, or, if the @var{DIM} argument is supplied, determines the
8879 locations of the minimum element along each row of the array in the
8880 @var{DIM} direction.  If @var{MASK} is present, only the elements for
8881 which @var{MASK} is @code{.TRUE.} are considered.  If more than one
8882 element in the array has the minimum value, the location returned is
8883 that of the first such element in array element order.  If the array has
8884 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8885 the result is an array of zeroes.  Similarly, if @var{DIM} is supplied
8886 and all of the elements of @var{MASK} along a given row are zero, the
8887 result value for that row is zero.
8888
8889 @item @emph{Standard}:
8890 Fortran 95 and later
8891
8892 @item @emph{Class}:
8893 Transformational function
8894
8895 @item @emph{Syntax}:
8896 @multitable @columnfractions .80
8897 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8898 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8899 @end multitable
8900
8901 @item @emph{Arguments}:
8902 @multitable @columnfractions .15 .70
8903 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8904 @code{REAL}.
8905 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8906 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8907 inclusive.  It may not be an optional dummy argument.
8908 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8909 and conformable with @var{ARRAY}.
8910 @end multitable
8911
8912 @item @emph{Return value}:
8913 If @var{DIM} is absent, the result is a rank-one array with a length
8914 equal to the rank of @var{ARRAY}.  If @var{DIM} is present, the result
8915 is an array with a rank one less than the rank of @var{ARRAY}, and a
8916 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8917 dimension removed.  If @var{DIM} is present and @var{ARRAY} has a rank
8918 of one, the result is a scalar.  In all cases, the result is of default
8919 @code{INTEGER} type.
8920
8921 @item @emph{See also}:
8922 @ref{MIN}, @ref{MINVAL}
8923
8924 @end table
8925
8926
8927
8928 @node MINVAL
8929 @section @code{MINVAL} --- Minimum value of an array
8930 @fnindex MINVAL
8931 @cindex array, minimum value
8932 @cindex minimum value
8933
8934 @table @asis
8935 @item @emph{Description}:
8936 Determines the minimum value of the elements in an array value, or, if
8937 the @var{DIM} argument is supplied, determines the minimum value along
8938 each row of the array in the @var{DIM} direction.  If @var{MASK} is
8939 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8940 considered.  If the array has zero size, or all of the elements of
8941 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8942 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8943 @var{ARRAY} is of character type.
8944
8945 @item @emph{Standard}:
8946 Fortran 95 and later
8947
8948 @item @emph{Class}:
8949 Transformational function
8950
8951 @item @emph{Syntax}:
8952 @multitable @columnfractions .80
8953 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8954 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8955 @end multitable
8956
8957 @item @emph{Arguments}:
8958 @multitable @columnfractions .15 .70
8959 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8960 @code{REAL}.
8961 @item @var{DIM}   @tab (Optional) Shall be a scalar of type
8962 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8963 inclusive.  It may not be an optional dummy argument.
8964 @item @var{MASK}  @tab Shall be an array of type @code{LOGICAL},
8965 and conformable with @var{ARRAY}.
8966 @end multitable
8967
8968 @item @emph{Return value}:
8969 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8970 is a scalar.  If @var{DIM} is present, the result is an array with a
8971 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8972 the size of @var{ARRAY} with the @var{DIM} dimension removed.  In all
8973 cases, the result is of the same type and kind as @var{ARRAY}.
8974
8975 @item @emph{See also}:
8976 @ref{MIN}, @ref{MINLOC}
8977
8978 @end table
8979
8980
8981
8982 @node MOD
8983 @section @code{MOD} --- Remainder function
8984 @fnindex MOD
8985 @fnindex AMOD
8986 @fnindex DMOD
8987 @cindex remainder
8988 @cindex division, remainder
8989
8990 @table @asis
8991 @item @emph{Description}:
8992 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8993 calculated as @code{A - (INT(A/P) * P)}.
8994
8995 @item @emph{Standard}:
8996 Fortran 77 and later
8997
8998 @item @emph{Class}:
8999 Elemental function
9000
9001 @item @emph{Syntax}:
9002 @code{RESULT = MOD(A, P)}
9003
9004 @item @emph{Arguments}:
9005 @multitable @columnfractions .15 .70
9006 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9007 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
9008 equal to zero
9009 @end multitable
9010
9011 @item @emph{Return value}:
9012 The kind of the return value is the result of cross-promoting
9013 the kinds of the arguments.
9014
9015 @item @emph{Example}:
9016 @smallexample
9017 program test_mod
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
9023   print *, mod(-17,3)
9024   print *, mod(-17.5,5.5)
9025   print *, mod(-17.5d0,5.5)
9026   print *, mod(-17.5,5.5d0)
9027
9028   print *, mod(17,-3)
9029   print *, mod(17.5,-5.5)
9030   print *, mod(17.5d0,-5.5)
9031   print *, mod(17.5,-5.5d0)
9032 end program test_mod
9033 @end smallexample
9034
9035 @item @emph{Specific names}:
9036 @multitable @columnfractions .20 .20 .20 .25
9037 @item Name             @tab Arguments          @tab Return type    @tab Standard
9038 @item @code{MOD(A,P)}  @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9039 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9040 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9041 @end multitable
9042 @end table
9043
9044
9045
9046 @node MODULO
9047 @section @code{MODULO} --- Modulo function
9048 @fnindex MODULO
9049 @cindex modulo
9050 @cindex division, modulo
9051
9052 @table @asis
9053 @item @emph{Description}:
9054 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9055
9056 @item @emph{Standard}:
9057 Fortran 95 and later
9058
9059 @item @emph{Class}:
9060 Elemental function
9061
9062 @item @emph{Syntax}:
9063 @code{RESULT = MODULO(A, P)}
9064
9065 @item @emph{Arguments}:
9066 @multitable @columnfractions .15 .70
9067 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9068 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9069 @end multitable
9070
9071 @item @emph{Return value}:
9072 The type and kind of the result are those of the arguments.
9073 @table @asis
9074 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9075 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9076 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9077 (exclusive).
9078 @item If @var{A} and @var{P} are of type @code{REAL}:
9079 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9080 @end table
9081 In all cases, if @var{P} is zero the result is processor-dependent.
9082
9083 @item @emph{Example}:
9084 @smallexample
9085 program test_modulo
9086   print *, modulo(17,3)
9087   print *, modulo(17.5,5.5)
9088
9089   print *, modulo(-17,3)
9090   print *, modulo(-17.5,5.5)
9091
9092   print *, modulo(17,-3)
9093   print *, modulo(17.5,-5.5)
9094 end program
9095 @end smallexample
9096
9097 @end table
9098
9099
9100
9101 @node MOVE_ALLOC
9102 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9103 @fnindex MOVE_ALLOC
9104 @cindex moving allocation
9105 @cindex allocation, moving
9106
9107 @table @asis
9108 @item @emph{Description}:
9109 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9110 @var{TO}.  @var{FROM} will become deallocated in the process.
9111
9112 @item @emph{Standard}:
9113 Fortran 2003 and later
9114
9115 @item @emph{Class}:
9116 Pure subroutine
9117
9118 @item @emph{Syntax}:
9119 @code{CALL MOVE_ALLOC(FROM, TO)}
9120
9121 @item @emph{Arguments}:
9122 @multitable @columnfractions .15 .70
9123 @item @var{FROM}  @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9124 of any type and kind.
9125 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9126 of the same type, kind and rank as @var{FROM}.
9127 @end multitable
9128
9129 @item @emph{Return value}:
9130 None
9131
9132 @item @emph{Example}:
9133 @smallexample
9134 program test_move_alloc
9135     integer, allocatable :: a(:), b(:)
9136
9137     allocate(a(3))
9138     a = [ 1, 2, 3 ]
9139     call move_alloc(a, b)
9140     print *, allocated(a), allocated(b)
9141     print *, b
9142 end program test_move_alloc
9143 @end smallexample
9144 @end table
9145
9146
9147
9148 @node MVBITS
9149 @section @code{MVBITS} --- Move bits from one integer to another
9150 @fnindex MVBITS
9151 @cindex bits, move
9152
9153 @table @asis
9154 @item @emph{Description}:
9155 Moves @var{LEN} bits from positions @var{FROMPOS} through
9156 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9157 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9158 affected by the movement of bits is unchanged. The values of
9159 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9160 @code{BIT_SIZE(FROM)}.
9161
9162 @item @emph{Standard}:
9163 Fortran 95 and later
9164
9165 @item @emph{Class}:
9166 Elemental subroutine
9167
9168 @item @emph{Syntax}:
9169 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9170
9171 @item @emph{Arguments}:
9172 @multitable @columnfractions .15 .70
9173 @item @var{FROM}    @tab The type shall be @code{INTEGER}.
9174 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9175 @item @var{LEN}     @tab The type shall be @code{INTEGER}.
9176 @item @var{TO}      @tab The type shall be @code{INTEGER}, of the
9177 same kind as @var{FROM}.
9178 @item @var{TOPOS}   @tab The type shall be @code{INTEGER}.
9179 @end multitable
9180
9181 @item @emph{See also}:
9182 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9183 @end table
9184
9185
9186
9187 @node NEAREST
9188 @section @code{NEAREST} --- Nearest representable number
9189 @fnindex NEAREST
9190 @cindex real number, nearest different
9191 @cindex floating point, nearest different
9192
9193 @table @asis
9194 @item @emph{Description}:
9195 @code{NEAREST(X, S)} returns the processor-representable number nearest
9196 to @code{X} in the direction indicated by the sign of @code{S}.
9197
9198 @item @emph{Standard}:
9199 Fortran 95 and later
9200
9201 @item @emph{Class}:
9202 Elemental function
9203
9204 @item @emph{Syntax}:
9205 @code{RESULT = NEAREST(X, S)}
9206
9207 @item @emph{Arguments}:
9208 @multitable @columnfractions .15 .70
9209 @item @var{X} @tab Shall be of type @code{REAL}.
9210 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9211 not equal to zero.
9212 @end multitable
9213
9214 @item @emph{Return value}:
9215 The return value is of the same type as @code{X}. If @code{S} is
9216 positive, @code{NEAREST} returns the processor-representable number
9217 greater than @code{X} and nearest to it. If @code{S} is negative,
9218 @code{NEAREST} returns the processor-representable number smaller than
9219 @code{X} and nearest to it.
9220
9221 @item @emph{Example}:
9222 @smallexample
9223 program test_nearest
9224   real :: x, y
9225   x = nearest(42.0, 1.0)
9226   y = nearest(42.0, -1.0)
9227   write (*,"(3(G20.15))") x, y, x - y
9228 end program test_nearest
9229 @end smallexample
9230 @end table
9231
9232
9233
9234 @node NEW_LINE
9235 @section @code{NEW_LINE} --- New line character
9236 @fnindex NEW_LINE
9237 @cindex newline
9238 @cindex output, newline
9239
9240 @table @asis
9241 @item @emph{Description}:
9242 @code{NEW_LINE(C)} returns the new-line character.
9243
9244 @item @emph{Standard}:
9245 Fortran 2003 and later
9246
9247 @item @emph{Class}:
9248 Inquiry function
9249
9250 @item @emph{Syntax}:
9251 @code{RESULT = NEW_LINE(C)}
9252
9253 @item @emph{Arguments}:
9254 @multitable @columnfractions .15 .70
9255 @item @var{C}    @tab The argument shall be a scalar or array of the
9256 type @code{CHARACTER}.
9257 @end multitable
9258
9259 @item @emph{Return value}:
9260 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9261 the same kind as parameter @var{C}.
9262
9263 @item @emph{Example}:
9264 @smallexample
9265 program newline
9266   implicit none
9267   write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9268 end program newline
9269 @end smallexample
9270 @end table
9271
9272
9273
9274 @node NINT
9275 @section @code{NINT} --- Nearest whole number
9276 @fnindex NINT
9277 @fnindex IDNINT
9278 @cindex rounding, nearest whole number
9279
9280 @table @asis
9281 @item @emph{Description}:
9282 @code{NINT(A)} rounds its argument to the nearest whole number.
9283
9284 @item @emph{Standard}:
9285 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9286
9287 @item @emph{Class}:
9288 Elemental function
9289
9290 @item @emph{Syntax}:
9291 @code{RESULT = NINT(A [, KIND])}
9292
9293 @item @emph{Arguments}:
9294 @multitable @columnfractions .15 .70
9295 @item @var{A}    @tab The type of the argument shall be @code{REAL}.
9296 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9297 expression indicating the kind parameter of the result.
9298 @end multitable
9299
9300 @item @emph{Return value}:
9301 Returns @var{A} with the fractional portion of its magnitude eliminated by
9302 rounding to the nearest whole number and with its sign preserved,
9303 converted to an @code{INTEGER} of the default kind.
9304
9305 @item @emph{Example}:
9306 @smallexample
9307 program test_nint
9308   real(4) x4
9309   real(8) x8
9310   x4 = 1.234E0_4
9311   x8 = 4.321_8
9312   print *, nint(x4), idnint(x8)
9313 end program test_nint
9314 @end smallexample
9315
9316 @item @emph{Specific names}:
9317 @multitable @columnfractions .20 .20 .20 .25
9318 @item Name             @tab Argument           @tab Return Type     @tab Standard
9319 @item @code{NINT(A)}   @tab @code{REAL(4) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9320 @item @code{IDNINT(A)} @tab @code{REAL(8) A}   @tab  @code{INTEGER} @tab Fortran 95 and later
9321 @end multitable
9322
9323 @item @emph{See also}:
9324 @ref{CEILING}, @ref{FLOOR}
9325
9326 @end table
9327
9328
9329
9330 @node NORM2
9331 @section @code{NORM2} --- Euclidean vector norms
9332 @fnindex NORM2
9333 @cindex Euclidean vector norm
9334 @cindex L2 vector norm
9335 @cindex norm, Euclidean
9336
9337 @table @asis
9338 @item @emph{Description}:
9339 Calculates the Euclidean vector norm (@math{L_2} norm) of
9340 of @var{ARRAY} along dimension @var{DIM}.
9341
9342 @item @emph{Standard}:
9343 Fortran 2008 and later
9344
9345 @item @emph{Class}:
9346 Transformational function
9347
9348 @item @emph{Syntax}:
9349 @multitable @columnfractions .80
9350 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9351 @end multitable
9352
9353 @item @emph{Arguments}:
9354 @multitable @columnfractions .15 .70
9355 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9356 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9357 @code{INTEGER} with a value in the range from 1 to n, where n
9358 equals the rank of @var{ARRAY}.
9359 @end multitable
9360
9361 @item @emph{Return value}:
9362 The result is of the same type as @var{ARRAY}.
9363
9364 If @var{DIM} is absent, a scalar with the square root of the sum of all
9365 elements in @var{ARRAY} squared  is returned. Otherwise, an array of
9366 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9367 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9368 is returned.
9369
9370 @item @emph{Example}:
9371 @smallexample
9372 PROGRAM test_sum
9373   REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9374   print *, NORM2(x)  ! = sqrt(55.) ~ 7.416
9375 END PROGRAM
9376 @end smallexample
9377 @end table
9378
9379
9380
9381 @node NOT
9382 @section @code{NOT} --- Logical negation
9383 @fnindex NOT
9384 @cindex bits, negate
9385 @cindex bitwise logical not
9386 @cindex logical not, bitwise
9387
9388 @table @asis
9389 @item @emph{Description}:
9390 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9391
9392 @item @emph{Standard}:
9393 Fortran 95 and later
9394
9395 @item @emph{Class}:
9396 Elemental function
9397
9398 @item @emph{Syntax}:
9399 @code{RESULT = NOT(I)}
9400
9401 @item @emph{Arguments}:
9402 @multitable @columnfractions .15 .70
9403 @item @var{I} @tab The type shall be @code{INTEGER}.
9404 @end multitable
9405
9406 @item @emph{Return value}:
9407 The return type is @code{INTEGER}, of the same kind as the
9408 argument.
9409
9410 @item @emph{See also}:
9411 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9412
9413 @end table
9414
9415
9416
9417 @node NULL
9418 @section @code{NULL} --- Function that returns an disassociated pointer
9419 @fnindex NULL
9420 @cindex pointer, status
9421 @cindex pointer, disassociated
9422
9423 @table @asis
9424 @item @emph{Description}:
9425 Returns a disassociated pointer.
9426
9427 If @var{MOLD} is present, a disassociated pointer of the same type is
9428 returned, otherwise the type is determined by context.
9429
9430 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9431 includes cases where it is required.
9432
9433 @item @emph{Standard}:
9434 Fortran 95 and later
9435
9436 @item @emph{Class}:
9437 Transformational function
9438
9439 @item @emph{Syntax}:
9440 @code{PTR => NULL([MOLD])}
9441
9442 @item @emph{Arguments}:
9443 @multitable @columnfractions .15 .70
9444 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9445 status and of any type.
9446 @end multitable
9447
9448 @item @emph{Return value}:
9449 A disassociated pointer.
9450
9451 @item @emph{Example}:
9452 @smallexample
9453 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9454 @end smallexample
9455
9456 @item @emph{See also}:
9457 @ref{ASSOCIATED}
9458 @end table
9459
9460
9461
9462 @node NUM_IMAGES
9463 @section @code{NUM_IMAGES} --- Function that returns the number of images
9464 @fnindex NUM_IMAGES
9465 @cindex coarray, @code{NUM_IMAGES}
9466 @cindex images, number of
9467
9468 @table @asis
9469 @item @emph{Description}:
9470 Returns the number of images.
9471
9472 @item @emph{Standard}:
9473 Fortran 2008 and later
9474
9475 @item @emph{Class}:
9476 Transformational function
9477
9478 @item @emph{Syntax}:
9479 @code{RESULT = NUM_IMAGES()}
9480
9481 @item @emph{Arguments}: None.
9482
9483 @item @emph{Return value}:
9484 Scalar default-kind integer.
9485
9486 @item @emph{Example}:
9487 @smallexample
9488 INTEGER :: value[*]
9489 INTEGER :: i
9490 value = THIS_IMAGE()
9491 SYNC ALL
9492 IF (THIS_IMAGE() == 1) THEN
9493   DO i = 1, NUM_IMAGES()
9494     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9495   END DO
9496 END IF
9497 @end smallexample
9498
9499 @item @emph{See also}:
9500 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9501 @end table
9502
9503
9504
9505 @node OR
9506 @section @code{OR} --- Bitwise logical OR
9507 @fnindex OR
9508 @cindex bitwise logical or
9509 @cindex logical or, bitwise
9510
9511 @table @asis
9512 @item @emph{Description}:
9513 Bitwise logical @code{OR}.
9514
9515 This intrinsic routine is provided for backwards compatibility with
9516 GNU Fortran 77.  For integer arguments, programmers should consider
9517 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9518
9519 @item @emph{Standard}:
9520 GNU extension
9521
9522 @item @emph{Class}:
9523 Function
9524
9525 @item @emph{Syntax}:
9526 @code{RESULT = OR(I, J)}
9527
9528 @item @emph{Arguments}:
9529 @multitable @columnfractions .15 .70
9530 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9531 type or a scalar @code{LOGICAL} type.
9532 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9533 @end multitable
9534
9535 @item @emph{Return value}:
9536 The return type is either a scalar @code{INTEGER} or a scalar
9537 @code{LOGICAL}.  If the kind type parameters differ, then the
9538 smaller kind type is implicitly converted to larger kind, and the
9539 return has the larger kind.
9540
9541 @item @emph{Example}:
9542 @smallexample
9543 PROGRAM test_or
9544   LOGICAL :: T = .TRUE., F = .FALSE.
9545   INTEGER :: a, b
9546   DATA a / Z'F' /, b / Z'3' /
9547
9548   WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9549   WRITE (*,*) OR(a, b)
9550 END PROGRAM
9551 @end smallexample
9552
9553 @item @emph{See also}:
9554 Fortran 95 elemental function: @ref{IOR}
9555 @end table
9556
9557
9558
9559 @node PACK
9560 @section @code{PACK} --- Pack an array into an array of rank one
9561 @fnindex PACK
9562 @cindex array, packing
9563 @cindex array, reduce dimension
9564 @cindex array, gather elements
9565
9566 @table @asis
9567 @item @emph{Description}:
9568 Stores the elements of @var{ARRAY} in an array of rank one.
9569
9570 The beginning of the resulting array is made up of elements whose @var{MASK}
9571 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9572 @var{VECTOR}.
9573
9574 @item @emph{Standard}:
9575 Fortran 95 and later
9576
9577 @item @emph{Class}:
9578 Transformational function
9579
9580 @item @emph{Syntax}:
9581 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9582
9583 @item @emph{Arguments}:
9584 @multitable @columnfractions .15 .70
9585 @item @var{ARRAY}  @tab Shall be an array of any type.
9586 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL} and
9587 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9588 scalar.
9589 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9590 as @var{ARRAY} and of rank one. If present, the number of elements in
9591 @var{VECTOR} shall be equal to or greater than the number of true elements
9592 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9593 @var{VECTOR} shall be equal to or greater than the number of elements in
9594 @var{ARRAY}.
9595 @end multitable
9596
9597 @item @emph{Return value}:
9598 The result is an array of rank one and the same type as that of @var{ARRAY}.
9599 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9600 number of @code{TRUE} values in @var{MASK} otherwise.
9601
9602 @item @emph{Example}:
9603 Gathering nonzero elements from an array:
9604 @smallexample
9605 PROGRAM test_pack_1
9606   INTEGER :: m(6)
9607   m = (/ 1, 0, 0, 0, 5, 0 /)
9608   WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0)  ! "1 5"
9609 END PROGRAM
9610 @end smallexample
9611
9612 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9613 @smallexample
9614 PROGRAM test_pack_2
9615   INTEGER :: m(4)
9616   m = (/ 1, 0, 0, 2 /)
9617   WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))  ! "1 2 3 4"
9618 END PROGRAM
9619 @end smallexample
9620
9621 @item @emph{See also}:
9622 @ref{UNPACK}
9623 @end table
9624
9625
9626
9627 @node PARITY
9628 @section @code{PARITY} --- Reduction with exclusive OR
9629 @fnindex PARITY
9630 @cindex Parity
9631 @cindex Reduction, XOR
9632 @cindex XOR reduction
9633
9634 @table @asis
9635 @item @emph{Description}:
9636 Calculates the parity, i.e. the reduction using @code{.XOR.},
9637 of @var{MASK} along dimension @var{DIM}.
9638
9639 @item @emph{Standard}:
9640 Fortran 2008 and later
9641
9642 @item @emph{Class}:
9643 Transformational function
9644
9645 @item @emph{Syntax}:
9646 @multitable @columnfractions .80
9647 @item @code{RESULT = PARITY(MASK[, DIM])}
9648 @end multitable
9649
9650 @item @emph{Arguments}:
9651 @multitable @columnfractions .15 .70
9652 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9653 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9654 @code{INTEGER} with a value in the range from 1 to n, where n
9655 equals the rank of @var{MASK}.
9656 @end multitable
9657
9658 @item @emph{Return value}:
9659 The result is of the same type as @var{MASK}.
9660
9661 If @var{DIM} is absent, a scalar with the parity of all elements in
9662 @var{MASK} is returned, i.e. true if an odd number of elements is
9663 @code{.true.} and false otherwise.  If @var{DIM} is present, an array
9664 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9665 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9666 dropped is returned.
9667
9668 @item @emph{Example}:
9669 @smallexample
9670 PROGRAM test_sum
9671   LOGICAL :: x(2) = [ .true., .false. ]
9672   print *, PARITY(x) ! prints "T" (true).
9673 END PROGRAM
9674 @end smallexample
9675 @end table
9676
9677
9678
9679 @node PERROR
9680 @section @code{PERROR} --- Print system error message
9681 @fnindex PERROR
9682 @cindex system, error handling
9683
9684 @table @asis
9685 @item @emph{Description}:
9686 Prints (on the C @code{stderr} stream) a newline-terminated error
9687 message corresponding to the last system error. This is prefixed by
9688 @var{STRING}, a colon and a space. See @code{perror(3)}.
9689
9690 @item @emph{Standard}:
9691 GNU extension
9692
9693 @item @emph{Class}:
9694 Subroutine
9695
9696 @item @emph{Syntax}:
9697 @code{CALL PERROR(STRING)}
9698
9699 @item @emph{Arguments}:
9700 @multitable @columnfractions .15 .70
9701 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9702 default kind.
9703 @end multitable
9704
9705 @item @emph{See also}:
9706 @ref{IERRNO}
9707 @end table
9708
9709
9710
9711 @node PRECISION
9712 @section @code{PRECISION} --- Decimal precision of a real kind
9713 @fnindex PRECISION
9714 @cindex model representation, precision
9715
9716 @table @asis
9717 @item @emph{Description}:
9718 @code{PRECISION(X)} returns the decimal precision in the model of the
9719 type of @code{X}.
9720
9721 @item @emph{Standard}:
9722 Fortran 95 and later
9723
9724 @item @emph{Class}:
9725 Inquiry function
9726
9727 @item @emph{Syntax}:
9728 @code{RESULT = PRECISION(X)}
9729
9730 @item @emph{Arguments}:
9731 @multitable @columnfractions .15 .70
9732 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9733 @end multitable
9734
9735 @item @emph{Return value}:
9736 The return value is of type @code{INTEGER} and of the default integer
9737 kind.
9738
9739 @item @emph{See also}:
9740 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9741
9742 @item @emph{Example}:
9743 @smallexample
9744 program prec_and_range
9745   real(kind=4) :: x(2)
9746   complex(kind=8) :: y
9747
9748   print *, precision(x), range(x)
9749   print *, precision(y), range(y)
9750 end program prec_and_range
9751 @end smallexample
9752 @end table
9753
9754
9755
9756 @node POPCNT
9757 @section @code{POPCNT} --- Number of bits set
9758 @fnindex POPCNT
9759 @cindex binary representation
9760 @cindex bits set
9761
9762 @table @asis
9763 @item @emph{Description}:
9764 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9765 representation of @code{I}.
9766
9767 @item @emph{Standard}:
9768 Fortran 2008 and later
9769
9770 @item @emph{Class}:
9771 Elemental function
9772
9773 @item @emph{Syntax}:
9774 @code{RESULT = POPCNT(I)}
9775
9776 @item @emph{Arguments}:
9777 @multitable @columnfractions .15 .70
9778 @item @var{I} @tab Shall be of type @code{INTEGER}.
9779 @end multitable
9780
9781 @item @emph{Return value}:
9782 The return value is of type @code{INTEGER} and of the default integer
9783 kind.
9784
9785 @item @emph{See also}:
9786 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9787
9788 @item @emph{Example}:
9789 @smallexample
9790 program test_population
9791   print *, popcnt(127),       poppar(127)
9792   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9793   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9794 end program test_population
9795 @end smallexample
9796 @end table
9797
9798
9799 @node POPPAR
9800 @section @code{POPPAR} --- Parity of the number of bits set
9801 @fnindex POPPAR
9802 @cindex binary representation
9803 @cindex parity
9804
9805 @table @asis
9806 @item @emph{Description}:
9807 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9808 of the number of bits set ('1' bits) in the binary representation of
9809 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9810 and 1 for an odd number of '1' bits.
9811
9812 @item @emph{Standard}:
9813 Fortran 2008 and later
9814
9815 @item @emph{Class}:
9816 Elemental function
9817
9818 @item @emph{Syntax}:
9819 @code{RESULT = POPPAR(I)}
9820
9821 @item @emph{Arguments}:
9822 @multitable @columnfractions .15 .70
9823 @item @var{I} @tab Shall be of type @code{INTEGER}.
9824 @end multitable
9825
9826 @item @emph{Return value}:
9827 The return value is of type @code{INTEGER} and of the default integer
9828 kind.
9829
9830 @item @emph{See also}:
9831 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9832
9833 @item @emph{Example}:
9834 @smallexample
9835 program test_population
9836   print *, popcnt(127),       poppar(127)
9837   print *, popcnt(huge(0_4)), poppar(huge(0_4))
9838   print *, popcnt(huge(0_8)), poppar(huge(0_8))
9839 end program test_population
9840 @end smallexample
9841 @end table
9842
9843
9844
9845 @node PRESENT
9846 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9847 @fnindex PRESENT
9848
9849 @table @asis
9850 @item @emph{Description}:
9851 Determines whether an optional dummy argument is present.
9852
9853 @item @emph{Standard}:
9854 Fortran 95 and later
9855
9856 @item @emph{Class}:
9857 Inquiry function
9858
9859 @item @emph{Syntax}:
9860 @code{RESULT = PRESENT(A)}
9861
9862 @item @emph{Arguments}:
9863 @multitable @columnfractions .15 .70
9864 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9865 value, or a dummy procedure. It shall be the name of an optional dummy argument
9866 accessible within the current subroutine or function.
9867 @end multitable
9868
9869 @item @emph{Return value}:
9870 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9871 @code{FALSE} otherwise.
9872
9873 @item @emph{Example}:
9874 @smallexample
9875 PROGRAM test_present
9876   WRITE(*,*) f(), f(42)      ! "F T"
9877 CONTAINS
9878   LOGICAL FUNCTION f(x)
9879     INTEGER, INTENT(IN), OPTIONAL :: x
9880     f = PRESENT(x)
9881   END FUNCTION
9882 END PROGRAM
9883 @end smallexample
9884 @end table
9885
9886
9887
9888 @node PRODUCT
9889 @section @code{PRODUCT} --- Product of array elements
9890 @fnindex PRODUCT
9891 @cindex array, product
9892 @cindex array, multiply elements
9893 @cindex array, conditionally multiply elements
9894 @cindex multiply array elements
9895
9896 @table @asis
9897 @item @emph{Description}:
9898 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9899 the corresponding element in @var{MASK} is @code{TRUE}.
9900
9901 @item @emph{Standard}:
9902 Fortran 95 and later
9903
9904 @item @emph{Class}:
9905 Transformational function
9906
9907 @item @emph{Syntax}:
9908 @multitable @columnfractions .80
9909 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9910 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9911 @end multitable
9912
9913 @item @emph{Arguments}:
9914 @multitable @columnfractions .15 .70
9915 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9916 @code{REAL} or @code{COMPLEX}.
9917 @item @var{DIM}   @tab (Optional) shall be a scalar of type
9918 @code{INTEGER} with a value in the range from 1 to n, where n
9919 equals the rank of @var{ARRAY}.
9920 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
9921 and either be a scalar or an array of the same shape as @var{ARRAY}.
9922 @end multitable
9923
9924 @item @emph{Return value}:
9925 The result is of the same type as @var{ARRAY}.
9926
9927 If @var{DIM} is absent, a scalar with the product of all elements in
9928 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9929 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9930 dimension @var{DIM} dropped is returned.
9931
9932
9933 @item @emph{Example}:
9934 @smallexample
9935 PROGRAM test_product
9936   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9937   print *, PRODUCT(x)                    ! all elements, product = 120
9938   print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9939 END PROGRAM
9940 @end smallexample
9941
9942 @item @emph{See also}:
9943 @ref{SUM}
9944 @end table
9945
9946
9947
9948 @node RADIX
9949 @section @code{RADIX} --- Base of a model number
9950 @fnindex RADIX
9951 @cindex model representation, base
9952 @cindex model representation, radix
9953
9954 @table @asis
9955 @item @emph{Description}:
9956 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9957
9958 @item @emph{Standard}:
9959 Fortran 95 and later
9960
9961 @item @emph{Class}:
9962 Inquiry function
9963
9964 @item @emph{Syntax}:
9965 @code{RESULT = RADIX(X)}
9966
9967 @item @emph{Arguments}:
9968 @multitable @columnfractions .15 .70
9969 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9970 @end multitable
9971
9972 @item @emph{Return value}:
9973 The return value is a scalar of type @code{INTEGER} and of the default
9974 integer kind.
9975
9976 @item @emph{See also}:
9977 @ref{SELECTED_REAL_KIND}
9978
9979 @item @emph{Example}:
9980 @smallexample
9981 program test_radix
9982   print *, "The radix for the default integer kind is", radix(0)
9983   print *, "The radix for the default real kind is", radix(0.0)
9984 end program test_radix
9985 @end smallexample
9986
9987 @end table
9988
9989
9990
9991 @node RAN
9992 @section @code{RAN} --- Real pseudo-random number
9993 @fnindex RAN
9994 @cindex random number generation
9995
9996 @table @asis
9997 @item @emph{Description}:
9998 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9999 provided as an alias for @code{RAND}.  See @ref{RAND} for complete
10000 documentation.
10001
10002 @item @emph{Standard}:
10003 GNU extension
10004
10005 @item @emph{Class}:
10006 Function
10007
10008 @item @emph{See also}:
10009 @ref{RAND}, @ref{RANDOM_NUMBER}
10010 @end table
10011
10012
10013
10014 @node RAND
10015 @section @code{RAND} --- Real pseudo-random number
10016 @fnindex RAND
10017 @cindex random number generation
10018
10019 @table @asis
10020 @item @emph{Description}:
10021 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10022 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10023 in the current sequence is returned; if @var{FLAG} is 1, the generator
10024 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10025 it is used as a new seed with @code{SRAND}.
10026
10027 This intrinsic routine is provided for backwards compatibility with
10028 GNU Fortran 77. It implements a simple modulo generator as provided
10029 by @command{g77}. For new code, one should consider the use of
10030 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10031
10032 @item @emph{Standard}:
10033 GNU extension
10034
10035 @item @emph{Class}:
10036 Function
10037
10038 @item @emph{Syntax}:
10039 @code{RESULT = RAND(I)}
10040
10041 @item @emph{Arguments}:
10042 @multitable @columnfractions .15 .70
10043 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10044 @end multitable
10045
10046 @item @emph{Return value}:
10047 The return value is of @code{REAL} type and the default kind.
10048
10049 @item @emph{Example}:
10050 @smallexample
10051 program test_rand
10052   integer,parameter :: seed = 86456
10053
10054   call srand(seed)
10055   print *, rand(), rand(), rand(), rand()
10056   print *, rand(seed), rand(), rand(), rand()
10057 end program test_rand
10058 @end smallexample
10059
10060 @item @emph{See also}:
10061 @ref{SRAND}, @ref{RANDOM_NUMBER}
10062
10063 @end table
10064
10065
10066
10067 @node RANDOM_NUMBER
10068 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10069 @fnindex RANDOM_NUMBER
10070 @cindex random number generation
10071
10072 @table @asis
10073 @item @emph{Description}:
10074 Returns a single pseudorandom number or an array of pseudorandom numbers
10075 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10076
10077 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10078 Stupid) random number generator (RNG). This RNG combines:
10079 @enumerate
10080 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10081 with a period of @math{2^{32}},
10082 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10083 @item  Two 16-bit multiply-with-carry generators with a period of
10084 @math{597273182964842497 > 2^{59}}.
10085 @end enumerate
10086 The overall period exceeds @math{2^{123}}.
10087
10088 Please note, this RNG is thread safe if used within OpenMP directives,
10089 i.e., its state will be consistent while called from multiple threads.
10090 However, the KISS generator does not create random numbers in parallel
10091 from multiple sources, but in sequence from a single source. If an
10092 OpenMP-enabled application heavily relies on random numbers, one should
10093 consider employing a dedicated parallel random number generator instead.
10094
10095 @item @emph{Standard}:
10096 Fortran 95 and later
10097
10098 @item @emph{Class}:
10099 Subroutine
10100
10101 @item @emph{Syntax}:
10102 @code{RANDOM_NUMBER(HARVEST)}
10103
10104 @item @emph{Arguments}:
10105 @multitable @columnfractions .15 .70
10106 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10107 @end multitable
10108
10109 @item @emph{Example}:
10110 @smallexample
10111 program test_random_number
10112   REAL :: r(5,5)
10113   CALL init_random_seed()         ! see example of RANDOM_SEED
10114   CALL RANDOM_NUMBER(r)
10115 end program
10116 @end smallexample
10117
10118 @item @emph{See also}:
10119 @ref{RANDOM_SEED}
10120 @end table
10121
10122
10123
10124 @node RANDOM_SEED
10125 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10126 @fnindex RANDOM_SEED
10127 @cindex random number generation, seeding
10128 @cindex seeding a random number generator
10129
10130 @table @asis
10131 @item @emph{Description}:
10132 Restarts or queries the state of the pseudorandom number generator used by
10133 @code{RANDOM_NUMBER}.
10134
10135 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10136 a default state. The example below shows how to initialize the random
10137 seed based on the system's time.
10138
10139 @item @emph{Standard}:
10140 Fortran 95 and later
10141
10142 @item @emph{Class}:
10143 Subroutine
10144
10145 @item @emph{Syntax}:
10146 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10147
10148 @item @emph{Arguments}:
10149 @multitable @columnfractions .15 .70
10150 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10151 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10152 of the arrays used with the @var{PUT} and @var{GET} arguments.
10153 @item @var{PUT}  @tab (Optional) Shall be an array of type default
10154 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10155 the array must be larger than or equal to the number returned by the
10156 @var{SIZE} argument.
10157 @item @var{GET}  @tab (Optional) Shall be an array of type default
10158 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10159 of the array must be larger than or equal to the number returned by
10160 the @var{SIZE} argument.
10161 @end multitable
10162
10163 @item @emph{Example}:
10164 @smallexample
10165 SUBROUTINE init_random_seed()
10166   INTEGER :: i, n, clock
10167   INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10168
10169   CALL RANDOM_SEED(size = n)
10170   ALLOCATE(seed(n))
10171
10172   CALL SYSTEM_CLOCK(COUNT=clock)
10173
10174   seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10175   CALL RANDOM_SEED(PUT = seed)
10176
10177   DEALLOCATE(seed)
10178 END SUBROUTINE
10179 @end smallexample
10180
10181 @item @emph{See also}:
10182 @ref{RANDOM_NUMBER}
10183 @end table
10184
10185
10186
10187 @node RANGE
10188 @section @code{RANGE} --- Decimal exponent range
10189 @fnindex RANGE
10190 @cindex model representation, range
10191
10192 @table @asis
10193 @item @emph{Description}:
10194 @code{RANGE(X)} returns the decimal exponent range in the model of the
10195 type of @code{X}.
10196
10197 @item @emph{Standard}:
10198 Fortran 95 and later
10199
10200 @item @emph{Class}:
10201 Inquiry function
10202
10203 @item @emph{Syntax}:
10204 @code{RESULT = RANGE(X)}
10205
10206 @item @emph{Arguments}:
10207 @multitable @columnfractions .15 .70
10208 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10209 or @code{COMPLEX}.
10210 @end multitable
10211
10212 @item @emph{Return value}:
10213 The return value is of type @code{INTEGER} and of the default integer
10214 kind.
10215
10216 @item @emph{See also}:
10217 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10218
10219 @item @emph{Example}:
10220 See @code{PRECISION} for an example.
10221 @end table
10222
10223
10224
10225 @node RANK
10226 @section @code{RANK} --- Rank of a data object
10227 @fnindex RANK
10228 @cindex rank
10229
10230 @table @asis
10231 @item @emph{Description}:
10232 @code{RANK(A)} returns the rank of a scalar or array data object.
10233
10234 @item @emph{Standard}:
10235 Technical Specification (TS) 29113
10236
10237 @item @emph{Class}:
10238 Inquiry function
10239
10240 @item @emph{Syntax}:
10241 @code{RESULT = RANGE(A)}
10242
10243 @item @emph{Arguments}:
10244 @multitable @columnfractions .15 .70
10245 @item @var{A} @tab can be of any type
10246 @end multitable
10247
10248 @item @emph{Return value}:
10249 The return value is of type @code{INTEGER} and of the default integer
10250 kind. For arrays, their rank is returned; for scalars zero is returned.
10251
10252 @item @emph{Example}:
10253 @smallexample
10254 program test_rank
10255   integer :: a
10256   real, allocatable :: b(:,:)
10257
10258   print *, rank(a), rank(b) ! Prints:  0  3
10259 end program test_rank
10260 @end smallexample
10261
10262 @end table
10263
10264
10265
10266 @node REAL
10267 @section @code{REAL} --- Convert to real type
10268 @fnindex REAL
10269 @fnindex REALPART
10270 @fnindex FLOAT
10271 @fnindex DFLOAT
10272 @fnindex SNGL
10273 @cindex conversion, to real
10274 @cindex complex numbers, real part
10275
10276 @table @asis
10277 @item @emph{Description}:
10278 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type.  The
10279 @code{REALPART} function is provided for compatibility with @command{g77},
10280 and its use is strongly discouraged.
10281
10282 @item @emph{Standard}:
10283 Fortran 77 and later
10284
10285 @item @emph{Class}:
10286 Elemental function
10287
10288 @item @emph{Syntax}:
10289 @multitable @columnfractions .80
10290 @item @code{RESULT = REAL(A [, KIND])}
10291 @item @code{RESULT = REALPART(Z)}
10292 @end multitable
10293
10294 @item @emph{Arguments}:
10295 @multitable @columnfractions .15 .70
10296 @item @var{A}    @tab Shall be @code{INTEGER}, @code{REAL}, or
10297 @code{COMPLEX}.
10298 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10299 expression indicating the kind parameter of the result.
10300 @end multitable
10301
10302 @item @emph{Return value}:
10303 These functions return a @code{REAL} variable or array under
10304 the following rules:
10305
10306 @table @asis
10307 @item (A)
10308 @code{REAL(A)} is converted to a default real type if @var{A} is an
10309 integer or real variable.
10310 @item (B)
10311 @code{REAL(A)} is converted to a real type with the kind type parameter
10312 of @var{A} if @var{A} is a complex variable.
10313 @item (C)
10314 @code{REAL(A, KIND)} is converted to a real type with kind type
10315 parameter @var{KIND} if @var{A} is a complex, integer, or real
10316 variable.
10317 @end table
10318
10319 @item @emph{Example}:
10320 @smallexample
10321 program test_real
10322   complex :: x = (1.0, 2.0)
10323   print *, real(x), real(x,8), realpart(x)
10324 end program test_real
10325 @end smallexample
10326
10327 @item @emph{Specific names}:
10328 @multitable @columnfractions .20 .20 .20 .25
10329 @item Name             @tab Argument           @tab Return type     @tab Standard
10330 @item @code{FLOAT(A)}  @tab @code{INTEGER(4)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10331 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)}  @tab @code{REAL(8)}  @tab GNU extension
10332 @item @code{SNGL(A)}   @tab @code{INTEGER(8)}  @tab @code{REAL(4)}  @tab Fortran 77 and later
10333 @end multitable
10334
10335
10336 @item @emph{See also}:
10337 @ref{DBLE}
10338
10339 @end table
10340
10341
10342
10343 @node RENAME
10344 @section @code{RENAME} --- Rename a file
10345 @fnindex RENAME
10346 @cindex file system, rename file
10347
10348 @table @asis
10349 @item @emph{Description}:
10350 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10351 character (@code{CHAR(0)}) can be used to mark the end of the names in
10352 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10353 names are ignored.  If the @var{STATUS} argument is supplied, it
10354 contains 0 on success or a nonzero error code upon return; see
10355 @code{rename(2)}.
10356
10357 This intrinsic is provided in both subroutine and function forms;
10358 however, only one form can be used in any given program unit.
10359
10360 @item @emph{Standard}:
10361 GNU extension
10362
10363 @item @emph{Class}:
10364 Subroutine, function
10365
10366 @item @emph{Syntax}:
10367 @multitable @columnfractions .80
10368 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10369 @item @code{STATUS = RENAME(PATH1, PATH2)}
10370 @end multitable
10371
10372 @item @emph{Arguments}:
10373 @multitable @columnfractions .15 .70
10374 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10375 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10376 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10377 @end multitable
10378
10379 @item @emph{See also}:
10380 @ref{LINK}
10381
10382 @end table
10383
10384
10385
10386 @node REPEAT
10387 @section @code{REPEAT} --- Repeated string concatenation
10388 @fnindex REPEAT
10389 @cindex string, repeat
10390 @cindex string, concatenate
10391
10392 @table @asis
10393 @item @emph{Description}:
10394 Concatenates @var{NCOPIES} copies of a string.
10395
10396 @item @emph{Standard}:
10397 Fortran 95 and later
10398
10399 @item @emph{Class}:
10400 Transformational function
10401
10402 @item @emph{Syntax}:
10403 @code{RESULT = REPEAT(STRING, NCOPIES)}
10404
10405 @item @emph{Arguments}:
10406 @multitable @columnfractions .15 .70
10407 @item @var{STRING}  @tab Shall be scalar and of type @code{CHARACTER}.
10408 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10409 @end multitable
10410
10411 @item @emph{Return value}:
10412 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10413 of @var{STRING}.
10414
10415 @item @emph{Example}:
10416 @smallexample
10417 program test_repeat
10418   write(*,*) repeat("x", 5)   ! "xxxxx"
10419 end program
10420 @end smallexample
10421 @end table
10422
10423
10424
10425 @node RESHAPE
10426 @section @code{RESHAPE} --- Function to reshape an array
10427 @fnindex RESHAPE
10428 @cindex array, change dimensions
10429 @cindex array, transmogrify
10430
10431 @table @asis
10432 @item @emph{Description}:
10433 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10434 the new array may be padded with elements from @var{PAD} or permuted
10435 as defined by @var{ORDER}.
10436
10437 @item @emph{Standard}:
10438 Fortran 95 and later
10439
10440 @item @emph{Class}:
10441 Transformational function
10442
10443 @item @emph{Syntax}:
10444 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10445
10446 @item @emph{Arguments}:
10447 @multitable @columnfractions .15 .70
10448 @item @var{SOURCE} @tab Shall be an array of any type.
10449 @item @var{SHAPE}  @tab Shall be of type @code{INTEGER} and an
10450 array of rank one. Its values must be positive or zero.
10451 @item @var{PAD}    @tab (Optional) shall be an array of the same
10452 type as @var{SOURCE}.
10453 @item @var{ORDER}  @tab (Optional) shall be of type @code{INTEGER}
10454 and an array of the same shape as @var{SHAPE}. Its values shall
10455 be a permutation of the numbers from 1 to n, where n is the size of
10456 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10457 be assumed.
10458 @end multitable
10459
10460 @item @emph{Return value}:
10461 The result is an array of shape @var{SHAPE} with the same type as
10462 @var{SOURCE}.
10463
10464 @item @emph{Example}:
10465 @smallexample
10466 PROGRAM test_reshape
10467   INTEGER, DIMENSION(4) :: x
10468   WRITE(*,*) SHAPE(x)                       ! prints "4"
10469   WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/)))    ! prints "2 2"
10470 END PROGRAM
10471 @end smallexample
10472
10473 @item @emph{See also}:
10474 @ref{SHAPE}
10475 @end table
10476
10477
10478
10479 @node RRSPACING
10480 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10481 @fnindex RRSPACING
10482 @cindex real number, relative spacing
10483 @cindex floating point, relative spacing
10484
10485
10486 @table @asis
10487 @item @emph{Description}:
10488 @code{RRSPACING(X)} returns the  reciprocal of the relative spacing of
10489 model numbers near @var{X}.
10490
10491 @item @emph{Standard}:
10492 Fortran 95 and later
10493
10494 @item @emph{Class}:
10495 Elemental function
10496
10497 @item @emph{Syntax}:
10498 @code{RESULT = RRSPACING(X)}
10499
10500 @item @emph{Arguments}:
10501 @multitable @columnfractions .15 .70
10502 @item @var{X} @tab Shall be of type @code{REAL}.
10503 @end multitable
10504
10505 @item @emph{Return value}:
10506 The return value is of the same type and kind as @var{X}.
10507 The value returned is equal to
10508 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10509
10510 @item @emph{See also}:
10511 @ref{SPACING}
10512 @end table
10513
10514
10515
10516 @node RSHIFT
10517 @section @code{RSHIFT} --- Right shift bits
10518 @fnindex RSHIFT
10519 @cindex bits, shift right
10520
10521 @table @asis
10522 @item @emph{Description}:
10523 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10524 bits shifted right by @var{SHIFT} places.  If the absolute value of
10525 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10526 Bits shifted out from the right end are lost. The fill is arithmetic: the
10527 bits shifted in from the left end are equal to the leftmost bit, which in
10528 two's complement representation is the sign bit.
10529
10530 This function has been superseded by the @code{SHIFTA} intrinsic, which
10531 is standard in Fortran 2008 and later.
10532
10533 @item @emph{Standard}:
10534 GNU extension
10535
10536 @item @emph{Class}:
10537 Elemental function
10538
10539 @item @emph{Syntax}:
10540 @code{RESULT = RSHIFT(I, SHIFT)}
10541
10542 @item @emph{Arguments}:
10543 @multitable @columnfractions .15 .70
10544 @item @var{I} @tab The type shall be @code{INTEGER}.
10545 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10546 @end multitable
10547
10548 @item @emph{Return value}:
10549 The return value is of type @code{INTEGER} and of the same kind as
10550 @var{I}.
10551
10552 @item @emph{See also}:
10553 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10554 @ref{SHIFTL}
10555
10556 @end table
10557
10558
10559
10560 @node SAME_TYPE_AS
10561 @section @code{SAME_TYPE_AS} ---  Query dynamic types for equality
10562 @fnindex SAME_TYPE_AS
10563
10564 @table @asis
10565 @item @emph{Description}:
10566 Query dynamic types for equality.
10567
10568 @item @emph{Standard}:
10569 Fortran 2003 and later
10570
10571 @item @emph{Class}:
10572 Inquiry function
10573
10574 @item @emph{Syntax}:
10575 @code{RESULT = SAME_TYPE_AS(A, B)}
10576
10577 @item @emph{Arguments}:
10578 @multitable @columnfractions .15 .70
10579 @item @var{A} @tab Shall be an object of extensible declared type or
10580 unlimited polymorphic.
10581 @item @var{B} @tab Shall be an object of extensible declared type or
10582 unlimited polymorphic.
10583 @end multitable
10584
10585 @item @emph{Return value}:
10586 The return value is a scalar of type default logical. It is true if and
10587 only if the dynamic type of A is the same as the dynamic type of B.
10588
10589 @item @emph{See also}:
10590 @ref{EXTENDS_TYPE_OF}
10591
10592 @end table
10593
10594
10595
10596 @node SCALE
10597 @section @code{SCALE} --- Scale a real value
10598 @fnindex SCALE
10599 @cindex real number, scale
10600 @cindex floating point, scale
10601
10602 @table @asis
10603 @item @emph{Description}:
10604 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10605
10606 @item @emph{Standard}:
10607 Fortran 95 and later
10608
10609 @item @emph{Class}:
10610 Elemental function
10611
10612 @item @emph{Syntax}:
10613 @code{RESULT = SCALE(X, I)}
10614
10615 @item @emph{Arguments}:
10616 @multitable @columnfractions .15 .70
10617 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10618 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10619 @end multitable
10620
10621 @item @emph{Return value}:
10622 The return value is of the same type and kind as @var{X}.
10623 Its value is @code{X * RADIX(X)**I}.
10624
10625 @item @emph{Example}:
10626 @smallexample
10627 program test_scale
10628   real :: x = 178.1387e-4
10629   integer :: i = 5
10630   print *, scale(x,i), x*radix(x)**i
10631 end program test_scale
10632 @end smallexample
10633
10634 @end table
10635
10636
10637
10638 @node SCAN
10639 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10640 @fnindex SCAN
10641 @cindex string, find subset
10642
10643 @table @asis
10644 @item @emph{Description}:
10645 Scans a @var{STRING} for any of the characters in a @var{SET}
10646 of characters.
10647
10648 If @var{BACK} is either absent or equals @code{FALSE}, this function
10649 returns the position of the leftmost character of @var{STRING} that is
10650 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10651 is returned. If no character of @var{SET} is found in @var{STRING}, the
10652 result is zero.
10653
10654 @item @emph{Standard}:
10655 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10656
10657 @item @emph{Class}:
10658 Elemental function
10659
10660 @item @emph{Syntax}:
10661 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10662
10663 @item @emph{Arguments}:
10664 @multitable @columnfractions .15 .70
10665 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10666 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
10667 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
10668 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
10669 expression indicating the kind parameter of the result.
10670 @end multitable
10671
10672 @item @emph{Return value}:
10673 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10674 @var{KIND} is absent, the return value is of default integer kind.
10675
10676 @item @emph{Example}:
10677 @smallexample
10678 PROGRAM test_scan
10679   WRITE(*,*) SCAN("FORTRAN", "AO")          ! 2, found 'O'
10680   WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.)  ! 6, found 'A'
10681   WRITE(*,*) SCAN("FORTRAN", "C++")         ! 0, found none
10682 END PROGRAM
10683 @end smallexample
10684
10685 @item @emph{See also}:
10686 @ref{INDEX intrinsic}, @ref{VERIFY}
10687 @end table
10688
10689
10690
10691 @node SECNDS
10692 @section @code{SECNDS} --- Time function
10693 @fnindex SECNDS
10694 @cindex time, elapsed
10695 @cindex elapsed time
10696
10697 @table @asis
10698 @item @emph{Description}:
10699 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10700 @var{X} is a reference time, also in seconds. If this is zero, the time in
10701 seconds from midnight is returned. This function is non-standard and its
10702 use is discouraged.
10703
10704 @item @emph{Standard}:
10705 GNU extension
10706
10707 @item @emph{Class}:
10708 Function
10709
10710 @item @emph{Syntax}:
10711 @code{RESULT = SECNDS (X)}
10712
10713 @item @emph{Arguments}:
10714 @multitable @columnfractions .15 .70
10715 @item @var{T}     @tab Shall be of type @code{REAL(4)}.
10716 @item @var{X}     @tab Shall be of type @code{REAL(4)}.
10717 @end multitable
10718
10719 @item @emph{Return value}:
10720 None
10721
10722 @item @emph{Example}:
10723 @smallexample
10724 program test_secnds
10725     integer :: i
10726     real(4) :: t1, t2
10727     print *, secnds (0.0)   ! seconds since midnight
10728     t1 = secnds (0.0)       ! reference time
10729     do i = 1, 10000000      ! do something
10730     end do
10731     t2 = secnds (t1)        ! elapsed time
10732     print *, "Something took ", t2, " seconds."
10733 end program test_secnds
10734 @end smallexample
10735 @end table
10736
10737
10738
10739 @node SECOND
10740 @section @code{SECOND} --- CPU time function
10741 @fnindex SECOND
10742 @cindex time, elapsed
10743 @cindex elapsed time
10744
10745 @table @asis
10746 @item @emph{Description}:
10747 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10748 seconds.  This provides the same functionality as the standard
10749 @code{CPU_TIME} intrinsic, and is only included for backwards
10750 compatibility.
10751
10752 This intrinsic is provided in both subroutine and function forms;
10753 however, only one form can be used in any given program unit.
10754
10755 @item @emph{Standard}:
10756 GNU extension
10757
10758 @item @emph{Class}:
10759 Subroutine, function
10760
10761 @item @emph{Syntax}:
10762 @multitable @columnfractions .80
10763 @item @code{CALL SECOND(TIME)}
10764 @item @code{TIME = SECOND()}
10765 @end multitable
10766
10767 @item @emph{Arguments}:
10768 @multitable @columnfractions .15 .70
10769 @item @var{TIME}  @tab Shall be of type @code{REAL(4)}.
10770 @end multitable
10771
10772 @item @emph{Return value}:
10773 In either syntax, @var{TIME} is set to the process's current runtime in
10774 seconds.
10775
10776 @item @emph{See also}:
10777 @ref{CPU_TIME}
10778
10779 @end table
10780
10781
10782
10783 @node SELECTED_CHAR_KIND
10784 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10785 @fnindex SELECTED_CHAR_KIND
10786 @cindex character kind
10787 @cindex kind, character
10788
10789 @table @asis
10790 @item @emph{Description}:
10791
10792 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10793 set named @var{NAME}, if a character set with such a name is supported,
10794 or @math{-1} otherwise. Currently, supported character sets include
10795 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10796 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10797
10798 @item @emph{Standard}:
10799 Fortran 2003 and later
10800
10801 @item @emph{Class}:
10802 Transformational function
10803
10804 @item @emph{Syntax}:
10805 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10806
10807 @item @emph{Arguments}:
10808 @multitable @columnfractions .15 .70
10809 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10810 @end multitable
10811
10812 @item @emph{Example}:
10813 @smallexample
10814 program character_kind
10815   use iso_fortran_env
10816   implicit none
10817   integer, parameter :: ascii = selected_char_kind ("ascii")
10818   integer, parameter :: ucs4  = selected_char_kind ('ISO_10646')
10819
10820   character(kind=ascii, len=26) :: alphabet
10821   character(kind=ucs4,  len=30) :: hello_world
10822
10823   alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10824   hello_world = ucs4_'Hello World and Ni Hao -- ' &
10825                 // char (int (z'4F60'), ucs4)     &
10826                 // char (int (z'597D'), ucs4)
10827
10828   write (*,*) alphabet
10829
10830   open (output_unit, encoding='UTF-8')
10831   write (*,*) trim (hello_world)
10832 end program character_kind
10833 @end smallexample
10834 @end table
10835
10836
10837
10838 @node SELECTED_INT_KIND
10839 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10840 @fnindex SELECTED_INT_KIND
10841 @cindex integer kind
10842 @cindex kind, integer
10843
10844 @table @asis
10845 @item @emph{Description}:
10846 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10847 type that can represent all values ranging from @math{-10^R} (exclusive)
10848 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10849 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10850
10851 @item @emph{Standard}:
10852 Fortran 95 and later
10853
10854 @item @emph{Class}:
10855 Transformational function
10856
10857 @item @emph{Syntax}:
10858 @code{RESULT = SELECTED_INT_KIND(R)}
10859
10860 @item @emph{Arguments}:
10861 @multitable @columnfractions .15 .70
10862 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10863 @end multitable
10864
10865 @item @emph{Example}:
10866 @smallexample
10867 program large_integers
10868   integer,parameter :: k5 = selected_int_kind(5)
10869   integer,parameter :: k15 = selected_int_kind(15)
10870   integer(kind=k5) :: i5
10871   integer(kind=k15) :: i15
10872
10873   print *, huge(i5), huge(i15)
10874
10875   ! The following inequalities are always true
10876   print *, huge(i5) >= 10_k5**5-1
10877   print *, huge(i15) >= 10_k15**15-1
10878 end program large_integers
10879 @end smallexample
10880 @end table
10881
10882
10883
10884 @node SELECTED_REAL_KIND
10885 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10886 @fnindex SELECTED_REAL_KIND
10887 @cindex real kind
10888 @cindex kind, real
10889 @cindex radix, real
10890
10891 @table @asis
10892 @item @emph{Description}:
10893 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10894 with decimal precision of at least @code{P} digits, exponent range of
10895 at least @code{R}, and with a radix of @code{RADIX}.
10896
10897 @item @emph{Standard}:
10898 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10899
10900 @item @emph{Class}:
10901 Transformational function
10902
10903 @item @emph{Syntax}:
10904 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10905
10906 @item @emph{Arguments}:
10907 @multitable @columnfractions .15 .70
10908 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10909 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10910 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10911 @end multitable
10912 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10913 be present; since Fortran 2008, they are assumed to be zero if absent.
10914
10915 @item @emph{Return value}:
10916
10917 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10918 a real data type with decimal precision of at least @code{P} digits, a
10919 decimal exponent range of at least @code{R}, and with the requested
10920 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10921 any radix can be returned. If more than one real data type meet the
10922 criteria, the kind of the data type with the smallest decimal precision
10923 is returned. If no real data type matches the criteria, the result is
10924 @table @asis
10925 @item -1 if the processor does not support a real data type with a
10926 precision greater than or equal to @code{P}, but the @code{R} and
10927 @code{RADIX} requirements can be fulfilled
10928 @item -2 if the processor does not support a real type with an exponent
10929 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10930 are fulfillable
10931 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10932 are fulfillable
10933 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10934 are fulfillable
10935 @item -5 if there is no real type with the given @code{RADIX}
10936 @end table
10937
10938 @item @emph{See also}:
10939 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10940
10941 @item @emph{Example}:
10942 @smallexample
10943 program real_kinds
10944   integer,parameter :: p6 = selected_real_kind(6)
10945   integer,parameter :: p10r100 = selected_real_kind(10,100)
10946   integer,parameter :: r400 = selected_real_kind(r=400)
10947   real(kind=p6) :: x
10948   real(kind=p10r100) :: y
10949   real(kind=r400) :: z
10950
10951   print *, precision(x), range(x)
10952   print *, precision(y), range(y)
10953   print *, precision(z), range(z)
10954 end program real_kinds
10955 @end smallexample
10956 @end table
10957
10958
10959
10960 @node SET_EXPONENT
10961 @section @code{SET_EXPONENT} --- Set the exponent of the model
10962 @fnindex SET_EXPONENT
10963 @cindex real number, set exponent
10964 @cindex floating point, set exponent
10965
10966 @table @asis
10967 @item @emph{Description}:
10968 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10969 is that that of @var{X} and whose exponent part is @var{I}.
10970
10971 @item @emph{Standard}:
10972 Fortran 95 and later
10973
10974 @item @emph{Class}:
10975 Elemental function
10976
10977 @item @emph{Syntax}:
10978 @code{RESULT = SET_EXPONENT(X, I)}
10979
10980 @item @emph{Arguments}:
10981 @multitable @columnfractions .15 .70
10982 @item @var{X} @tab Shall be of type @code{REAL}.
10983 @item @var{I} @tab Shall be of type @code{INTEGER}.
10984 @end multitable
10985
10986 @item @emph{Return value}:
10987 The return value is of the same type and kind as @var{X}.
10988 The real number whose fractional part
10989 is that that of @var{X} and whose exponent part if @var{I} is returned;
10990 it is @code{FRACTION(X) * RADIX(X)**I}.
10991
10992 @item @emph{Example}:
10993 @smallexample
10994 PROGRAM test_setexp
10995   REAL :: x = 178.1387e-4
10996   INTEGER :: i = 17
10997   PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10998 END PROGRAM
10999 @end smallexample
11000
11001 @end table
11002
11003
11004
11005 @node SHAPE
11006 @section @code{SHAPE} --- Determine the shape of an array
11007 @fnindex SHAPE
11008 @cindex array, shape
11009
11010 @table @asis
11011 @item @emph{Description}:
11012 Determines the shape of an array.
11013
11014 @item @emph{Standard}:
11015 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11016
11017 @item @emph{Class}:
11018 Inquiry function
11019
11020 @item @emph{Syntax}:
11021 @code{RESULT = SHAPE(SOURCE [, KIND])}
11022
11023 @item @emph{Arguments}:
11024 @multitable @columnfractions .15 .70
11025 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11026 If @var{SOURCE} is a pointer it must be associated and allocatable
11027 arrays must be allocated.
11028 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
11029 expression indicating the kind parameter of the result.
11030 @end multitable
11031
11032 @item @emph{Return value}:
11033 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11034 has dimensions. The elements of the resulting array correspond to the extend
11035 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11036 the result is the rank one array of size zero. If @var{KIND} is absent, the
11037 return value has the default integer kind otherwise the specified kind.
11038
11039 @item @emph{Example}:
11040 @smallexample
11041 PROGRAM test_shape
11042   INTEGER, DIMENSION(-1:1, -1:2) :: A
11043   WRITE(*,*) SHAPE(A)             ! (/ 3, 4 /)
11044   WRITE(*,*) SIZE(SHAPE(42))      ! (/ /)
11045 END PROGRAM
11046 @end smallexample
11047
11048 @item @emph{See also}:
11049 @ref{RESHAPE}, @ref{SIZE}
11050 @end table
11051
11052
11053
11054 @node SHIFTA
11055 @section @code{SHIFTA} --- Right shift with fill
11056 @fnindex SHIFTA
11057 @cindex bits, shift right
11058 @cindex shift, right with fill
11059
11060 @table @asis
11061 @item @emph{Description}:
11062 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11063 bits shifted right by @var{SHIFT} places.  If the absolute value of
11064 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11065 Bits shifted out from the right end are lost. The fill is arithmetic: the
11066 bits shifted in from the left end are equal to the leftmost bit, which in
11067 two's complement representation is the sign bit.
11068
11069 @item @emph{Standard}:
11070 Fortran 2008 and later
11071
11072 @item @emph{Class}:
11073 Elemental function
11074
11075 @item @emph{Syntax}:
11076 @code{RESULT = SHIFTA(I, SHIFT)}
11077
11078 @item @emph{Arguments}:
11079 @multitable @columnfractions .15 .70
11080 @item @var{I} @tab The type shall be @code{INTEGER}.
11081 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11082 @end multitable
11083
11084 @item @emph{Return value}:
11085 The return value is of type @code{INTEGER} and of the same kind as
11086 @var{I}.
11087
11088 @item @emph{See also}:
11089 @ref{SHIFTL}, @ref{SHIFTR}
11090 @end table
11091
11092
11093
11094 @node SHIFTL
11095 @section @code{SHIFTL} --- Left shift
11096 @fnindex SHIFTL
11097 @cindex bits, shift left
11098 @cindex shift, left
11099
11100 @table @asis
11101 @item @emph{Description}:
11102 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11103 bits shifted left by @var{SHIFT} places.  If the absolute value of
11104 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11105 Bits shifted out from the left end are lost, and bits shifted in from
11106 the right end are set to 0.
11107
11108 @item @emph{Standard}:
11109 Fortran 2008 and later
11110
11111 @item @emph{Class}:
11112 Elemental function
11113
11114 @item @emph{Syntax}:
11115 @code{RESULT = SHIFTL(I, SHIFT)}
11116
11117 @item @emph{Arguments}:
11118 @multitable @columnfractions .15 .70
11119 @item @var{I} @tab The type shall be @code{INTEGER}.
11120 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11121 @end multitable
11122
11123 @item @emph{Return value}:
11124 The return value is of type @code{INTEGER} and of the same kind as
11125 @var{I}.
11126
11127 @item @emph{See also}:
11128 @ref{SHIFTA}, @ref{SHIFTR}
11129 @end table
11130
11131
11132
11133 @node SHIFTR
11134 @section @code{SHIFTR} --- Right shift
11135 @fnindex SHIFTR
11136 @cindex bits, shift right
11137 @cindex shift, right
11138
11139 @table @asis
11140 @item @emph{Description}:
11141 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11142 bits shifted right by @var{SHIFT} places.  If the absolute value of
11143 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11144 Bits shifted out from the right end are lost, and bits shifted in from
11145 the left end are set to 0.
11146
11147 @item @emph{Standard}:
11148 Fortran 2008 and later
11149
11150 @item @emph{Class}:
11151 Elemental function
11152
11153 @item @emph{Syntax}:
11154 @code{RESULT = SHIFTR(I, SHIFT)}
11155
11156 @item @emph{Arguments}:
11157 @multitable @columnfractions .15 .70
11158 @item @var{I} @tab The type shall be @code{INTEGER}.
11159 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11160 @end multitable
11161
11162 @item @emph{Return value}:
11163 The return value is of type @code{INTEGER} and of the same kind as
11164 @var{I}.
11165
11166 @item @emph{See also}:
11167 @ref{SHIFTA}, @ref{SHIFTL}
11168 @end table
11169
11170
11171
11172 @node SIGN
11173 @section @code{SIGN} --- Sign copying function
11174 @fnindex SIGN
11175 @fnindex ISIGN
11176 @fnindex DSIGN
11177 @cindex sign copying
11178
11179 @table @asis
11180 @item @emph{Description}:
11181 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11182
11183 @item @emph{Standard}:
11184 Fortran 77 and later
11185
11186 @item @emph{Class}:
11187 Elemental function
11188
11189 @item @emph{Syntax}:
11190 @code{RESULT = SIGN(A, B)}
11191
11192 @item @emph{Arguments}:
11193 @multitable @columnfractions .15 .70
11194 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11195 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11196 @end multitable
11197
11198 @item @emph{Return value}:
11199 The kind of the return value is that of @var{A} and @var{B}.
11200 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11201 it is @code{-ABS(A)}.
11202
11203 @item @emph{Example}:
11204 @smallexample
11205 program test_sign
11206   print *, sign(-12,1)
11207   print *, sign(-12,0)
11208   print *, sign(-12,-1)
11209
11210   print *, sign(-12.,1.)
11211   print *, sign(-12.,0.)
11212   print *, sign(-12.,-1.)
11213 end program test_sign
11214 @end smallexample
11215
11216 @item @emph{Specific names}:
11217 @multitable @columnfractions .20 .20 .20 .25
11218 @item Name              @tab Arguments              @tab Return type       @tab Standard
11219 @item @code{SIGN(A,B)}  @tab @code{REAL(4) A, B}    @tab @code{REAL(4)}    @tab f77, gnu
11220 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11221 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B}    @tab @code{REAL(8)}    @tab f77, gnu
11222 @end multitable
11223 @end table
11224
11225
11226
11227 @node SIGNAL
11228 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11229 @fnindex SIGNAL
11230 @cindex system, signal handling
11231
11232 @table @asis
11233 @item @emph{Description}:
11234 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11235 @var{HANDLER} to be executed with a single integer argument when signal
11236 @var{NUMBER} occurs.  If @var{HANDLER} is an integer, it can be used to
11237 turn off handling of signal @var{NUMBER} or revert to its default
11238 action.  See @code{signal(2)}.
11239
11240 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11241 is supplied, it is set to the value returned by @code{signal(2)}.
11242
11243 @item @emph{Standard}:
11244 GNU extension
11245
11246 @item @emph{Class}:
11247 Subroutine, function
11248
11249 @item @emph{Syntax}:
11250 @multitable @columnfractions .80
11251 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11252 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11253 @end multitable
11254
11255 @item @emph{Arguments}:
11256 @multitable @columnfractions .15 .70
11257 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11258 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11259 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11260 @code{INTEGER}. It is @code{INTENT(IN)}.
11261 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11262 integer. It has @code{INTENT(OUT)}.
11263 @end multitable
11264 @c TODO: What should the interface of the handler be?  Does it take arguments?
11265
11266 @item @emph{Return value}:
11267 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11268
11269 @item @emph{Example}:
11270 @smallexample
11271 program test_signal
11272   intrinsic signal
11273   external handler_print
11274
11275   call signal (12, handler_print)
11276   call signal (10, 1)
11277
11278   call sleep (30)
11279 end program test_signal
11280 @end smallexample
11281 @end table
11282
11283
11284
11285 @node SIN
11286 @section @code{SIN} --- Sine function
11287 @fnindex SIN
11288 @fnindex DSIN
11289 @fnindex CSIN
11290 @fnindex ZSIN
11291 @fnindex CDSIN
11292 @cindex trigonometric function, sine
11293 @cindex sine
11294
11295 @table @asis
11296 @item @emph{Description}:
11297 @code{SIN(X)} computes the sine of @var{X}.
11298
11299 @item @emph{Standard}:
11300 Fortran 77 and later
11301
11302 @item @emph{Class}:
11303 Elemental function
11304
11305 @item @emph{Syntax}:
11306 @code{RESULT = SIN(X)}
11307
11308 @item @emph{Arguments}:
11309 @multitable @columnfractions .15 .70
11310 @item @var{X} @tab The type shall be @code{REAL} or
11311 @code{COMPLEX}.
11312 @end multitable
11313
11314 @item @emph{Return value}:
11315 The return value has same type and kind as @var{X}.
11316
11317 @item @emph{Example}:
11318 @smallexample
11319 program test_sin
11320   real :: x = 0.0
11321   x = sin(x)
11322 end program test_sin
11323 @end smallexample
11324
11325 @item @emph{Specific names}:
11326 @multitable @columnfractions .20 .20 .20 .25
11327 @item Name            @tab Argument             @tab Return type       @tab Standard
11328 @item @code{SIN(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}    @tab f77, gnu
11329 @item @code{DSIN(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}    @tab f95, gnu
11330 @item @code{CSIN(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)} @tab f95, gnu
11331 @item @code{ZSIN(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11332 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)} @tab f95, gnu
11333 @end multitable
11334
11335 @item @emph{See also}:
11336 @ref{ASIN}
11337 @end table
11338
11339
11340
11341 @node SINH
11342 @section @code{SINH} --- Hyperbolic sine function
11343 @fnindex SINH
11344 @fnindex DSINH
11345 @cindex hyperbolic sine
11346 @cindex hyperbolic function, sine
11347 @cindex sine, hyperbolic
11348
11349 @table @asis
11350 @item @emph{Description}:
11351 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11352
11353 @item @emph{Standard}:
11354 Fortran 95 and later, for a complex argument Fortran 2008 or later
11355
11356 @item @emph{Class}:
11357 Elemental function
11358
11359 @item @emph{Syntax}:
11360 @code{RESULT = SINH(X)}
11361
11362 @item @emph{Arguments}:
11363 @multitable @columnfractions .15 .70
11364 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11365 @end multitable
11366
11367 @item @emph{Return value}:
11368 The return value has same type and kind as @var{X}.
11369
11370 @item @emph{Example}:
11371 @smallexample
11372 program test_sinh
11373   real(8) :: x = - 1.0_8
11374   x = sinh(x)
11375 end program test_sinh
11376 @end smallexample
11377
11378 @item @emph{Specific names}:
11379 @multitable @columnfractions .20 .20 .20 .25
11380 @item Name            @tab Argument          @tab Return type       @tab Standard
11381 @item @code{SINH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
11382 @item @code{DSINH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
11383 @end multitable
11384
11385 @item @emph{See also}:
11386 @ref{ASINH}
11387 @end table
11388
11389
11390
11391 @node SIZE
11392 @section @code{SIZE} --- Determine the size of an array
11393 @fnindex SIZE
11394 @cindex array, size
11395 @cindex array, number of elements
11396 @cindex array, count elements
11397
11398 @table @asis
11399 @item @emph{Description}:
11400 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11401 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11402
11403 @item @emph{Standard}:
11404 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11405
11406 @item @emph{Class}:
11407 Inquiry function
11408
11409 @item @emph{Syntax}:
11410 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11411
11412 @item @emph{Arguments}:
11413 @multitable @columnfractions .15 .70
11414 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11415 a pointer it must be associated and allocatable arrays must be allocated.
11416 @item @var{DIM}   @tab (Optional) shall be a scalar of type @code{INTEGER}
11417 and its value shall be in the range from 1 to n, where n equals the rank
11418 of @var{ARRAY}.
11419 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11420 expression indicating the kind parameter of the result.
11421 @end multitable
11422
11423 @item @emph{Return value}:
11424 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11425 @var{KIND} is absent, the return value is of default integer kind.
11426
11427 @item @emph{Example}:
11428 @smallexample
11429 PROGRAM test_size
11430   WRITE(*,*) SIZE((/ 1, 2 /))    ! 2
11431 END PROGRAM
11432 @end smallexample
11433
11434 @item @emph{See also}:
11435 @ref{SHAPE}, @ref{RESHAPE}
11436 @end table
11437
11438
11439 @node SIZEOF
11440 @section @code{SIZEOF} --- Size in bytes of an expression
11441 @fnindex SIZEOF
11442 @cindex expression size
11443 @cindex size of an expression
11444
11445 @table @asis
11446 @item @emph{Description}:
11447 @code{SIZEOF(X)} calculates the number of bytes of storage the
11448 expression @code{X} occupies.
11449
11450 @item @emph{Standard}:
11451 GNU extension
11452
11453 @item @emph{Class}:
11454 Intrinsic function
11455
11456 @item @emph{Syntax}:
11457 @code{N = SIZEOF(X)}
11458
11459 @item @emph{Arguments}:
11460 @multitable @columnfractions .15 .70
11461 @item @var{X} @tab The argument shall be of any type, rank or shape.
11462 @end multitable
11463
11464 @item @emph{Return value}:
11465 The return value is of type integer and of the system-dependent kind
11466 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11467 number of bytes occupied by the argument.  If the argument has the
11468 @code{POINTER} attribute, the number of bytes of the storage area pointed
11469 to is returned.  If the argument is of a derived type with @code{POINTER}
11470 or @code{ALLOCATABLE} components, the return value doesn't account for
11471 the sizes of the data pointed to by these components. If the argument is
11472 polymorphic, the size according to the declared type is returned. The argument
11473 may not be a procedure or procedure pointer.
11474
11475 @item @emph{Example}:
11476 @smallexample
11477    integer :: i
11478    real :: r, s(5)
11479    print *, (sizeof(s)/sizeof(r) == 5)
11480    end
11481 @end smallexample
11482 The example will print @code{.TRUE.} unless you are using a platform
11483 where default @code{REAL} variables are unusually padded.
11484
11485 @item @emph{See also}:
11486 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11487 @end table
11488
11489
11490 @node SLEEP
11491 @section @code{SLEEP} --- Sleep for the specified number of seconds
11492 @fnindex SLEEP
11493 @cindex delayed execution
11494
11495 @table @asis
11496 @item @emph{Description}:
11497 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11498
11499 @item @emph{Standard}:
11500 GNU extension
11501
11502 @item @emph{Class}:
11503 Subroutine
11504
11505 @item @emph{Syntax}:
11506 @code{CALL SLEEP(SECONDS)}
11507
11508 @item @emph{Arguments}:
11509 @multitable @columnfractions .15 .70
11510 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11511 @end multitable
11512
11513 @item @emph{Example}:
11514 @smallexample
11515 program test_sleep
11516   call sleep(5)
11517 end
11518 @end smallexample
11519 @end table
11520
11521
11522
11523 @node SPACING
11524 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11525 @fnindex SPACING
11526 @cindex real number, relative spacing
11527 @cindex floating point, relative spacing
11528
11529 @table @asis
11530 @item @emph{Description}:
11531 Determines the distance between the argument @var{X} and the nearest
11532 adjacent number of the same type.
11533
11534 @item @emph{Standard}:
11535 Fortran 95 and later
11536
11537 @item @emph{Class}:
11538 Elemental function
11539
11540 @item @emph{Syntax}:
11541 @code{RESULT = SPACING(X)}
11542
11543 @item @emph{Arguments}:
11544 @multitable @columnfractions .15 .70
11545 @item @var{X} @tab Shall be of type @code{REAL}.
11546 @end multitable
11547
11548 @item @emph{Return value}:
11549 The result is of the same type as the input argument @var{X}.
11550
11551 @item @emph{Example}:
11552 @smallexample
11553 PROGRAM test_spacing
11554   INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11555   INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11556
11557   WRITE(*,*) spacing(1.0_SGL)      ! "1.1920929E-07"          on i686
11558   WRITE(*,*) spacing(1.0_DBL)      ! "2.220446049250313E-016" on i686
11559 END PROGRAM
11560 @end smallexample
11561
11562 @item @emph{See also}:
11563 @ref{RRSPACING}
11564 @end table
11565
11566
11567
11568 @node SPREAD
11569 @section @code{SPREAD} --- Add a dimension to an array
11570 @fnindex SPREAD
11571 @cindex array, increase dimension
11572 @cindex array, duplicate elements
11573 @cindex array, duplicate dimensions
11574
11575 @table @asis
11576 @item @emph{Description}:
11577 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11578 dimension @var{DIM}.
11579
11580 @item @emph{Standard}:
11581 Fortran 95 and later
11582
11583 @item @emph{Class}:
11584 Transformational function
11585
11586 @item @emph{Syntax}:
11587 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11588
11589 @item @emph{Arguments}:
11590 @multitable @columnfractions .15 .70
11591 @item @var{SOURCE}  @tab Shall be a scalar or an array of any type and
11592 a rank less than seven.
11593 @item @var{DIM}     @tab Shall be a scalar of type @code{INTEGER} with a
11594 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11595 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11596 @end multitable
11597
11598 @item @emph{Return value}:
11599 The result is an array of the same type as @var{SOURCE} and has rank n+1
11600 where n equals the rank of @var{SOURCE}.
11601
11602 @item @emph{Example}:
11603 @smallexample
11604 PROGRAM test_spread
11605   INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11606   WRITE(*,*) SPREAD(A, 1, 2)            ! "1 1"
11607   WRITE(*,*) SPREAD(B, 1, 2)            ! "1 1 2 2"
11608 END PROGRAM
11609 @end smallexample
11610
11611 @item @emph{See also}:
11612 @ref{UNPACK}
11613 @end table
11614
11615
11616
11617 @node SQRT
11618 @section @code{SQRT} --- Square-root function
11619 @fnindex SQRT
11620 @fnindex DSQRT
11621 @fnindex CSQRT
11622 @fnindex ZSQRT
11623 @fnindex CDSQRT
11624 @cindex root
11625 @cindex square-root
11626
11627 @table @asis
11628 @item @emph{Description}:
11629 @code{SQRT(X)} computes the square root of @var{X}.
11630
11631 @item @emph{Standard}:
11632 Fortran 77 and later
11633
11634 @item @emph{Class}:
11635 Elemental function
11636
11637 @item @emph{Syntax}:
11638 @code{RESULT = SQRT(X)}
11639
11640 @item @emph{Arguments}:
11641 @multitable @columnfractions .15 .70
11642 @item @var{X} @tab The type shall be @code{REAL} or
11643 @code{COMPLEX}.
11644 @end multitable
11645
11646 @item @emph{Return value}:
11647 The return value is of type @code{REAL} or @code{COMPLEX}.
11648 The kind type parameter is the same as @var{X}.
11649
11650 @item @emph{Example}:
11651 @smallexample
11652 program test_sqrt
11653   real(8) :: x = 2.0_8
11654   complex :: z = (1.0, 2.0)
11655   x = sqrt(x)
11656   z = sqrt(z)
11657 end program test_sqrt
11658 @end smallexample
11659
11660 @item @emph{Specific names}:
11661 @multitable @columnfractions .20 .20 .20 .25
11662 @item Name             @tab Argument             @tab Return type          @tab Standard
11663 @item @code{SQRT(X)}   @tab @code{REAL(4) X}     @tab @code{REAL(4)}       @tab Fortran 95 and later
11664 @item @code{DSQRT(X)}  @tab @code{REAL(8) X}     @tab @code{REAL(8)}       @tab Fortran 95 and later
11665 @item @code{CSQRT(X)}  @tab @code{COMPLEX(4) X}  @tab @code{COMPLEX(4)}    @tab Fortran 95 and later
11666 @item @code{ZSQRT(X)}  @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11667 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X}  @tab @code{COMPLEX(8)}    @tab GNU extension
11668 @end multitable
11669 @end table
11670
11671
11672
11673 @node SRAND
11674 @section @code{SRAND} --- Reinitialize the random number generator
11675 @fnindex SRAND
11676 @cindex random number generation, seeding
11677 @cindex seeding a random number generator
11678
11679 @table @asis
11680 @item @emph{Description}:
11681 @code{SRAND} reinitializes the pseudo-random number generator
11682 called by @code{RAND} and @code{IRAND}. The new seed used by the
11683 generator is specified by the required argument @var{SEED}.
11684
11685 @item @emph{Standard}:
11686 GNU extension
11687
11688 @item @emph{Class}:
11689 Subroutine
11690
11691 @item @emph{Syntax}:
11692 @code{CALL SRAND(SEED)}
11693
11694 @item @emph{Arguments}:
11695 @multitable @columnfractions .15 .70
11696 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11697 @end multitable
11698
11699 @item @emph{Return value}:
11700 Does not return anything.
11701
11702 @item @emph{Example}:
11703 See @code{RAND} and @code{IRAND} for examples.
11704
11705 @item @emph{Notes}:
11706 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11707 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11708 to generate pseudo-random numbers. Please note that in
11709 GNU Fortran, these two sets of intrinsics (@code{RAND},
11710 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11711 @code{RANDOM_SEED} on the other hand) access two independent
11712 pseudo-random number generators.
11713
11714 @item @emph{See also}:
11715 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11716
11717 @end table
11718
11719
11720
11721 @node STAT
11722 @section @code{STAT} --- Get file status
11723 @fnindex STAT
11724 @cindex file system, file status
11725
11726 @table @asis
11727 @item @emph{Description}:
11728 This function returns information about a file. No permissions are required on
11729 the file itself, but execute (search) permission is required on all of the
11730 directories in path that lead to the file.
11731
11732 The elements that are obtained and stored in the array @code{VALUES}:
11733 @multitable @columnfractions .15 .70
11734 @item @code{VALUES(1)}   @tab  Device ID
11735 @item @code{VALUES(2)}   @tab  Inode number
11736 @item @code{VALUES(3)}   @tab  File mode
11737 @item @code{VALUES(4)}   @tab  Number of links
11738 @item @code{VALUES(5)}   @tab  Owner's uid
11739 @item @code{VALUES(6)}   @tab  Owner's gid
11740 @item @code{VALUES(7)}   @tab  ID of device containing directory entry for file (0 if not available)
11741 @item @code{VALUES(8)}   @tab  File size (bytes)
11742 @item @code{VALUES(9)}   @tab  Last access time
11743 @item @code{VALUES(10)}  @tab  Last modification time
11744 @item @code{VALUES(11)}  @tab  Last file status change time
11745 @item @code{VALUES(12)}  @tab  Preferred I/O block size (-1 if not available)
11746 @item @code{VALUES(13)}  @tab  Number of blocks allocated (-1 if not available)
11747 @end multitable
11748
11749 Not all these elements are relevant on all systems.
11750 If an element is not relevant, it is returned as 0.
11751
11752 This intrinsic is provided in both subroutine and function forms; however,
11753 only one form can be used in any given program unit.
11754
11755 @item @emph{Standard}:
11756 GNU extension
11757
11758 @item @emph{Class}:
11759 Subroutine, function
11760
11761 @item @emph{Syntax}:
11762 @multitable @columnfractions .80
11763 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11764 @item @code{STATUS = STAT(NAME, VALUES)}
11765 @end multitable
11766
11767 @item @emph{Arguments}:
11768 @multitable @columnfractions .15 .70
11769 @item @var{NAME}   @tab The type shall be @code{CHARACTER}, of the
11770 default kind and a valid path within the file system.
11771 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11772 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11773 on success and a system specific error code otherwise.
11774 @end multitable
11775
11776 @item @emph{Example}:
11777 @smallexample
11778 PROGRAM test_stat
11779   INTEGER, DIMENSION(13) :: buff
11780   INTEGER :: status
11781
11782   CALL STAT("/etc/passwd", buff, status)
11783
11784   IF (status == 0) THEN
11785     WRITE (*, FMT="('Device ID:',               T30, I19)") buff(1)
11786     WRITE (*, FMT="('Inode number:',            T30, I19)") buff(2)
11787     WRITE (*, FMT="('File mode (octal):',       T30, O19)") buff(3)
11788     WRITE (*, FMT="('Number of links:',         T30, I19)") buff(4)
11789     WRITE (*, FMT="('Owner''s uid:',            T30, I19)") buff(5)
11790     WRITE (*, FMT="('Owner''s gid:',            T30, I19)") buff(6)
11791     WRITE (*, FMT="('Device where located:',    T30, I19)") buff(7)
11792     WRITE (*, FMT="('File size:',               T30, I19)") buff(8)
11793     WRITE (*, FMT="('Last access time:',        T30, A19)") CTIME(buff(9))
11794     WRITE (*, FMT="('Last modification time',   T30, A19)") CTIME(buff(10))
11795     WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11796     WRITE (*, FMT="('Preferred block size:',    T30, I19)") buff(12)
11797     WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11798   END IF
11799 END PROGRAM
11800 @end smallexample
11801
11802 @item @emph{See also}:
11803 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11804 @end table
11805
11806
11807
11808 @node STORAGE_SIZE
11809 @section @code{STORAGE_SIZE} --- Storage size in bits
11810 @fnindex STORAGE_SIZE
11811 @cindex storage size
11812
11813 @table @asis
11814 @item @emph{Description}:
11815 Returns the storage size of argument @var{A} in bits.
11816 @item @emph{Standard}:
11817 Fortran 2008 and later
11818 @item @emph{Class}:
11819 Inquiry function
11820 @item @emph{Syntax}:
11821 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11822
11823 @item @emph{Arguments}:
11824 @multitable @columnfractions .15 .70
11825 @item @var{A} @tab Shall be a scalar or array of any type.
11826 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11827 @end multitable
11828
11829 @item @emph{Return Value}:
11830 The result is a scalar integer with the kind type parameter specified by KIND
11831 (or default integer type if KIND is missing). The result value is the size
11832 expressed in bits for an element of an array that has the dynamic type and type
11833 parameters of A.
11834
11835 @item @emph{See also}:
11836 @ref{C_SIZEOF}, @ref{SIZEOF}
11837 @end table
11838
11839
11840
11841 @node SUM
11842 @section @code{SUM} --- Sum of array elements
11843 @fnindex SUM
11844 @cindex array, sum
11845 @cindex array, add elements
11846 @cindex array, conditionally add elements
11847 @cindex sum array elements
11848
11849 @table @asis
11850 @item @emph{Description}:
11851 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11852 the corresponding element in @var{MASK} is @code{TRUE}.
11853
11854 @item @emph{Standard}:
11855 Fortran 95 and later
11856
11857 @item @emph{Class}:
11858 Transformational function
11859
11860 @item @emph{Syntax}:
11861 @multitable @columnfractions .80
11862 @item @code{RESULT = SUM(ARRAY[, MASK])}
11863 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11864 @end multitable
11865
11866 @item @emph{Arguments}:
11867 @multitable @columnfractions .15 .70
11868 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11869 @code{REAL} or @code{COMPLEX}.
11870 @item @var{DIM}   @tab (Optional) shall be a scalar of type
11871 @code{INTEGER} with a value in the range from 1 to n, where n
11872 equals the rank of @var{ARRAY}.
11873 @item @var{MASK}  @tab (Optional) shall be of type @code{LOGICAL}
11874 and either be a scalar or an array of the same shape as @var{ARRAY}.
11875 @end multitable
11876
11877 @item @emph{Return value}:
11878 The result is of the same type as @var{ARRAY}.
11879
11880 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11881 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11882 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11883 dropped is returned.
11884
11885 @item @emph{Example}:
11886 @smallexample
11887 PROGRAM test_sum
11888   INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11889   print *, SUM(x)                        ! all elements, sum = 15
11890   print *, SUM(x, MASK=MOD(x, 2)==1)     ! odd elements, sum = 9
11891 END PROGRAM
11892 @end smallexample
11893
11894 @item @emph{See also}:
11895 @ref{PRODUCT}
11896 @end table
11897
11898
11899
11900 @node SYMLNK
11901 @section @code{SYMLNK} --- Create a symbolic link
11902 @fnindex SYMLNK
11903 @cindex file system, create link
11904 @cindex file system, soft link
11905
11906 @table @asis
11907 @item @emph{Description}:
11908 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11909 character (@code{CHAR(0)}) can be used to mark the end of the names in
11910 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11911 names are ignored.  If the @var{STATUS} argument is supplied, it
11912 contains 0 on success or a nonzero error code upon return; see
11913 @code{symlink(2)}.  If the system does not supply @code{symlink(2)},
11914 @code{ENOSYS} is returned.
11915
11916 This intrinsic is provided in both subroutine and function forms;
11917 however, only one form can be used in any given program unit.
11918
11919 @item @emph{Standard}:
11920 GNU extension
11921
11922 @item @emph{Class}:
11923 Subroutine, function
11924
11925 @item @emph{Syntax}:
11926 @multitable @columnfractions .80
11927 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11928 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11929 @end multitable
11930
11931 @item @emph{Arguments}:
11932 @multitable @columnfractions .15 .70
11933 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11934 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11935 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11936 @end multitable
11937
11938 @item @emph{See also}:
11939 @ref{LINK}, @ref{UNLINK}
11940
11941 @end table
11942
11943
11944
11945 @node SYSTEM
11946 @section @code{SYSTEM} --- Execute a shell command
11947 @fnindex SYSTEM
11948 @cindex system, system call
11949
11950 @table @asis
11951 @item @emph{Description}:
11952 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11953 argument @var{STATUS} is present, it contains the value returned by
11954 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11955 Note that which shell is used to invoke the command is system-dependent
11956 and environment-dependent.
11957
11958 This intrinsic is provided in both subroutine and function forms;
11959 however, only one form can be used in any given program unit.
11960
11961 Note that the @code{system} function need not be thread-safe. It is
11962 the responsibility of the user to ensure that @code{system} is not
11963 called concurrently.
11964
11965 @item @emph{Standard}:
11966 GNU extension
11967
11968 @item @emph{Class}:
11969 Subroutine, function
11970
11971 @item @emph{Syntax}:
11972 @multitable @columnfractions .80
11973 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11974 @item @code{STATUS = SYSTEM(COMMAND)}
11975 @end multitable
11976
11977 @item @emph{Arguments}:
11978 @multitable @columnfractions .15 .70
11979 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11980 @item @var{STATUS}  @tab (Optional) Shall be of default @code{INTEGER} type.
11981 @end multitable
11982
11983 @item @emph{See also}:
11984 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11985 and should considered in new code for future portability.
11986 @end table
11987
11988
11989
11990 @node SYSTEM_CLOCK
11991 @section @code{SYSTEM_CLOCK} --- Time function
11992 @fnindex SYSTEM_CLOCK
11993 @cindex time, clock ticks
11994 @cindex clock ticks
11995
11996 @table @asis
11997 @item @emph{Description}:
11998 Determines the @var{COUNT} of a processor clock since an unspecified
11999 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12000 the number of clock ticks per second.  If the platform supports a high
12001 resolution monotonic clock, that clock is used and can provide up to
12002 nanosecond resolution.  If a high resolution monotonic clock is not
12003 available, the implementation falls back to a potentially lower
12004 resolution realtime clock.
12005
12006 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
12007 arguments.  For @var{kind=8} arguments, @var{COUNT} represents
12008 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
12009 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
12010 @var{COUNT_MAX} are constant, however the particular values are
12011 specific to @command{gfortran}.
12012
12013 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
12014 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
12015
12016 When running on a platform using the GNU C library (glibc), or a
12017 derivative thereof, the high resolution monotonic clock is available
12018 only when linking with the @var{rt} library.  This can be done
12019 explicitly by adding the @code{-lrt} flag when linking the
12020 application, but is also done implicitly when using OpenMP.
12021
12022 @item @emph{Standard}:
12023 Fortran 95 and later
12024
12025 @item @emph{Class}:
12026 Subroutine
12027
12028 @item @emph{Syntax}:
12029 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12030
12031 @item @emph{Arguments}:
12032 @multitable @columnfractions .15 .70
12033 @item @var{COUNT}      @tab (Optional) shall be a scalar of type
12034 @code{INTEGER} with @code{INTENT(OUT)}.
12035 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12036 @code{INTEGER} with @code{INTENT(OUT)}.
12037 @item @var{COUNT_MAX}  @tab (Optional) shall be a scalar of type
12038 @code{INTEGER} with @code{INTENT(OUT)}.
12039 @end multitable
12040
12041 @item @emph{Example}:
12042 @smallexample
12043 PROGRAM test_system_clock
12044   INTEGER :: count, count_rate, count_max
12045   CALL SYSTEM_CLOCK(count, count_rate, count_max)
12046   WRITE(*,*) count, count_rate, count_max
12047 END PROGRAM
12048 @end smallexample
12049
12050 @item @emph{See also}:
12051 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12052 @end table
12053
12054
12055
12056 @node TAN
12057 @section @code{TAN} --- Tangent function
12058 @fnindex TAN
12059 @fnindex DTAN
12060 @cindex trigonometric function, tangent
12061 @cindex tangent
12062
12063 @table @asis
12064 @item @emph{Description}:
12065 @code{TAN(X)} computes the tangent of @var{X}.
12066
12067 @item @emph{Standard}:
12068 Fortran 77 and later, for a complex argument Fortran 2008 or later
12069
12070 @item @emph{Class}:
12071 Elemental function
12072
12073 @item @emph{Syntax}:
12074 @code{RESULT = TAN(X)}
12075
12076 @item @emph{Arguments}:
12077 @multitable @columnfractions .15 .70
12078 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12079 @end multitable
12080
12081 @item @emph{Return value}:
12082 The return value has same type and kind as @var{X}.
12083
12084 @item @emph{Example}:
12085 @smallexample
12086 program test_tan
12087   real(8) :: x = 0.165_8
12088   x = tan(x)
12089 end program test_tan
12090 @end smallexample
12091
12092 @item @emph{Specific names}:
12093 @multitable @columnfractions .20 .20 .20 .25
12094 @item Name            @tab Argument          @tab Return type     @tab Standard
12095 @item @code{TAN(X)}   @tab @code{REAL(4) X}  @tab @code{REAL(4)}  @tab Fortran 95 and later
12096 @item @code{DTAN(X)}  @tab @code{REAL(8) X}  @tab @code{REAL(8)}  @tab Fortran 95 and later
12097 @end multitable
12098
12099 @item @emph{See also}:
12100 @ref{ATAN}
12101 @end table
12102
12103
12104
12105 @node TANH
12106 @section @code{TANH} --- Hyperbolic tangent function
12107 @fnindex TANH
12108 @fnindex DTANH
12109 @cindex hyperbolic tangent
12110 @cindex hyperbolic function, tangent
12111 @cindex tangent, hyperbolic
12112
12113 @table @asis
12114 @item @emph{Description}:
12115 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12116
12117 @item @emph{Standard}:
12118 Fortran 77 and later, for a complex argument Fortran 2008 or later
12119
12120 @item @emph{Class}:
12121 Elemental function
12122
12123 @item @emph{Syntax}:
12124 @code{X = TANH(X)}
12125
12126 @item @emph{Arguments}:
12127 @multitable @columnfractions .15 .70
12128 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12129 @end multitable
12130
12131 @item @emph{Return value}:
12132 The return value has same type and kind as @var{X}. If @var{X} is
12133 complex, the imaginary part of the result is in radians. If @var{X}
12134 is @code{REAL}, the return value lies in the range
12135 @math{ - 1 \leq tanh(x) \leq 1 }.
12136
12137 @item @emph{Example}:
12138 @smallexample
12139 program test_tanh
12140   real(8) :: x = 2.1_8
12141   x = tanh(x)
12142 end program test_tanh
12143 @end smallexample
12144
12145 @item @emph{Specific names}:
12146 @multitable @columnfractions .20 .20 .20 .25
12147 @item Name            @tab Argument          @tab Return type       @tab Standard
12148 @item @code{TANH(X)}  @tab @code{REAL(4) X}  @tab @code{REAL(4)}    @tab Fortran 95 and later
12149 @item @code{DTANH(X)} @tab @code{REAL(8) X}  @tab @code{REAL(8)}    @tab Fortran 95 and later
12150 @end multitable
12151
12152 @item @emph{See also}:
12153 @ref{ATANH}
12154 @end table
12155
12156
12157
12158 @node THIS_IMAGE
12159 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12160 @fnindex THIS_IMAGE
12161 @cindex coarray, @code{THIS_IMAGE}
12162 @cindex images, index of this image
12163
12164 @table @asis
12165 @item @emph{Description}:
12166 Returns the cosubscript for this image.
12167
12168 @item @emph{Standard}:
12169 Fortran 2008 and later
12170
12171 @item @emph{Class}:
12172 Transformational function
12173
12174 @item @emph{Syntax}:
12175 @multitable @columnfractions .80
12176 @item @code{RESULT = THIS_IMAGE()}
12177 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12178 @end multitable
12179
12180 @item @emph{Arguments}:
12181 @multitable @columnfractions .15 .70
12182 @item @var{COARRAY} @tab Coarray of any type  (optional; if @var{DIM}
12183 present, required).
12184 @item @var{DIM}     @tab default integer scalar (optional). If present,
12185 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12186 @end multitable
12187
12188
12189 @item @emph{Return value}:
12190 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12191 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12192 a rank-1 array with corank elements is returned, containing the cosubscripts
12193 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12194 a scalar is returned, with the value of the @var{DIM} element of
12195 @code{THIS_IMAGE(COARRAY)}.
12196
12197 @item @emph{Example}:
12198 @smallexample
12199 INTEGER :: value[*]
12200 INTEGER :: i
12201 value = THIS_IMAGE()
12202 SYNC ALL
12203 IF (THIS_IMAGE() == 1) THEN
12204   DO i = 1, NUM_IMAGES()
12205     WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12206   END DO
12207 END IF
12208 @end smallexample
12209
12210 @item @emph{See also}:
12211 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12212 @end table
12213
12214
12215
12216 @node TIME
12217 @section @code{TIME} --- Time function
12218 @fnindex TIME
12219 @cindex time, current
12220 @cindex current time
12221
12222 @table @asis
12223 @item @emph{Description}:
12224 Returns the current time encoded as an integer (in the manner of the
12225 UNIX function @code{time(3)}). This value is suitable for passing to
12226 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12227
12228 This intrinsic is not fully portable, such as to systems with 32-bit
12229 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12230 the values returned by this intrinsic might be, or become, negative, or
12231 numerically less than previous values, during a single run of the
12232 compiled program.
12233
12234 See @ref{TIME8}, for information on a similar intrinsic that might be
12235 portable to more GNU Fortran implementations, though to fewer Fortran
12236 compilers.
12237
12238 @item @emph{Standard}:
12239 GNU extension
12240
12241 @item @emph{Class}:
12242 Function
12243
12244 @item @emph{Syntax}:
12245 @code{RESULT = TIME()}
12246
12247 @item @emph{Return value}:
12248 The return value is a scalar of type @code{INTEGER(4)}.
12249
12250 @item @emph{See also}:
12251 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12252
12253 @end table
12254
12255
12256
12257 @node TIME8
12258 @section @code{TIME8} --- Time function (64-bit)
12259 @fnindex TIME8
12260 @cindex time, current
12261 @cindex current time
12262
12263 @table @asis
12264 @item @emph{Description}:
12265 Returns the current time encoded as an integer (in the manner of the
12266 UNIX function @code{time(3)}). This value is suitable for passing to
12267 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12268
12269 @emph{Warning:} this intrinsic does not increase the range of the timing
12270 values over that returned by @code{time(3)}. On a system with a 32-bit
12271 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12272 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12273 overflows of the 32-bit value can still occur. Therefore, the values
12274 returned by this intrinsic might be or become negative or numerically
12275 less than previous values during a single run of the compiled program.
12276
12277 @item @emph{Standard}:
12278 GNU extension
12279
12280 @item @emph{Class}:
12281 Function
12282
12283 @item @emph{Syntax}:
12284 @code{RESULT = TIME8()}
12285
12286 @item @emph{Return value}:
12287 The return value is a scalar of type @code{INTEGER(8)}.
12288
12289 @item @emph{See also}:
12290 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12291
12292 @end table
12293
12294
12295
12296 @node TINY
12297 @section @code{TINY} --- Smallest positive number of a real kind
12298 @fnindex TINY
12299 @cindex limits, smallest number
12300 @cindex model representation, smallest number
12301
12302 @table @asis
12303 @item @emph{Description}:
12304 @code{TINY(X)} returns the smallest positive (non zero) number
12305 in the model of the type of @code{X}.
12306
12307 @item @emph{Standard}:
12308 Fortran 95 and later
12309
12310 @item @emph{Class}:
12311 Inquiry function
12312
12313 @item @emph{Syntax}:
12314 @code{RESULT = TINY(X)}
12315
12316 @item @emph{Arguments}:
12317 @multitable @columnfractions .15 .70
12318 @item @var{X} @tab Shall be of type @code{REAL}.
12319 @end multitable
12320
12321 @item @emph{Return value}:
12322 The return value is of the same type and kind as @var{X}
12323
12324 @item @emph{Example}:
12325 See @code{HUGE} for an example.
12326 @end table
12327
12328
12329
12330 @node TRAILZ
12331 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12332 @fnindex TRAILZ
12333 @cindex zero bits
12334
12335 @table @asis
12336 @item @emph{Description}:
12337 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12338
12339 @item @emph{Standard}:
12340 Fortran 2008 and later
12341
12342 @item @emph{Class}:
12343 Elemental function
12344
12345 @item @emph{Syntax}:
12346 @code{RESULT = TRAILZ(I)}
12347
12348 @item @emph{Arguments}:
12349 @multitable @columnfractions .15 .70
12350 @item @var{I} @tab Shall be of type @code{INTEGER}.
12351 @end multitable
12352
12353 @item @emph{Return value}:
12354 The type of the return value is the default @code{INTEGER}.
12355 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12356
12357 @item @emph{Example}:
12358 @smallexample
12359 PROGRAM test_trailz
12360   WRITE (*,*) TRAILZ(8)  ! prints 3
12361 END PROGRAM
12362 @end smallexample
12363
12364 @item @emph{See also}:
12365 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12366 @end table
12367
12368
12369
12370 @node TRANSFER
12371 @section @code{TRANSFER} --- Transfer bit patterns
12372 @fnindex TRANSFER
12373 @cindex bits, move
12374 @cindex type cast
12375
12376 @table @asis
12377 @item @emph{Description}:
12378 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12379 is the representation of a variable or array of the same type and type
12380 parameters as @var{MOLD}.
12381
12382 This is approximately equivalent to the C concept of @emph{casting} one
12383 type to another.
12384
12385 @item @emph{Standard}:
12386 Fortran 95 and later
12387
12388 @item @emph{Class}:
12389 Transformational function
12390
12391 @item @emph{Syntax}:
12392 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12393
12394 @item @emph{Arguments}:
12395 @multitable @columnfractions .15 .70
12396 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12397 @item @var{MOLD}   @tab Shall be a scalar or an array of any type.
12398 @item @var{SIZE}   @tab (Optional) shall be a scalar of type
12399 @code{INTEGER}.
12400 @end multitable
12401
12402 @item @emph{Return value}:
12403 The result has the same type as @var{MOLD}, with the bit level
12404 representation of @var{SOURCE}.  If @var{SIZE} is present, the result is
12405 a one-dimensional array of length @var{SIZE}.  If @var{SIZE} is absent
12406 but @var{MOLD} is an array (of any size or shape), the result is a one-
12407 dimensional array of the minimum length needed to contain the entirety
12408 of the bitwise representation of @var{SOURCE}.   If @var{SIZE} is absent
12409 and @var{MOLD} is a scalar, the result is a scalar.
12410
12411 If the bitwise representation of the result is longer than that of
12412 @var{SOURCE}, then the leading bits of the result correspond to those of
12413 @var{SOURCE} and any trailing bits are filled arbitrarily.
12414
12415 When the resulting bit representation does not correspond to a valid
12416 representation of a variable of the same type as @var{MOLD}, the results
12417 are undefined, and subsequent operations on the result cannot be
12418 guaranteed to produce sensible behavior.  For example, it is possible to
12419 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12420 @code{.NOT.@var{VAR}} both appear to be true.
12421
12422 @item @emph{Example}:
12423 @smallexample
12424 PROGRAM test_transfer
12425   integer :: x = 2143289344
12426   print *, transfer(x, 1.0)    ! prints "NaN" on i686
12427 END PROGRAM
12428 @end smallexample
12429 @end table
12430
12431
12432
12433 @node TRANSPOSE
12434 @section @code{TRANSPOSE} --- Transpose an array of rank two
12435 @fnindex TRANSPOSE
12436 @cindex array, transpose
12437 @cindex matrix, transpose
12438 @cindex transpose
12439
12440 @table @asis
12441 @item @emph{Description}:
12442 Transpose an array of rank two. Element (i, j) of the result has the value
12443 @code{MATRIX(j, i)}, for all i, j.
12444
12445 @item @emph{Standard}:
12446 Fortran 95 and later
12447
12448 @item @emph{Class}:
12449 Transformational function
12450
12451 @item @emph{Syntax}:
12452 @code{RESULT = TRANSPOSE(MATRIX)}
12453
12454 @item @emph{Arguments}:
12455 @multitable @columnfractions .15 .70
12456 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12457 @end multitable
12458
12459 @item @emph{Return value}:
12460 The result has the same type as @var{MATRIX}, and has shape
12461 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12462 @end table
12463
12464
12465
12466 @node TRIM
12467 @section @code{TRIM} --- Remove trailing blank characters of a string
12468 @fnindex TRIM
12469 @cindex string, remove trailing whitespace
12470
12471 @table @asis
12472 @item @emph{Description}:
12473 Removes trailing blank characters of a string.
12474
12475 @item @emph{Standard}:
12476 Fortran 95 and later
12477
12478 @item @emph{Class}:
12479 Transformational function
12480
12481 @item @emph{Syntax}:
12482 @code{RESULT = TRIM(STRING)}
12483
12484 @item @emph{Arguments}:
12485 @multitable @columnfractions .15 .70
12486 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12487 @end multitable
12488
12489 @item @emph{Return value}:
12490 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12491 less the number of trailing blanks.
12492
12493 @item @emph{Example}:
12494 @smallexample
12495 PROGRAM test_trim
12496   CHARACTER(len=10), PARAMETER :: s = "GFORTRAN  "
12497   WRITE(*,*) LEN(s), LEN(TRIM(s))  ! "10 8", with/without trailing blanks
12498 END PROGRAM
12499 @end smallexample
12500
12501 @item @emph{See also}:
12502 @ref{ADJUSTL}, @ref{ADJUSTR}
12503 @end table
12504
12505
12506
12507 @node TTYNAM
12508 @section @code{TTYNAM} --- Get the name of a terminal device.
12509 @fnindex TTYNAM
12510 @cindex system, terminal
12511
12512 @table @asis
12513 @item @emph{Description}:
12514 Get the name of a terminal device. For more information,
12515 see @code{ttyname(3)}.
12516
12517 This intrinsic is provided in both subroutine and function forms;
12518 however, only one form can be used in any given program unit.
12519
12520 @item @emph{Standard}:
12521 GNU extension
12522
12523 @item @emph{Class}:
12524 Subroutine, function
12525
12526 @item @emph{Syntax}:
12527 @multitable @columnfractions .80
12528 @item @code{CALL TTYNAM(UNIT, NAME)}
12529 @item @code{NAME = TTYNAM(UNIT)}
12530 @end multitable
12531
12532 @item @emph{Arguments}:
12533 @multitable @columnfractions .15 .70
12534 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12535 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12536 @end multitable
12537
12538 @item @emph{Example}:
12539 @smallexample
12540 PROGRAM test_ttynam
12541   INTEGER :: unit
12542   DO unit = 1, 10
12543     IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12544   END DO
12545 END PROGRAM
12546 @end smallexample
12547
12548 @item @emph{See also}:
12549 @ref{ISATTY}
12550 @end table
12551
12552
12553
12554 @node UBOUND
12555 @section @code{UBOUND} --- Upper dimension bounds of an array
12556 @fnindex UBOUND
12557 @cindex array, upper bound
12558
12559 @table @asis
12560 @item @emph{Description}:
12561 Returns the upper bounds of an array, or a single upper bound
12562 along the @var{DIM} dimension.
12563 @item @emph{Standard}:
12564 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12565
12566 @item @emph{Class}:
12567 Inquiry function
12568
12569 @item @emph{Syntax}:
12570 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12571
12572 @item @emph{Arguments}:
12573 @multitable @columnfractions .15 .70
12574 @item @var{ARRAY} @tab Shall be an array, of any type.
12575 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12576 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12577 expression indicating the kind parameter of the result.
12578 @end multitable
12579
12580 @item @emph{Return value}:
12581 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12582 @var{KIND} is absent, the return value is of default integer kind.
12583 If @var{DIM} is absent, the result is an array of the upper bounds of
12584 @var{ARRAY}.  If @var{DIM} is present, the result is a scalar
12585 corresponding to the upper bound of the array along that dimension.  If
12586 @var{ARRAY} is an expression rather than a whole array or array
12587 structure component, or if it has a zero extent along the relevant
12588 dimension, the upper bound is taken to be the number of elements along
12589 the relevant dimension.
12590
12591 @item @emph{See also}:
12592 @ref{LBOUND}, @ref{LCOBOUND}
12593 @end table
12594
12595
12596
12597 @node UCOBOUND
12598 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12599 @fnindex UCOBOUND
12600 @cindex coarray, upper bound
12601
12602 @table @asis
12603 @item @emph{Description}:
12604 Returns the upper cobounds of a coarray, or a single upper cobound
12605 along the @var{DIM} codimension.
12606 @item @emph{Standard}:
12607 Fortran 2008 and later
12608
12609 @item @emph{Class}:
12610 Inquiry function
12611
12612 @item @emph{Syntax}:
12613 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12614
12615 @item @emph{Arguments}:
12616 @multitable @columnfractions .15 .70
12617 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12618 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12619 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12620 expression indicating the kind parameter of the result.
12621 @end multitable
12622
12623 @item @emph{Return value}:
12624 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12625 @var{KIND} is absent, the return value is of default integer kind.
12626 If @var{DIM} is absent, the result is an array of the lower cobounds of
12627 @var{COARRAY}.  If @var{DIM} is present, the result is a scalar
12628 corresponding to the lower cobound of the array along that codimension.
12629
12630 @item @emph{See also}:
12631 @ref{LCOBOUND}, @ref{LBOUND}
12632 @end table
12633
12634
12635
12636 @node UMASK
12637 @section @code{UMASK} --- Set the file creation mask
12638 @fnindex UMASK
12639 @cindex file system, file creation mask
12640
12641 @table @asis
12642 @item @emph{Description}:
12643 Sets the file creation mask to @var{MASK}. If called as a function, it
12644 returns the old value. If called as a subroutine and argument @var{OLD}
12645 if it is supplied, it is set to the old value. See @code{umask(2)}.
12646
12647 @item @emph{Standard}:
12648 GNU extension
12649
12650 @item @emph{Class}:
12651 Subroutine, function
12652
12653 @item @emph{Syntax}:
12654 @multitable @columnfractions .80
12655 @item @code{CALL UMASK(MASK [, OLD])}
12656 @item @code{OLD = UMASK(MASK)}
12657 @end multitable
12658
12659 @item @emph{Arguments}:
12660 @multitable @columnfractions .15 .70
12661 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12662 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12663 @code{INTEGER}.
12664 @end multitable
12665
12666 @end table
12667
12668
12669
12670 @node UNLINK
12671 @section @code{UNLINK} --- Remove a file from the file system
12672 @fnindex UNLINK
12673 @cindex file system, remove file
12674
12675 @table @asis
12676 @item @emph{Description}:
12677 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12678 used to mark the end of the name in @var{PATH}; otherwise, trailing
12679 blanks in the file name are ignored.  If the @var{STATUS} argument is
12680 supplied, it contains 0 on success or a nonzero error code upon return;
12681 see @code{unlink(2)}.
12682
12683 This intrinsic is provided in both subroutine and function forms;
12684 however, only one form can be used in any given program unit.
12685
12686 @item @emph{Standard}:
12687 GNU extension
12688
12689 @item @emph{Class}:
12690 Subroutine, function
12691
12692 @item @emph{Syntax}:
12693 @multitable @columnfractions .80
12694 @item @code{CALL UNLINK(PATH [, STATUS])}
12695 @item @code{STATUS = UNLINK(PATH)}
12696 @end multitable
12697
12698 @item @emph{Arguments}:
12699 @multitable @columnfractions .15 .70
12700 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12701 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12702 @end multitable
12703
12704 @item @emph{See also}:
12705 @ref{LINK}, @ref{SYMLNK}
12706 @end table
12707
12708
12709
12710 @node UNPACK
12711 @section @code{UNPACK} --- Unpack an array of rank one into an array
12712 @fnindex UNPACK
12713 @cindex array, unpacking
12714 @cindex array, increase dimension
12715 @cindex array, scatter elements
12716
12717 @table @asis
12718 @item @emph{Description}:
12719 Store the elements of @var{VECTOR} in an array of higher rank.
12720
12721 @item @emph{Standard}:
12722 Fortran 95 and later
12723
12724 @item @emph{Class}:
12725 Transformational function
12726
12727 @item @emph{Syntax}:
12728 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12729
12730 @item @emph{Arguments}:
12731 @multitable @columnfractions .15 .70
12732 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12733 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12734 @item @var{MASK}   @tab Shall be an array of type @code{LOGICAL}.
12735 @item @var{FIELD}  @tab Shall be of the same type as @var{VECTOR} and have
12736 the same shape as @var{MASK}.
12737 @end multitable
12738
12739 @item @emph{Return value}:
12740 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12741 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12742
12743 @item @emph{Example}:
12744 @smallexample
12745 PROGRAM test_unpack
12746   integer :: vector(2)  = (/1,1/)
12747   logical :: mask(4)  = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12748   integer :: field(2,2) = 0, unity(2,2)
12749
12750   ! result: unity matrix
12751   unity = unpack(vector, reshape(mask, (/2,2/)), field)
12752 END PROGRAM
12753 @end smallexample
12754
12755 @item @emph{See also}:
12756 @ref{PACK}, @ref{SPREAD}
12757 @end table
12758
12759
12760
12761 @node VERIFY
12762 @section @code{VERIFY} --- Scan a string for characters not a given set
12763 @fnindex VERIFY
12764 @cindex string, find missing set
12765
12766 @table @asis
12767 @item @emph{Description}:
12768 Verifies that all the characters in @var{STRING} belong to the set of
12769 characters in @var{SET}.
12770
12771 If @var{BACK} is either absent or equals @code{FALSE}, this function
12772 returns the position of the leftmost character of @var{STRING} that is
12773 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12774 position is returned. If all characters of @var{STRING} are found in
12775 @var{SET}, the result is zero.
12776
12777 @item @emph{Standard}:
12778 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12779
12780 @item @emph{Class}:
12781 Elemental function
12782
12783 @item @emph{Syntax}:
12784 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12785
12786 @item @emph{Arguments}:
12787 @multitable @columnfractions .15 .70
12788 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12789 @item @var{SET}    @tab Shall be of type @code{CHARACTER}.
12790 @item @var{BACK}   @tab (Optional) shall be of type @code{LOGICAL}.
12791 @item @var{KIND}   @tab (Optional) An @code{INTEGER} initialization
12792 expression indicating the kind parameter of the result.
12793 @end multitable
12794
12795 @item @emph{Return value}:
12796 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12797 @var{KIND} is absent, the return value is of default integer kind.
12798
12799 @item @emph{Example}:
12800 @smallexample
12801 PROGRAM test_verify
12802   WRITE(*,*) VERIFY("FORTRAN", "AO")           ! 1, found 'F'
12803   WRITE(*,*) VERIFY("FORTRAN", "FOO")          ! 3, found 'R'
12804   WRITE(*,*) VERIFY("FORTRAN", "C++")          ! 1, found 'F'
12805   WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.)  ! 7, found 'N'
12806   WRITE(*,*) VERIFY("FORTRAN", "FORTRAN")      ! 0' found none
12807 END PROGRAM
12808 @end smallexample
12809
12810 @item @emph{See also}:
12811 @ref{SCAN}, @ref{INDEX intrinsic}
12812 @end table
12813
12814
12815
12816 @node XOR
12817 @section @code{XOR} --- Bitwise logical exclusive OR
12818 @fnindex XOR
12819 @cindex bitwise logical exclusive or
12820 @cindex logical exclusive or, bitwise
12821
12822 @table @asis
12823 @item @emph{Description}:
12824 Bitwise logical exclusive or.
12825
12826 This intrinsic routine is provided for backwards compatibility with
12827 GNU Fortran 77.  For integer arguments, programmers should consider
12828 the use of the @ref{IEOR} intrinsic and for logical arguments the
12829 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12830
12831 @item @emph{Standard}:
12832 GNU extension
12833
12834 @item @emph{Class}:
12835 Function
12836
12837 @item @emph{Syntax}:
12838 @code{RESULT = XOR(I, J)}
12839
12840 @item @emph{Arguments}:
12841 @multitable @columnfractions .15 .70
12842 @item @var{I} @tab The type shall be either  a scalar @code{INTEGER}
12843 type or a scalar @code{LOGICAL} type.
12844 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12845 @end multitable
12846
12847 @item @emph{Return value}:
12848 The return type is either a scalar @code{INTEGER} or a scalar
12849 @code{LOGICAL}.  If the kind type parameters differ, then the
12850 smaller kind type is implicitly converted to larger kind, and the
12851 return has the larger kind.
12852
12853 @item @emph{Example}:
12854 @smallexample
12855 PROGRAM test_xor
12856   LOGICAL :: T = .TRUE., F = .FALSE.
12857   INTEGER :: a, b
12858   DATA a / Z'F' /, b / Z'3' /
12859
12860   WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12861   WRITE (*,*) XOR(a, b)
12862 END PROGRAM
12863 @end smallexample
12864
12865 @item @emph{See also}:
12866 Fortran 95 elemental function: @ref{IEOR}
12867 @end table
12868
12869
12870
12871 @node Intrinsic Modules
12872 @chapter Intrinsic Modules
12873 @cindex intrinsic Modules
12874
12875 @menu
12876 * ISO_FORTRAN_ENV::
12877 * ISO_C_BINDING::
12878 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12879 @end menu
12880
12881 @node ISO_FORTRAN_ENV
12882 @section @code{ISO_FORTRAN_ENV}
12883 @table @asis
12884 @item @emph{Standard}:
12885 Fortran 2003 and later, except when otherwise noted
12886 @end table
12887
12888 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12889 named constants:
12890
12891 @table @asis
12892 @item @code{ATOMIC_INT_KIND}:
12893 Default-kind integer constant to be used as kind parameter when defining
12894 integer variables used in atomic operations. (Fortran 2008 or later.)
12895
12896 @item @code{ATOMIC_LOGICAL_KIND}:
12897 Default-kind integer constant to be used as kind parameter when defining
12898 logical variables used in atomic operations. (Fortran 2008 or later.)
12899
12900 @item @code{CHARACTER_KINDS}:
12901 Default-kind integer constant array of rank one containing the supported kind
12902 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12903
12904 @item @code{CHARACTER_STORAGE_SIZE}:
12905 Size in bits of the character storage unit.
12906
12907 @item @code{ERROR_UNIT}:
12908 Identifies the preconnected unit used for error reporting.
12909
12910 @item @code{FILE_STORAGE_SIZE}:
12911 Size in bits of the file-storage unit.
12912
12913 @item @code{INPUT_UNIT}:
12914 Identifies the preconnected unit identified by the asterisk
12915 (@code{*}) in @code{READ} statement.
12916
12917 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12918 Kind type parameters to specify an INTEGER type with a storage
12919 size of 16, 32, and 64 bits. It is negative if a target platform
12920 does not support the particular kind. (Fortran 2008 or later.)
12921
12922 @item @code{INTEGER_KINDS}:
12923 Default-kind integer constant array of rank one containing the supported kind
12924 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12925
12926 @item @code{IOSTAT_END}:
12927 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12928 an input/output statement if an end-of-file condition occurred.
12929
12930 @item @code{IOSTAT_EOR}:
12931 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12932 an input/output statement if an end-of-record condition occurred.
12933
12934 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12935 Scalar default-integer constant, used by @code{INQUIRE} for the
12936 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12937 internal unit. (Fortran 2008 or later.)
12938
12939 @item @code{NUMERIC_STORAGE_SIZE}:
12940 The size in bits of the numeric storage unit.
12941
12942 @item @code{LOGICAL_KINDS}:
12943 Default-kind integer constant array of rank one containing the supported kind
12944 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12945
12946 @item @code{OUTPUT_UNIT}:
12947 Identifies the preconnected unit identified by the asterisk
12948 (@code{*}) in @code{WRITE} statement.
12949
12950 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12951 Kind type parameters to specify a REAL type with a storage
12952 size of 32, 64, and 128 bits. It is negative if a target platform
12953 does not support the particular kind. (Fortran 2008 or later.)
12954
12955 @item @code{REAL_KINDS}:
12956 Default-kind integer constant array of rank one containing the supported kind
12957 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12958
12959 @item @code{STAT_LOCKED}:
12960 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12961 denote that the lock variable is locked by the executing image. (Fortran 2008
12962 or later.)
12963
12964 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12965 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12966 denote that the lock variable is locked by another image. (Fortran 2008 or
12967 later.)
12968
12969 @item @code{STAT_STOPPED_IMAGE}:
12970 Positive, scalar default-integer constant used as STAT= return value if the
12971 argument in the statement requires synchronisation with an image, which has
12972 initiated the termination of the execution. (Fortran 2008 or later.)
12973
12974 @item @code{STAT_UNLOCKED}:
12975 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12976 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12977 @end table
12978
12979 The module provides the following derived type:
12980
12981 @table @asis
12982 @item @code{LOCK_TYPE}:
12983 Derived type with private components to be use with the @code{LOCK} and
12984 @code{UNLOCK} statement. A variable of its type has to be always declared
12985 as coarray and may not appear in a variable-definition context.
12986 (Fortran 2008 or later.)
12987 @end table
12988
12989 The module also provides the following intrinsic procedures:
12990 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12991
12992
12993
12994 @node ISO_C_BINDING
12995 @section @code{ISO_C_BINDING}
12996 @table @asis
12997 @item @emph{Standard}:
12998 Fortran 2003 and later, GNU extensions
12999 @end table
13000
13001 The following intrinsic procedures are provided by the module; their
13002 definition can be found in the section Intrinsic Procedures of this
13003 manual.
13004
13005 @table @asis
13006 @item @code{C_ASSOCIATED}
13007 @item @code{C_F_POINTER}
13008 @item @code{C_F_PROCPOINTER}
13009 @item @code{C_FUNLOC}
13010 @item @code{C_LOC}
13011 @item @code{C_SIZEOF}
13012 @end table
13013 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13014 @c don't really know why.
13015
13016 The @code{ISO_C_BINDING} module provides the following named constants of
13017 type default integer, which can be used as KIND type parameters.
13018
13019 In addition to the integer named constants required by the Fortran 2003
13020 standard, GNU Fortran provides as an extension named constants for the
13021 128-bit integer types supported by the C compiler: @code{C_INT128_T,
13022 C_INT_LEAST128_T, C_INT_FAST128_T}. Furthermore, if @code{__float} is
13023 supported in C, the named constants @code{C_FLOAT128, C_FLOAT128_COMPLEX}
13024 are defined.
13025
13026 @multitable @columnfractions .15 .35 .35 .35
13027 @item Fortran Type  @tab Named constant         @tab C type                                @tab Extension
13028 @item @code{INTEGER}@tab @code{C_INT}           @tab @code{int}
13029 @item @code{INTEGER}@tab @code{C_SHORT}         @tab @code{short int}
13030 @item @code{INTEGER}@tab @code{C_LONG}          @tab @code{long int}
13031 @item @code{INTEGER}@tab @code{C_LONG_LONG}     @tab @code{long long int}
13032 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR}   @tab @code{signed char}/@code{unsigned char}
13033 @item @code{INTEGER}@tab @code{C_SIZE_T}        @tab @code{size_t}
13034 @item @code{INTEGER}@tab @code{C_INT8_T}        @tab @code{int8_t}
13035 @item @code{INTEGER}@tab @code{C_INT16_T}       @tab @code{int16_t}
13036 @item @code{INTEGER}@tab @code{C_INT32_T}       @tab @code{int32_t}
13037 @item @code{INTEGER}@tab @code{C_INT64_T}       @tab @code{int64_t}
13038 @item @code{INTEGER}@tab @code{C_INT128_T}      @tab @code{int128_t}                      @tab Ext.
13039 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T}  @tab @code{int_least8_t}
13040 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13041 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13042 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13043 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t}                @tab Ext.
13044 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}   @tab @code{int_fast8_t}
13045 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}  @tab @code{int_fast16_t}
13046 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}  @tab @code{int_fast32_t}
13047 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}  @tab @code{int_fast64_t}
13048 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t}                 @tab Ext.
13049 @item @code{INTEGER}@tab @code{C_INTMAX_T}      @tab @code{intmax_t}
13050 @item @code{INTEGER}@tab @code{C_INTPTR_T}      @tab @code{intptr_t}
13051 @item @code{REAL}   @tab @code{C_FLOAT}         @tab @code{float}
13052 @item @code{REAL}   @tab @code{C_DOUBLE}        @tab @code{double}
13053 @item @code{REAL}   @tab @code{C_LONG_DOUBLE}   @tab @code{long double}
13054 @item @code{REAL}   @tab @code{C_FLOAT128}      @tab @code{__float128}                    @tab Ext.
13055 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13056 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13057 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13058 @item @code{REAL}   @tab @code{C_FLOAT128_COMPLEX}   @tab @code{__float128 _Complex}      @tab Ext.
13059 @item @code{LOGICAL}@tab @code{C_BOOL}          @tab @code{_Bool}
13060 @item @code{CHARACTER}@tab @code{C_CHAR}        @tab @code{char}
13061 @end multitable
13062
13063 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13064 are defined.
13065
13066 @multitable @columnfractions .20 .45 .15
13067 @item Name                     @tab C definition    @tab Value
13068 @item @code{C_NULL_CHAR}       @tab null character  @tab @code{'\0'}
13069 @item @code{C_ALERT}           @tab alert           @tab @code{'\a'}
13070 @item @code{C_BACKSPACE}       @tab backspace       @tab @code{'\b'}
13071 @item @code{C_FORM_FEED}       @tab form feed       @tab @code{'\f'}
13072 @item @code{C_NEW_LINE}        @tab new line        @tab @code{'\n'}
13073 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13074 @item @code{C_HORIZONTAL_TAB}  @tab horizontal tab  @tab @code{'\t'}
13075 @item @code{C_VERTICAL_TAB}    @tab vertical tab    @tab @code{'\v'}
13076 @end multitable
13077
13078 Moreover, the following two named constants are defined:
13079
13080 @multitable @columnfractions .20 .80
13081 @item Name                 @tab Type
13082 @item @code{C_NULL_PTR}    @tab @code{C_PTR}
13083 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13084 @end multitable
13085
13086 Both are equivalent to the value @code{NULL} in C.
13087
13088 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13089 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13090 @table @asis
13091 @item @emph{Standard}:
13092 OpenMP Application Program Interface v3.1
13093 @end table
13094
13095
13096 The OpenMP Fortran runtime library routines are provided both in
13097 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13098 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13099 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13100 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13101 the named constants defined in the modules are listed
13102 below.
13103
13104 For details refer to the actual
13105 @uref{http://www.openmp.org/mp-documents/spec31.pdf,
13106 OpenMP Application Program Interface v3.1}.
13107
13108 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13109 named constants:
13110
13111 @table @asis
13112 @item @code{omp_lock_kind}
13113 @item @code{omp_nest_lock_kind}
13114 @item @code{omp_sched_kind}
13115 @end table
13116
13117 @code{OMP_LIB} provides the scalar default-integer
13118 named constant @code{openmp_version} with a value of the form
13119 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13120 of the OpenMP version; for OpenMP v3.1 the value is @code{201107}.
13121
13122 And the following scalar integer named constants of the
13123 kind @code{omp_sched_kind}:
13124
13125 @table @asis
13126 @item @code{omp_sched_static}
13127 @item @code{omp_sched_dynamic}
13128 @item @code{omp_sched_guided}
13129 @item @code{omp_sched_auto}
13130 @end table